Merge branch 'main' into v2.0

Author: KennyVaneetvelde

.github/workflows/code-quality.yml

@@ -7,6 +7,9 @@ on:
     branches: [ main, v2.0 ]
   workflow_dispatch:
 
+permissions:
+  contents: read
+
 jobs:
   quality:
     runs-on: ubuntu-latest

.github/workflows/docs.yml

@@ -39,8 +39,13 @@ jobs:
       - name: Build documentation
         run: |
           cd docs
+          poetry run make singlehtml
           poetry run make html
 
+      - name: Generate llms.txt
+        run: |
+          poetry run python scripts/generate_llms_txt.py
+
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:

README.md

@@ -2,16 +2,55 @@
 
 <img src="./.assets/logo.png" alt="Atomic Agents" width="350"/>
 
----
-
 [![PyPI version](https://badge.fury.io/py/atomic-agents.svg)](https://badge.fury.io/py/atomic-agents)
+[![Documentation](https://img.shields.io/badge/docs-read%20the%20docs-blue?logo=readthedocs&style=flat-square)](https://brainblend-ai.github.io/atomic-agents/)
+[![Build Docs](https://github.com/BrainBlend-AI/atomic-agents/actions/workflows/docs.yml/badge.svg)](https://github.com/BrainBlend-AI/atomic-agents/actions/workflows/docs.yml)
+[![Code Quality](https://github.com/BrainBlend-AI/atomic-agents/actions/workflows/code-quality.yml/badge.svg)](https://github.com/BrainBlend-AI/atomic-agents/actions/workflows/code-quality.yml)
+[![Discord](https://img.shields.io/badge/chat-on%20discord-7289DA?logo=discord&style=flat-square)](https://discord.gg/J3W9b5AZJR)
+[![PyPI downloads](https://img.shields.io/pypi/dm/atomic-agents?style=flat-square)](https://pypi.org/project/atomic-agents/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/atomic-agents?style=flat-square)](https://pypi.org/project/atomic-agents/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-yellow?style=flat-square)](LICENSE)
+[![GitHub Stars](https://img.shields.io/github/stars/BrainBlend-AI/atomic-agents?style=social)](https://github.com/BrainBlend-AI/atomic-agents/stargazers)
+[![GitHub Forks](https://img.shields.io/github/forks/BrainBlend-AI/atomic-agents?style=social)](https://github.com/BrainBlend-AI/atomic-agents/network/members)
+
+## Table of Contents
+
+- [Atomic Agents](#atomic-agents)
+  - [Table of Contents](#table-of-contents)
+  - [Overview](#overview)
+  - [Documentation](#documentation)
+    - [Watch the Overview Video](#watch-the-overview-video)
+    - [Watch the Quickstart Video](#watch-the-quickstart-video)
+  - [Why Atomic Agents?](#why-atomic-agents)
+  - [Anatomy of an Agent](#anatomy-of-an-agent)
+  - [Installation](#installation)
+  - [Project Structure](#project-structure)
+  - [Quickstart \& Examples](#quickstart--examples)
+  - [Context Providers](#context-providers)
+    - [Using Context Providers](#using-context-providers)
+  - [Chaining Schemas and Agents](#chaining-schemas-and-agents)
+    - [Example: Generating Queries for Different Search Providers](#example-generating-queries-for-different-search-providers)
+  - [Running the CLI](#running-the-cli)
+  - [Provider \& Model Compatibility](#provider--model-compatibility)
+  - [Atomic Forge](#atomic-forge)
+  - [Contributing](#contributing)
+  - [License](#license)
+  - [Star History](#star-history)
+
+## Overview
 
 The Atomic Agents framework is designed around the concept of atomicity to be an extremely lightweight and modular framework for building Agentic AI pipelines and applications without sacrificing developer experience and maintainability. The framework provides a set of tools and agents that can be combined to create powerful applications. It is built on top of [Instructor](https://github.com/jxnl/instructor) and leverages the power of [Pydantic](https://docs.pydantic.dev/latest/) for data and schema validation and serialization.
 All logic and control flows are written in Python, enabling developers to apply familiar best practices and workflows from traditional software development without compromising flexibility or clarity.
 
-**NEW: We now also have an official subreddit at [/r/AtomicAgents](https://www.reddit.com/r/AtomicAgents/) - Be sure to join!**
+**NEW: Join our community on Discord at [discord.gg/J3W9b5AZJR](https://discord.gg/J3W9b5AZJR) and our official subreddit at [/r/AtomicAgents](https://www.reddit.com/r/AtomicAgents/)!**
 
----
+## Documentation
+
+[![Read the Docs](https://img.shields.io/badge/docs-read%20the%20docs-blue?logo=readthedocs&style=for-the-badge)](https://brainblend-ai.github.io/atomic-agents/)
+
+> 🚀 Ready to explore our documentation? Dive in below!
+
+[Visit the Documentation Site »](https://brainblend-ai.github.io/atomic-agents/)
 
 If you want to learn more about the motivation and philosophy behind Atomic Agents, [I suggest reading this Medium article (no account needed)](https://ai.gopubby.com/want-to-build-ai-agents-c83ab4535411?sk=b9429f7c57dbd3bda59f41154b65af35) or check out the overview video below:
 
@@ -327,10 +366,6 @@ The `atomic-assembler` CLI gives you complete control over your tools, avoiding
 
 Atomic Agents depends on the [Instructor](https://github.com/jxnl/instructor) package. This means that in all examples where OpenAI is used, any other API supported by Instructor can also be used—such as Ollama, Groq, Mistral, Cohere, Anthropic, Gemini, and more. For a complete list, please refer to the Instructor documentation on its [GitHub page](https://github.com/jxnl/instructor).
 
-## API Documentation
-
-API documentation can be found [here](https://brainblend-ai.github.io/atomic-agents/).
-
 ## Atomic Forge
 
 Atomic Forge is a collection of tools that can be used with Atomic Agents to extend its functionality. Current tools include:
@@ -343,7 +378,7 @@ For more information on using and creating tools, see the [Atomic Forge README](
 
 ## Contributing
 
-We welcome contributions! Please see the [Developer Guide](/guides/DEV_GUIDE.md) for detailed information on how to contribute to Atomic Agents. Here are some quick steps:
+We welcome contributions! Please see the [Contributing Guide](/docs/contributing.md) for detailed information on how to contribute to Atomic Agents. Here are some quick steps:
 
 1. Fork the repository
 2. Create a new branch (`git checkout -b feature-branch`)

atomic-agents/atomic_agents/agents/base_agent.py

@@ -59,18 +59,17 @@ class BaseAgentOutputSchema(BaseIOSchema):
 
 class BaseAgentConfig(BaseModel):
     client: instructor.client.Instructor = Field(..., description="Client for interacting with the language model.")
-    model: str = Field("gpt-4o-mini", description="The model to use for generating responses.")
-    memory: Optional[AgentMemory] = Field(None, description="Memory component for storing chat history.")
+    model: str = Field(default="gpt-4o-mini", description="The model to use for generating responses.")
+    memory: Optional[AgentMemory] = Field(default=None, description="Memory component for storing chat history.")
     system_prompt_generator: Optional[SystemPromptGenerator] = Field(
-        None, description="Component for generating system prompts."
+        default=None, description="Component for generating system prompts."
     )
     system_role: Optional[str] = Field(
-        "system", description="The role of the system in the conversation. None means no system prompt."
+        default="system", description="The role of the system in the conversation. None means no system prompt."
     )
     model_config = {"arbitrary_types_allowed": True}
     model_api_parameters: Optional[dict] = Field(None, description="Additional parameters passed to the API provider.")
 
-
 class BaseAgent[InputSchema: BaseIOSchema, OutputSchema: BaseIOSchema]:
     """
     Base class for chat agents.

atomic-agents/atomic_agents/lib/factories/schema_transformer.py

@@ -109,6 +109,7 @@ def create_model_from_schema(
             model_name,
             __base__=BaseIOSchema,
             __doc__=docstring or f"Dynamically generated Pydantic model for {model_name}",
+            __config__={"title": tool_name_literal},
             **fields,
         )
 

atomic-examples/deep-research/deep_research/tools/webpage_scraper.py

@@ -46,6 +46,7 @@ class WebpageScraperToolOutputSchema(BaseIOSchema):
 
     content: str = Field(..., description="The scraped content in markdown format.")
     metadata: WebpageMetadata = Field(..., description="Metadata about the scraped webpage.")
+    error: Optional[str] = Field(None, description="Error message if the scraping failed.")
 
 
 #################
@@ -213,38 +214,47 @@ def run(self, params: WebpageScraperToolInputSchema) -> WebpageScraperToolOutput
         Returns:
             WebpageScraperToolOutputSchema: The output containing the markdown content and metadata.
         """
-        # Fetch webpage content
-        html_content = self._fetch_webpage(str(params.url))
 
-        # Parse HTML with BeautifulSoup
-        soup = BeautifulSoup(html_content, "html.parser")
+        try:
+            # Fetch webpage content
+            html_content = self._fetch_webpage(str(params.url))
 
-        # Extract main content using custom extraction
-        main_content = self._extract_main_content(soup)
+            # Parse HTML with BeautifulSoup
+            soup = BeautifulSoup(html_content, "html.parser")
 
-        # Convert to markdown
-        markdown_options = {
-            "strip": ["script", "style"],
-            "heading_style": "ATX",
-            "bullets": "-",
-            "wrap": True,
-        }
+            # Extract main content using custom extraction
+            main_content = self._extract_main_content(soup)
 
-        if not params.include_links:
-            markdown_options["strip"].append("a")
+            # Convert to markdown
+            markdown_options = {
+                "strip": ["script", "style"],
+                "heading_style": "ATX",
+                "bullets": "-",
+                "wrap": True,
+            }
 
-        markdown_content = markdownify(main_content, **markdown_options)
+            if not params.include_links:
+                markdown_options["strip"].append("a")
 
-        # Clean up the markdown
-        markdown_content = self._clean_markdown(markdown_content)
+            markdown_content = markdownify(main_content, **markdown_options)
 
-        # Extract metadata
-        metadata = self._extract_metadata(soup, Document(html_content), str(params.url))
+            # Clean up the markdown
+            markdown_content = self._clean_markdown(markdown_content)
 
-        return WebpageScraperToolOutputSchema(
-            content=markdown_content,
-            metadata=metadata,
-        )
+            # Extract metadata
+            metadata = self._extract_metadata(soup, Document(html_content), str(params.url))
+
+            return WebpageScraperToolOutputSchema(
+                content=markdown_content,
+                metadata=metadata,
+            )
+        except Exception as e:
+            # Create empty/minimal metadata with at least the domain
+            domain = urlparse(str(params.url)).netloc
+            minimal_metadata = WebpageMetadata(title="Error retrieving page", domain=domain)
+
+            # Return with error message in the error field
+            return WebpageScraperToolOutputSchema(content="", metadata=minimal_metadata, error=str(e))
 
 
 #################
@@ -266,12 +276,18 @@ def run(self, params: WebpageScraperToolInputSchema) -> WebpageScraperToolOutput
             )
         )
 
-        console.print(Panel.fit("Metadata", style="bold green"))
-        console.print(result.metadata.model_dump_json(indent=2))
+        # Check if there was an error during scraping, otherwise print the results
+        if result.error:
+            console.print(Panel.fit("Error", style="bold red"))
+            console.print(f"[red]{result.error}[/red]")
+        else:
+            console.print(Panel.fit("Metadata", style="bold green"))
+            console.print(result.metadata.model_dump_json(indent=2))
+
+            console.print(Panel.fit("Content Preview (first 500 chars)", style="bold green"))
+            # To show as markdown with proper formatting
+            console.print(Panel.fit("Content as Markdown", style="bold green"))
+            console.print(Markdown(result.content[:500]))
 
-        console.print(Panel.fit("Content Preview (first 500 chars)", style="bold green"))
-        # To show as markdown with proper formatting
-        console.print(Panel.fit("Content as Markdown", style="bold green"))
-        console.print(Markdown(result.content[:500]))
     except Exception as e:
         console.print(f"[red]Error:[/red] {str(e)}")

atomic-examples/mcp-agent/example-client/poetry.lock

@@ -8,7 +8,7 @@ authors = ["Your Name <[email protected]>"]
 python = ">=3.12,<4.0"
 atomic-agents = { path = "../../../", develop = true }
 example-mcp-server = { path = "../example-mcp-server", develop = true }
-pydantic = ">=2.0.0"
+pydantic = ">=2.10.3,<3.0.0"
 rich = ">=13.0.0"
 openai = ">=1.0.0"
 mcp = {extras = ["cli"], version = "^1.6.0"}

atomic-examples/mcp-agent/example-client/pyproject.toml

@@ -9,7 +9,7 @@ readme = "README.md"
 python = ">=3.12,<4.0"
 atomic-agents = {path = "../..", develop = true}
 instructor = "^1.6.1"
-pydantic = "^2.9.2"
+pydantic = ">=2.10.3,<3.0.0"
 sympy = "^1.13.3"
 python-dotenv = ">=1.0.1,<2.0.0"
 openai = ">=1.35.12,<2.0.0"

atomic-examples/orchestration-agent/poetry.lock

@@ -57,14 +57,20 @@ def setup_client(provider):
             mode=instructor.Mode.JSON,
         )
         model = "gemini-2.0-flash-exp"
+    elif provider == "6" or provider == "openrouter":
+        from openai import OpenAI as OpenRouterClient
+
+        api_key = os.getenv("OPENROUTER_API_KEY")
+        client = instructor.from_openai(OpenRouterClient(base_url="https://openrouter.ai/api/v1", api_key=api_key))
+        model = "mistral/ministral-8b"
     else:
         raise ValueError(f"Unsupported provider: {provider}")
 
     return client, model
 
 
 # Prompt the user to choose a provider from one in the list below.
-providers_list = ["openai", "anthropic", "groq", "ollama", "gemini"]
+providers_list = ["openai", "anthropic", "groq", "ollama", "gemini", "openrouter"]
 y = "bold yellow"
 b = "bold blue"
 g = "bold green"

atomic-examples/orchestration-agent/pyproject.toml

@@ -59,9 +59,10 @@ Make sure to add these lines to `settings.tml`:
    SEARXNG_BASE_URL=your_searxng_instance_url
    ```
 
-   Replace `your_openai_api_key` with your actual OpenAI API key and `your_searxng_instance_url` with the URL of your SearXNG instance.
+   Replace `your_openai_api_key` with your actual OpenAI API key and `your_searxng_instance_url` with the URL of your SearXNG instance.  
+   If you do not have a SearxNG instance, see the instructions below to set up one locally with docker.
 
-1. Run the Web Search Agent:
+2. Run the Web Search Agent:
 
    ```bash
    poetry run python web_search_agent/main.py
@@ -75,6 +76,30 @@ Make sure to add these lines to `settings.tml`:
 4. The Question Answering Agent analyzes the search results and formulates a detailed answer.
 5. The main script presents the answer, along with references and follow-up questions.
 
+## SearxNG Setup with docker
+
+From the [official instructions](https://docs.searxng.org/admin/installation-docker.html):
+
+```shell
+mkdir my-instance
+cd my-instance
+export PORT=8080
+docker pull searxng/searxng
+docker run --rm \
+           -d -p ${PORT}:8080 \
+           -v "${PWD}/searxng:/etc/searxng" \
+           -e "BASE_URL=http://localhost:$PORT/" \
+           -e "INSTANCE_NAME=my-instance" \
+           searxng/searxng
+```
+
+Set the `SEARXNG_BASE_URL` environment variable to `http://localhost:8080/` in your `.env` file.
+
+
+Note: for the agent to communicate with SearxNG, the instance must enable the JSON engine, which is disabled by default.
+Edit `/etc/searxng/settings.yml` and add `- json` in the `search.formats` section, then restart the container.
+
+
 ## Customization
 
 You can customize the Web Search Agent by modifying the following:

atomic-examples/quickstart/quickstart/4_basic_chatbot_different_providers.py

@@ -4,8 +4,6 @@
 from typing import List
 from atomic_agents.agents.base_agent import BaseIOSchema, BaseAgent, BaseAgentConfig
 from atomic_agents.lib.components.system_prompt_generator import SystemPromptGenerator
-
-
 class QueryAgentInputSchema(BaseIOSchema):
     """This is the input schema for the QueryAgent."""