Skip to content

Building AI agents, atomically

Add agents.md

KennyVaneetvelde50941533581f
diff --git a/agents.md b/agents.md
new file mode 100644
index 0000000..5464272
--- /dev/null
+++ b/agents.md
@@ -0,0 +1,357 @@
+# Atomic Agents Monorepo
+
+## What is this Repository?
+
+**atomic-monorepo** is the development repository for **Atomic Agents**, a lightweight and modular Python framework for building Agentic AI applications. The framework is built around the principle of **atomicity** - creating single-purpose, reusable, and composable components for AI pipelines.
+
+### Core Philosophy
+
+Atomic Agents bridges the gap between flexibility and reliability in production AI applications by providing:
+
+- **Predictable AI Behavior**: Controlled, schema-driven agent construction vs. autonomous but unpredictable multi-agent systems
+- **Modular Development**: Build AI applications using familiar software engineering principles (LEGO-like composability)
+- **Type Safety**: Consistent input/output contracts through Pydantic schemas
+- **Developer Control**: Full visibility and control over AI behavior with no hidden abstractions
+
+Built on top of [Instructor](https://github.com/jxnl/instructor) (for structured LLM outputs) and [Pydantic](https://docs.pydantic.dev/) (for data validation).
+
+---
+
+## Monorepo Structure
+
+This repository contains four main packages/projects:
+
+```
+atomic-monorepo/
+├── atomic-agents/ # Core framework library (main package)
+├── atomic-assembler/ # CLI tool for managing components
+├── atomic-examples/ # Example projects and use cases
+├── atomic-forge/ # Collection of downloadable tools
+├── docs/ # Sphinx documentation
+├── guides/ # Development guides
+├── .github/workflows/ # CI/CD pipelines
+├── pyproject.toml # Poetry configuration
+└── README.md # Main documentation
+```
+
+---
+
+## Package Details
+
+### 1. atomic-agents/ - Core Framework
+
+**Published as:** `atomic-agents` on PyPI
+**Current Version:** 2.2.2
+**Purpose:** Main Python package containing all core framework components
+
+**Key Components:**
+- `agents/` - AtomicAgent class and agent configuration
+- `base/` - Base abstractions (BaseIOSchema, BaseTool, BasePrompt, BaseResource)
+- `context/` - Chat history and system prompt generation
+- `connectors/` - External integrations (MCP support)
+- `lib/` - Extended library components (components, factories, utils)
+- `memory/` - Memory management systems
+- `prompting/` - Prompt engineering utilities
+- `services/` - Service integrations
+
+**Installation:**
+```bash
+pip install atomic-agents
+```
+
+### 2. atomic-assembler/ - CLI Tool
+
+**Command:** `atomic`
+**Purpose:** Terminal UI application for browsing, downloading, and managing tools from atomic-forge
+**Built With:** [Textual](https://textual.textualize.io/) (TUI framework)
+
+**Features:**
+- Interactive tool exploration
+- Download tools directly into your project
+- Manage tool dependencies
+
+**Usage:**
+```bash
+atomic # Launch interactive TUI
+```
+
+### 3. atomic-examples/ - Example Projects
+
+**Purpose:** Complete, runnable example implementations demonstrating framework capabilities
+
+**Available Examples:**
+- `quickstart/` - Basic getting started examples
+- `deep-research/` - Research agent implementations
+- `web-search-agent/` - Web search integration
+- `rag-chatbot/` - RAG (Retrieval Augmented Generation)
+- `youtube-summarizer/` - Video transcript summarization
+- `orchestration-agent/` - Multi-agent orchestration patterns
+- `mcp-agent/` - Model Context Protocol integration
+- `fastapi-memory/` - API with memory/state management
+- And 5+ more examples...
+
+Each example is self-contained and demonstrates specific patterns and capabilities.
+
+### 4. atomic-forge/ - Tool Repository
+
+**Not a Python package** - This is a downloadable tool collection that users integrate into their projects.
+
+**Philosophy:** Tools are NOT bundled with the framework. Instead, users download individual tools for full control and customization.
+
+**Available Tools:**
+- `calculator/` - Mathematical computation tool
+- `searxng_search/` - Privacy-focused search integration
+- `tavily_search/` - Tavily API search tool
+- `webpage_scraper/` - Web scraping capabilities
+- `youtube_transcript_scraper/` - YouTube transcript extraction
+
+**Benefits:**
+- Only install what you need (reduces dependency bloat)
+- Full control to modify tools for your specific use case
+- Tools become part of your codebase (no black boxes)
+
+---
+
+## Core Architecture
+
+### Agent Anatomy
+
+Every Atomic Agent consists of:
+
+1. **System Prompt** - Defines agent behavior and purpose
+2. **Input Schema** (Pydantic model) - Validates and structures input
+3. **Output Schema** (Pydantic model) - Ensures consistent output format
+4. **Chat History** - Maintains conversation context
+5. **Context Providers** - Injects dynamic runtime context
+6. **Tools** (optional) - Function calling capabilities
+
+### Schema-Driven Development
+
+All data flows through typed Pydantic schemas:
+
+```python
+from atomic_agents.base import BaseIOSchema
+from pydantic import Field
+
+class CustomOutputSchema(BaseIOSchema):
+ chat_message: str = Field(..., description="The response message")
+ suggested_questions: list[str] = Field(..., description="Follow-up questions")
+```
+
+### Composability Pattern
+
+Agents can be chained by connecting output schemas to input schemas:
+
+```
+Agent A (OutputSchemaA) → Agent B (InputSchemaB) → Agent C (OutputSchemaC)
+```
+
+This creates predictable data flow pipelines with type safety at each step.
+
+### Context Providers
+
+Dynamic context injection pattern allows runtime enhancement of prompts without modifying agent code:
+
+```python
+context_provider = CustomContextProvider()
+agent = AtomicAgent(
+ system_prompt=prompt,
+ input_schema=InputSchema,
+ output_schema=OutputSchema,
+ context_providers=[context_provider] # Inject runtime context
+)
+```
+
+### Model Context Protocol (MCP)
+
+Full support for MCP enables connection to external tools and resources through standardized interfaces:
+
+- Connect to MCP servers
+- Use remote tools as if they were local
+- Access external resources seamlessly
+- Standard protocol for tool integration
+
+---
+
+## Technologies & Frameworks
+
+### Core Stack
+
+- **Language:** Python 3.12+
+- **AI/LLM:** Instructor (supports multiple providers)
+- **Data Validation:** Pydantic v2
+- **CLI Framework:** Textual (TUI), Rich (terminal formatting)
+- **Testing:** pytest with coverage
+- **Documentation:** Sphinx + MyST + ReadTheDocs theme
+- **Build System:** Poetry
+
+### LLM Provider Compatibility
+
+Through Instructor, Atomic Agents supports all major LLM providers:
+
+- OpenAI
+- Anthropic (Claude)
+- Groq
+- Mistral
+- Cohere
+- Google Gemini
+- Ollama (local models)
+- Any Instructor-compatible provider
+
+### Execution Modes
+
+- **Synchronous:** `agent.run(input_data)`
+- **Asynchronous:** `await agent.run_async(input_data)`
+- **Streaming:** `agent.run_stream(input_data)` and `agent.run_async_stream(input_data)`
+
+---
+
+## Development Setup
+
+### Prerequisites
+
+- Python ≥3.12, <4.0
+- Poetry (package manager)
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/BrainBlend-AI/atomic-agents.git
+cd atomic-monorepo
+
+# Install dependencies
+poetry install
+
+# Activate virtual environment
+poetry shell
+```
+
+### Development Commands
+
+```bash
+# Code formatting
+poetry run black atomic-agents atomic-assembler atomic-examples atomic-forge
+
+# Linting
+poetry run flake8 --extend-exclude=.venv atomic-agents atomic-assembler atomic-examples atomic-forge
+
+# Testing
+poetry run pytest --cov=atomic_agents atomic-agents
+
+# Build documentation
+cd docs && make html
+```
+
+### Code Quality Standards
+
+- **Formatter:** Black (line length: 127)
+- **Linter:** Flake8
+- **Testing:** pytest with coverage tracking
+- **Type Safety:** Pydantic runtime validation
+
+### CI/CD
+
+Two GitHub Actions workflows:
+
+1. **code-quality.yml** - Runs Black, Flake8, and pytest on push/PR to main/v2.0
+2. **docs.yml** - Builds and deploys Sphinx documentation
+
+---
+
+## Key Design Patterns
+
+### 1. Single Responsibility Principle
+Each component does one thing well. Agents, tools, and schemas are atomic units of functionality.
+
+### 2. Type-Safe Contracts
+Pydantic schemas enforce contracts at runtime, catching errors before they propagate.
+
+### 3. Composition Over Inheritance
+Build complex behaviors by composing simple agents rather than deep inheritance hierarchies.
+
+### 4. Explicit Over Implicit
+No hidden magic - full control over what your agent does and how it does it.
+
+### 5. Separation of Concerns
+- **Prompts** define behavior
+- **Schemas** define data contracts
+- **Tools** define capabilities
+- **Context Providers** inject runtime information
+
+---
+
+## Version 2.0+ Features
+
+Recent improvements include:
+
+- Cleaner imports (removed `.lib` from import paths)
+- Renamed classes for clarity (`BaseAgent` → `AtomicAgent`)
+- Better type safety with generic type parameters
+- Enhanced streaming capabilities
+- Improved module organization
+- Backward compatibility layer for v1.x migration
+
+---
+
+## Community & Resources
+
+### Documentation
+- **Main Docs:** https://brainblend-ai.github.io/atomic-agents/
+- **Repository:** https://github.com/BrainBlend-AI/atomic-agents
+- **PyPI:** https://pypi.org/project/atomic-agents/
+
+### Community
+- **Discord:** https://discord.gg/J3W9b5AZJR
+- **Subreddit:** /r/AtomicAgents
+
+### Learning Resources
+- YouTube overview and quickstart videos
+- Medium articles on philosophy and patterns
+- Comprehensive examples in `atomic-examples/`
+- Interactive tutorials in documentation
+
+---
+
+## Quick Start
+
+```python
+from atomic_agents import AtomicAgent
+from atomic_agents.base import BaseIOSchema
+from pydantic import Field
+
+# Define schemas
+class InputSchema(BaseIOSchema):
+ query: str = Field(..., description="User's question")
+
+class OutputSchema(BaseIOSchema):
+ answer: str = Field(..., description="Agent's response")
+ confidence: float = Field(..., description="Confidence score 0-1")
+
+# Create agent
+agent = AtomicAgent(
+ system_prompt="You are a helpful assistant. Provide accurate answers.",
+ input_schema=InputSchema,
+ output_schema=OutputSchema,
+ model="gpt-4o-mini",
+)
+
+# Run agent
+result = agent.run(InputSchema(query="What is atomic computing?"))
+print(result.answer)
+print(f"Confidence: {result.confidence}")
+```
+
+---
+
+## Philosophy Summary
+
+Atomic Agents emphasizes:
+
+1. **Developer Experience** - Clean APIs, type safety, familiar patterns
+2. **Modularity** - LEGO-like composability of components
+3. **Control** - Full visibility and control over AI behavior
+4. **Production Readiness** - Schema validation, testing, CI/CD
+5. **Community** - Active development with examples, docs, and support
+
+This framework is designed for developers who want to build **reliable, maintainable AI applications** using standard software engineering practices, rather than dealing with unpredictable autonomous agent systems.
\ No newline at end of file