pixeltable-starter-kit AGENTS.md

AGENTS.md

Instructions for AI coding agents working in the Pixeltable Starter Kit.

Apps

Apps are one Python file (app.py): TableModel classes and a FastAPIRouter. The loop is Declare, Experiment, Serve: apply with pxt schema update, serve with pxt service update or pxt service run, then insert / /ask / pxt dashboard. If .venv is not on PATH after uv sync, prefix pxt with uv run. Indexes belong on the model (__indexes__). Routes live on FastAPIRouter. No TOML route tables. Already have FastAPI? app.include_router(...) on the router in app.py.

Same file on Cloud: pxt db update pxt://org:mydb, then pxt secret set pxt://org KEY=..., then pxt schema update app.py pxt://org:mydb, then pxt service update app.py pxt://org:mydb. Then t = pxt.get_table('pxt://org:mydb/docs'). pxt db update packs the hosted image and workers; it is not Experiment. pxt schema update applies tables. It does not start HTTP. pxt service update starts HTTP (local or pxt://). pxt service run is local only. Experiment on Cloud is dashboard insert plus pxt schema diff.

uvx pixeltable-new myapp
cd myapp && uv sync
pxt schema update app.py agent
pxt service update app.py agent

agent and videointel are catalog directories, not folders on disk. Video: uvx pixeltable-new myapp --video, then TARGET videointel.

Layout

video-search/   Frames, CLIP, images. TARGET videointel. uvx --video
chat-agent/     Knowledge, memory, LLM. TARGET agent. uvx default
tests/          Structure and config. Schema smoke: --run-slow.

Do not add templates/, backend/, serving/, batch/, or a PaaS deploy/ zoo. New verticals: edit app.py or add a folder next to these two with the same apply path.

Extend an app

1. Add a TableModel in that app's app.py.
2. Put indexes on the class (__indexes__).
3. Register routes on the existing FastAPIRouter.
4. Run pxt schema update app.py agent (or videointel).

Annotation is a stored column. Assignment is a computed column. Primary key is pxt.Column(..., primary_key=True), not a bare typed field. Optional is T | None. Do not use pxt.Required. Similarity uses string=: col.similarity(string=query). In @pxt.query, alias as score=sim.