pmlab 0.1.0__py3-none-any.whl

pmlab/__init__.py

@@ -0,0 +1,63 @@
+"""pmlab — Generic ML framework for Polymarket prediction markets."""
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from pmlab.backtest.holdout_gate import HoldoutGateResult, SegmentGateResult
+from pmlab.backtest.metrics import BacktestMetrics, compute_metrics
+from pmlab.core.edge import compute_edge
+from pmlab.core.fees import estimate_fee
+from pmlab.core.market_spec import MarketSpec, OutcomeBin
+from pmlab.core.pnl import Position, settle_position
+from pmlab.core.sizing import flat_stake_size, kelly_fraction, kelly_stake_size
+from pmlab.execution.edge_signal import EdgeSignal
+from pmlab.execution.live_broker import LiveBroker, LiveBrokerError, OrderReceipt
+from pmlab.execution.paper_broker import PaperBroker
+from pmlab.execution.settlement import SettlementEngine
+from pmlab.features.transforms import (
+    add_lags,
+    add_rolling_stats,
+    clip_outliers,
+    encode_cyclical,
+    encode_onehot,
+)
+from pmlab.markets.async_clob_client import AsyncClobClient
+from pmlab.markets.async_gamma_client import AsyncGammaClient
+from pmlab.markets.cache import DiskCache
+from pmlab.markets.clob_client import ClobClient
+from pmlab.markets.gamma_client import GammaClient
+from pmlab.modeling.base import MarketForecaster
+from pmlab.modeling.champion import ChampionManifest
+from pmlab.modeling.diagnostics import BrierDecomposition, brier_decomposition, reliability_data
+from pmlab.modeling.lgbm_baseline import LGBMForecaster
+from pmlab.plugins.base import MarketPlugin
+from pmlab.plugins.registry import PluginRegistry
+from pmlab.reports.html_report import generate_report
+from pmlab.workspace.context import WorkspaceContext
+
+__all__ = [
+    "__version__",
+    # Core
+    "MarketSpec", "OutcomeBin",
+    "Position", "settle_position",
+    "compute_edge", "estimate_fee",
+    "flat_stake_size", "kelly_fraction", "kelly_stake_size",
+    # Execution
+    "EdgeSignal", "PaperBroker", "SettlementEngine",
+    "LiveBroker", "LiveBrokerError", "OrderReceipt",
+    # Features
+    "add_lags", "add_rolling_stats", "encode_cyclical", "encode_onehot", "clip_outliers",
+    # Markets
+    "GammaClient", "ClobClient", "AsyncGammaClient", "AsyncClobClient", "DiskCache",
+    # Modeling
+    "MarketForecaster", "ChampionManifest", "LGBMForecaster",
+    "BrierDecomposition", "brier_decomposition", "reliability_data",
+    # Backtest
+    "HoldoutGateResult", "SegmentGateResult",
+    "BacktestMetrics", "compute_metrics",
+    # Reports
+    "generate_report",
+    # Plugins / Workspace
+    "MarketPlugin", "PluginRegistry",
+    "WorkspaceContext",
+]

pmlab/backtest/holdout_gate.py

