# hyperf/odin architecture

> Architecture diagram of the GitHub repository hyperf/odin, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hyperf/odin
- Repository: https://github.com/hyperf/odin

## Overview

##### Project type and purpose
- Odin is a PHP‑based framework/library for building LLM‑powered applications.
- It unifies multiple model providers (OpenAI, Azure, AWS Bedrock, etc.), supports tool/function calling, memory management, vector retrieval (via Qdrant), and an agent framework.

##### File structure
- Top‑level directories:
- src: core code organized into subpackages (Api, Agent, Memory, Model, Tool, Prompt, VectorStore, etc.)
- doc/user-guide: detailed user documentation
- examples: usage examples for AWS, OpenAI, streams, tools, exceptions
- tests: unit and integration suites
- Key configuration: composer.json, .php-cs-fixer.php, phpunit.xml
- Deployment: GitHub Actions workflows under .github/workflows

##### README insights
- Describes supported features (multi‑model, unified interface, function calls, memory, vector search, agents, streaming)
- Lists system requirements and quickstart (composer install, config publish, .env, etc.)

##### Main components and interactions
a. API Layer
- ClientFactory → ConfigProvider → AbstractClient/Provider implementations (OpenAI, AzureOpenAI, AWSBedrock)
- Request/RequestOptions → Transport (HTTP/SSEClient) → Response/ResponseHandler
b. Model Layer
- ModelFactory → AbstractModel/Provider‑specific Model classes
- ModelOptions drives parameterization
c. Prompt Layer
- PromptInterface + concrete templates (.prompt files) generate the raw text or JSON function calls
d. Memory Layer
- MemoryManager → multiple Policies (time window, token limit, summarization, relevancy) → Driver (InMemoryDriver, custom drivers)
- MessageHistory organizes system/user/assistant/tool messages
e. Tool/Agent Layer
- ToolDefinition/Schema → AbstractTool implementations → Agent coordinating ToolUseAgent and MultiToolUseParallelTool
f. VectorStore Layer
- QdrantFactory → Qdrant client/config → semantic search for knowledge retrieval
g. Exception/Logging
- Centralized exception hierarchy for API, configuration, model, network errors
- Logger for diagnostic and stream‑level error detection

##### Relationships and data flow
- Application code invokes Odin’s public façade (Factory, ConfigProvider)
- Factories spin up ApiClient + Model + Prompt
- Prompt + conversation memory → Request → Transport → External LLM service
- Response → converters → Response objects → consumed by application or agent
- Agents may call Tools (with definitions) → ToolExecutor → external APIs or business logic → back into conversation
- For retrieval tasks: Agent or developer code calls VectorStore → Qdrant → returns documents → fed back into prompt

##### Architectural patterns and design principles
- Dependency Injection (ConfigProvider, Factories)
- Strategy/Provider pattern for multi‑model support
- Builder pattern for request/response conversion
- Policy pattern for memory management
- Modular layering (API, Model, Prompt, Memory, Agent/Tool, VectorStore)

##### Detail level

