Documentationsection 13 of 13
Architecture
- 1One engine, several front doors
Kotoba is a single Python engine with more than one way in. A browser, a terminal and a Discord bot are three separate processes, and each one builds the same…
- 2A turn, end to end
This traces one spoken turn from the browser through the ElevenLabs agent path, because that is the path with the most moving parts. Where another surface…
- 3Register, channel, transport — three axes, and the two that get confused
Three separate facts travel with a turn. They are frequently collapsed into one another, and each collapse has a name in the bug history.
- 4Events and cards — being listened to is not being drawn
Everything the engine wants to put on a screen goes through one primitive: core/events.py. It is a registry of per-session asyncio.Queues, and it is…
- 5Inline versus deferred execution
Most of the time an approval-gated tool blocks: it shows the card, waits, and runs or does not run inside the same turn. On exactly one transport it cannot…
- 6The data layer
One SQLite file, one connection per process, and a schema version tracked by PRAGMA user_version. Everything durable that is not a document lives here…
- 7The packaged frontend
Kotoba's web UI is a Next.js app, and pip install kotoba-companion needs no Node at all. This page explains how that works and what it means when you are…
- 8Rate limiting and back-pressure
An agentic turn is token-heavy: the system prompt, the history, the tool schemas and every tool result go back on every iteration. A long work run can exhaust…
- 9Untrusted text — content, not a request
A page she fetched, a file she opened, a tool description an MCP server advertised: all of it reaches the same model that reads your instructions. The…
- 10What is deliberately not in the architecture
Architecture pages are where stale diagrams go to be believed. This one exists so nobody documents a ghost, or waits for a subsystem that was refused rather…