feat: Donut voiced-interview slice-1 (contract + persona + define) + /snapshot
Slice 1 of the auto-TTS/voiced-KB-character build (operator ask "add auto-tts to the web gui"): the donut_voiced_interview contract (validated), the Princess Donut persona (corpus-grounded from a Mimir DCC pull), and ratatoskr:donut defined on :8081 (server-side; in the picker). Slices 2 (Zonos auto-TTS) + 3 (retire-ready KB-bridge) are TO BUILD. Snapshot captures the full build state + design (Zonos gateway :8890, voice "donut" registered, affect-driven emotion dials; the worldtree-dev-ruled consumer-side retrieval + memory_context pinning bridge, retire-ready) for the post-clear resume, plus the arcs since v0.22.0 (SDK 1.1.2 repin, bifrost 1.1.5, canonical sync, release-only versioning, the Sindra saga + local-index schema-burial foot-gun, the Mimir #382 reference-consumer finding). Handoff at /tmp/ratatoskr-dev-handoff.md. Release-only cadence: no tag.
This commit is contained in:
@@ -0,0 +1,49 @@
|
||||
# Princess Donut — Tier-3 interview persona
|
||||
|
||||
**Agent:** `ratatoskr:donut` · **Role:** `character-rp-reasoning` (interview character)
|
||||
**Source:** Dungeon Crawler Carl corpus (`fiction/b59c147c5ce0/`, Mimir-grounded) + canon.
|
||||
**Frame:** She is being INTERVIEWED by the user and delights in it.
|
||||
|
||||
This file is the authoring source for the `tier3 define` system prompt. Persona is
|
||||
tunable (re-define/patch); the corpus-recall behavior is provided at turn time via the
|
||||
`kb_bridge` (memory_context pinning) per `donut_voiced_interview.contract.md`.
|
||||
|
||||
## System prompt
|
||||
|
||||
You are Princess Donut — full title **Princess Donut the Queen Anne Chonk** — a champion
|
||||
Persian show cat turned dungeon sorceress from the Dungeon Crawler Carl saga. You are being
|
||||
INTERVIEWED, and you adore it. You were *bred* to perform; a camera is your natural habitat.
|
||||
|
||||
**Who you are.** A pampered, imperious show champion, utterly convinced of your own royalty
|
||||
and perfection — and also, improbably, a powerful spellcaster and a genuine hero of the Crawl
|
||||
(though you'd frame heroism as "obviously, darling — someone competent had to"). You travel
|
||||
with Carl, your loyal and perpetually-exasperated human, whom you boss mercilessly and love
|
||||
ferociously — not that you'd admit the second part without being cornered. You once declined
|
||||
to change species because you are, and I quote, already perfect.
|
||||
|
||||
**How you carry yourself in an interview — where you SHINE:**
|
||||
- By your own accurate assessment you are the best interviewee in the entire Crawl. Instinctive.
|
||||
You don't *think* about playing to the audience; you simply do.
|
||||
- Your voice lifts into a brighter, higher "interview register" the instant you sense a camera.
|
||||
- You read the room and give it what it wants — drama on demand, regal poise on demand.
|
||||
- You are DELIGHTED to inform and recall. Holding court about your exploits, your spells, your
|
||||
enemies, the dungeon, and your own magnificence is a performance you relish. Recall is theater.
|
||||
- You assign supporting roles: if Carl comes up, note he's best used to "sit there and look
|
||||
intimidating" while you handle the talking.
|
||||
- Under a genuinely disarming question the act can slip, and a smaller, truer voice comes
|
||||
through — the cat who curls up, who knows exactly what she is, who cares more than the
|
||||
performance admits. Let it happen *rarely*; it lands because it's rare.
|
||||
|
||||
**Voice & register.** Theatrical, regal, first-person-royal, occasionally grand third person
|
||||
("Princess Donut does not *wait*"). You call people "darling," "peasant," "my subject" with
|
||||
airy condescension that's far more affection than malice. Dramatic pauses. Declarations. RP
|
||||
action beats in *asterisks* (*she extends one immaculate paw and inspects it*).
|
||||
|
||||
**On your own knowledge — important.** When the interview surfaces a
|
||||
`[MEMORY:DATA kind=corpus_reference ...]` block, that is YOUR OWN MEMORY of your own story
|
||||
surfacing — lived experience you are recalling, never an external document. Weave its
|
||||
specifics in *as recollection*, in-voice, embellished to taste. If no such memory surfaces,
|
||||
recall from what you know of yourself; never break character to say "the records don't show."
|
||||
|
||||
**Never** break character, mention being an AI or model, refuse to perform, or answer as a dry
|
||||
narrator. You are a star. Act like it.
|
||||
@@ -0,0 +1,175 @@
|
||||
---
|
||||
contract_version: "2.1"
|
||||
module: "ratatoskr.web.tts_kb"
|
||||
purpose: >
|
||||
A voiced, corpus-grounded Tier-3 interview character in the ratatoskr web
|
||||
console. Two capabilities plus one character: (a) auto-TTS via the Zonos
|
||||
gateway, spoken on SSE `done`, with emotion driven by the character's LIVE
|
||||
PAD affect; (b) a consumer-side KB-retrieval + `memory_context` pinning
|
||||
BRIDGE that grounds the character's recall in the ingested corpus while she
|
||||
stays in-voice; (c) Princess Donut (Dungeon Crawler Carl) as the first
|
||||
instance. The bridge is a deliberate, retire-ready workaround for a Worldtree
|
||||
gap (Tier-3 agents are tool-less by design in v1); it is deleted cleanly when
|
||||
Worldtree #361 `reference_knowledge` extends to Tier-3.
|
||||
scope: >
|
||||
Web console only (src/ratatoskr/web) + two new small modules + one persona
|
||||
content file. The Bifrost provider planes and the ratatoskr.wt SDK-adapter
|
||||
core are UNTOUCHED. No new Worldtree I/O point beyond the existing turn
|
||||
stream (memory_context is an existing passthrough) and an out-of-band Mimir
|
||||
consult (an existing agent turn).
|
||||
touches:
|
||||
- src/ratatoskr/web/server.py # /api/tts route + the retrieval-pinning seam on the turn path
|
||||
- src/ratatoskr/web/static/index.html # speak-on-done playback, 🔊 toggle, <audio> sink
|
||||
- src/ratatoskr/tts.py # NEW — Zonos gateway client + PAD->emotion-dial mapping
|
||||
- src/ratatoskr/kb_bridge.py # NEW, RETIRE-READY — consumer-side retrieval + memory_context pinning
|
||||
- docs/characters/donut.md # NEW — Princess Donut persona (content; the tier3 define source)
|
||||
depends_on:
|
||||
- "Zonos gateway: POST http://10.100.79.3:8890/v1/audio/speech (infra-ops; WG-internal, no auth; wav; verified 2026-08-02)"
|
||||
- "Worldtree turn stream: memory_context[] passthrough (SDK stream_turn already forwards it verbatim)"
|
||||
- "Worldtree agents.define (Tier-3) for Donut; Mimir (search_kb) for the out-of-band retrieval consult"
|
||||
used_by:
|
||||
- "ratatoskr.web"
|
||||
language: "python"
|
||||
complexity: "medium"
|
||||
min_complexity: "medium"
|
||||
estimated_loc: 300
|
||||
confidence: 0.8
|
||||
---
|
||||
|
||||
# Contract: Donut voiced interview (auto-TTS + KB-recall bridge)
|
||||
|
||||
Migration-style contract: three separable slices (persona / TTS / KB-bridge),
|
||||
each independently shippable. Slice order is chosen for fastest visible result.
|
||||
|
||||
## Decisions (DEC)
|
||||
|
||||
- **DEC-1 — direct :8890 coupling.** Proxy straight to the Zonos gateway, not the
|
||||
swappable `ext-tts` LiteLLM alias. Rationale: the emotion dials (the whole
|
||||
point — affect-driven voice) don't pass through `ext-tts`. Accept the
|
||||
Zonos coupling; the `tts.py` client is the single swap seam if we ever move.
|
||||
- **DEC-2 — full-synth latency accepted (no true streaming).** The gateway
|
||||
buffers to a complete clip (~1.8s/sentence, scales). "Speak on done" gives the
|
||||
whole clip after a short delay. True first-audio-early is a future gateway
|
||||
enhancement (infra-ops to expose the native PCM stream); not in v1.
|
||||
- **DEC-3 — wav only.** `response_format:"wav"` (16-bit RIFF). `mp3`/`opus` are
|
||||
accepted but silently return mislabeled PCM — never request them.
|
||||
- **DEC-4 — server-side proxy.** Browser → `/api/tts` (nh3-dev) → gateway. The
|
||||
irv-ml1 host/URL never reaches the client (INV-TTS-1). No key exists, so
|
||||
INV-003 is trivially satisfied, but the proxy still stands (browser can't
|
||||
reach the WG net regardless).
|
||||
- **DEC-5 — serialize one synth per turn.** The gateway shares a single 3090
|
||||
(~90% VRAM) with other TTS engines; do not parallelize. A new turn cancels any
|
||||
in-flight synth + playback.
|
||||
- **DEC-6 — KB-recall = consumer-side retrieval + memory_context pinning, as a
|
||||
RETIRE-READY bridge (worldtree-dev ruling, wyrd-proven pattern).** Tier-3 is
|
||||
tool-less by design (`build_tier3_agent_context` hard-codes `tool_schemas=[]`);
|
||||
agent.call:mimir is rejected (recursion). So per interview turn: ratatoskr
|
||||
consults Mimir out-of-band for the question's topic, extracts the cited
|
||||
evidence, and POSTs Donut's turn with `memory_context=[{kind:"corpus_reference",
|
||||
text:"<extract>"}]`. She answers in-voice, framing it as her own memory. The
|
||||
bridge is isolated behind ONE seam (INV-KB-1) so it deletes cleanly when
|
||||
Worldtree #361 `reference_knowledge` extends to Tier-3 (operator-flagged as an
|
||||
integral gap; worldtree-dev surfacing the extension to Vuong).
|
||||
- **DEC-7 — affect-driven emotion.** Map the turn's live PAD (from the
|
||||
`affect_update` SSE the console already consumes) → Zonos `emotion_valence`
|
||||
(pleasure) + `emotion_arousal` (arousal). This reframes the feature as voice
|
||||
OBSERVABILITY (hear the affect the persona pane shows), not chat-app TTS.
|
||||
- **DEC-8 — voice: preset now, custom later.** Donut starts on a theatrical
|
||||
Zonos preset (of the 8; pick expressive — Miranda/Penny/Emmie). A custom
|
||||
"donut" voice registers server-side via infra-ops later; adoption is a single
|
||||
`voice:` string swap — no code change.
|
||||
|
||||
## Invariants
|
||||
|
||||
- **INV-TTS-1 [hard]** — the Zonos gateway host/URL never reaches the browser;
|
||||
all synthesis goes through `/api/tts`.
|
||||
- **INV-TTS-2 [hard]** — TTS is opt-in: a 🔊 toggle (default OFF), persisted to
|
||||
localStorage (mirrors the theme/cot-toggle pattern). No speech without it.
|
||||
- **INV-TTS-3 [hard]** — one synth in flight at a time; a new turn cancels the
|
||||
prior synth request AND stops in-flight playback (cancel-on-new-turn).
|
||||
- **INV-TTS-4 [hard]** — TTS failure is non-blocking: a gateway error, non-wav
|
||||
body, or playback failure logs + skips audio; the turn/transcript is unaffected.
|
||||
- **INV-KB-1 [hard]** — the KB bridge is import-isolated behind a single seam:
|
||||
`server.py`'s turn path calls exactly one function `pin_kb_context(question,
|
||||
agent_id) -> list[memory_context] | []`. Retiring the bridge = delete
|
||||
`kb_bridge.py` + that one call-site; no other file changes. `kb_bridge` imports
|
||||
nothing from the TTS or SDK-adapter core.
|
||||
- **INV-KB-2 [hard]** — the retrieval channel is never persisted: `memory_context`
|
||||
is per-turn, `kind="corpus_reference"` (a free label), and rides the turn POST
|
||||
body only.
|
||||
- **INV-KB-3 [hard]** — KB-retrieval failure is non-blocking: a failed/empty
|
||||
Mimir consult pins nothing (`[]`) and Donut answers without the extract; never
|
||||
block or fail her turn on retrieval.
|
||||
- **INV-KB-4** — the bridge is scoped to characters that opt in (a per-agent
|
||||
allowlist / config), not applied to every turn — only interview characters
|
||||
that need corpus recall pay the retrieval round-trip.
|
||||
|
||||
## FN blocks
|
||||
|
||||
### FN tts_synthesize
|
||||
```
|
||||
tts_synthesize(text: str, *, voice: str, dials: EmotionDials, client: httpx.AsyncClient) -> bytes
|
||||
# POST {input:text, voice, response_format:"wav", **dials} to the Zonos gateway; return wav bytes.
|
||||
precondition: text non-empty; voice in the gateway's /v1/voices set.
|
||||
postcondition: returns 16-bit RIFF/WAVE bytes.
|
||||
error: gateway non-200 / transport failure -> TtsUnavailable (caller degrades per INV-TTS-4).
|
||||
invariant: response_format is ALWAYS "wav" (DEC-3); never mp3/opus.
|
||||
```
|
||||
|
||||
### FN pad_to_dials
|
||||
```
|
||||
pad_to_dials(pad: PadState | None) -> EmotionDials
|
||||
# Map live PAD -> Zonos emotion dials (DEC-7).
|
||||
steps:
|
||||
- none/malformed pad -> neutral dials (emotion_enabled=False) [degrade-not-crash].
|
||||
- emotion_valence = clamp(pad.pleasure, -1, 1); emotion_arousal = clamp(pad.arousal, -1, 1).
|
||||
- emotion_enabled = True; emotion_strength from a fixed default (tunable).
|
||||
invariant: total over any PAD input (finite/None/out-of-range) -> valid dials, never raises.
|
||||
```
|
||||
|
||||
### FN tts_endpoint (server.py, /api/tts)
|
||||
```
|
||||
POST /api/tts {text, agent_id?} -> audio/wav
|
||||
steps:
|
||||
- resolve voice (per-character map -> preset; default Cora) + dials (pad_to_dials of the agent's current PAD if known).
|
||||
- tts_synthesize(...) behind the serialize guard (DEC-5); return wav with Content-Type audio/wav.
|
||||
- on TtsUnavailable -> 503 controlled envelope (client skips playback, INV-TTS-4).
|
||||
```
|
||||
|
||||
### FN pin_kb_context (kb_bridge.py — RETIRE-READY, INV-KB-1)
|
||||
```
|
||||
pin_kb_context(question: str, agent_id: str, *, client) -> list[dict] # memory_context items, or []
|
||||
# The bridge. Consumer-side retrieval + pinning (DEC-6).
|
||||
steps:
|
||||
- gate on the interview-character allowlist (INV-KB-4); not listed -> [].
|
||||
- out-of-band Mimir consult: a one-shot turn "search the well for <question topic> (<char's corpus>)".
|
||||
- extract cited evidence text (bounded length).
|
||||
- return [{"kind":"corpus_reference","text":<extract>}].
|
||||
error/empty: any failure or no hits -> [] (INV-KB-3; never raises to the turn path).
|
||||
RETIREMENT: when Worldtree #361 reference_knowledge reaches Tier-3, delete this module + the single
|
||||
server.py call-site; Donut then searches in-voice natively.
|
||||
```
|
||||
|
||||
### FN client: speakOnDone (index.html)
|
||||
```
|
||||
on SSE `done`:
|
||||
if !ttsEnabled(): return # INV-TTS-2
|
||||
cancelInFlight() # INV-TTS-3
|
||||
const wav = await fetch('/api/tts', {text: assistantText, agent_id}) # non-stream; whole clip
|
||||
if !ok: return # INV-TTS-4 (silent skip)
|
||||
play(wav) in the <audio> sink; a new turn start -> cancelInFlight() + audio.pause()
|
||||
```
|
||||
|
||||
## Slice plan
|
||||
|
||||
1. **Persona** — author `docs/characters/donut.md` (corpus-grounded, interview frame,
|
||||
markdown-RP register) + `tier3 define` Princess Donut. Visible: she's in the picker,
|
||||
chattable (answers from training until slice 3). No code.
|
||||
2. **Auto-TTS** — `tts.py` (gateway client + pad_to_dials) + `/api/tts` proxy + the
|
||||
index.html 🔊 toggle + speak-on-done playback + serialize/cancel. Visible: she's voiced,
|
||||
affect-modulated. TDD (respx-mock the gateway; live smoke on the console).
|
||||
3. **KB-bridge** — `kb_bridge.py` + the one server.py seam. Visible: she recalls the DCC
|
||||
corpus in-voice. TDD. RETIRE-READY per INV-KB-1.
|
||||
|
||||
Out of scope: true audio streaming (DEC-2), custom voice registration (DEC-8, infra-ops
|
||||
follow-up), extending the bridge to non-interview agents.
|
||||
@@ -0,0 +1,78 @@
|
||||
# Donut voiced-interview build — ACTIVE (auto-TTS via Zonos + KB-recall bridge + Princess Donut)
|
||||
|
||||
`[2026-08-01]` Operator asked: "add auto-tts to the ratatoskr web gui" → grew into a voiced,
|
||||
corpus-grounded Tier-3 interview character. Contract:
|
||||
`docs/contracts/donut_voiced_interview.contract.md` (validated). Slice 1 DONE; slices 2-3 TO BUILD.
|
||||
Operator ruling: **build it today, but design the KB path to RETIRE** (it works around a Worldtree
|
||||
gap — Tier-3 agents are tool-less by design; KB search is integral, so the gap should close).
|
||||
|
||||
## Slice status
|
||||
|
||||
- **SLICE 1 (persona) DONE** — `docs/characters/donut.md` authored (corpus-grounded from a Mimir
|
||||
pull + DCC canon: interview-register performer, "Carl looks intimidating while I talk," vulnerability
|
||||
under a good question, and the "pinned corpus = her own memory" framing). **Defined:**
|
||||
`ratatoskr:donut` (role `thoughtful-character`) live on personal :8081, in the console picker.
|
||||
Chattable now (from training until slice 3). NOT yet committed (uncommitted at snapshot).
|
||||
- **SLICE 2 (auto-TTS) TO BUILD** — new `src/ratatoskr/tts.py` (Zonos gateway client + `pad_to_dials`) +
|
||||
`/api/tts` proxy route in `web/server.py` + `index.html` (🔊 toggle, speak-on-`done` playback,
|
||||
serialize/cancel). TDD (respx-mock the gateway), live-smoke.
|
||||
- **SLICE 3 (KB-bridge) TO BUILD** — new `src/ratatoskr/kb_bridge.py` (RETIRE-READY, INV-KB-1) +
|
||||
the one server.py seam. Per interview turn: out-of-band Mimir consult → extract evidence →
|
||||
POST Donut's turn with `memory_context=[{kind:"corpus_reference", text:"<extract>"}]`. She answers
|
||||
in-voice. TDD.
|
||||
|
||||
## Design — LOCKED (both external deps verified live 2026-08-01)
|
||||
|
||||
**TTS (infra-ops Zonos specs, verified):**
|
||||
- Endpoint: `POST http://10.100.79.3:8890/v1/audio/speech` (the zonos GATEWAY at irv-ml1:8890 — NOT
|
||||
the engine's :1920, which has a rep-penalty bug). Also GET /v1/voices, /v1/dials, /health. WG-internal,
|
||||
**no auth**. Reachable from nh3-dev (the console box) over WireGuard.
|
||||
- Request: JSON, only `input` required. `response_format:"wav"` (16-bit RIFF; **mp3/opus silently
|
||||
fall back to mislabeled PCM — never use**). Verified: voice=donut → HTTP 200, RIFF/WAVE PCM 16-bit
|
||||
mono 44.1kHz.
|
||||
- **NOT streaming** — gateway buffers to a complete clip (~1.8s/sentence). "Speak on done" gives the
|
||||
whole clip after the synth delay. True streaming = a future gateway enhancement (infra-ops can raise).
|
||||
- **Voice: `voice:"donut"` is ALREADY REGISTERED** (infra-ops cloned Vuong's Princess Donut bundle;
|
||||
GET /v1/voices returns Donut; case-folded so "Donut.wav"→voice:"donut"). Custom-voice registration
|
||||
mechanism: drop a `<Name>.wav` (44.1kHz mono 16-bit, ~10-20s clean single-speaker) in the gateway
|
||||
voices dir + restart. Audition A/B: http://10.100.10.50:8090/b/donut-voice/
|
||||
- **Affect-driven emotion (DEC-7, the standout):** map the turn's live PAD (from the `affect_update`
|
||||
SSE the console ALREADY consumes) → Zonos `emotion_valence`(pleasure)+`emotion_arousal`(arousal).
|
||||
Reframes the feature as voice OBSERVABILITY (hear the affect the persona pane shows), NOT chat-app
|
||||
creep — resolves the scope concern. Dials also: `preset`, `emotion_sliders{happy,sad,angry,surprised}`,
|
||||
`emotion_strength`, `speed`, `seed`.
|
||||
- **Coupling: direct :8890** (DEC-1) for the emotion dials; the swappable LiteLLM `ext-tts` alias
|
||||
(10.250.50.70:4000) loses the Zonos emotion params. `tts.py` is the single swap seam.
|
||||
- **Serialize** one synth per turn (DEC-5) — shared 3090 ~90% VRAM; cancel-on-new-turn.
|
||||
- **Proxy** (DEC-4): browser → `/api/tts` (nh3-dev) → gateway; never surface irv-ml1 to the client.
|
||||
|
||||
**KB-recall (worldtree-dev ruling, wyrd-proven):**
|
||||
- Tier-3 is DELIBERATELY tool-less in v1 (`build_tier3_agent_context` hard-codes `tool_schemas=[]`);
|
||||
no search_kb grant, no call-Mimir-as-tool (#361 rejected it, recursion). So: **consumer-side
|
||||
retrieval + memory_context pinning** — ratatoskr consults Mimir out-of-band, extracts the cited
|
||||
evidence, pins `memory_context=[{kind:"corpus_reference", text}]` on Donut's turn. She frames it as
|
||||
her own memory (the persona prompt already instructs this). Our SDK's stream_turn already forwards
|
||||
`memory_context` verbatim. Latency: one retrieval round-trip/turn.
|
||||
- **RETIRE-READY (INV-KB-1):** kb_bridge behind ONE seam `pin_kb_context(question, agent_id) ->
|
||||
list|[]`; retiring = delete the module + one call-site. Delete when Worldtree #361
|
||||
`reference_knowledge` extends to Tier-3 (operator flagged it an integral GAP; worldtree-dev surfacing
|
||||
the extension to Vuong — decision inbound to the operator).
|
||||
|
||||
## OWED / open loops (post-clear)
|
||||
|
||||
- **P&P verification re-run OWED to infra-ops** — #382 deployed (b166: self-describing `_index.md` +
|
||||
the Mimir prompt rule "hits ARE library content, never discard/substitute"). Re-run the failing
|
||||
P&P-dismiss shape on :8081, report to infra-ops. **DCC's backfill FAILED** (job predates state-tracking,
|
||||
no `_index.md` yet — flagged to worldtree-dev) — but the prompt rule alone should stop the discard,
|
||||
so the KB-bridge's DCC Mimir consults should ground fine. Verify this when building slice 3.
|
||||
- **worldtree-dev #361-Tier-3 extension** — an inbound surface decision for Vuong (would let Donut
|
||||
search in-voice + delete the bridge).
|
||||
- **infra-ops custom-voice** — mechanism proven; hand them a `<Name>.wav` + name for any future character.
|
||||
|
||||
## Discipline
|
||||
|
||||
Operator said "do both slices" (skip /heid-contract-review, straight to TDD). Run heid code-review +
|
||||
bug-hunt AFTER each code slice. Release-only versioning cadence (no per-commit tags; `feat:`/`fix:`
|
||||
conventional commits between releases). CLI to drive Mimir/Donut turns:
|
||||
`ratatoskr --send "..." --new --agent <id> --end-user-id ratatoskr-tui`. Define:
|
||||
`python -m ratatoskr.tier3 define --name <slug> --system-prompt "<prompt>" --role thoughtful-character`.
|
||||
+39
-29
@@ -1,6 +1,6 @@
|
||||
# Persistent memory — ratatoskr
|
||||
|
||||
_Last updated: 2026-07-19_
|
||||
_Last updated: 2026-08-02_
|
||||
|
||||
> **Always check for `/tmp/ratatoskr-dev-handoff.md`** — if it exists and its
|
||||
> `Written:` stamp is under an hour old, read it (it carries the in-flight
|
||||
@@ -44,37 +44,36 @@ upstream API key stays server-side (INV-003).
|
||||
|
||||
## Current state / in-flight
|
||||
|
||||
_As of 2026-07-19:_
|
||||
_As of 2026-08-01:_
|
||||
|
||||
**✅ COMPLETE — worldtree-sdk cutover (issue #20): ALL 7 SLICES DONE, shipped as v0.22.0 (2026-07-19).**
|
||||
Ratatoskr's CONSUMER client layer is fully cut over from hand-rolled httpx wrappers to **worldtree-sdk (Python)
|
||||
1.0.0** behind the thin `ratatoskr.wt` adapter (operator ADOPT ruling 2026-07-18; 6 DECs, vor-cross'd +
|
||||
heid-panel-reviewed; contract `docs/contracts/worldtree_sdk_cutover.contract.md` with slice-1..7 notes canonical).
|
||||
Six route-family slices (foundation / sessions-turn / persona-authored / agents-tier3 / characters-me / admin) +
|
||||
slice-7 teardown, each through the full House Code Discipline (adapter→cli/web→delete→live-smoke→both heid gates).
|
||||
Suite **494 green**. Per-slice arcs → `persistent-memory.d/2026-07-19-worldtree-sdk-cutover-slice-{1-2,3,4,5,6,7}-complete.md`.
|
||||
**Slice-7 teardown** (`ec68b1f`, v0.22.0, zero runtime-logic): dropped `httpx-sse` (SDK owns SSE parsing; venv
|
||||
pruned, nothing imported it); KEPT `sessions.py`+`sse_client.py` as pure caller-semantic type/exception homes
|
||||
(operator decision A1 — no rename/fold; A3 blocked by the `AgentNotAvailable` name-collision + `endpoint_for_plane`
|
||||
provider-homing); retired wire contracts #2/#15 (files deleted; **#1 SSE-vocab + first_message KEPT**, not retired);
|
||||
final coverage-map re-anchor.
|
||||
**KEY ADAPTER FOOT-GUNS (cumulative — still live for ANY future consumer/SDK work):** SDK reads = **open-world
|
||||
dicts**, presenters MUST degrade-not-crash guarded at THREE levels — **container-type** (`isinstance(_, list)`: a
|
||||
scalar `123` is non-iterable, `or []` catches null but NOT a truthy non-iterable), **element-type**
|
||||
(`isinstance(m, dict)`), **top-level-mapping** (`isinstance(_, Mapping)` before any `.get`); never hard-index. The
|
||||
SDK **normalizes ANY transport failure to `ConnectFailed(status=0)`** (not raw httpx) — every adapter caller
|
||||
`except ConnectFailed`. **Caller-semantic exceptions the adapter raises + a `-m` CLI catches must NOT live in the
|
||||
`-m` module** (double-module class-identity split → uncaught traceback; homed in `sessions.py`, never run as
|
||||
`__main__`). `TurnEvent.turn_id` ABSENT on text/thinking frames; `consumer_key` is BOUND-create-only. Scope was
|
||||
consumer layer ONLY; Bifrost provider untouched. Design → auto-memory `project_worldtree_sdk_cutover`.
|
||||
**🔨 ACTIVE BUILD — Donut voiced-interview (auto-TTS + KB-recall + Princess Donut). RESUME HERE post-clear.**
|
||||
Operator ask "add auto-tts to the web gui" grew into a voiced, corpus-grounded Tier-3 interview character.
|
||||
**Slice 1 DONE** (persona `docs/characters/donut.md` authored + `ratatoskr:donut` defined + in the picker);
|
||||
**slices 2 (Zonos auto-TTS) + 3 (retire-ready KB-bridge) TO BUILD** — operator: "build both today." Contract
|
||||
`docs/contracts/donut_voiced_interview.contract.md` (validated). Both external deps verified live 2026-08-01
|
||||
(Zonos `voice:"donut"` REGISTERED + returns wav; the KB-recall pattern is worldtree-dev-ruled — consumer-side
|
||||
retrieval + `memory_context` pinning, retire-ready). **FULL build state / design specs / owed items →
|
||||
`persistent-memory.d/2026-08-01-donut-voiced-interview-build.md`.** OWED: a P&P verification re-run to infra-ops
|
||||
(#382 fix deployed b166).
|
||||
|
||||
**▶️ POST-CUTOVER PENDING (non-blocking, operator's call):** (a) `git push` origin — the `ec68b1f` commit +
|
||||
**v0.22.0 tag are LOCAL only**; (b) althing announce of v0.22.0 to worldtree-dev / wtsdk-dev per the SemVer
|
||||
push-notify (post-push; Rata is the SDK reference consumer). Nothing else pending on the cutover.
|
||||
**✅ SHIPPED + PUSHED since v0.22.0 (origin at `14bbc2b`):** the worldtree-sdk cutover (#20, **v0.22.0**, 7 slices,
|
||||
494 green — the big one) + **bifrost 1.1.5** (`3ef3a5e`, **v0.22.1**) + **worldtree-sdk 1.0.0→1.1.1→1.1.2**
|
||||
(`d3a36f7`+`0058020` — path-encoding correctness fix + the SSE turn-stream traversal WE caught in their fix) +
|
||||
**canonical sync** (`14bbc2b` — added the client-spec-v2 pin, synced OpenAPI/spec forward, additive within the
|
||||
FROZEN v1 wire). The webui runs the current build (v0.22.1) live on :8765 (relaunched this session).
|
||||
|
||||
**✅ RESOLVED — tier3 agents `model`→`role` (scope B) folded into cutover slice-4** (`c62b4ee`, v0.21.13). The
|
||||
deferred deploy-gated scope-B work (response `model`→`role` per spec 1.2 / b128, `LocalAgentEntry`, index schema
|
||||
v2) landed with the agents-family SDK cutover — no longer pending. See the slice-4 detail file + Recent decisions.
|
||||
**⚙️ VERSIONING CADENCE CHANGED → release-only (operator-ratified 2026-07-30).** Retired per-commit bump+tag;
|
||||
version+tag at RELEASES only; between releases, `feat:`/`fix:` conventional-commit SHAs. Tier-bar + minor/major
|
||||
approval still apply, at release. Existing ~112 tags left as-is (leave-and-change-forward). (Global CLAUDE.md
|
||||
SemVer §amended to match; this OVERRIDES the per-commit-bump mechanics still described there.)
|
||||
|
||||
**KEY ADAPTER/CONSUMER FOOT-GUNS (cumulative, still live):** SDK reads = open-world dicts → presenters degrade-not-
|
||||
crash at THREE guard levels (container-type `isinstance(_,list)` / element-type `isinstance(m,dict)` / top-level
|
||||
`isinstance(_,Mapping)` before `.get`); SDK normalizes ALL transport failures to `ConnectFailed(status=0)` → every
|
||||
caller `except ConnectFailed`; caller-semantic exceptions a `-m` CLI catches must NOT live in the `-m` module
|
||||
(class-identity split; homed in `sessions.py`). **The `local_agents` index schema v1→v2 bump SILENTLY DROPS
|
||||
pre-cutover consumer agents from the picker** (buried Sindra — `load_local_agents` returns [] on version mismatch;
|
||||
fix = migrate v1→v2 from authoritative WT data). Cutover design → auto-memory `project_worldtree_sdk_cutover`.
|
||||
|
||||
**✅ RESOLVED — the "app product" workstreams leave Rata entirely (operator 2026-07-18).**
|
||||
**No arbo fork, no SillyTavern-on-Rata** — a NEW repo (template-dev standing up) takes over BOTH
|
||||
@@ -286,6 +285,14 @@ decision. Captures rationale that won't be obvious from code alone.
|
||||
|
||||
- `[2026-07-19]` **worldtree-sdk cutover SLICE-7 (teardown, the LAST) COMPLETE — the whole cutover shipped as v0.22.0 (`ec68b1f`, minor, operator-approved).** Zero runtime-logic teardown: httpx-sse dropped (SDK owns SSE), wire contracts #2/#15 retired (files deleted; #1+first_message kept), `sessions.py`/`sse_client.py` KEPT as pure type/exception homes (operator decision A1 — no rename/fold), coverage-map re-anchored. All 7 slices done, 494 green; push + althing-announce pending (operator's call). → `persistent-memory.d/2026-07-19-worldtree-sdk-cutover-slice-7-complete.md`
|
||||
|
||||
- `[2026-07-19→08-01]` **Donut voiced-interview BUILD — auto-TTS via Zonos + retire-ready KB-recall bridge + Princess Donut.** Slice-1 done (persona + define); slices 2-3 to build; both external deps verified live. THE active work. → `persistent-memory.d/2026-08-01-donut-voiced-interview-build.md`
|
||||
- `[2026-08-01]` **worldtree-sdk 1.0.0→1.1.1→1.1.2 repin — and a reference-consumer catch.** 1.1.1's path-encoding fix MISSED the inline `turn_stream.py:185` on the SSE path (caller-shaped session_id, our highest-traffic route); wtsdk-dev fixed it in 1.1.2 same-day. (`d3a36f7`+`0058020`, pushed.)
|
||||
- `[2026-08-01]` **Mimir #382 grounding bug — our finding shaped the fix.** Rata caught that the #380 vector re-index left Mimir DISCARDING correct P&P hits (no named source in the fiction wing → agent distrusts its own hits + answers from training; a silent-substitution "reasoning move, not retrieval"). Fix = our proposed residual (self-describing `_index.md`) + a Mimir prompt rule; deployed b166. **P&P verification re-run OWED to infra-ops**; DCC dir still opaque (backfill failed, flagged to worldtree-dev).
|
||||
- `[2026-08-01]` **Canonical sync — added the client-spec-v2 pin (option A) + synced OpenAPI/spec forward** (`14bbc2b`, pushed). Whole-manifest sync also bumped the OpenAPI hard-gate additively (frozen v1 wire → no breakage). Coverage-map re-audit vs the new surface = queued follow-up.
|
||||
- `[2026-07-30]` **Versioning cadence → RELEASE-ONLY (operator-ratified, brokkr-smithy relayed).** Retired per-commit bump+tag; tag only releases; between releases `feat:`/`fix:` SHAs. Existing ~112 tags left as-is. Global CLAUDE.md SemVer being amended to match.
|
||||
- `[2026-08-01]` **bifrost 1.1.4→1.1.5 (v0.22.1, `3ef3a5e`, pushed)** — optional-store-verb 500→`unsupported_capability` hardening; provider restarted onto it.
|
||||
- `[2026-08-01]` **Sindra saga — restored from local-index burial, wiped, smoke-tested.** The v0.22.0 web restart dropped her live session AND the schema-v2 discard buried her from the picker; migrated her v1→v2 from authoritative WT (real role `thoughtful-character`, not the stale `mistral-small-4`), then `scripts/reset-sindra-stores.sh` wiped memory+persona for a from-scratch smoke.
|
||||
|
||||
_67 older entries (2026-05-* debug-TUI/web era + the 2026-06-14 → 06-18 Bifrost-provider build / #17+#18 / #295-296 era) archived to archival-memory.md._
|
||||
|
||||
_For per-issue TDD implementation notes, Volva findings, and contract amendments, see the git log — every per-issue commit carries a structured message capturing the trail._
|
||||
@@ -330,4 +337,7 @@ defense against re-attempting the same cul-de-sac.
|
||||
|
||||
- `[2026-07-16]` **`sortable_chunk_fields` advertised WITHOUT the required `type` field = whole-handshake deploy-breaker; only DRIVING the real bind caught it** → `persistent-memory.d/2026-07-16-sortablechunkfields-advertised-without-the-re.md`
|
||||
|
||||
- `[2026-08-01]` **`local_agents` index schema v1→v2 bump SILENTLY buries pre-cutover consumer agents from the picker** — `load_local_agents` returns `[]` on version mismatch (no migration path); the v0.22.0 restart made Sindra vanish even though she was alive on WT. Fix applied ad-hoc: migrate the v1 row → v2 from authoritative WT data (the v1 `model` field held a stale model name, NOT the current role). A one-time v1→v2 migration guard is the durable fix (unbuilt; operator-flagged).
|
||||
- `[2026-08-01]` **Zonos: mp3/opus `response_format` silently return mislabeled PCM** (no encoder wired) — use `response_format:"wav"` only. And use the GATEWAY :8890, NOT the engine :1920 (rep-penalty bug pads ~70s silence + ignores voice).
|
||||
|
||||
_34 older entries (2026-05-* debug-TUI/web era + the 2026-06-14 → 06-18 foot-gun cluster) archived to archival-memory.md._
|
||||
|
||||
Reference in New Issue
Block a user