# hazyresearch/minions architecture

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

- Interactive diagram: https://gitdiagram.com/hazyresearch/minions
- Repository: https://github.com/hazyresearch/minions

## Overview

##### Main Components
- Frontend/Demo Interface: This includes the “app.py” that launches a Streamlit demo, the “minions_cli.py” for CLI interaction, and “minions.ipynb” for notebook usage. These interfaces allow a user to trigger the protocol.
- Core Protocol Module: The core modules (“minion.py”, “minions.py”, “minions_mcp.py”) implement the logic for orchestrating the back-and-forth communication between local and remote models.
- Clients Library: The “minions/clients/” directory encapsulates integrations with many cloud services and on-device model servers (e.g., “ollama”, “openai”, “azure_openai”, “together”, “tokasaurus”, etc.). Each client acts as an abstraction for handling API interactions.
- Utilities and Helpers: The “minions/utils/” directory – including helpers for document processing, energy tracking, retrieval, etc. – which provide ancillary functionalities.
- Example Code & Prompts: Directories “minions/examples/” and “minions/prompts/” demonstrate how to set up tasks and run cases, providing real-world scenarios that show the protocol in action.

##### Relationships and Data Flow
- User inputs a request (via a CLI, GUI, or Notebook).
- The front-end interface directs the input to the core protocol layer.
- The protocol layer calls the appropriate clients (one local and one remote) to process a “context” and “task” in a conversational or round-based manner.
- The clients manage their own API interactions – local requests (via servers like “ollama” or “tokasaurus”) and remote requests (to providers like “OpenAI”, “Azure OpenAI”, etc.), then exchange feedback based on the protocol.
- Utility modules may handle additional processing (like document extraction or energy tracking) throughout this communication cycle.
- Results are then communicated back to the user through the front-end.

##### Architectural Patterns and Design Principles
- Modular Design: The project is organized into discrete modules (clients, core protocol, utilities) allowing independent updates and potential extensions.
- Plugin-like Integration: Each client is isolated in its own module, following a standardized interface, which resembles a plugin system.
- Extensibility and Abstraction: The protocol classes encapsulate the round-based communication logic, abstracting away the details of different LLM interactions.
- Separation of Concerns: Front-end presentation (CLI/streamlit/notebook), core orchestration, and external service integrations are kept distinct.

##### Technology Stack and Relevant Details
- Python 3.10-3.11 support (with compatibility notes).
- Integration with external LLM services (OpenAI, Azure OpenAI, Together, etc.) is critical.
- Optional components for specialized hardware support (e.g., using “ollama” on non-NVIDIA setups or “tokasaurus” with NVIDIA GPUs).

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% User Interface Layer
    subgraph "User Interface Layer"
        UI1("Streamlit App"):::ui
        UI2("CLI Interface"):::ui
        UI3("Notebook Interface"):::ui
    end

    %% Core Protocol Engine
    subgraph "Core Protocol Engine"
        CP1("Minion"):::protocol
        CP2("Minions"):::protocol
        CP3("Minions MCP"):::protocol
        CP4("Minion w/ Tools"):::protocol
    end

    %% Clients Library
    subgraph "Clients Library"
        CL("Clients Library"):::client
    end

    %% Utilities and Helpers
    subgraph "Utilities & Helpers"
        UT("Utilities & Helpers"):::util
    end

    %% Example Code & Prompts
    subgraph "Example Code & Prompts"
        EX("Examples"):::example
        PR("Prompts"):::example
    end

    %% Connections from User Interfaces to Core Protocol Engine
    UI1 -->|"input"| CP1
    UI2 -->|"input"| CP1
    UI3 -->|"input"| CP1

    %% Internal core protocol sequence
    CP1 -->|"chain"| CP2
    CP2 -->|"chain"| CP3
    CP3 -->|"chain"| CP4

    %% Core Protocol Engine communicates with Clients and Utilities
    CP1 -->|"invoke"| CL
    CP1 -->|"utilize"| UT
    CL -->|"response"| CP1
    UT -->|"feedback"| CP1

    %% Core Protocol Engine responds back to User Interfaces
    CP1 -->|"result"| UI1
    CP1 -->|"result"| UI2
    CP1 -->|"result"| UI3

    %% Demonstration examples linking to the UI (showing sample task setups)
    EX ---|"demo_tasks"| UI1
    PR ---|"demo_tasks"| UI1

    %% Click Events for Frontend/Demo Interface
    click UI1 "https://github.com/hazyresearch/minions/blob/main/app.py"
    click UI2 "https://github.com/hazyresearch/minions/blob/main/minions_cli.py"
    click UI3 "https://github.com/hazyresearch/minions/blob/main/minions.ipynb"

    %% Click Events for Core Protocol Module
    click CP1 "https://github.com/hazyresearch/minions/blob/main/minions/minion.py"
    click CP2 "https://github.com/hazyresearch/minions/blob/main/minions/minions.py"
    click CP3 "https://github.com/hazyresearch/minions/blob/main/minions/minions_mcp.py"
    click CP4 "https://github.com/hazyresearch/minions/blob/main/minions/minion_wtools.py"

    %% Click Events for Clients Library
    click CL "https://github.com/hazyresearch/minions/tree/main/minions/clients/"

    %% Click Events for Utilities and Helpers
    click UT "https://github.com/hazyresearch/minions/tree/main/minions/utils/"

    %% Click Events for Example Code & Prompts
    click EX "https://github.com/hazyresearch/minions/tree/main/minions/examples/"
    click PR "https://github.com/hazyresearch/minions/tree/main/minions/prompts/"

    %% Styles
    classDef ui fill:#FFD700,stroke:#DAA520,stroke-width:2px;
    classDef protocol fill:#87CEFA,stroke:#4682B4,stroke-width:2px;
    classDef client fill:#90EE90,stroke:#228B22,stroke-width:2px;
    classDef util fill:#FFA07A,stroke:#CD5C5C,stroke-width:2px;
    classDef example fill:#DDA0DD,stroke:#9932CC,stroke-width:2px;
```
