# andrewhampton/bristow architecture

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

- Interactive diagram: https://gitdiagram.com/andrewhampton/bristow
- Repository: https://github.com/andrewhampton/bristow

## Overview

##### Main components
- Agents – Represented by classes inheriting from Bristow::Agent, these encapsulate AI model interactions, specific system messages, and can have access to functions.
- Functions – These provide the API or “operational” endpoints that can be called by the AI model during a conversation. Functions are defined in classes inheriting from Bristow::Function.
- Agencies – Higher-level constructs that group together agents to orchestrate multi-agent interactions. The built-in agency patterns include the Supervisor (for dynamic hand-offs among agents) and the Workflow agency (for sequential processing).

##### Break out configuration and supporting modules
- Configuration – Handled in Bristow::Configuration, this module holds API keys, default models, logger settings, etc.
- Helpers and Delegates – Utility classes and methods (found under lib/bristow/helpers and lib/bristow/functions/delegate.rb) used to streamline interactions.
- Terminations – Handling exit conditions for agents and controls for stopping behavior (see lib/bristow/terminations).

##### Detail external interactions
- AI Model API – Note that the agents make calls to external APIs (such as OpenAI) by using the API key provided in the configuration.
- User Input / Output – Highlight that an end-user (or consuming application) provides input which is processed incrementally (streaming responses via blocks) and then returned back.

- A clear path starting from the user/application calling an agent’s chat method.
- The agent, based on its configuration (system message, agent traits), communicates with the OpenAI model.
- If necessary, the AI model chooses to make one or more function calls (via the defined Function classes) to interact with your application data.
- In the case of agencies, illustrate how a supervisor or workflow agency delegates parts of the conversation/task to different agents, aggregating their responses into a final outcome.

##### Important architectural patterns and design principles
- Modularity – Each of the Agents, Functions, and Agencies are individually encapsulated, which makes it easy to extend or modify behavior.
- Separation of concerns – Configuration, AI communication, function execution, and orchestration (via agencies) are clearly separated.
- Streaming responses – Emphasize the interactive, incremental data flow through streaming blocks.
- Reusable patterns – Especially within agencies (e.g., Supervisor and Workflow), show how multi-agent coordination is achieved.

##### Final checklist
- Each component (Agent, Function, Agency, Configuration, Helpers) should be clearly labeled.
- Incorporate annotations for design patterns such as Supervisor or Workflow where appropriate.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Interaction Layer
    User["User/Application"]:::interaction

    %% Core Modules Subgraph
    subgraph "Core Modules"
        Agent["Agent: Bristow::Agent"]:::core
        Function["Function: Bristow::Function"]:::core
        Agency["Agency: Bristow::Agency"]:::core
        Config["Configuration: Bristow::Configuration"]:::core
    end

    %% Supporting Modules Subgraph
    subgraph "Supporting Modules"
        Helpers["Helpers & Delegates"]:::support
        Terminations["Terminations"]:::support
    end

    %% External Dependency
    API["OpenAI API"]:::external

    %% Detailed Agencies subgraph (inside or connected to Agency)
    subgraph "Agencies"
        Supervisor["Supervisor Agency"]:::core
        Workflow["Workflow Agency"]:::core
    end

    %% Data Flow
    User -->|"initiates chat"| Agent
    Agent -->|"calls OpenAI"| API
    Agent -->|"invokes"| Function
    Function -->|"returns result"| Agent
    Agent -->|"delegates task"| Agency
    Agency -->|"coordinates with"| Supervisor
    Agency -->|"coordinates workflow with"| Workflow

    %% Configuration and Helpers influence core modules
    Config ---|"configures"| Agent
    Config ---|"configures"| Function
    Helpers ---|"assists"| Agent
    Terminations ---|"monitors"| Agent

    %% Styles
    classDef core fill:#f4d03f,stroke:#873600,stroke-width:2px;
    classDef external fill:#85c1e9,stroke:#1b4f72,stroke-width:2px;
    classDef interaction fill:#d5f5e3,stroke:#196f3d,stroke-width:2px;
    classDef support fill:#fad7a0,stroke:#935116,stroke-width:2px;

    %% Click Events for Core Modules
    click Agent "https://github.com/andrewhampton/bristow/blob/main/lib/bristow/agent.rb"
    click Agent "https://github.com/andrewhampton/bristow/tree/main/lib/bristow/agents/"
    click Function "https://github.com/andrewhampton/bristow/blob/main/lib/bristow/function.rb"
    click Function "https://github.com/andrewhampton/bristow/blob/main/lib/bristow/functions/delegate.rb"
    click Agency "https://github.com/andrewhampton/bristow/blob/main/lib/bristow/agency.rb"
    click Supervisor "https://github.com/andrewhampton/bristow/blob/main/lib/bristow/agencies/supervisor.rb"
    click Workflow "https://github.com/andrewhampton/bristow/blob/main/lib/bristow/agencies/workflow.rb"
    click Config "https://github.com/andrewhampton/bristow/blob/main/lib/bristow/configuration.rb"
    
    %% Click Events for Supporting Modules
    click Helpers "https://github.com/andrewhampton/bristow/tree/main/lib/bristow/helpers/"
    click Terminations "https://github.com/andrewhampton/bristow/blob/main/lib/bristow/termination.rb"
    click Terminations "https://github.com/andrewhampton/bristow/tree/main/lib/bristow/terminations/"
```
