# bingreeky/maas architecture

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

- Interactive diagram: https://gitdiagram.com/bingreeky/maas
- Repository: https://github.com/bingreeky/maas

## Overview

##### Project type and purpose
- MaAS is a research‐oriented Python library and CLI tool for “Multi-agent Architecture Search via Agentic Supernet.”
- It dynamically samples and optimizes multi-agent system architectures for diverse user queries, leveraging large language models (LLMs) and feedback.
- It includes experiment harnesses for benchmarks (GSM8K, HumanEval, MATH) and integrates with multiple LLM providers, retrieval backends, and tool plugins.

##### File structure
- Top-level directories:
- maas/                ← core library
- examples/maas/       ← experiment entrypoints (optimize.py)
- config/ & .maas/     ← configuration files (YAML)
- assets/              ← figures for README
- maas/ext/maas/       ← benchmark scripts & models
- maas/actions/        ← atomic “agent” behaviors (plugins)
- maas/provider/       ← LLM API adapters & registry
- maas/rag/            ← retrieval-augmented generation engine
- maas/strategy/       ← search-space, planner, solver logic
- maas/tools/          ← tool invocation (email, TTS, browser, ML preprocessing)
- Key config files: config2.yaml, browser_config.py, llm_config.py, redis_config.py, etc.
- Entry point: setup.py + requirements.txt for packaging; examples invoke `python -m examples.maas.optimize`.

##### README for additional insights
- Two core components:
a. Agentic Supernet (probabilistic distribution over agent pipelines)
b. Controller that samples sub-networks per query and updates both distribution and operators via feedback.
- External dependencies: downloaded datasets in maas/ext/maas/data; API keys for LLM providers.
- Benchmarks orchestrated by examples/maas/optimize.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Experiment Harness
    subgraph "Experiment Harness" 
        direction TB
        BenchmarkRunner["Benchmark Runner"]:::experiment
        OptimizeScript["examples/maas/optimize.py"]:::experiment
        GSM8K["gsm8k.py"]:::experiment
        HumanEval["humaneval.py"]:::experiment
        MATH["math.py"]:::experiment
    end

    %% Core Engine
    subgraph "Core Engine" 
        direction TB
        UserInput["User / CLI / API Input"]:::external
        ConfigLoader["Configuration Loader"]:::config
        Controller["Controller & Sampler"]:::core
        Supernet["Agentic Supernet"]:::core
        SampledSystem["Sampled Multi-Agent System"]:::core
        FeedbackLoop["Feedback & Optimization Loop"]:::core
    end

    %% Plugins
    subgraph "Plugins & Providers" 
        direction TB
        subgraph "Actions" 
            direction TB
            ActionGraph["action_graph.py"]:::plugin
            ActionNode["action_node.py"]:::plugin
            ActionRegistry["action_outcls_registry.py"]:::plugin
        end
        subgraph "LLM Providers"
            direction TB
            ProviderRegistry["llm_provider_registry.py"]:::plugin
            OpenAI["openai_api.py"]:::plugin
            Anthropic["anthropic_api.py"]:::plugin
            Azure["azure_openai_api.py"]:::plugin
            Bedrock["bedrock_provider.py"]:::plugin
        end
        subgraph "RAG Engine"
            direction TB
            RAGInterface["interface.py"]:::plugin
            SimpleEngine["simple.py"]:::plugin
            FlareEngine["flare.py"]:::plugin
            EmbeddingFactory["embedding.py"]:::plugin
            RetrieverFactory["retriever.py"]:::plugin
            FAISS["faiss_retriever.py"]:::plugin
            Chroma["chroma_retriever.py"]:::plugin
        end
        subgraph "Tools & External Services"
            direction TB
            ToolRegistry["tool_registry.py"]:::plugin
            TTS["azure_tts.py"]:::plugin
            Browser["web_browser_engine_playwright.py"]:::plugin
            EmailLib["email_login.py"]:::plugin
            EmbeddingTool["openai_text_to_embedding.py"]:::plugin
        end
    end

    %% Utilities
    subgraph "Utilities & DI" 
        direction TB
        DI["di_graph_repository.py"]:::util
        YAML["yaml_model.py"]:::util
        MermaidUtil["mermaid.py"]:::util
        RedisUtil["redis.py"]:::util
        S3Util["s3.py"]:::util
        GraphRepo["graph_repository.py"]:::util
    end

    %% Core Relationships
    UserInput -->|"load configs"| ConfigLoader
    ConfigLoader -->|"initialize"| Controller
    Controller -->|"manage distribution"| Supernet
    Supernet -->|"sample topology"| SampledSystem
    SampledSystem -->|"execute actions"| ActionGraph
    ActionGraph --> ActionNode
    ActionNode -->|"invoke"| ActionRegistry
    ActionRegistry -->|"calls"| ProviderRegistry
    ActionRegistry -->|"calls"| RAGInterface
    ActionRegistry -->|"calls"| ToolRegistry
    ProviderRegistry -->|"select adapter"| OpenAI
    ProviderRegistry --> Anthropic
    ProviderRegistry --> Azure
    ProviderRegistry --> Bedrock
    RAGInterface --> SimpleEngine
    RAGInterface --> FlareEngine
    SimpleEngine --> EmbeddingFactory
    FlareEngine --> RetrieverFactory
    RetrieverFactory --> FAISS
    RetrieverFactory --> Chroma
    ToolRegistry --> TTS
    ToolRegistry --> Browser
    ToolRegistry --> EmailLib
    ToolRegistry --> EmbeddingTool
    SampledSystem -->|"feedback data"| FeedbackLoop
    FeedbackLoop -->|"update distribution"| Controller

    %% Experiment Flow
    BenchmarkRunner --> OptimizeScript
    OptimizeScript --> Controller
    BenchmarkRunner --> GSM8K
    BenchmarkRunner --> HumanEval
    BenchmarkRunner --> MATH
    GSM8K --> FeedbackLoop
    HumanEval --> FeedbackLoop
    MATH --> FeedbackLoop

    %% Utilities usage
    DI --> Controller
    YAML --> ConfigLoader
    MermaidUtil --> Controller
    RedisUtil --> FeedbackLoop
    S3Util --> FeedbackLoop
    GraphRepo --> Supernet

    %% Click Events
    click OptimizeScript "https://github.com/bingreeky/maas/blob/main/examples/maas/optimize.py"
    click GSM8K "https://github.com/bingreeky/maas/blob/main/maas/ext/maas/benchmark/gsm8k.py"
    click HumanEval "https://github.com/bingreeky/maas/blob/main/maas/ext/maas/benchmark/humaneval.py"
    click MATH "https://github.com/bingreeky/maas/blob/main/maas/ext/maas/benchmark/math.py"
    click BenchmarkRunner "https://github.com/bingreeky/maas/blob/main/maas/ext/maas/benchmark/benchmark.py"
    click ConfigLoader "https://github.com/bingreeky/maas/blob/main/config/config2.yaml"
    click ConfigLoader "https://github.com/bingreeky/maas/blob/main/.maas/config2.yaml"
    click ConfigLoader "https://github.com/bingreeky/maas/blob/main/maas/configs/llm_config.py"
    click ConfigLoader "https://github.com/bingreeky/maas/blob/main/maas/configs/redis_config.py"
    click ConfigLoader "https://github.com/bingreeky/maas/blob/main/maas/configs/browser_config.py"
    click DI "https://github.com/bingreeky/maas/blob/main/maas/utils/di_graph_repository.py"
    click Supernet "https://github.com/bingreeky/maas/blob/main/maas/strategy/search_space.py"
    click Supernet "https://github.com/bingreeky/maas/blob/main/maas/strategy/base.py"
    click Supernet "https://github.com/bingreeky/maas/blob/main/maas/strategy/solver.py"
    click Supernet "https://github.com/bingreeky/maas/blob/main/maas/strategy/planner.py"
    click Controller "https://github.com/bingreeky/maas/blob/main/maas/ext/maas/models/controller.py"
    click Controller "https://github.com/bingreeky/maas/blob/main/maas/ext/maas/models/utils.py"
    click ActionGraph "https://github.com/bingreeky/maas/blob/main/maas/actions/action_graph.py"
    click ActionNode "https://github.com/bingreeky/maas/blob/main/maas/actions/action_node.py"
    click ActionRegistry "https://github.com/bingreeky/maas/blob/main/maas/actions/action_outcls_registry.py"
    click ProviderRegistry "https://github.com/bingreeky/maas/blob/main/maas/provider/llm_provider_registry.py"
    click OpenAI "https://github.com/bingreeky/maas/blob/main/maas/provider/openai_api.py"
    click Anthropic "https://github.com/bingreeky/maas/blob/main/maas/provider/anthropic_api.py"
    click Azure "https://github.com/bingreeky/maas/blob/main/maas/provider/azure_openai_api.py"
    click Bedrock "https://github.com/bingreeky/maas/blob/main/maas/provider/bedrock/bedrock_provider.py"
    click RAGInterface "https://github.com/bingreeky/maas/blob/main/maas/rag/interface.py"
    click SimpleEngine "https://github.com/bingreeky/maas/blob/main/maas/rag/engines/simple.py"
    click FlareEngine "https://github.com/bingreeky/maas/blob/main/maas/rag/engines/flare.py"
    click EmbeddingFactory "https://github.com/bingreeky/maas/blob/main/maas/rag/factories/embedding.py"
    click RetrieverFactory "https://github.com/bingreeky/maas/blob/main/maas/rag/factories/retriever.py"
    click FAISS "https://github.com/bingreeky/maas/blob/main/maas/rag/retrievers/faiss_retriever.py"
    click Chroma "https://github.com/bingreeky/maas/blob/main/maas/rag/retrievers/chroma_retriever.py"
    click ToolRegistry "https://github.com/bingreeky/maas/blob/main/maas/tools/tool_registry.py"
    click TTS "https://github.com/bingreeky/maas/blob/main/maas/tools/azure_tts.py"
    click Browser "https://github.com/bingreeky/maas/blob/main/maas/tools/web_browser_engine_playwright.py"
    click EmailLib "https://github.com/bingreeky/maas/blob/main/maas/tools/libs/email_login.py"
    click EmbeddingTool "https://github.com/bingreeky/maas/blob/main/maas/tools/openai_text_to_embedding.py"

    %% Styles
    classDef core fill:#f9f,stroke:#333,stroke-width:1px
    classDef plugin fill:#bbf,stroke:#333,stroke-width:1px
    classDef util fill:#bfb,stroke:#333,stroke-width:1px
    classDef config fill:#ffb,stroke:#333,stroke-width:1px
    classDef experiment fill:#fb8,stroke:#333,stroke-width:1px
    classDef external fill:#fdd,stroke:#333,stroke-width:1px
```
