Public API¶

This page describes the stable, user-facing APIs exposed by Options Chain Features (OCF).

OCF is designed so that all computation is accessible through explicit function calls, with no hidden state, implicit IO, or side effects. Users may call individual feature builders, Greeks utilities, or the full pipeline depending on their use case.

API Layers Overview¶

OCF exposes three primary API layers:

Feature APIs – underlying-level feature construction
Greeks APIs – per-option and aggregate exposure computation
Pipeline APIs – end-to-end orchestration from raw or normalized inputs

Each layer can be used independently.

Feature APIs¶

The feature API operates on canonical underlying daily data.

Entry Point¶

from ocf.features.api import build_features

build_features(
    df: polars.DataFrame,
    *,
    include: Iterable[str] | None = None,
    exclude: Iterable[str] | None = None,
    config: dict[str, dict] | None = None,
) -> polars.DataFrame

Description¶

Builds a model-ready feature table by applying registered feature blocks in deterministic order.

Supported Feature Blocks¶

ohlcv
iv
skew_smile
term_structure
liquidity

Each block can be enabled, disabled, or configured independently.

See Features section for block-specific documentation.

Greeks APIs¶

The Greeks API provides Black-Scholes per-option Greeks and aggregate exposure features.

Per-Option Greeks¶

from ocf.greeks.api import per_option_greeks

per_option_greeks(
    *,
    chain_snapshot: polars.DataFrame,
    underlying_row: dict,
    rate_field: str = "rate_sofr_90d",
) -> polars.DataFrame

Returns one row per option contract with price and Greeks.

Aggregate Exposure Features¶

from ocf.greeks.api import exposure_features

exposure_features(
    greeks_df: polars.DataFrame,
    *,
    atm_tau: float = 0.15,
    slope_window: float = 0.25,
) -> polars.DataFrame

Returns a single-row DataFrame of chain-level exposure features.

Composite Greeks API¶

from ocf.greeks.api import option_chain_greeks

option_chain_greeks(
    *,
    chain_snapshot: polars.DataFrame,
    underlying_row: dict,
    rate_field: str = "rate_sofr_90d",
    return_per_option: bool = True,
    return_exposures: bool = True,
) -> dict[str, polars.DataFrame]

Convenience wrapper that computes both per-option Greeks and aggregate exposures.

See Greeks/Overview for details.

Pipeline APIs¶

Pipeline APIs coordinate normalization, alignment, feature building, and Greeks computation.

Functional Entry Point (Raw Inputs)¶

from ocf.pipelines.pipeline import run_pipeline

run_pipeline(
    *,
    config: PipelineConfig,
    raw_inputs: dict[str, str | polars.DataFrame],
) -> dict[str, polars.DataFrame]

Functional Entry Point (Normalized Inputs)¶

from ocf.pipelines.pipeline import run_pipeline_normalized

run_pipeline_normalized(
    *,
    config: PipelineConfig,
    normalized_inputs: dict[str, polars.DataFrame],
) -> dict[str, polars.DataFrame]

This entry point is intended for advanced users who manage normalization externally.

See Pipelines section for architecture and configuration details.

Design Guarantees¶

All public APIs in OCF guarantee:

No file IO
No implicit joins
Deterministic outputs
Explicit configuration
Stable schemas within a major version

Breaking API changes will only occur in major version updates.

When to Use Which API¶

Use Case	Recommended API
Research feature engineering	`build_features`
Option-level modeling	`per_option_greeks`
Chain-level exposure modeling	`exposure_features`
Full data pipeline	`run_pipeline`
Custom ingestion	`run_pipeline_normalized`

For detailed explanations of feature construction, schemas, and data assumptions, refer to the relevant sections in the documentation.