Metadata-Version: 2.4
Name: pydantic-ai-unirate
Version: 0.1.0
Summary: Pydantic AI integration for the UniRate currency-exchange API — a toolset plus tool functions for FX rate lookups, conversion, currency lists, and VAT rates.
Project-URL: Homepage, https://github.com/UniRate-API/pydantic-ai-unirate
Project-URL: Repository, https://github.com/UniRate-API/pydantic-ai-unirate
Project-URL: Issues, https://github.com/UniRate-API/pydantic-ai-unirate/issues
Project-URL: Provider, https://unirateapi.com
Author: Unirate Team
License: MIT
License-File: LICENSE
Keywords: currency,exchange-rates,fintech,pydantic-ai,unirate
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: httpx<1.0,>=0.27
Requires-Dist: pydantic-ai-slim>=0.0.14
Description-Content-Type: text/markdown

# pydantic-ai-unirate

[![PyPI](https://img.shields.io/pypi/v/pydantic-ai-unirate.svg)](https://pypi.org/project/pydantic-ai-unirate/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

[Pydantic AI](https://ai.pydantic.dev) integration for the
[UniRate API](https://unirateapi.com) — a drop-in currency-exchange toolset
for Pydantic AI agents.

UniRate provides 593+ fiat, crypto, and commodity exchange rates. Latest rates,
conversion, the currency list, and VAT rates are available on the free tier;
historical and time-series endpoints require a Pro plan.

## Why this package

Pydantic AI has no built-in FX tool — most examples hand-roll one against
`exchangerate-api.com` or AlphaVantage. This package gives you a typed, tested
`UniRateToolset` (a subclass of `pydantic_ai.toolsets.FunctionToolset`, i.e. an
`AbstractToolset`) that plugs straight into an `Agent`, plus the underlying
async wrapper and tool functions if you want to compose your own toolset.

## Install

```bash
pip install pydantic-ai-unirate
```

## Quick start

```python
import os

os.environ["UNIRATE_API_KEY"] = "..."  # https://unirateapi.com

from pydantic_ai import Agent

from pydantic_ai_unirate import UniRateToolset

agent = Agent("openai:gpt-4o-mini", toolsets=[UniRateToolset()])

result = agent.run_sync("How many euros is 250 US dollars right now?")
print(result.output)
```

The toolset registers four tools the model can call:

| Tool | Description |
|---|---|
| `get_rate` | Latest rate for a pair, or every rate for a base currency. |
| `convert` | Convert an amount from one currency to another. |
| `list_currencies` | Every currency code UniRate can convert between. |
| `get_vat_rates` | VAT rates for all countries, or one country. |

## Direct use of the wrapper

The transport layer is a standalone async client you can call without an agent:

```python
import asyncio

from pydantic_ai_unirate import UniRateAPIWrapper


async def main() -> None:
    async with UniRateAPIWrapper() as unirate:
        print(await unirate.convert("USD", "EUR", amount=100))  # 92.5
        print(await unirate.get_rate("USD", "GBP"))             # 0.79
        print((await unirate.get_supported_currencies())[:5])
        print(await unirate.get_vat_rates("DE"))


asyncio.run(main())
```

## Composing your own toolset

The tool functions are exported so you can register them on an existing
`FunctionToolset` or hand them to an agent individually. Each takes the
`UniRateAPIWrapper` as its first argument:

```python
from pydantic_ai.toolsets import FunctionToolset

from pydantic_ai_unirate import UniRateAPIWrapper, convert, get_rate

wrapper = UniRateAPIWrapper()
toolset = FunctionToolset()
toolset.add_function(lambda from_currency, to_currency: get_rate(wrapper, from_currency, to_currency), name="get_rate")
```

## Configuration

| Constructor arg | Env var | Default |
|---|---|---|
| `api_key` | `UNIRATE_API_KEY` | — (required) |
| `base_url` | — | `https://api.unirateapi.com` |
| `timeout` | — | `30` (seconds) |
| `enable_historical` | — | `False` (Pro-gated; opt in) |

`UniRateToolset(api_key=..., enable_historical=..., wrapper=...)` forwards to
the wrapper; pass a pre-built `wrapper=` to share an `httpx` client.

## Error handling

Every failure raises a typed subclass of `UniRateError`:

| HTTP status | Exception | Meaning |
|---|---|---|
| 400 | `InvalidRequestError` | Invalid request parameters |
| 401 | `AuthenticationError` | Missing or invalid API key |
| 403 | `APIError` (`status_code == 403`) | Endpoint requires a Pro subscription |
| 404 | `InvalidCurrencyError` | Currency not found or no data available |
| 429 | `RateLimitError` | Rate limit exceeded |
| 503 | `APIError` (`status_code == 503`) | Service unavailable |
| transport | `UniRateError` | Connection / timeout failure (wrapped) |

## Related UniRate clients

If you want to call the API directly from a non-Python application, there are
official clients in
[Python](https://github.com/UniRate-API/unirate-api-python),
[Node.js](https://github.com/UniRate-API/unirate-api-nodejs),
[Go](https://github.com/UniRate-API/unirate-api-go),
[Rust](https://github.com/UniRate-API/unirate-api-rust),
[Java](https://github.com/UniRate-API/unirate-api-java),
[Ruby](https://github.com/UniRate-API/unirate-api-ruby),
[PHP](https://github.com/UniRate-API/unirate-api-php),
[.NET](https://github.com/UniRate-API/unirate-api-dotnet), and
[Swift](https://github.com/UniRate-API/unirate-api-swift), plus a
[LangChain integration](https://github.com/UniRate-API/langchain-unirate) and an
[MCP server](https://github.com/UniRate-API/unirate-mcp) for Claude Desktop and
other MCP hosts.

## License

MIT — see [LICENSE](LICENSE).
