Architecture

This document describes the internal architecture of Ripperdoc.

Overview

┌─────────────────────────────────────────────────────────────┐
│                         CLI Layer                            │
│  (ripperdoc/cli/)                                           │
│  - Terminal UI, Commands, User Interaction                  │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                        Core Layer                            │
│  (ripperdoc/core/)                                          │
│  - Query Loop, Tool Registry, Permissions, Hooks            │
└─────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
┌───────────────────┐ ┌─────────────┐ ┌─────────────────────┐
│     Providers     │ │    Tools    │ │      Utilities      │
│  (core/providers/)│ │  (tools/)   │ │      (utils/)       │
│  - Anthropic      │ │  - Bash     │ │  - File Watch       │
│  - OpenAI         │ │  - Read     │ │  - Session Mgmt     │
│  - Gemini         │ │  - Edit     │ │  - Logging          │
│  - DeepSeek       │ │  - Glob     │ │  - Permissions      │
└───────────────────┘ │  - Grep     │ └─────────────────────┘
                      │  - Task     │
                      │  - ...      │
                      └─────────────┘

Core Components

Query Loop (`core/query.py`)

The main query loop handles:

Building the system prompt with tool definitions
Sending messages to the LLM provider
Parsing tool calls from responses
Executing tools and collecting results
Handling errors and context overflow

async def query(messages, system_prompt, context, query_context):
    for iteration in range(MAX_ITERATIONS):
        # Build full prompt
        full_prompt = build_full_system_prompt(...)

        # Call LLM
        response = await query_llm(messages, full_prompt, tools)

        # Extract and execute tool calls
        tool_calls = extract_tool_use_blocks(response)
        for tool_call in tool_calls:
            result = await execute_tool(tool_call)

        # Continue or return based on response

Tool System (`core/tool.py`)

Tools follow a common interface:

class Tool(Generic[TInput, TOutput]):
    @property
    def name(self) -> str: ...

    @property
    def input_schema(self) -> type[TInput]: ...

    async def validate_input(self, input_data, context) -> ValidationResult: ...

    async def call(self, input_data, context) -> AsyncGenerator[ToolOutput]: ...

    def needs_permissions(self, input_data) -> bool: ...

Provider Abstraction (`core/providers/`)

Providers normalize different LLM APIs:

class ProviderClient:
    async def call(
        self,
        model_profile: ModelProfile,
        system_prompt: str,
        normalized_messages: List[Dict],
        tools: List[Tool],
        **kwargs
    ) -> ProviderResponse: ...

Hook System (`core/hooks/`)

Hooks intercept lifecycle events:

Event Flow:
1. UserPromptSubmit → User sends message
2. PreToolUse → Before tool execution
3. PermissionRequest → When permission needed
4. PostToolUse → After tool completes
5. Stop → Agent finishes responding

Data Flow

Message Flow

User Input
    │
    ▼
┌────────────────┐
│ CLI Input      │
└───────┬────────┘
        │
        ▼
┌────────────────┐     ┌────────────────┐
│ Hook: Submit   │────▶│ May modify     │
└───────┬────────┘     │ or block       │
        │              └────────────────┘
        ▼
┌────────────────┐
│ Query Loop     │
└───────┬────────┘
        │
        ▼
┌────────────────┐
│ LLM Provider   │
└───────┬────────┘
        │
        ▼
┌────────────────┐
│ Tool Execution │◀───── Hooks: Pre/Post
└───────┬────────┘
        │
        ▼
┌────────────────┐
│ Response       │
└───────┬────────┘
        │
        ▼
┌────────────────┐
│ CLI Output     │
└────────────────┘

Tool Execution Flow

Tool Call (from LLM)
    │
    ▼
┌────────────────┐
│ Resolve Tool   │
└───────┬────────┘
        │
        ▼
┌────────────────┐
│ Parse Input    │ ← Pydantic validation
└───────┬────────┘
        │
        ▼
┌────────────────┐
│ PreToolUse     │ ← Hook can block/modify
│ Hook           │
└───────┬────────┘
        │
        ▼
┌────────────────┐
│ Permission     │ ← May prompt user
│ Check          │
└───────┬────────┘
        │
        ▼
┌────────────────┐
│ Execute Tool   │ ← Yields progress/result
└───────┬────────┘
        │
        ▼
┌────────────────┐
│ PostToolUse    │ ← Hook can add context
│ Hook           │
└────────────────┘