# primisai/nexus architecture

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

- Interactive diagram: https://gitdiagram.com/primisai/nexus
- Repository: https://github.com/primisai/nexus

## Overview

##### Project type and purpose
- This is an open-source Python library (“PrimisAI Nexus”) for orchestrating multiple LLM-powered agents under a hierarchical supervisor.
- Key use case: build and coordinate AI agents (via Supervisor and Agent classes), persist history, integrate external tool/LLM services, and configure everything via code or YAML.

##### File structure
- Top-level folders:
- primisai/nexus/
– config/ (AgentFactory, YAML loader, validators)
– core/ (AI base class, Agent, Supervisor)
– history/ (HistoryManager)
– tools/ (tool_functions)
– utils/ (Debugger)
- examples/ (Python scripts & YAML, demonstrating various workflows)
- test/ (unit tests)
- scripts/ (helper scripts: e.g., sync_dependencies.py)
- CI/CD and metadata (.github, pyproject.toml, setup.py, requirements.txt)

##### Key insights from README
- Core classes: AI → Agent → Supervisor (supports both main and assistant supervisors).
- Hierarchical supervision: main supervisor can register agents and assistant supervisors.
- Configurable: via Python API or YAML (AgentFactory, load_yaml_config).
- Persistent history (JSONL) and logging per workflow.
- External integration: LLM endpoints (OpenAI), MCP servers (SSE or stdio).
- Structured outputs via JSON schema, debugging utilities.

##### Main components & interactions
a. Components
- External LLM Service (e.g., OpenAI API)
- Core Library Modules
– AI Base Class (abstract LLM interface)
– Agent (extends AI, optional tools, output schema)
– Supervisor (main or assistant; registers/coordinates Agents)
– AgentFactory & YAML Loader (config module)
– HistoryManager (persistent JSONL storage)
– Debugger (logging/troubleshooting)
- External Tool Servers (MCP SSE endpoints or stdio subprocesses)
- User or Host Application (the Python script that instantiates Supervisor/Agents)
- File System (workflow directories, history.jsonl, logs/)

b. Relationships & data flows
- Host Application → Supervisor.create/register agents (calls into config and core).
- Supervisor → manages Agent lifecycle and task delegation.
- Supervisor & Agents → HistoryManager (load/save chat history).
- Agents → AI Base → External LLM Service (HTTP calls).
- Agents → optional Tools via:
– local Python functions (tool_functions)
– external MCP Servers (SSE or stdio)—call/update_mcp_tools.
- Debugger hooks into Agent/Supervisor for logging events.

c. Architectural patterns & principles
- Factory Pattern (AgentFactory creates Supervisor/Agent tree from YAML).
- Composite pattern (Supervisor contains Agents or other Supervisors in a tree).
- Strategy/Plugin (tools injection, output schema validation).
- Separation of Concerns (core vs config vs history vs utils).

d. Key technologies & libraries
- Python 3.x
- HTTP/SSE (requests or aiohttp for MCP SSE)
- YAML (PyYAML for config)
- JSON Schema (for structured outputs)
- JSONL (history storage)
- subprocess (for stdio MCP servers)

##### Supervisor
- Two variants:
- Main Supervisor (root)
- Assistant Supervisor (child of Main)
- Supervisor’s methods: register_agent(), start_interactive_session(), display_agent_graph().
- How Supervisor delegates tasks, routes messages, and persists history for each Agent.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Config Modules
    subgraph "Config Layer"
        AF["AgentFactory"]:::config
        YML["YAML Loader"]:::config
        CV["Config Validator"]:::config
    end

    %% Core Library
    subgraph "Core Layer"
        SM["Main Supervisor"]:::core
        SA["Assistant Supervisor"]:::core
        AG1["Agent"]:::core
        AG2["Agent"]:::core
        AI["AI Base Class"]:::core
    end

    %% History Storage
    subgraph "Storage"
        HM[(HistoryManager)]:::storage
    end

    %% Utilities
    subgraph "Utils"
        DBG["Debugger"]:::util
    end

    %% External Services
    subgraph "External Services"
        LLM(("External LLM Service")):::external
        MCP_SSE(("MCP SSE Server")):::external
        MCP_PROC[(Subprocess MCP Server)]:::external
    end

    %% Host Application
    HostApp["Host Application"]:::core

    %% Relationships
    HostApp -->|"uses"| AF
    AF -->|"loads config"| YML
    AF -->|"validates config"| CV
    AF -->|"creates"| SM

    SM -->|"registers/delegates"| AG1
    SM -->|"registers assistant"| SA
    SA -->|"registers/delegates"| AG2

    AG1 -->|"extends"| AI
    AG2 -->|"extends"| AI

    AG1 -->|"HTTP POST"| LLM
    AG2 -->|"HTTP POST"| LLM

    AG1 -->|"function call"| ToolFun
    AG2 -->|"function call"| ToolFun

    AG1 -->|"SSE subscribe"| MCP_SSE
    AG2 -->|"SSE subscribe"| MCP_SSE

    AG1 -->|"stdio"| MCP_PROC
    AG2 -->|"stdio"| MCP_PROC

    SM -->|"read/write"| HM
    SA -->|"read/write"| HM
    AG1 -->|"read/write"| HM
    AG2 -->|"read/write"| HM

    SM -->|"log events"| DBG
    AG1 -->|"log events"| DBG
    AG2 -->|"log events"| DBG

    %% Tool Functions as node
    ToolFun["Tool Functions"]:::core

    %% Click Events
    click AI "https://github.com/primisai/nexus/blob/main/primisai/nexus/core/ai.py"
    click AG1 "https://github.com/primisai/nexus/blob/main/primisai/nexus/core/agents.py"
    click SM "https://github.com/primisai/nexus/blob/main/primisai/nexus/core/supervisor.py"
    click AF "https://github.com/primisai/nexus/blob/main/primisai/nexus/config/agent_factory.py"
    click YML "https://github.com/primisai/nexus/blob/main/primisai/nexus/config/yaml_config.py"
    click CV "https://github.com/primisai/nexus/blob/main/primisai/nexus/config/config_validator.py"
    click HM "https://github.com/primisai/nexus/blob/main/primisai/nexus/history/history_manager.py"
    click ToolFun "https://github.com/primisai/nexus/blob/main/primisai/nexus/tools/tool_functions.py"
    click DBG "https://github.com/primisai/nexus/blob/main/primisai/nexus/utils/debugger.py"
    click HostApp "https://github.com/primisai/nexus/blob/main/examples/hierarchical_structure.py"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000080,color:#000080
    classDef config fill:#90EE90,stroke:#006400,color:#006400
    classDef external fill:#FFA500,stroke:#FF8C00,color:#FF8C00
    classDef storage fill:#D3D3D3,stroke:#696969,color:#696969
    classDef util fill:#DDA0DD,stroke:#8B008B,color:#8B008B
```
