vh
3f3a9f7b0f
The textual TUI (tui.py) is superseded by the web console (ratatoskr-web) and is removed per the no-backwards-compat rule. The `ratatoskr` command stays as a headless client: --send / --whoami / --characters / --set-persona-pad / --seed-first-message still work; invoking it with no --send now returns a usage error (rc 10) instead of launching the TUI. Removed: src/ratatoskr/tui.py, tests/test_tui.py, the textual + textual-dev deps, and cli.py's run_tui launch path. cli.py's shared exports (USER_AGENT, ParsedArgs, formatters) stay — web/entrypoint.py and tier3.py depend on them. BREAKING CHANGE: the interactive `ratatoskr --agent X` TUI is gone; use the web console (ratatoskr-web) for interactive debugging, or --send for scripted. Verified: full suite 520 passed; ratatoskr --help exit 0; no-send -> rc 10; web/provider/tier3 import clean; textual absent from the lockfile.
103 lines
4.3 KiB
Markdown
103 lines
4.3 KiB
Markdown
# 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)
|