Metadata-Version: 2.3
Name: dc-preflight-llm-check
Version: 0.2.1
Summary: Pre-flight connectivity checks for the n8n + Ollama training stack.
Requires-Python: >=3.13
Description-Content-Type: text/markdown

# 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:

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

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

  ```powershell
  uvx dc-preflight-llm-check
  ```

  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; `dc-preflight-llm-check` 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 `dc-preflight-llm-check`.

## Profiles and flags

Which checks run is controlled by `checks.toml`, which defines named
**profiles** — e.g. `api-only` runs `network, uv, gemini, openai, openrouter`.
`dc-preflight-llm-check`'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:

```powershell
uv run dc-preflight-llm-check --profile api-only
uv run dc-preflight-llm-check --checks network,uv
uv run dc-preflight-llm-check --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
```

`dc-preflight-llm-check` 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):

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

## Running the test suite

```powershell
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`/`openai`/`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.
