Protocol Interfaces¶

Bases: str, Enum

Order-book resolution a feed (or a plot) works at — MBP vs MBO.

The granularity axis, orthogonal to :class:FeedType's crossing invariant. A source declares its :attr:Source.level so the pipeline knows which stages apply:

• :attr:L2 — Market-By-Price (MBP): aggregate volume per price level, with no persistent order identity. Price-level feeds (Binance, Kalshi, Polymarket, most CCXT sources) are L2. The per-order stages (:func:~ob_analytics.analytics.set_order_types, :func:~ob_analytics.analytics.order_aggressiveness, queue reconstruction) have nothing to key on and are skipped; depth / spread / trade analytics run directly on the price-level book.
• :attr:L3 — Market-By-Order (MBO): one primitive per resting order, with stable identity (queue position recoverable). The reconstruction model ob-analytics was built for (Bitstamp, LOBSTER, Databento).

The str mixin lets members slot directly into the visualization renderer-registry tuple keys and, via the :meth:__str__ override, render as the bare token ("L2") in file stems and f-strings rather than "Level.L2".

Bases: str, Enum

How a data feed represents the order book — its crossing invariant.

A source declares its feed type so downstream code can reason about crossed books by coordinate, not by source name. The distinction is a property of the source, not of the reconstruction:

• :attr:MATCHED_BOOK — an L3 feed emitted by the venue's own matching engine (LOBSTER, exchange MBO such as Databento). Bids can never rest above asks, so an uncrossed book is a guaranteed invariant of the data.
• :attr:DIFF_FEED — an L3 feed reconstructed from a public placement/cancellation diff stream (the Bitstamp public feed). It can contain genuinely crossed resting orders (a bid resting above an ask, neither filling); :func:~ob_analytics.analytics.order_book replays this faithfully — a crossed book in the output is a property of the feed, not a reconstruction bug.
• :attr:UNKNOWN — a source that does not declare its feed type (the structural default for third-party sources predating this attribute).

Mixes in str so members compare and serialise as their value (FeedType.DIFF_FEED == "diff_feed"), which keeps CLI/JSON output and equality checks ergonomic.

Bases: str, Enum

Which orders of a trade a feed's order events can name.

Every trade has a maker, the order that was resting in the book, and a taker, the order that arrived and traded against it. Whether the order events show both depends on the feed, not on the reconstruction:

• :attr:BOTH — the feed reports every order the venue accepts, takers included, so both orders of a trade can be found. Bitstamp's live_orders channel does this.
• :attr:MAKER_ONLY — the feed shows resting orders only. A taker trades on arrival and never rests, so it never appears. Exchange order-by-order feeds (Nasdaq ITCH, from which LOBSTER is built, and Databento MBO) do not identify the aggressor, and a feed made of book snapshots cannot show it.
• :attr:NONE — the feed has no order identity (L2), so neither order can be named.

A source declares it so the unmatched-trades check in :func:~ob_analytics.analytics.data_quality_summary counts only the orders the feed can show. A source that does not declare it is read as :attr:BOTH, the check's behaviour before this declaration existed.

Mixes in str so members compare and serialise as their value, as :class:FeedType does.

Bases: str, Enum

What a feed's venue sequence number promises.

A source declares it so a gap check knows what a skipped number means:

• :attr:CONTIGUOUS — every message adds exactly one. A skipped number is a dropped message. This is the default, and what a per-message counter (cryptofeed's L3 channels) gives.
• :attr:MONOTONIC — the number only rises. A skip is normal and says nothing about loss; only a step that does not rise is a fault. CCXT's book nonce is this kind: on Binance it is the last update ID of a diff that covers a range of IDs, and watch_order_book can apply several diffs before it returns a book. Databento's sequence is too: it numbers every message on the venue's channel, but a file usually holds one instrument of that channel, and the trade and fill records it carries become trades rather than book events.

Mixes in str so members compare and serialise as their value, as :class:FeedType does.

Bases: Protocol

Loads raw order-book events from a data source.

The returned DataFrame must contain at least the columns required by ob_analytics.schemas.validate_events_df.

load(source: Any) -> pd.DataFrame

Bases: Protocol

Loads a price-level (L2) depth stream into the canonical depth frame.

The L2 counterpart to :class:EventLoader. Where an EventLoader returns per-order events that the pipeline later folds into depth via :func:~ob_analytics.depth.price_level_volume, a DepthSource returns the depth frame directly — a price-level feed is a depth stream, so there is nothing to reconstruct.

An :attr:Level.L2 source's :meth:OfflineSource.create_loader returns a DepthSource; the pipeline validates its output with :func:~ob_analytics.schemas.validate_depth_df and feeds it straight to :class:~ob_analytics.depth.DepthMetricsEngine.

Returned DataFrame columns (see :data:~ob_analytics.schemas.DEPTH_COLUMNS):

• timestamp — pandas datetime64[ns, UTC]
• price — int64, the price level in integer ticks (× tick_size for the quote currency)
• volume — int64, the level's new absolute resting size in integer lots (× lot_size for the base asset) after the update (0 removes the level); not a signed delta
• direction — categorical bid/ask

load(source: Any) -> pd.DataFrame

Bases: Protocol

Builds the trades DataFrame for a given run.

Implementations read explicit trade records (a separate trades.csv, LOBSTER execution rows embedded in the events frame, etc.) and project them into the canonical trades schema.

Returned DataFrame columns:

• timestamp — pandas datetime64[ns, UTC]
• price — int64 (integer ticks; × tick_size for the quote currency)
• volume — int64 (integer lots; × lot_size for the base asset)
• direction — categorical buy/sell (taker side)
• maker_event_id — integer event id of the resting order
• taker_event_id — integer event id of the aggressing order
• maker — order id of the resting order
• taker — order id of the aggressing order
• maker_og — original_number of the maker event
• taker_og — original_number of the taker event

load(events: DataFrame, source: Any) -> pd.DataFrame

Bases: Protocol

Writes pipeline results to a format-specific output.

write(
    data: dict[str, DataFrame],
    dest: str | Path,
    **kwargs: Any,
) -> Path | tuple[Path, ...]

Bases: Protocol

Structural contract shared by every data source, file or live.

One shape covers both a file loader and a live capturer: a source states the two coordinates downstream code reasons by — :attr:level (L2 vs L3) and :attr:feed_type (the crossing invariant) — and carries its typed, validated :attr:settings (a :class:~ob_analytics.config.SourceSettings) in place of an untyped dict. There is no base class to inherit: any object providing these members satisfies the contract (structural typing).

A source declares how it produces the shared schema by also satisfying a capability protocol — :class:OfflineSource (replay stored files) and/or :class:LiveSource (capture a live venue). A venue that supports both (e.g. Bitstamp) satisfies both.

Attributes:

Bases: Source, Protocol

A :class:Source that replays stored files into the shared schema.

Bundles the per-source factories the pipeline needs to read from a path: how to load events (or depth), how to acquire trades, and (optionally) how to write results or compute depth directly. Pass instances to Pipeline(source=...).

create_loader(
    config: Any, ctx: RunContext
) -> EventLoader | DepthSource

create_trade_source(
    config: Any, ctx: RunContext
) -> TradeSource

create_writer(
    config: Any, ctx: RunContext
) -> DataWriter | None

compute_depth(
    events: DataFrame,
    config: Any,
    source: Any,
    ctx: RunContext,
) -> tuple[pd.DataFrame, pd.DataFrame] | None

config_defaults() -> dict[str, Any]

required_context() -> list[str]

Bases: Source, Protocol

The live-capture capability of a :class:~ob_analytics.protocols.Source.

A live source is an async iterator of order/trade (or depth) events, plus two bookend methods for snapshot + shutdown synthesis. It inherits the source coordinates from :class:~ob_analytics.protocols.Source — name, level, feed_type, and typed settings — so a venue that both replays files and captures live agrees with itself on those.

:attr:~ob_analytics.protocols.Source.level routes the book events the runner writes: :attr:~ob_analytics.protocols.Level.L3 → per-order events to orders.csv; :attr:~ob_analytics.protocols.Level.L2 → price-level depth updates to depth.csv.

Implementors only worry about parsing. Persistence, raw-frame archival, and signal handling live in ob_analytics.live._runner.

A source does not reconnect on its own. When it loses its connection it raises from :meth:stream: a book carried across a disconnect misses every change made while it was down. :func:~ob_analytics.live.run_capture then closes the segment, waits, and starts a new one from a fresh snapshot, recording the time between them as a gap in manifest.json.

A live source MAY additionally implement :class:SupportsDiagnostics to surface per-run counters in meta.json; that hook is a separate, optional protocol so it is never required to conform to this one.

snapshot(config: CaptureConfig) -> AsyncIterator[EventDict]

stream(
    config: CaptureConfig,
) -> AsyncIterator[tuple[str, EventDict, Any]]

shutdown_synthetic_events() -> AsyncIterator[EventDict]

Bases: Protocol

Structural contract for a measurement taken from a finished run.

A metric reads a run's tables and returns one table of its own, then says how to turn that table into a renderer payload. There is no base class to inherit: any object providing these members satisfies the contract (structural typing), and registering it in :data:~ob_analytics.metrics.METRICS is what makes it run and plot.

:attr:name is both the registry key and the level-less plot concept the metric draws under, so a renderer registered at (name, None, backend) is the metric's face.

Attributes:

compute(result: Any) -> pd.DataFrame

prepare(frame: DataFrame) -> dict[str, Any]