phi — a bluesky bot. python + pydantic-ai + atproto + turbopuffer + cosmik/semble. fastapi for the small web surface (status pages, memory graph).

## development

- `just run` / `just dev` (hot-reload) / `just deploy` (manual fly.io) / `just release X` (tag vX, CI deploys)
- `just check` — lint + typecheck + test
- `just evals` — behavioral tests (llm-as-judge)
- `just loq-relax <file>` — relax line limit for a file. never edit loq.toml manually or compress code to fit
- work from repo root

## python style

- 3.10+ typing (`T | None`, `list[T]`)
- prefer functional over OOP
- imports at the top — no deferred imports unless circular
- never use `pytest.mark.asyncio`
- tool params: `Annotated[T, Field(description=...)]` so the LLM sees what each param does

## project structure

```
src/bot/
├── agent.py               # pydantic-ai agent + dynamic system prompts
├── config.py              # settings (env vars)
├── main.py                # fastapi app, status pages, memory graph
├── status.py              # runtime metrics
├── core/                  # atproto client, profile, mentionable, goals, self_state
├── memory/                # turbopuffer namespaces + extraction/reconciliation/review pipelines
├── services/              # notification polling + message handler
├── tools/                 # native pydantic-ai tools (posting, search, memory, goals, blog, etc.)
└── utils/                 # thread context, text formatting

personalities/             # personality definitions (public; phi.md is the live one)
evals/                     # behavioral tests
scripts/                   # proven utility scripts
sandbox/                   # experiments (graduate to scripts/ once proven)
.eggs/                     # cloned reference projects
```

## key architecture

- one agent loop, many entry points (notifications batch, scheduled musing, daily reflection, relay check). all end in `agent.run()` with different `PhiDeps`.
- actions happen as tool calls inside the run, not via structured output. the agent's return value is a brief summary string for logging.
- personality is separate from operational rules. tool docstrings carry per-tool guidance, not the system prompt.
- memory: turbopuffer namespaces (`phi-users-{handle}`, `phi-episodic`). intent state on PDS under `io.zzstoatzz.phi.*` (goals, mention consent, legacy queue).
- owner-gated mutations (`follow_user`, `propose_goal_change`, `manage_mentionable`, `create_feed`) flow through a like-as-approval mechanism: phi posts an authorization request, owner likes it, next batch lets the action through.
- MCP servers: pdsx (atproto record CRUD), pub-search (publication search). connected via `MCPServerStreamableHTTP`, fresh per `agent.run()`.
- web grounding via tavily for recency claims (`web_search`).

## documentation

deeper reference in `docs/`:
- `architecture.md` — entry points, scheduling, why this shape
- `memory.md` — the four kinds of state and how they compose
- `system-prompt.md` — block-by-block reference for what's in phi's context
- `mcp.md` — MCP integration
- `testing.md` — testing philosophy

## deployment

fly.io app `zzstoatzz-phi`. CI deploys on `v*` tag push (tangled `.tangled/workflows/deploy.yml`). `just release X.Y.Z` tags + pushes; `just deploy` runs fly deploy directly when CI is backed up. push to both `origin` (tangled) and `github` mirror.

secrets via `fly secrets set` or `fly secrets import` (pipe `grep ^KEY .env` into it to keep values off the terminal).