feat(examples): add setup tooling so the examples can actually be run

[williedoran-neo4j]

Linear: GENKGB-1857

Follow-up to #578, which fixed the gpt-5 breakage in the OpenAI examples. That work exposed a second problem: there is no way to run the other examples without reverse-engineering their requirements from the source.

examples/README.md is a pure link index — no mention of API keys, extras, Docker, or the fact that sixteen examples talk to a remote demo database. What setup knowledge exists is spread across the README's Tests section, three per-store READMEs, and tests/e2e/docker-compose.yml, which exists for the e2e suite rather than the examples. CI uses a fourth, divergent path: hand-rolled docker run, no compose.

What's here

scripts/setup_examples.py — a doctor and an interactive installer.

python scripts/setup_examples.py --check   # what is missing, changes nothing
python scripts/setup_examples.py           # walk through fixing it

--check resolves every example against a shared requirement model, probes packages, env vars, databases and containers, and reports the single first thing blocking each one, grouped so the biggest wins surface first. It writes nothing and exits 0 unless --strict. On a machine with keys set but no services running it reports 52 runnable, 34 blocked, 18 snippets — and 33 of those 34 are blocked only on a stopped Neo4j or Ollama, which is the point: bring the stack up and they run.

The installer works in tiers, so the free and local providers work before any cloud account is involved: extras and local Neo4j, then API keys, then local runtimes, then cloud. Every step is skippable and safe to re-run. Tier 3 asks whether you're using a Neo4j Aura dev environment or your own cloud accounts — the internal path is useless to an outside contributor, and the reverse is wrong for a Neo4j developer, and neither can be inferred safely.

scripts/example_requirements.py — one model of what each example needs, shared with check_examples.py. Package requirements come from an AST import scan mapping library symbols to extras, because an example imports OpenAILLM rather than openai, so the dependency is invisible from its imports alone. Env vars and datastores are read from os.getenv calls and connection URIs. Anything that leaves no trace in the source — APOC, a pre-existing index, outbound internet, or a component named only in a YAML/JSON config — is declared per path.

This also replaces providers_used() in check_examples.py, which matched provider names as substrings of the whole file: any file containing the word "google" counted as a Vertex example, and OpenAIEmbeddings couldn't be told from AzureOpenAIEmbeddings. --live now also skips snippets rather than running them and reporting a pass, and checks whether the services an example needs are actually up — a stopped Neo4j previously surfaced as FAIL on ~30 examples, which reads as "the examples are broken" when the truth is "nothing was running".

examples/docker-compose.yml — Neo4j with APOC by default; a vectordb profile adding Weaviate, Qdrant and Pinecone Local; an optional ollama profile. Services declare healthchecks so up --wait blocks until they actually answer; the e2e stack has none and CI polls readiness by hand, which leaves local users racing connection-refused. The one exception is pinecone-local, whose image ships no shell and no binary a healthcheck could run — documented in the file header. Pinecone Local is an in-memory emulator that ignores API keys, so that path no longer needs a hosted account. Same ports as the e2e stack, so the two are mutually exclusive — the file header says so.

examples/.env.example and examples/SETUP.md — a credential template, and per-example docs covering provider, extras, env vars and services, plus which providers are free without a card. Every non-OpenAI provider turns out to have a free or local path. examples/README.md now links it.

python-dotenv and requests declared in the examples extra — fourteen examples call load_dotenv() and tools_retriever_example.py calls a web API with requests, but neither was declared, so both resolved only by accident.

Credentials

Keys are read with getpass, validated against the provider with a free list-models call, and written only to a gitignored .env. A key that doesn't validate is never written — a bad value there turns a clear "unset" into a confusing 401. Nothing is printed in full, and cloud account identifiers are resolved at run time rather than persisted.

Two details worth calling out, because both are the kind of thing that is easy to get subtly wrong:

• The key never travels in a URL. Gemini's validator sends it as an x-goog-api-key header, and no error message interpolates a URL, since a query string is logged by every proxy in the path and error strings are printed to the terminal.
• .env is created at mode 0600 rather than created and then chmod-ed, so the secret never exists on disk world-readable, not even briefly. It is written through a temp file and os.replace, so an interrupted write cannot truncate the credentials already there.

Tests

