Building AI agents, atomically
Add Firecrawl Search tool to the Atomic Forge
Juampi160100897917
diff --git a/AGENTS.md b/AGENTS.mdindex ac320a4..688aa82 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -100,6 +100,7 @@ Each example is self-contained and demonstrates specific patterns and capabiliti- `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)+- `firecrawl_search/` - Web and news search via the Firecrawl API, with optional page content as Markdown- `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 integrationdiff --git a/README.md b/README.mdindex 270f558..eaa6a16 100644--- a/README.md+++ b/README.md@@ -349,6 +349,7 @@ Atomic Forge is a collection of tools that can be used with Atomic Agents to ext- Calculator- DateTime- Fía Signals+- Firecrawl Search- Hacker News Search- PDF Reader- SearXNG Searchdiff --git a/atomic-forge/README.md b/atomic-forge/README.mdindex d34c5a0..1930426 100644--- a/atomic-forge/README.md+++ b/atomic-forge/README.md@@ -18,6 +18,7 @@ The Atomic Forge project includes the following tools:- [Calculator](/atomic-forge/tools/calculator/README.md)- [DateTime](/atomic-forge/tools/datetime_tool/README.md) — timezone-aware now/parse/convert/shift/diff.- [Fía Signals](/atomic-forge/tools/fia_signals/README.md)+- [Firecrawl Search](/atomic-forge/tools/firecrawl_search/README.md) — web and news search via the Firecrawl API, with optional page content as Markdown.- [Hacker News Search](/atomic-forge/tools/hackernews_search/README.md) — search HN stories, comments, Show HN, Ask HN via the free Algolia API.- [PDF Reader](/atomic-forge/tools/pdf_reader/README.md) — extract text and metadata from a local or remote PDF, with page-range filtering.- [SearXNG Search](/atomic-forge/tools/searxng_search/README.md)diff --git a/atomic-forge/tools/firecrawl_search/.coveragerc b/atomic-forge/tools/firecrawl_search/.coveragercnew file mode 100644index 0000000..c45136e--- /dev/null+++ b/atomic-forge/tools/firecrawl_search/.coveragerc@@ -0,0 +1,8 @@+[run]+source = tool+omit = */tests/*++[report]+exclude_lines =+ if __name__ == "__main__":+show_missing = Truediff --git a/atomic-forge/tools/firecrawl_search/README.md b/atomic-forge/tools/firecrawl_search/README.mdnew file mode 100644index 0000000..74b1782--- /dev/null+++ b/atomic-forge/tools/firecrawl_search/README.md@@ -0,0 +1,61 @@+# Firecrawl Search Tool++## Overview+Searches the web or recent news through the [Firecrawl Search](https://www.firecrawl.dev/search) API and returns each result's title, URL, snippet, and rank, plus the publish date for news. With `include_content=True` the main content of each result page also comes back as Markdown in the same call, so an agent does not need a separate fetch step to read the pages. Requires a Firecrawl API key.++## Prerequisites and Dependencies+- Python 3.12 or later+- `atomic-agents`+- `pydantic`+- `aiohttp`+- A Firecrawl API key from [firecrawl.dev/app/api-keys](https://www.firecrawl.dev/app/api-keys), set as `FIRECRAWL_API_KEY` or passed in the config++## Installation+1. Use the Atomic Assembler CLI: run `atomic` and pick `firecrawl_search`.+2. Or copy the `tool/` folder directly into your project.++## Configuration+- `api_key` (str): Firecrawl API key. Falls back to the `FIRECRAWL_API_KEY` environment variable when empty.+- `base_url` (str): API base URL (default `https://api.firecrawl.dev/v2`).+- `location` (str, optional): location to localise results, e.g. `Germany`.+- `time_range` (str, optional): `day`, `week`, `month`, or `year`. Only applies to web results.+- `max_content_chars` (int, optional): truncate each result's `content` to this many characters. No limit by default.+- `timeout` (float): HTTP timeout in seconds (default 75, since requests with `include_content` fetch each page).++## Input & Output Structure++### Input Schema+- `queries` (list[str]): search queries to run. Operators such as `site:`, `"exact phrase"`, `-term`, and `filetype:pdf` are supported.+- `search_type` (str): `web` or `news`. Default `web`.+- `max_results_per_query` (int): 1-100 (default 5, kept low because each result can carry a full page with `include_content`).+- `include_content` (bool): also return each result page as Markdown (default `False`).++### Output Schema+A list of `FirecrawlSearchResultItem` items. Each has `query`, `title`, `url`, and optional `description` (a query-relevant excerpt or snippet), `position`, `published` (news), and `content` (Markdown, when `include_content` is set).++## Usage+If every query fails (for example a wrong API key), `run` raises the error. If only some fail, the others are returned and the failures are logged.++```python+from tool.firecrawl_search import FirecrawlSearchTool, FirecrawlSearchToolConfig, FirecrawlSearchToolInputSchema++tool = FirecrawlSearchTool(config=FirecrawlSearchToolConfig(api_key="your-firecrawl-api-key"))++output = tool.run(FirecrawlSearchToolInputSchema(+ queries=["retrieval augmented generation"],+ max_results_per_query=3,+ include_content=True,+))++for item in output.results:+ print(item.title, "-", item.url)+ print(item.content[:500] if item.content else item.description)+```++The request and response formats are documented at [docs.firecrawl.dev/features/search](https://docs.firecrawl.dev/features/search).++## Contributing+PRs welcome. See the main repo `CONTRIBUTING.md`.++## License+Same as the main Atomic Agents project.diff --git a/atomic-forge/tools/firecrawl_search/pyproject.toml b/atomic-forge/tools/firecrawl_search/pyproject.tomlnew file mode 100644index 0000000..efdc59a--- /dev/null+++ b/atomic-forge/tools/firecrawl_search/pyproject.toml@@ -0,0 +1,34 @@+[build-system]+requires = ["hatchling"]+build-backend = "hatchling.build"++[tool.hatch.build.targets.wheel]+packages = ["tool"]++[project]+name = "firecrawl-search"+version = "1.0.0"+description = "Web and news search for Atomic Agents via the Firecrawl Search API, with optional page content"+readme = "README.md"+authors = [+ { name = "Juampi (Firecrawl)", email = "[email protected]" }+]+requires-python = ">=3.12"+dependencies = [+ "atomic-agents",+ "pydantic>=2.10.3,<3.0.0",+ "aiohttp>=3.9.0,<4.0.0",+]++[dependency-groups]+dev = [+ "coverage>=7.6.1,<8.0.0",+ "pytest>=8.3.3,<9.0.0",+ "pytest-asyncio>=0.23.5,<1.0.0",+ "pytest-cov>=5.0.0,<6.0.0",+ "python-dotenv>=1.0.0,<2.0.0",+ "rich>=13.7.0,<14.0.0",+]++[tool.uv.sources]+atomic-agents = { workspace = true }diff --git a/atomic-forge/tools/firecrawl_search/requirements.txt b/atomic-forge/tools/firecrawl_search/requirements.txtnew file mode 100644index 0000000..469c7e9--- /dev/null+++ b/atomic-forge/tools/firecrawl_search/requirements.txt@@ -0,0 +1,3 @@+atomic-agents>=2.0.0,<3.0.0+pydantic>=2.10.3,<3.0.0+aiohttp>=3.9.0,<4.0.0diff --git a/atomic-forge/tools/firecrawl_search/tests/test_firecrawl_search.py b/atomic-forge/tools/firecrawl_search/tests/test_firecrawl_search.pynew file mode 100644index 0000000..2c78168--- /dev/null+++ b/atomic-forge/tools/firecrawl_search/tests/test_firecrawl_search.py@@ -0,0 +1,317 @@+import os+import sys+from types import SimpleNamespace+from unittest.mock import AsyncMock, MagicMock, patch++import pytest++sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))++from tool.firecrawl_search import ( # noqa: E402+ FirecrawlSearchResultItem,+ FirecrawlSearchTool,+ FirecrawlSearchToolConfig,+ FirecrawlSearchToolInputSchema,+ FirecrawlSearchToolOutputSchema,+)+++WEB_HIT = {+ "url": "https://www.python.org/",+ "title": "Welcome to Python.org",+ "description": "Python is a programming language that lets you work quickly.",+ "position": 1,+}++NEWS_HIT = {+ "url": "https://example.com/python-3-14",+ "title": "Python 3.14 released",+ "snippet": "The Python core team shipped 3.14 today.",+ "date": "2 days ago",+ "imageUrl": "https://example.com/thumb.png",+ "position": 2,+}++CONTENT_HIT = {+ "url": "https://example.com/guide",+ "description": "A guide to agents.",+ "position": 3,+ "markdown": "# Agent guide\n\nBuild agents step by step.",+ "metadata": {"title": "Agent guide | Example", "description": "Metadata description", "statusCode": 200},+}+++def _mock_session(status: int, payload: dict, reason: str = "OK") -> MagicMock:+ session = MagicMock()+ response = SimpleNamespace(status=status, reason=reason, json=AsyncMock(return_value=payload))+ session.post.return_value.__aenter__.return_value = response+ return session+++def tool():+ return FirecrawlSearchTool(config=FirecrawlSearchToolConfig(api_key="test-key"))+++def test_to_item_web():+ item = FirecrawlSearchTool._to_item(WEB_HIT, "python")+ assert isinstance(item, FirecrawlSearchResultItem)+ assert item.query == "python"+ assert item.title == "Welcome to Python.org"+ assert item.url == "https://www.python.org/"+ assert item.description.startswith("Python is a programming language")+ assert item.position == 1+ assert item.published is None+ assert item.content is None+++def test_to_item_news():+ """News results carry a snippet and a relative date instead of a description."""+ item = FirecrawlSearchTool._to_item(NEWS_HIT, "python")+ assert item.description == "The Python core team shipped 3.14 today."+ assert item.published == "2 days ago"+ assert item.position == 2+++def test_to_item_with_content():+ """With scrapeOptions each result carries markdown and page metadata."""+ item = FirecrawlSearchTool._to_item(CONTENT_HIT, "agents")+ assert item.title == "Agent guide | Example"+ assert item.description == "A guide to agents."+ assert item.content.startswith("# Agent guide")+++def test_to_item_falls_back_to_url_for_title():+ item = FirecrawlSearchTool._to_item({"url": "https://example.com/untitled"}, "q")+ assert item.title == "https://example.com/untitled"+ assert item.description is None+++def test_build_body_defaults(tool):+ body = tool._build_body("python", FirecrawlSearchToolInputSchema(queries=["python"]))+ assert body == {"query": "python", "limit": 5, "sources": ["web"], "origin": "atomic-agents"}+++def test_build_body_with_options():+ tool = FirecrawlSearchTool(config=FirecrawlSearchToolConfig(api_key="k", location="Germany", time_range="week"))+ params = FirecrawlSearchToolInputSchema(queries=["python"], max_results_per_query=3, include_content=True)++ body = tool._build_body("python", params)++ assert body["sources"] == ["web"]+ assert body["limit"] == 3+ assert body["location"] == "Germany"+ assert body["tbs"] == "qdr:w"+ assert body["scrapeOptions"] == {"formats": ["markdown"], "onlyMainContent": True}+++def test_build_body_skips_time_range_for_news():+ """The API's tbs filter only applies to web results."""+ tool = FirecrawlSearchTool(config=FirecrawlSearchToolConfig(api_key="k", time_range="day"))++ body = tool._build_body("python", FirecrawlSearchToolInputSchema(queries=["python"], search_type="news"))++ assert body["sources"] == ["news"]+ assert "tbs" not in body+++def test_to_item_truncates_content_and_ignores_bad_metadata():+ hit = {**CONTENT_HIT, "metadata": ["not", "a", "dict"]}++ item = FirecrawlSearchTool._to_item(hit, "agents", max_content_chars=7)++ assert item.content == "# Agent"+ assert item.title == "https://example.com/guide"+++async def test_fetch_builds_request(tool):+ session = _mock_session(200, {"success": True, "data": {"web": [WEB_HIT]}})+ params = FirecrawlSearchToolInputSchema(queries=["python"])++ items = await tool._fetch(session, "python", params)++ assert len(items) == 1+ assert items[0].url == "https://www.python.org/"+ call_args = session.post.call_args+ assert call_args[0][0] == "https://api.firecrawl.dev/v2/search"+ assert call_args[1]["json"]["query"] == "python"+++async def test_fetch_reads_news_results(tool):+ session = _mock_session(200, {"success": True, "data": {"news": [NEWS_HIT] * 4}})+ params = FirecrawlSearchToolInputSchema(queries=["python"], search_type="news", max_results_per_query=2)++ items = await tool._fetch(session, "python", params)++ assert len(items) == 2+ assert items[0].published == "2 days ago"+++async def test_fetch_handles_missing_source_key(tool):+ """The API omits the source key entirely when there are no results."""+ session = _mock_session(200, {"success": True, "data": {}})++ items = await tool._fetch(session, "nothing", FirecrawlSearchToolInputSchema(queries=["nothing"]))++ assert items == []+++async def test_fetch_skips_hits_without_url(tool):+ session = _mock_session(200, {"success": True, "data": {"web": [WEB_HIT, {"title": "no url"}]}})++ items = await tool._fetch(session, "python", FirecrawlSearchToolInputSchema(queries=["python"]))++ assert [item.url for item in items] == ["https://www.python.org/"]+++async def test_fetch_raises_on_http_error(tool):+ session = _mock_session(401, {"success": False, "error": "Unauthorized: Invalid token"}, reason="Unauthorized")++ with pytest.raises(Exception, match="Firecrawl search failed for 'python': 401 Unauthorized: Invalid token"):+ await tool._fetch(session, "python", FirecrawlSearchToolInputSchema(queries=["python"]))+++async def test_fetch_raises_when_success_is_false(tool):+ session = _mock_session(200, {"success": False})++ with pytest.raises(Exception, match="Firecrawl search failed for 'python': 200 OK"):+ await tool._fetch(session, "python", FirecrawlSearchToolInputSchema(queries=["python"]))+++async def test_fetch_reports_status_for_non_json_body(tool):+ session = MagicMock()+ response = SimpleNamespace(status=502, reason="Bad Gateway", json=AsyncMock(side_effect=ValueError("not json")))+ session.post.return_value.__aenter__.return_value = response++ with pytest.raises(Exception, match="Firecrawl search failed for 'python': 502 Bad Gateway"):+ await tool._fetch(session, "python", FirecrawlSearchToolInputSchema(queries=["python"]))+++async def test_fetch_applies_max_content_chars():+ tool = FirecrawlSearchTool(config=FirecrawlSearchToolConfig(api_key="k", max_content_chars=5))+ session = _mock_session(200, {"success": True, "data": {"web": [CONTENT_HIT, "not a dict"]}})++ items = await tool._fetch(session, "agents", FirecrawlSearchToolInputSchema(queries=["agents"], include_content=True))++ assert [item.content for item in items] == ["# Age"]+++async def test_run_async_aggregates_results(tool):+ async def fake_fetch(self, session, query, params):+ return [FirecrawlSearchTool._to_item(WEB_HIT, query), FirecrawlSearchTool._to_item(NEWS_HIT, query)]++ with patch.object(FirecrawlSearchTool, "_fetch", fake_fetch):+ out = await tool.run_async(FirecrawlSearchToolInputSchema(queries=["q1", "q2"]))++ assert isinstance(out, FirecrawlSearchToolOutputSchema)+ assert len(out.results) == 4+ assert {r.query for r in out.results} == {"q1", "q2"}+++async def test_run_async_skips_failing_query(tool):+ async def fake_fetch(self, session, query, params):+ if query == "bad":+ raise Exception("rate limited")+ return [FirecrawlSearchTool._to_item(WEB_HIT, query)]++ with patch.object(FirecrawlSearchTool, "_fetch", fake_fetch):+ out = await tool.run_async(FirecrawlSearchToolInputSchema(queries=["bad", "good"]))++ assert len(out.results) == 1+ assert out.results[0].query == "good"+++async def test_run_async_raises_when_every_query_fails(tool):+ """A bad key or exhausted credits should surface as an error, not as an empty result."""++ async def fake_fetch(self, session, query, params):+ raise Exception("Firecrawl search failed for 'q': 401 Unauthorized: Invalid token")++ with patch.object(FirecrawlSearchTool, "_fetch", fake_fetch):+ with pytest.raises(Exception, match="401"):+ await tool.run_async(FirecrawlSearchToolInputSchema(queries=["q1", "q2"]))+++async def test_run_async_end_to_end_with_mocked_session(tool):+ session = _mock_session(200, {"success": True, "data": {"web": [WEB_HIT]}})++ class FakeSession:+ def __init__(self, headers=None, timeout=None):+ self.headers = headers++ async def __aenter__(self):+ return session++ async def __aexit__(self, *args):+ return False++ with patch("tool.firecrawl_search.aiohttp.ClientSession", FakeSession):+ out = await tool.run_async(FirecrawlSearchToolInputSchema(queries=["python"], include_content=True))++ assert [r.url for r in out.results] == ["https://www.python.org/"]+ assert session.post.call_args[1]["json"]["scrapeOptions"]["formats"] == ["markdown"]+++async def test_run_async_sends_bearer_header(tool):+ captured = {}++ class FakeSession:+ def __init__(self, headers=None, timeout=None):+ captured["headers"] = headers++ async def __aenter__(self):+ return self++ async def __aexit__(self, *args):+ return False++ async def fake_fetch(self, session, query, params):+ return []++ with (+ patch("tool.firecrawl_search.aiohttp.ClientSession", FakeSession),+ patch.object(FirecrawlSearchTool, "_fetch", fake_fetch),+ ):+ await tool.run_async(FirecrawlSearchToolInputSchema(queries=["q"]))++ assert captured["headers"]["Authorization"] == "Bearer test-key"+ assert captured["headers"]["Content-Type"] == "application/json"+++async def test_run_async_requires_api_key(monkeypatch):+ monkeypatch.delenv("FIRECRAWL_API_KEY", raising=False)+ tool = FirecrawlSearchTool(config=FirecrawlSearchToolConfig())++ with pytest.raises(ValueError, match="FIRECRAWL_API_KEY"):+ await tool.run_async(FirecrawlSearchToolInputSchema(queries=["q"]))+++def test_api_key_falls_back_to_environment(monkeypatch):+ monkeypatch.setenv("FIRECRAWL_API_KEY", "env-key")+ tool = FirecrawlSearchTool(config=FirecrawlSearchToolConfig())+ assert tool.api_key == "env-key"+++def test_run_invokes_run_async(tool):+ sentinel = FirecrawlSearchToolOutputSchema(results=[])+ with patch.object(FirecrawlSearchTool, "run_async", AsyncMock(return_value=sentinel)):+ out = tool.run(FirecrawlSearchToolInputSchema(queries=["x"]))+ assert out is sentinel+++if __name__ == "__main__":+ pytest.main([__file__, "-v"])diff --git a/atomic-forge/tools/firecrawl_search/tool/firecrawl_search.py b/atomic-forge/tools/firecrawl_search/tool/firecrawl_search.pynew file mode 100644index 0000000..4ee7a66--- /dev/null+++ b/atomic-forge/tools/firecrawl_search/tool/firecrawl_search.py@@ -0,0 +1,220 @@+import asyncio+import logging+import os+from concurrent.futures import ThreadPoolExecutor+from typing import List, Literal, Optional++import aiohttp+from pydantic import Field++from atomic_agents import BaseIOSchema, BaseTool, BaseToolConfig+++logger = logging.getLogger(__name__)+++################+# INPUT SCHEMA #+################+class FirecrawlSearchToolInputSchema(BaseIOSchema):+ """+ Search the web or recent news through the Firecrawl Search API.+ Use this to find current information on a topic. Set include_content to true to also get+ each result page as Markdown in the same call. Requires a Firecrawl API key.+ """++ queries: List[str] = Field(+ ...,+ description='Search queries to run. Supports operators such as site:, "exact phrase", -term, and filetype:pdf.',+ )+ search_type: Literal["web", "news"] = Field(+ default="web",+ description="Which results to return. 'web' = web pages; 'news' = news articles.",+ )+ max_results_per_query: int = Field(default=5, ge=1, le=100, description="Maximum results per query.")+ include_content: bool = Field(+ default=False,+ description="Also return the main content of each result page as Markdown. Slower than a plain search.",+ )+++####################+# OUTPUT SCHEMA(S) #+####################+class FirecrawlSearchResultItem(BaseIOSchema):+ """A single Firecrawl search result (web page or news article)."""++ query: str = Field(..., description="The query that produced this result.")+ title: str = Field(..., description="Title of the result.")+ url: str = Field(..., description="URL of the result.")+ description: Optional[str] = Field(None, description="Query-relevant excerpt or snippet for the result.")+ position: Optional[int] = Field(None, description="Rank of the result.")+ published: Optional[str] = Field(None, description="Publication date string (news only).")+ content: Optional[str] = Field(None, description="Page content as Markdown (only when include_content is set).")+++class FirecrawlSearchToolOutputSchema(BaseIOSchema):+ """Output of the Firecrawl search tool."""++ results: List[FirecrawlSearchResultItem] = Field(..., description="Matching results across all queries.")+++#################+# CONFIGURATION #+#################+class FirecrawlSearchToolConfig(BaseToolConfig):+ """Configuration for the FirecrawlSearchTool."""++ api_key: str = Field(+ default="", description="Firecrawl API key. Falls back to the FIRECRAWL_API_KEY environment variable."+ )+ base_url: str = Field(default="https://api.firecrawl.dev/v2", description="Firecrawl API base URL.")+ location: Optional[str] = Field(+ default=None, description="Location to localise results, e.g. 'Germany' or 'San Francisco,California,United States'."+ )+ time_range: Optional[Literal["day", "week", "month", "year"]] = Field(+ default=None, description="Only return web results from this time window. Does not apply to news."+ )+ max_content_chars: Optional[int] = Field(+ default=None, ge=1, description="Truncate each result's content to this many characters. No limit when unset."+ )+ timeout: float = Field(default=75.0, ge=1.0, le=120.0, description="HTTP request timeout in seconds.")+++#####################+# MAIN TOOL & LOGIC #+#####################+class FirecrawlSearchTool(BaseTool[FirecrawlSearchToolInputSchema, FirecrawlSearchToolOutputSchema]):+ """Tool for searching the web and news via the Firecrawl Search API."""++ TIME_RANGES = {"day": "qdr:d", "week": "qdr:w", "month": "qdr:m", "year": "qdr:y"}++ def __init__(self, config: FirecrawlSearchToolConfig = FirecrawlSearchToolConfig()):+ super().__init__(config)+ self.api_key = config.api_key or os.getenv("FIRECRAWL_API_KEY", "")+ self.base_url = config.base_url.rstrip("/")+ self.location = config.location+ self.time_range = config.time_range+ self.max_content_chars = config.max_content_chars+ self.timeout = config.timeout++ @classmethod+ def _to_item(cls, hit: dict, query: str, max_content_chars: Optional[int] = None) -> FirecrawlSearchResultItem:+ metadata = hit.get("metadata") if isinstance(hit.get("metadata"), dict) else {}+ content = hit.get("markdown")+ if content and max_content_chars:+ content = content[:max_content_chars]+ return FirecrawlSearchResultItem(+ query=query,+ title=hit.get("title") or metadata.get("title") or hit["url"],+ url=hit["url"],+ description=hit.get("description") or hit.get("snippet") or metadata.get("description"),+ position=hit.get("position"),+ published=hit.get("date"),+ content=content,+ )++ def _build_body(self, query: str, params: FirecrawlSearchToolInputSchema) -> dict:+ body = {+ "query": query,+ "limit": params.max_results_per_query,+ "sources": [params.search_type],+ "origin": "atomic-agents",+ }+ if self.location:+ body["location"] = self.location+ if self.time_range and params.search_type == "web":+ body["tbs"] = self.TIME_RANGES[self.time_range]+ if params.include_content:+ body["scrapeOptions"] = {"formats": ["markdown"], "onlyMainContent": True}+ return body++ async def _fetch(+ self,+ session: aiohttp.ClientSession,+ query: str,+ params: FirecrawlSearchToolInputSchema,+ ) -> List[FirecrawlSearchResultItem]:+ async with session.post(f"{self.base_url}/search", json=self._build_body(query, params)) as resp:+ try:+ data = await resp.json(content_type=None)+ except ValueError:+ data = None+ if resp.status != 200 or not isinstance(data, dict) or not data.get("success"):+ error = data.get("error") if isinstance(data, dict) else None+ raise Exception(f"Firecrawl search failed for '{query}': {resp.status} {error or resp.reason}")++ # The key for the requested source is absent when there are no results.+ groups = data.get("data") if isinstance(data.get("data"), dict) else {}+ hits = groups.get(params.search_type) or []+ items = [self._to_item(hit, query, self.max_content_chars) for hit in hits if isinstance(hit, dict) and hit.get("url")]+ return items[: params.max_results_per_query]++ async def run_async(self, params: FirecrawlSearchToolInputSchema) -> FirecrawlSearchToolOutputSchema:+ if not self.api_key:+ raise ValueError(+ "Firecrawl API key is missing. Set FirecrawlSearchToolConfig.api_key or the FIRECRAWL_API_KEY "+ "environment variable."+ )++ headers = {"Authorization": f"Bearer {self.api_key}", "Content-Type": "application/json"}+ timeout = aiohttp.ClientTimeout(total=self.timeout)+ async with aiohttp.ClientSession(headers=headers, timeout=timeout) as session:+ tasks = [self._fetch(session, q, params) for q in params.queries]+ grouped = await asyncio.gather(*tasks, return_exceptions=True)++ # A bad key or exhausted credits fails every query; raise instead of returning an empty list.+ failures = [group for group in grouped if isinstance(group, Exception)]+ if failures and len(failures) == len(grouped):+ raise failures[0]++ results: List[FirecrawlSearchResultItem] = []+ for query, group in zip(params.queries, grouped):+ if isinstance(group, Exception):+ logger.warning("Firecrawl query '%s' failed: %s", query, str(group) or repr(group))+ continue+ results.extend(group)+ return FirecrawlSearchToolOutputSchema(results=results)++ def run(self, params: FirecrawlSearchToolInputSchema) -> FirecrawlSearchToolOutputSchema:+ with ThreadPoolExecutor() as executor:+ return executor.submit(asyncio.run, self.run_async(params)).result()+++#################+# EXAMPLE USAGE #+#################+if __name__ == "__main__": # pragma: no cover+ from dotenv import load_dotenv+ from rich.console import Console++ load_dotenv()+ console = Console()+ tool = FirecrawlSearchTool(config=FirecrawlSearchToolConfig(api_key=os.getenv("FIRECRAWL_API_KEY", "")))++ examples = [+ ("web", False, "atomic agents framework"),+ ("news", False, "AI agents"),+ ("web", True, "atomic agents framework"),+ ]+ for search_type, include_content, query in examples:+ output = tool.run(+ FirecrawlSearchToolInputSchema(+ queries=[query],+ search_type=search_type,+ max_results_per_query=3,+ include_content=include_content,+ )+ )+ console.rule(f"[bold cyan]{search_type}{' + content' if include_content else ''}")+ for item in output.results:+ console.print(f"[bold]{item.title}[/bold]")+ console.print(item.url)+ if item.description:+ console.print(item.description[:200])+ if item.published:+ console.print(f"[bold]Published:[/bold] {item.published}")+ if item.content:+ console.print(f"[bold]Content:[/bold] {len(item.content)} chars")+ console.print(item.content[:300])+ console.print()diff --git a/docs/guides/tools.md b/docs/guides/tools.mdindex 5d29036..7d9e2a2 100644--- a/docs/guides/tools.md+++ b/docs/guides/tools.md@@ -150,6 +150,7 @@ The Atomic Forge ships with several pre-built tools:- **Calculator**: Perform mathematical calculations- **DateTime**: Timezone-aware now / parse / convert / shift / diff (no key required)- **Fía Signals**: Crypto market intelligence — market regime, trading signals, DeFi yields, gas prices, Solana trending tokens, and wallet risk scoring+- **Firecrawl Search**: Web and news search via the Firecrawl API, with optional page content as Markdown- **Hacker News Search**: Search HN stories, comments, Show HN, Ask HN, polls (free Algolia API)- **PDF Reader**: Extract text and metadata from local or remote PDFs, with page-range filtering- **SearXNG Search**: Search the web using SearXNGdiff --git a/uv.lock b/uv.lockindex 6c39d50..a357fa2 100644--- a/uv.lock+++ b/uv.lock@@ -21,6 +21,7 @@ members = ["example-mcp-server","fastapi-memory","fia-signals",+ "firecrawl-search","hackernews-search","hooks-example","nested-multimodal",@@ -1329,6 +1330,43 @@ wheels = [{ url = "https://files.pythonhosted.org/packages/76/91/7216b27286936c16f5b4d0c530087e4a54eead683e6b0b73dd0c64844af6/filelock-3.20.0-py3-none-any.whl", hash = "sha256:339b4732ffda5cd79b13f4e2711a31b0365ce445d95d243bb996273d072546a2", size = 16054, upload-time = "2025-10-08T18:03:48.35Z" },]+[[package]]+name = "firecrawl-search"+version = "1.0.0"+source = { editable = "atomic-forge/tools/firecrawl_search" }+dependencies = [+ { name = "aiohttp" },+ { name = "atomic-agents" },+ { name = "pydantic" },+]++[package.dev-dependencies]+dev = [+ { name = "coverage" },+ { name = "pytest" },+ { name = "pytest-asyncio" },+ { name = "pytest-cov" },+ { name = "python-dotenv" },+ { name = "rich" },+]++[package.metadata]+requires-dist = [+ { name = "aiohttp", specifier = ">=3.9.0,<4.0.0" },+ { name = "atomic-agents", editable = "." },+ { name = "pydantic", specifier = ">=2.10.3,<3.0.0" },+]++[package.metadata.requires-dev]+dev = [+ { name = "coverage", specifier = ">=7.6.1,<8.0.0" },+ { name = "pytest", specifier = ">=8.3.3,<9.0.0" },+ { name = "pytest-asyncio", specifier = ">=0.23.5,<1.0.0" },+ { name = "pytest-cov", specifier = ">=5.0.0,<6.0.0" },+ { name = "python-dotenv", specifier = ">=1.0.0,<2.0.0" },+ { name = "rich", specifier = ">=13.7.0,<14.0.0" },+]+[[package]]name = "flake8"version = "7.3.0"