# yashchinchole/agenthub architecture

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

- Interactive diagram: https://gitdiagram.com/yashchinchole/agenthub
- Repository: https://github.com/yashchinchole/agenthub

## Overview

##### Project Type and Purpose
- AgentHub is a full-stack, multi-agent AI assistant system.
- It combines a Streamlit UI (frontend), a FastAPI service (backend), an agent orchestrator (LangGraph/LangChain), multiple specialized agents, persistent memory (ChromaDB/SQLite), and external services (OpenAI, Groq, DuckDuckGo, ArXiv).
- Use cases: conversational chat, document Q&A (RAG), SQL querying, live web searches, Wikipedia lookups, ArXiv paper research.

##### File Structure Analysis
- Top-level: docker-compose.prod.yml, Dockerfiles in docker/, environment config (.env.example), project metadata (pyproject.toml, requirements.txt, uv.lock).
- scripts/: a utility to build ChromaDB.
- src/: the core of the system:
- run_agent.py, run_service.py, run_client.py, streamlit_app.py – entrypoints.
- agents/: implementations of 6 agents + content moderation tools.
- service/: FastAPI service layer and utilities.
- client/: client abstraction for backend calls.
- core/: LLM integration and settings.
- memory/: persistent store adapters (ChromaDB, SQLite).
- schema/: Pydantic models, Graph schemas, task definitions.

##### Key Architectural Patterns
- Modular, plugin-style agents loaded into a LangGraph orchestrator.
- Asynchronous, event-driven FastAPI service exposing REST and streaming endpoints.
- Separation of concerns: UI (Streamlit) ↔ API (FastAPI) ↔ Orchestrator (LangGraph) ↔ Agents/Tools ↔ Data Stores.
- Containerized deployment (Docker Compose for app + service).