- And group all src/* subpackages into logical layers
- External dependencies clearly (LLM providers, Qdrant)
- Agent/Tool workflow as a distinct flow

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Application and Services
    Application["Application Code"]:::external
    LLM["LLM Service Endpoints"]:::external
    QdrantDB["Qdrant Vector DB"]:::external

    %% Integration / Adapters
    subgraph "Integration / Adapters"
        direction TB
        subgraph "API Layer"
            direction TB
            ConfigProvider["ConfigProvider"]:::api
            ClientFactory["ClientFactory"]:::api
            ApiInterfaces["Api Contracts"]:::api
            SSEClient["SSEClient"]:::api
            StreamExceptionDetector["StreamExceptionDetector"]:::api
        end

        subgraph "VectorStore Layer"
            direction TB
            QdrantFactory["QdrantFactory"]:::api
            QdrantClient["Qdrant Client"]:::api
        end
    end

    %% Core Engine
    subgraph "Core Engine"
        direction TB
        subgraph "Model Layer"
            direction TB
            ModelFactory["ModelFactory"]:::core
            ModelInterfaces["Model Contracts"]:::core
        end

        subgraph "Prompt Layer"
            direction TB
            PromptInterface["PromptInterface"]:::core
            Templates[".prompt Templates"]:::core
        end

        subgraph "Memory Layer"
            direction TB
            MemoryManager["MemoryManager"]:::core
            InMemoryDriver["InMemoryDriver"]:::core
            Policies["Memory Policies"]:::core
            MessageHistory["MessageHistory"]:::core
        end
    end

    %% High-level Features
    subgraph "High‑level Features"
        direction TB
        subgraph "Tool / Agent Layer"
            direction TB
            AbstractTool["AbstractTool"]:::feature
            ToolDefinition["ToolDefinition/Schema"]:::feature
            ToolExecutor["ToolExecutor"]:::feature
            ToolUseAgent["ToolUseAgent"]:::feature
            MultiToolParallel["MultiToolUseParallelTool"]:::feature
        end
    end

    %% Plumbing
    subgraph "Plumbing"
        direction TB
        ExceptionHierarchy["Exception Hierarchy"]:::plumbing
        Logger["Logger"]:::plumbing
    end

    %% Relationships
    Application -->|"invokes"| ConfigProvider
    ConfigProvider --> ClientFactory
    ClientFactory --> ApiInterfaces
    ClientFactory --> SSEClient
    SSEClient -->|"HTTP JSON / SSE stream"| LLM
    ApiInterfaces -->|"uses"| StreamExceptionDetector

    Application -->|"requests model"| ModelFactory
    ModelFactory --> ModelInterfaces
    ModelFactory --> ConfigProvider

    Application -->|"builds prompt"| PromptInterface
    PromptInterface --> Templates

    Application -->|"manages memory"| MemoryManager
    MemoryManager --> InMemoryDriver
    MemoryManager --> Policies
    MemoryManager --> MessageHistory

    Application -->|"calls agent"| ToolUseAgent
    ToolUseAgent --> AbstractTool
    AbstractTool --> ToolDefinition
    ToolExecutor --> AbstractTool
    MultiToolParallel --> AbstractTool

    Application -->|"semantic search"| QdrantFactory
    QdrantFactory --> QdrantClient
    QdrantClient -->|"HTTP JSON"| QdrantDB

    %% Exception flow
    LLM -->|errors| ExceptionHierarchy
    ExceptionHierarchy --> Logger
    Application -->|logs| Logger

    %% Click Events
    click ConfigProvider "https://github.com/hyperf/odin/blob/master/src/ConfigProvider.php"
    click ClientFactory "https://github.com/hyperf/odin/blob/master/src/Factory/ClientFactory.php"
    click ApiInterfaces "https://github.com/hyperf/odin/tree/master/src/Contract/Api"
    click SSEClient "https://github.com/hyperf/odin/blob/master/src/Api/Transport/SSEClient.php"
    click StreamExceptionDetector "https://github.com/hyperf/odin/blob/master/src/Api/Transport/StreamExceptionDetector.php"

    click ModelFactory "https://github.com/hyperf/odin/blob/master/src/Factory/ModelFactory.php"
    click ModelInterfaces "https://github.com/hyperf/odin/tree/master/src/Contract/Model"

    click PromptInterface "https://github.com/hyperf/odin/tree/master/src/Prompt"
    click Templates "https://github.com/hyperf/odin/tree/master/src/Prompt"

    click MemoryManager "https://github.com/hyperf/odin/blob/master/src/Memory/MemoryManager.php"
    click InMemoryDriver "https://github.com/hyperf/odin/blob/master/src/Memory/Driver/InMemoryDriver.php"
    click Policies "https://github.com/hyperf/odin/tree/master/src/Memory/Policy"
    click MessageHistory "https://github.com/hyperf/odin/blob/master/src/Memory/MessageHistory.php"
    click MemoryManager "https://github.com/hyperf/odin/tree/master/src/Contract/Memory"

    click AbstractTool "https://github.com/hyperf/odin/tree/master/src/Tool"
    click ToolDefinition "https://github.com/hyperf/odin/tree/master/src/Tool"
    click ToolExecutor "https://github.com/hyperf/odin/blob/master/src/Agent/ToolExecutor.php"
    click ToolUseAgent "https://github.com/hyperf/odin/blob/master/src/Agent/ToolUseAgent.php"
    click MultiToolParallel "https://github.com/hyperf/odin/blob/master/src/Agent/MultiToolUseParallelTool.php"

    click QdrantFactory "https://github.com/hyperf/odin/blob/master/src/VectorStore/Qdrant/QdrantFactory.php"
    click QdrantClient "https://github.com/hyperf/odin/blob/master/src/VectorStore/Qdrant/Qdrant.php"

    click ExceptionHierarchy "https://github.com/hyperf/odin/tree/master/src/Exception"
    click Logger "https://github.com/hyperf/odin/blob/master/src/Logger.php"

    %% Styles
    classDef api fill:#a8f0c6,stroke:#2b7a0b,color:#000;
    classDef core fill:#9ec5fe,stroke:#1a4b8d,color:#000;
    classDef feature fill:#fddc99,stroke:#a65e00,color:#000;
    classDef plumbing fill:#d3d3d3,stroke:#7a7a7a,color:#000;
    classDef external fill:#ffffff,stroke:#000000,color:#000,stroke-dasharray: 5 5;
    class Application,LLM,QdrantDB external
```
