# Pixeltable for Developers

> Scoped developer context: install, schema DSL, CLI, serving, MCP, and agent tooling.
> Full product overview (class-based Quick Start): https://pixeltable.com/llms.txt

## Install
- Python 3.11+: `pip install 'pixeltable[serve]'`
- Project root: `pxt init` (schema and service refuse a file without one)
- Starter app: `pxt service example --out app.py`
- TypeScript SDK (Cloud): `@pixeltable/sdk`

## Schema DSL (product path)
- `TableModel = pxt.model_base()` then `class Docs(TableModel, name='docs'):`
- Stored columns as annotations (`text: pxt.String`, `image: pxt.Image | None`)
- Computed fields as class body assignments (`summary = expr`), not annotations
- Views: `class Chunks(TableModel, name='chunks', base=Docs, iterator=...):`
- Indexes: `__indexes__ = [pxt.EmbeddingIndex(col, string_embed=...)]` (also `image_embed=` / `embedding=`)
- Apply: `pxt schema diff app.py my_app` then `pxt schema update app.py my_app`
- Drops need `--allow-destructive`; extras are `pxt schema prune app.py my_app -f`
- Same file on Cloud: `PIXELTABLE_API_KEY` plus `[[pixeltable.database]]` `name = 'pxt://org:db'`, then `pxt db update`, `pxt schema update`, `pxt service update`

## Cloud for agents
- Key + org: user signs in on pixeltable.com (header Sign in / Dashboard). Create `sk_...` at `/dashboard/<org>/api-keys`. Ask for org slug and key. `pxt org list` then `pxt db update pxt://org:db`. CLI cannot create orgs. `PIXELTABLE_API_KEY` wins over `~/.pixeltable/config.toml`. Do not invent `internal-api.pixeltable.com`.
- Order is required: `pxt db update` then `pxt schema update` then `pxt service update`. Schema first fails `404: UDF not found`. Omit `cpu` / `memory_mb` / `workers`.
- Hosted URL: `https://<org>-<db>.svc.pxt.run/<service>/` with a trailing slash and `X-api-key`. `/docs` is the same host and needs the key. Browse on the website dashboard (`/dashboard/<org>/<db>`). `pxt dashboard` and `pxt service list` are local only.
- Agents and CI need `-f` (no TTY). `pxt.create_table()` at import in `app.py` fails `pxt service check`. Scaffold with `pxt service example`, not `pixeltable-new`.

## Notebook / REPL API (still valid)
- Create tables: `pxt.create_table(name, {col: pxt.Image, ...})`
- Run AI on insert/change: `table.add_computed_column(out=fn(table.col))`
- Vector search: `table.add_embedding_index(col, embedding=...)` then `col.similarity(string=query)`
- Reusable queries: `@pxt.query`; custom functions: `@pxt.udf`
- Versioning: `table.history()`, `table.revert()` / `pxt revert`

## Serving
- Local or hosted: `pxt service update app.py my_app` or `pxt service update app.py pxt://org:db` (`FastAPIRouter` in the same file)
- `pxt service run` is local only; `pxt db update` packs hosted image and workers
- Solutions (ten primitives): https://pixeltable.com/solutions

## Agent & MCP tooling
- Agent Skill: `npx skills add pixeltable/pixeltable-skill`
- Skill source: https://github.com/pixeltable/pixeltable-skill
- Skills index: https://pixeltable.com/.well-known/agent-skills/index.json
- Onboard this agent: https://pixeltable.com/get-started.md
- Hosted WebMCP (read-only docs tools): https://pixeltable.com/mcp
- MCP server card: https://pixeltable.com/.well-known/mcp/server-card.json
- Installable MCP (stdio; table/REPL exploration):
  - pixeltable-developer: https://github.com/pixeltable/mcp-server-pixeltable-developer
  - pixeltable-memory: https://github.com/pixeltable/pixeltable-mcp-server
- Ask endpoint (NLWeb): POST https://pixeltable.com/ask (10 req/min per IP)

## Authentication
- Open-source library: none required.
- Public `/ask` and `/mcp`: none required.
- Pixeltable Cloud: API keys via `X-api-key` (dashboard); WorkOS bearer tokens for the control plane.
- Agent registration: https://pixeltable.com/auth.md (WorkOS AuthKit at https://signin.pixeltable.com).
- OAuth PRM: https://pixeltable.com/.well-known/oauth-protected-resource
- OpenAPI for public agent endpoints (`/ask`, `/mcp`, `/health`): https://pixeltable.com/openapi.json
- A public Pixeltable Cloud REST API (orgs/tables/billing) is not published yet.

## References
- Documentation: https://docs.pixeltable.com/
- API reference: https://docs.pixeltable.com/sdk/latest/pixeltable
- HTTP serving: https://docs.pixeltable.com/howto/deployment/serving
- Full docs as text: https://docs.pixeltable.com/llms-full.txt
- Architecture for agents: https://github.com/pixeltable/pixeltable/blob/main/AGENTS.md
- GitHub: https://github.com/pixeltable/pixeltable