feat(scripts): add an opt-in live runner for the examples

[williedoran-neo4j]

Split out of #578 so the example fixes there can be reviewed as a plain bug fix.

Nothing in CI executes anything under examples/, so a bulk model swap in #482 left 17 files passing parameters their model rejects. The failures were deterministic — nobody had run them.

What's here

scripts/check_examples.py resolves each example's provider and model, skips the ones there are no credentials or services for, and runs the rest against the live APIs. Static rules cover the parameter combinations providers reject outright — OpenAI reasoning models refuse max_tokens and any temperature but the default, while Anthropic requires max_tokens — so an obvious break is caught before spending a call on it.

Deliberately opt-in

It costs money and hits the network, so nothing runs it on a commit, a push, or in CI. It is a manual-stage pre-commit hook, run when you mean it:

uv run pre-commit run --hook-stage manual examples-live

The hook carries always_run: true; without it pre-commit skips a non-file-driven hook whenever nothing matching is staged, and the command silently does nothing.

The trade-off is worth stating plainly: because nothing runs automatically, this catches drift only when somebody chooses to run it. It is a tool for before a release or after touching the examples, not a guard rail.

Tests

tests/unit/scripts/test_check_examples.py — 24 cases fed as source strings. No network, no API key, no temp files.

They exist because the rules are the part that has to be trusted, and writing them found two real defects: model_params bound to a variable resolved to an empty dict, so every rule silently skipped — which is how a broken example survived a first pass — and a valid ChatOpenAI(temperature=1) was reported with the self-contradictory fix "or pass temperature=1". Both tests were confirmed to fail against the pre-fix code. They also pin the two false-positive guards that are easy to regress: Anthropic's required max_tokens, and Ollama nesting parameters under options.

scripts/ sits outside the coverage gate ([tool.coverage.run] source = ["src"]), so these are additive and cannot move the 90% number. They need one line of wiring, pythonpath = ["scripts"].

Type of Change

• New feature
• Bug fix
• Breaking change
• Documentation update
• Project configuration change

Complexity

Complexity: Low

How Has This Been Tested?

• Unit tests
• E2E tests
• Manual tests

Green on ruff, mypy --strict and the unit suite. Run against main the static rules report 22 problems across 17 example files — the ones #578 fixes.

Checklist

• Documentation has been updated
• Unit tests have been updated
• E2E tests have been updated
• Examples have been updated
• New files have copyright header
• CLA (https://neo4j.com/developer/cla/) has been signed
• CHANGELOG.md updated if appropriate (developer tooling)

🤖 Generated with Claude Code