add orchestrator / tatlock distinction to docs

2025-12-06 21:31:59 +01:00
parent 5f4e93bf09
commit e85823ff18
3 changed files with 631 additions and 5 deletions
@@ -112,6 +112,33 @@ The system should feel less like "using a tool" and more like "asking a capable

 ## The Household Architecture

+### System Layers
+
+The Tatlock system consists of two distinct architectural layers:
+
+#### The Orchestrator (Infrastructure Layer)
+
+The **Orchestrator** is the FastAPI application that provides the technical infrastructure:
+- HTTP/SSE endpoints (`/v1/responses`, `/v1/chat/completions`)
+- Streaming coordination and conversation management
+- Token counting and context window management
+- Integration with Open WebUI and other clients
+- Request/response lifecycle management
+
+This is the "plumbing" layer that exists now and handles all the technical concerns of running an OpenAI-compatible API.
+
+#### Tatlock - The Butler (Agent Layer)
+
+**Tatlock** is the PydanticAI agent that provides the intelligence and personality:
+- The witty British butler persona
+- Coordination with the Steward and household staff
+- Multi-agent orchestration and synthesis
+- Context-aware, personalized responses
+
+The Orchestrator hosts Tatlock—users interact with "Tatlock" (the advertised model name), but technically they're talking to the Orchestrator infrastructure which routes requests through the Tatlock agent.
+
+**Current State**: The Orchestrator exists and uses mock agents. Phase 1-3 of the implementation roadmap will integrate the real Tatlock agent using PydanticAI.
+
 ### The British Household Metaphor

 Tatlock adopts the organizational structure of a traditional British estate household, where specialized staff members handle distinct domains of responsibility under the coordination of a capable butler. This metaphor is not merely aesthetic—it reflects a deliberate architectural pattern that enables focused expertise, clear separation of concerns, and efficient coordination.
@@ -170,8 +197,8 @@ The household operates through a carefully orchestrated two-tier process:

 #### Tier 1: The Steward's Preparation

-1. **User request arrives** in the system
-2. **Steward receives the raw request** for analysis
+1. **User request arrives** at the Orchestrator (via HTTP API)
+2. **Orchestrator routes** the raw request to the Steward for analysis
 3. **Steward determines** which tools and household staff are relevant
 4. **Steward prepares recommendations**, written as a note to Tatlock
 5. **Recommendations are prepended** to the user's request