Metadata-Version: 2.5
Name: norn-mimird
Version: 0.2.0
Summary: A small, contribution-friendly framework for market-data strategies and signal interpreters.
Requires-Python: >=3.11
Requires-Dist: heimdall-mimird[all]>=0.3.0
Requires-Dist: polars>=1.44.1
Requires-Dist: pydantic>=2.7
Requires-Dist: ramonavocado-logger>=0.1.3
Description-Content-Type: text/markdown

# norn

A small framework for market-data **strategies** (OHLCV → signal) and
**interpreters** (signal → target position). norn owns the contracts, a name
registry, a typed error hierarchy and structured logging. Market data is the
caller's to supply — e.g. straight from
[`heimdall`](https://pypi.org/project/heimdall-mimird/).

```python
import heimdall
from norn.strategies import SMACrossoverStrategy
from norn.interpreter import BuyAndHoldInterpreter

result = heimdall.fetch("yfinance", "AAPL", interval="1d")
ohlcv = result.frame.rename({"timestamp": "date", "symbol": "ticker"})

signals = SMACrossoverStrategy({"fast": 10, "slow": 30}).run(ohlcv)
targets = BuyAndHoldInterpreter().run(signals)
```

Don't know the class ahead of time? Look it up by name in the registry:

```python
from norn.strategies import STRATEGY_REGISTRY

signals = STRATEGY_REGISTRY.get("sma_crossover")({"fast": 10, "slow": 30}).run(ohlcv)
```

## Concepts

| | contract | input → output |
|---|---|---|
| **Strategy** | `norn.strategies.BaseStrategy` | OHLCV frame → `date, ticker, signal` (`signal` ∈ [-1, 1]) |
| **Interpreter** | `norn.interpreter.BaseInterpreter` | signal frame → same frame + `target_position` (∈ [-1, 1]) |

Canonical column names live in `norn.schema` (`OHLCV`, `SIGNAL`) — the OHLCV
frame you hand in must use them. Every frame is a [Polars](https://pola.rs)
`DataFrame`.

Built-ins: strategies `sma_crossover`, `rsi_mean_reversion`; interpreters
`signal_following`, `buy_and_hold`.

## sandbox/

A dev playground — not part of the package. `sandbox/run_sma.py` is a worked
example of the OHLCV → signals → positions path (fetches through `heimdall`, so
it needs network access):

```bash
uv run python sandbox/run_sma.py
```

## Extending

Add a strategy or interpreter in your own package and expose it through an entry
point so `pip install` is all a user needs. See [CONTRIBUTING.md](CONTRIBUTING.md).

## Development

```bash
uv sync
uv run pytest
uv run ruff check . && uv run ruff format --check .
uv run mypy
```
