# sonnh96/saio architecture

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

- Interactive diagram: https://gitdiagram.com/sonnh96/saio
- Repository: https://github.com/sonnh96/saio

## Overview

##### Project Type and Purpose
- SAIO is a Python library and framework for building AI agents, workflows, and intelligent systems.
- It provides a modular, plug-and-play architecture: “Core Engine” (agents, workflows, runners), “Layers” (model abstraction, memory, knowledge, tools, storage), plus frontends (CLI, API server, GUI/playground).
- Use case: embed into other applications or run via CLI/API/playground to build, orchestrate, and evaluate AI-driven workflows.

##### File Structure Analysis
- Top-level directories:
- agent, workflow, run: Core engine components
- models, embedder: Model‐provider abstractions & embedding adapters
- memory, knowledge, tools: Business logic layers
- storage, vectordb: Persistence adapters (SQL, NoSQL, vector DBs)
- api, app, cli, playground: Entry points / UIs
- utils, document, eval, reasoning, reranker: Supporting services
- Pattern: Layered, hexagonal/adaptor style. Each layer defines interfaces (e.g., `memory/db/base.py`) and multiple backends (e.g., mongodb, postgres).
- Config & orchestration: `pyproject.toml`, `setup.py`, `run/`, `cli/entrypoint.py`.

##### README Insights
- Explicit mentions of the modular architecture:
- Core Engine
- Model Layer
- Storage Layer
- Tool Layer
- Memory Layer
- Lists core modules matching directories, confirming separation of concerns.

