pmlab 0.1.0__tar.gz

pmlab-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,58 @@
+name: CI
+
+on:
+  push:
+    branches: [main, "feat/**", "fix/**"]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Test (Python 3.12)
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Lint (ruff)
+        run: uv run ruff check src/ tests/
+
+      - name: Run tests with coverage
+        run: uv run pytest --cov=src/pmlab --cov-report=term-missing --cov-fail-under=70
+
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    needs: test
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Build wheel + sdist
+        run: uv build
+
+      - name: Verify dist contents
+        run: ls -la dist/

pmlab-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+# gitignore para Python library
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+*.lock
+!uv.lock
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+*.log
+.DS_Store

pmlab-0.1.0/AGENTS.md

@@ -0,0 +1,155 @@
+# pmlab Agent Guide
+
+## Purpose
+
+`pmlab` is a **generic, plugin-based ML framework** for Polymarket prediction markets.
+It is designed to be published as a Python library (pip/uv installable).
+
+The framework is market-family agnostic: each domain (weather, sports, politics, crypto)
+implements a `MarketPlugin` and the core handles everything else.
+
+Use this file as the shared contract for all agents (Codex, Claude, etc).
+
+---
+
+## Module Ownership
+
+| Module | Owns |
+|--------|------|
+| `src/pmlab/core/` | MarketSpec, OutcomeBin, PnL, edge, fees, sizing — no domain logic |
+| `src/pmlab/plugins/` | MarketPlugin ABC, PluginRegistry, domain plugin implementations |
+| `src/pmlab/plugins/weather_tmax/` | Weather/temperature market plugin (reference implementation) |
+| `src/pmlab/plugins/sports_f1/` | F1 race outcome plugin |
+| `src/pmlab/backtest/` | Rolling-origin eval, metrics, HoldoutGate — no lookahead |
+| `src/pmlab/modeling/` | MarketForecaster ABC, LGBMForecaster, calibration, ChampionManifest |
+| `src/pmlab/execution/` | EdgeSignal, PaperBroker, SettlementEngine |
+| `src/pmlab/workspace/` | WorkspaceContext — multi-workspace path isolation |
+| `src/pmlab/markets/` | Polymarket Gamma API client, CLOB price client (Phase 4) |
+| `src/pmlab/cli/` | Typer CLI entry points |
+
+---
+
+## Safety Rules
+
+1. **Never publish a champion with NO_GO gate.**
+   `ChampionManifest.publish()` hard-raises `ValueError` if `gate.decision != "GO"`.
+   This is not configurable. A failed gate must be investigated, not bypassed.
+
+2. **Never overwrite canonical training data without explicit `--allow-overwrite`.**
+   Experiments use variant output paths. Canonical data is for stable baselines only.
+
+3. **Never mix workspace data.**
+   `ops_daily` is live forward evidence only. `historical_real` is training data.
+   A model trained on ops_daily data is contaminated — do not promote it.
+
+4. **Always use `scripts/pmlab-workspace <name> <cmd>` for workspace-scoped operations.**
+   This sets `PMLAB_ARTIFACTS_DIR` and friends so all paths resolve correctly.
+
+5. **City/segment gate always reads from `champion.json`.**
+   The `recent_core_benchmark_summary.json` (or equivalent) is overwritten on each retrain.
+   `champion.json` reflects the gate at promotion time and is the authoritative source.
+
+6. **Never settle trades before `plugin.is_truth_final()` returns True.**
+   Some data sources have a lag (e.g. weather stations). Wait for finalization.
+
+---
+
+## Adding a New Plugin
+
+1. Create `src/pmlab/plugins/<your_family>/plugin.py`
+2. Subclass `MarketPlugin` from `pmlab.plugins.base`
+3. Set `family = "your_family"`
+4. Implement all 4 abstract methods: `discover_markets`, `fetch_features`, `fetch_truth`, `build_training_row`
+5. Optionally override `is_truth_final()` if your data source has a finalization lag
+6. Add tests in `tests/plugins/<your_family>/`
+7. Register via `PluginRegistry.register(YourPlugin())`
+
+See `src/pmlab/plugins/weather_tmax/plugin.py` as the reference implementation.
+See `docs/plugin-authoring.md` for the full guide.
+
+---
+
+## Standard Commands
+
+```bash
+# Install in development mode
+uv sync --extra dev
+
+# Run all tests
+uv run pytest
+
+# Run tests with coverage
+uv run pytest --cov=src/pmlab --cov-report=term-missing
+
+# Lint
+uv run ruff check src/ tests/
+
+# Type check
+uv run mypy src/
+
+# Workspace-scoped command
+scripts/pmlab-workspace ops_daily uv run pmlab scan-edge --plugin weather_tmax
+
+# Build distribution
+uv build
+```
+
+---
+
+## Commit Convention
+
+Format: `<type>: <subject>` — imperative, no period.
+
+Types: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `ci`, `perf`
+
+Examples:
+- `feat: add SportsF1Plugin with categorical outcome bins`
+- `fix: champion gate reads from champion.json not retrain summary`
+- `test: add rolling_origin no-lookahead assertion`
+- `docs: update plugin-authoring guide with is_truth_final`
+
+---
+
+## TDD Contract
+
+Every new module gets tests BEFORE implementation:
+1. Write test → run → confirm RED (import error or assertion failure)
+2. Implement minimal code → run → confirm GREEN
+3. Refactor → run → confirm still GREEN
+4. Commit
+
+Coverage gate: 70% minimum (enforced in pyproject.toml).
+
+---
+
+## Architecture Summary
+
+```
+Polymarket API ──► MarketPlugin.discover_markets() ──► list[MarketSpec]
+                                │
+                                ├──► MarketPlugin.fetch_features()   ──► features dict
+                                ├──► MarketPlugin.fetch_truth()       ──► realized outcome
+                                └──► MarketPlugin.build_training_row() ──► training row
+                                              │
+                    ┌─────────────────────────┘
+                    │
+                    ▼
+            rolling_origin_eval(panel, model)
+                    │
+                    ├──► BacktestMetrics (PnL, hit_rate, edge)
+                    └──► HoldoutGate.evaluate(required_segments) ──► GO / NO_GO
+                                            │
+                                           GO
+                                            │
+                              ChampionManifest.publish(model, gate)
+                              (hard-raises on NO_GO)
+                                            │
+                                     champion.json
+                                     champion.pkl
+                                            │
+                              PaperBroker.record(signals)
+                              (reads allowed_segments from champion.json)
+                                            │
+                              SettlementEngine.settle_all(specs)
+                              (calls plugin.fetch_truth + is_truth_final)
+```