@@ -0,0 +1,127 @@
+"""Holdout gate for go/no-go publish decisions."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import pandas as pd
+
+
+@dataclass
+class SegmentGateResult:
+    segment: str
+    num_trades: int
+    total_pnl: float
+    passes: bool
+    reason: str  # "ok" | "negative_pnl" | "insufficient_trades" | "missing"
+
+
+@dataclass
+class HoldoutGateResult:
+    decision: str  # "GO" | "NO_GO"
+    segment_results: list[SegmentGateResult]
+    aggregate_pnl: float
+    aggregate_trades: int
+
+    @classmethod
+    def evaluate(
+        cls,
+        trades: pd.DataFrame,  # columns: realized_pnl, outcome, segment
+        required_segments: list[str],
+        min_trades_per_segment: int = 40,
+        min_pnl_per_segment: float = 0.0,
+    ) -> HoldoutGateResult:
+        """Evaluate holdout gate across required segments.
+
+        Returns GO only if every required segment passes both
+        the PnL and trade-count thresholds.
+        """
+        segment_results: list[SegmentGateResult] = []
+
+        for seg in required_segments:
+            seg_trades = trades[trades["segment"] == seg] if not trades.empty else pd.DataFrame()
+
+            if seg_trades.empty and seg not in (trades["segment"].unique() if not trades.empty else []):
+                # Segment entirely missing from data
+                segment_results.append(
+                    SegmentGateResult(
+                        segment=seg,
+                        num_trades=0,
+                        total_pnl=0.0,
+                        passes=False,
+                        reason="missing",
+                    )
+                )
+                continue
+
+            num = len(seg_trades)
+            total_pnl = float(seg_trades["realized_pnl"].sum())
+
+            if num < min_trades_per_segment:
+                reason = "insufficient_trades"
+                passes = False
+            elif total_pnl < min_pnl_per_segment:
+                reason = "negative_pnl"
+                passes = False
+            else:
+                reason = "ok"
+                passes = True
+
+            segment_results.append(
+                SegmentGateResult(
+                    segment=seg,
+                    num_trades=num,
+                    total_pnl=total_pnl,
+                    passes=passes,
+                    reason=reason,
+                )
+            )
+
+        all_pass = all(r.passes for r in segment_results)
+        decision = "GO" if all_pass else "NO_GO"
+
+        agg_pnl = float(trades["realized_pnl"].sum()) if not trades.empty else 0.0
+        agg_trades = len(trades)
+
+        return cls(
+            decision=decision,
+            segment_results=segment_results,
+            aggregate_pnl=agg_pnl,
+            aggregate_trades=agg_trades,
+        )
+
+    def to_dict(self) -> dict:
+        return {
+            "decision": self.decision,
+            "aggregate_pnl": self.aggregate_pnl,
+            "aggregate_trades": self.aggregate_trades,
+            "segment_results": [
+                {
+                    "segment": r.segment,
+                    "num_trades": r.num_trades,
+                    "total_pnl": r.total_pnl,
+                    "passes": r.passes,
+                    "reason": r.reason,
+                }
+                for r in self.segment_results
+            ],
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict) -> HoldoutGateResult:
+        segment_results = [
+            SegmentGateResult(
+                segment=r["segment"],
+                num_trades=r["num_trades"],
+                total_pnl=r["total_pnl"],
+                passes=r["passes"],
+                reason=r["reason"],
+            )
+            for r in d["segment_results"]
+        ]
+        return cls(
+            decision=d["decision"],
+            segment_results=segment_results,
+            aggregate_pnl=d["aggregate_pnl"],
+            aggregate_trades=d["aggregate_trades"],
+        )

pmlab/backtest/metrics.py

@@ -0,0 +1,53 @@
+"""Backtest performance metrics."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import pandas as pd
+
+
+@dataclass
+class BacktestMetrics:
+    num_trades: int
+    total_pnl: float
+    hit_rate: float
+    avg_pnl_per_trade: float
+    avg_edge: float
+
+
+def compute_metrics(trades: pd.DataFrame) -> BacktestMetrics:
+    """Compute backtest metrics from a trades DataFrame.
+
+    Args:
+        trades: DataFrame with columns:
+            - realized_pnl (float)
+            - outcome ("won" | "lost")
+            - edge (float)
+
+    Returns:
+        BacktestMetrics with aggregated stats. All zeros if trades is empty.
+    """
+    if trades.empty:
+        return BacktestMetrics(
+            num_trades=0,
+            total_pnl=0.0,
+            hit_rate=0.0,
+            avg_pnl_per_trade=0.0,
+            avg_edge=0.0,
+        )
+
+    n = len(trades)
+    total_pnl = float(trades["realized_pnl"].sum())
+    won = (trades["outcome"] == "won").sum()
+    hit_rate = float(won / n)
+    avg_pnl = total_pnl / n
+    avg_edge = float(trades["edge"].mean())
+
+    return BacktestMetrics(
+        num_trades=n,
+        total_pnl=total_pnl,
+        hit_rate=hit_rate,
+        avg_pnl_per_trade=avg_pnl,
+        avg_edge=avg_edge,
+    )

pmlab/backtest/rolling_origin.py

