# mainframecomputer/orchestra architecture

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

- Interactive diagram: https://gitdiagram.com/mainframecomputer/orchestra
- Repository: https://github.com/mainframecomputer/orchestra

## Overview

##### Main Components

a) Core System Components:
- Agent System
- Task Management System
- Tool Registry
- LLM Interface Layer
- Orchestration Engine

b) External Integrations:
- LLM Providers (OpenAI, Anthropic, Openrouter, Ollama, Groq)
- External Tools/Services (GitHub, Wikipedia, Amadeus, etc.)
- Vector Stores (FAISS, Pinecone)

**Top Layer: Client Applications**

**Middle Layer: Orchestra Core**

**Bottom Layer: External Services & Integrations**

##### Specific Component Relationships

- It to the Agent System and Task Management System
- Tool Registry interfacing with both Agents and Tasks

b) Agent Layer:
- How agents can be both executors and conductors
- Multi-agent team structure
- Agents to their assigned tools

c) Tool Integration Layer:
- Tools by category (Web, File, Analytics, etc.)
- Connection to external services
- Docstring-based tool definition system

##### Key Flows to Highlight

a) Task Execution Flow:
**User Request → Task Creation → Agent Assignment → Tool Selection → Execution → Response**

b) Multi-Agent Orchestration:
**Conductor Agent → Sub-Agents → Tool Usage → Result Aggregation**

##### Important Elements

- Streaming support indicators
- Fallback chains
- Tool registration system
- Message passing between agents
- Task decomposition flow

##### Specific Implementation Details

- The modular tool system (from /tools directory)
- The agent implementation (from agent.py)
- The task management system (from task.py)
- The orchestration layer (from orchestration.py)

##### Technical Details to Emphasize

- Support for different LLM providers
- Streaming capabilities
- Phased task execution system
- Fallback mechanisms

##### Architectural Patterns to Highlight

- Modular design
- Plugin architecture for tools
- Event-driven communication
- Hierarchical agent structure

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles
    classDef core fill:#2374ab,color:#fff,stroke:#333
    classDef external fill:#7dba84,color:#333,stroke:#333
    classDef llm fill:#ff914d,color:#333,stroke:#333
    classDef tool fill:#8675a9,color:#fff,stroke:#333
    classDef infra fill:#c2c2c2,color:#333,stroke:#333
    
    %% Core Components
    subgraph Orchestra["Orchestra Core"]
        OE[Orchestration Engine]:::core
        AS[Agent System]:::core
        TMS[Task Management]:::core
        TR[Tool Registry]:::core
        LLM[LLM Interface]:::core
    end

    %% LLM Providers
    subgraph LLMProviders["LLM Providers"]
        OpenAI[OpenAI]:::llm
        Anthropic[Anthropic]:::llm
        Openrouter[Openrouter]:::llm
        Ollama[Ollama]:::llm
        Groq[Groq]:::llm
    end

    %% Tool Categories
    subgraph Tools["Tool Integration"]
        VectorStores[Vector Stores]:::tool
        WebTools[Web Tools]:::tool
        FileTools[File Tools]:::tool
        AnalyticsTools[Analytics Tools]:::tool
    end

    %% External Services
    subgraph External["External Services"]
        GitHub[GitHub]:::external
        Wikipedia[Wikipedia]:::external
        Amadeus[Amadeus]:::external
        FAISS[FAISS]:::external
        Pinecone[Pinecone]:::external
    end

    %% Relationships
    OE --> AS
    OE --> TMS
    OE --> TR
    AS --> TR
    TMS --> TR
    LLM --> AS
    LLM --> LLMProviders
    TR --> Tools
    Tools --> External
    
    %% Click Events
    click OE "https://github.com/mainframecomputer/orchestra/blob/main/packages/python/src/mainframe_orchestra/orchestration.py"
    click AS "https://github.com/mainframecomputer/orchestra/blob/main/packages/python/src/mainframe_orchestra/agent.py"
    click TMS "https://github.com/mainframecomputer/orchestra/blob/main/packages/python/src/mainframe_orchestra/task.py"
    click TR "https://github.com/mainframecomputer/orchestra/blob/main/packages/python/src/mainframe_orchestra/tools/__init__.py"
    click LLM "https://github.com/mainframecomputer/orchestra/blob/main/packages/python/src/mainframe_orchestra/llm.py"
    click GitHub "https://github.com/mainframecomputer/orchestra/blob/main/packages/python/src/mainframe_orchestra/tools/github_tools.py"
    click Wikipedia "https://github.com/mainframecomputer/orchestra/blob/main/packages/python/src/mainframe_orchestra/tools/wikipedia_tools.py"
    click Amadeus "https://github.com/mainframecomputer/orchestra/blob/main/packages/python/src/mainframe_orchestra/tools/amadeus_tools.py"
    click FAISS "https://github.com/mainframecomputer/orchestra/blob/main/packages/python/src/mainframe_orchestra/tools/faiss_tools.py"
    click Pinecone "https://github.com/mainframecomputer/orchestra/blob/main/packages/python/src/mainframe_orchestra/tools/pinecone_tools.py"

    %% Legend
    subgraph Legend
        L1[Core Components]:::core
        L2[External Services]:::external
        L3[LLM Providers]:::llm
        L4[Tool Categories]:::tool
        L5[Infrastructure]:::infra
    end
```
