vh
9703eb2b6b
Worldtree Conversation API debug TUI. Multi-pane observability dashboard: chat transcript + persona/Vili affect log + tool events + admin events + Bifrost state + tool inventory + (opt-in) raw server log. Design locked at docs/design-brief.md (originated as brokkr-smithy/docs/ratatoskr-design-brief.md). Operator-locked decisions: - Textual application-shell framework (multi-pane dashboard, not REPL). - Separate repo + separate dev team (no Worldtree-source imports). - httpx-sse for SSE consumption (reference Python SSE-resume impl). - Triple version-skew mitigation: spec-pin in pyproject.toml + recorded SSE snapshot tests + conformance smoke. Initial pin: Worldtree v0.19.0 at 55101e909abcd2219833266b6f905c5bc956e0f0. - Persona pane: label-don't-refuse PII posture. - Server-log pane: opt-in via --server-log <path>. - Two-stage Ctrl-C (cancel then exit). - Markdown rendering default-on; --raw opt-out. In the box: - docs/design-brief.md — the locked design with full rationale. - docs/SPEC-PIN.md — Worldtree spec pin + bump procedure. - docs/conversation-api-spec.md + docs/conversation_api.contract.md — vendored Worldtree spec snapshots at the pinned SHA. - pyproject.toml — Python 3.12, hatchling, uv-managed, deps locked. - src/ratatoskr/ — stub package (cli.py raises NotImplementedError). - tests/test_no_worldtree_imports.py — boundary smoke test PASSING. - tests/snapshots/README.md — recording convention for SSE snapshot tests. Not in the box yet: - Gitea remote (operator/infra-ops to register at vh/ratatoskr). - Implementation — the dev team owns this; design brief is the spec. Origin: althing thread 01KS3R34XD3N6HMK91VXESHGW7 (worldtree-dev → brokkr-smithy-dev, 2026-05-20). Volva consulted via thread 01KS3VF6W33N3V5FNMGQ91YNVD.
100 lines
4.1 KiB
Markdown
100 lines
4.1 KiB
Markdown
# Ratatoskr
|
|
|
|
A Worldtree Conversation API debug TUI. 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, in one terminal.
|
|
|
|
## 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 (once implementation lands)
|
|
# Worldtree must be running: python -m core.conversation_api
|
|
ratatoskr --agent mimir
|
|
```
|
|
|
|
## 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 three things only:
|
|
|
|
- `httpx` + `httpx-sse` (network layer)
|
|
- `textual` (TUI framework)
|
|
- 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)
|