# Ratatoskr

A Worldtree Conversation API debug console. Runs up and down Worldtree's
API surface — sessions, turns, persona, tools, admin events, Bifrost
state — carrying messages between layers. Like the squirrel.

The product **is** the observability surface; chat is the input mechanism.
Devs run Ratatoskr against a local Worldtree to watch a turn flow through
every layer of the system, side-by-side. The interactive surface is the
web console (`ratatoskr-web`); a headless `--send` CLI drives scripted smokes.

## Status

**v0 scaffold.** Design locked; implementation hasn't started. The dev
team owns the implementation pass.

## Read in this order

1. **`docs/design-brief.md`** — the locked design. Read this first. Every
   architectural decision is recorded with its rationale, the alternatives
   considered, and (where relevant) the operator's lock-in moment.
2. **`docs/SPEC-PIN.md`** — what Worldtree spec version Ratatoskr is built
   against, where the vendored snapshot lives, and how to bump the pin.
3. **`docs/conversation-api-spec.md`** — the vendored Worldtree spec
   snapshot. Read this to understand the API surface Ratatoskr consumes.
   **Do not import anything from a Worldtree checkout** — the boundary is
   the spec, not the code. See `docs/design-brief.md` §2.
4. **`CLAUDE.md`** — Claude Code conventions for this repo (mostly
   inherited from the Corviduo template).
5. **`persistent-memory.md`** — durable intent across context resets.
   Update as decisions and state evolve.

## Quickstart

```bash
# 1. Environment
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"

# 2. Verify the spec pin
cat docs/SPEC-PIN.md   # documented Worldtree SHA + bump procedure

# 3. Tests (none yet; scaffold only)
uv run pytest

# 4. Run against a local Worldtree (Worldtree must be running)
# Interactive web console:
ratatoskr-web --host 0.0.0.0 --port 8765
# Headless CLI (scripted smoke):
ratatoskr --send "hello" --new --agent mimir --api-key "$WORLDTREE_API_KEY"
```

## What this repo is NOT

- **NOT** a polished consumer for Worldtree's end-users — that's the web app.
- **NOT** a Worldtree admin tool — admin CLI is separate (`sessions_cli.py` lives in Worldtree).
- **NOT** a featuretracking shadow of the web app — when the Conversation API surface grows, Ratatoskr does not necessarily grow with it.
- **NOT** a remote-Worldtree debug client — file-tail surfaces (persona log, server log) assume local-dev posture.

The full negative-clause list lives in `docs/design-brief.md` §6.

## Boundary rule

Ratatoskr depends on a small, fixed surface:

- `httpx` + `httpx-sse` (network layer)
- `starlette` + `uvicorn` (the web console; the `web` extra)
- Worldtree's **published Conversation API spec** at the pinned SHA

Hard rule: **no imports from a Worldtree checkout.** No `core.*` imports,
no `from worldtree.*`, no shared models, no submodule of Worldtree. The
spec is the entire surface. Boundary smoke test at `tests/test_no_worldtree_imports.py`
enforces this in CI.

## Version-skew strategy

The dev team is decoupled from Worldtree's dev team. To detect drift
when Worldtree changes the API:

1. **Spec-version pin** in `pyproject.toml` (`worldtree-spec-rev`). Bump
   explicitly; bumps are a tracked action.
2. **Recorded-SSE snapshot tests** at `tests/snapshots/`. Captured against
   a live Worldtree; replayed in CI. Re-record after every pin bump.
3. **Conformance smoke test** — boots Worldtree via Docker compose in CI,
   runs a one-turn happy path. Catches integration-level drift.

See `docs/SPEC-PIN.md` for the bump procedure.

## Consumer-side discoveries

If you find a spec gap, ambiguity, or missing-but-needed endpoint while
working on Ratatoskr: route the discovery back to worldtree-dev via
althing rather than via PR on Worldtree directly. The separate-team
boundary is intentional and helps catch spec gaps that an in-tree
consumer would paper over.

## Related repos

- [Worldtree](https://gitea.phasefinal.com/vh/Worldtree) — the API Ratatoskr consumes
- [brokkr-smithy](https://gitea.phasefinal.com/vh/brokkr-smithy) — authored this design brief
- [Skaldsong](https://gitea.phasefinal.com/vh/skaldsong) — another Worldtree API consumer (Python; render-and-aggregate pattern)
- [mead-hall](https://gitea.phasefinal.com/vh/mead-hall) — another Worldtree API consumer (TypeScript; server-side broker)