mostlyright.markets.kalshi

mostlyright.markets.kalshi

Kalshi thin-sugar layer over the venue-free core dataset() (Phase 32 32-03).

markets.kalshi.dataset(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 core mostlyright.research.dataset(). 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. 79-80 then 81-82, so both endpoints belong to exactly one bucket).

Functions

dataset(ticker, from_date, to_date, *[, …])	Kalshi convenience wrapper over core dataset(label="cli", ...).
parse_ticker(ticker)	Parse a full Kalshi market ticker → structured (series, strike, station).

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.dataset(ticker, from_date, to_date, , outcome=False, include_trades=False, features=None, **core_kwargs)

Kalshi convenience wrapper over core dataset(label="cli", ...).

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

Trades: the core "trades" feature is still a contract-gated stub (33-01 registered it as a marker; the real contribute() wiring is deferred — a station-path features=["trades"] raises the documented core ValueError). This wrapper therefore defaults include_trades=False so delegation always succeeds. Live trade columns are attached via the dedicated mostlyright.markets.kalshi_trades surface (candles/fills/ orderbook), NOT this settlement-join wrapper. Passing include_trades=True forwards it honestly and surfaces the core ValueError loudly (never a silent no-op) until the core trades contribute() lands.

• Parameters:
  • ticker (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()).
  • include_trades (bool) – Default False (see the Trades note). When True, the "trades" feature is forwarded to core (raises the documented core ValueError while trades stays contract-gated).
  • features (list[str] | tuple[str, ...] | None) – Extra core feature names (merged with "trades" when include_trades is True).
  • **core_kwargs (Any) – Forwarded verbatim to core dataset() (e.g. granularity=, source=, tz_override=, qc=).
• 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.

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.