Skip to content

Fix the first-run break, move to 0.7.5, and make CI exercise what it claimed to - #8

Merged
pierrebrunelle merged 5 commits into
mainfrom
fix-first-run
Sep 5, 2026
Merged

pierrebrunelle merged 5 commits into
mainfrom
fix-first-run

Conversation

@pierrebrunelle

Copy link
Copy Markdown
Member

Reviewed the kit against the pixeltable 0.7.5 wheel from PyPI.

Both app.py files are clean. Every API call in chat-agent/app.py and video-search/app.py was 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

/ask has been failing 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.

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 never reaches it.

Recovery isn't 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 put the export first and explain why; app.py's docstring leads with it. The hosted docs already had the ordering right (pxt secret set before schema update) but never said why — they now share the explanation.

Three more things that were broken

  • .env.example is loaded by nothing. Neither app imports dotenv, neither pyproject depends on python-dotenv, and pixeltable never reads .env (zero hits in the 0.7.5 tree). post-create.sh copied 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 up python-dotenv would have been worse than useless here: the daemon imports app.py in-process, so a module-scope load_dotenv() would mutate the daemon's own environment and trip its STALE_CONFIG guard on the next request.
  • The dev container forwarded port 8000 while instructing pxt service update, which binds an OS-assigned port (serving/service_runner.py:22,35). It also only ever set up chat-agent, and hardcoded /workspaces/pixeltable-starter-kit under set -euo pipefail, so cloning under any other directory name aborted postCreate at the first cd.
  • docker compose up --build shipped without the API key. ANTHROPIC_API_KEY was commented out, so every route worked except /ask, with nothing explaining why. Now a bare ANTHROPIC_API_KEY in list form, 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.

pxt service update is now the only serving command recommended

pxt service run is 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 Dockerfile CMDs, where a container entrypoint must stay in the foreground (both now carry a comment saying so), and app-smoke in 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.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 — containers were installing the older patch. Bumped and relocked both.

test_pixeltable_minimum_version was 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 own uv.lock pins. Verified the new test fails when either is broken.

CI was green on paths it never ran

Three of them:

  • 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. Now wired to secrets.ANTHROPIC_API_KEY — which also makes the weekly run the canary for the model id pinned in chat-agent/app.py, so a retired model becomes a red build instead of 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 (preinstalled 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, since uvx pixeltable-new ships this tree to every user.
  • Nothing on push/PR tested the reconciler. The gating tests are file-existence and ast.parse checks; the one slow test only asserts import app succeeds, so a schema that imports cleanly but pxt schema update rejects — a bad base=, a duplicate index name — passed. schema-smoke now also runs pxt schema update then pxt schema diff per app against a temp catalog. Keyless, so it works on fork PRs.

CONTRIBUTING.md described schema-smoke as push/PR-only when it is ungated and also runs on cron and dispatch; corrected.

Left deliberately

The pinned claude-sonnet-4-5-20250929 in chat-agent/app.py:111. Pixeltable passes model= 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 into app-smoke is 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-dev in both Dockerfiles, which psycopg[binary] probably makes unnecessary — but spacy and torch are 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 passes bash -n; the YAML parses; the ffmpeg command produces an 11KB clip; docker compose config confirms the key passthrough both ways. The new drift invariant was confirmed to fail when deliberately broken.

app-smoke has 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 manual workflow_dispatch on main after merge to prove the shell before relying on it.

🤖 Generated with Claude Code

pierrebrunelle and others added 5 commits September 5, 2026 10:24
/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>
@pierrebrunelle
pierrebrunelle merged commit 797d53c into main Sep 5, 2026
6 checks passed
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