Metadata-Version: 2.5
Name: heimdall-mimird
Version: 0.5.0
Summary: A data-provider SDK
Requires-Python: >=3.11
Requires-Dist: polars>=1.44.1
Requires-Dist: ramonavocado-logger>=0.1.3
Provides-Extra: all
Requires-Dist: httpx>=0.27; extra == 'all'
Requires-Dist: pyarrow>=15; extra == 'all'
Requires-Dist: yfinance>=0.2.40; extra == 'all'
Provides-Extra: fred
Requires-Dist: httpx>=0.27; extra == 'fred'
Provides-Extra: sp500
Requires-Dist: httpx>=0.27; extra == 'sp500'
Provides-Extra: testing
Requires-Dist: pytest>=8.2; extra == 'testing'
Provides-Extra: yfinance
Requires-Dist: pyarrow>=15; extra == 'yfinance'
Requires-Dist: yfinance>=0.2.40; extra == 'yfinance'
Description-Content-Type: text/markdown

# Heimdall

A host-agnostic **data-provider SDK**. Finance data first (Yahoo Finance OHLCV,
FRED economic series), built so that any data source - yours or the community's -
can plug in behind one small contract.

A provider takes a `FetchRequest` and returns a `FetchResult`: a
[Polars](https://pola.rs) frame, a `SchemaSpec` that describes and validates it,
and some metadata. That's the whole surface. Nothing in the core is
finance-specific; OHLCV bars and economic observations are just two predefined
schemas.

## Install

```bash
pip install heimdall-mimird[fred,yfinance,sp500]   # or: heimdall-mimird[all]
```

The core depends only on `polars` (plus a small logging shim). Each provider
pulls its own client library through an extra, so you install only what you use.

## Quick start

```python
import heimdall

# string shorthand -> FetchRequest(resource="DGS10")
result = heimdall.fetch("fred", "DGS10")
result.schema.validate(result.frame)  # raises SchemaError if it doesn't conform
print(result.frame.head())

bars = heimdall.fetch("yfinance", "AAPL", interval="1d")
print(bars.frame.tail())
print(bars.metadata)  # {"ticker": "AAPL", "interval": "1d", "rows": ...}

sp500 = heimdall.fetch("sp500", "constituents")
print(sp500.frame.select("symbol", "security", "gics_sector").head())

# a list of resources -> BatchResult(.ok / .failed keyed by resource, + combined .frame)
batch = heimdall.fetch("yfinance", ["AAPL", "MSFT", "NVDA"], interval="1d")
print(batch.frame.height, list(batch.failed))

# afetch() is the async mirror of both forms
result = await heimdall.afetch("fred", ["DGS10", "GDP"])
```

`heimdall.list_providers()` shows what's registered. Providers are registered
automatically when their extra is installed; register your own with
`heimdall.register(MyProvider)` (pass a constructed instance,
`heimdall.register(MyProvider(timeout=10))`, to override its `__init__`
defaults). Asking `heimdall.fetch(...)` for a provider whose extra is missing
raises `ProviderNotFound` telling you which extra to install, rather than
failing blank.

## Writing a provider

Subclass `heimdall.Provider`, set `id` + `capabilities`, implement `_fetch`
(one resource - batch, async, and failure collection come for free). See
[docs/writing-a-provider.md](docs/writing-a-provider.md) for a full worked
example, and run `heimdall.testing.assert_provider_conformance(...)` to check it
against the contract.

## Status

Early. The provider contract and the two bundled providers are usable today. The
ingestion/storage layer, entry-point plugin discovery, and retry/rate-limit
middleware are on the [roadmap](ROADMAP.md).