pmlab-0.1.0/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes are documented here. Format: [Keep a Changelog](https://keepachangelog.com/).
+
+## [0.1.0] — 2026-05-10
+
+### Added
+- `MarketPlugin` ABC — interface for domain-specific plugins
+- `PluginRegistry` — register and look up plugins by family name
+- `WeatherTmaxPlugin` — reference implementation for temperature markets
+- `SportsF1Plugin` — categorical outcome plugin for F1 race markets
+- `MarketSpec` + `OutcomeBin` — generic market descriptor
+- `Position` + `settle_position` — binary outcome PnL accounting
+- `compute_edge` — after-cost probability edge
+- `estimate_fee` + `flat_stake_size` — trade sizing utilities
+- `rolling_origin_eval` — walk-forward backtest with no-lookahead guarantee
+- `BacktestMetrics` + `compute_metrics` — PnL, hit rate, edge statistics
+- `HoldoutGateResult` — per-segment GO/NO_GO gate
+- `MarketForecaster` ABC — model protocol
+- `LGBMForecaster` — LightGBM binary/multiclass implementation
+- `IsotonicCalibrator` — probability calibration
+- `ChampionManifest` — hard-gate champion publish (raises on NO_GO)
+- `EdgeSignal` — typed scan-edge output dataclass
+- `PaperBroker` — record trades with segment gate, stale guard, dedup
+- `SettlementEngine` — settle open trades via plugin truth resolution
+- `WorkspaceContext` + `scripts/pmlab-workspace` — workspace isolation
+- `GammaClient` + `fetch_gamma_markets` — Polymarket Gamma API
+- `ClobClient` + `fetch_token_prices` — Polymarket CLOB price fetch
+- CLI: `pmlab version`, `status`, `scan-markets`, `record-trades`, `settle-trades`, `backtest`, `promote-champion`
+- GitHub Actions CI: lint (ruff) + pytest (70% coverage gate) + build
+- 123+ tests, 92%+ coverage

pmlab-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arthur Breguez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.