atomic-agents 2.7.4__tar.gz → 2.8.0__tar.gz

{atomic_agents-2.7.4 → atomic_agents-2.8.0}/.claude-plugin/marketplace.json

@@ -9,8 +9,8 @@
   "plugins": [
     {
       "name": "atomic-agents",
-      "description": "Comprehensive development workflow for building well-organized Atomic Agents applications with specialized agents for schema design, architecture planning, code review, and tool development",
-      "version": "1.0.0",
+      "description": "Skills plus explorer and reviewer subagents for building, scaffolding, understanding, and auditing applications with the Atomic Agents Python framework. Progressive-disclosure references for schemas, agents, tools, context providers, prompts, orchestration, memory, hooks, providers, project structure, and testing — plus isolated-context subagents for codebase mapping and code review, and a new-app scaffolder.",
+      "version": "2.0.1",
       "author": {
         "name": "BrainBlend AI",
         "email": "support@brainblend.ai"

{atomic_agents-2.7.4 → atomic_agents-2.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atomic-agents
-Version: 2.7.4
+Version: 2.8.0
 Summary: A versatile framework for creating and managing intelligent agents.
 Project-URL: Homepage, https://github.com/BrainBlend-AI/atomic-agents
 Project-URL: Repository, https://github.com/BrainBlend-AI/atomic-agents
@@ -18,7 +18,7 @@ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.12
 Requires-Dist: gitpython<4.0.0,>=3.1.43
-Requires-Dist: instructor==1.13.0
+Requires-Dist: instructor==1.14.5
 Requires-Dist: litellm<2.0.0,>=1.50.0
 Requires-Dist: mcp[cli]>=1.6.0
 Requires-Dist: pydantic<3.0.0,>=2.11.0
@@ -96,12 +96,16 @@ To install Atomic Agents, you can use pip:
 pip install atomic-agents
 ```
 
-Make sure you also install the provider you want to use. For example, to use OpenAI and Groq, you can install the `openai` and `groq` packages:
+Make sure you also install the provider you want to use. Provider SDKs are available as instructor extras:
 
 ```bash
-pip install openai groq
+pip install instructor[groq]        # for Groq
+pip install instructor[anthropic]   # for Anthropic
+pip install instructor[google-genai] # for Gemini
 ```
 
+OpenAI is included by default. For a full list of supported providers, see the [Instructor docs](https://python.useinstructor.com/integrations/).
+
 This also installs the CLI *Atomic Assembler*, which can be used to download Tools (and soon also Agents and Pipelines).
 
 ### Quick Example
@@ -341,8 +345,18 @@ If you're upgrading from v1.x, please read our comprehensive [**Upgrade Guide**]
 
 Atomic Forge is a collection of tools that can be used with Atomic Agents to extend its functionality. Current tools include:
 
+- arXiv Search
+- BoCha Search
 - Calculator
+- DateTime
+- Fía Signals
+- Hacker News Search
+- PDF Reader
 - SearXNG Search
+- Tavily Search
+- Webpage Scraper
+- Weather
+- Wikipedia Search
 - YouTube Transcript Scraper
 
 For more information on using and creating tools, see the [Atomic Forge README](/atomic-forge/README.md).
@@ -404,7 +418,7 @@ uv sync --all-packages
 
 ## Provider & Model Compatibility
 
-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).
+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, [MiniMax](https://www.minimax.io/), and more. For a complete list, please refer to the Instructor documentation on its [GitHub page](https://github.com/jxnl/instructor).
 
 ## Contributing
 

{atomic_agents-2.7.4 → atomic_agents-2.8.0}/README.md

@@ -65,12 +65,16 @@ To install Atomic Agents, you can use pip:
 pip install atomic-agents
 ```
 
-Make sure you also install the provider you want to use. For example, to use OpenAI and Groq, you can install the `openai` and `groq` packages:
+Make sure you also install the provider you want to use. Provider SDKs are available as instructor extras:
 
 ```bash
-pip install openai groq
+pip install instructor[groq]        # for Groq
+pip install instructor[anthropic]   # for Anthropic
+pip install instructor[google-genai] # for Gemini
 ```
 
+OpenAI is included by default. For a full list of supported providers, see the [Instructor docs](https://python.useinstructor.com/integrations/).
+
 This also installs the CLI *Atomic Assembler*, which can be used to download Tools (and soon also Agents and Pipelines).
 
 ### Quick Example
@@ -310,8 +314,18 @@ If you're upgrading from v1.x, please read our comprehensive [**Upgrade Guide**]
 
 Atomic Forge is a collection of tools that can be used with Atomic Agents to extend its functionality. Current tools include:
 
+- arXiv Search
+- BoCha Search
 - Calculator
+- DateTime
+- Fía Signals
+- Hacker News Search
+- PDF Reader
 - SearXNG Search
+- Tavily Search
+- Webpage Scraper
+- Weather
+- Wikipedia Search
 - YouTube Transcript Scraper
 
 For more information on using and creating tools, see the [Atomic Forge README](/atomic-forge/README.md).
@@ -373,7 +387,7 @@ uv sync --all-packages
 
 ## Provider & Model Compatibility
 
-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).
+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, [MiniMax](https://www.minimax.io/), and more. For a complete list, please refer to the Instructor documentation on its [GitHub page](https://github.com/jxnl/instructor).
 
 ## Contributing
 

{atomic_agents-2.7.4 → atomic_agents-2.8.0}/agents.md

@@ -99,10 +99,18 @@ Each example is self-contained and demonstrates specific patterns and capabiliti
 **Philosophy:** Tools are NOT bundled with the framework. Instead, users download individual tools for full control and customization.
 
 **Available Tools:**
+- `arxiv_search/` - Academic paper search via the public arXiv API
+- `bocha_search/` - BoCha web search
 - `calculator/` - Mathematical computation tool
+- `datetime_tool/` - Timezone-aware now / parse / convert / shift / diff
+- `fia_signals/` - Crypto market intelligence (regime, signals, yields, gas, trending, wallet risk)
+- `hackernews_search/` - Hacker News search via the free Algolia API
+- `pdf_reader/` - PDF text + metadata extraction (local file or URL, page-range support)
 - `searxng_search/` - Privacy-focused search integration
 - `tavily_search/` - Tavily API search tool
+- `weather/` - Current conditions and daily/hourly forecast via Open-Meteo (no key)
 - `webpage_scraper/` - Web scraping capabilities
+- `wikipedia_search/` - Wikipedia search in any language edition (no key)
 - `youtube_transcript_scraper/` - YouTube transcript extraction
 
 **Benefits:**

{atomic_agents-2.7.4 → atomic_agents-2.8.0}/atomic-agents/atomic_agents/agents/atomic_agent.py

@@ -8,6 +8,7 @@ from atomic_agents.context.chat_history import ChatHistory
 from atomic_agents.context.system_prompt_generator import (
     BaseDynamicContextProvider,
     SystemPromptGenerator,
+    BaseSystemPromptGenerator,
 )
 from atomic_agents.base.base_io_schema import BaseIOSchema
 from atomic_agents.utils.token_counter import get_token_counter, TokenCountResult
@@ -63,11 +64,15 @@ class BasicChatOutputSchema(BaseIOSchema):
 
 
 class AgentConfig(BaseModel):
-    client: instructor.client.Instructor = Field(..., description="Client for interacting with the language model.")
+    client: instructor.core.client.Instructor = Field(..., description="Client for interacting with the language model.")
     model: str = Field(default="gpt-5-mini", description="The model to use for generating responses.")
     history: Optional[ChatHistory] = Field(default=None, description="History component for storing chat history.")
-    system_prompt_generator: Optional[SystemPromptGenerator] = Field(
-        default=None, description="Component for generating system prompts."
+    system_prompt_generator: Optional[BaseSystemPromptGenerator] = Field(
+        default=None,
+        description=(
+            "Component for generating system prompts. "
+            "Defaults to SystemPromptGenerator if no subclass of BaseSystemPromptGenerator is passed."
+        ),
     )
     system_role: Optional[str] = Field(
         default="system", description="The role of the system in the conversation. None means no system prompt."
@@ -76,9 +81,25 @@ class AgentConfig(BaseModel):
         default="assistant",
         description="The role of the assistant in the conversation. Use 'model' for Gemini, 'assistant' for OpenAI/Anthropic.",
     )
+    tool_result_role: Optional[str] = Field(
+        default=None,
+        description=(
+            "The role to use for mid-conversation tool results and context injections. "
+            "Defaults to 'user' when assistant_role is 'model' (Gemini), otherwise 'system'. "
+            "Set explicitly to override auto-detection."
+        ),
+    )
     model_config = {"arbitrary_types_allowed": True}
     mode: Mode = Field(default=Mode.TOOLS, description="The Instructor mode used for structured outputs (TOOLS, JSON, etc.).")
     model_api_parameters: Optional[dict] = Field(None, description="Additional parameters passed to the API provider.")
+    max_context_tokens: Optional[int] = Field(
+        None,
+        description=(
+            "Maximum tokens for the full context (system prompt + history + tools). "
+            "When exceeded, oldest conversation turns are automatically trimmed to stay within limit. "
+            "Uses LiteLLM's provider-agnostic token counter — works with any supported model."
+        ),
+    )
 
 
 class AtomicAgent[InputSchema: BaseIOSchema, OutputSchema: BaseIOSchema]:
@@ -97,13 +118,15 @@ class AtomicAgent[InputSchema: BaseIOSchema, OutputSchema: BaseIOSchema]:
         client: Client for interacting with the language model.
         model (str): The model to use for generating responses.
         history (ChatHistory): History component for storing chat history.
-        system_prompt_generator (SystemPromptGenerator): Component for generating system prompts.
+        system_prompt_generator (BaseSystemPromptGenerator): Component for generating system prompts.
         system_role (Optional[str]): The role of the system in the conversation. None means no system prompt.
         assistant_role (str): The role of the assistant in the conversation. Use 'model' for Gemini, 'assistant' for OpenAI/Anthropic.
         initial_history (ChatHistory): Initial state of the history.
         current_user_input (Optional[InputSchema]): The current user input being processed.
         model_api_parameters (dict): Additional parameters passed to the API provider.
             - Use this for parameters like 'temperature', 'max_tokens', etc.
+        max_context_tokens (Optional[int]): Maximum tokens for the full context. When exceeded,
+            oldest conversation turns are automatically trimmed. Uses LiteLLM's token counter.
 
     Hook System:
         The AtomicAgent integrates with Instructor's hook system to provide comprehensive monitoring
@@ -170,10 +193,17 @@ class AtomicAgent[InputSchema: BaseIOSchema, OutputSchema: BaseIOSchema]:
         self.system_prompt_generator = config.system_prompt_generator or SystemPromptGenerator()
         self.system_role = config.system_role
         self.assistant_role = config.assistant_role
+        if config.tool_result_role is not None:
+            self.tool_result_role = config.tool_result_role
+        else:
+            # Auto-detect: Gemini drops mid-conversation "system" messages,
+            # so default to "user" for Gemini backends (identified by assistant_role="model")
+            self.tool_result_role = "user" if config.assistant_role == "model" else "system"
         self.initial_history = self.history.copy()
         self.current_user_input = None
         self.mode = config.mode
         self.model_api_parameters = config.model_api_parameters or {}
+        self.max_context_tokens = config.max_context_tokens
 
         # Hook management attributes
         self._hook_handlers: Dict[str, List[Callable]] = {}
@@ -185,6 +215,21 @@ class AtomicAgent[InputSchema: BaseIOSchema, OutputSchema: BaseIOSchema]:
         """
         self.history = self.initial_history.copy()
 
+    def add_tool_result(self, content: BaseIOSchema) -> None:
+        """
+        Adds a tool result or context injection to the chat history using the
+        backend-appropriate role.
+
+        This method should be used instead of ``history.add_message("system", ...)``
+        when injecting tool execution results, resource contents, or other mid-conversation
+        context into the agent's history. It automatically uses the correct role for the
+        configured backend (e.g. ``"user"`` for Gemini, ``"system"`` for OpenAI/Anthropic).
+
+        Args:
+            content (BaseIOSchema): The tool result or context to inject.
+        """
+        self.history.add_message(self.tool_result_role, content)
+
     @property
     def input_schema(self) -> Type[BaseIOSchema]:
         """
@@ -245,9 +290,79 @@ class AtomicAgent[InputSchema: BaseIOSchema, OutputSchema: BaseIOSchema]:
             }
         ]
 
+    def _trim_context(self) -> None:
+        """
+        Trim oldest conversation turns to stay within max_context_tokens limit.
+
+        Called before building the messages list. Uses the full context token count
+        (system prompt + history + tools) via get_context_token_count().
+        Removes oldest turns one at a time until the context fits within the limit.
+
+        Turn-preserving: always removes complete turns, never individual messages.
+
+        Raises:
+            ValueError: If a single turn itself exceeds max_context_tokens.
+        """
+        if self.max_context_tokens is None:
+            return
+
+        result = self.get_context_token_count()
+        total_tokens = result.total
+
+        if total_tokens <= self.max_context_tokens:
+            return
+
+        logger = logging.getLogger(__name__)
+
+        # Collect unique turn_ids in order (oldest first)
+        turn_ids_ordered = []
+        seen = set()
+        for msg in self.history.history:
+            if msg.turn_id and msg.turn_id not in seen:
+                turn_ids_ordered.append(msg.turn_id)
+                seen.add(msg.turn_id)
+
+        # Remove oldest turns until within limit
+        for turn_id in turn_ids_ordered:
+            if total_tokens <= self.max_context_tokens:
+                break
+
+            self.history.delete_turn_id(turn_id)
+            new_result = self.get_context_token_count()
+            removed = total_tokens - new_result.total
+            total_tokens = new_result.total
+            logger.warning(
+                "Context exceeded max_context_tokens (%d). " "Trimmed turn '%s' (%d tokens). New total: %d.",
+                self.max_context_tokens,
+                turn_id,
+                removed,
+                total_tokens,
+            )
+
+        if total_tokens > self.max_context_tokens:
+            raise ValueError(
+                f"max_context_tokens ({self.max_context_tokens}) is smaller than the "
+                f"minimum required for a single turn ({total_tokens} tokens). "
+                "Increase max_context_tokens or reduce system prompt size."
+            )
+
     def _prepare_messages(self):
         self.messages = self._build_system_messages()
-        self.messages += self.history.get_history()
+        history = self.history.get_history()
+        # Remap "system" role messages in history when the backend doesn't support
+        # mid-conversation system messages (e.g. Gemini). The initial system prompt
+        # is built separately via _build_system_messages() and is unaffected.
+        if self.tool_result_role != "system":
+            logger = logging.getLogger(__name__)
+            for msg in history:
+                if msg["role"] == "system":
+                    logger.debug(
+                        "Remapping mid-conversation 'system' message to '%s' "
+                        "(backend does not support mid-conversation system messages).",
+                        self.tool_result_role,
+                    )
+                    msg["role"] = self.tool_result_role
+        self.messages += history
 
     def _get_completion_kwargs(self) -> Dict[str, Any]:
         """
@@ -444,8 +559,12 @@ class AtomicAgent[InputSchema: BaseIOSchema, OutputSchema: BaseIOSchema]:
             OutputSchema: The response from the chat agent.
         """
         assert not isinstance(
-            self.client, instructor.client.AsyncInstructor
+            self.client, instructor.core.client.AsyncInstructor
         ), "The run method is not supported for async clients. Use run_async instead."
+
+        # Trim history BEFORE adding new user message to protect the new input
+        self._trim_context()
+
         if user_input:
             self.history.initialize_turn()
             self.current_user_input = user_input
@@ -477,8 +596,11 @@ class AtomicAgent[InputSchema: BaseIOSchema, OutputSchema: BaseIOSchema]:
             OutputSchema: The final response from the chat agent.
         """
         assert not isinstance(
-            self.client, instructor.client.AsyncInstructor
+            self.client, instructor.core.client.AsyncInstructor
         ), "The run_stream method is not supported for async clients. Use run_async instead."
+
+        self._trim_context()
+
         if user_input:
             self.history.initialize_turn()
             self.current_user_input = user_input
@@ -519,7 +641,10 @@ class AtomicAgent[InputSchema: BaseIOSchema, OutputSchema: BaseIOSchema]:
             NotAsyncIterableError: If used as an async generator (in an async for loop).
                                    Use run_async_stream() method instead for streaming responses.
         """
-        assert isinstance(self.client, instructor.client.AsyncInstructor), "The run_async method is for async clients."
+        assert isinstance(self.client, instructor.core.client.AsyncInstructor), "The run_async method is for async clients."
+
+        self._trim_context()
+
         if user_input:
             self.history.initialize_turn()
             self.current_user_input = user_input
@@ -545,7 +670,8 @@ class AtomicAgent[InputSchema: BaseIOSchema, OutputSchema: BaseIOSchema]:
         Yields:
             OutputSchema: Partial responses from the chat agent.
         """
-        assert isinstance(self.client, instructor.client.AsyncInstructor), "The run_async method is for async clients."
+        assert isinstance(self.client, instructor.core.client.AsyncInstructor), "The run_async method is for async clients."
+        self._trim_context()
         if user_input:
             self.history.initialize_turn()
             self.current_user_input = user_input

{atomic_agents-2.7.4 → atomic_agents-2.8.0}/atomic-agents/atomic_agents/connectors/mcp/mcp_factory.py

@@ -848,7 +848,7 @@ class MCPFactory:
                             if isinstance(content, str):
                                 texts.append(content)
                             elif isinstance(content, dict):
-                                texts.append(content.get("text"))
+                                texts.append(content.get("text", ""))
                             elif getattr(content, "text", None):
                                 texts.append(content.text)  # type: ignore
                             else:

{atomic_agents-2.7.4 → atomic_agents-2.8.0}/atomic-agents/atomic_agents/context/__init__.py

@@ -2,6 +2,7 @@ from .chat_history import Message, ChatHistory
 from .system_prompt_generator import (
     BaseDynamicContextProvider,
     SystemPromptGenerator,
+    BaseSystemPromptGenerator,
 )
 
 __all__ = [
@@ -9,4 +10,5 @@ __all__ = [
     "ChatHistory",
     "SystemPromptGenerator",
     "BaseDynamicContextProvider",
+    "BaseSystemPromptGenerator",
 ]

{atomic_agents-2.7.4 → atomic_agents-2.8.0}/atomic-agents/atomic_agents/context/chat_history.py

@@ -4,7 +4,7 @@ from enum import Enum
 from pathlib import Path
 from typing import Dict, List, Optional, Type
 
-from instructor.multimodal import PDF, Image, Audio
+from instructor.processing.multimodal import PDF, Image, Audio
 from pydantic import BaseModel, Field
 
 from atomic_agents.base.base_io_schema import BaseIOSchema

{atomic_agents-2.7.4 → atomic_agents-2.8.0}/atomic-agents/atomic_agents/context/system_prompt_generator.py

@@ -14,7 +14,19 @@ class BaseDynamicContextProvider(ABC):
         return self.get_info()
 
 
-class SystemPromptGenerator:
+class BaseSystemPromptGenerator(ABC):
+    def __init__(self, context_providers: Optional[Dict[str, BaseDynamicContextProvider]] = None):
+        self.context_providers = context_providers or {}
+
+    @abstractmethod
+    def generate_prompt(self) -> str:
+        pass
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__} (providers={list(self.context_providers)})"
+
+
+class SystemPromptGenerator(BaseSystemPromptGenerator):
     def __init__(
         self,
         background: Optional[List[str]] = None,
@@ -22,10 +34,10 @@ class SystemPromptGenerator:
         output_instructions: Optional[List[str]] = None,
         context_providers: Optional[Dict[str, BaseDynamicContextProvider]] = None,
     ):
+        super().__init__(context_providers=context_providers)
         self.background = background or ["This is a conversation with a helpful and friendly AI assistant."]
         self.steps = steps or []
         self.output_instructions = output_instructions or []
-        self.context_providers = context_providers or {}
 
         self.output_instructions.extend(
             [