Skip to content

Building AI agents, atomically

Organization & readme

KennyVaneetvelde4d571900c07e
diff --git a/atomic_agents/agents/README.md b/atomic_agents/agents/README.md
new file mode 100644
index 0000000..07a9375
--- /dev/null
+++ b/atomic_agents/agents/README.md
@@ -0,0 +1,11 @@
+# Agents
+## Overview
+In the Atomic Agents framework, an agent is a class that can interact with a user or another agent. Agents can be used to handle chat interactions, interface with tools, or perform other specialized tasks. The `BaseChatAgent` class is the base class for all chat agents, and the `ToolInterfaceAgent` class extends the `BaseChatAgent` to add tool interfacing capabilities.
+
+## BaseChatAgent
+The `BaseChatAgent` class serves two primary purposes:
+1. It can be used directly to handle chat interactions.
+2. It can be extended to create more specialized agents either to be re-used such as the `ToolInterfaceAgent` or to create new agents for specific tasks. For examples, see the `examples` directory.
+
+## ToolInterfaceAgent
+The `ToolInterfaceAgent` class extends the `BaseChatAgent` class to add tool interfacing capabilities. It provides a standard interface for interacting with tools such as those in the `atomic_agents.tools` package.
\ No newline at end of file
diff --git a/atomic_agents/agents/base_chat_agent.py b/atomic_agents/agents/base_chat_agent.py
index c105dc4..2d61e5d 100644
--- a/atomic_agents/agents/base_chat_agent.py
+++ b/atomic_agents/agents/base_chat_agent.py
@@ -37,9 +37,37 @@ class GeneralPlanResponse(BaseModel):
'description': description
}
-# Base Chat Agent Class
class BaseChatAgent:
- def __init__(self, client, system_prompt_generator: SystemPromptGenerator = None, model: str = 'gpt-3.5-turbo', memory: ChatMemory = None, include_planning_step = False, input_schema = BaseChatAgentInputSchema, output_schema = BaseChatAgentResponse):
+ """
+ Base class for chat agents.
+
+ This class provides the core functionality for handling chat interactions, including managing memory,
+ generating system prompts, and obtaining responses from a language model.
+
+ Attributes:
+ input_schema (BaseModel): Schema for the input data.
+ output_schema (BaseModel): Schema for the output data.
+ client: Client for interacting with the language model.
+ model (str): The model to use for generating responses.
+ memory (ChatMemory): Memory component for storing chat history.
+ system_prompt_generator (SystemPromptGenerator): Component for generating system prompts.
+ include_planning_step (bool): Whether to include a planning step in the response generation.
+ initial_memory (ChatMemory): Initial state of the memory.
+ """
+
+ def __init__(self, client, system_prompt_generator: SystemPromptGenerator = None, model: str = 'gpt-3.5-turbo', memory: ChatMemory = None, include_planning_step=False, input_schema=BaseChatAgentInputSchema, output_schema=BaseChatAgentResponse):
+ """
+ Initializes the BaseChatAgent.
+
+ Args:
+ client: Client for interacting with the language model.
+ system_prompt_generator (SystemPromptGenerator, optional): Component for generating system prompts. Defaults to None.
+ model (str, optional): The model to use for generating responses. Defaults to 'gpt-3.5-turbo'.
+ memory (ChatMemory, optional): Memory component for storing chat history. Defaults to None.
+ include_planning_step (bool, optional): Whether to include a planning step in the response generation. Defaults to False.
+ input_schema (BaseModel, optional): Schema for the input data. Defaults to BaseChatAgentInputSchema.
+ output_schema (BaseModel, optional): Schema for the output data. Defaults to BaseChatAgentResponse.
+ """
self.input_schema = input_schema
self.output_schema = output_schema
self.client = client
@@ -48,17 +76,35 @@ class BaseChatAgent:
self.system_prompt_generator = system_prompt_generator or SystemPromptGenerator()
self.include_planning_step = include_planning_step
self.initial_memory = self.memory.copy()
-
+
def reset_memory(self):
+ """
+ Resets the memory to its initial state.
+ """
self.memory = self.initial_memory.copy()
-
+
def get_system_prompt(self) -> str:
+ """
+ Generates the system prompt.
+
+ Returns:
+ str: The generated system prompt.
+ """
return self.system_prompt_generator.generate_prompt()
def get_response(self, response_model=None) -> BaseModel:
+ """
+ Obtains a response from the language model.
+
+ Args:
+ response_model (Type[BaseModel], optional): The schema for the response data. If not set, self.output_schema is used.
+
+ Returns:
+ BaseModel: The response from the language model.
+ """
if response_model is None:
response_model = self.output_schema
-
+
messages = [{'role': 'system', 'content': self.get_system_prompt()}] + self.memory.get_history()
response = self.client.chat.completions.create(
model=self.model,
@@ -68,6 +114,15 @@ class BaseChatAgent:
return response
def run(self, user_input: str) -> str:
+ """
+ Runs the chat agent with the given user input.
+
+ Args:
+ user_input (str): The input text from the user.
+
+ Returns:
+ str: The response from the chat agent.
+ """
self._init_run(user_input)
self._pre_run()
if self.include_planning_step:
@@ -75,20 +130,44 @@ class BaseChatAgent:
response = self._get_and_handle_response()
self._post_run(response)
return response
-
+
def _get_and_handle_response(self):
+ """
+ Handles obtaining and processing the response.
+
+ Returns:
+ BaseModel: The processed response.
+ """
return self.get_response(response_model=self.output_schema)
def _plan_run(self):
+ """
+ Executes the planning step, if included.
+ """
self.memory.add_message('assistant', 'I will now note any observations about the relevant input, context and thought process involved in preparing the response.')
plan = self.get_response(response_model=GeneralPlanResponse)
self.memory.add_message('assistant', plan.model_dump_json())
def _init_run(self, user_input):
+ """
+ Initializes the run with the given user input.
+
+ Args:
+ user_input (str): The input text from the user.
+ """
self.memory.add_message('user', user_input)
def _pre_run(self):
+ """
+ Prepares for the run. This method can be overridden by subclasses to add custom pre-run logic.
+ """
pass
-
+
def _post_run(self, response):
+ """
+ Finalizes the run with the given response.
+
+ Args:
+ response (Type[BaseModel]): The response from the chat agent.
+ """
self.memory.add_message('assistant', response.model_dump_json())
\ No newline at end of file
diff --git a/atomic_agents/lib/tools/web_scraping_tool.py b/atomic_agents/lib/tools/web_scraping_tool.py
index bc769a5..a4c310e 100644
--- a/atomic_agents/lib/tools/web_scraping_tool.py
+++ b/atomic_agents/lib/tools/web_scraping_tool.py
@@ -7,19 +7,18 @@ import instructor
import requests
from atomic_agents.lib.tools.base import BaseTool
-from atomic_agents.lib.scraping.url_to_markdown import UrlToMarkdownConverter
-from atomic_agents.lib.scraping.pdf_to_markdown import PdfToMarkdownConverter
-from atomic_agents.lib.models.web_document import WebDocument
+from atomic_agents.lib.utils.scraping.url_to_markdown import UrlToMarkdownConverter
+from atomic_agents.lib.utils.scraping.pdf_to_markdown import PdfToMarkdownConverter
################
# INPUT SCHEMA #
################
-class WebScrapingToolSchema(BaseModel):
- url: str = Field(..., description="URL of the web page to scrape.")
+class ContentScrapingToolSchema(BaseModel):
+ url: str = Field(..., description="URL of the web page or PDF to scrape.")
class Config:
- title = "WebScrapingTool"
- description = "Tool for scraping web pages and converting content to markdown in order to extract information or summarize the content."
+ title = "ContentScrapingTool"
+ description = "Tool for scraping web pages or PDFs and converting content to markdown in order to extract information or summarize the content."
json_schema_extra = {
"title": title,
"description": description
@@ -28,30 +27,30 @@ class WebScrapingToolSchema(BaseModel):
####################
# OUTPUT SCHEMA(S) #
####################
-class WebScrapingResultSchema(BaseModel):
+class ContentScrapingResultSchema(BaseModel):
content: str
metadata: Optional[dict] = None
-class WebScrapingToolOutputSchema(BaseModel):
- result: WebScrapingResultSchema
+class ContentScrapingToolOutputSchema(BaseModel):
+ result: ContentScrapingResultSchema
##############
# TOOL LOGIC #
##############
-class WebScrapingTool(BaseTool):
+class ContentScrapingTool(BaseTool):
"""
- Tool for scraping web pages and converting content to markdown.
+ Tool for scraping web pages or PDFs and converting content to markdown.
Attributes:
- input_schema (WebScrapingToolSchema): The schema for the input data.
- output_schema (WebScrapingToolOutputSchema): The schema for the output data.
+ input_schema (ContentScrapingToolSchema): The schema for the input data.
+ output_schema (ContentScrapingToolOutputSchema): The schema for the output data.
"""
- input_schema = WebScrapingToolSchema
- output_schema = WebScrapingToolOutputSchema
+ input_schema = ContentScrapingToolSchema
+ output_schema = ContentScrapingToolOutputSchema
def __init__(self, *args, **kwargs):
"""
- Initializes the WebScrapingTool.
+ Initializes the ContentScrapingTool.
Args:
*args: Variable length argument list.
@@ -59,15 +58,15 @@ class WebScrapingTool(BaseTool):
"""
super().__init__(*args, **kwargs)
- def run(self, params: WebScrapingToolSchema) -> WebScrapingToolOutputSchema:
+ def run(self, params: ContentScrapingToolSchema) -> ContentScrapingToolOutputSchema:
"""
- Runs the WebScrapingTool with the given parameters.
+ Runs the ContentScrapingTool with the given parameters.
Args:
- params (WebScrapingToolSchema): The input parameters for the tool, adhering to the input schema.
+ params (ContentScrapingToolSchema): The input parameters for the tool, adhering to the input schema.
Returns:
- WebScrapingToolOutputSchema: The output of the tool, adhering to the output schema.
+ ContentScrapingToolOutputSchema: The output of the tool, adhering to the output schema.
"""
url = params.url
response = requests.head(url)
@@ -78,8 +77,8 @@ class WebScrapingTool(BaseTool):
else:
document = UrlToMarkdownConverter.convert(url=url)
- result = WebScrapingResultSchema(content=document.content, metadata=document.metadata.model_dump())
- return WebScrapingToolOutputSchema(result=result)
+ result = ContentScrapingResultSchema(content=document.content, metadata=document.metadata.model_dump())
+ return ContentScrapingToolOutputSchema(result=result)
#################
# EXAMPLE USAGE #
@@ -95,13 +94,25 @@ if __name__ == "__main__":
)
)
- # Extract structured data from natural language
+ # Extract from webpage
result = client.chat.completions.create(
model="gpt-3.5-turbo",
- response_model=WebScrapingTool.input_schema,
+ response_model=ContentScrapingTool.input_schema,
messages=[{"role": "user", "content": "Scrape the content of https://example.com"}],
)
# Print the result
- output = WebScrapingTool().run(result)
+ output = ContentScrapingTool().run(result)
+ rich_console.print(f"Content: {output.result.content}, Metadata: {output.result.metadata}")
+
+
+ # Extract from PDF
+ result = client.chat.completions.create(
+ model="gpt-3.5-turbo",
+ response_model=ContentScrapingTool.input_schema,
+ messages=[{"role": "user", "content": "Scrape the content of https://pdfobject.com/pdf/sample.pdf"}],
+ )
+
+ # Print the result
+ output = ContentScrapingTool().run(result)
rich_console.print(f"Content: {output.result.content}, Metadata: {output.result.metadata}")
\ No newline at end of file
diff --git a/atomic_agents/lib/scraping/__init__.py b/atomic_agents/lib/utils/scraping/__init__.py
similarity index 100%
rename from atomic_agents/lib/scraping/__init__.py
rename to atomic_agents/lib/utils/scraping/__init__.py
diff --git a/atomic_agents/lib/scraping/pdf_to_markdown.py b/atomic_agents/lib/utils/scraping/pdf_to_markdown.py
similarity index 93%
rename from atomic_agents/lib/scraping/pdf_to_markdown.py
rename to atomic_agents/lib/utils/scraping/pdf_to_markdown.py
index 86443db..c47b1cb 100644
--- a/atomic_agents/lib/scraping/pdf_to_markdown.py
+++ b/atomic_agents/lib/utils/scraping/pdf_to_markdown.py
@@ -1,8 +1,6 @@
-import os
import requests
-from pydantic import BaseModel
from PyPDF2 import PdfReader
-from io import BytesIO, StringIO
+from io import BytesIO
import markdownify
from atomic_agents.lib.models.web_document import WebDocument, WebDocumentMetadata
diff --git a/atomic_agents/lib/scraping/url_to_markdown.py b/atomic_agents/lib/utils/scraping/url_to_markdown.py
similarity index 98%
rename from atomic_agents/lib/scraping/url_to_markdown.py
rename to atomic_agents/lib/utils/scraping/url_to_markdown.py
index 2ab0f8e..88e14b6 100644
--- a/atomic_agents/lib/scraping/url_to_markdown.py
+++ b/atomic_agents/lib/utils/scraping/url_to_markdown.py
@@ -2,8 +2,6 @@ import os
from bs4 import BeautifulSoup
import requests
from markdownify import MarkdownConverter
-from pydantic import BaseModel, Field
-
from atomic_agents.lib.models.web_document import WebDocument, WebDocumentMetadata