##### Main Components
A. Frontend (Streamlit App)
- Entrypoint: streamlit_app.py
- Connects via HTTP/Websocket to FastAPI service.
B. Backend Service (FastAPI)
- run_service.py → exposes /chat, /stream endpoints.
- service/service.py, service/utils.py
C. Agent Orchestrator (LangGraph + LangChain)
- Defined by langgraph.json and core/llm.py, schema/schema.py
- Orchestrates agent workflows and streaming.
D. Agents
- agents/*.py: chatbot, rag_assistant (ChromaDB), sql_agent (Chinook SQLite), research_assistant (DuckDuckGo + calculator), wikipedia_agent, arxiv_agent.
- LlamaGuard for content moderation.
E. Client Library
- client/client.py & run_client.py for programmatic usage.
F. Memory / Data Stores
- ChromaDB (vector store) folder + chroma.sqlite3
- SQLite (Chinook.db) for SQL Agent
- task_data.py + models.py for schema persistence
G. External Services
- LLM providers (OpenAI, Groq)
- DuckDuckGo Search API (ddgs)
- ArXiv API
- LangSmith telemetry
H. Deployment
- Dockerfile.app (Streamlit + client?)
- Dockerfile.service (FastAPI)
- docker-compose.prod.yml orchestrates multi-container setup
I. Utility Scripts
- scripts/create_chroma_db.py to ingest PDFs into ChromaDB

##### Relationships and Data Flows
1. User interacts with Streamlit UI → sends request to FastAPI.
2. FastAPI handler loads Graph workflow (langgraph.json) → instantiates required agent(s).
3. Agents request LLM calls via core/llm.py.
4. Agents may read/write memory: ChromaDB (RAG), SQLite (SQL), in-memory state.
5. Agents may invoke external tools/services (DuckDuckGo, ArXiv, calculator).
6. Responses stream back through FastAPI to Streamlit.
7. Feedback/analytics sent to LangSmith.

##### Essential Elements to Capture
- Component names (exact file or module names).
- Data stores and their physical locations (local file vs. container volume).
- Deployment units (Docker images, Compose services).
- Interaction protocols and asynchronous streams.
- Extensibility points (adding new agents or tools).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        StreamlitApp["Streamlit App"]:::frontend
    end

    %% API Service Layer
    subgraph "API Service Layer"
        direction TB
        RunService["run_service.py"]:::api
        ServiceLayer["service.py"]:::api
        ServiceUtils["utils.py"]:::api
    end

    %% Orchestrator Layer
    subgraph "Orchestrator Layer"
        direction TB
        LangGraphConfig["langgraph.json"]:::orchestrator
        LLMLib["llm.py"]:::orchestrator
        CoreSettings["settings.py"]:::orchestrator
        AgentLoader["agents.py"]:::orchestrator
        SchemaDef["schema.py"]:::orchestrator
    end

    %% Agents Layer
    subgraph "Agents Layer"
        direction TB
        ChatbotAgent["chatbot.py"]:::agent
        RAGAgent["rag_assistant.py"]:::agent
        SQLAgent["sql_agent.py"]:::agent
        ResearchAgent["research_assistant.py"]:::agent
        WikiAgent["wikipedia_agent.py"]:::agent
        ArxivAgent["arxiv_agent.py"]:::agent
        LlamaGuard["llama_guard.py"]:::agent
        SharedTools["tools.py"]:::agent
    end

    %% Client Library
    subgraph "Client Library"
        direction TB
        RunClient["run_client.py"]:::client
        ClientModule["client.py"]:::client
    end

    %% Data Stores Layer
    subgraph "Data Stores"
        direction TB
        ChromaDBStore["ChromaDB Store"]:::db
        SQLiteStore["SQLite Store"]:::db
        TaskData["task_data.py / models.py"]:::db
    end

    %% External Services Layer
    subgraph "External Services"
        direction TB
        OpenAI["OpenAI / Groq"]:::external
        DuckDuckGo["DuckDuckGo API"]:::external
        Arxiv["ArXiv API"]:::external
        LangSmith["LangSmith Telemetry"]:::external
    end

    %% Deployment Layer
    subgraph "Deployment"
        direction TB
        DockerCompose["docker-compose.prod.yml"]:::deploy
        DockerApp["Dockerfile.app"]:::deploy
        DockerService["Dockerfile.service"]:::deploy
    end

    %% Connections
    StreamlitApp -->|"HTTP/WebSocket"| RunService
    RunService -->|imports| ServiceLayer
    RunService -->|imports| ServiceUtils
    RunService -->|loads| LangGraphConfig
    ServiceLayer -->|"calls"| AgentLoader
    AgentLoader -->|loads| ChatbotAgent
    AgentLoader -->|loads| RAGAgent
    AgentLoader -->|loads| SQLAgent
    AgentLoader -->|loads| ResearchAgent
    AgentLoader -->|loads| WikiAgent
    AgentLoader -->|loads| ArxivAgent
    AgentLoader -->|loads| LlamaGuard
    AgentLoader -->|loads| SharedTools

    AgentLoader -->|"uses"| LLMLib
    LLMLib -->|"reads"| CoreSettings

    RAGAgent -->|"reads/writes"| ChromaDBStore
    SQLAgent -->|"reads/writes"| SQLiteStore
    ResearchAgent -->|"uses"| DuckDuckGo
    ArxivAgent -->|"uses"| Arxiv
    SharedTools -->|"uses"| LLMLib

    AgentLoader -->|streams to| ServiceLayer
    ServiceLayer -->|streams| StreamlitApp

    AgentLoader -->|sends telemetry| LangSmith
    LLMLib -->|"calls"| OpenAI

    RunClient -->|uses HTTP| ClientModule
    ClientModule -->|calls| RunService

    %% Data Store Persistence
    TaskData -->|"used by"| ServiceLayer

    %% Deployment Links
    DockerCompose --> DockerApp
    DockerCompose --> DockerService

    %% Click Events
    click StreamlitApp "https://github.com/yashchinchole/agenthub/blob/master/src/streamlit_app.py"
    click RunService "https://github.com/yashchinchole/agenthub/blob/master/src/run_service.py"
    click ServiceLayer "https://github.com/yashchinchole/agenthub/blob/master/src/service/service.py"
    click ServiceUtils "https://github.com/yashchinchole/agenthub/blob/master/src/service/utils.py"
    click LangGraphConfig "https://github.com/yashchinchole/agenthub/blob/master/langgraph.json"
    click LLMLib "https://github.com/yashchinchole/agenthub/blob/master/src/core/llm.py"
    click CoreSettings "https://github.com/yashchinchole/agenthub/blob/master/src/core/settings.py"
    click ChatbotAgent "https://github.com/yashchinchole/agenthub/blob/master/src/agents/chatbot.py"
    click RAGAgent "https://github.com/yashchinchole/agenthub/blob/master/src/agents/rag_assistant.py"
    click SQLAgent "https://github.com/yashchinchole/agenthub/blob/master/src/agents/sql_agent.py"
    click ResearchAgent "https://github.com/yashchinchole/agenthub/blob/master/src/agents/research_assistant.py"
    click WikiAgent "https://github.com/yashchinchole/agenthub/blob/master/src/agents/wikipedia_agent.py"
    click ArxivAgent "https://github.com/yashchinchole/agenthub/blob/master/src/agents/arxiv_agent.py"
    click LlamaGuard "https://github.com/yashchinchole/agenthub/blob/master/src/agents/llama_guard.py"
    click SharedTools "https://github.com/yashchinchole/agenthub/blob/master/src/agents/tools.py"
    click AgentLoader "https://github.com/yashchinchole/agenthub/blob/master/src/agents/agents.py"
    click RunClient "https://github.com/yashchinchole/agenthub/blob/master/src/run_client.py"
    click ClientModule "https://github.com/yashchinchole/agenthub/blob/master/src/client/client.py"
    click SQLiteStore "https://github.com/yashchinchole/agenthub/blob/master/src/memory/sqlite.py"
    click TaskData "https://github.com/yashchinchole/agenthub/blob/master/src/schema/task_data.py"
    click DockerCompose "https://github.com/yashchinchole/agenthub/blob/master/docker-compose.prod.yml"
    click DockerApp "https://github.com/yashchinchole/agenthub/blob/master/docker/Dockerfile.app"
    click DockerService "https://github.com/yashchinchole/agenthub/blob/master/docker/Dockerfile.service"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,color:#004085
    classDef api fill:#d4edda,stroke:#155724,color:#155724
    classDef orchestrator fill:#fff3cd,stroke:#856404,color:#856404
    classDef agent fill:#f8d7da,stroke:#721c24,color:#721c24
    classDef client fill:#d1ecf1,stroke:#0c5460,color:#0c5460
    classDef db fill:#ffe5b4,stroke:#cc7a00,color:#662200
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#383d41
    classDef deploy fill:#f0f0f0,stroke:#333333,color:#333333
```
