fix(install): give the studyloop tool venv the semantic runtime - #45
Merged
Merged
Conversation
… runtime `studyloop web` warms the query encoder at boot inside the STUDYLOOP tool venv; the warm imports tokenizers, onnxruntime, huggingface_hub, numpy and sqlite_vec there. install_workspace_tools() co-installs agent-session-tools into that venv with `--with-editable <path>` and no extras, so none of them arrive (the standalone agent-session-tools tool gets [all], but it is a different venv). Observed on the maintainer's install: the warm fails in 9 ms with "RuntimeError: tokenizers is not installed", the header chip reads "semantic: failed (0.0s)", and `studyloop doctor` in the same venv reports the encoder check as "does not apply". The same warm in the repo .venv reaches `warm` in 0.28 s. Nothing could see it: the nightly installer job checks `--version` and `--help`, which pass without the runtime. Four RED, each for the stated reason: - the installer's studyloop command co-installs the bare path (2 tests); - scripts/smoke-uv-tool-install.sh neither co-installs [all] nor imports the runtime in the studyloop venv; - the nightly installer job has no step importing it after install.sh.
…tool venv `studyloop web` warms the query encoder in-process at boot, inside the studyloop tool venv, and every hybrid search runs there too. The installer co-installed agent-session-tools into that venv bare, so tokenizers, onnxruntime, huggingface-hub, numpy and sqlite-vec never arrived: the warm failed at import, the header chip read "semantic: failed (0.0s)", search silently stayed lexical-only, and `doctor` in the same venv reported the encoder check as "does not apply". The standalone agent-session-tools tool always had [all]; it is a different venv. - installers.py: `--with-editable <agent-session-tools>[all]`. - scripts/smoke-uv-tool-install.sh: the same co-install, plus an import of the runtime in the studyloop venv (import level only; the isolated HOME has no Hugging Face cache and the artefact is `doctor --fix`'s job). - nightly-install.yml: a step importing the runtime from the studyloop venv after install.sh -- the job's --version/--help checks pass without it, which is why nothing in CI ever saw this. - docs/setup-guide.md: both manual commands carry [all], with one sentence on why the co-install needs it. - CHANGELOG: Unreleased/Fixed entry. Verified on the maintainer's machine after rebuilding the studyloop tool venv with the fixed command: the web-surface warm reaches `warm` (bge-small-en-v1.5), and the real app started from that venv on 127.0.0.1:8599 answers /api/retrieval/health with state "warm".
There was a problem hiding this comment.
Copilot review overview
🟢 Approval recommended
The reviewed changes resolve the semantic runtime installation issue with supporting tests and CI checks.
Review effort: Lite
Findings: None
What changed in this PR
Fixes source installation so the studyloop tool environment includes the semantic runtime required by web retrieval.
Changes:
- Co-installs
agent-session-tools[all]. - Adds smoke and nightly runtime checks.
- Updates tests, setup documentation, and changelog.
| File | Summary |
|---|---|
scripts/smoke-uv-tool-install.sh |
Verifies semantic runtime imports. |
packages/studyloop/tests/test_smoke_installed_cli_contract.py |
Tests smoke-script expectations. |
packages/studyloop/tests/test_installers_workspace_tools.py |
Tests installer extras. |
packages/studyloop/tests/test_ci_workflow_contract.py |
Tests nightly verification. |
packages/studyloop/src/studyloop/installers.py |
Installs semantic extras. |
docs/setup-guide.md |
Documents required extras. |
CHANGELOG.md |
Records the installation fix. |
.github/workflows/nightly-install.yml |
Validates the installed runtime. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
studyloop webstarted from the installed tool showed semantic: failed (0.0s) on every source install. The installer co-installedagent-session-toolsinto thestudylooptool venv with no extras, so the semantic runtime (tokenizers, onnxruntime, huggingface-hub, numpy, sqlite-vec) never reached the venv that serves the web UI. The server's boot-time encoder warm failed at import in ~10 ms, search stayed lexical-only, andstudyloop doctorin the same venv called the encoder check "does not apply". The standaloneagent-session-toolstool always had[all], but it is a different venv.Changes
installers.py:--with-editable <agent-session-tools>[all]for the studyloop tool.scripts/smoke-uv-tool-install.sh: the same co-install, plus an import of the runtime in the studyloop venv.nightly-install.yml: a step importing the runtime from the studyloop venv afterinstall.sh. The job's--version/--helpchecks pass without it, which is why CI never caught this.docs/setup-guide.md: both manual commands carry[all].RED
a652d3da(4 failing for the stated reasons) -> GREEN8b3e3a7c.Verification
failed ... RuntimeError: tokenizers is not installedin 9 ms. After, it reportswarm(bge-small-en-v1.5). The real app started from that venv on 127.0.0.1:8599 answered/api/retrieval/healthwith"state":"warm".doctor'squery_encoder_artefactwent from info to pass, with no failing checks.studyloop --versionis 0.5.0 (the env's metadata still said 0.2.1 from 5 Sept).scripts/smoke-uv-tool-install.shpasses end to end.Found, not fixed here
python3is a mise shim,scripts/smoke-installed-cli.sh(unchanged) fails under the smoke's isolated HOME, because mise cannot find its trust state there. With a realpython3first on PATH the smoke passes.uv tool install 'agent-session-tools[semantic]') points at the wrong venv.[semantic]does not declareonnxruntime, anddoctorreports a missing runtime as info. Filed separately.