Building AI agents, atomically
Add agents.md
KennyVaneetvelde50941533581f
diff --git a/agents.md b/agents.mdnew file mode 100644index 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