check_LLM

Pre-flight connectivity checks for the n8n + Ollama training stack. Run this before a training session to catch VPN/firewall/proxy problems that would otherwise derail the day — before participants start blaming n8n or Ollama for what's actually a blocked outbound connection.

Setup

There are two ways to run check_LLM:

• Local dev clone — for anyone editing checks.toml/course profiles or working on the code itself. Clone the repo, cd into it, then:

  Copy-Item .env.example .env
  # edit .env: set GEMINI_API_KEY / OPENROUTER_API_KEY (only needed for
  # profiles that include the gemini/openrouter checks)
  uv run check-llm
  

• Zero-clone, straight from PyPI — for a participant who just wants to run the pre-flight checks, no git required:

  uvx check-llm
  

  With no local checks.toml, this uses a bundled default profile set (api-only/n8n-ollama/ollama-only — same as the repo's). Drop your own .env/checks.toml in whatever directory you run this from to customize either; check-llm reads/writes .env, checks.toml, and check_log.txt relative to your current directory, not wherever the tool itself is installed.

• Windows, no terminal comfort needed — just double-click check_script.bat. The first time, it asks for your API keys and saves them to a .env next to itself; every run after that reuses the saved keys automatically, no prompts. It also checks network connectivity and installs uv if it's missing before running check-llm.

Profiles and flags

Which checks run is controlled by checks.toml, which defines named profiles — e.g. api-only runs network, uv, gemini, openrouter. check-llm's no-flag default is checks.toml's default_profile (currently api-only).

• --profile NAME — run a specific named profile instead of the default
• --checks a,b,c — run an explicit, comma-separated list of checks, overriding both --profile and checks.toml; handy for testing one or two checks without editing the config
• --config PATH — use a checks.toml file at a non-default location
• --list-profiles — print the profiles defined in checks.toml and exit

Examples:

uv run check-llm --profile api-only
uv run check-llm --checks network,uv
uv run check-llm --list-profiles

The network check always runs first regardless of the order it's listed in, since every other check's failure is ambiguous without first knowing whether outbound internet works at all.

Reading the output

Each check prints one [PASS]/[FAIL] line as it runs, followed by an aggregate summary line, e.g.:

[PASS] network: reached https://www.google.com
[FAIL] gemini: GEMINI_API_KEY not set in .env — skipped network call
[PASS] openrouter: OpenRouter API reachable, key accepted
[PASS] uv: uv reached the package index
SUMMARY: 3/4 passed — FAILED: gemini

check-llm exits 0 if every check passed, 1 if one or more checks ran and failed, and 2 if a config problem (an unknown --profile, or a missing/malformed checks.toml) stopped checks from running at all.

Every run also appends a timestamped block to check_log.txt (same content as the screen output) — paste this file when asking for help instead of re-describing what happened. It accumulates across runs rather than being overwritten, so a retry history is preserved; it's gitignored since it's a local runtime artifact, not something to commit.

Running a single check standalone

Every check_*.py under src/check_llm/ is independently runnable and follows the same contract — prints its [PASS]/[FAIL] line, appends to check_log.txt, and exits 0/1. This only works from a local dev clone (these aren't published as separate PyPI commands):

uv run src/check_llm/check_network.py
uv run src/check_llm/check_gemini.py

Running the test suite

uv run python -m unittest discover tests

This runs the full suite of unittest.mock-based tests accumulated so far — _common.py's helpers, main.py's orchestration logic, and the network/gemini/openrouter/uv checks — with no real network calls and no third-party test framework. Docker-related checks and their tests aren't part of this repo yet; see PLAN.md Stage 8.