mostlyrightmd-markets 0.1.3__tar.gz

mostlyrightmd_markets-0.1.3/.gitignore

@@ -0,0 +1,68 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg
+*.egg-info/
+build/
+dist/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Testing / linting
+.pytest_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+
+# Local cache (tradewinds runtime cache lives in $HOME/.tradewinds/; this catches any test-time fixtures that leak)
+.tradewinds-cache/
+
+# Phase 4 CI-05 — drift watchdog populates tests/fixtures/drift/ from the
+# weekly cron. The scripts + README are tracked; the captured parquets
+# and the drift-report are not (rotation is the whole point — git history
+# isn't the storage layer for drift fixtures).
+tests/fixtures/drift/case_*.parquet
+tests/fixtures/drift/drift-report.md
+
+# uv — uv.lock IS committed for dev reproducibility across Lane F + Lane V (decision: lockfile-tracked for dev parity)
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+.claude/scheduled_tasks.lock
+
+# Planning artifacts — local GSD planning workspace; NOT for public consumption.
+# Untracked since the repo went public (Phase 13 W0 cleanup commit, 2026-05-25).
+# Operators keep these on disk for ongoing GSD workflow; nothing in `.planning/`
+# should be required to build or run the SDK.
+.planning/
+
+# Dev-only TODO scratchpad (replaced by GSD TODOS in .planning/)
+TODOS.md
+
+# TypeScript / pnpm workspace (packages-ts/)
+node_modules/
+coverage/
+.tsbuildinfo
+packages-ts/*/dist/
+packages-ts/*/coverage/
+# Note: top-level `dist/` and `build/` already covered by Python section above.
+
+# TS-W2 Plan 08 drift watchdog — output files are transient, not committed.
+packages-ts/meta/tests/parity/drift/*.json
+packages-ts/meta/tests/parity/drift-report.md
+.claude/

mostlyrightmd_markets-0.1.3/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.4
+Name: mostlyrightmd-markets
+Version: 0.1.3
+Summary: Prediction market data for mostlyright: Kalshi (NHIGH/NLOW contract specs in v0.1.0rc1, market metadata in Sprint 0.5), Polymarket (Phase 3.3). Python module: `import mostlyright.markets`.
+Author-email: Robert Tarabcak <tarabcakr@gmail.com>
+License-Expression: MIT
+Keywords: kalshi,polymarket,prediction-markets
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: jsonschema>=4.21
+Requires-Dist: mostlyrightmd<0.2,>=0.1.0
+Provides-Extra: parquet
+Requires-Dist: pandas<4.0,>=2.2; extra == 'parquet'
+Requires-Dist: pyarrow<24.0,>=17.0; extra == 'parquet'
+Provides-Extra: polars
+Requires-Dist: narwhals<2.0,>=1.20; extra == 'polars'
+Requires-Dist: pandas<4.0,>=2.2; extra == 'polars'
+Requires-Dist: polars<2.0,>=1.0; extra == 'polars'
+Requires-Dist: pyarrow<24.0,>=17.0; extra == 'polars'
+Provides-Extra: polymarket
+Requires-Dist: mostlyrightmd-weather<0.2,>=0.1.0; extra == 'polymarket'
+Requires-Dist: pandas<4.0,>=2.2; extra == 'polymarket'
+Provides-Extra: trades
+Requires-Dist: filelock<4,>=3.20; extra == 'trades'
+Requires-Dist: pandas<4.0,>=2.2; extra == 'trades'
+Requires-Dist: pyarrow<24.0,>=17.0; extra == 'trades'
+Description-Content-Type: text/markdown
+
+# mostlyrightmd-markets
+
+Prediction market data for `mostlyright`: Kalshi, Polymarket.
+
+🚧 **v0.0.1 is a placeholder.** Real Kalshi metadata client lands in v0.1.0 (Sprint 0.5) — port from `therminal/therminal-ingest/src/sources/kalshi/` (TypeScript reference). Public endpoints, no auth required.
+
+See the workspace [README](../../README.md) and [CLAUDE.md](../../CLAUDE.md) for project rules.

mostlyrightmd_markets-0.1.3/README.md

@@ -0,0 +1,7 @@
+# mostlyrightmd-markets
+
+Prediction market data for `mostlyright`: Kalshi, Polymarket.
+
+🚧 **v0.0.1 is a placeholder.** Real Kalshi metadata client lands in v0.1.0 (Sprint 0.5) — port from `therminal/therminal-ingest/src/sources/kalshi/` (TypeScript reference). Public endpoints, no auth required.
+
+See the workspace [README](../../README.md) and [CLAUDE.md](../../CLAUDE.md) for project rules.

mostlyrightmd_markets-0.1.3/pyproject.toml

@@ -0,0 +1,79 @@
+[project]
+name = "mostlyrightmd-markets"
+version = "0.1.3"
+description = "Prediction market data for mostlyright: Kalshi (NHIGH/NLOW contract specs in v0.1.0rc1, market metadata in Sprint 0.5), Polymarket (Phase 3.3). Python module: `import mostlyright.markets`."
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "Robert Tarabcak", email = "tarabcakr@gmail.com" }]
+requires-python = ">=3.11"
+keywords = ["kalshi", "polymarket", "prediction-markets"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    # PKG-03: pin mostlyright (core) so users cannot mix markets/core releases
+    # across the canonical-schema boundary. The Kalshi resolvers use
+    # mostlyright.markets.catalog (this package) but the wider settlement
+    # pipeline reads mostlyright.core.* schemas; a stale core would silently
+    # serve the wrong column set.
+    "mostlyrightmd>=0.1.0,<0.2",
+    "httpx>=0.27",
+    "jsonschema>=4.21",
+]
+
+[project.optional-dependencies]
+# Mirrors the core `parquet` extra caps (PKG-05, PKG-06) so a future install
+# cannot silently drift across the parity-critical pandas/pyarrow boundary.
+parquet = [
+    "pyarrow>=17.0,<24.0",
+    "pandas>=2.2,<4.0",
+]
+# Phase 3.3: Polymarket discovery + settlement. polymarket_discover()
+# returns a DataFrame (pandas required); polymarket_settle() calls
+# daily_extremes() which imports mostlyright.weather.cache (sibling
+# weather package required). Codex iter-1 P2: without these the
+# polymarket_* public surface raises ModuleNotFoundError on every call.
+# Users opt in via `pip install mostlyrightmd-markets[polymarket]`.
+polymarket = [
+    "pandas>=2.2,<4.0",
+    "mostlyrightmd-weather>=0.1.0,<0.2",
+]
+# Phase 9: trade-history surface. kalshi_trades + polymarket_trades return
+# DataFrames (pandas required); _trades_cache writes parquet (pyarrow
+# required) with FileLock-guarded atomic writes (filelock required).
+# Phase 9 iter-5 codex HIGH: the install hints in kalshi_trades.py /
+# polymarket_trades.py / _trades_cache.py reference this extra by name;
+# the extra was missing from pyproject.toml, so the advertised
+# `pip install mostlyrightmd-markets[trades]` would fail with
+# `WARNING: mostlyrightmd-markets X does not provide the extra 'trades'`
+# and a clean install would still raise `ModuleNotFoundError: filelock`
+# the first time the cache is hit. Pinned to the same parity-critical
+# pandas/pyarrow boundaries as `[parquet]`/`[polymarket]` (PKG-05/06).
+# NB: pandas pinned to <4.0 to match Phase 6's pandas-3 broadening.
+trades = [
+    "pandas>=2.2,<4.0",
+    "pyarrow>=17.0,<24.0",
+    "filelock>=3.20,<4",
+]
+# Phase 6 (POLARS-05): mirror mostlyrightmd[polars] so polymarket_discover
+# can return polars frames via the `backend="polars"` kwarg.
+# pandas required for the boundary shim's polars↔pandas conversion
+# (codex iter-3 P2 fix). pyarrow required by pl.from_pandas/to_pandas
+# for non-trivial dtypes (codex iter-5 P1 fix).
+polars = [
+    "polars>=1.0,<2.0",
+    "narwhals>=1.20,<2.0",
+    "pandas>=2.2,<4.0",
+    "pyarrow>=17.0,<24.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mostlyright"]

mostlyrightmd_markets-0.1.3/src/mostlyright/markets/__init__.py

@@ -0,0 +1,19 @@
+"""mostlyright.markets — prediction market data (Kalshi, Polymarket).
+
+v0.0.1 is a PLACEHOLDER only. Real functionality lands in v0.1.0 (Sprint 0.5)
+when Lane V ports the Kalshi metadata client from
+``therminal/therminal-ingest/src/sources/kalshi/`` (TypeScript reference)
+using endpoints documented in ``therminal/research/notes/research-kalshi-api.md``
+(no auth required for public market data).
+
+Sprint 0 ships ONLY ``mostlyright`` + ``mostlyrightmd-weather`` at v0.1.0;
+``mostlyrightmd-markets`` stays at v0.0.1 placeholder until Sprint 0.5.
+
+Roadmap:
+- Sprint 0.5: ``mostlyright.markets.kalshi.{series, events, markets, candles, research_by_market}``
+- Sprint 3: ``mostlyright.markets.polymarket.*`` (port from
+  ``monorepo-v0.14.1/src/mostlyright/_polymarket.py``)
+"""
+
+__version__ = "0.0.1"
+__all__ = ["__version__"]

mostlyrightmd_markets-0.1.3/src/mostlyright/markets/_kalshi_client.py

@@ -0,0 +1,292 @@
+"""Kalshi public REST client — Phase 9.
+
+Public read-only Kalshi market-data API at
+``https://api.elections.kalshi.com/trade-api/v2``. No auth required, no
+API key, no key registration — the candlestick, trades, and orderbook
+endpoints are documented as public.
+
+Kalshi documents a 10 req/sec rate limit for public endpoints (see
+``.planning/research/MARKETS-RATE-LIMITS.md``). The 0.1s per-request
+polite floor matches that ceiling exactly without throttling normal
+backtest runs.
+
+The module is deliberately narrow — only what
+:mod:`mostlyright.markets.kalshi_trades` needs for v0.2 candles + fills +
+orderbook. Authenticated endpoints (orders, positions, account state)
+are out of scope and intentionally not exposed.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any
+
+import httpx
+
+log = logging.getLogger(__name__)
+
+
+#: Kalshi public REST endpoint base URL.
+KALSHI_API_BASE: str = "https://api.elections.kalshi.com/trade-api/v2"
+
+
+#: Per-request polite floor. Kalshi documents 10 req/sec ceiling for
+#: public endpoints; 0.1s spaces requests to exactly match without
+#: tripping the 429 burst threshold. Tests pass ``sleep_between=0`` to
+#: skip.
+_REQUEST_DELAY_S: float = 0.1
+
+
+#: Per-page batch size for paginated trade endpoints.
+_TRADES_PAGE_LIMIT: int = 1000
+
+
+#: HTTP status codes that warrant a retry (transient).
+_TRANSIENT_CODES: frozenset[int] = frozenset({429, 500, 502, 503, 504})
+
+
+#: Bounded retry budget per request.
+_MAX_RETRIES: int = 3
+
+
+#: Base exponential backoff delay (doubled each retry).
+_BASE_DELAY: float = 1.0
+
+
+#: Upper cap on the per-attempt sleep induced by a server ``Retry-After``
+#: header. A hostile or buggy upstream returning ``Retry-After: 86400``
+#: would otherwise hang the SDK for ~24h per retry; ~2 retries → 48h.
+#: 120s = 2-minute ceiling matches the AWS SDK default and is more than
+#: enough headroom for any legitimate Kalshi rate-limit backoff hint.
+#: Iter-2 python-architect HIGH.
+_MAX_RETRY_AFTER_S: float = 120.0
+
+
+#: Safety cap on total pages walked per `fetch_trades` call. 10k pages *
+#: 1000 trades/page = 10M trades, well beyond any sane backtest scope.
+_MAX_TRADES_PAGES: int = 10_000
+
+
+#: User-Agent banner. Sites occasionally block blank UAs as bot traffic.
+_USER_AGENT: str = "mostlyrightmd-markets/0.2 (+https://github.com/mostlyrightmd/mostlyright-sdk)"
+
+
+def _request(
+    path: str,
+    *,
+    params: dict[str, Any] | None = None,
+    client: httpx.Client | None = None,
+    sleep_between: float | None = None,
+    timeout: float = 30.0,
+) -> Any:
+    """GET ``path`` and return decoded JSON.
+
+    Retries 429/5xx with exponential backoff. 4xx (other than 429)
+    surfaces immediately so callers see permanent errors (bad ticker,
+    bad params) rather than wasting the retry budget.
+
+    Args:
+        path: Path under ``KALSHI_API_BASE`` (must start with ``/``).
+        params: Optional query parameters.
+        client: Optional ``httpx.Client`` for connection reuse.
+        sleep_between: Per-request polite sleep. ``None`` uses the
+            default 0.1s floor; tests pass ``0``.
+        timeout: Per-request httpx timeout in seconds.
+
+    Returns:
+        Parsed JSON payload (``dict`` or ``list``).
+    """
+    if sleep_between is None:
+        sleep_between = _REQUEST_DELAY_S
+    url = f"{KALSHI_API_BASE}{path}"
+    headers = {"User-Agent": _USER_AGENT, "Accept": "application/json"}
+    owns_client = client is None
+    if client is None:
+        client = httpx.Client(timeout=timeout)
+    try:
+        delay = _BASE_DELAY
+        for attempt in range(_MAX_RETRIES):
+            response = client.get(url, params=params, headers=headers)
+            if response.status_code in _TRANSIENT_CODES and attempt < _MAX_RETRIES - 1:
+                # Architect iter-1 CRITICAL: honor the upstream Retry-After
+                # header if present. RFC 7231 §7.1.3 allows either an int
+                # (seconds) or an HTTP-date; we honor the integer form (Kalshi
+                # documents seconds). Use max(retry_after, delay) so a
+                # smaller server hint doesn't shorten our exponential
+                # backoff and lose monotonicity.
+                retry_after = _parse_retry_after_seconds(response.headers.get("Retry-After"))
+                # Iter-2 python-architect HIGH: cap Retry-After at
+                # _MAX_RETRY_AFTER_S so a hostile/buggy upstream cannot
+                # pin the SDK in time.sleep() for arbitrary durations.
+                if retry_after is not None:
+                    retry_after = min(retry_after, _MAX_RETRY_AFTER_S)
+                sleep_s = max(retry_after, delay) if retry_after is not None else delay
+                log.warning(
+                    "kalshi HTTP %d for %s, retry %d/%d in %.1fs%s",
+                    response.status_code,
+                    url,
+                    attempt + 1,
+                    _MAX_RETRIES,
+                    sleep_s,
+                    f" (Retry-After={retry_after}s)" if retry_after is not None else "",
+                )
+                time.sleep(sleep_s)
+                delay *= 2
+                continue
+            response.raise_for_status()
+            if sleep_between > 0:
+                time.sleep(sleep_between)
+            return response.json()
+        # Loop only exits via `continue` (transient + budget remaining) or
+        # `return`. Reaching here means the final attempt was transient and
+        # raise_for_status didn't fire — defensive RuntimeError.
+        raise RuntimeError(  # pragma: no cover — unreachable
+            f"kalshi {url}: exhausted retries without raising"
+        )
+    finally:
+        if owns_client:
+            client.close()
+
+
+def fetch_candlesticks(
+    ticker: str,
+    *,
+    start_ts: int,
+    end_ts: int,
+    period_interval: int,
+    client: httpx.Client | None = None,
+    sleep_between: float | None = None,
+) -> list[dict[str, Any]]:
+    """Fetch OHLCV candlesticks for a Kalshi market.
+
+    Args:
+        ticker: Full market ticker (e.g. ``KXHIGHNY-25MAY26-T79``). The
+            series ticker is parsed as the prefix before the first ``-``.
+        start_ts, end_ts: UNIX timestamps (seconds) bounding the window.
+        period_interval: Bucket size in MINUTES (Kalshi documents 1, 60, 1440).
+        client: Optional ``httpx.Client``.
+        sleep_between: Per-request polite sleep override.
+
+    Returns:
+        List of candle dicts as returned by Kalshi (shape:
+        ``{"end_period_ts": int, "price": {"open": int, "high": int,
+        "low": int, "close": int}, "volume": int, "open_interest": int}``).
+        Empty list when no candles in the window.
+    """
+    if "-" not in ticker:
+        raise ValueError(f"kalshi ticker must contain '-' to derive series prefix; got {ticker!r}")
+    series = ticker.split("-", 1)[0]
+    path = f"/series/{series}/markets/{ticker}/candlesticks"
+    params = {
+        "start_ts": start_ts,
+        "end_ts": end_ts,
+        "period_interval": period_interval,
+    }
+    payload = _request(path, params=params, client=client, sleep_between=sleep_between)
+    candles = payload.get("candlesticks") if isinstance(payload, dict) else None
+    return list(candles) if candles else []
+
+
+def fetch_trades(
+    ticker: str,
+    *,
+    min_ts: int | None = None,
+    max_ts: int | None = None,
+    limit: int = _TRADES_PAGE_LIMIT,
+    client: httpx.Client | None = None,
+    sleep_between: float | None = None,
+    max_pages: int = _MAX_TRADES_PAGES,
+) -> list[dict[str, Any]]:
+    """Fetch historical fills for ``ticker``, paginated via cursor.
+
+    The cursor field is documented but its exact name varies — we
+    forward whatever key the upstream returned. When the cursor is
+    empty or missing, pagination terminates.
+
+    Args:
+        ticker: Full market ticker.
+        min_ts, max_ts: Optional UNIX timestamp bounds.
+        limit: Per-page count (default 1000, Kalshi's documented max).
+        client: Optional ``httpx.Client``.
+        sleep_between: Per-request polite sleep override.
+        max_pages: Safety cap on total pages walked. Raises
+            :class:`RuntimeError` if exceeded.
+
+    Returns:
+        List of trade dicts.
+    """
+    path = "/markets/trades"
+    out: list[dict[str, Any]] = []
+    cursor: str | None = None
+    pages = 0
+    while True:
+        params: dict[str, Any] = {"ticker": ticker, "limit": limit}
+        if min_ts is not None:
+            params["min_ts"] = min_ts
+        if max_ts is not None:
+            params["max_ts"] = max_ts
+        if cursor:
+            params["cursor"] = cursor
+        payload = _request(path, params=params, client=client, sleep_between=sleep_between)
+        trades = payload.get("trades") if isinstance(payload, dict) else None
+        if trades:
+            out.extend(trades)
+        cursor = (
+            payload.get("cursor") if isinstance(payload, dict) else None  # type: ignore[arg-type]
+        )
+        pages += 1
+        if not cursor or not trades:
+            break
+        if pages >= max_pages:
+            raise RuntimeError(
+                f"kalshi fetch_trades({ticker!r}) exceeded max_pages={max_pages}; "
+                "narrow the window via min_ts/max_ts or raise the cap"
+            )
+    return out
+
+
+def fetch_orderbook(
+    ticker: str,
+    *,
+    depth: int = 50,
+    client: httpx.Client | None = None,
+    sleep_between: float | None = None,
+) -> dict[str, Any]:
+    """Fetch current orderbook snapshot for ``ticker``."""
+    if depth < 1 or depth > 1000:
+        raise ValueError(f"depth out of range [1, 1000]: {depth}")
+    path = f"/markets/{ticker}/orderbook"
+    payload = _request(path, params={"depth": depth}, client=client, sleep_between=sleep_between)
+    if not isinstance(payload, dict):
+        raise RuntimeError(
+            f"kalshi orderbook for {ticker!r}: expected dict payload, got {type(payload).__name__}"
+        )
+    return payload
+
+
+def _parse_retry_after_seconds(value: str | None) -> float | None:
+    """Parse an HTTP ``Retry-After`` header into seconds.
+
+    RFC 7231 §7.1.3 allows either delta-seconds (int) or an HTTP-date.
+    We honor the int form only — Kalshi documents seconds. HTTP-date is
+    rare in 429 contexts and not worth a date parser. Negative / unparseable
+    values return ``None`` so the caller falls back to its own backoff.
+    """
+    if not value:
+        return None
+    try:
+        s = float(value.strip())
+    except (TypeError, ValueError):
+        return None
+    if s < 0 or not (s == s) or s == float("inf"):
+        return None
+    return s
+
+
+__all__ = [
+    "KALSHI_API_BASE",
+    "fetch_candlesticks",
+    "fetch_orderbook",
+    "fetch_trades",
+]