tests/unit/scripts/ — 44 cases over the requirement model, the .env writer and the provider validators. No network (urlopen is replaced and a fixture fails the test if anything reaches out), no keys, no services.

They are there because they catch real things. Each of these was confirmed to fail against the code as it was before: the key-in-the-URL disclosure, the .env creation mode, and the three config-file examples being reported as needing nothing at all. Worth noting for anyone reviewing the permissions test: asserting the final mode of .env proves nothing, since the old and new code both end at 0600 — the test forbids the chmod fixup instead, so the mode has to be right at creation.

scripts/ is deliberately outside the coverage gate ([tool.coverage.run] source = ["src"]), so these are additive and cannot move the 90% number.

For review

• The feat(scripts): add static checks for the examples directory commit is byte-identical to fix(examples): make OpenAI examples work with gpt-5 #578's copy of that file. It exists so this branch stands alone off main; it drops out cleanly on rebase once fix(examples): make OpenAI examples work with gpt-5 #578 merges. Nothing to re-review there. The same applies to the one-line chore(tests): put scripts/ on the pytest path commit, which both branches need independently.

  Both were verified rather than assumed — rebasing this branch onto a main containing fix(examples): make OpenAI examples work with gpt-5 #578 reports dropping … patch contents already upstream and skipped previously applied commit, 15 commits become 13, with zero conflicts.

• With both branches together the checker reports 104 files, no problems — verified locally. On this branch alone it reports 22 problems, because this branch carries the checker but not fix(examples): make OpenAI examples work with gpt-5 #578's example fixes.

• Commits are ordered to be reviewed one at a time: compose and env template first (no Python), then the requirement model, then the CLI on top, then docs.

• Deliberately not fixed, documented in SETUP.md instead: two examples write message history to the read-only demo database and fail with Forbidden, and three need PYTHONPATH=examples/data.

Type of Change

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

Complexity

Complexity: Medium

How Has This Been Tested?

• Unit tests
• E2E tests
• Manual tests

Exercised, not just reviewed. Brought the stack up from clean and watched the doctor's runnable count climb as services started. Ran tier 0 and confirmed it creates the four indexes the examples assume — including the moviePlotsEmbedding index on the local database that no script in this repo previously created. Confirmed all five key validators reject an invalid key and write nothing. Stopped Neo4j and confirmed the doctor reports blocked rather than passing. The t2v-transformers healthcheck was verified by running the image: it has no wget or curl but does ship python3, and the ready endpoint answers 204.

Green on ruff check, ruff format --check, mypy --strict, and the unit suite with coverage at the 90% gate.

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

[williedoran-neo4j]

Closing this in favour of five smaller PRs. At 15 commits and ~3,900 lines it was too much to ask of a reviewer, and going back over it turned up a fair amount that should not have shipped at all — a hand-maintained 86-row table with rows that were already wrong, a Provider.extra field with fifteen values and no readers, a --provider flag that silently did nothing for 7 of 15 providers, and a tier-0 step that pre-created the two indexes examples/database_operations/create_*_index.py exist to demonstrate, turning both examples into no-ops.

It also carried a Neo4j-internal omni/Aura path that prompted outside contributors with an option they cannot use. That is a sentence in examples/SETUP.md now, not a code path.

Replaced by:

• build(compose): put the vector stores behind a profile and add healthchecks #595 — one compose stack: vector stores behind a vectordb profile, healthchecks, Pinecone Local
• docs(examples): document what the examples need in order to run #596 — examples/SETUP.md, .env.example, the undeclared python-dotenv/requests deps, Ollama examples taking a model argument (stacked on build(compose): put the vector stores behind a profile and add healthchecks #595)
• feat(scripts): add an opt-in live runner for the examples #598 — scripts/check_examples.py as an opt-in, manual, live runner
• feat(scripts): model what each example requires, and use it in the checker #597 — the AST requirement model, replacing substring provider matching (stacked on feat(scripts): add an opt-in live runner for the examples #598)
• feat(scripts): add a doctor and installer for the example environment #599 — the --check doctor and the credential installer (stacked on feat(scripts): model what each example requires, and use it in the checker #597)

Net effect: roughly 1,400 fewer lines than this PR, in pieces that can be reviewed and merged independently.