finance flow¶

Standard financial flow models

Overview¶

finance-flow provides reusable finance-specific callable models, schemas, and transformations. It owns provider-neutral research and portfolio workflow logic: normalize market data, validate finance structures, build universes, calculate signals, produce target positions, backtest, and generate reports.

It does not own extraction credentials, provider clients, storage destinations, or application orchestration. Those concerns belong in finance-etl, connector packages, or downstream applications.

Quick Start¶

Normalize provider-shaped daily aggregate rows into typed daily bars:

from finance_flow import normalize_massive_daily_bars

bars = normalize_massive_daily_bars(
    {
        "results": [
            {"T": "AAPL", "o": 184.22, "h": 185.88, "l": 183.43, "c": 184.95, "v": 58414500}
        ]
    },
    ticker="AAPL",
    session_date="2024-01-03",
)

Use the callable wrapper when composing the transform inside a ccflow graph:

from finance_flow import MassiveDailyBarsNormalizeContext, MassiveDailyBarsNormalizeModel

result = MassiveDailyBarsNormalizeModel()(
    MassiveDailyBarsNormalizeContext(
        payload=[{"ticker": "AAPL", "open": 1, "high": 2, "low": 1, "close": 2, "volume": 100}],
        ticker="AAPL",
        session_date="2024-01-03",
    )
)

Publish normalized daily bars as parquet artifacts:

from finance_flow import MassiveDailyBarsArtifactContext, MassiveDailyBarsArtifactModel

result = MassiveDailyBarsArtifactModel(input_store=store, output=store)(
    MassiveDailyBarsArtifactContext(ticker="AAPL", date="2024-01-03")
)

The artifact task reads massive/stocks/rest/daily-aggs/json/{date}/{ticker}.json and writes massive/stocks/bars/daily/parquet/{date}/{ticker}.parquet.

Documentation¶

Dependency Contract¶

Depends on ccflow for callable model integration and may depend on dataframe and validation libraries needed for finance transformations.
May be consumed by finance-etl and application-specific packages.
Must not depend on connector packages unless a transformation genuinely needs optional I/O support, and must not depend on application-specific packages.

Test Convention¶

Default tests should use small synthetic finance datasets and run without external services or provider credentials.