# chain-ml/council architecture

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

- Interactive diagram: https://gitdiagram.com/chain-ml/council
- Repository: https://github.com/chain-ml/council

## Overview

##### Main Components
- LLM Interface Module – Represented by the “council/llm” directory and its subdirectories. This includes the base classes, configurations, message formatting, and integrations with provider-specific implementations (e.g., OpenAI, Anthropic, Gemini, Groq, Ollama).
- Agents and Agent Tests – Under “council/agents” and “council/agent_tests”. These represent the autonomous agents that carry out tasks using LLM interactions.
- Chains – In “council/chains”. This module relates to constructing multi-step workflows (chains) that the agents execute.
- Contexts – In “council/contexts”. This manages runtime contexts such as conversation histories, budgets, logging, and execution contexts. It’s critical for maintaining state and enforcing controls.
- Controllers – Under “council/controllers”. They orchestrate how agents and chains are executed and provide control flow capabilities.
- Evaluators & Scorers – Found in “council/evaluators” and “council/scorers”. These components are responsible for evaluating LLM outputs, scoring responses, and ensuring quality.
- Filters – In “council/filters”. They perform pre- and post-processing to clean or filter out unwanted content.
- Skills – Under “council/skills”. This directory encapsulates additional functionalities (like Google search integration, Python coding skills, Wikipedia queries, etc.) that extend the core agent capabilities.
- Runners – Located in “council/runners”. They execute different control flow logic, such as loop runners, conditional and parallel execution strategies.
- Prompts – In “council/prompt”. This module handles prompt building, dataset management, and configuration of LLM prompt templates.
- Auxiliary Modules – “council/utils” for helper utilities and “council/mocks” for testing support.

##### Establish Relationships and Interactions
- That Controllers drive the overall execution by managing both agents and chains, connecting to both.
- That Filters wrap around LLM responses or agent outputs before final delivery.
- For Skills, show that they extend agents’ capabilities, with connections both toward the Agents module and the external service integrations.
- The Prompts module should be presented as the preparatory layer that feeds into the LLM interface when constructing requests.

##### Architectural Patterns and Design Principles
- Clearly separate concerns by grouping similar modules together (for example, all control-flow related components – controllers, runners, contexts – on one side and the LLM/provider abstractions on the other).
- Modular design, illustrating the Strategy pattern used for choosing the appropriate LLM provider dynamically.
- Use dependency inversion concepts where core modules (like Agents and Controllers) depend on abstract interfaces (as seen in the base classes in many packages) rather than concrete implementations.
- Elements of enterprise-grade monitoring and error handling, as indicated by the built-in retry mechanisms and monitoring modules.

##### Relevant Technologies and Frameworks
- That it’s a Python-based project.
- That integrations with external LLM providers (OpenAI, Anthropic, etc.) are performed through dedicated provider modules.
- Mention the use of configuration files (YAML in docs/data/configs) that help in parameterizing the LLM calls.
- Testing frameworks and CI/CD integration (GitHub Workflows like linting, testing, docs build) as ancillary but important for overall system integrity.

##### Additional Elements
- Use callout annotations to indicate how configuration, error handling, and retry mechanisms operate within modules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Modules: LLM & Agents
    subgraph "LLM & Agents"
        Agents["Agents"]:::core
        AgentTests["Agent Tests"]:::aux
        LLMInterface["LLM Interface Module"]:::core
        Prompts["Prompts"]:::extension
    end

    %% Workflows & Control
    subgraph "Workflows & Control"
        Chains["Chains"]:::core
        Controllers["Controllers"]:::core
        Contexts["Contexts"]:::core
        Runners["Runners"]:::aux
    end

    %% Evaluation and Filtering
    subgraph "Evaluation and Filtering"
        Evaluators["Evaluators"]:::evaluation
        Scorers["Scorers"]:::evaluation
        Filters["Filters"]:::extension
    end

    %% Extensions & Auxiliary
    subgraph "Extensions & Auxiliary"
        Skills["Skills"]:::extension
        Utilities["Utilities"]:::aux
        Mocks["Mocks"]:::aux
    end

    %% Relationships and Interactions
    Agents -->|"requests"| LLMInterface
    LLMInterface -->|"response"| Agents

    Prompts -->|"buildsRequest"| LLMInterface

    Agents <-->|"triggersWorkflow"| Chains

    Controllers -->|"orchestrates"| Agents
    Controllers -->|"orchestrates"| Chains
    Controllers -->|"manages"| Contexts

    Contexts -->|"providesState"| Agents
    Contexts -->|"providesContext"| Chains

    LLMInterface -->|"evaluatedBy"| Evaluators
    LLMInterface -->|"evaluatedBy"| Scorers

    LLMInterface -->|"filteredBy"| Filters
    Filters -->|"refines"| Agents

    Skills <-->|"enhances"| Agents

    Runners -->|"executesFlow"| Controllers

    AgentTests -->|"tests"| Agents

    Utilities -->|"supports"| Agents
    Utilities -->|"supports"| Controllers
    Mocks -->|"simulates"| Agents

    %% Click Events
    click LLMInterface "https://github.com/chain-ml/council/tree/main/council/llm"
    click Agents "https://github.com/chain-ml/council/tree/main/council/agents"
    click AgentTests "https://github.com/chain-ml/council/tree/main/council/agent_tests"
    click Chains "https://github.com/chain-ml/council/tree/main/council/chains"
    click Contexts "https://github.com/chain-ml/council/tree/main/council/contexts"
    click Controllers "https://github.com/chain-ml/council/tree/main/council/controllers"
    click Evaluators "https://github.com/chain-ml/council/tree/main/council/evaluators"
    click Scorers "https://github.com/chain-ml/council/tree/main/council/scorers"
    click Filters "https://github.com/chain-ml/council/tree/main/council/filters"
    click Skills "https://github.com/chain-ml/council/tree/main/council/skills"
    click Runners "https://github.com/chain-ml/council/tree/main/council/runners"
    click Prompts "https://github.com/chain-ml/council/tree/main/council/prompt"
    click Utilities "https://github.com/chain-ml/council/tree/main/council/utils"
    click Mocks "https://github.com/chain-ml/council/tree/main/council/mocks"

    %% Styles
    classDef core fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef evaluation fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef extension fill:#C3E6CB,stroke:#117A65,stroke-width:2px;
    classDef aux fill:#D7BDE2,stroke:#6C3483,stroke-width:2px;
```