@@ -0,0 +1,142 @@
+"""Walk-forward (rolling origin) evaluation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import pandas as pd
+
+from pmlab.core.pnl import Position, settle_position
+
+
+@dataclass
+class RollingOriginResult:
+    trades: pd.DataFrame  # columns: market_id, eval_date, outcome_label, predicted_prob, market_price, realized_pnl, edge
+    steps: list[dict] = field(default_factory=list)
+
+
+def rolling_origin_eval(
+    panel: pd.DataFrame,
+    model,  # has fit(X, y) and predict_proba(X) -> ndarray
+    min_train_rows: int = 20,
+    stride: int = 10,
+    flat_stake: float = 1.0,
+    taker_bps: float = 30.0,
+) -> RollingOriginResult:
+    """Walk-forward evaluation on a panel dataset.
+
+    panel columns required:
+        market_id, decision_date (str YYYY-MM-DD),
+        outcome_label, winning_label, market_price,
+        + feature_* columns
+
+    For each eval step:
+        - Train on rows with decision_date < eval_date
+        - Predict on rows at eval_date
+        - Select best bin per (market_id, decision_date) by max predicted_prob
+        - Compute PnL using settle_position
+
+    Returns:
+        RollingOriginResult with all trade records and step metadata.
+    """
+    panel = panel.copy()
+    panel["decision_date"] = panel["decision_date"].astype(str)
+
+    feature_cols = [c for c in panel.columns if c.startswith("feature_")]
+
+    sorted_dates = sorted(panel["decision_date"].unique())
+    n_dates = len(sorted_dates)
+
+    all_trades: list[dict] = []
+    steps: list[dict] = []
+
+    # Walk-forward: iterate in stride steps starting after min_train_rows worth of dates
+    for i in range(0, n_dates, stride):
+        eval_date = sorted_dates[i]
+
+        train_mask = panel["decision_date"] < eval_date
+        train_df = panel[train_mask]
+
+        if len(train_df) < min_train_rows:
+            continue
+
+        eval_df = panel[panel["decision_date"] == eval_date]
+        if eval_df.empty:
+            continue
+
+        X_train = train_df[feature_cols]
+        y_train = (train_df["outcome_label"] == train_df["winning_label"]).astype(int)
+
+        X_eval = eval_df[feature_cols]
+
+        model.fit(X_train, y_train)
+        proba = model.predict_proba(X_eval)
+
+        # Handle both binary (shape N,2) and single-column output
+        if proba.ndim == 2 and proba.shape[1] >= 2:
+            prob_positive = proba[:, 1]
+        elif proba.ndim == 2:
+            prob_positive = proba[:, 0]
+        else:
+            prob_positive = proba
+
+        eval_df = eval_df.copy()
+        eval_df["_predicted_prob"] = prob_positive
+
+        # Select best bin per (market_id, decision_date) by max prob
+        best_idx = eval_df.groupby(["market_id", "decision_date"])["_predicted_prob"].idxmax()
+        best_rows = eval_df.loc[best_idx]
+
+        fee_rate = taker_bps / 10_000.0
+
+        for _, row in best_rows.iterrows():
+            price = float(row["market_price"])
+            prob = float(row["_predicted_prob"])
+            edge = prob - price
+            fee_paid = flat_stake * fee_rate
+
+            pos = Position(
+                outcome_label=str(row["outcome_label"]),
+                price=price,
+                size=flat_stake / price if price > 0 else 0.0,
+                side="buy",
+            )
+            pnl = settle_position(pos, str(row["winning_label"]), fee_paid=fee_paid)
+
+            all_trades.append(
+                {
+                    "market_id": row["market_id"],
+                    "eval_date": eval_date,
+                    "outcome_label": row["outcome_label"],
+                    "predicted_prob": prob,
+                    "market_price": price,
+                    "realized_pnl": pnl,
+                    "edge": edge,
+                }
+            )
+
+        steps.append(
+            {
+                "eval_date": eval_date,
+                "train_rows": len(train_df),
+                "eval_rows": len(eval_df),
+                "trades": len(best_rows),
+            }
+        )
+
+    if all_trades:
+        trades_df = pd.DataFrame(all_trades)
+    else:
+        trades_df = pd.DataFrame(
+            columns=[
+                "market_id",
+                "eval_date",
+                "outcome_label",
+                "predicted_prob",
+                "market_price",
+                "realized_pnl",
+                "edge",
+            ]
+        )
+
+    return RollingOriginResult(trades=trades_df, steps=steps)

pmlab/cli/main.py

@@ -0,0 +1,83 @@
+"""CLI entry point — thin typer shell (filled in Phase 8)."""
+
+from __future__ import annotations
+
+import typer
+
+app = typer.Typer(
+    name="pmlab",
+    help="Generic ML framework for Polymarket prediction markets.",
+    no_args_is_help=True,
+)
+
+
+@app.command("version")
+def version_cmd() -> None:
+    """Print the installed version."""
+    from pmlab import __version__
+
+    typer.echo(f"pmlab {__version__}")
+
+
+@app.command("status")
+def status_cmd() -> None:
+    """Show current champion, open trades count, and cumulative PnL."""
+    typer.echo("pmlab status: no champion published yet.")
+
+
+@app.command("scan-markets")
+def scan_markets_cmd(
+    plugin: str = typer.Option(..., "--plugin", "-p", help="Plugin family name (e.g. weather_tmax)"),
+    workspace: str = typer.Option("ops_daily", "--workspace", "-w"),
+) -> None:
+    """Discover open markets for a plugin family."""
+    typer.echo(f"[scan-markets] plugin={plugin} workspace={workspace}")
+    typer.echo("(Configure plugin clients via environment variables)")
+
+
+@app.command("record-trades")
+def record_trades_cmd(
+    plugin: str = typer.Option(..., "--plugin", "-p"),
+    workspace: str = typer.Option("ops_daily", "--workspace", "-w"),
+    min_edge: float = typer.Option(0.20, "--min-edge"),
+) -> None:
+    """Record paper trades from latest scan-edge signals."""
+    typer.echo(f"[record-trades] plugin={plugin} workspace={workspace} min_edge={min_edge}")
+
+
+@app.command("settle-trades")
+def settle_trades_cmd(
+    plugin: str = typer.Option(..., "--plugin", "-p"),
+    workspace: str = typer.Option("ops_daily", "--workspace", "-w"),
+) -> None:
+    """Settle open paper trades against resolved market truth."""
+    typer.echo(f"[settle-trades] plugin={plugin} workspace={workspace}")
+
+
+@app.command("backtest")
+def backtest_cmd(
+    plugin: str = typer.Option(..., "--plugin", "-p"),
+    model: str = typer.Option("lgbm_baseline", "--model", "-m"),
+    stride: int = typer.Option(30, "--stride", help="Walk-forward stride (min 10, never 1 in production)"),
+    workspace: str = typer.Option("historical_real", "--workspace", "-w"),
+) -> None:
+    """Run walk-forward backtest for a plugin+model combination."""
+    if stride < 10:
+        typer.echo(f"[error] stride={stride} is too low — minimum 10. Default stride=1 takes hours.", err=True)
+        raise typer.Exit(1)
+    typer.echo(f"[backtest] plugin={plugin} model={model} stride={stride} workspace={workspace}")
+
+
+@app.command("promote-champion")
+def promote_champion_cmd(
+    model_path: str = typer.Argument(..., help="Path to trained model .pkl"),
+    gate_path: str = typer.Option(..., "--gate-path", help="Path to holdout gate JSON"),
+    plugin: str = typer.Option(..., "--plugin", "-p"),
+    output_dir: str = typer.Option("artifacts/public_models", "--output-dir"),
+) -> None:
+    """Promote a model to champion if gate decision is GO."""
+    typer.echo(f"[promote-champion] model={model_path} gate={gate_path} plugin={plugin}")
+
+
+if __name__ == "__main__":
+    app()

pmlab/core/edge.py

@@ -0,0 +1,27 @@
+"""Edge calculation — domain-agnostic.
+
+Edge is the after-cost expected value of a trade: how much better
+our fair probability is than the market price, minus costs.
+"""
+
+from __future__ import annotations
+
+
+def compute_edge(
+    fair_probability: float,
+    executable_price: float,
+    fee_estimate: float = 0.0,
+    slippage_estimate: float = 0.0,
+) -> float:
+    """Compute after-cost probability edge for a binary outcome bet.
+
+    Args:
+        fair_probability: Our model's estimated probability for this outcome (0–1).
+        executable_price: Market price we actually pay per share (0–1).
+        fee_estimate: Expected taker fee on this trade.
+        slippage_estimate: Expected price impact / slippage.
+
+    Returns:
+        Edge value. Positive = expected profit. Negative = expected loss.
+    """
+    return fair_probability - executable_price - fee_estimate - slippage_estimate

pmlab/core/fees.py

@@ -0,0 +1,21 @@
+"""Fee estimation for Polymarket CLOB trades."""
+
+from __future__ import annotations
+
+# Polymarket CLOB taker fee: 30 basis points on the flat stake.
+DEFAULT_TAKER_BPS: float = 30.0
+
+
+def estimate_fee(flat_stake: float, taker_bps: float = DEFAULT_TAKER_BPS) -> float:
+    """Estimate taker fee for a trade sized at *flat_stake* USDC.
+
+    Polymarket charges taker_bps / 10_000 on the notional stake (not per share).
+
+    Args:
+        flat_stake: Notional USDC being risked (e.g. 1.0 USDC).
+        taker_bps: Taker fee in basis points (default 30 = 0.30%).
+
+    Returns:
+        Fee amount in USDC.
+    """
+    return flat_stake * taker_bps / 10_000.0

pmlab/core/market_spec.py

@@ -0,0 +1,73 @@
+"""Generic market domain models — domain-agnostic core primitives.
+
+These models describe any Polymarket market family without embedding
+domain-specific logic (no weather, no sports, no crypto here).
+Domain plugins extend these via MarketPlugin in pmlab.plugins.base.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class OutcomeBin(BaseModel):
+    """A single outcome bin for a prediction market.
+
+    Supports:
+    - Unbounded bins (binary YES/NO)
+    - Half-open numeric ranges (temperature, price)
+    - Categorical labels (driver name, country)
+
+    For categorical outcomes, leave lower/upper as None and match by label externally.
+    """
+
+    label: str
+    lower: float | None = None
+    upper: float | None = None
+    lower_inclusive: bool = True
+    upper_inclusive: bool = True
+
+    def contains(self, value: float) -> bool:
+        """Return True if *value* falls inside this bin's numeric range."""
+        if self.lower is not None:
+            if self.lower_inclusive and value < self.lower:
+                return False
+            if not self.lower_inclusive and value <= self.lower:
+                return False
+        if self.upper is not None:
+            if self.upper_inclusive and value > self.upper:
+                return False
+            if not self.upper_inclusive and value >= self.upper:
+                return False
+        return True
+
+
+class MarketSpec(BaseModel):
+    """Domain-agnostic descriptor for a single Polymarket market.
+
+    Carries the minimum information needed by the core framework —
+    market identity, outcome structure, and timing.
+    Domain-specific fields (e.g. city, weather station) live in ``metadata``.
+    """
+
+    market_id: str
+    slug: str
+    question: str
+    outcome_bins: list[OutcomeBin]
+    close_time: str
+    market_family: str  # "binary" | "range" | "categorical" | "numeric"
+
+    # Optional enrichment
+    tags: list[str] = Field(default_factory=list)
+    metadata: dict = Field(default_factory=dict)  # domain-specific extras
+
+    def resolve_winning_bin(self, realized_value: float) -> str | None:
+        """Return the label of the first bin whose range contains *realized_value*.
+
+        Returns None if no bin matches (gap in coverage or uncovered value).
+        For categorical markets, resolve externally by label — do not call this.
+        """
+        for bin_ in self.outcome_bins:
+            if bin_.contains(realized_value):
+                return bin_.label
+        return None

