mostlyright.markets.kalshi

Kalshi thin-sugar layer over the venue-free core composition body.

markets.kalshi.training_table(ticker, ...) owns ALL Kalshi venue knowledge — series/city → settlement station resolution, the label="cli" routing (Kalshi NHIGH/NLOW settle on the NWS CLI product), trades columns — and delegates the entire feature-composition + join to the core private _dataset_impl body. There is ZERO duplicated join logic here: the wrapper resolves a station, then forwards to core with label="cli".

outcome=True appends a single label_outcome column derived from a NET-NEW Kalshi strike parser (there is no settlement engine to reuse — the catalog resolves city → station only). The parser reads the strike from the full market ticker and binarizes the venue’s own label column against it.

Kalshi settlement comparison (DOCUMENTED CHOICE — see _settle_threshold()): -T<strike> threshold markets (“{strike}° or above”) resolve YES when the settlement value is >= strike (INCLUSIVE — boundary equality is YES). -B<lo>-<hi> range/between markets resolve YES when lo <= value <= hi (both ends INCLUSIVE — Kalshi’s integer-degree range buckets partition the degree space contiguously, e.g. then, so both endpoints belong to exactly one bucket).

Module Attributes

label	The kalshi.label namespace singleton (kalshi.label.settlement(...)).

Functions

parse_ticker(ticker)	Parse a full Kalshi market ticker → structured (series, strike, station).
settlement_days(entity, from_date, to_date)	The bare Kalshi settlement-day grid (train == live — the skew guard).
training_table(entity, from_date, to_date, *)	Kalshi leakage-free supervised table over the label="cli" settlement target.

Exceptions

KalshiTickerError	A Kalshi market ticker could not be parsed to (series, city, strike).

exception mostlyright.markets.kalshi.KalshiTickerError

Bases: ValueError

A Kalshi market ticker could not be parsed to (series, city, strike).

Subclasses ValueError so existing pytest.raises(ValueError) guards and callers catching ValueError keep working.

mostlyright.markets.kalshi.label = <mostlyright.markets.kalshi._KalshiLabel object>

The kalshi.label namespace singleton (kalshi.label.settlement(...)).

mostlyright.markets.kalshi.parse_ticker(ticker)

Parse a full Kalshi market ticker → structured (series, strike, station).

NET-NEW parser (there is no settlement engine to reuse — the catalog only resolves city → station). Handles both strike shapes:

• KXHIGHNY-25MAY26-T79 → threshold, T79 (high >= 79 → YES)
• KXLOWCHI-25MAY26-B40-42 → range, 40 <= low <= 42 → YES

• Parameters: ticker (str) – The full market ticker (<SERIES>-<DATECODE>-<STRIKE>).
• Return type: _ParsedTicker
• Returns: A _ParsedTicker.
• Raises: KalshiTickerError – the ticker doesn’t decompose into series / date / strike, the series isn’t a HIGH/LOW weather series, the strike isn’t a T/B form, or the city isn’t in the settlement whitelist.

mostlyright.markets.kalshi.settlement_days(entity, from_date, to_date)

The bare Kalshi settlement-day grid (train == live — the skew guard).

TWO POSITIONAL DATES (inclusive ends). entity is a full Kalshi ticker (or a list). Each ticker resolves its settlement station via the parity-critical catalog whitelist (parse_ticker — ZERO duplicated station logic); the grid is one row per LST settlement day with NO y columns.

IDENTITY RETENTION: every returned row RETAINS its originating ticker as the LEADING column (before station and the date day field), so concatenating several contracts never collapses provenance — a per-row ticker survives the concat and each day is attributable to the contract that minted it.

The caller names the contracts; the factory mints the calendar for the settlement station(s) they existed under. PIT-correct rolling-feature transforms are OUT of scope (computed inside sources or by users downstream at their own risk).

• Parameters:
  • entity (str | list[str] | tuple[str, ...]) – A full Kalshi ticker, or a list of tickers for a long-format panel.
  • from_date (str) – Inclusive start date.
  • to_date (str) – Inclusive end date.
• Return type: DataFrame

Example

>>> grid = settlement_days("KXHIGHNY", "2025-01-06", "2025-01-12")
>>> grid.columns[:3].tolist()
['ticker', 'station', 'date']

mostlyright.markets.kalshi.training_table(entity, from_date, to_date, , outcome=False, features=None)

Kalshi leakage-free supervised table over the label="cli" settlement target.

THIN DELEGATOR — zero duplicated join logic. Resolves the settlement station from entity (the full Kalshi ticker, via the parity-critical catalog whitelist), then forwards the whole feature-composition + join to core research.dataset with label="cli" (Kalshi NHIGH/NLOW settle on the NWS CLI product). TWO positional dates. outcome=True appends a single binary label_outcome column from the NET-NEW strike parser.

This is the markets analogue of weather.training_table(); it composes the domain day-grid factory + sources (kalshi.settlement_days() / kalshi.label.settlement() + the core observation join). The old kalshi.dataset() name is a deprecation shim routing here — dataset is reserved for the catalog noun.

Trades: live trade columns are attached via the dedicated mostlyright.markets._kalshi_trades surface (candles/fills/orderbook), NOT this settlement-join wrapper. The core "trades" feature remains a contract-gated stub (a station-path features=["trades"] raises the documented core ValueError until the real contribute() wiring lands).

• Parameters:
  • entity (str) – The full Kalshi market ticker (KXHIGHNY-25MAY26-T79 / KXLOWCHI-25MAY26-B40-42). Its series → settlement station and, when outcome=True, its strike → the outcome comparison.
  • from_date (str) – YYYY-MM-DD window bounds (forwarded verbatim).
  • to_date (str) – YYYY-MM-DD window bounds (forwarded verbatim).
  • outcome (bool) – When True, append a binary label_outcome (Int64, 0/1/NA) column: 1 when the day’s settlement value settles the market YES per the documented comparison rule (see _settle_threshold()).
  • features (list[str] | tuple[str, ...] | None) – Extra core feature names forwarded verbatim to the core composition.
• Return type: DataFrame
• Returns: The core dataset(label="cli", ...) frame (⊇ byte-identical core columns) plus, when outcome=True, the label_outcome column.
• Raises: KalshiTickerError – the ticker doesn’t parse or its city isn’t in the settlement whitelist.