feat(scripts): model what each example under examples/ requires

[williedoran-neo4j]

First of four PRs. The order matches how the tools get used: work out what each example needs (this) → report what is missing (#599) → walk through fixing it (#602) → run what the machine supports (#598).

Nothing knows what an example needs in order to run, so a contributor finds out by running it and reading the traceback. This adds one source of truth the rest of the tooling shares.

Where requirements come from

• Packages, from an AST import scan that maps library symbols to extras. An example imports OpenAILLM, not openai, so the dependency is invisible from its imports alone. The substring scan this replaces treated any file containing the word "google" as a Vertex example and could not tell OpenAIEmbeddings from AzureOpenAIEmbeddings.
• Env vars and datastores, read from os.getenv calls and connection URIs in the source.
• Everything else — APOC, a pre-existing index, outbound internet, or a component named only in a YAML config — declared per path in SERVICE_RULES, because it leaves no trace in the source.

Stdlib-only by design: it has to run before uv sync, which is exactly when somebody most needs to be told what to install.

Keeping the tables honest

The tables are hand-maintained, and a half-finished edit produced a plausible wrong answer rather than an error. Each of these is a one-line test:

• SYMBOL_EXTRAS and SYMBOL_PROVIDERS are two halves of one fact. Their values legitimately differ — AzureOpenAILLM needs the openai extra but talks to the azure provider — so they cannot be merged, but their keys must not drift. A symbol in one and not the other means the doctor installs a package it never asks for a key for, or the reverse.
• Every service an example needs has a label. service_available() returns True for anything it cannot probe, so a typo'd service name would otherwise report as satisfied.
• SERVICE_RULES matches are pinned by count. Asserting only that a pattern matches something protects the nine rules matching exactly one file; the other ten match several, so renaming one of them leaves the pattern non-empty and the requirement silently lost. The count also catches a glob widened until it sweeps in a file that does not want the requirement. Update it deliberately when examples/ gains or loses a file — that is the moment to confirm the rule still applies.

SERVICE_RULES specs are a TypedDict rather than dict[str, object]. Read back through spec.get(), a mistyped key ("service") or a scalar where a list belongs both silently did nothing. mypy already runs over scripts/ in CI and now rejects both.

Two CI commits, which do not belong to the model

Called out because they are unrelated to everything above, and would otherwise be a surprise in the diff.

Four e2e jobs failed on #596 with ImportError: cannot import name 'WeaviateNeo4jRetriever' — and the same for Pinecone and Qdrant — on a commit that changed two Markdown files. No test was flaky: the job restored a cached .venv missing the vector-store extras and, because installation was skipped on an exact cache hit, nothing repaired it. Re-running reproduced it exactly; deleting the cache entry fixed it.

• ci: always install dependencies, even on a cache hit stops a bad entry causing failures.
• ci: never publish a half-installed venv to the cache stops one being created: actions/cache saves in a post step that also runs when a job is cancelled, so an interrupted uv sync publishes the partial venv. Splitting into restore/save makes the save an ordinary step, which an interrupted install never reaches.

They are here rather than in their own PR to avoid opening another one; happy to lift them out if a maintainer would rather they merged independently, since they fix CI for everyone and this stack is four deep.

Scope

Deliberately just the model, its tests and those CI fixes. The model has no consumer until #599 — which is what keeps this small enough to check by reading.

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

29 tests over the scan, the per-path rules and the table invariants. Each new invariant was confirmed to fail when the thing it guards is broken — dropping a symbol from one table, and simulating a rename against the rule counts — rather than merely passing today.

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

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

🤖 Generated with Claude Code