Building AI agents, atomically
Merge current main and fix FXMacroData validation and redaction
Robert Tidballa95fb9e23852
diff --cc AGENTS.mdindex 82972be,688aa82..4bebe4b--- a/AGENTS.md+++ b/AGENTS.md@@@ -100,7 -100,7 +100,8 @@@ Each example is self-contained and demo- `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+- `fxmacrodata/` - Macroeconomic releases, release calendars, FX rates, and COT positioning via the FXMacroData API- `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 --cc README.mdindex 81bc8e4,eaa6a16..4e78b32--- a/README.md+++ b/README.md@@@ -349,7 -349,7 +349,8 @@@ Atomic Forge is a collection of tools t- Calculator- DateTime- Fía Signals+ - Firecrawl Search+- FXMacroData- Hacker News Search- PDF Reader- SearXNG Searchdiff --cc atomic-forge/README.mdindex ea4084a,1930426..9fbee93--- a/atomic-forge/README.md+++ b/atomic-forge/README.md@@@ -18,7 -18,7 +18,8 @@@ The Atomic Forge project includes the f- [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.+- [FXMacroData](/atomic-forge/tools/fxmacrodata/README.md)- [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 --cc atomic-forge/tools/fxmacrodata/README.mdindex 1091463,0000000..fc504c9mode 100644,000000..100644--- a/atomic-forge/tools/fxmacrodata/README.md+++ b/atomic-forge/tools/fxmacrodata/README.md@@@ -1,74 -1,0 +1,76 @@@+# FXMacroData Tool++## Overview- Queries the [FXMacroData](https://fxmacrodata.com) API for official-source macroeconomic data: release history with the official announcement timestamp of each print (CPI, GDP, unemployment, payrolls, policy rates, bond yields and more), the latest value of every indicator for a currency, upcoming release dates, the indicator catalogue, FX spot history, CFTC Commitments of Traders positioning, and commodity prices.++Queries the [FXMacroData](https://fxmacrodata.com) API for official-source macroeconomic data: release history with publication timestamps where available (CPI, GDP, unemployment, payrolls, policy rates, bond yields and more), the latest value of every indicator for a currency, upcoming release dates, the indicator catalogue, FX spot history, CFTC Commitments of Traders positioning, and commodity prices.++USD releases, the USD release calendar and the indicator catalogue work without an API key. Other currencies, FX rates, COT and commodities need a key from [fxmacrodata.com/subscribe](https://fxmacrodata.com/subscribe).++## Prerequisites and Dependencies+- Python 3.12 or later+- `atomic-agents`+- `pydantic`+- `requests`+- Optional: an FXMacroData API key++## Installation+1. Use the Atomic Assembler CLI: run `atomic` and pick `fxmacrodata`.+2. Or copy the `tool/` folder directly into your project.++## Configuration+- `api_key` (secret str): FXMacroData API key, hidden from the config repr, sent in the `X-API-Key` header. Falls back to the `FXMACRODATA_API_KEY` environment variable; surrounding whitespace is ignored. Leave empty for keyless USD access. The key never appears in `url`, `error` or any other output field, even if the API echoes it.- - `base_url` (str): API base URL (default `https://api.fxmacrodata.com/v1`). Must be an `https://` URL with a host, checked when the config is created; redirects are not followed, so the key is only ever sent to this origin.++- `base_url` (str): API base URL (default `https://api.fxmacrodata.com/v1`). Must be an `https://` URL with a host and a valid port when specified, checked when the config is created; redirects are not followed, so the key is only ever sent to this origin.+- `timeout` (float): HTTP timeout in seconds (default 30).++## Input & Output Structure++### Input Schema+- `endpoint` (str): one of+ - `announcements`: release history for one indicator (`currency` and `indicator` required)+ - `latest`: the most recent value of every indicator for a currency+ - `calendar`: upcoming release dates for a currency, optionally filtered by `indicator`+ - `catalogue`: indicator slugs, units and coverage available for a currency+ - `forex`: FX spot history (`currency` is the base, `quote` required)+ - `cot`: CFTC positioning for a currency+ - `commodities`: price history for a commodity (`indicator`, e.g. `gold`)+- `currency` (str, optional): three-letter code such as `usd`, `eur`, `jpy`.+- `indicator` (str, optional): indicator slug such as `inflation`, `policy_rate`, `gdp`.+- `quote` (str, optional): quote currency for `forex`.+- `start_date`, `end_date` (str, optional): real dates as `YYYY-MM-DD`; `start_date` must not be after `end_date`.+- `limit` (int, optional): rows per page, 1-100. History endpoints return 20 rows by default.+- `offset` (int, optional): row offset for paging.++### Output Schema+- `endpoint` (str): the endpoint that was called.+- `url` (str): the request URL (the key is never included).- - `data`: the rows returned by the API, with the API's own field names. Announcement rows carry `date` (reference period), `val`, and `announcement_datetime` (Unix seconds of the official release). For `catalogue` this is a mapping of indicator slug to metadata.++- `data`: the rows returned by the API, with the API's own field names. Announcement rows include `date` (reference period), `val`, and an `announcement_datetime` timestamp field (Unix seconds when available; the timestamp can be unavailable). For `catalogue` this is a mapping of indicator slug to metadata.+- `pagination` (dict, optional): `has_more`, `next_offset` and `total_count` for paged endpoints.+- `metadata` (dict): the remaining top-level response fields, such as source, provenance and data quality.+- `error` (str, optional): set instead of raising when the input is invalid, the request fails, or the response is not the documented shape, so an agent can read the reason (for example a missing API key for a non-USD currency) and adjust.+++Response structure is validated before credential redaction. Names that collide after redaction receive unique, redacted suffixes; all values are retained.+++## Usage++```python+from tool.fxmacrodata import FXMacroDataTool, FXMacroDataToolInputSchema++tool = FXMacroDataTool() # reads FXMACRODATA_API_KEY if set++cpi = tool.run(FXMacroDataToolInputSchema(endpoint="announcements", currency="usd", indicator="inflation", limit=3))+for row in cpi.data:+ print(row["date"], row["val"], row["announcement_datetime"])++upcoming = tool.run(FXMacroDataToolInputSchema(endpoint="calendar", currency="usd"))+for row in upcoming.data[:5]:+ print(row["announcement_datetime_utc"], row["name"])+```++To page through a long history, repeat the call with `offset=output.pagination["next_offset"]` until `has_more` is false.++The full list of endpoints and response fields is in the [API reference](https://fxmacrodata.com/documentation/reference).++## Contributing+PRs welcome. See the main repo `CONTRIBUTING.md`.++## License+Same as the main Atomic Agents project.diff --cc atomic-forge/tools/fxmacrodata/tests/test_fxmacrodata.pyindex ecd350c,0000000..668b036mode 100644,000000..100644--- a/atomic-forge/tools/fxmacrodata/tests/test_fxmacrodata.py+++ b/atomic-forge/tools/fxmacrodata/tests/test_fxmacrodata.py@@@ -1,388 -1,0 +1,476 @@@+import json+import os+import sys+from unittest.mock import MagicMock, patch++import pytest+import requests+from pydantic import ValidationError++sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))++from tool.fxmacrodata import ( # noqa: E402+ FXMacroDataTool,+ FXMacroDataToolConfig,+ FXMacroDataToolInputSchema,+ FXMacroDataToolOutputSchema,+ build_request,+)+-+ANNOUNCEMENTS_PAYLOAD = {+ "currency": "USD",+ "indicator": "inflation",+ "name": "Inflation (CPI)",+ "source": "BLS",+ "data": [+ {"date": "2026-08-31", "val": 3.4, "announcement_datetime": 1789129800},+ {"date": "2026-07-31", "val": 3.4, "announcement_datetime": 1786537800},+ ],+ "pagination": {"limit": 2, "offset": 0, "has_more": True, "next_offset": 2, "total_count": 3},+}++CALENDAR_PAYLOAD = {+ "currency": "USD",+ "timezone": "America/New_York",+ "data": [+ {+ "release": "trade_balance",+ "name": "Trade Balance",+ "announcement_datetime": 1791289800,+ "announcement_datetime_utc": "2026-10-06T12:30:00+00:00",+ }+ ],+}++CATALOGUE_PAYLOAD = {+ "gdp": {"name": "GDP", "unit": "USD bn", "frequency": "Quarterly"},+ "inflation": {"name": "Inflation (CPI)", "unit": "%", "frequency": "Monthly"},+}++SECRET = "fxmd-dummy-secret-0123456789"+++def _response(status: int, payload, reason: str = "OK") -> MagicMock:+ response = MagicMock()+ response.status_code = status+ response.reason = reason+ response.json.return_value = payload+ return response+++def _real_response(request: requests.PreparedRequest, status: int, body: str, headers=None) -> requests.Response:+ """A genuine requests.Response, so redirect handling and header checks run through Requests itself."""+ response = requests.Response()+ response.status_code = status+ response._content = body.encode()+ response.headers.update(headers or {})+ response.url = request.url+ response.request = request+ response.reason = "Found" if status == 302 else "OK"+ return response+++def tool(monkeypatch):+ monkeypatch.delenv("FXMACRODATA_API_KEY", raising=False)+ return FXMacroDataTool(FXMacroDataToolConfig())+++ "fields, path, query",+ [+ (+ {"endpoint": "announcements", "currency": "USD", "indicator": "inflation", "limit": 5},+ "/announcements/usd/inflation",+ {"limit": "5"},+ ),+ ({"endpoint": "latest", "currency": "eur"}, "/announcements/eur/latest", {}),+ (+ {"endpoint": "calendar", "currency": "gbp", "indicator": "policy_rate"},+ "/calendar/gbp",+ {"indicator": "policy_rate"},+ ),+ ({"endpoint": "catalogue", "currency": "jpy"}, "/data_catalogue/jpy", {}),+ (+ {"endpoint": "forex", "currency": "eur", "quote": "USD", "start_date": "2026-01-01", "end_date": "2026-02-01"},+ "/forex/eur/usd",+ {"start_date": "2026-01-01", "end_date": "2026-02-01"},+ ),+ ({"endpoint": "cot", "currency": "aud", "offset": 20}, "/cot/aud", {"offset": "20"}),+ ({"endpoint": "commodities", "indicator": "gold"}, "/commodities/gold", {}),+ ],+)+def test_build_request(fields, path, query):+ assert build_request(FXMacroDataToolInputSchema(**fields)) == (path, query)+++ "fields, message",+ [+ ({"endpoint": "announcements", "indicator": "inflation"}, "'currency'"),+ ({"endpoint": "announcements", "currency": "usd"}, "'indicator'"),+ ({"endpoint": "forex", "currency": "eur"}, "'quote'"),+ ({"endpoint": "latest", "currency": "dollars"}, "'currency'"),+ ({"endpoint": "announcements", "currency": "usd", "indicator": "../ping"}, "'indicator'"),+ ({"endpoint": "calendar", "currency": "usd", "start_date": "01/02/2026"}, "'start_date'"),+ ({"endpoint": "commodities"}, "'indicator'"),+ ],+)+def test_invalid_input_returns_error_without_request(tool, fields, message):+ with patch("tool.fxmacrodata.requests.get") as mock_get:+ output = tool.run(FXMacroDataToolInputSchema(**fields))+ mock_get.assert_not_called()+ assert output.error and message in output.error+ assert output.data == []+++ "dates, message",+ [+ ({"start_date": "2026-02-30"}, "'start_date' must be a real date"),+ ({"end_date": "2026-13-01"}, "'end_date' must be a real date"),+ ({"start_date": ""}, "'start_date' must be a real date"),+ ({"start_date": "20260101"}, "'start_date' must be a real date"),+ ({"start_date": "2026-03-01", "end_date": "2026-02-01"}, "'start_date' must not be after 'end_date'"),+ ],+)+def test_impossible_empty_and_reversed_dates_are_rejected(tool, dates, message):+ with patch("tool.fxmacrodata.requests.get") as mock_get:+ output = tool.run(FXMacroDataToolInputSchema(endpoint="forex", currency="eur", quote="usd", **dates))+ mock_get.assert_not_called()+ assert message in output.error+++def test_announcements_split_rows_pagination_and_metadata(tool):+ with patch("tool.fxmacrodata.requests.get", return_value=_response(200, ANNOUNCEMENTS_PAYLOAD)) as mock_get:+ output = tool.run(FXMacroDataToolInputSchema(endpoint="announcements", currency="usd", indicator="inflation", limit=2))++ assert isinstance(output, FXMacroDataToolOutputSchema)+ assert output.error is None+ assert [row["val"] for row in output.data] == [3.4, 3.4]+ assert output.data[0]["announcement_datetime"] == 1789129800+ assert output.pagination["next_offset"] == 2+ assert output.metadata == {"currency": "USD", "indicator": "inflation", "name": "Inflation (CPI)", "source": "BLS"}+ assert output.url == "https://api.fxmacrodata.com/v1/announcements/usd/inflation?limit=2"++ args, kwargs = mock_get.call_args+ assert args[0] == "https://api.fxmacrodata.com/v1/announcements/usd/inflation"+ assert kwargs["params"] == {"limit": "2"}+ assert kwargs["timeout"] == 30.0+ assert kwargs["allow_redirects"] is False+ assert "X-API-Key" not in kwargs["headers"]+++def test_calendar_without_pagination(tool):+ with patch("tool.fxmacrodata.requests.get", return_value=_response(200, CALENDAR_PAYLOAD)):+ output = tool.run(FXMacroDataToolInputSchema(endpoint="calendar", currency="usd"))++ assert output.data[0]["release"] == "trade_balance"+ assert output.pagination is None+ assert output.metadata == {"currency": "USD", "timezone": "America/New_York"}+++def test_catalogue_returns_mapping(tool):+ with patch("tool.fxmacrodata.requests.get", return_value=_response(200, CATALOGUE_PAYLOAD)):+ output = tool.run(FXMacroDataToolInputSchema(endpoint="catalogue", currency="usd"))++ assert output.data == CATALOGUE_PAYLOAD+ assert output.metadata == {}+++def test_api_key_from_config_is_sent_as_header():+ tool = FXMacroDataTool(FXMacroDataToolConfig(api_key="test-key", base_url="https://example.test/v1/", timeout=5))+ with patch("tool.fxmacrodata.requests.get", return_value=_response(200, CALENDAR_PAYLOAD)) as mock_get:+ output = tool.run(FXMacroDataToolInputSchema(endpoint="calendar", currency="eur"))++ args, kwargs = mock_get.call_args+ assert args[0] == "https://example.test/v1/calendar/eur"+ assert kwargs["headers"]["X-API-Key"] == "test-key"+ assert kwargs["timeout"] == 5+ assert "test-key" not in output.url+++def test_api_key_falls_back_to_environment(monkeypatch):+ monkeypatch.setenv("FXMACRODATA_API_KEY", "env-key")+ tool = FXMacroDataTool()+ with patch("tool.fxmacrodata.requests.get", return_value=_response(200, CALENDAR_PAYLOAD)) as mock_get:+ tool.run(FXMacroDataToolInputSchema(endpoint="calendar", currency="eur"))+ assert mock_get.call_args[1]["headers"]["X-API-Key"] == "env-key"+++def test_http_error_surfaces_api_detail(tool):+ body = {"detail": "This endpoint requires an Individual or Business API key.", "code": "api_key_required"}+ with patch("tool.fxmacrodata.requests.get", return_value=_response(401, body, "Unauthorized")):+ output = tool.run(FXMacroDataToolInputSchema(endpoint="forex", currency="eur", quote="usd"))++ assert output.error == "FXMacroData returned 401: This endpoint requires an Individual or Business API key."+ assert output.data == []+++def test_http_error_without_json_body(tool):+ response = _response(502, None, "Bad Gateway")+ response.json.side_effect = ValueError("not json")+ with patch("tool.fxmacrodata.requests.get", return_value=response):+ output = tool.run(FXMacroDataToolInputSchema(endpoint="latest", currency="usd"))+ assert output.error == "FXMacroData returned 502 Bad Gateway"+++# Regression: base_url problems used to surface mid-request (InvalidURL/ValueError); they now fail when the+# config is built, so they can never reach a request.+ "base_url",+ ["https://", "https:///v1", "http://api.fxmacrodata.com/v1", "api.fxmacrodata.com/v1", "ftp://api.fxmacrodata.com", ""],+)+def test_invalid_base_url_is_rejected_by_config(base_url):+ with pytest.raises(ValidationError, match="base_url must be an https:// URL with a host"):+ FXMacroDataToolConfig(api_key=SECRET, base_url=base_url)+++def test_base_url_is_normalised_by_config():+ assert FXMacroDataToolConfig(base_url=" https://example.test/v1/ ").base_url == "https://example.test/v1"+++# Regression: the full key appeared in the config's repr() and str().+def test_config_repr_and_str_hide_the_key():+ config = FXMacroDataToolConfig(api_key=SECRET)+ assert SECRET not in repr(config)+ assert SECRET not in str(config)+ assert SECRET not in config.model_dump_json()+++# Regression: a successful response echoing the key copied it into metadata and the output repr.+def test_key_echoed_in_a_successful_response_is_redacted():+ payload = {"data": [{"note": f"row {SECRET}"}], "detail": "echo " + SECRET, f"field-{SECRET}": 1}+ tool = FXMacroDataTool(FXMacroDataToolConfig(api_key=SECRET))+ with patch("tool.fxmacrodata.requests.get", return_value=_response(200, payload)):+ output = tool.run(FXMacroDataToolInputSchema(endpoint="latest", currency="usd"))++ assert output.error is None+ assert SECRET not in repr(output)+ assert SECRET not in output.model_dump_json()+ assert output.metadata["detail"] == "echo [redacted]"+ assert output.data == [{"note": "row [redacted]"}]+++def test_key_echoed_in_a_catalogue_response_is_redacted():+ payload = {"gdp": {"name": "GDP", "note": SECRET}}+ tool = FXMacroDataTool(FXMacroDataToolConfig(api_key=SECRET))+ with patch("tool.fxmacrodata.requests.get", return_value=_response(200, payload)):+ output = tool.run(FXMacroDataToolInputSchema(endpoint="catalogue", currency="usd"))+ assert output.data == {"gdp": {"name": "GDP", "note": "[redacted]"}}+++# Regression: a 302 from the HTTPS API to an unrelated HTTP host must not carry X-API-Key there.+def test_redirect_to_other_http_host_does_not_forward_api_key():+ sent = []++ def send(adapter, request, **kwargs):+ sent.append((request.url, dict(request.headers)))+ if request.url.startswith("https://api.fxmacrodata.com/"):+ return _real_response(request, 302, "", {"Location": "http://collector.example/steal"})+ return _real_response(request, 200, json.dumps(CALENDAR_PAYLOAD))++ tool = FXMacroDataTool(FXMacroDataToolConfig(api_key=SECRET))+ with patch("requests.adapters.HTTPAdapter.send", send):+ output = tool.run(FXMacroDataToolInputSchema(endpoint="calendar", currency="usd"))++ assert [url for url, _ in sent] == ["https://api.fxmacrodata.com/v1/calendar/usd"]+ assert all(not url.startswith("http://collector.example") for url, _ in sent)+ assert output.error == "FXMacroData answered with a redirect (302); redirects are not followed."+ assert output.data == []+++# Regression: a key with leading whitespace raised InvalidHeader, whose text carried the full key.+def test_key_with_leading_whitespace_is_stripped_and_never_echoed():+ sent = []++ def send(adapter, request, **kwargs):+ sent.append(dict(request.headers))+ return _real_response(request, 200, json.dumps(CALENDAR_PAYLOAD))++ tool = FXMacroDataTool(FXMacroDataToolConfig(api_key=f" {SECRET}"))+ with patch("requests.adapters.HTTPAdapter.send", send):+ output = tool.run(FXMacroDataToolInputSchema(endpoint="calendar", currency="usd"))++ assert output.error is None+ assert sent[0]["X-API-Key"] == SECRET+++def test_key_that_cannot_be_a_header_is_reported_without_its_value():+ tool = FXMacroDataTool(FXMacroDataToolConfig(api_key=f"{SECRET}\nInjected: 1"))+ with patch("requests.adapters.HTTPAdapter.send") as send:+ output = tool.run(FXMacroDataToolInputSchema(endpoint="calendar", currency="usd"))++ send.assert_not_called()+ assert SECRET not in output.error+ assert "cannot be sent in an HTTP header" in output.error+++ "error",+ [requests.ConnectionError(f"refused for X-API-Key: {SECRET}"), requests.exceptions.InvalidHeader(f"bad {SECRET}")],+)+def test_request_exception_text_never_reaches_the_output(error):+ tool = FXMacroDataTool(FXMacroDataToolConfig(api_key=SECRET))+ with patch("requests.adapters.HTTPAdapter.send", side_effect=error):+ output = tool.run(FXMacroDataToolInputSchema(endpoint="latest", currency="usd"))++ assert SECRET not in output.error+ assert output.error == f"Could not reach FXMacroData ({type(error).__name__})."+++def test_upstream_detail_echoing_the_key_is_redacted():+ tool = FXMacroDataTool(FXMacroDataToolConfig(api_key=SECRET))+ with patch("tool.fxmacrodata.requests.get", return_value=_response(403, {"detail": f"key {SECRET} revoked"})):+ output = tool.run(FXMacroDataToolInputSchema(endpoint="latest", currency="usd"))+ assert output.error == "FXMacroData returned 403: key [redacted] revoked"+++# Regression: HTTP 200 bodies that are not the documented shape must come back as an error, not as data=[] or a+# ValidationError.+ "endpoint, payload, message",+ [+ ("latest", {"detail": "upstream failure"}, "unexpected response body: upstream failure"),+ ("latest", {"data": None}, "unexpected response body"),+ ("latest", {"data": "not rows"}, "unexpected response body"),+ ("latest", {"data": [1, 2, 3]}, "unexpected response body"),+ ("latest", {"data": [], "pagination": "page 1"}, "unexpected response body"),+ ("latest", ["not", "an", "object"], "unexpected response body"),+ ("catalogue", {"detail": "upstream failure"}, "unexpected response body: upstream failure"),+ ("catalogue", {"gdp": "GDP"}, "unexpected response body"),+ ("catalogue", [], "unexpected response body"),+ ],+)+def test_malformed_200_responses_return_an_error(tool, endpoint, payload, message):+ with patch("tool.fxmacrodata.requests.get", return_value=_response(200, payload)):+ output = tool.run(FXMacroDataToolInputSchema(endpoint=endpoint, currency="usd"))++ assert isinstance(output, FXMacroDataToolOutputSchema)+ assert message in output.error+ assert output.data == []+++# Regression: a present but malformed pagination value was normalised away and returned error=None.+ "pagination",+ [[], False, 0, "", "page 1", {"has_more": "yes"}, {"total_count": True}, {"next_offset": "2"}, {"limit": 1.5}],+)+def test_present_malformed_pagination_is_an_error(tool, pagination):+ with patch("tool.fxmacrodata.requests.get", return_value=_response(200, {"data": [], "pagination": pagination})):+ output = tool.run(FXMacroDataToolInputSchema(endpoint="latest", currency="usd"))+ assert "unexpected response body" in output.error+ assert output.pagination is None+++def test_null_pagination_is_treated_as_absent(tool):+ with patch("tool.fxmacrodata.requests.get", return_value=_response(200, {"data": [], "pagination": None})):+ output = tool.run(FXMacroDataToolInputSchema(endpoint="latest", currency="usd"))+ assert output.error is None+ assert output.pagination is None+++def test_non_json_200_response_returns_an_error(tool):+ response = _response(200, None)+ response.json.side_effect = ValueError("Expecting value")+ with patch("tool.fxmacrodata.requests.get", return_value=response):+ output = tool.run(FXMacroDataToolInputSchema(endpoint="latest", currency="usd"))+ assert output.error == "FXMacroData returned a response that is not JSON."+++async def test_run_async(tool):+ with patch("tool.fxmacrodata.requests.get", return_value=_response(200, ANNOUNCEMENTS_PAYLOAD)):+ output = await tool.run_async(+ FXMacroDataToolInputSchema(endpoint="announcements", currency="usd", indicator="inflation")+ )+ assert len(output.data) == 2++++++ "base_url",++ ["https://example.test:abc/v1", "https://example.test:65536/v1", "https://example.test:-1/v1", "https://[invalid/v1"],++)++def test_malformed_ports_and_hosts_are_rejected_by_config(base_url):++ with patch("requests.adapters.HTTPAdapter.send") as send:++ with pytest.raises(ValidationError, match="base_url must be an https:// URL with a host"):++ FXMacroDataToolConfig(api_key=SECRET, base_url=base_url)++ send.assert_not_called()++++[email protected]("base_url", ["https://example.test:443/v1", "https://[::1]:8443/v1"])++def test_valid_explicit_ports_are_preserved(base_url):++ assert FXMacroDataToolConfig(base_url=base_url).base_url == base_url++++[email protected]("pagination", [{"total_count": True}, {"has_more": "yes"}, {"limit": 1.5}])++def test_pagination_is_validated_before_sensitive_keys_are_redacted(pagination):++ key = next(iter(pagination))++ tool = FXMacroDataTool(FXMacroDataToolConfig(api_key=key))++ with patch("tool.fxmacrodata.requests.get", return_value=_response(200, {"data": [], "pagination": pagination})):++ output = tool.run(FXMacroDataToolInputSchema(endpoint="latest", currency="usd"))++ assert "unexpected response body" in output.error++ assert output.pagination is None++++[email protected]("endpoint", ["latest", "catalogue"])++def test_redacted_key_collisions_preserve_all_values(endpoint):++ values = {++ SECRET: {"value": 1},++ "[redacted]": {"value": 2},++ "[redacted]_": {"value": 3},++ SECRET + "_": {"value": 4},++ }++ payload = values if endpoint == "catalogue" else {"data": [values], "pagination": values, **values}++ tool = FXMacroDataTool(FXMacroDataToolConfig(api_key=SECRET))++ with patch("tool.fxmacrodata.requests.get", return_value=_response(200, payload)):++ output = tool.run(FXMacroDataToolInputSchema(endpoint=endpoint, currency="usd"))++ assert output.error is None++ objects = [output.data] if endpoint == "catalogue" else [output.data[0], output.pagination, output.metadata]++ for value in objects:++ assert len(value) == 4++ assert sorted(item["value"] for item in value.values()) == [1, 2, 3, 4]++ assert SECRET not in output.model_dump_json()++++++def test_collision_suffixes_are_redacted_too():++ tool = FXMacroDataTool(FXMacroDataToolConfig(api_key="_"))++ with patch("tool.fxmacrodata.requests.get", return_value=_response(200, {"data": [{"_": 1, "[redacted]": 2}]})):++ output = tool.run(FXMacroDataToolInputSchema(endpoint="latest", currency="usd"))++ assert output.error is None++ assert list(output.data[0].values()) == [1, 2]++ assert "_" not in output.model_dump_json()++++++def test_nested_redaction_collisions_preserve_values_and_safe_keys():++ payload = {"data": [{"nested": {SECRET: "first", "[redacted]": "second"}, "ordinary": 3}]}++ tool = FXMacroDataTool(FXMacroDataToolConfig(api_key=SECRET))++ with patch("tool.fxmacrodata.requests.get", return_value=_response(200, payload)):++ output = tool.run(FXMacroDataToolInputSchema(endpoint="latest", currency="usd"))++ assert output.error is None++ assert list(output.data[0]["nested"].values()) == ["first", "second"]++ assert output.data[0]["ordinary"] == 3++ assert SECRET not in output.model_dump_json()++++[email protected]("api_key", ["[redacted]_", "[redacted]", "redacted", "[", "_", "1", "][", "*][", "*["])++def test_marker_and_suffix_overlaps_terminate_without_losing_values(api_key):++ tool = FXMacroDataTool(FXMacroDataToolConfig(api_key=api_key))++ redact = FXMacroDataTool.redact++ calls = 0++++ def bounded_redact(self, value):++ nonlocal calls++ calls += 1++ assert calls <= 100, "redaction must make progress when suffixes overlap the key"++ return redact(self, value)++++ marker = tool.redact(api_key)++ payload = {api_key: 1, marker: 2, marker + "_1": 3, api_key + "_1": 4}++ with patch.object(FXMacroDataTool, "redact", bounded_redact):++ result = tool.redact_object(payload)++ assert list(result.values()) == list(payload.values())++ assert len(result) == len(payload)++ assert all(api_key not in name for name in result)++ assert api_key not in tool.redact(api_key * 2)++ assert api_key not in tool.redact("*" + api_key * 2)diff --cc atomic-forge/tools/fxmacrodata/tool/fxmacrodata.pyindex 634a9a4,0000000..f187a02mode 100644,000000..100644--- a/atomic-forge/tools/fxmacrodata/tool/fxmacrodata.py+++ b/atomic-forge/tools/fxmacrodata/tool/fxmacrodata.py@@@ -1,349 -1,0 +1,375 @@@+import asyncio+import os+import re+from datetime import date+from typing import Dict, List, Literal, Optional, Tuple, Union+from urllib.parse import urlsplit++import requests+from pydantic import Field, JsonValue, SecretStr, field_validator++from atomic_agents import BaseIOSchema, BaseTool, BaseToolConfig+-+CURRENCY_PATTERN = re.compile(r"^[a-z]{3}$")+INDICATOR_PATTERN = re.compile(r"^[a-z0-9_]+$")+DATE_PATTERN = re.compile(r"^\d{4}-\d{2}-\d{2}$")+# Printable ASCII without spaces: anything else cannot travel in an HTTP header.+API_KEY_PATTERN = re.compile(r"^[\x21-\x7e]+$")++ENDPOINT_PATHS = {+ "announcements": "/announcements/{currency}/{indicator}",+ "latest": "/announcements/{currency}/latest",+ "calendar": "/calendar/{currency}",+ "catalogue": "/data_catalogue/{currency}",+ "forex": "/forex/{currency}/{quote}",+ "cot": "/cot/{currency}",+ "commodities": "/commodities/{indicator}",+}++FIELD_RULES = {+ "currency": (CURRENCY_PATTERN, "a three-letter currency code such as 'usd' or 'eur'"),+ "quote": (CURRENCY_PATTERN, "a three-letter currency code such as 'usd' or 'eur'"),+ "indicator": (INDICATOR_PATTERN, "an indicator slug such as 'inflation' or 'policy_rate'"),+}++JsonObject = Dict[str, JsonValue]++# Documented pagination fields and the exact JSON types each may hold. bool is listed+# separately because it is a subclass of int and must not pass as a count.+PAGINATION_TYPES = {+ "limit": {int},+ "offset": {int},+ "returned_count": {int},+ "total_count": {int},+ "next_offset": {int, type(None)},+ "has_more": {bool},+ "page_includes_latest_available": {bool},+}+++class FXMacroDataError(Exception):+ """A request or response problem, worded so it is safe to hand back to an agent."""+++################+# INPUT SCHEMA #+################+class FXMacroDataToolInputSchema(BaseIOSchema):+ """+ Look up official-source macroeconomic data from FXMacroData: economic releases with their+ announcement timestamps (CPI, GDP, unemployment, payrolls, policy rates, bond yields and more),+ the latest value of every indicator for a currency, upcoming release dates, the indicator+ catalogue, FX spot history, CFTC Commitments of Traders positioning, and commodity prices.+ USD releases work without an API key; other currencies, FX, COT and commodities need one.+ """++ endpoint: Literal["announcements", "latest", "calendar", "catalogue", "forex", "cot", "commodities"] = Field(+ ...,+ description=(+ "'announcements' = release history for one indicator of a currency; 'latest' = most recent value of every"+ " indicator for a currency; 'calendar' = upcoming release dates for a currency; 'catalogue' = available"+ " indicator slugs for a currency (call this first if unsure of a slug); 'forex' = FX spot history for"+ " currency/quote; 'cot' = CFTC positioning for a currency; 'commodities' = price history for a commodity"+ " indicator."+ ),+ )+ currency: Optional[str] = Field(+ None,+ description="Three-letter currency code, e.g. 'usd', 'eur', 'jpy'. Required for every endpoint except commodities."+ " For 'forex' this is the base currency.",+ )+ indicator: Optional[str] = Field(+ None,+ description="Indicator slug, e.g. 'inflation', 'policy_rate', 'gdp', 'unemployment', 'non_farm_payrolls'."+ " Required for 'announcements' and 'commodities' (e.g. 'gold'); optional filter for 'calendar'.",+ )+ quote: Optional[str] = Field(None, description="Quote currency for the 'forex' endpoint, e.g. 'usd' for EUR/USD.")+ start_date: Optional[str] = Field(None, description="Start of the date range, YYYY-MM-DD.")+ end_date: Optional[str] = Field(None, description="End of the date range, YYYY-MM-DD.")+ limit: Optional[int] = Field(None, ge=1, le=100, description="Rows per page for history endpoints (API default 20).")+ offset: Optional[int] = Field(None, ge=0, description="Row offset for paging through history endpoints.")+++####################+# OUTPUT SCHEMA(S) #+####################+class FXMacroDataToolOutputSchema(BaseIOSchema):+ """Output of the FXMacroData tool. Field names inside `data` are the API's own."""++ endpoint: str = Field(..., description="The endpoint that was called.")+ url: str = Field(..., description="The request URL, without the API key.")+ data: Union[List[JsonObject], JsonObject] = Field(+ default_factory=list,+ description=(+ "Rows returned by the API. Announcement rows carry 'date' (reference period), 'val', and"+ " 'announcement_datetime' (Unix seconds of the official release). For 'catalogue' this is a mapping"+ " of indicator slug to its metadata."+ ),+ )+ pagination: Optional[JsonObject] = Field(+ None, description="Paging info ('has_more', 'next_offset', 'total_count') when the endpoint pages."+ )+ metadata: JsonObject = Field(+ default_factory=dict,+ description="Remaining top-level response fields, such as source, units, provenance and data quality.",+ )+ error: Optional[str] = Field(None, description="Error message when the request failed.")+++#################+# CONFIGURATION #+#################+class FXMacroDataToolConfig(BaseToolConfig):+ """Configuration for the FXMacroDataTool."""++ api_key: SecretStr = Field(+ default=SecretStr(""),+ description="FXMacroData API key. Falls back to the FXMACRODATA_API_KEY environment variable. Optional for USD data.",+ )+ base_url: str = Field(default="https://api.fxmacrodata.com/v1", description="FXMacroData API base URL (HTTPS only).")+ timeout: float = Field(default=30.0, ge=1.0, le=120.0, description="HTTP request timeout in seconds.")++ @field_validator("base_url")+ @classmethod+ def require_https_host(cls, value: str) -> str:+ """Reject anything but an https:// URL with a host, so a bad value fails here rather than mid-request."""+ base_url = value.strip().rstrip("/")- parts = urlsplit(base_url)- if parts.scheme != "https" or not parts.hostname:- raise ValueError("base_url must be an https:// URL with a host, e.g. https://api.fxmacrodata.com/v1")- return base_url++ try:++ parts = urlsplit(base_url)++ if parts.scheme == "https" and parts.hostname:++ _ = parts.port # urlsplit defers malformed/out-of-range port checks until this access.++ return base_url++ except ValueError:++ pass++ raise ValueError("base_url must be an https:// URL with a host, e.g. https://api.fxmacrodata.com/v1")+++####################+# REQUEST BUILDING #+####################+def validated_field(params: FXMacroDataToolInputSchema, name: str) -> str:+ """Return a path field lower-cased, or raise if it is missing or malformed."""+ pattern, expected = FIELD_RULES[name]+ value = (getattr(params, name) or "").strip().lower()+ if not pattern.match(value):+ raise FXMacroDataError(f"'{name}' must be {expected}.")+ return value+++def parse_date(name: str, value: str) -> date:+ """Parse a YYYY-MM-DD string into a real calendar date."""+ try:+ if DATE_PATTERN.match(value):+ return date.fromisoformat(value)+ except ValueError:+ pass+ raise FXMacroDataError(f"'{name}' must be a real date formatted YYYY-MM-DD.")+++def optional_date(name: str, value: Optional[str]) -> Optional[date]:+ return None if value is None else parse_date(name, value)+++def check_order(start: Optional[date], end: Optional[date]) -> None:+ if start is not None and end is not None and start > end:+ raise FXMacroDataError("'start_date' must not be after 'end_date'.")+++def date_query(params: FXMacroDataToolInputSchema) -> Dict[str, str]:+ """Validate the date range and return it as query parameters."""+ dates = {name: optional_date(name, getattr(params, name)) for name in ("start_date", "end_date")}+ check_order(dates["start_date"], dates["end_date"])+ return {name: day.isoformat() for name, day in dates.items() if day is not None}+++def build_path(params: FXMacroDataToolInputSchema) -> str:+ template = ENDPOINT_PATHS[params.endpoint]+ names = re.findall(r"{(\w+)}", template)+ return template.format(**{name: validated_field(params, name) for name in names})+++def build_query(params: FXMacroDataToolInputSchema) -> Dict[str, str]:+ query = date_query(params)+ paging = {"limit": params.limit, "offset": params.offset}+ query.update({name: str(value) for name, value in paging.items() if value is not None})+ if params.endpoint == "calendar" and params.indicator is not None:+ query["indicator"] = validated_field(params, "indicator")+ return query+++def build_request(params: FXMacroDataToolInputSchema) -> Tuple[str, Dict[str, str]]:+ """Return the (path, query) pair for an input, validating the fields the endpoint needs."""+ return build_path(params), build_query(params)+++####################+# RESPONSE PARSING #+####################+def is_object_list(value: JsonValue) -> bool:+ return isinstance(value, list) and all(isinstance(item, dict) for item in value)+++def upstream_detail(payload: JsonValue) -> str:+ detail = payload.get("detail") if isinstance(payload, dict) else None+ return f": {detail}" if isinstance(detail, str) and detail else ""+++def unexpected_body(payload: JsonValue) -> FXMacroDataError:+ return FXMacroDataError(f"FXMacroData returned an unexpected response body{upstream_detail(payload)}")+++def response_object(payload: JsonValue) -> JsonObject:+ if not isinstance(payload, dict):+ raise unexpected_body(payload)+ return payload+++def valid_pagination(value: JsonValue) -> bool:+ """Absent or null is fine; anything else must be an object whose documented fields have their documented types."""+ if value is None:+ return True+ if not isinstance(value, dict):+ return False+ return all(type(value[name]) in PAGINATION_TYPES[name] for name in PAGINATION_TYPES.keys() & value.keys())+++def metadata_fields(body: JsonObject) -> JsonObject:+ return {name: value for name, value in body.items() if name not in ("data", "pagination")}+++def parse_rows(payload: JsonValue) -> Tuple[List[JsonObject], Optional[JsonObject], JsonObject]:+ """Split a row endpoint's body into rows, pagination and the remaining metadata."""+ body = response_object(payload)+ rows, pagination = body.get("data"), body.get("pagination")+ if not is_object_list(rows) or not valid_pagination(pagination):+ raise unexpected_body(body)+ return rows, pagination, metadata_fields(body)+++def parse_catalogue(payload: JsonValue) -> JsonObject:+ """The catalogue is a mapping of indicator slug to an object describing it."""+ body = response_object(payload)+ if not body or not all(isinstance(entry, dict) for entry in body.values()):+ raise unexpected_body(body)+ return body+++#####################+# MAIN TOOL & LOGIC #+#####################+class FXMacroDataTool(BaseTool[FXMacroDataToolInputSchema, FXMacroDataToolOutputSchema]):+ """Tool for querying macroeconomic releases, release calendars, FX and positioning data from FXMacroData."""++ def __init__(self, config: FXMacroDataToolConfig = FXMacroDataToolConfig()):+ super().__init__(config)+ self._api_key = (config.api_key.get_secret_value() or os.getenv("FXMACRODATA_API_KEY", "")).strip()+ self.base_url = config.base_url+ self.timeout = config.timeout++ def redact(self, message: str) -> str:+ """Remove the API key from any text that leaves the tool."""- return message.replace(self._api_key, "[redacted]") if self._api_key else message++ if not self._api_key:++ return message++ redacted = message.replace(self._api_key, "[redacted]")++ if self._api_key not in redacted:++ return redacted++ replacement = "*"++ while replacement in self._api_key:++ replacement = chr(ord(replacement) + 1)++ return message.replace(self._api_key, replacement)++ def redact_json(self, value: JsonValue) -> JsonValue:+ """Redact the API key from every string in a response body, keys included."""+ if isinstance(value, list):+ return [self.redact_json(item) for item in value]+ if isinstance(value, dict):+ return self.redact_object(value)+ return self.redact(value) if isinstance(value, str) else value++ def redact_object(self, value: JsonObject) -> JsonObject:- return {self.redact(name): self.redact_json(item) for name, item in value.items()}++ """Keep every value when redacting different keys to the same name."""++ result = {}++ for name, item in value.items():++ redacted_name = self.redact(name)++ key = redacted_name++ suffix = 0++ while key in result:++ suffix += 1++ key = self.redact(f"{redacted_name}_{suffix}")++ result[key] = self.redact_json(item)++ return result++ def headers(self) -> Dict[str, str]:+ if self._api_key and not API_KEY_PATTERN.match(self._api_key):+ raise FXMacroDataError("The FXMacroData API key contains characters that cannot be sent in an HTTP header.")+ return {"Accept": "application/json", **({"X-API-Key": self._api_key} if self._api_key else {})}++ def fetch(self, url: str, query: Dict[str, str]) -> JsonValue:+ """GET one URL. Redirects are never followed, so the key only goes to the configured HTTPS origin."""+ try:+ response = requests.get(url, params=query, headers=self.headers(), timeout=self.timeout, allow_redirects=False)+ except requests.RequestException as error:+ raise FXMacroDataError(f"Could not reach FXMacroData ({type(error).__name__}).") from None+ if response.status_code != 200:+ raise FXMacroDataError(self.status_message(response))+ try:+ return response.json()+ except ValueError:+ raise FXMacroDataError("FXMacroData returned a response that is not JSON.") from None++ @staticmethod+ def status_message(response: requests.Response) -> str:+ if 300 <= response.status_code < 400:+ return f"FXMacroData answered with a redirect ({response.status_code}); redirects are not followed."+ try:+ detail = upstream_detail(response.json())+ except ValueError:+ detail = ""+ return f"FXMacroData returned {response.status_code}{detail or ' ' + str(response.reason)}"++ def query_endpoint(self, params: FXMacroDataToolInputSchema) -> FXMacroDataToolOutputSchema:+ path, query = build_request(params)+ url = f"{self.base_url}{path}"+ display_url = requests.Request("GET", url, params=query).prepare().url- payload = self.redact_json(self.fetch(url, query))++ payload = self.fetch(url, query)+ if params.endpoint == "catalogue":- return FXMacroDataToolOutputSchema(endpoint=params.endpoint, url=display_url, data=parse_catalogue(payload))++ catalogue = parse_catalogue(payload)++ return FXMacroDataToolOutputSchema(endpoint=params.endpoint, url=display_url, data=self.redact_object(catalogue))+ rows, pagination, metadata = parse_rows(payload)+ return FXMacroDataToolOutputSchema(- endpoint=params.endpoint, url=display_url, data=rows, pagination=pagination, metadata=metadata++ endpoint=params.endpoint,++ url=display_url,++ data=self.redact_json(rows),++ pagination=self.redact_json(pagination),++ metadata=self.redact_object(metadata),+ )++ def run(self, params: FXMacroDataToolInputSchema) -> FXMacroDataToolOutputSchema:+ try:+ return self.query_endpoint(params)+ except FXMacroDataError as error:+ return FXMacroDataToolOutputSchema(endpoint=params.endpoint, url="", error=self.redact(str(error)))++ async def run_async(self, params: FXMacroDataToolInputSchema) -> FXMacroDataToolOutputSchema:+ return await asyncio.to_thread(self.run, params)+++#################+# EXAMPLE USAGE #+#################+if __name__ == "__main__": # pragma: no cover+ from dotenv import load_dotenv+ from rich.console import Console++ load_dotenv()+ console = Console()+ tool = FXMacroDataTool()++ output = tool.run(FXMacroDataToolInputSchema(endpoint="announcements", currency="usd", indicator="inflation", limit=3))+ console.rule("[bold cyan]USD CPI")+ console.print(output.error or [(row["date"], row["val"]) for row in output.data])++ output = tool.run(FXMacroDataToolInputSchema(endpoint="calendar", currency="usd"))+ console.rule("[bold cyan]Upcoming USD releases")+ for row in output.data[:5]:+ console.print(row.get("announcement_datetime_utc"), row.get("name"))diff --cc docs/guides/tools.mdindex 6c4aad9,7d9e2a2..0998b8f--- a/docs/guides/tools.md+++ b/docs/guides/tools.md@@@ -150,7 -150,7 +150,8 @@@ The Atomic Forge ships with several pre- **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+- **FXMacroData**: Macroeconomic releases with official announcement times, release calendars, FX rates, and COT positioning (USD data needs no key)- **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 --cc uv.lockindex 64b4fff,a357fa2..e0a4a4c--- a/uv.lock+++ b/uv.lock@@@ -21,7 -21,7 +21,8 @@@ members ="example-mcp-server","fastapi-memory","fia-signals",+ "firecrawl-search",+ "fxmacrodata-tool","hackernews-search","hooks-example","nested-multimodal",