Metadata-Version: 2.5
Name: heimdall-mimird
Version: 0.8.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: alpaca
Requires-Dist: httpx>=0.27; extra == 'alpaca'
Provides-Extra: cac40
Requires-Dist: httpx>=0.27; extra == 'cac40'
Provides-Extra: coingecko
Requires-Dist: httpx>=0.27; extra == 'coingecko'
Provides-Extra: dax
Requires-Dist: httpx>=0.27; extra == 'dax'
Provides-Extra: dow30
Requires-Dist: httpx>=0.27; extra == 'dow30'
Provides-Extra: fred
Requires-Dist: httpx>=0.27; extra == 'fred'
Provides-Extra: ftse100
Requires-Dist: httpx>=0.27; extra == 'ftse100'
Provides-Extra: hang-seng
Requires-Dist: httpx>=0.27; extra == 'hang-seng'
Provides-Extra: mimird
Requires-Dist: httpx>=0.27; extra == 'mimird'
Provides-Extra: nasdaq100
Requires-Dist: httpx>=0.27; extra == 'nasdaq100'
Provides-Extra: nikkei225
Requires-Dist: httpx>=0.27; extra == 'nikkei225'
Provides-Extra: sec
Requires-Dist: httpx>=0.27; extra == 'sec'
Provides-Extra: sp500
Requires-Dist: httpx>=0.27; extra == 'sp500'
Provides-Extra: testing
Requires-Dist: pytest>=8.2; extra == 'testing'
Provides-Extra: treasuries
Requires-Dist: httpx>=0.27; extra == 'treasuries'
Provides-Extra: us-listings
Requires-Dist: httpx>=0.27; extra == 'us-listings'
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": ...}
# one provider, several kinds of data: `kind` picks one (default: the provider's first).
# Kinds: candles, observations, fundamentals, financial_statements, analyst_ratings,
# insider_trading, table; or `from heimdall.schemas import Kind` for autocomplete.
fundamentals = heimdall.fetch("yfinance", "AAPL", kind="financial_statements")
ratings = heimdall.fetch("yfinance", "AAPL", kind="analyst_ratings")

# SEC EDGAR: Form 4 insider transactions and point-in-time XBRL fundamentals
from heimdall import FetchRequest
from heimdall.providers.sec import SecProvider

sec = SecProvider(user_agent="Your Name you@example.com")
insiders = sec.fetch(FetchRequest("AAPL", params={"limit": 5}))  # default kind
facts = sec.fetch("AAPL", kind="fundamentals")

sp500 = heimdall.fetch("sp500", "constituents")
print(sp500.frame.select("symbol", "security", "gics_sector").head())
# + former members (listed=False, date_removed, removal_reason); env: HEIMDALL_SP500_PULL_UNLISTED=true
from heimdall.providers.sp500 import SP500Provider
everyone = SP500Provider(pull_unlisted=True).fetch()

# other indexes, same shape (symbol, name, ...): nasdaq100, dow30, ftse100,
# dax, cac40, nikkei225, hang_seng
dax = heimdall.fetch("dax", "constituents")

# instrument listings (resource "listings"): us_listings (every US-listed stock/ETF,
# Nasdaq Trader), coingecko (top crypto + logo URLs; HEIMDALL_COINGECKO_PAGES=4 for
# 1000), treasuries (outstanding US Treasuries with CUSIP/ISIN, TreasuryDirect)
listings = heimdall.fetch("us_listings", "listings")

# 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;
`heimdall.list_providers(kind="candles")` only the ones that can return that
kind, so a host can route by capability. 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.

## Configuration

Providers that need config (an API key, a contact for SEC) read it from, in order:

```python
heimdall.configure("sec", user_agent="Your Name you@example.com")  # 1. code
```

```bash
export HEIMDALL_SEC_USER_AGENT="Your Name you@example.com"  # 2. env / .env
```

```toml
# 3. pyproject.toml - one place for every package's config; no secrets, it's committed
[tool.heimdall.sec]
user_agent = "Your Name you@example.com"
```

## Writing a provider

Subclass `heimdall.Provider`, set `metadata` + `capabilities`, implement
`_fetch` (one resource - batch, async, and failure collection come for free).
See [CONTRIBUTING.md](CONTRIBUTING.md) for a full worked example, and run
`heimdall.testing.assert_provider_conformance(...)` to check it against the
contract. Third-party packages register through the `heimdall.providers`
entry-point group, picked up automatically on first use.

## Explore the catalog

`heimdall.catalog()` describes every bundled provider (whose extra is installed)
as JSON-safe data: id, description, author, source, `__init__` parameters and
capabilities. The Mimird docs are built from it, and an MCP server can call it
on the installed package:

```bash
uv run --extra all python -m heimdall > catalog.json
```

## Status

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