Skip to content

Let the last two bin/ scripts run without PYTHONPATH, like the others - #224

Merged
adamjohnwright merged 3 commits into
mainfrom
fix/bin-scripts-bootstrap
Sep 16, 2026
Merged

adamjohnwright merged 3 commits into
mainfrom
fix/bin-scripts-bootstrap

Conversation

@adamjohnwright

Copy link
Copy Markdown
Contributor

Four of the six bin/ scripts bootstrap their own sys.path and run from anywhere. embeddings_manager and retrieval_baseline did not:

$ ./bin/embeddings_manager ls
ModuleNotFoundError: No module named 'data_generation'

The Dockerfile and CI both set PYTHONPATH (/app/src, ./bin:./src), so these worked there and nowhere else — including in their own documented usage. Same defect fixed for evaluate and probe_model_temperature in cbe20fc; these two were missed.

The cost of leaving it wasn't hypothetical

On 2026-09-14 I hit exactly this on embeddings_manager, worked around it with a PYTHONPATH=src prefix rather than fixing it, and then — because the tool felt awkward — bypassed it entirely and called generate_userguide_embeddings directly.

That skipped the use() call which registers a bundle. So 16 MB of correctly-generated user guide sat on disk, invisible to the app, and it took a wasted deploy and a round trip with Adam to notice.

A tool that doesn't run as documented gets worked around, and the workaround is where the bug was.

After

  answer-sweep               works
  embeddings_manager         works
  evaluate                   works
  mcp-probe                  works
  probe_model_temperature    works
  retrieval_baseline         works
$ .venv/bin/python bin/embeddings_manager ls        # no PYTHONPATH
  * openai/text-embedding-3-large/reactome/Release95
  * openai/text-embedding-3-large/userguide/Release95

ruff, mypy clean; full suite passes.

🤖 Generated with Claude Code

adamjohnwright and others added 3 commits September 16, 2026 15:57
Four of the six bin/ scripts bootstrap their own sys.path, so they run from
anywhere. `embeddings_manager` and `retrieval_baseline` did not, and failed:

    $ ./bin/embeddings_manager ls
    ModuleNotFoundError: No module named 'data_generation'

The Dockerfile and CI both set PYTHONPATH (`/app/src`, `./bin:./src`), so these
worked there and nowhere else -- including in their own documented usage. That
is the same defect fixed for `evaluate` and `probe_model_temperature` in
cbe20fc; these two were missed.

**The cost of leaving it was not hypothetical.** On 2026-09-14 I hit exactly
this on `embeddings_manager`, worked around it with a PYTHONPATH prefix rather
than fixing it, and then -- because the tool felt awkward -- bypassed it
entirely and called `generate_userguide_embeddings` directly. That skipped the
`use()` call which registers a bundle, so 16 MB of correctly generated user
guide sat on disk invisible to the app, and it took a wasted deploy and a
round trip with Adam to notice. A tool that does not run as documented gets
worked around, and the workaround is where the bug was.

All six now run without PYTHONPATH.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@adamjohnwright
adamjohnwright merged commit a4de878 into main Sep 16, 2026
10 checks passed
@adamjohnwright
adamjohnwright deleted the fix/bin-scripts-bootstrap branch September 16, 2026 17:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant