# brainblend-ai/atomic-agents architecture

> Architecture diagram of the GitHub repository brainblend-ai/atomic-agents, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/brainblend-ai/atomic-agents
- Repository: https://github.com/brainblend-ai/atomic-agents

## Overview

##### Project Type and Purpose
- Project type: A Python‐based, open‐source, modular AI‐agent framework delivered as a monorepo.
- Purpose: Provide a lightweight, composable “atomic” framework for building AI agents and pipelines, plus a CLI (“Atomic Assembler”) for installing and managing tools, a suite of example applications, and a curated tool registry (“Atomic Forge”).

##### File Structure
Top‐level directories:
- atomic-agents/ – Core library
- atomic-assembler/ – CLI application
- atomic-examples/ – Sample projects
- atomic-forge/ – Curated tool implementations
- docs/ & guides/ – Documentation site and developer guide
- scripts/, setup.py, pyproject.toml, requirements.txt – Build, CI, packaging

Inside atomic-agents/:
- atomic_agents/agents – BaseAgent classes & configs
- atomic_agents/lib/components – SystemPromptGenerator, AgentMemory, Context Providers
- atomic_agents/lib/factories – Tool‐factory, schema transformers
- atomic_agents/lib/utils – Message formatting
- tests/ – Unit tests for agents, components, factories, utils

atomic-assembler/:
- app.py, main.py – CLI entrypoints
- screens/, widgets/ – TUI layers (menus, explorers)
- utils.py, color_utils.py – CLI helpers

atomic-examples/:
- Subfolders for specific use cases (quickstart, RAG, orchestration, multimodal, etc.)

atomic-forge/:
- tools/ – Individual tool packages (calculator, searxng_search, etc.)
- Each tool: own tests, pyproject.toml, implementation

##### Extract Architectural Insights from README
- Core library (atomic-agents) is framework that wires together:
– System prompts
– Input/output schemas (Pydantic)
– Memory components
– Context Providers
– Agent execution via Instructor clients (OpenAI, Groq, etc.)
– Plugin tooling via atomic-forge
- CLI (atomic-assembler) is a menu‐based interface to download and scaffold tools/agents.
- Examples demonstrate typical pipelines: multi‐provider chatbots, RAG, orchestration, web search, summarization.

a. Main Components
1. Presentation / UX Layer
– atomic-assembler CLI (menus, file explorers, interactive screens)
– Example scripts / entrypoints in atomic-examples/
2. Core Framework (atomic-agents)
– BaseAgent & BaseIOSchema
– SystemPromptGenerator & ContextProviders
– AgentMemory
– Factories (ToolFactory, SchemaTransformer)
– Utils (format_tool_message)
3. Tool Registry (atomic-forge)
– Tools implementing input_schema, output_schema, perform()
4. External Services
– LLM Providers via Instructor (OpenAI, Groq, Anthropic, etc.)
– Third‐party APIs (search engines, web scraping endpoints)
5. Data Models & Storage
– Pydantic models for schema validation
– In‐memory conversation history (AgentMemory)
– Optional: external storage (not shown in tree)

b. Relationships & Data Flows
- User invokes CLI or runs an example → CLI/Script calls BaseAgent.run()
- BaseAgent assembles prompt via SystemPromptGenerator + registered ContextProviders + Memory
- Agent sends prompt to LLM client (Instructor) and receives response
- Response parsed into Output Schema (Pydantic)
- Optionally, agent invokes Tools from atomic-forge via ToolFactory → Tool input schema → external API call → return output schema → integrated into agent’s next step
- AgentMemory records conversation turns for future context
- Example scripts chain multiple agents/tools by matching output_schema to next input_schema

c. Architectural Patterns & Principles
– Modular / Plugin Architecture: core framework + external tools + context providers
– Factory Pattern: decouple tool instantiation (MCP Tool Factory, Schema Transformer)
– Dependency Inversion: abstract LLM client (Instructor) behind BaseAgentConfig.client
– Schema‐Driven Design: enforce strict input/output contracts via Pydantic
– Monorepo for cohesive distribution of library, CLI, examples, and tools

d. Key Technologies & Frameworks
– Python 3.x
– Pydantic for schema validation
– Instructor library as LLM client abstraction
– Poetry / pyproject.toml & setup.py for packaging
– pytest for testing
– Typer or a similar TUI library in atomic-assembler (menus/widgets)
– GitHub Actions for CI (code‐quality, docs generation)

##### Final Advice
– Capture both static structure (modules and packages) and dynamic flow (runtime prompt assembly and execution).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation / UX Layer
    subgraph "Presentation / UX Layer"
        CLI["Atomic Assembler CLI"]:::cli
        EXAMPLES["Example Scripts"]:::examples
    end

    %% Core Framework
    subgraph "Core Framework (atomic-agents)"
        BA["BaseAgent"]:::core
        BI["BaseIOSchema"]:::core
        BT["BaseTool"]:::core
        SPG["SystemPromptGenerator"]:::core
        AM["AgentMemory"]:::core
        FACT["Factories"]:::core
        UTIL["Utils"]:::core
    end

    %% Tool Registry
    subgraph "Tool Registry (atomic-forge)"
        TOOL1["Calculator"]:::tool
        TOOL2["SearxNG Search"]:::tool
        TOOL3["Tavily Search"]:::tool
        TOOL4["Webpage Scraper"]:::tool
        TOOL5["YouTube Transcript Scraper"]:::tool
    end

    %% External Services
    subgraph "External Services"
        LLM["LLM Providers"]:::external
        API["3rd-Party APIs"]:::external
    end

    %% Flows
    User["User"]:::user
    User -->|"invoke CLI"| CLI
    User -->|"run example"| EXAMPLES

    CLI -->|"calls BaseAgent.run()"| BA
    EXAMPLES -->|"calls BaseAgent.run()"| BA

    BA -->|"assemble prompt"| SPG
    BA -->|"load context"| AM
    BA -.->|"optional plugin"| FACT
    SPG --> BI
    AM --> BI

    BI -->|"prompt JSON"| LLM
    LLM -->|"LLM response"| BI
    BI -->|"parsed response"| BA

    BA -->|"ToolFactory → instantiate"| FACT
    FACT -->|"Tool input schema"| TOOL1
    TOOL1 -->|"external call"| API
    API -->|"return output schema"| TOOL1
    TOOL1 -->|"Tool output schema"| BA

    BA -->|"records turn"| AM
    BA -->|"format messages"| UTIL

    %% Example chaining (collapsed)
    EXAMPLES -->|"chain agents/tools"| BA

    %% Click Events
    click BA "https://github.com/brainblend-ai/atomic-agents/blob/main/atomic-agents/atomic_agents/agents/base_agent.py"
    click BI "https://github.com/brainblend-ai/atomic-agents/blob/main/atomic-agents/atomic_agents/lib/base/base_io_schema.py"
    click BT "https://github.com/brainblend-ai/atomic-agents/blob/main/atomic-agents/atomic_agents/lib/base/base_tool.py"
    click SPG "https://github.com/brainblend-ai/atomic-agents/blob/main/atomic-agents/atomic_agents/lib/components/system_prompt_generator.py"
    click AM "https://github.com/brainblend-ai/atomic-agents/blob/main/atomic-agents/atomic_agents/lib/components/agent_memory.py"
    click FACT "https://github.com/brainblend-ai/atomic-agents/blob/main/atomic-agents/atomic_agents/lib/factories/mcp_tool_factory.py"
    click FACT "https://github.com/brainblend-ai/atomic-agents/blob/main/atomic-agents/atomic_agents/lib/factories/schema_transformer.py"
    click FACT "https://github.com/brainblend-ai/atomic-agents/blob/main/atomic-agents/atomic_agents/lib/factories/tool_definition_service.py"
    click UTIL "https://github.com/brainblend-ai/atomic-agents/blob/main/atomic-agents/atomic_agents/lib/utils/format_tool_message.py"
    click CLI "https://github.com/brainblend-ai/atomic-agents/blob/main/atomic-assembler/atomic_assembler/app.py"
    click CLI "https://github.com/brainblend-ai/atomic-agents/blob/main/atomic-assembler/atomic_assembler/main.py"
    click CLI "https://github.com/brainblend-ai/atomic-agents/blob/main/atomic-assembler/atomic_assembler/utils.py"
    click CLI "https://github.com/brainblend-ai/atomic-agents/blob/main/atomic-assembler/atomic_assembler/color_utils.py"
    click CLI "https://github.com/brainblend-ai/atomic-agents/blob/main/atomic-assembler/atomic_assembler/constants.py"
    click CLI "https://github.com/brainblend-ai/atomic-agents/tree/main/atomic-assembler/atomic_assembler/screens/"
    click CLI "https://github.com/brainblend-ai/atomic-agents/tree/main/atomic-assembler/atomic_assembler/widgets/"
    click TOOL1 "https://github.com/brainblend-ai/atomic-agents/blob/main/atomic-forge/tools/calculator/tool/calculator.py"
    click TOOL2 "https://github.com/brainblend-ai/atomic-agents/blob/main/atomic-forge/tools/searxng_search/tool/searxng_search.py"
    click TOOL3 "https://github.com/brainblend-ai/atomic-agents/blob/main/atomic-forge/tools/tavily_search/tool/tavily_search.py"
    click TOOL4 "https://github.com/brainblend-ai/atomic-agents/blob/main/atomic-forge/tools/webpage_scraper/tool/webpage_scraper.py"
    click TOOL5 "https://github.com/brainblend-ai/atomic-agents/blob/main/atomic-forge/tools/youtube_transcript_scraper/tool/youtube_transcript_scraper.py"

    %% Styles
    classDef core fill:#D0E6F6,stroke:#004E89,color:#000
    classDef tool fill:#D4F1BE,stroke:#0B6623,color:#000
    classDef examples fill:#FDEBD0,stroke:#D35400,color:#000
    classDef cli fill:#B8E0F9,stroke:#1B4F72,color:#000
    classDef external fill:#F0F0F0,stroke:#555,color:#000
    classDef user fill:#FFFFFF,stroke:#000,color:#000,stroke-dasharray: 5 5
```
