Building AI agents, atomically
feat(tools): add TavilySearchTool with max_results fix (fix #132/#219)
ueveu97d9940e036b
diff --git a/atomic-forge/atomic_tools/tavily_search/pyproject.toml b/atomic-forge/atomic_tools/tavily_search/pyproject.tomlnew file mode 100644index 0000000..379a599--- /dev/null+++ b/atomic-forge/atomic_tools/tavily_search/pyproject.toml@@ -0,0 +1,16 @@+[project]+name = "atomic-tools-tavily-search"+version = "0.1.0"+description = "Tavily search tool for atomic-agents"+requires-python = ">=3.10"+dependencies = ["aiohttp", "pydantic"]++[project.optional-dependencies]+dev = ["pytest", "pytest-asyncio"]++[build-system]+requires = ["hatchling"]+build-backend = "hatchling.build"++[tool.pytest.ini_options]+asyncio_mode = "auto"diff --git a/atomic-forge/atomic_tools/tavily_search/requirements.txt b/atomic-forge/atomic_tools/tavily_search/requirements.txtnew file mode 100644index 0000000..74408d9--- /dev/null+++ b/atomic-forge/atomic_tools/tavily_search/requirements.txt@@ -0,0 +1,2 @@+aiohttp>=3.9.0+pydantic>=2.0.0diff --git a/atomic-forge/atomic_tools/tavily_search/tests/test_tavily_search.py b/atomic-forge/atomic_tools/tavily_search/tests/test_tavily_search.pynew file mode 100644index 0000000..3e0f3eb--- /dev/null+++ b/atomic-forge/atomic_tools/tavily_search/tests/test_tavily_search.py@@ -0,0 +1,117 @@+from unittest.mock import AsyncMock, MagicMock, patch+import pytest+from tavily_search import TavilySearchTool, TavilySearchToolConfig, TavilySearchToolInputSchema+++def mock_config():+ return TavilySearchToolConfig(api_key="test_api_key", max_results=5)+++def tool(mock_config):+ return TavilySearchTool(config=mock_config)+++class TestTavilySearchTool:+ @pytest.mark.asyncio+ async def test_fetch_search_results_respects_max_results_override(self, tool):+ """Regression test: max_results override must propagate to the API call, not be ignored."""+ mock_session = AsyncMock()+ mock_response = AsyncMock()+ mock_response.status = 200+ mock_response.json = AsyncMock(+ return_value={+ "results": [+ {"title": f"Result {i}", "url": f"http://example.com/{i}", "content": "...", "score": 1.0 - i * 0.1}+ for i in range(5)+ ],+ "answer": "test answer",+ }+ )+ mock_response.reason = "OK"+ mock_session.post = AsyncMock(return_value=mock_response)+ mock_session.__aenter__ = AsyncMock(return_value=mock_session)+ mock_session.__aexit__ = AsyncMock(return_value=None)++ result = await tool._fetch_search_results(mock_session, "test query", max_results=2)++ # The key assertion: the API must have been called with max_results=2, not self.max_results=5+ call_args = mock_session.post.call_args+ json_data = call_args.kwargs["json"]+ assert json_data["max_results"] == 2, "max_results override was ignored in API call"++ @pytest.mark.asyncio+ async def test_run_async_respects_max_results_override(self, tool):+ """Runtime max_results override must reach the API and limit result count."""+ mock_session = AsyncMock()++ async def mock_post(*args, **kwargs):+ max_override = kwargs["json"]["max_results"]+ return AsyncMock(+ status=200,+ reason="OK",+ json=AsyncMock(+ return_value={+ "results": [+ {"title": f"Result {i}", "url": f"http://example.com/{i}", "content": "...", "score": 1.0}+ for i in range(max_override + 3) # Return MORE than requested+ ],+ "answer": "test answer",+ }+ ),+ )++ mock_session.post = mock_post+ mock_session.__aenter__ = AsyncMock(return_value=mock_session)+ mock_session.__aexit__ = AsyncMock(return_value=None)++ params = TavilySearchToolInputSchema(queries=["test query"])+ output = await tool.run_async(params, max_results=2)++ # Should have exactly 2 results since we requested 2, even though API returned 5+ assert len(output.results) == 2+ for call in mock_session.post.call_args_list:+ assert call.kwargs["json"]["max_results"] == 2++ @pytest.mark.asyncio+ async def test_run_async_uses_default_when_no_override(self, tool):+ """When no override is passed, self.max_results should be used."""+ mock_session = AsyncMock()++ async def mock_post(*args, **kwargs):+ return AsyncMock(+ status=200,+ reason="OK",+ json=AsyncMock(+ return_value={+ "results": [+ {"title": f"Result {i}", "url": f"http://example.com/{i}", "content": "...", "score": 1.0}+ for i in range(5)+ ],+ "answer": "test answer",+ }+ ),+ )++ mock_session.post = mock_post+ mock_session.__aenter__ = AsyncMock(return_value=mock_session)+ mock_session.__aexit__ = AsyncMock(return_value=None)++ params = TavilySearchToolInputSchema(queries=["test query"])+ output = await tool.run_async(params) # No max_results override++ for call in mock_session.post.call_args_list:+ assert call.kwargs["json"]["max_results"] == 5 # Should use config default (5)++ def test_init_defaults(self):+ """Default config should set max_results to 5."""+ tool = TavilySearchTool()+ assert tool.max_results == 5+ assert tool.search_depth == "basic"++ def test_config_respects_custom_max_results(self):+ """Config should accept and store custom max_results."""+ config = TavilySearchToolConfig(max_results=10)+ tool = TavilySearchTool(config=config)+ assert tool.max_results == 10diff --git a/atomic-forge/atomic_tools/tavily_search/tool/__init__.py b/atomic-forge/atomic_tools/tavily_search/tool/__init__.pynew file mode 100644index 0000000..8807f5d--- /dev/null+++ b/atomic-forge/atomic_tools/tavily_search/tool/__init__.py@@ -0,0 +1,8 @@+from tavily_search import TavilySearchTool, TavilySearchToolConfig, TavilySearchToolInputSchema, TavilySearchToolOutputSchema++__all__ = [+ "TavilySearchTool",+ "TavilySearchToolConfig",+ "TavilySearchToolInputSchema",+ "TavilySearchToolOutputSchema",+]diff --git a/atomic-forge/atomic_tools/tavily_search/tool/tavily_search.py b/atomic-forge/atomic_tools/tavily_search/tool/tavily_search.pynew file mode 100644index 0000000..a14195b--- /dev/null+++ b/atomic-forge/atomic_tools/tavily_search/tool/tavily_search.py@@ -0,0 +1,171 @@+import os+from typing import List, Literal, Optional+import asyncio+from concurrent.futures import ThreadPoolExecutor++import aiohttp+from pydantic import Field++from atomic_agents import BaseIOSchema, BaseTool, BaseToolConfig+++################+# INPUT SCHEMA #+################+class TavilySearchToolInputSchema(BaseIOSchema):+ """+ Schema for input to a tool for searching for information, news, references, and other content using Tavily.+ Returns a list of search results with a short description or content snippet and URLs for further exploration+ """++ queries: List[str] = Field(..., description="List of search queries.")+++####################+# OUTPUT SCHEMA(S) #+####################+class TavilySearchResultItemSchema(BaseIOSchema):+ """This schema represents a single search result item"""++ title: str = Field(..., description="The title of the search result")+ url: str = Field(..., description="The URL of the search result")+ content: str = Field(None, description="The content snippet of the search result")+ score: float = Field(..., description="The score of the search result")+ raw_content: Optional[str] = Field(None, description="The raw content of the search result")+ query: Optional[str] = Field(..., description="The query used to obtain this search result")+ answer: Optional[str] = Field(..., description="The answer to the query provided by Tavily")+++class TavilySearchToolOutputSchema(BaseIOSchema):+ """This schema represents the output of the Tavily search tool."""++ results: List[TavilySearchResultItemSchema] = Field(..., description="List of search result items")+++##############+# TOOL LOGIC #+##############+class TavilySearchToolConfig(BaseToolConfig):+ api_key: str = ""+ max_results: int = 5+ search_depth: Literal["basic", "advanced"] = "basic"+ include_domains: Optional[List[str]] = None+ exclude_domains: Optional[List[str]] = None+++class TavilySearchTool(BaseTool[TavilySearchToolInputSchema, TavilySearchToolOutputSchema]):+ """+ Tool for performing searches using the Tavily search API.++ Attributes:+ input_schema (TavilySearchToolInputSchema): The schema for the input data.+ output_schema (TavilySearchToolOutputSchema): The schema for the output data.+ max_results (int): The maximum number of search results to return.+ api_key (str): The API key for the Tavily API.+ """++ def __init__(self, config: TavilySearchToolConfig = TavilySearchToolConfig()):+ """+ Initializes the TavilySearchTool.++ Args:+ config (TavilySearchToolConfig):+ Configuration for the tool, including API key, max results, and optional title and description overrides.+ """+ super().__init__(config)+ self.api_key = config.api_key or os.getenv("TAVILY_API_KEY", "")+ self.max_results = config.max_results+ self.search_depth = config.search_depth+ self.include_domains = config.include_domains+ self.exclude_domains = config.exclude_domains+ self.include_answer = False++ async def _fetch_search_results(self, session: aiohttp.ClientSession, query: str, max_results: int) -> dict:+ headers = {+ "accept": "/",+ "content-type": "application/json",+ "origin": "https://app.tavily.com/",+ "referer": "https://app.tavily.com/",+ "user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",+ }++ json_data = {+ "query": query,+ "api_key": self.api_key,+ "search_depth": self.search_depth,+ "include_domains": self.include_domains,+ "exclude_domains": self.exclude_domains,+ "max_results": max_results,+ "include_answer": self.include_answer,+ }++ async with session.post("https://api.tavily.com/search", headers=headers, json=json_data) as response:+ if response.status != 200:+ error_message = await response.text()+ raise Exception(+ f"Failed to fetch search results for query '{query}': {response.status} {response.reason}. Details: {error_message}"+ )+ data = await response.json()++ results = data.get("results", [])+ answer = data.get("answer", "")++ for result in results:+ result["query"] = query++ return {"results": results, "answer": answer}++ async def run_async(+ self, params: TavilySearchToolInputSchema, max_results: Optional[int] = None+ ) -> TavilySearchToolOutputSchema:+ effective_max_results = self.max_results if max_results is None else max_results++ async with aiohttp.ClientSession() as session:+ tasks = [self._fetch_search_results(session, query, effective_max_results) for query in params.queries]+ raw_responses = await asyncio.gather(*tasks)++ processed_results = []+ for response in raw_responses:+ query_results = response["results"]+ answer = response["answer"]++ query_processed = []+ for result in query_results:+ if all(key in result for key in ["title", "url", "content", "score"]):+ query_processed.append(+ TavilySearchResultItemSchema(+ title=result["title"],+ url=result["url"],+ content=result.get("content", ""),+ score=result.get("score", 0),+ raw_content=result.get("raw_content"),+ query=result.get("query"),+ answer=answer,+ )+ )+ else:+ print(f"Skipping result due to missing keys: {result}")++ query_processed = query_processed[:effective_max_results]+ processed_results.extend(query_processed)++ return TavilySearchToolOutputSchema(results=processed_results)++ def run(self, params: TavilySearchToolInputSchema, max_results: Optional[int] = None) -> TavilySearchToolOutputSchema:+ """+ Runs the TavilyTool synchronously with the given parameters.++ Args:+ params (TavilySearchToolInputSchema): The input parameters for the tool, adhering to the input schema.+ max_results (Optional[int]): The maximum number of search results to return.++ Returns:+ TavilySearchToolOutputSchema: The output of the tool, adhering to the output schema.+ """+ with ThreadPoolExecutor() as executor:+ result = executor.submit(+ asyncio.run,+ self.run_async(params, max_results),+ ).result()++ return result