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.

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:

from norn.strategies import STRATEGY_REGISTRY

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

Concepts

Canonical column names live in norn.schema (OHLCV, SIGNAL) — the OHLCV frame you hand in must use them. Every frame is a Polars 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):

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.

Development

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