# zyren41/agi_saber architecture

> Architecture diagram of the GitHub repository zyren41/agi_saber, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zyren41/agi_saber
- Repository: https://github.com/zyren41/agi_saber

## Overview

AGI-assistant is a multimodal conversational agent exposed through a FastAPI service. The principal flow accepts a chat request, routes it to conversation, RAG, a single tool, or multi-step ReAct, then returns an answer and execution details; memory and snapshots support continuity and recovery. Separate document ingestion and retrieval branches support knowledge-base use. The graph preserves README-documented capabilities and source-indexed core modules; some connections are documented rather than verified in sampled implementation excerpts.

Main entry points: [`final/internal/agent/agent.py`](https://github.com/zyren41/agi_saber/blob/python/final/internal/agent/agent.py) (Unified agent), [`final/internal/repo/ragchunk.py`](https://github.com/zyren41/agi_saber/blob/python/final/internal/repo/ragchunk.py) (Repositories), [`final/internal/handler/handler.py`](https://github.com/zyren41/agi_saber/blob/python/final/internal/handler/handler.py) (HTTP API), [`final/main.py`](https://github.com/zyren41/agi_saber/blob/python/final/main.py) (Service assembly)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Service interface"]
  node_http["HTTP API<br/>[handler.py]"]
  node_app["Service assembly<br/>[main.py]"]
end

subgraph group_agent["Agent orchestration"]
  node_agent_core["Unified agent<br/>[agent.py]"]
  node_mode_router["Mode router<br/>[router.py]"]
  node_planner["ReAct planner<br/>[planner.py]"]
  node_prompt["Prompt context<br/>[assembler.py]"]
end

subgraph group_knowledge["Knowledge and memory"]
  node_rag["RAG engine<br/>[rag.py]"]
  node_hybrid["Hybrid retrieval<br/>[hybrid.py]"]
  node_document["Document library<br/>[library.py]"]
  node_parser["Document parser<br/>[parser.py]"]
  node_kg["Knowledge graph<br/>[kgstore.py]"]
  node_memory["Three-tier memory<br/>[memory.py]"]
  node_graph_memory["Graph memory<br/>[graph_memory.py]"]
end

subgraph group_execution["Tools and recovery"]
  node_toolkit["Tool registry<br/>[tools.py]"]
  node_sandbox["Sandbox executor<br/>[executor.py]"]
  node_harness["Task recovery<br/>[restore.py]"]
end

subgraph group_platform["Persistence and services"]
  node_llm["LLM client<br/>[llm.py]"]
  node_infra["Infrastructure<br/>[infra.py]"]
  node_repos["Repositories<br/>[ragchunk.py]"]
  node_postgres[("PostgreSQL<br/>[postgres.py]")]
  node_milvus[("Milvus<br/>[milvus.py]")]
  node_elasticsearch[("Elasticsearch<br/>[es.py]")]
  node_neo4j[("Neo4j<br/>[neo4j.py]")]
  node_kafka["Kafka<br/>[kafka.py]"]
end

node_user(("User"))

node_user -->|"sends request"| node_http
node_app -->|"initializes"| node_infra
node_app -->|"constructs"| node_agent_core
node_app -->|"sets up routes"| node_http
node_http -->|"processes chat"| node_agent_core
node_agent_core -->|"selects mode"| node_mode_router
node_mode_router -->|"chooses ReAct"| node_planner
node_agent_core -->|"assembles context"| node_prompt
node_agent_core -->|"loads and stores"| node_memory
node_agent_core -->|"generates responses"| node_llm
node_agent_core -->|"runs knowledge search"| node_rag
node_agent_core -->|"dispatches tools"| node_toolkit
node_planner -->|"plans tool calls"| node_toolkit
node_toolkit -->|"executes commands"| node_sandbox
node_http -->|"manages documents"| node_document
node_document -->|"parses content"| node_parser
node_rag -->|"retrieves and fuses"| node_hybrid
node_rag -->|"synthesizes answer"| node_llm
node_hybrid -->|"searches graph"| node_kg
node_memory -->|"extends recall"| node_graph_memory
node_kg -->|"queries graph store"| node_neo4j
node_hybrid -->|"loads and indexes chunks"| node_repos
node_repos -->|"persists source chunks"| node_postgres
node_repos -->|"indexes vectors"| node_milvus
node_repos -->|"indexes keywords"| node_elasticsearch
node_infra -->|"assembles repositories"| node_repos
node_agent_core -->|"recovers execution"| node_harness
node_harness -->|"stores snapshots"| node_postgres
node_infra -->|"publishes events"| node_kafka

click node_http "https://github.com/zyren41/agi_saber/blob/python/final/internal/handler/handler.py"
click node_app "https://github.com/zyren41/agi_saber/blob/python/final/main.py"
click node_agent_core "https://github.com/zyren41/agi_saber/blob/python/final/internal/agent/agent.py"
click node_mode_router "https://github.com/zyren41/agi_saber/blob/python/final/internal/agent/router.py"
click node_planner "https://github.com/zyren41/agi_saber/blob/python/final/internal/agent/planner.py"
click node_prompt "https://github.com/zyren41/agi_saber/blob/python/final/internal/promptctx/assembler.py"
click node_llm "https://github.com/zyren41/agi_saber/blob/python/final/internal/llm/llm.py"
click node_rag "https://github.com/zyren41/agi_saber/blob/python/final/internal/rag/rag.py"
click node_hybrid "https://github.com/zyren41/agi_saber/blob/python/final/internal/rag/hybrid.py"
click node_document "https://github.com/zyren41/agi_saber/blob/python/final/internal/document/library.py"
click node_parser "https://github.com/zyren41/agi_saber/blob/python/final/internal/document/parser.py"
click node_kg "https://github.com/zyren41/agi_saber/blob/python/final/internal/graph/kgstore.py"
click node_memory "https://github.com/zyren41/agi_saber/blob/python/final/internal/memory/memory.py"
click node_graph_memory "https://github.com/zyren41/agi_saber/blob/python/final/internal/memory/graph_memory.py"
click node_toolkit "https://github.com/zyren41/agi_saber/blob/python/final/internal/tools/tools.py"
click node_sandbox "https://github.com/zyren41/agi_saber/blob/python/final/internal/sandbox/executor.py"
click node_harness "https://github.com/zyren41/agi_saber/blob/python/final/internal/agent/restore.py"
click node_infra "https://github.com/zyren41/agi_saber/blob/python/final/internal/infra/infra.py"
click node_repos "https://github.com/zyren41/agi_saber/blob/python/final/internal/repo/ragchunk.py"
click node_postgres "https://github.com/zyren41/agi_saber/blob/python/final/internal/platform/postgres.py"
click node_milvus "https://github.com/zyren41/agi_saber/blob/python/final/internal/platform/milvus.py"
click node_elasticsearch "https://github.com/zyren41/agi_saber/blob/python/final/internal/platform/es.py"
click node_neo4j "https://github.com/zyren41/agi_saber/blob/python/final/internal/platform/neo4j.py"
click node_kafka "https://github.com/zyren41/agi_saber/blob/python/final/internal/platform/kafka.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_http,node_app,node_user toneBlue
class node_agent_core,node_mode_router,node_planner,node_prompt toneAmber
class node_rag,node_hybrid,node_document,node_parser,node_kg,node_memory,node_graph_memory toneMint
class node_toolkit,node_sandbox,node_harness toneRose
class node_llm,node_infra,node_repos,node_postgres,node_milvus,node_elasticsearch,node_neo4j,node_kafka toneIndigo
```

## Components

### Service interface

- [HTTP API](https://github.com/zyren41/agi_saber/blob/python/final/internal/handler/handler.py): `final/internal/handler/handler.py`
- [Service assembly](https://github.com/zyren41/agi_saber/blob/python/final/main.py): `final/main.py`

### Agent orchestration

- [Unified agent](https://github.com/zyren41/agi_saber/blob/python/final/internal/agent/agent.py): `final/internal/agent/agent.py`
- [Mode router](https://github.com/zyren41/agi_saber/blob/python/final/internal/agent/router.py): `final/internal/agent/router.py`
- [ReAct planner](https://github.com/zyren41/agi_saber/blob/python/final/internal/agent/planner.py): `final/internal/agent/planner.py`
- [Prompt context](https://github.com/zyren41/agi_saber/blob/python/final/internal/promptctx/assembler.py): `final/internal/promptctx/assembler.py`

### Knowledge and memory

- [RAG engine](https://github.com/zyren41/agi_saber/blob/python/final/internal/rag/rag.py): `final/internal/rag/rag.py`
- [Hybrid retrieval](https://github.com/zyren41/agi_saber/blob/python/final/internal/rag/hybrid.py): `final/internal/rag/hybrid.py`
- [Document library](https://github.com/zyren41/agi_saber/blob/python/final/internal/document/library.py): `final/internal/document/library.py`
- [Document parser](https://github.com/zyren41/agi_saber/blob/python/final/internal/document/parser.py): `final/internal/document/parser.py`
- [Knowledge graph](https://github.com/zyren41/agi_saber/blob/python/final/internal/graph/kgstore.py): `final/internal/graph/kgstore.py`
- [Three-tier memory](https://github.com/zyren41/agi_saber/blob/python/final/internal/memory/memory.py): `final/internal/memory/memory.py`
- [Graph memory](https://github.com/zyren41/agi_saber/blob/python/final/internal/memory/graph_memory.py): `final/internal/memory/graph_memory.py`

### Tools and recovery

- [Tool registry](https://github.com/zyren41/agi_saber/blob/python/final/internal/tools/tools.py): `final/internal/tools/tools.py`
- [Sandbox executor](https://github.com/zyren41/agi_saber/blob/python/final/internal/sandbox/executor.py): `final/internal/sandbox/executor.py`
- [Task recovery](https://github.com/zyren41/agi_saber/blob/python/final/internal/agent/restore.py): `final/internal/agent/restore.py`

### Persistence and services

- [LLM client](https://github.com/zyren41/agi_saber/blob/python/final/internal/llm/llm.py): `final/internal/llm/llm.py`
- [Infrastructure](https://github.com/zyren41/agi_saber/blob/python/final/internal/infra/infra.py): `final/internal/infra/infra.py`
- [Repositories](https://github.com/zyren41/agi_saber/blob/python/final/internal/repo/ragchunk.py): `final/internal/repo/ragchunk.py`
- [PostgreSQL](https://github.com/zyren41/agi_saber/blob/python/final/internal/platform/postgres.py): `final/internal/platform/postgres.py`
- [Milvus](https://github.com/zyren41/agi_saber/blob/python/final/internal/platform/milvus.py): `final/internal/platform/milvus.py`
- [Elasticsearch](https://github.com/zyren41/agi_saber/blob/python/final/internal/platform/es.py): `final/internal/platform/es.py`
- [Neo4j](https://github.com/zyren41/agi_saber/blob/python/final/internal/platform/neo4j.py): `final/internal/platform/neo4j.py`
- [Kafka](https://github.com/zyren41/agi_saber/blob/python/final/internal/platform/kafka.py): `final/internal/platform/kafka.py`

### Other components

- **User**

## Connections

- User → HTTP API: sends request
- Service assembly → Infrastructure: initializes (evidence: `final/main.py`)
- Service assembly → Unified agent: constructs (evidence: `final/main.py`)
- Service assembly → HTTP API: sets up routes (evidence: `final/main.py`)
- HTTP API → Unified agent: processes chat (evidence: `final/internal/handler/handler.py`)
- Unified agent → Mode router: selects mode (evidence: `final/internal/agent/agent.py`)
- Mode router → ReAct planner: chooses ReAct
- Unified agent → Prompt context: assembles context (evidence: `final/internal/agent/agent.py`)
- Unified agent → Three-tier memory: loads and stores (evidence: `final/internal/agent/agent.py`)
- Unified agent → LLM client: generates responses (evidence: `final/internal/agent/agent.py`)
- Unified agent → RAG engine: runs knowledge search (evidence: `final/internal/agent/agent.py`)
- Unified agent → Tool registry: dispatches tools (evidence: `final/internal/agent/agent.py`)
- ReAct planner → Tool registry: plans tool calls
- Tool registry → Sandbox executor: executes commands
- HTTP API → Document library: manages documents (evidence: `final/internal/handler/handler.py`)
- Document library → Document parser: parses content
- RAG engine → Hybrid retrieval: retrieves and fuses (evidence: `final/internal/rag/rag.py`)
- RAG engine → LLM client: synthesizes answer (evidence: `final/internal/rag/rag.py`)
- Hybrid retrieval → Knowledge graph: searches graph (evidence: `final/internal/rag/hybrid.py`)
- Three-tier memory → Graph memory: extends recall (evidence: `final/internal/memory/memory.py`)
- Knowledge graph → Neo4j: queries graph store (evidence: `final/internal/graph/kgstore.py`)
- Hybrid retrieval → Repositories: loads and indexes chunks
- Repositories → PostgreSQL: persists source chunks (evidence: `final/internal/repo/ragchunk.py`)
- Repositories → Milvus: indexes vectors (evidence: `final/internal/repo/ragchunk.py`)
- Repositories → Elasticsearch: indexes keywords (evidence: `final/internal/repo/ragchunk.py`)
- Infrastructure → Repositories: assembles repositories (evidence: `final/internal/infra/infra.py`)
- Unified agent → Task recovery: recovers execution (evidence: `final/internal/agent/agent.py`)
- Task recovery → PostgreSQL: stores snapshots
- Infrastructure → Kafka: publishes events (evidence: `final/internal/infra/infra.py`)
