Building AI agents, atomically
Added, renamed and consolidated methods in BaseModel
Koichi KAWAMURAe3041f5a0987
diff --git a/atomic-agents/atomic_agents/agents/base_agent.py b/atomic-agents/atomic_agents/agents/base_agent.pyindex a2a8360..993710c 100644--- a/atomic-agents/atomic_agents/agents/base_agent.py+++ b/atomic-agents/atomic_agents/agents/base_agent.py@@ -1,6 +1,7 @@import instructorfrom pydantic import BaseModel, Field-from typing import Optional, Type+from typing import Optional, Type, TypeVar, Generator, AsyncGenerator+import warningsfrom atomic_agents.lib.components.agent_memory import AgentMemoryfrom atomic_agents.lib.components.system_prompt_generator import (SystemPromptContextProviderBase,@@ -10,7 +11,6 @@ from atomic_agents.lib.base.base_io_schema import BaseIOSchemafrom instructor.dsl.partial import PartialBasefrom jiter import from_json-import warningsdef model_from_chunks_patched(cls, json_chunks, **kwargs):@@ -82,6 +82,10 @@ class BaseAgentConfig(BaseModel):model_api_parameters: Optional[dict] = Field(None, description="Additional parameters passed to the API provider.")+TI = TypeVar("TI", bound=BaseIOSchema) # InputSchema+TO = TypeVar("TO", bound=BaseIOSchema) # OutputSchema++class BaseAgent:"""Base class for chat agents.@@ -145,7 +149,7 @@ class BaseAgent:"""self.memory = self.initial_memory.copy()- def prepare_messages(self):+ def _prepare_messages(self):if self.system_role is None:self.messages = []else:@@ -158,66 +162,51 @@ class BaseAgent:self.messages += self.memory.get_history()- def get_response(self, response_model=None) -> Type[BaseModel]:- """- Obtains a response from the language model synchronously.-- Args:- response_model (Type[BaseModel], optional):- The schema for the response data. If not set, self.output_schema is used.-- Returns:- Type[BaseModel]: The response from the language model.- """- if response_model is None:- response_model = self.output_schema-- self.prepare_messages()- response = self.client.chat.completions.create(- messages=self.messages,- model=self.model,- response_model=response_model,- **self.model_api_parameters,- )-- return response-- def run(self, user_input: Optional[BaseIOSchema] = None) -> BaseIOSchema:+ def run(self, user_input: Optional[TI] = None) -> TO:"""Runs the chat agent with the given user input synchronously.Args:- user_input (Optional[BaseIOSchema]): The input from the user. If not provided, skips adding to memory.+ user_input (Optional[TI]): The input from the user. If not provided, skips adding to memory.Returns:- BaseIOSchema: The response from the chat agent.+ TO: The response from the chat agent."""if user_input:self.memory.initialize_turn()self.current_user_input = user_inputself.memory.add_message("user", user_input)- response = self.get_response(response_model=self.output_schema)+ self._prepare_messages()+ response = self.client.chat.completions.create(+ messages=self.messages,+ model=self.model,+ response_model=self.output_schema,+ **self.model_api_parameters,+ )self.memory.add_message("assistant", response)return response- async def run_async(self, user_input: Optional[BaseIOSchema] = None):+ def run_stream(self, user_input: Optional[TI] = None) -> Generator[TO, None, TO]:"""- Runs the chat agent with the given user input, supporting streaming output asynchronously.+ Runs the chat agent with the given user input, supporting streaming output.Args:- user_input (Optional[BaseIOSchema]): The input from the user. If not provided, skips adding to memory.+ user_input (Optional[TI]): The input from the user. If not provided, skips adding to memory.Yields:- BaseModel: Partial responses from the chat agent.+ TO: Partial responses from the chat agent.++ Returns:+ TO: The final response from the chat agent."""if user_input:self.memory.initialize_turn()self.current_user_input = user_inputself.memory.add_message("user", user_input)- self.prepare_messages()+ self._prepare_messages()response_stream = self.client.chat.completions.create_partial(model=self.model,@@ -227,28 +216,34 @@ class BaseAgent:stream=True,)- async for partial_response in response_stream:+ for partial_response in response_stream:yield partial_responsefull_response_content = self.output_schema(**partial_response.model_dump())self.memory.add_message("assistant", full_response_content)- async def run_async_batch(self, user_input: Optional[BaseIOSchema] = None) -> BaseIOSchema:+ return full_response_content++ async def run_async(self, user_input: Optional[TI] = None) -> TO:"""- Runs the chat agent with the given user input, supporting streaming output asynchronously.+ Runs the chat agent asynchronously with the given user input.Args:- user_input (Optional[BaseIOSchema]): The input from the user. If not provided, skips adding to memory.+ user_input (Optional[TI]): The input from the user. If not provided, skips adding to memory.Returns:- BaseIOSchema: Partial responses from the chat agent.+ TO: The response from the chat agent.++ Raises:+ NotAsyncIterableError: If used as an async generator (in an async for loop).+ Use run_async_stream() method instead for streaming responses."""if user_input:self.memory.initialize_turn()self.current_user_input = user_inputself.memory.add_message("user", user_input)- self.prepare_messages()+ self._prepare_messages()response = await self.client.chat.completions.create(model=self.model, messages=self.messages, response_model=self.output_schema, **self.model_api_parameters@@ -257,9 +252,43 @@ class BaseAgent:self.memory.add_message("assistant", response)return response+ async def run_async_stream(self, user_input: Optional[TI] = None) -> AsyncGenerator[TO, None]:+ """+ Runs the chat agent asynchronously with the given user input, supporting streaming output.++ Args:+ user_input (Optional[TI]): The input from the user. If not provided, skips adding to memory.++ Yields:+ TO: Partial responses from the chat agent.+ """+ if user_input:+ self.memory.initialize_turn()+ self.current_user_input = user_input+ self.memory.add_message("user", user_input)++ self._prepare_messages()++ response_stream = self.client.chat.completions.create_partial(+ model=self.model,+ messages=self.messages,+ response_model=self.output_schema,+ **self.model_api_parameters,+ stream=True,+ )++ last_response = None+ async for partial_response in response_stream:+ last_response = partial_response+ yield partial_response++ if last_response:+ full_response_content = self.output_schema(**last_response.model_dump())+ self.memory.add_message("assistant", full_response_content)+async def stream_response_async(self, user_input: Optional[Type[BaseIOSchema]] = None):"""- Deprecated method for streaming responses asynchronously. Use run_async instead.+ Deprecated method for streaming responses asynchronously. Use run_async_stream instead.Args:user_input (Optional[Type[BaseIOSchema]]): The input from the user. If not provided, skips adding to memory.@@ -268,11 +297,11 @@ class BaseAgent:BaseModel: Partial responses from the chat agent."""warnings.warn(- "stream_response_async is deprecated and will be removed in version 1.1. Use run_async instead which can be used in the exact same way.",+ "stream_response_async is deprecated and will be removed in version 1.1. Use run_async_stream instead.",DeprecationWarning,stacklevel=2,)- async for response in self.run_async(user_input):+ async for response in self.run_async_stream(user_input):yield responsedef get_context_provider(self, provider_name: str) -> Type[SystemPromptContextProviderBase]:@@ -441,7 +470,8 @@ if __name__ == "__main__":console.print("[bold blue]Assistant:[/bold blue]")if streaming:with Live(console=console, refresh_per_second=4) as live:- async for partial_response in agent.run_async(user_input):+ # Use run_async_stream instead of run_async for streaming responses+ async for partial_response in agent.run_async_stream(user_input):response_json = partial_response.model_dump()json_str = json.dumps(response_json, indent=2)live.update(json_str)diff --git a/atomic-agents/tests/agents/test_base_agent.py b/atomic-agents/tests/agents/test_base_agent.pyindex 95bb356..99cacae 100644--- a/atomic-agents/tests/agents/test_base_agent.py+++ b/atomic-agents/tests/agents/test_base_agent.py@@ -18,15 +18,27 @@ from instructor.dsl.partial import PartialBase@pytest.fixturedef mock_instructor():mock = Mock(spec=instructor.Instructor)- mock.chat.completions.create = Mock()- mock.chat.completions.create_partial = Mock()+ # Set up the nested mock structure+ mock.chat = Mock()+ mock.chat.completions = Mock()+ mock.chat.completions.create = Mock(return_value=BaseAgentOutputSchema(chat_message="Test output"))++ # Make create_partial return an iterable+ mock_response = BaseAgentOutputSchema(chat_message="Test output")+ mock_iter = Mock()+ mock_iter.__iter__ = Mock(return_value=iter([mock_response]))+ mock.chat.completions.create_partial.return_value = mock_iter+return mock@pytest.fixturedef mock_instructor_async():mock = Mock(spec=instructor.Instructor)- mock.chat.completions.create = Mock()++ # Configure chat.completions structure+ mock.chat = Mock()+ mock.chat.completions = Mock()# Make create method awaitable by using an async functionasync def mock_create(*args, **kwargs):@@ -36,9 +48,10 @@ def mock_instructor_async():# Mock the create_partial method to return an async generatorasync def mock_create_partial(*args, **kwargs):- yield BaseAgentOutputSchema(chat_message="Mocked response")+ yield BaseAgentOutputSchema(chat_message="Test output")mock.chat.completions.create_partial = mock_create_partial+return mock@@ -75,6 +88,21 @@ def agent(agent_config):return BaseAgent(agent_config)+def agent_config_async(mock_instructor_async, mock_memory, mock_system_prompt_generator):+ return BaseAgentConfig(+ client=mock_instructor_async,+ model="gpt-4o-mini",+ memory=mock_memory,+ system_prompt_generator=mock_system_prompt_generator,+ )+++def agent_async(agent_config_async):+ return BaseAgent(agent_config_async)++def test_initialization(agent, mock_instructor, mock_memory, mock_system_prompt_generator):assert agent.client == mock_instructorassert agent.model == "gpt-4o-mini"@@ -135,7 +163,7 @@ def test_initialization_system_role_equals_developer(mock_instructor, mock_memormodel_api_parameters={}, # No temperature specified)agent = BaseAgent(config)- _ = agent.get_response()+ _ = agent._prepare_messages()assert isinstance(agent.messages, list) and agent.messages[0]["role"] == "developer"@@ -149,7 +177,7 @@ def test_initialization_system_role_equals_None(mock_instructor, mock_memory, momodel_api_parameters={}, # No temperature specified)agent = BaseAgent(config)- _ = agent.get_response()+ _ = agent._prepare_messages()assert isinstance(agent.messages, list) and len(agent.messages) == 0@@ -160,24 +188,6 @@ def test_reset_memory(agent, mock_memory):mock_memory.copy.assert_called_once()-def test_get_response(agent, mock_instructor, mock_memory, mock_system_prompt_generator):- mock_memory.get_history.return_value = [{"role": "user", "content": "Hello"}]- mock_system_prompt_generator.generate_prompt.return_value = "System prompt"-- mock_response = Mock(spec=BaseAgentOutputSchema)- mock_instructor.chat.completions.create.return_value = mock_response-- response = agent.get_response()-- assert response == mock_response-- mock_instructor.chat.completions.create.assert_called_once_with(- model="gpt-4o-mini",- messages=[{"role": "system", "content": "System prompt"}, {"role": "user", "content": "Hello"}],- response_model=BaseAgentOutputSchema,- )--def test_get_context_provider(agent, mock_system_prompt_generator):mock_provider = Mock(spec=SystemPromptContextProviderBase)mock_system_prompt_generator.context_providers = {"test_provider": mock_provider}@@ -239,20 +249,6 @@ def test_base_agent_io_str_and_rich():assert test_io.__rich__() is not None # Just check if it returns something, as we can't easily compare Rich objects-def test_run(agent, mock_memory):- mock_input = BaseAgentInputSchema(chat_message="Test input")- mock_output = BaseAgentOutputSchema(chat_message="Test output")-- agent.get_response = Mock(return_value=mock_output)-- result = agent.run(mock_input)-- assert result == mock_output- assert agent.current_user_input == mock_input-- mock_memory.add_message.assert_has_calls([call("user", mock_input), call("assistant", mock_output)])--def test_base_io_schema_empty_docstring():with pytest.raises(ValueError, match="must have a non-empty docstring"):@@ -276,79 +272,108 @@ def test_base_io_schema_model_json_schema_no_description():assert schema["description"] == "Test schema docstring."-async def test_run_async(agent, mock_memory):+def test_run(agent, mock_memory):+ # Use the agent fixture that's already configured correctlymock_input = BaseAgentInputSchema(chat_message="Test input")- mock_output = BaseAgentOutputSchema(chat_message="Test output")- # Create a mock async generator that properly sets current_user_input and adds messages- async def mock_run_async(*args, **kwargs):- agent.memory.initialize_turn()- agent.current_user_input = mock_input- agent.memory.add_message("user", mock_input)- yield mock_output- agent.memory.add_message("assistant", mock_output)-- # Replace run_async with our mock- agent.run_async = mock_run_async-- # Collect all responses from the generator- responses = []- async for response in agent.run_async(mock_input):- responses.append(response)+ result = agent.run(mock_input)- assert responses == [mock_output]+ # Assertions+ assert result.chat_message == "Test output"assert agent.current_user_input == mock_input- mock_memory.add_message.assert_has_calls([call("user", mock_input), call("assistant", mock_output)])+ mock_memory.add_message.assert_has_calls([call("user", mock_input), call("assistant", result)])-async def test_run_async_batch(mock_instructor_async, mock_memory):++def test_run_stream(mock_instructor, mock_memory):# Create a BaseAgentConfig with system_role set to Noneconfig = BaseAgentConfig(- client=mock_instructor_async,+ client=mock_instructor,model="gpt-4o-mini",memory=mock_memory,system_prompt_generator=None, # No system prompt generator)agent = BaseAgent(config)+ mock_input = BaseAgentInputSchema(chat_message="Test input")+ mock_output = BaseAgentOutputSchema(chat_message="Test output")++ for result in agent.run_stream(mock_input):+ pass++ assert result == mock_output+ assert agent.current_user_input == mock_input++ mock_memory.add_message.assert_has_calls([call("user", mock_input), call("assistant", mock_output)])+++async def test_run_async(agent_async, mock_memory):# Create a mock inputmock_input = BaseAgentInputSchema(chat_message="Test input")mock_output = BaseAgentOutputSchema(chat_message="Test output")- # Get response from run_async_batch method- response = await agent.run_async_batch(mock_input)+ # Get response from run_async method+ response = await agent_async.run_async(mock_input)# Assertions- assert response == mock_output # Ensure self.messages was set to an empty list+ assert response == mock_output+ assert agent_async.current_user_input == mock_input+ mock_memory.add_message.assert_has_calls([call("user", mock_input), call("assistant", mock_output)])@pytest.mark.asyncio-async def test_stream_response_async(agent, mock_memory, mock_instructor, mock_system_prompt_generator):+async def test_run_async_stream(agent_async, mock_memory):+ # Create a mock inputmock_input = BaseAgentInputSchema(chat_message="Test input")- mock_memory.get_history.return_value = [{"role": "user", "content": "Hello"}]- mock_system_prompt_generator.generate_prompt.return_value = "System prompt"+ mock_output = BaseAgentOutputSchema(chat_message="Test output")- partial_responses = [- BaseAgentOutputSchema(chat_message="Partial response 1"),- BaseAgentOutputSchema(chat_message="Partial response 2"),- BaseAgentOutputSchema(chat_message="Final response"),- ]+ responses = []+ # Get response from run_async_stream method+ async for response in agent_async.run_async_stream(mock_input):+ responses.append(response)- async def mock_create_partial(*args, **kwargs):- for response in partial_responses:- yield response+ # Assertions+ assert len(responses) == 1+ assert responses[0] == mock_output+ assert agent_async.current_user_input == mock_input++ # Verify that both user input and assistant response were added to memory+ mock_memory.add_message.assert_any_call("user", mock_input)++ # Create the expected full response content to check+ full_response_content = agent_async.output_schema(**responses[0].model_dump())+ mock_memory.add_message.assert_any_call("assistant", full_response_content)+++async def test_stream_response_async(agent, mock_memory, mock_instructor_async, mock_system_prompt_generator):+ # Replace the agent's client with the async version+ agent.client = mock_instructor_async++ mock_input = BaseAgentInputSchema(chat_message="Test input")+ mock_output = BaseAgentOutputSchema(chat_message="Test output")++ # Since stream_response_async is deprecated and now just wraps run_async_stream,+ # we need to mock run_async_stream directly++ # Create a simple async generator for testing+ async def mock_async_gen():+ yield mock_output- mock_instructor.chat.completions.create_partial = mock_create_partial+ # Mock the run_async_stream method+ agent.run_async_stream = Mock(return_value=mock_async_gen())responses = []async for partial_response in agent.stream_response_async(mock_input):responses.append(partial_response)- assert responses == partial_responses+ # Verify run_async_stream was called+ agent.run_async_stream.assert_called_once_with(mock_input)- mock_memory.add_message.assert_called_with("assistant", partial_responses[-1])+ # Verify we got the expected response+ assert len(responses) == 1+ assert responses[0] == mock_outputdef test_model_from_chunks_patched():diff --git a/atomic-examples/quickstart/quickstart/1_1_basic_chatbot_streaming.py b/atomic-examples/quickstart/quickstart/1_1_basic_chatbot_streaming.pyindex 7c5aa46..5c44f1e 100644--- a/atomic-examples/quickstart/quickstart/1_1_basic_chatbot_streaming.py+++ b/atomic-examples/quickstart/quickstart/1_1_basic_chatbot_streaming.py@@ -67,7 +67,8 @@ async def main():# Use Live display to show streaming responsewith Live("", refresh_per_second=10, auto_refresh=True) as live:current_response = ""- async for partial_response in agent.run_async(input_schema):+ # Use run_async_stream instead of run_async for streaming functionality+ async for partial_response in agent.run_async_stream(input_schema):if hasattr(partial_response, "chat_message") and partial_response.chat_message:# Only update if we have new contentif partial_response.chat_message != current_response:diff --git a/atomic-examples/quickstart/quickstart/1_2_basic_chatbot_sync_streaming.py b/atomic-examples/quickstart/quickstart/1_2_basic_chatbot_sync_streaming.pynew file mode 100644index 0000000..e8c1114--- /dev/null+++ b/atomic-examples/quickstart/quickstart/1_2_basic_chatbot_sync_streaming.py@@ -0,0 +1,98 @@+import os+import instructor+import openai+from rich.console import Console+from rich.panel import Panel+from rich.text import Text+from atomic_agents.lib.components.agent_memory import AgentMemory+from atomic_agents.agents.base_agent import BaseAgent, BaseAgentConfig, BaseAgentInputSchema, BaseAgentOutputSchema++# API Key setup+API_KEY = ""+if not API_KEY:+ 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."+ )++# Initialize a Rich Console for pretty console outputs+console = Console()++# Memory setup+memory = AgentMemory()++# Initialize memory with an initial message from the assistant+initial_message = BaseAgentOutputSchema(chat_message="Hello! How can I assist you today?")+memory.add_message("assistant", initial_message)++# OpenAI client setup using the Instructor library for synchronous operations+client = instructor.from_openai(openai.OpenAI(api_key=API_KEY))++# Agent setup with specified configuration+agent = BaseAgent(+ config=BaseAgentConfig(+ client=client,+ model="gpt-4o-mini",+ memory=memory,+ )+)++# Generate the default system prompt for the agent+default_system_prompt = agent.system_prompt_generator.generate_prompt()+# Display the system prompt in a styled panel+console.print(Panel(default_system_prompt, width=console.width, style="bold cyan"), style="bold cyan")++# Display the initial message from the assistant+console.print(Text("Agent:", style="bold green"), end=" ")+console.print(Text(initial_message.chat_message, style="green"))+++def main():+ """+ Main function to handle the chat loop using synchronous streaming.+ This demonstrates how to use BaseAgent.run_stream() instead of the async version.+ """+ # Start an infinite loop to handle user inputs and agent responses+ while True:+ # Prompt the user for input with a styled prompt+ user_input = console.input("\n[bold blue]You:[/bold blue] ")+ # Check if the user wants to exit the chat+ if user_input.lower() in ["/exit", "/quit"]:+ console.print("Exiting chat...")+ break++ # Process the user's input through the agent+ input_schema = BaseAgentInputSchema(chat_message=user_input)+ console.print() # Add newline before response+ console.print(Text("Agent: ", style="bold green"), end="")++ # Current display string to avoid repeating output+ current_display = ""++ # Use run_stream for synchronous streaming responses+ for partial_response in agent.run_stream(input_schema):+ if hasattr(partial_response, "chat_message") and partial_response.chat_message:+ # Only output the incremental part of the message+ new_content = partial_response.chat_message+ if new_content != current_display:+ # Only print the new part since the last update+ if new_content.startswith(current_display):+ incremental_text = new_content[len(current_display) :]+ console.print(Text(incremental_text, style="green"), end="")+ current_display = new_content+ else:+ # If there's a mismatch, print the full message+ # (this should rarely happen with most LLMs)+ console.print(Text(new_content, style="green"), end="")+ current_display = new_content++ # Flush to ensure output is displayed immediately+ console.file.flush()++ console.print() # Add a newline after the response is complete+++if __name__ == "__main__":+ main()diff --git a/atomic-examples/quickstart/quickstart/3_1_basic_custom_chatbot_with_custom_schema_streaming.py b/atomic-examples/quickstart/quickstart/3_1_basic_custom_chatbot_with_custom_schema_streaming.pyindex 14b0aae..fb2d5d7 100644--- a/atomic-examples/quickstart/quickstart/3_1_basic_custom_chatbot_with_custom_schema_streaming.py+++ b/atomic-examples/quickstart/quickstart/3_1_basic_custom_chatbot_with_custom_schema_streaming.py@@ -113,7 +113,7 @@ async def main():current_response = ""current_questions: List[str] = []- async for partial_response in agent.run_async(input_schema):+ async for partial_response in agent.run_async_stream(input_schema):if hasattr(partial_response, "chat_message") and partial_response.chat_message:# Update the message partif partial_response.chat_message != current_response:diff --git a/atomic-examples/quickstart/quickstart/6_asynchronous_processing.py b/atomic-examples/quickstart/quickstart/6_asynchronous_processing.pyindex f169091..058656d 100644--- a/atomic-examples/quickstart/quickstart/6_asynchronous_processing.py+++ b/atomic-examples/quickstart/quickstart/6_asynchronous_processing.py@@ -3,6 +3,8 @@ import asyncioimport instructorimport openaifrom rich.console import Console+from rich.live import Live+from rich.text import Textfrom atomic_agents.agents.base_agent import BaseIOSchema, BaseAgent, BaseAgentConfig, BaseAgentInputSchemafrom atomic_agents.lib.components.system_prompt_generator import SystemPromptGenerator@@ -64,7 +66,7 @@ async def exec_agent(message: str):user_input = BaseAgentInputSchema(chat_message=message)agent.reset_memory()partial_response = None- async for partial_response in agent.run_async(user_input):+ async for partial_response in agent.run_async_stream(user_input):passassert partial_response@@ -84,5 +86,21 @@ async def process(dataset: list[str]):return responses-responses = asyncio.run(process(dataset))-console.print(responses)+async def main():+ # Get input from the user+ user_input_text = console.input("[bold blue]You:[/bold blue] ")+ user_input = BaseAgentInputSchema(chat_message=user_input_text)++ console.print("\n[bold green]Agent (streaming):[/bold green]")++ # Use Live display to show the streaming response+ with Live(auto_refresh=True, refresh_per_second=10) as live:+ # Use run_async_stream instead of run_async for streaming functionality+ async for partial_response in agent.run_async_stream(user_input):+ # Display the partial response+ if partial_response.chat_message:+ live.update(Text(partial_response.chat_message))+++if __name__ == "__main__":+ asyncio.run(main())diff --git a/atomic-examples/quickstart/quickstart/7_asynchronous_processing_batch.py b/atomic-examples/quickstart/quickstart/7_asynchronous_processing_batch.pyindex c374e8c..aa71a10 100644--- a/atomic-examples/quickstart/quickstart/7_asynchronous_processing_batch.py+++ b/atomic-examples/quickstart/quickstart/7_asynchronous_processing_batch.py@@ -63,7 +63,7 @@ async def exec_agent(message: str):"""Execute the agent with the provided message."""user_input = BaseAgentInputSchema(chat_message=message)agent.reset_memory()- response = await agent.run_async_batch(user_input)+ response = await agent.run_async(user_input)return response