oddsgraph

Build prediction market logical knowledge graphs.

oddsgraph is a local, open-source Logical Knowledge Graph Compiler for prediction markets. It converts Polymarket WC2026 hourly-odds parquet into a logical knowledge graph of competitions, teams, stages, matches, markets, outcomes, and relationships.

Pipeline

Polymarket parquet
    → semantic market records
    → deterministic topology (match/group/stage templates)
    → official WC2026 bracket (curated FIFA schedule)
    → local structured LLM extraction (residual events only)
    → entity resolution
    → graph validation
    → nodes.parquet + edges.parquet

Performance note: Local LLM inference (infer) dominates end-to-end wall-clock time. By default, oddsgraph extracts TEAM/MATCH/GROUP/STAGE topology deterministically from structured Polymarket fields for the vast majority of events (~91% on WC2026 data), and only sends unrecognized/ambiguous events through the LLM. See Deterministic topology and Inference backends.

Source data

Place the Pipeline golden mart export at the repository root or under data/:

• polymarket_wc2026_market_hourly_odds_<timestamp>.parquet
• polymarket_wc2026_market_hourly_odds_<timestamp>.schema.json

Grain: one row per (market_id, odds_hour_epoch) with primary-outcome hourly OHLC and market/event metadata. Full contract: Source data schema.

Setup

uv sync --frozen --extra dev

uv.lock is committed for reproducible installs. CI uses the same lockfile and installs a prebuilt CPU wheel for llama-cpp-python (PyPI only ships an sdist).

On Apple Silicon, install llama-cpp-python with Metal support:

CMAKE_ARGS="-DGGML_METAL=on" uv sync --frozen --extra dev

On Linux / CPU-only machines, see Linux / CPU-only setup.

Download the local model (see models/README.md).

Documentation

Public docs: https://graph.oddsfox.io/

Local preview:

uv sync --extra docs
uv run mkdocs serve -a 127.0.0.1:8000

Start from docs/getting-started/index.md.

CLI

oddsgraph reduce          # reduce parquet to semantic markets
oddsgraph infer           # infer graph fragments per event
oddsgraph build           # resolve, validate, export graph
oddsgraph validate        # validate exported artifacts
oddsgraph odds-history    # hourly match + stage probability time-series exports
oddsgraph run             # full pipeline

Full flag reference: CLI. Stage walkthrough: Running the pipeline. Settings defaults: Configuration.

Key topics covered in the docs site:

• Deterministic topology — template extraction (~91% of WC2026 events) and optional --verify-deterministic
• Official bracket — curated FIFA schedule injection on build
• Logical layer — propositions, structural logical edges, WC2026 rules, and on-demand IMPLIES closure
• Inference backends — inprocess / server / mlx, outlines constrained decoding, benchmarks
• llama-server — concurrent residual inference
• Fine-tuning — experimental LoRA scripts
• Glossary — few-shot exemplars, resume, confidence, and related terms

Output artifacts

build/semantic_markets.parquet
build/fragments/<event_id>.json
build/nodes.parquet
build/edges.parquet
build/odds_history.parquet
build/stage_odds_history.parquet
build/rejected_edges.parquet
build/inference_report.json
build/ontology.json

Column contracts: Output artifacts.

Stack

• duckdb — query and reduce parquet
• httpx — optional llama-server HTTP client
• llama-cpp-python — local Metal-accelerated inference
• outlines — FSM constrained decoding for structured JSON
• mlx-lm — optional Apple Silicon backend (--extra mlx)
• Qwen3-4B-Q4_K_M — initial local GGUF model
• pydantic — constrained graph output schema
• rapidfuzz — entity, alias, and few-shot exemplar matching
• rustworkx — graph construction and validation
• typer — CLI
• pytest — tests

Testing

uv run pytest

Live model integration tests (optional):

ODDSGRAPH_LIVE_MODEL_TEST=1 uv run pytest -m integration

Live server integration tests (optional, requires running llama-server):

ODDSGRAPH_LIVE_SERVER_TEST=1 uv run pytest -m integration

Live MLX integration tests (optional, Apple Silicon + converted MLX model):

ODDSGRAPH_LIVE_MLX_TEST=1 uv run pytest -m integration -k mlx