Repository navigation
Fix the first-run break, move to 0.7.5, and make CI exercise what it claimed to - #8
Merged
Merged
Conversation
/ask has been broken for anyone following chat-agent/README.md in order. The README started the daemon at line 12 and exported ANTHROPIC_API_KEY at line 30. Why that fails: `pxt schema update` starts the daemon, which imports app.py in-process (utils/app_module.py:62-88). `pxt service update` then spawns the service with subprocess.Popen and no env= (serving/service_manager.py:279-281), so the service inherits the daemon's environment as of daemon start. The Anthropic client is built lazily in the service process from os.environ. A key exported after the daemon started is invisible to it. Recovery is not obvious either: the project fingerprint hashes files and the lockfile, never the environment, so re-running `pxt service update` finds the plan in agreement and respawns nothing. You need `pxt daemon restart`, `pxt service stop agent`, then `pxt service update`. Both READMEs now say so, and app.py's docstring leads with it. `pxt service run` is exempt -- it serves from the caller's own process -- which is why the container path always worked and hid this. The hosted docs already had the rule right (`pxt secret set` before schema update) but never said why; they now share the explanation. Also here, since they are the same paragraphs: every example uses `uv run pxt` rather than warning that bare `pxt` may not be on PATH and then using it anyway, and .env.example says outright that nothing loads it -- neither app imports dotenv and pixeltable never reads .env, so it was a file that looked like a mechanism and was not one. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
- post-create.sh copied .env.example to .env, which nothing reads. Dropped.
- devcontainer forwarded port 8000 while telling the user to run
`pxt service update`, which binds an OS-assigned ephemeral port
(serving/service_runner.py:22,35). Now it prints `pxt service run
--port 8000`, which is what a fixed forwarded port is for, and says
where to find the port if you use `service update` instead.
- Only chat-agent was synced; video-search is now set up too.
- Absolute /workspaces/pixeltable-starter-kit paths plus `set -euo
pipefail` meant cloning under any other directory name aborted
postCreate at the first cd. Paths are relative to the workspace now,
and the VS Code interpreter uses ${containerWorkspaceFolder}.
- docker-compose had ANTHROPIC_API_KEY commented out, so `docker compose
up --build` produced a container where every route worked except /ask,
with nothing explaining why. The environment block is now list form
with a bare ANTHROPIC_API_KEY, which passes the host value through and
omits the variable entirely when unset -- verified both ways with
`docker compose config`. `KEY: ${KEY}` would have injected an empty
string instead.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Both apps declared >=0.7.4 and both locks pinned 0.7.4 while PyPI was at 0.7.5. Since both Dockerfiles use `uv sync --frozen`, the lock is what ships, so containers were installing the older patch. Bumped the floor in both apps, relocked both, and updated CONTRIBUTING. test_pixeltable_minimum_version was a substring check for the literal ">=0.7.4", so it could only ever go stale with the thing it guarded. Replaced with two real invariants: both apps declare the same floor, and each app's floor equals the pixeltable version its own uv.lock pins. Verified the new test fails when either invariant is broken -- a floor bumped without a relock, or the two apps disagreeing, is now a red test rather than a README that contradicts the shipped image. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Three things in this workflow had never actually run. app-smoke's /ask branch was unreachable: the repo references no secrets at all, so ANTHROPIC_API_KEY was always empty and the job took the else branch that prints OK without calling Anthropic. Wired in secrets.ANTHROPIC_API_KEY. That also makes the weekly run the canary for the model id pinned in chat-agent/app.py, so a retired model surfaces as a red build rather than as a user's first request failing. The video-search phase always printed "SKIP video-search (no clip)" because VIDEO_CLIP is set nowhere. It now generates a 2s clip with ffmpeg, which ships on ubuntu-latest, and actually ingests it and reads a query route back -- previously it only waited for openapi.json, which proves the process booted and nothing more. Generating beats committing a fixture: `uvx pixeltable-new` ships this tree to every user. Both phases shared PORT=18100 with cleanup that has never been observed working; they now get separate ports. Coverage gap: everything gating push/PR was file-existence and ast.parse checks, and the one slow test only asserted `import app` succeeds. A schema that imports cleanly but the reconciler rejects -- a bad base=, a duplicate index name -- passed. schema-smoke now also runs `pxt schema update` and then `pxt schema diff` for each app against a temp catalog, which needs no API key and catches exactly that. CONTRIBUTING described schema-smoke as push/PR-only when it is ungated and also runs on cron and dispatch; corrected, along with what each job now does. Nits: dropped the Node .gitignore section (no Node tooling here), the duplicate `slow` marker registration (the pyproject ini entry is the load-bearing one under --strict-markers), and the hardcoded /tmp smoke dirs that were only cleaned at the start of the next run. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`pxt service update` is the serving command the kit should teach. Removed `pxt service run` from every piece of guidance: both app READMEs, the root README, AGENTS.md, and the dev container's printed next steps. The "Foreground and container" sections become "Container", since compose was the only part of them still worth documenting. The dev container no longer pins forwardPorts to 8000, which only made sense for `service run --port 8000`. VS Code auto-forwards whatever port `service update` picks, and the printed steps now end with `pxt service list` to find it. Two places keep `service run`, both because a backgrounding command would be wrong there rather than as advice: - the Dockerfile CMDs, since a container entrypoint must stay in the foreground -- `service update` returns and the container would exit. Both now carry a comment saying so and pointing at `service update` for use outside a container. - app-smoke in CI, which needs a foreground process on a known port. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
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.
Reviewed the kit against the pixeltable 0.7.5 wheel from PyPI.
Both
app.pyfiles are clean. Every API call inchat-agent/app.pyandvideo-search/app.pywas checked against the 0.7.5 source and nothing is wrong — several call sites match pixeltable's own docstring examples almost verbatim. The problems are all in the docs, the dev container, Docker, and CI.The first-run break
/askhas been failing for anyone followingchat-agent/README.mdin order. The README started the daemon at line 12 and exportedANTHROPIC_API_KEYat line 30.pxt schema updatestarts the daemon, which importsapp.pyin-process (utils/app_module.py:62-88).pxt service updatethen spawns the service withsubprocess.Popenand noenv=(serving/service_manager.py:279-281), so the service inherits the daemon's environment as of daemon start. The Anthropic client is built lazily in the service process fromos.environ. A key exported after the daemon started never reaches it.Recovery isn't obvious either: the project fingerprint hashes files and the lockfile, never the environment, so re-running
pxt service updatefinds the plan in agreement and respawns nothing. You needpxt daemon restart,pxt service stop agent, thenpxt service update.Both READMEs now put the export first and explain why;
app.py's docstring leads with it. The hosted docs already had the ordering right (pxt secret setbefore schema update) but never said why — they now share the explanation.Three more things that were broken
.env.exampleis loaded by nothing. Neither app imports dotenv, neither pyproject depends onpython-dotenv, and pixeltable never reads.env(zero hits in the 0.7.5 tree).post-create.shcopied it to.env, so it looked like a mechanism. That copy step is gone and the file now says outright that you must export instead. Wiring uppython-dotenvwould have been worse than useless here: the daemon importsapp.pyin-process, so a module-scopeload_dotenv()would mutate the daemon's own environment and trip itsSTALE_CONFIGguard on the next request.pxt service update, which binds an OS-assigned port (serving/service_runner.py:22,35). It also only ever set upchat-agent, and hardcoded/workspaces/pixeltable-starter-kitunderset -euo pipefail, so cloning under any other directory name aborted postCreate at the firstcd.docker compose up --buildshipped without the API key.ANTHROPIC_API_KEYwas commented out, so every route worked except/ask, with nothing explaining why. Now a bareANTHROPIC_API_KEYin list form, which passes the host value through and omits the variable entirely when unset — verified both ways withdocker compose config.KEY: ${KEY}would have injected an empty string.pxt service updateis now the only serving command recommendedpxt service runis gone from every piece of guidance. It survives in exactly two places, both because a backgrounding command would be wrong there rather than as advice: the DockerfileCMDs, where a container entrypoint must stay in the foreground (both now carry a comment saying so), andapp-smokein CI, which needs a foreground process on a known port.0.7.5, and a floor that can't drift again
Both apps declared
>=0.7.4and both locks pinned0.7.4while PyPI was at0.7.5. Since both Dockerfiles useuv sync --frozen, the lock is what ships — containers were installing the older patch. Bumped and relocked both.test_pixeltable_minimum_versionwas a substring check for the literal">=0.7.4", so it could only ever go stale alongside the thing it guarded. Replaced with two real invariants: both apps declare the same floor, and each app's floor equals the pixeltable version its ownuv.lockpins. Verified the new test fails when either is broken.CI was green on paths it never ran
Three of them:
app-smoke's/askbranch was unreachable. The repo references no secrets at all, soANTHROPIC_API_KEYwas always empty and the job took theelsebranch that printsOKwithout calling Anthropic. Now wired tosecrets.ANTHROPIC_API_KEY— which also makes the weekly run the canary for the model id pinned inchat-agent/app.py, so a retired model becomes a red build instead of a user's first request failing.SKIP video-search (no clip), becauseVIDEO_CLIPis set nowhere. It now generates a 2s clip with ffmpeg (preinstalled onubuntu-latest) and actually ingests it and reads a query route back; previously it only waited foropenapi.json, which proves the process booted and nothing more. Generating beats committing a fixture, sinceuvx pixeltable-newships this tree to every user.ast.parsechecks; the one slow test only assertsimport appsucceeds, so a schema that imports cleanly butpxt schema updaterejects — a badbase=, a duplicate index name — passed.schema-smokenow also runspxt schema updatethenpxt schema diffper app against a temp catalog. Keyless, so it works on fork PRs.CONTRIBUTING.mddescribedschema-smokeas push/PR-only when it is ungated and also runs on cron and dispatch; corrected.Left deliberately
The pinned
claude-sonnet-4-5-20250929inchat-agent/app.py:111. Pixeltable passesmodel=through with no validation, so nothing in the repo can tell whether that snapshot is still live, and swapping in a newer string is an unverifiable edit that goes stale again in months. Wiring the secret intoapp-smokeis the durable fix: the weekly run now exercises/ask, so retirement surfaces as a failure. Worth a separate decision on its own cadence.build-essential libpq-devin both Dockerfiles, whichpsycopg[binary]probably makes unnecessary — butspacyandtorchare the other consumers and I couldn't verify the images still build without it.Verified locally
ruff check,ruff format --check,pytest tests/(49 passed, 1 skipped). All embedded workflow bash passesbash -n; the YAML parses; the ffmpeg command produces an 11KB clip;docker compose configconfirms the key passthrough both ways. The new drift invariant was confirmed to fail when deliberately broken.app-smokehas never actually executed in its current form — the five most recent scheduled runs (Aug 3–31) failed against an older workflow, and the current job landed 2026-09-02, after the last cron. Worth one manualworkflow_dispatchonmainafter merge to prove the shell before relying on it.🤖 Generated with Claude Code