Metadata-Version: 2.4
Name: openai-agents-fxmacrodata
Version: 0.1.0
Summary: OpenAI Agents SDK 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=openai-agents-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: openai-agents<1,>=0.22.3
Provides-Extra: test
Requires-Dist: pytest<9,>=8; extra == "test"
Dynamic: license-file

# FXMacroData for the OpenAI Agents SDK

Give an OpenAI Agents SDK agent every public FXMacroData operation as a function
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 `FunctionTool` 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=openai-agents-fxmacrodata&utm_content=readme)

## Install

Install the `openai-agents-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 ./openai-agents-fxmacrodata
```

## Use with an agent

```python
from agents import Agent, Runner
from openai_agents_fxmacrodata import tools

agent = Agent(
    name="Macro analyst",
    instructions="Answer with the official release values and cite the source_url.",
    tools=tools(
        api_key_env="FXMD_API_KEY",
        include=["indicator_history", "release_calendar", "latest_announcements"],
    ),
)
result = Runner.run_sync(agent, "What is the latest US policy rate decision?")
print(result.final_output)
```

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. The tools are built with `strict_json_schema=False` because
several operations have optional parameters; the parameter schema itself
forbids unknown keys and every call is validated before it is sent.

## 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 with a short error
message. 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 a compact JSON string with `operation`, `source_url`,
`record_count`, the first `max_records` records (default 200) and a `truncated`
flag. 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 return `{"error": "..."}` 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 openai_agents_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=openai-agents-fxmacrodata&utm_content=readme

## Development

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