╔════════════════════════════════════════════════════════════════════════════════╗
║                   TIYCORE MODULE RELATIONSHIP DIAGRAM                          ║
╚════════════════════════════════════════════════════════════════════════════════╝

┌────────────────────────────────────────────────────────────────────────────────┐
│                             LIBRARY INTERFACE                                  │
│                            (src/lib.rs - 82 lines)                             │
│                                                                                │
│  Publicly exports:                                                             │
│  • types::* (Context, Message, ContentBlock, Tool, etc.)                      │
│  • agent::{Agent, AgentStateSnapshot}                                         │
│  • catalog::* (model catalog functions)                                       │
│  • stream::EventStream                                                        │
│  • provider::* (facades + registry)                                           │
│  • protocol::* (LLMProtocol trait)                                            │
└────────────────────────────────────────────────────────────────────────────────┘
                              ↓         ↓         ↓
                              │         │         │
          ╔════════════════════╩═════════╩═════════╩═════════════════════╗
          │                                                              │
          ▼                                                              ▼
┌──────────────────────────────────┐                    ┌──────────────────────────┐
│   TYPES MODULE (Core Types)      │                    │   AGENT MODULE           │
│  src/types/ (7 files, 1,800 LOC) │                    │ src/agent/ (5 files)    │
│                                  │                    │                          │
│ ┌──────────────────────────────┐ │                    │ ┌──────────────────────┐ │
│ │ context.rs (403 lines)       │ │                    │ │ agent.rs (~2700 LOC) │ │
│ ├──────────────────────────────┤ │                    │ ├──────────────────────┤ │
│ │ • Context                    │ │                    │ │ • Agent              │ │
│ │   ├─ system_prompt           │ │                    │ │ • AgentLoop          │ │
│ │   ├─ messages: Vec<Message>  │ │                    │ │ • AgentError         │ │
│ │   └─ tools: Vec<Tool>        │ │                    │ │ • SubscriberId       │ │
│ │                              │ │                    │ │                      │ │
│ │ • Tool                       │ │                    │ │ Functions:           │ │
│ │   ├─ name, description       │ │                    │ │ • agent_loop()       │ │
│ │   └─ parameters (JSON Schema)│ │                    │ │ • run_agent_loop()   │ │
│ │                              │ │                    │ └──────────────────────┘ │
│ │ • StreamOptions              │ │                    │                          │
│ │   ├─ temperature, max_tokens │ │                    │ ┌──────────────────────┐ │
│ │   ├─ api_key, base_url       │ │                    │ │ state.rs             │ │
│ │   ├─ headers, session_id     │ │                    │ ├──────────────────────┤ │
│ │   ├─ cache_retention         │ │                    │ │ • AgentState         │ │
│ │   ├─ security, transport     │ │                    │ │ • StateSnapshot      │ │
│ │   ├─ tool_choice, metadata   │ │                    │ └──────────────────────┘ │
│ │   └─ on_payload (hook)       │ │                    │                          │
│ │                              │ │                    │ ┌──────────────────────┐ │
│ │ • SimpleStreamOptions        │ │                    │ │ types.rs             │ │
│ │   └─ extends StreamOptions   │ │                    │ └──────────────────────┘ │
│ │     with reasoning/thinking  │ │                    │                          │
│ └──────────────────────────────┘ │                    └──────────────────────────┘
│                                  │                                │
│ ┌──────────────────────────────┐ │                                │
│ │ message.rs (400 lines)       │ │                                │
│ ├──────────────────────────────┤ │                    ┌───────────┴──────────┐
│ │ • Role (User, Assistant,     │ │                    │                      │
│ │   ToolResult)                │ │                    ▼                      ▼
│ │ • StopReason (Stop, Length,  │ │          ┌──────────────────┐  ┌──────────────────┐
│ │   ToolUse, Error, Aborted)   │ │          │ PROTOCOL MODULE  │  │ PROVIDER MODULE  │
│ │ • UserMessage                │ │          │ src/protocol/    │  │ src/provider/    │
│ │ • AssistantMessage           │ │          │ (7 files)        │  │ (18 files)       │
│ │ • ToolResultMessage          │ │          │                  │  │                  │
│ │ • Message (enum)             │ │          │ ┌────────────┐   │  │ ┌────────────┐   │
│ │                              │ │          │ │traits.rs   │   │  │ │registry.rs │   │
│ │                              │ │          │ ├────────────┤   │  │ ├────────────┤   │
│ │                              │ │          │ │LLMProtocol │   │  │ │ProtocolReg│   │
│ │                              │ │          │ │trait       │   │  │ │get_provider│   │
│ │                              │ │          │ │BoxedProto  │   │  │ │register_pro│   │
│ │                              │ │          │ │ArcProtocol │   │  │ └────────────┘   │
│ │                              │ │          │ └────────────┘   │  │                  │
│ │                              │ │          │                  │  │ ┌────────────┐   │
│ │ ContentBlock (enum):         │ │          │ ┌────────────┐   │  │ │openai.rs   │   │
│ │ • Text(TextContent)          │ │          │ │openai_comp │   │  │ ├────────────┤   │
│ │ • Thinking(ThinkingContent)  │ │          │ │_pletions.rs    │  │ │OpenAIProv  │   │
│ │ • ToolCall(ToolCall)         │ │          │ └────────────┘   │  │ │delegates to    │
│ │ • Image(ImageContent)        │ │          │                  │  │ │openai_compl    │
│ │                              │ │          │ ┌────────────┐   │  │ └────────────┘   │
│ │ UserContent (enum):          │ │          │ │openai_resp │   │  │                  │
│ │ • Text(String)               │ │          │ │_onses.rs   │   │  │ ┌────────────┐   │
│ │ • Blocks(Vec<ContentBlock>)  │ │          │ └────────────┘   │  │ │anthropic.rs│   │
│ │                              │ │          │                  │  │ ├────────────┤   │
│ └──────────────────────────────┘ │          │ ┌────────────┐   │  │ │Anthropic   │   │
│                                  │          │ │anthropic. │   │  │ │Prov        │   │
│ ┌──────────────────────────────┐ │          │ │rs         │   │  │ └────────────┘   │
│ │ content.rs (235 lines)       │ │          │ └────────────┘   │  │                  │
│ ├──────────────────────────────┤ │          │                  │  │ ┌────────────┐   │
│ │ • TextContent                │ │          │ ┌────────────┐   │  │ │google.rs   │   │
│ │ • ThinkingContent            │ │          │ │google.rs   │   │  │ ├────────────┤   │
│ │ • ImageContent               │ │          │ └────────────┘   │  │ │GoogleProv  │   │
│ │ • ToolCall                   │ │          │                  │  │ └────────────┘   │
│ │ • ContentBlock (enum)        │ │          │ ┌────────────┐   │  │                  │
│ │ • UserContent (enum)         │ │          │ │common.rs   │   │  │ ┌────────────┐   │
│ │                              │ │          │ └────────────┘   │  │ │ollama.rs   │   │
│ └──────────────────────────────┘ │          └──────────────────┘  │ ├────────────┤   │
│                                  │                                │ │OllamaProvider  │
│ ┌──────────────────────────────┐ │                                │ └────────────┘   │
│ │ model.rs (macro-generated     │ │                                │ + 13 more        │
│ │ Provider/Api enums +         │ │                                │   specialized    │
│ │ OpenAICompletionsCompat),    │ │                                │   providers      │
│ │ usage.rs, events.rs,         │ │                                │                  │
│ │ limits.rs (~600 LOC)         │ │
└──────────────────────────────────┘                                └──────────────────┘
          │                                                                  │
          └──────────────────────────────┬───────────────────────────────────┘
                                         │
                                         ▼
                        ┌─────────────────────────────────┐
                        │   STREAM MODULE                 │
                        │   src/stream/ (3 files, ~500)   │
                        │                                 │
                        │ ┌─────────────────────────────┐ │
                        │ │ event_stream.rs             │ │
                        │ ├─────────────────────────────┤ │
                        │ │ EventStream<T>              │ │
                        │ │ • Notify-based async result │ │
                        │ │ • futures::Stream impl      │ │
                        │ └─────────────────────────────┘ │
                        │                                 │
                        │ ┌─────────────────────────────┐ │
                        │ │ json_parser.rs              │ │
                        │ ├─────────────────────────────┤ │
                        │ │ Incremental JSON parsing    │ │
                        │ │ for streaming responses     │ │
                        │ └─────────────────────────────┘ │
                        └─────────────────────────────────┘
                                         │
                                         ▼
                        ┌─────────────────────────────────┐
                        │   TRANSFORM MODULE              │
                        │   src/transform/ (3 files)      │
                        │                                 │
                        │ ┌─────────────────────────────┐ │
                        │ │ messages.rs                 │ │
                        │ │ → Convert between formats   │ │
                        │ └─────────────────────────────┘ │
                        │                                 │
                        │ ┌─────────────────────────────┐ │
                        │ │ tool_calls.rs               │ │
                        │ │ → Parse & extract tool args │ │
                        │ └─────────────────────────────┘ │
                        └─────────────────────────────────┘
                                         │
                ┌────────────────────────┼────────────────────────┐
                │                        │                        │
                ▼                        ▼                        ▼
    ┌──────────────────────┐  ┌──────────────────────┐  ┌──────────────────────┐
    │ CATALOG MODULE       │  │ THINKING MODULE      │  │ VALIDATION MODULE    │
    │ src/catalog/         │  │ src/thinking/        │  │ src/validation/      │
    │ (~1,000 LOC)         │  │ (~300 LOC)           │  │ (~200 LOC)           │
    │                      │  │                      │  │                      │
    │ • CatalogSnapshot    │  │ • ThinkingLevel      │  │ • JSON Schema        │
    │ • list_models()      │  │ • ThinkingDisplay    │  │   validation         │
    │ • build_snapshot()   │  │ • Config             │  │ • Tool parameter     │
    │ • refresh_snapshot() │  │   for extended       │  │   verification       │
    │ • apply_patches()    │  │   thinking           │  │                      │
    │ • CatalogMetadataS.  │  │                      │  │                      │
    │                      │  │                      │  │                      │
    └──────────────────────┘  └──────────────────────┘  └──────────────────────┘
                │                                              │
                └──────────────────┬───────────────────────────┘
                                   │
                                   ▼
                        ┌──────────────────────┐
                        │ MODELS MODULE        │
                        │ src/models/          │
                        │ (~500 LOC)           │
                        │                      │
                        │ • predefined.rs      │
                        │   Pre-configured     │
                        │   model definitions  │
                        │                      │
                        └──────────────────────┘

════════════════════════════════════════════════════════════════════════════════

DEPENDENCY ARROWS (reading left to right):
→ Types are foundational (used by all modules)
→ Agent uses Types + Protocol/Provider system
→ Protocol & Provider implement wire format translation
→ Stream, Transform handle data flow between layers
→ Catalog, Thinking, Validation provide support services

════════════════════════════════════════════════════════════════════════════════

KEY PATTERNS:

1. PROTOCOL-PROVIDER SEPARATION
   protocol/ defines wire formats (openai_completions, anthropic, google)
   provider/ wraps them in convenient facades + manages registry

2. TYPE-DRIVEN DESIGN
   types/ provides core data model that everything else uses
   Strong type system prevents many bugs at compile time

3. STREAMING-FIRST ARCHITECTURE
   stream/ handles async event-based responses
   Supports both SSE and WebSocket transports

4. TRANSFORMATION PIPELINE
   Stream Data → JSON Parser → Transform → Unified Types

5. EXTENSIBILITY
   Add new providers by implementing LLMProtocol trait
   Auto-registration via registry system

════════════════════════════════════════════════════════════════════════════════