pmlab/core/pnl.py

@@ -0,0 +1,48 @@
+"""PnL accounting for binary outcome token positions.
+
+Matches the settlement logic used in polymarket-tmax-lab (pmtmax.backtest.pnl).
+Works for any Polymarket market family — weather, sports, crypto.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class Position:
+    """An open binary outcome token position.
+
+    Attributes:
+        outcome_label: The outcome bin label this position is on (e.g. "YES", "30°C", "Verstappen").
+        price: Entry price per share (0.0–1.0).
+        size: Number of shares held (flat_stake / entry_price).
+        side: "buy" (long YES) or "sell" (short YES / long NO).
+    """
+
+    outcome_label: str
+    price: float
+    size: float
+    side: str  # "buy" | "sell"
+
+
+def settle_position(position: Position, winning_label: str, fee_paid: float = 0.0) -> float:
+    """Compute realized PnL when market resolves.
+
+    Formula (mirrors Polymarket binary settlement):
+        payout = 1.0 if position.outcome_label == winning_label else 0.0
+        buy:  pnl = (payout - price) * size - fee_paid
+        sell: pnl = (price - payout) * size - fee_paid
+
+    Args:
+        position: The open position to settle.
+        winning_label: The resolved outcome label.
+        fee_paid: Total fee already paid at entry (not charged again here).
+
+    Returns:
+        Signed PnL in USDC (positive = profit, negative = loss).
+    """
+    payout = 1.0 if position.outcome_label == winning_label else 0.0
+    if position.side == "buy":
+        return (payout - position.price) * position.size - fee_paid
+    return (position.price - payout) * position.size - fee_paid