How primisai/nexus works
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.