From 26aab5b32af6d412e6757b0f2af5ce39330af255 Mon Sep 17 00:00:00 2001 From: Nick Carter Date: Thu, 24 Sep 2026 09:01:27 +0000 Subject: [PATCH 1/2] docs: make README describe the shipped library and runnable commands --- README.md | 129 +++++++++++++++++++++--------------------------------- 1 file changed, 50 insertions(+), 79 deletions(-) diff --git a/README.md b/README.md index b7fa626..137ccd9 100644 --- a/README.md +++ b/README.md @@ -1,101 +1,74 @@ # Verdict Edge — Edge Mining Framework -> Lightweight, low-latency mathematical engine for prediction market alpha pipelines. Enables algorithmic traders and quant researchers to decouple data ingestion from execution logic, running live features against compound logical filters evaluating profitability under friction constraints. The framework strictly gates deployment to maximize Expected Value (EV). +> A small library for prediction-market signals. It evaluates compound feature rules, then approves a trade only if the expected value remains positive after exchange fees. It also reports a Kelly-sized position. The package is `verdict-edge`; the import is `edge_mining_framework`. --- -## Architecture & Execution Flow +## What ships today + +A small, dependency-light library (`numpy` only) with two stages and a receipt helper: ``` -┌─────────────────────────────────────────────────────────────────────────────┐ -│ VERDICT EDGE │ -├─────────────────────────────────────────────────────────────────────────────┤ -│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌────────────┐ │ -│ │ Ingestion │───▶│ Feature │───▶│ Filter │───▶│ Execution │ │ -│ │ (Feeds) │ │ Engineering │ │ Pipeline │ │ Gateway │ │ -│ └──────────────┘ └──────────────┘ └──────────────┘ └────────────┘ │ -│ │ │ │ -│ ▼ ▼ │ -│ ┌──────────────┐ ┌──────────────┐ │ -│ │ Validators │ │ Risk Gates │ │ -│ │ (Schema, │ │ (verdict- │ │ -│ │ Bounds) │ │ risk) │ │ -│ └──────────────┘ └──────────────┘ │ -└─────────────────────────────────────────────────────────────────────────────┘ +features (dict) ──▶ FeatureEvaluator.evaluate_compound(rules) ──▶ ExpectedValueGate ──▶ trade / no trade + │ + build_strategy_receipt (Verdict provider receipt) ``` -### Core Principles - -1. **Separation of concerns** — Ingestion, feature engineering, filtering, execution are independent stages -2. **Deterministic evaluation** — Same inputs → same outputs, always -3. **Friction-aware** — Every filter accounts for fees, spread, slippage -4. **Composable** — Pluggable validators, filters, risk gates, fee models +| Component | What it does | Source | +|-----------|--------------|--------| +| `FeatureEvaluator` | AND-only compound rules with fail-fast short-circuit. Scalar operators `== != > < >= <= in_range in_set`; series operators `crosses_above crosses_below zscore rolling_corr rank`. No `eval()`. | `src/edge_mining_framework/evaluator.py` | +| `ExpectedValueGate` | Fee-aware expected value per contract, Kelly fraction, and recommended size for binary prediction-market contracts. | `src/edge_mining_framework/gate.py` | +| `build_strategy_receipt` / `canonical_hash` | Builds a Verdict provider receipt (ADR-021 shape). Conformance against `verdict-core` is tested in `tests/test_core_conformance.py`. | `src/edge_mining_framework/provider_receipts.py` | ---- +The evaluator is data-source agnostic. It does not ingest market feeds, place orders, or +call exchange APIs; those belong to the caller. Risk limits live in +[`verdict-risk`](https://github.com/mrnicholasbcarter-code/verdict-risk), and Monte Carlo +validation lives in [`verdict-backtest`](https://github.com/mrnicholasbcarter-code/verdict-backtest). -## Features +### Principles -| Feature | Description | -|---------|-------------| -| **Feature Pipeline** | Composable transforms: rolling stats, regime detection, microstructure | -| **Filter Pipeline** | Logical AND/OR/NOT chains with short-circuit evaluation | -| **Fee Models** | Kalshi bounded-profit, Polymarket maker-taker, custom | -| **Risk Integration** | Native `verdict-risk` gate evaluation | -| **Backtest Native** | Direct `verdict-backtest` tearsheet generation | -| **Telemetry** | OpenTelemetry spans for every stage | +1. **Deterministic**: the same inputs give the same outputs. +2. **Friction-aware**: the EV gate subtracts the exchange fee before it approves a trade. +3. **Agnostic**: rules evaluate plain dictionaries. There are no exchange SDK imports. --- -## Quick Start +## Quick start -```bash -# Install -pipx install verdict-edge +The package is not published to PyPI. Install from source: -# Run edge mining -verdict-edge mine --config config/alpha_pipeline.yaml --backtest +```bash +git clone https://github.com/mrnicholasbcarter-code/verdict-strategy.git +cd verdict-strategy +uv sync --extra dev +uv run python examples/gate_kalshi.py # EV gate rejects / accepts two trades +uv run python examples/run_evaluator.py # rules from examples/rules.yaml through both stages +uv run pytest -q ``` -## Configuration - -```yaml -# config/alpha_pipeline.yaml -ingestion: - sources: - - type: "polymarket" - markets: ["BTC-USD", "ETH-USD"] - ws_url: "wss://clob.polymarket.com" - -features: - - name: "spread_bps" - transform: "bid_ask_spread_bps" - - name: "volume_imbalance" - transform: "orderbook_volume_imbalance" - window: 100 - -filters: - - name: "min_edge_bps" - type: "threshold" - field: "expected_edge_bps" - operator: ">=" - value: 15 - - name: "liquidity_floor" - type: "threshold" - field: "bid_depth_usd" - operator: ">=" - value: 50000 - -risk: - verdict_risk_config: "~/.verdict/risk_config.yaml" - max_position_usd: 10000 - max_drawdown_pct: 0.05 - -execution: - gateway: "verdict_core" - retry_policy: "exponential" - timeout_ms: 500 +```python +from edge_mining_framework import ExpectedValueGate, FeatureEvaluator + +features = {"rsi": 28.0, "vol_expansion": True} +rules = [ + {"feature": "rsi", "operator": "<", "threshold": 30}, + {"feature": "vol_expansion", "operator": "==", "threshold": True}, +] + +if FeatureEvaluator.evaluate_compound(features, rules): + metrics = ExpectedValueGate.calculate_ev_metrics( + predicted_win_prob=0.57, + current_contract_price_cents=48, + payout_cents=100, + exchange_fee_pct=0.04, + bankroll=500.0, + ) + print(metrics.profitable, round(metrics.expected_value, 2), round(metrics.kelly_fraction, 4)) ``` +`examples/rules.yaml` shows the rule format, including series operators. +`examples/backtest_adapter.py` shows the optional hand-off to an installed `verdict-backtest`. + --- ## Links @@ -103,8 +76,6 @@ execution: - **Verdict Core**: https://github.com/verdict/verdict-core - **Verdict Risk**: https://github.com/verdict/verdict-risk - **Verdict Backtest**: https://github.com/verdict/verdict-backtest -- **RuVector**: https://github.com/ruvnet/ruvector -- **Ruflo**: https://github.com/ruvnet/claude-flow --- From a7e3559d99ca07fe87147eb733bf5e3ac7648c05 Mon Sep 17 00:00:00 2001 From: Nick Carter Date: Thu, 24 Sep 2026 09:09:44 +0000 Subject: [PATCH 2/2] docs: point repository and package links at the real GitHub owner --- README.md | 6 +++--- pyproject.toml | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 137ccd9..bdb7540 100644 --- a/README.md +++ b/README.md @@ -73,9 +73,9 @@ if FeatureEvaluator.evaluate_compound(features, rules): ## Links -- **Verdict Core**: https://github.com/verdict/verdict-core -- **Verdict Risk**: https://github.com/verdict/verdict-risk -- **Verdict Backtest**: https://github.com/verdict/verdict-backtest +- **Verdict Core**: https://github.com/mrnicholasbcarter-code/verdict-core +- **Verdict Risk**: https://github.com/mrnicholasbcarter-code/verdict-risk +- **Verdict Backtest**: https://github.com/mrnicholasbcarter-code/verdict-backtest --- diff --git a/pyproject.toml b/pyproject.toml index 2fe07ec..d8a31ef 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -40,9 +40,9 @@ dev = [ release = ["build>=1.2", "twine>=5.0"] [project.urls] -Homepage = "https://github.com/verdict/verdict-edge" -Repository = "https://github.com/verdict/verdict-edge" -Issues = "https://github.com/verdict/verdict-edge/issues" +Homepage = "https://github.com/mrnicholasbcarter-code/verdict-strategy" +Repository = "https://github.com/mrnicholasbcarter-code/verdict-strategy" +Issues = "https://github.com/mrnicholasbcarter-code/verdict-strategy/issues" [tool.ruff] line-length = 100