Building AI agents, atomically
Documentation improvements
KennyVaneetvelde671e9b35504f
diff --git a/docs/api/components.md b/docs/api/components.mdindex a3a8c60..df0cd18 100644--- a/docs/api/components.md+++ b/docs/api/components.md@@ -2,6 +2,45 @@## Agent Memory+The `AgentMemory` class manages conversation history and state for AI agents:++```python+from atomic_agents.lib.components.agent_memory import AgentMemory+from atomic_agents.lib.base.base_io_schema import BaseIOSchema++# Initialize memory with optional max messages+memory = AgentMemory(max_messages=10)++# Add messages with proper schemas+memory.add_message(+ role="assistant",+ content=BaseIOSchema(...)+)++# Access history+history = memory.get_history()++# Manage turns+memory.initialize_turn() # Start new turn+turn_id = memory.get_current_turn_id()++# Persistence+serialized = memory.dump() # Save to string+memory.load(serialized) # Load from string++# Create copy+new_memory = memory.copy()+```++Key features:+- Message history management with role-based messages+- Turn-based conversation tracking+- Support for multimodal content+- Serialization and deserialization+- Memory size management+- Deep copy functionality++For full API details:```{eval-rst}.. automodule:: atomic_agents.lib.components.agent_memory:members:@@ -12,6 +51,59 @@## System Prompt Generator+The `SystemPromptGenerator` creates structured system prompts for AI agents:++```python+from atomic_agents.lib.components.system_prompt_generator import (+ SystemPromptGenerator,+ SystemPromptContextProviderBase+)++# Create basic generator+generator = SystemPromptGenerator(+ background=[+ "You are a helpful AI assistant.",+ "You specialize in technical support."+ ],+ steps=[+ "1. Understand the user's request",+ "2. Analyze available information",+ "3. Provide clear solutions"+ ],+ output_instructions=[+ "Use clear, concise language",+ "Include step-by-step instructions",+ "Cite relevant documentation"+ ]+)++# Generate prompt+prompt = generator.generate_prompt()+```++### Context Providers++Create custom context providers by extending `SystemPromptContextProviderBase`:++```python+class CustomContextProvider(SystemPromptContextProviderBase):+ def __init__(self, title: str):+ super().__init__(title=title)+ self.data = {}++ def get_info(self) -> str:+ return f"Custom context: {self.data}"++# Use with generator+generator = SystemPromptGenerator(+ background=["You are a helpful AI assistant."],+ context_providers={+ "custom": CustomContextProvider("Custom Info")+ }+)+```++For full API details:```{eval-rst}.. automodule:: atomic_agents.lib.components.system_prompt_generator:members:diff --git a/docs/api/index.md b/docs/api/index.mdindex 05f3635..88cb6bb 100644--- a/docs/api/index.md+++ b/docs/api/index.md@@ -28,11 +28,22 @@ The agents module provides the base classes for creating AI agents:### Components-The components module contains building blocks for extending agent functionality:+The components module contains essential building blocks:-- `AgentMemory`: Manages conversation history and context-- `SystemPromptGenerator`: Creates dynamic system prompts-- `SystemPromptContextProvider`: Provides contextual information for prompts+- `AgentMemory`: Manages conversation history and state with support for:+ - Message history with role-based messages+ - Turn-based conversation tracking+ - Multimodal content+ - Serialization and persistence+ - Memory size management++- `SystemPromptGenerator`: Creates structured system prompts with:+ - Background information+ - Processing steps+ - Output instructions+ - Dynamic context through context providers++- `SystemPromptContextProviderBase`: Base class for creating custom context providers that can inject dynamic information into system prompts[Learn more about components](components.md)@@ -52,6 +63,4 @@ The utils module provides helper functions and utilities:For practical examples and guides on using these components, see:- [Quickstart Guide](../guides/quickstart.md)-- [Basic Concepts](../guides/basic_concepts.md)- [Tools Guide](../guides/tools.md)-- [Advanced Usage](../guides/advanced_usage.md)diff --git a/docs/guides/advanced_usage.md b/docs/guides/advanced_usage.mddeleted file mode 100644index b5534ba..0000000--- a/docs/guides/advanced_usage.md+++ /dev/null@@ -1,241 +0,0 @@-# Advanced Usage--This guide covers advanced features and patterns in Atomic Agents.--## Custom Schemas--You can create custom input/output schemas for specialized agents:--```python-from typing import List-from pydantic import Field-from atomic_agents.lib.base.base_io_schema import BaseIOSchema-from atomic_agents.agents.base_agent import BaseAgent, BaseAgentConfig--# Custom output schema-class CustomOutputSchema(BaseIOSchema):- """Schema for responses with suggested follow-up questions."""-- chat_message: str = Field(- ...,- description="The chat message exchanged between the user and the chat agent.",- )- suggested_user_questions: List[str] = Field(- ...,- description="A list of suggested follow-up questions the user could ask the agent.",- )--# Initialize memory with custom schema-initial_message = CustomOutputSchema(- chat_message="Hello! How can I assist you today?",- suggested_user_questions=[- "What can you do?",- "Tell me a joke",- "Tell me about how you were made"- ]-)-memory.add_message("assistant", initial_message)--# Create agent with custom schema-agent = BaseAgent(- config=BaseAgentConfig(- client=client,- model="gpt-4o-mini",- memory=memory,- output_schema=CustomOutputSchema- )-)-```--## RAG Implementation--Here's how to implement a Retrieval-Augmented Generation (RAG) system with two specialized agents:--```python-import instructor-import openai-from pydantic import Field-from atomic_agents.agents.base_agent import BaseIOSchema, BaseAgent, BaseAgentConfig-from atomic_agents.lib.components.system_prompt_generator import SystemPromptGenerator--# Query Agent for generating semantic search queries-class RAGQueryAgentInputSchema(BaseIOSchema):- """Input schema for the RAG query agent."""- user_message: str = Field(- ...,- description="The user's question or message to generate a semantic search query for"- )--class RAGQueryAgentOutputSchema(BaseIOSchema):- """Output schema for the RAG query agent."""- query: str = Field(- ...,- description="The semantic search query to use for retrieving relevant chunks"- )--query_agent = BaseAgent(- BaseAgentConfig(- client=client,- model="gpt-4o-mini",- system_prompt_generator=SystemPromptGenerator(- background=[- "You are an expert at formulating semantic search queries for RAG systems.",- "Your role is to convert user questions into effective semantic search queries that will retrieve the most relevant text chunks.",- ],- steps=[- "1. Analyze the user's question to identify key concepts and information needs",- "2. Reformulate the question into a semantic search query that will match relevant content",- "3. Ensure the query captures the core meaning while being general enough to match similar content",- ],- output_instructions=[- "Generate a clear, concise semantic search query",- "Focus on key concepts and entities from the user's question",- "Avoid overly specific details that might miss relevant matches",- "Include synonyms or related terms when appropriate",- "Explain your reasoning for the query formulation",- ],- ),- input_schema=RAGQueryAgentInputSchema,- output_schema=RAGQueryAgentOutputSchema,- )-)--# QA Agent for answering questions using retrieved context-class RAGQuestionAnsweringAgentInputSchema(BaseIOSchema):- """Input schema for the RAG QA agent."""- question: str = Field(- ...,- description="The user's question to answer"- )--class RAGQuestionAnsweringAgentOutputSchema(BaseIOSchema):- """Output schema for the RAG QA agent."""- answer: str = Field(- ...,- description="The answer to the user's question based on the retrieved context"- )--qa_agent = BaseAgent(- BaseAgentConfig(- client=client,- model="gpt-4o-mini",- system_prompt_generator=SystemPromptGenerator(- background=[- "You are an expert at answering questions using retrieved context chunks from a RAG system.",- "Your role is to synthesize information from the chunks to provide accurate, well-supported answers.",- "You must explain your reasoning process before providing the answer.",- ],- steps=[- "1. Analyze the question and available context chunks",- "2. Identify the most relevant information in the chunks",- "3. Explain how you'll use this information to answer the question",- "4. Synthesize information into a coherent answer",- ],- output_instructions=[- "First explain your reasoning process clearly",- "Then provide a clear, direct answer based on the context",- "If context is insufficient, state this in your reasoning",- "Never make up information not present in the chunks",- "Focus on being accurate and concise",- ],- ),- input_schema=RAGQuestionAnsweringAgentInputSchema,- output_schema=RAGQuestionAnsweringAgentOutputSchema,- )-)-```--## Streaming with Rich Display--Handle streaming responses with rich formatting:--```python-from rich.live import Live-from rich.text import Text-from typing import List--async def process_stream():- with Live("", refresh_per_second=10, auto_refresh=True) as live:- current_response = ""- current_questions: List[str] = []-- async for partial_response in agent.run_async(input_schema):- if hasattr(partial_response, "chat_message") and partial_response.chat_message:- # Update message if changed- if partial_response.chat_message != current_response:- current_response = partial_response.chat_message-- # Update questions if available- if hasattr(partial_response, "suggested_user_questions"):- current_questions = partial_response.suggested_user_questions-- # Build display text- display_text = Text.assemble(- ("Agent: ", "bold green"),- (current_response, "green")- )-- # Add questions if we have them- if current_questions:- display_text.append("\n\n")- display_text.append(- "Suggested questions you could ask:\n",- style="bold cyan"- )- for i, question in enumerate(current_questions, 1):- display_text.append(f"{i}. {question}\n", style="cyan")-- live.update(display_text)--# Run with asyncio-import asyncio-asyncio.run(process_stream())-```--## Best Practices--### Error Handling--```python-try:- response = agent.run(input_schema)-except openai.APIError as e:- console.print(f"[red]API Error:[/red] {e}")- # Handle API-specific errors-except Exception as e:- console.print(f"[red]Error:[/red] {e}")- # Handle other errors appropriately-```--### Memory Management--```python-# Initialize memory with context-memory = AgentMemory()--# Add system context-memory.add_message(- "system",- "Important context or instructions for the agent..."-)--# Add initial message-memory.add_message("assistant", initial_message)--# Clear memory if needed-memory.clear()-```--### Security--```python-# Use environment variables for sensitive data-API_KEY = os.getenv("OPENAI_API_KEY")-if not API_KEY:- raise ValueError(- "API key is not set. Please set the API key as a static variable "- "or in the environment variable OPENAI_API_KEY."- )-```--## Troubleshootingdiff --git a/docs/guides/basic_concepts.md b/docs/guides/basic_concepts.mddeleted file mode 100644index 27dcc8e..0000000--- a/docs/guides/basic_concepts.md+++ /dev/null@@ -1,237 +0,0 @@-# Basic Concepts--This guide introduces the core concepts of Atomic Agents.--## What is an Agent?--In Atomic Agents, an agent is an autonomous entity that can:--- Process input using natural language-- Make decisions based on its configuration and context-- Execute actions through defined tools and capabilities-- Maintain state and history of interactions--## Core Components--### BaseAgent--The `BaseAgent` class is the foundation of all agents in the framework. It provides:--- Input/output schema handling-- Memory management-- System prompt generation-- Streaming capabilities-- Tool integration--### Components--Components are modular pieces that can be added to agents to extend their functionality:--#### AgentMemory--Manages conversation history and state:--```python-from atomic_agents.lib.components.agent_memory import AgentMemory-from atomic_agents.agents.base_agent import BaseAgentOutputSchema-from rich.console import Console--# Initialize console for pretty outputs-console = Console()--# Initialize memory-memory = AgentMemory()--# Initialize with a greeting-initial_message = BaseAgentOutputSchema(- chat_message="Hello! How can I assist you today?"-)-memory.add_message("assistant", initial_message)--# Add system context if needed-memory.add_message(- "system",- "This agent has access to specific tools and capabilities..."-)--# Access conversation history-for message in memory.get_messages():- console.print(f"{message.role}: {message.content}")-```--#### SystemPromptGenerator--Customizes agent behavior through prompts:--```python-from atomic_agents.lib.components.system_prompt_generator import SystemPromptGenerator--generator = SystemPromptGenerator(- background=[- "This assistant is a knowledgeable AI designed to be helpful, friendly, and informative.",- "It specializes in providing clear explanations and step-by-step guidance.",- "It maintains a professional yet approachable tone.",- ],- steps=[- "1. Carefully analyze the user's input to understand their needs and context.",- "2. Consider any relevant background information or previous conversation context.",- "3. Formulate a clear, structured response that directly addresses the query.",- "4. Include examples or analogies when they would help clarify the explanation.",- ],- output_instructions=[- "Always provide clear, actionable information.",- "Use markdown formatting for code blocks and technical terms.",- "Break down complex concepts into digestible parts.",- "Maintain a helpful and encouraging tone.",- ]-)--# Use in agent configuration-agent = BaseAgent(- config=BaseAgentConfig(- client=client,- model="gpt-4o-mini",- memory=memory,- system_prompt_generator=generator- )-)-```--## Basic Usage Patterns--### Creating an Agent--```python-import os-import instructor-import openai-from rich.console import Console-from rich.panel import Panel-from atomic_agents.agents.base_agent import BaseAgent, BaseAgentConfig--# Initialize console for pretty outputs-console = Console()--# API Key setup-API_KEY = os.getenv("OPENAI_API_KEY")-if not API_KEY:- raise ValueError(- "API key is not set. Please set the API key as a static variable "- "or in the environment variable OPENAI_API_KEY."- )--# OpenAI client setup-client = instructor.from_openai(openai.OpenAI(api_key=API_KEY))--# Create agent with custom configuration-agent = BaseAgent(- config=BaseAgentConfig(- client=client,- model="gpt-4o-mini",- memory=memory,- system_prompt_generator=generator- )-)--# Display the system prompt-default_system_prompt = agent.system_prompt_generator.generate_prompt()-console.print(Panel(default_system_prompt, width=console.width, style="bold cyan"))-```--### Running Commands--```python-from atomic_agents.agents.base_agent import BaseAgentInputSchema-from rich.text import Text-from rich.live import Live--# Simple command-input_schema = BaseAgentInputSchema(chat_message="What is the weather?")-response = agent.run(input_schema)-console.print(Text("Agent:", style="bold green"), end=" ")-console.print(Text(response.chat_message, style="green"))--# Streaming response-async def process_stream():- with Live("", refresh_per_second=10, auto_refresh=True) as live:- current_response = ""- async for partial_response in agent.run_async(input_schema):- if hasattr(partial_response, "chat_message") and partial_response.chat_message:- if partial_response.chat_message != current_response:- current_response = partial_response.chat_message- display_text = Text.assemble(- ("Agent: ", "bold green"),- (current_response, "green")- )- live.update(display_text)--# Run with asyncio-import asyncio-asyncio.run(process_stream())-```--## Next Steps--After understanding these basic concepts, you can:--1. Explore [advanced usage patterns](advanced_usage)-2. Check out the [API Reference](/api/index) for detailed documentation-3. Try building your own custom agents--## Implementation Patterns--Atomic Agents supports several common implementation patterns for different use cases:--### Chatbots and Assistants--Create conversational agents with various capabilities:--```python-from atomic_agents.lib.components.agent_memory import AgentMemory-from atomic_agents.lib.components.system_prompt_generator import SystemPromptGenerator--# Create memory for conversation history-memory = AgentMemory()--# Create personality-generator = SystemPromptGenerator(- background=["You are a helpful assistant specializing in technical support."],- steps=[- "1. Understand the technical issue",- "2. Ask clarifying questions if needed",- "3. Provide step-by-step solutions"- ]-)--# Create agent-support_agent = BaseAgent(- config=BaseAgentConfig(- client=client,- model="gpt-4o-mini",- memory=memory,- system_prompt_generator=generator- )-)-```--### RAG Systems--Build Retrieval-Augmented Generation systems:--```python-from atomic_agents.lib.components.rag import RAGComponent-from atomic_agents.lib.components.embeddings import EmbeddingsManager--# Initialize RAG components-embeddings = EmbeddingsManager(client=client)-rag = RAGComponent(embeddings=embeddings)--# Create RAG agent-rag_agent = BaseAgent(- config=BaseAgentConfig(- client=client,- model="gpt-4o-mini",- components={"rag": rag}- )-)-```diff --git a/docs/guides/quickstart.md b/docs/guides/quickstart.mdindex 4e43e8d..633ea56 100644--- a/docs/guides/quickstart.md+++ b/docs/guides/quickstart.md@@ -1,138 +1,323 @@# Quickstart Guide-This guide will help you get started with Atomic Agents quickly through practical examples.+This guide will help you get started with the Atomic Agents framework. We'll cover basic usage, custom agents, and different AI providers.## Installation-1. Clone the Atomic Agents repository:+First, install the package using pip:- ```bash- git clone https://github.com/BrainBlend-AI/atomic-agents- ```--2. Install dependencies using Poetry:-- ```bash- cd atomic-agents- poetry install- ```--## Basic Examples+```bash+pip install atomic-agents+```-### 1. Basic Chatbot+## Basic Chatbot-This example demonstrates a simple chatbot using the Atomic Agents framework:+Let's start with a simple chatbot:```pythonimport os-import instructor-from openai import OpenAI+from rich.console import Console+from dotenv import load_dotenvfrom atomic_agents.agents.base_agent import BaseAgent, BaseAgentConfig+from atomic_agents.lib.components.agent_memory import AgentMemory-# Initialize OpenAI client-client = instructor.from_openai(OpenAI())+# Load environment variables and setup+load_dotenv()+console = Console()-# Create basic configuration-config = BaseAgentConfig(- client=client,- model="gpt-4o-mini"+# Initialize memory with assistant's first message+memory = AgentMemory()+memory.add_assistant_message("Hello! I'm your AI assistant. How can I help you today?")++# Create agent+agent = BaseAgent(+ config=BaseAgentConfig(+ client=instructor.from_openai(OpenAI(api_key=os.getenv("OPENAI_API_KEY"))),+ model="gpt-4-turbo-preview",+ model_api_parameters={"max_tokens": 2048}+ ))-# Initialize agent-agent = BaseAgent(config)+# Chat loop+while True:+ # Get user input+ user_input = console.input("[bold green]You:[/bold green] ")+ if user_input.lower() in ["exit", "quit"]:+ break++ # Add user message to memory+ memory.add_user_message(user_input)++ # Get response from agent+ response = agent.run(memory=memory)-# Start chat loop+ # Add response to memory and display+ memory.add_assistant_message(response)+ console.print("[bold blue]Assistant:[/bold blue]", response)+```++## Streaming Responses++For a more interactive experience, you can use streaming:++```python+import os+from rich.console import Console+from rich.live import Live+from rich.markdown import Markdown+from dotenv import load_dotenv+from atomic_agents.agents.base_agent import BaseAgent, BaseAgentConfig+from atomic_agents.lib.components.agent_memory import AgentMemory++# Setup as before...++# Chat loop with streamingwhile True:- user_input = input("You: ")- if user_input.lower() == "exit":+ user_input = console.input("[bold green]You:[/bold green] ")+ if user_input.lower() in ["exit", "quit"]:break- response = agent.run({"chat_message": user_input})- print(f"Assistant: {response.chat_message}")+ memory.add_user_message(user_input)++ # Stream the response+ with Live(console=console, refresh_per_second=4) as live:+ response = ""+ for chunk in agent.stream(memory=memory):+ response += chunk+ live.update(Markdown(f"**Assistant:** {response}"))++ memory.add_assistant_message(response)```-### 2. Custom Chatbot+## Custom Chatbot-This example shows how to create a custom chatbot with a specific personality:+You can customize the agent's behavior using system prompts and context providers. Context providers are particularly useful for injecting dynamic information that changes between calls:```python-from atomic_agents.lib.components.system_prompt_generator import SystemPromptGenerator+from dataclasses import dataclass+from typing import List+from atomic_agents.lib.components.system_prompt_generator import (+ SystemPromptGenerator,+ SystemPromptContextProviderBase+)++@dataclass+class SearchResult:+ content: str+ metadata: dict++class SearchResultsProvider(SystemPromptContextProviderBase):+ def __init__(self, title: str):+ super().__init__(title=title)+ self.results: List[SearchResult] = []++ def get_info(self) -> str:+ """Dynamically format search results for the system prompt"""+ if not self.results:+ return "No search results available."-# Create custom system prompt-generator = SystemPromptGenerator(+ return "\n\n".join([+ f"Result {idx}:\nMetadata: {result.metadata}\nContent:\n{result.content}\n{'-' * 80}"+ for idx, result in enumerate(self.results, 1)+ ])++# Create prompt generator with dynamic context+prompt_generator = SystemPromptGenerator(background=[- "You are a friendly assistant that always responds in rhyming verse.",- "You maintain a playful and poetic tone while being helpful.",+ "You are an AI assistant that answers questions based on search results.",+ "Analyze the provided search results to give accurate answers."],steps=[- "1. Understand the user's question or request",- "2. Formulate your response in rhyming verse",- "3. Ensure the response is both helpful and entertaining"+ "1. Review all provided search results",+ "2. Extract relevant information",+ "3. Synthesize a comprehensive answer"],output_instructions=[- "Always respond in rhyming verse",- "Keep responses concise but informative",- "Maintain a playful tone"- ]+ "Base your answer only on the provided search results",+ "Cite specific results when possible",+ "Admit when information is not found in the results"+ ],+ context_providers={+ "search_results": SearchResultsProvider("Search Results")+ })-# Create agent with custom configuration+# Create agent with dynamic contextagent = BaseAgent(config=BaseAgentConfig(client=client,- model="gpt-4o-mini",- system_prompt_generator=generator+ model=model,+ system_prompt_generator=prompt_generator))++# Example usage with dynamic updates+def process_question(question: str):+ # Perform search and get results+ results = perform_search(question) # Your search implementation++ # Update context provider with new results+ search_provider = prompt_generator.context_providers["search_results"]+ search_provider.results = [+ SearchResult(content=result.text, metadata=result.meta)+ for result in results+ ]++ # Each call to the agent will now include the updated search results+ response = agent.run(memory=memory)```-### 3. Custom Schema+The key difference with context providers is that they allow you to:+- Inject dynamic information that changes between calls+- Update context (like search results, current state, etc.) without changing the base prompt+- Keep a clear separation between static prompt elements and dynamic context+- Handle potentially large or structured data in a clean way++This pattern is especially useful for:+- RAG (Retrieval Augmented Generation) systems+- Agents that need access to external data+- Stateful conversations where context changes+- Multi-step processes with varying intermediate results-This example demonstrates using a custom output schema:+## Custom Input/Output Schema++For more structured interactions, define custom schemas:```python-from pydantic import BaseModel-from typing import List+from pydantic import BaseModel, Field-class CustomResponseSchema(BaseModel):- chat_message: str- follow_up_questions: List[str]+class CustomInput(BaseModel):+ question: str = Field(..., description="The user's question")+ context: str = Field(..., description="Additional context for the question")++class CustomOutput(BaseModel):+ answer: str = Field(..., description="The answer to the user's question")+ confidence: float = Field(..., description="Confidence score (0-1)")+ sources: list[str] = Field(default_factory=list, description="Sources used")# Create agent with custom schema-agent = BaseAgent(+agent = BaseAgent[CustomInput, CustomOutput](config=BaseAgentConfig(client=client,- model="gpt-4o-mini",- output_schema=CustomResponseSchema+ model=model,+ input_schema=CustomInput,+ output_schema=CustomOutput))++# Use with custom schema+result = agent.run(+ memory=memory,+ input_data=CustomInput(+ question="What is machine learning?",+ context="Explain for a beginner"+ )+)+print(f"Answer: {result.answer}")+print(f"Confidence: {result.confidence}")+print(f"Sources: {result.sources}")```-### 4. Multiple Providers+## Multiple Providers-This example shows how to use different AI providers:+The framework supports multiple AI providers:```python-# OpenAI-openai_client = instructor.from_openai(OpenAI())--# Groq-from groq import Groq-groq_client = instructor.from_openai(Groq())--# Ollama (for local development)-from atomic_agents.lib.providers.ollama import OllamaClient-ollama_client = instructor.from_openai(OllamaClient())+import os+import instructor+from rich.console import Console+from dotenv import load_dotenv+from atomic_agents.agents.base_agent import BaseAgent, BaseAgentConfig-# Use any provider+load_dotenv()+console = Console()++def setup_client(provider):+ if provider == "openai":+ from openai import OpenAI+ api_key = os.getenv("OPENAI_API_KEY")+ client = instructor.from_openai(OpenAI(api_key=api_key))+ model = "gpt-4-turbo-preview"++ elif provider == "anthropic":+ from anthropic import Anthropic+ api_key = os.getenv("ANTHROPIC_API_KEY")+ client = instructor.from_anthropic(Anthropic(api_key=api_key))+ model = "claude-3-haiku-20240307"++ elif provider == "groq":+ from groq import Groq+ api_key = os.getenv("GROQ_API_KEY")+ client = instructor.from_groq(+ Groq(api_key=api_key),+ mode=instructor.Mode.JSON+ )+ model = "mixtral-8x7b-32768"++ elif provider == "ollama":+ from openai import OpenAI as OllamaClient+ client = instructor.from_openai(+ OllamaClient(+ base_url="http://localhost:11434/v1",+ api_key="ollama"+ )+ )+ model = "llama2"++ elif provider == "gemini":+ from openai import OpenAI+ api_key = os.getenv("GEMINI_API_KEY")+ client = instructor.from_openai(+ OpenAI(+ api_key=api_key,+ base_url="https://generativelanguage.googleapis.com/v1beta/openai/"+ ),+ mode=instructor.Mode.JSON+ )+ model = "gemini-pro"++ else:+ raise ValueError(f"Unsupported provider: {provider}")++ return client, model++# Choose a provider+provider = "openai" # or "anthropic", "groq", "ollama", "gemini"+client, model = setup_client(provider)++# Create agent with chosen provideragent = BaseAgent(config=BaseAgentConfig(- client=openai_client, # or groq_client, or ollama_client- model="gpt-4o-mini" # adjust model name based on provider+ client=client,+ model=model,+ model_api_parameters={"max_tokens": 2048}))```+The framework supports multiple providers through Instructor:++- **OpenAI**: Standard GPT models+- **Anthropic**: Claude models+- **Groq**: Fast inference for open models+- **Ollama**: Local models (requires Ollama running)+- **Gemini**: Google's Gemini models++Each provider requires its own API key (except Ollama) which should be set in environment variables:+```bash+# OpenAI+export OPENAI_API_KEY="your-openai-key"++# Anthropic+export ANTHROPIC_API_KEY="your-anthropic-key"++# Groq+export GROQ_API_KEY="your-groq-key"++# Gemini+export GEMINI_API_KEY="your-gemini-key"+```+## Running the ExamplesTo run any of these examples:@@ -154,7 +339,5 @@ To run any of these examples:After trying these examples, you can:-1. Explore [basic concepts](basic_concepts) for deeper understanding-2. Learn about [tools and their integration](tools.md)-3. Check out [advanced usage patterns](advanced_usage)-4. Review the [API reference](../api/index) for detailed documentation+1. Learn about [tools and their integration](tools.md)+2. Review the [API reference](../api/index) for detailed documentationdiff --git a/docs/guides/tools.md b/docs/guides/tools.mdindex cc933df..acae497 100644--- a/docs/guides/tools.md+++ b/docs/guides/tools.md@@ -1,225 +1,165 @@# Tools Guide-Atomic Agents provides a collection of tools through the Atomic Forge that extend agent capabilities.+Atomic Agents uses a unique approach to tools through the **Atomic Forge** system. Rather than bundling all tools into a single package, tools are designed to be standalone, modular components that you can download and integrate into your project as needed.-## Installing Tools+## Philosophy-Tools are managed using the Atomic Assembler CLI:+The Atomic Forge approach provides several key benefits:-```bash-# Install a specific tool-atomic-assembler install calculator--# List available tools-atomic-assembler list--# Update installed tools-atomic-assembler update-```+1. **Full Control**: You have complete ownership and control over each tool you download. Want to modify a tool's behavior? You can change it without impacting other users.+2. **Dependency Management**: Since tools live in your codebase, you have better control over dependencies.+3. **Lightweight**: Download only the tools you need, avoiding unnecessary dependencies. For example, you don't need Sympy if you're not using the Calculator tool.## Available Tools-### Calculator+The Atomic Forge includes several pre-built tools:-A tool for performing mathematical calculations:+- **Calculator**: Perform mathematical calculations+- **SearxNG Search**: Search the web using SearxNG+- **Tavily Search**: AI-powered web search+- **YouTube Transcript Scraper**: Extract transcripts from YouTube videos+- **Webpage Scraper**: Extract content from web pages-```python-from atomic_agents.agents.base_agent import BaseAgent, BaseAgentConfig+## Using Tools-agent = BaseAgent(- config=BaseAgentConfig(- client=client,- model="gpt-4o-mini",- tools=["calculator"]- )-)+### 1. Download Tools-# The agent can now perform calculations-response = agent.run({- "chat_message": "What is the square root of 144 plus 50?"-})-```--### SearxNG Search--A privacy-focused web search tool:+Use the Atomic Assembler CLI to download tools:-```python-# Configure with your SearxNG instance-agent = BaseAgent(- config=BaseAgentConfig(- client=client,- model="gpt-4o-mini",- tools=["searxng_search"],- tool_configs={- "searxng_search": {- "instance_url": "https://your-searxng-instance.com"- }- }- )-)+```bash+atomic```-### Tavily Search--An AI-optimized search engine:+This will present a menu where you can select and download tools. Each tool includes:+- Input/Output schemas+- Usage examples+- Dependencies+- Installation instructions-```python-import os+### 2. Tool Structure-# Set your Tavily API key-os.environ["TAVILY_API_KEY"] = "your-api-key"+Each tool follows a standard structure:-agent = BaseAgent(- config=BaseAgentConfig(- client=client,- model="gpt-4o-mini",- tools=["tavily_search"]- )-)+```+tool_name/+│ .coveragerc+│ pyproject.toml+│ README.md+│ requirements.txt+│ poetry.lock+│+├── tool/+│ │ tool_name.py+│ │ some_util_file.py+│+└── tests/+ │ test_tool_name.py+ │ test_some_util_file.py```-### YouTube Transcript Scraper+### 3. Using a Tool-Extract transcripts from YouTube videos:+Here's an example of using a downloaded tool:```python-import os--# Set your YouTube API key-os.environ["YOUTUBE_API_KEY"] = "your-api-key"--agent = BaseAgent(- config=BaseAgentConfig(- client=client,- model="gpt-4o-mini",- tools=["youtube_transcript"]- )+from calculator.tool.calculator import (+ CalculatorTool,+ CalculatorInputSchema,+ CalculatorToolConfig)-# The agent can now analyze YouTube videos-response = agent.run({- "chat_message": "Summarize this video: https://youtube.com/watch?v=..."-})-```--### Webpage Scraper--Extract content from web pages:+# Initialize the tool+calculator = CalculatorTool(+ config=CalculatorToolConfig()+)-```python-agent = BaseAgent(- config=BaseAgentConfig(- client=client,- model="gpt-4o-mini",- tools=["webpage_scraper"]+# Use the tool+result = calculator.run(+ CalculatorInputSchema(+ expression="2 + 2"))--# The agent can now analyze web pages-response = agent.run({- "chat_message": "What are the main points from this article: https://..."-})+print(f"Result: {result.value}") # Result: 4```## Creating Custom Tools-You can create your own tools by following these steps:--### 1. Create Tool Structure--Create a new directory with the required files:--```-my_tool/-├── __init__.py-├── README.md-├── pyproject.toml-└── my_tool/- ├── __init__.py- └── tool.py-```--### 2. Implement Tool Logic+You can create your own tools by following these guidelines:-Create your tool implementation:+### 1. Basic Structure```python-from pydantic import BaseModel-from atomic_agents.lib.tools import BaseTool--class MyToolInputs(BaseModel):- param1: str- param2: int+from atomic_agents.lib.base.base_tool import BaseTool, BaseToolConfig+from atomic_agents.agents.base_agent import BaseIOSchema++################+# Input Schema #+################++class MyToolInputSchema(BaseIOSchema):+ """Define what your tool accepts as input"""+ value: str = Field(..., description="Input value to process")++#####################+# Output Schema(s) #+#####################++class MyToolOutputSchema(BaseIOSchema):+ """Define what your tool returns"""+ result: str = Field(..., description="Processed result")++#################+# Configuration #+#################++class MyToolConfig(BaseToolConfig):+ """Tool configuration options"""+ api_key: str = Field(+ default=os.getenv("MY_TOOL_API_KEY"),+ description="API key for the service"+ )-class MyToolOutputs(BaseModel):- result: str+#####################+# Main Tool & Logic #+#####################class MyTool(BaseTool):- name = "my_tool"- description = "Description of what my tool does"- inputs_schema = MyToolInputs- outputs_schema = MyToolOutputs-- def run(self, inputs: MyToolInputs) -> MyToolOutputs:- # Implement your tool logic here- result = f"Processed {inputs.param1} {inputs.param2} times"- return MyToolOutputs(result=result)-```--### 3. Configure Package--Create a pyproject.toml:--```toml-[tool.poetry]-name = "my-tool"-version = "0.1.0"-description = "My custom tool for Atomic Agents"-authors = ["Your Name <[email protected]>"]--[tool.poetry.dependencies]-python = "^3.11"-atomic-agents = "^0.1.0"+ """Main tool implementation"""+ input_schema = MyToolInputSchema+ output_schema = MyToolOutputSchema++ def __init__(self, config: MyToolConfig = MyToolConfig()):+ super().__init__(config)+ self.api_key = config.api_key++ def run(self, params: MyToolInputSchema) -> MyToolOutputSchema:+ # Implement your tool's logic here+ result = self.process_input(params.value)+ return MyToolOutputSchema(result=result)```-### 4. Document Usage--Create a README.md with:--* Installation instructions-* Configuration requirements-* Usage examples-* Any environment variables needed--## Best Practices--### 1. Error Handling--* Implement proper error handling in tools-* Return meaningful error messages-* Handle rate limits and retries--### 2. Configuration--* Use environment variables for sensitive data-* Make configuration flexible but with sensible defaults-* Document all configuration options--### 3. Testing+### 2. Best Practices-* Write unit tests for your tools-* Include integration tests if applicable-* Test error cases and edge conditions+- **Single Responsibility**: Each tool should do one thing well+- **Clear Interfaces**: Use explicit input/output schemas+- **Error Handling**: Validate inputs and handle errors gracefully+- **Documentation**: Include clear usage examples and requirements+- **Tests**: Write comprehensive tests for your tool+- **Dependencies**: Manually create `requirements.txt` with only runtime dependencies-### 4. Documentation+### 3. Tool Requirements-* Keep README up to date-* Include example code-* Document any breaking changes+- Must inherit from appropriate base classes:+ - Input/Output schemas from `BaseIOSchema`+ - Configuration from `BaseToolConfig`+ - Tool class from `BaseTool`+- Must include proper documentation+- Must include tests+- Must follow the standard directory structure## Next Steps-* Check out the [example projects](../examples/index.md)-* Learn about [advanced usage patterns](advanced_usage.md)-* Contribute your own tools to the [Atomic Forge](../contributing.md)+1. Browse available tools in the [Atomic Forge repository](https://github.com/BrainBlend-AI/atomic-agents/tree/main/atomic-forge)+2. Try downloading and using different tools via the CLI+3. Consider creating your own tools following the guidelines+4. Share your tools with the community through pull requests