a. Main Components
- Frontends:
- CLI (cli/)
- API Server (api/, app/fastapi/)
- GUI/Playground (app/agui/, playground/)
- Core Engine:
- Agent Manager (agent/)
- Workflow Engine (workflow/, run/)
- Layers & Services:
- Model Abstraction (models/)
- Embedding Service (embedder/)
- Knowledge Systems (knowledge/, document/)
- Memory Management (memory/)
- Tool Integrations (tools/)
- Vector Stores (vectordb/)
- General Storage (storage/)
- External Dependencies:
- Third-party AI providers (OpenAI, Anthropic, etc.)
- Databases (Postgres, MongoDB, Redis, etc.)
- External APIs via tools (e.g., Gmail, Twitter, AWS)
b. Relationships & Data Flow
- Frontend → Core Engine: user requests or workflow definitions are passed to Agent/Workflow Engine.
- Core Engine ↔ Layers:
- Agent invokes memory for context/history.
- Agent/Workflow calls model abstraction to generate text.
- Workflows may call tools, knowledge retrieval, embeddings.
- Storage layers persist sessions, memory, vector embeddings.
- Core Engine ↔ External Services: HTTP/SDK calls to AI providers and tool APIs.
c. Architectural Patterns & Principles
- Hexagonal (ports & adapters) for each layer: interface definitions + multiple backend adapters.
- Modular layering: clear separation of concerns, easy to swap providers.
- Dependency inversion: Core engine depends on interfaces, not concrete classes.
- Asynchronous/synchronous router patterns in API and playground modules.
d. Key Technologies & Frameworks
- Python 3.9+
- FastAPI (api/, app/fastapi/)
- Click / Rich for CLI (cli/)
- Pydantic schemas (api/schemas/)
- Multiple third-party SDKs: OpenAI, Anthropic, AWS, etc.
- Vector DB clients: Chroma, Milvus, Pinecone, etc.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontends
    subgraph "Frontends"
        CLI["CLI"]:::frontend
        API["API Server"]:::frontend
        GUI["GUI/Playground"]:::frontend
    end

    %% Core Engine
    subgraph "Core Engine"
        Agent["Agent Manager"]:::core
        WF["Workflow Engine"]:::core
        Runner["Runner"]:::core
    end

    %% Layers
    subgraph "Model Layer"
        ModelAbst["Model Abstraction Interface"]:::model
        OAI["OpenAIChat Adapter"]:::ext
        Anthropic["Anthropic Adapter"]:::ext
    end

    subgraph "Embedding Service Layer"
        Emb["Embedding Service Interface"]:::model
        EBHelper["Embedding Helpers"]:::support
    end

    subgraph "Memory Layer"
        MemMgr["Memory Manager"]:::memory
        MemDB["Memory DB Interface"]:::memory
        PGMem["Postgres Memory Adapter"]:::ext
    end

    subgraph "Knowledge Layer"
        KnowCombined["Combined Knowledge"]:::knowledge
        DocChunk["Document Chunker"]:::knowledge
        DocReader["Document Reader"]:::knowledge
    end

    subgraph "Tool Layer"
        ToolReg["Tool Registry"]:::tools
        ToolImpl["Tool Adapters"]:::ext
    end

    subgraph "Vector Store Layer"
        VDBInterface["VectorDB Interface"]:::storage
        Chroma["Chroma Adapter"]:::ext
        MongoVDB["MongoDB Adapter"]:::ext
    end

    subgraph "Storage Layer"
        StorInterface["Storage Interface"]:::storage
        JSONStor["JSON Adapter"]:::storage
        PGStor["Postgres Adapter"]:::ext
    end

    subgraph "Utils & Support"
        Utils["Common Utilities"]:::support
        Eval["Evaluation Services"]:::support
    end

    %% External Services
    OpenAI["OpenAI API"]:::external
    AnthropicAPI["Anthropic API"]:::external
    Postgres["Postgres DB"]:::external
    MongoDB["MongoDB"]:::external
    Redis["Redis"]:::external
    ThirdPartyTools["External Tool APIs"]:::external

    %% Connections - Frontends to Core
    CLI -->|sync| Agent
    CLI -->|sync| WF
    API -->|async| Agent
    API -->|async| WF
    GUI -->|async| Agent
    GUI -->|async| WF

    %% Core Engine interactions
    Agent -->|invokes| MemMgr
    Agent -->|calls| ModelAbst
    Agent -->|executes| ToolReg
    WF -->|orchestrates| Runner

    Runner -->|persists| StorInterface
    Runner -->|loads| MemMgr

    %% Layer connections
    ModelAbst -->|implements| OAI
    ModelAbst -->|implements| Anthropic

    Emb -->|uses| EBHelper
    Agent -->|embeds| Emb

    MemMgr -->|uses| MemDB
    MemDB -->|adapter| PGMem

    KnowCombined -->|chunks| DocChunk
    KnowCombined -->|reads| DocReader
    Agent -->|retrieves| KnowCombined

    ToolReg -->|registers| ToolImpl
    Agent -->|executes| ToolImpl

    VDBInterface -->|adapter| Chroma
    VDBInterface -->|adapter| MongoVDB
    Agent -->|stores embeddings| VDBInterface

    StorInterface -->|format| JSONStor
    StorInterface -->|adapter| PGStor

    Agent -->|logs & metrics| Utils
    WF -->|evaluates| Eval

    %% Core ↔ External
    OAI -->|HTTP| OpenAI
    Anthropic -->|HTTP| AnthropicAPI
    PGMem -->|SQL| Postgres
    PGStor -->|SQL| Postgres
    MongoVDB -->|NoSQL| MongoDB
    JSONStor -->|filesystem| Redis
    ToolImpl -->|API| ThirdPartyTools

    %% Click Events
    click CLI "https://github.com/sonnh96/saio/blob/main/cli/entrypoint.py"
    click API "https://github.com/sonnh96/saio/blob/main/api/app.py"
    click GUI "https://github.com/sonnh96/saio/blob/main/app/playground/app.py"
    click Agent "https://github.com/sonnh96/saio/blob/main/agent/agent.py"
    click WF "https://github.com/sonnh96/saio/blob/main/workflow/workflow.py"
    click Runner "https://github.com/sonnh96/saio/blob/main/run/base.py"
    click ModelAbst "https://github.com/sonnh96/saio/blob/main/models/base.py"
    click Emb "https://github.com/sonnh96/saio/blob/main/embedder/base.py"
    click MemMgr "https://github.com/sonnh96/saio/blob/main/memory/memory.py"
    click KnowCombined "https://github.com/sonnh96/saio/blob/main/knowledge/combined.py"
    click ToolReg "https://github.com/sonnh96/saio/blob/main/tools/tool_registry.py"
    click VDBInterface "https://github.com/sonnh96/saio/blob/main/vectordb/base.py"
    click StorInterface "https://github.com/sonnh96/saio/blob/main/storage/base.py"
    click Utils "https://github.com/sonnh96/saio/blob/main/utils/common.py"

    %% Styles
    classDef frontend fill:#dddddd,stroke:#888,stroke-width:1px
    classDef core fill:#cce5ff,stroke:#339,stroke-width:1px
    classDef model fill:#fff2cc,stroke:#996600,stroke-width:1px
    classDef memory fill:#d9ead3,stroke:#38761d,stroke-width:1px
    classDef knowledge fill:#f4cccc,stroke:#cc0000,stroke-width:1px
    classDef tools fill:#fce5cd,stroke:#e69138,stroke-width:1px
    classDef storage fill:#e1d5e7,stroke:#6b3b6b,stroke-width:1px
    classDef support fill:#dddddd,stroke:#666,stroke-width:1px
    classDef external fill:#ffffff,stroke:#999999,stroke-width:1px,stroke-dasharray: 5 5
```
