Metadata-Version: 2.4
Name: haystack-unirate
Version: 0.1.0
Summary: Haystack integration for the UniRate currency-exchange API — components for FX rate lookups, conversion, and currency listings in Haystack pipelines.
Project-URL: Homepage, https://github.com/UniRate-API/haystack-unirate
Project-URL: Repository, https://github.com/UniRate-API/haystack-unirate
Project-URL: Issues, https://github.com/UniRate-API/haystack-unirate/issues
Project-URL: Provider, https://unirateapi.com
Author: Unirate Team
License: MIT
License-File: LICENSE
Keywords: currency,exchange-rates,fintech,haystack,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: haystack-ai<3.0,>=2.0.0
Requires-Dist: requests<3.0,>=2.31
Description-Content-Type: text/markdown

# haystack-unirate

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

[Haystack](https://haystack.deepset.ai) integration for the
[UniRate API](https://unirateapi.com) — drop-in currency-exchange components for
Haystack 2.x pipelines.

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

## Why this package

There's no first-class FX component in core Haystack. This package gives you
typed, tested `@component`-decorated blocks that slot straight into a
`Pipeline` — with `Secret`-based API-key handling and full `to_dict` /
`from_dict` serialization so pipelines round-trip to YAML/JSON cleanly.

## Install

```bash
pip install haystack-unirate
```

## Quick start

```python
import os

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

from haystack.utils import Secret
from haystack_unirate import (
    UniRateConverter,
    UniRateCurrencies,
    UniRateExchangeRate,
)

api_key = Secret.from_env_var("UNIRATE_API_KEY")

rate = UniRateExchangeRate(api_key=api_key)
print(rate.run(from_currency="USD", to_currency="GBP")["rate"])       # 0.79

converter = UniRateConverter(api_key=api_key)
print(converter.run(from_currency="USD", to_currency="EUR", amount=100)["result"])  # 92.5

currencies = UniRateCurrencies(api_key=api_key)
print(currencies.run()["currencies"][:5])
```

## In a pipeline

```python
from haystack import Pipeline
from haystack.utils import Secret

from haystack_unirate import UniRateConverter

pipeline = Pipeline()
pipeline.add_component(
    "convert", UniRateConverter(api_key=Secret.from_env_var("UNIRATE_API_KEY"))
)

result = pipeline.run(
    {"convert": {"from_currency": "USD", "to_currency": "JPY", "amount": 250}}
)
print(result["convert"]["result"])
```

## Components

| Component | Output sockets | Description |
|---|---|---|
| `UniRateExchangeRate` | `rate: float`, `rates: dict` | Latest rate for a pair; if `to_currency` is omitted, `rates` holds every supported target and `rate` is `None`. |
| `UniRateConverter` | `result: float` | Convert `amount` from one currency to another at the latest rate. |
| `UniRateCurrencies` | `currencies: list[str]` | All currency codes UniRate can convert between. |

Each component takes:

| Constructor arg | Env var | Default |
|---|---|---|
| `api_key` (`Secret`) | `UNIRATE_API_KEY` | — (required) |
| `base_url` | — | `https://api.unirateapi.com` |
| `timeout` | — | `30.0` (seconds) |

## Error handling

Non-2xx responses raise `UniRateAPIError` (subclass of `RuntimeError`) with a
`.status_code` attribute:

| Status | Meaning |
|---|---|
| 400 | Invalid request parameters |
| 401 | Missing or invalid API key |
| 403 | Endpoint requires a Pro subscription (e.g. historical data) |
| 404 | Currency not found or no data available |
| 429 | Rate limit exceeded |
| 503 | Service unavailable |

Transport failures raise `UniRateAPIError` with `status_code=None`.

## Related UniRate clients

If you want to call the API directly from a non-Haystack 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), a
[LangChain integration](https://github.com/UniRate-API/langchain-unirate), and an
[MCP server](https://github.com/UniRate-API/unirate-mcp).

## License

MIT — see [LICENSE](LICENSE).
