Metadata-Version: 2.4
Name: autogen-fxmacrodata
Version: 0.1.0
Summary: AutoGen tools for public FXMacroData macroeconomic and market data
License-Expression: MIT
Project-URL: Documentation, https://fxmacrodata.com/documentation/reference?utm_source=pypi&utm_medium=referral&utm_campaign=autogen-fxmacrodata&utm_content=package
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fxmacrodata-platform-core==0.1.0
Requires-Dist: autogen-core<1,>=0.7.5
Provides-Extra: test
Requires-Dist: pytest<9,>=8; extra == "test"
Dynamic: license-file

# FXMacroData for AutoGen

Give an AutoGen agent every public FXMacroData operation as a tool:
macroeconomic releases, central-bank decisions, release calendars, FX reference
rates, commodities, positioning and research tools. Each of the 87 REST
operations and MCP tools becomes one `autogen_core.tools.BaseTool` whose name,
description and parameter schema come straight from the public operation
catalogue, so the model sees the same contract the documentation describes.

[Explore FXMacroData](https://fxmacrodata.com/?utm_source=github&utm_medium=referral&utm_campaign=autogen-fxmacrodata&utm_content=readme)

## Install

Install the `autogen-fxmacrodata` wheel together with its
`fxmacrodata-platform-core` and `fxmacrodata-public-client` dependencies. From
the supplied packages directory:

```sh
python -m pip install ./fxmacrodata-public-client ./fxmacrodata-platform-core ./autogen-fxmacrodata
```

`autogen-agentchat` supplies the `AssistantAgent` used below; this package
depends only on `autogen-core`.

## Use with an agent

```python
import asyncio

from autogen_agentchat.agents import AssistantAgent
from autogen_fxmacrodata import tools

agent = AssistantAgent(
    name="macro_analyst",
    model_client=model_client,
    tools=tools(
        api_key_env="FXMD_API_KEY",
        include=["indicator_history", "release_calendar", "latest_announcements"],
    ),
    system_message="Answer with the official release values and cite the source_url.",
)
result = asyncio.run(agent.run(task="What is the latest US policy rate decision?"))
print(result.messages[-1].content)
```

`model_client` is any AutoGen chat completion client. Omit `include` to expose
every operation, or pass `exclude` to drop a few. MCP tools keep their `mcp_`
prefix. Unknown names raise `ValueError` before any request is made. A single
operation can also be wrapped directly with `FXMacroDataTool("indicator_history")`.

## Credentials

Set `FXMD_API_KEY` (or any name you prefer) in your environment or secret
manager and pass its *name* through `api_key_env`. The value is read only while
a tool executes; it is never stored on the tools, never placed in a tool
description or schema, and never shown to the model. A tool call that tries to
pass an API key, token or URL as an argument is rejected before any request is
made. Omitting `api_key_env` selects anonymous access, which serves the USD
catalogue and is enough to evaluate the tools.

## Bounded tool output

Every tool returns an `FXMacroDataResult` with `operation`, `source_url`,
`record_count`, the first `max_records` records (default 200) and a `truncated`
flag; AutoGen renders it to the model as compact JSON. The complete response
envelope is included as `response` while the whole document fits in `max_chars`
(default 60,000 characters); otherwise it is omitted and records are trimmed
until the document fits, so a long history can never flood a model context.
Failed reads set `error` on the result rather than raising, so the agent can
adjust its arguments and retry. Reads run in a worker thread and never block
the event loop.

For the complete, unbounded response in your own code, use the plain helper:

```python
from autogen_fxmacrodata import fetch

batch = fetch("indicator_history", {"currency": "usd", "indicator": "policy_rate"})
batch.payload      # original response envelope
batch.records()    # list of records
batch.rows()       # tabular rows with record_json and response_json
```

Historical operations follow every page by default (`complete_history=True`,
`max_pages=1000`). Calendar and observation times keep the API's original
strings; nothing is inferred.

Full operation reference:
https://fxmacrodata.com/documentation/reference?utm_source=github&utm_medium=referral&utm_campaign=autogen-fxmacrodata&utm_content=readme

## Development

Run the offline tests with `python -m pytest tests`. They build the tools, run
them against fixture responses and never call the live service.
