PQTS - Protheus Quant Trading System

A governed system for monetizing future predictions.

Canonical product message:

• Tagline: PQTS monetizes future predictions under explicit EV, risk, provenance, and promotion gates.
• Scope: Prediction markets are the primary trading surface; adjacent tradable forecasting venues use the same control plane when they satisfy the same safety and eligibility contracts.

Why This Repo Is Different

PQTS is designed as a deployment-trust operating system for forecast monetization:

• One engine, two user densities: beginner-friendly guided workflows and pro-grade drilldowns on the same object model
• Promotion gates built in: explicit backtest -> paper -> shadow -> canary -> live lifecycle
• Truth + provenance surfaces: benchmark trust labels, artifact paths, and per-order explainability
• Fast stack with measured native hotpaths: Python-first with Rust acceleration where latency matters
• Web-primary product surface: Next.js Studio + FastAPI control plane, with Dash retained as operator fallback

🚀 Features

• Web-Primary Studio: Next.js dashboard for onboarding, execution, risk, promotion, and benchmark evidence
• Canonical FastAPI Control Plane: typed /v1 contracts for account, portfolio, execution, risk, promotions, and ops diagnostics
• Order-Truth and Execution Explainability: signal -> risk gate -> router/venue -> fill outcome drilldowns
• Promotion Control Center: explicit advance/hold/rollback/halt state transitions
• Paper-First Safety Defaults: no hidden live execution path in first-success onboarding
• Benchmark Program + Trust Labels: reference vs diagnostic vs unverified artifact classification
• Operational Guardrails: kill-switches, risk controls, reconciliation workflows, and incident telemetry
• Notifications Hooks: stdout/Telegram/Discord channel validation and alert plumbing

Capability	PQTS	Freqtrade	NautilusTrader	Hummingbot
Institutional-style risk gates	✅ Native	⚠️ Partial	✅ Strong	⚠️ Partial
Reconciliation + incident telemetry	✅ Native	⚠️ Limited	⚠️ Depends on setup	⚠️ Limited
Promotion/canary controls	✅ Native	❌ No first-class flow	⚠️ Custom	❌ No first-class flow
Simulation leaderboard + reporting	✅ Native	⚠️ Backtesting focus	✅ Strong backtesting	⚠️ Bot metrics focus
Multi-market scope (prediction markets + adjacent forecast venues)	✅ (prediction-market-first, governed expansion)	⚠️ Primarily crypto	✅	⚠️ Primarily crypto/market-making

Current System State (2026-03-18)

• Requirements closure: 855/855 implemented (SRS Coverage Matrix)
• Gap backlog: 0 open at P0/P1/P2 (SRS Gap Backlog)
• Completion evidence and implementation traceability: Engineering TODO
• Public strategy and execution priorities: Top 100 ROI Moves
• Core implemented contract families now include forecast lifecycle, multilingual event intelligence, stage-bounded copy/follow, formula-policy controls, LMSR/liquidity contracts, scenario governance, value-allocation policy, and dominance/public-surface federation modules under src/.

Reference Performance Snapshot

Reference performance artifacts are auto-generated from results/reference_performance_latest.json. The current bundle-level metrics are shown in the Strategy Performance section.

🖼️ Visual Tour

Screenshots

Dashboard Overview	Simulation Leaderboard

Risk Controls	Canary Progress

Ops Health	Execution Pipeline

Architecture Layers	Performance Snapshot

GIF Previews

Dashboard Pulse	Leaderboard Cycle	Risk Alert Flash

Regenerate media assets from the primary web Studio with:

python scripts/generate_readme_media.py

📊 Quick Start

# 1) Install package
pip install -U pqts

# 2) Launch guided first-success flow
pqts quickstart --execute

# 3) Validate strategy and start bounded paper forecast-trading run
pqts backtest momentum
pqts paper start --risk-profile conservative

Source/development path:

git clone https://github.com/jakerslam/pqts.git
cd pqts
make setup
source .venv/bin/activate
cp .env.example .env

# Start canonical API control plane
python -m uvicorn services.api.app:app --host 0.0.0.0 --port 8000

# Start primary web Studio surface
cd apps/web
npm install
npm run dev

# Optional: Dash operator fallback surface
cd ..
python src/dashboard/start.py

# Run bounded paper forecast-trading loop
python main.py config/paper.yaml
# or enforce a specific user risk tolerance profile:
python main.py config/paper.yaml --risk-profile conservative
# or run AI autopilot with human strategy overrides:
python main.py config/paper.yaml \
  --autopilot-mode auto \
  --autopilot-include mean_reversion \
  --autopilot-exclude ml

🐳 Docker Compose

One-command local stack (app + API + web + Redis + Postgres):

docker compose up --build

# Cloud MVP profile (api + web + redis + postgres):
# make cloud-mvp-up

# Optional operator fallback (Dash):
# docker compose --profile operator up --build

# optional observability profile:
# docker compose --profile observability up --build
# or:
# make observability-up

Web Studio: http://localhost:3000
Dash fallback (operator profile): http://localhost:8501
API metrics (observability profile): http://localhost:8000/metrics
Prometheus (observability profile): http://localhost:9090
Grafana (observability profile): http://localhost:3001 (admin / admin) Docs site (GitHub Pages): https://jakerslam.github.io/pqts/ Leaderboard in-repo fallback page: docs/leaderboard/index.html If GitHub Pages is temporarily unavailable, the workflow publishes a docs-site-fallback artifact in Publish Docs Site runs. Latest releases: GitHub Releases

💳 Pricing & Cloud

PQTS uses an open-core model: MIT community core + managed cloud/support layers.

• Community: free, self-hosted, paper-first safety defaults
• Starter Cloud: $49/mo
• Pro Cloud: $299/mo
• Enterprise: $999+/mo or annual self-hosted contracts
• Verified strategy marketplace commission: 25%

Details and guardrails: Pricing And Packaging

🌐 Web App Dashboard (Next.js)

Primary public web surface: Next.js (apps/web). Dash remains the operator fallback during web cutover.

• Promotion Control Center (/dashboard/promotion)
• Execution Quality (/dashboard/execution-quality)
• Per-Order Truth Drilldown (/dashboard/order-truth)
• Deterministic Replay Timeline (/dashboard/replay)
• Template Gallery (/dashboard/templates)
• Notifications Channel Check (/dashboard/notifications)

Run locally:

cd apps/web
npm install
npm run dev

📋 Deployment Considerations

When deploying Protheus to production-like environments:

• Environment Variables: Always copy .env.example to .env and populate with production credentials
• Configuration Files: Start with config/paper.yaml for testing, then modify for live trading with appropriate risk limits
• Data Directories: Ensure data/ and logs/ directories have sufficient disk space and appropriate backups
• Port Configuration: Web Studio defaults to 3000, API to 8000, Dash fallback to 8501 (operator profile)
• Secret Management: Use a secrets manager (AWS Secrets Manager, Vault, etc.) rather than storing credentials in config files for production

⚡ One-Command Demo

make demo
# or:
python apps/demo.py --market crypto --strat ml-ensemble --source x_launch_thread
# optional:
# python apps/demo.py --market crypto --risk-profile aggressive

The demo runs a deterministic paper-simulation slice, emits:

• a markdown demo report in data/reports/
• a Protheus handoff blob for agent-pilot workflows
• an attribution event row in data/analytics/attribution_events.jsonl

Preset launch paths:

python apps/demo.py --preset casual --source quickstart
python apps/demo.py --preset pro --source quant_desk --track-upgrade-intent
python scripts/funnel_report.py

First-success template flows (code-visible artifacts + diffs):

pqts backtest momentum
pqts paper start

Operator UX commands (beginner + pro):

pqts doctor --fix
pqts quickstart
pqts quickstart --execute
pqts strategies list
pqts strategies explain underdog_value
pqts risk recommend --experience beginner --capital-usd 5000 --automation manual
pqts status reports
pqts status leaderboard
pqts status readiness
pqts explain block net_ev_non_positive
pqts artifacts latest --root data
pqts notify test --channel stdout

These commands now emit template artifacts and config diffs under the selected output directory:

• template_run_<timestamp>.json
• template_run_diff_<timestamp>.diff

Skill package discovery + install URL export:

pqts skills list
pqts skills urls

Nightly bounded review + tuning proposals:

python3 scripts/run_nightly_strategy_review.py --snapshot auto
# optional: write override patch
python3 scripts/run_nightly_strategy_review.py --snapshot auto --write-overrides data/reports/nightly_review/overrides.yaml
# make target
make nightly-review

The nightly review also writes standardized autonomous artifacts under data/analytics/autonomous/: memory.jsonl, trade_journal.jsonl, and judge_report.jsonl.

Ops certification + retention:

python scripts/run_exchange_certification.py --venues binance,coinbase,alpaca,oanda
python scripts/enforce_data_retention.py --root data --max-age-days 365 --max-total-files 10000

Six-month paper-trading harness (monthly slices + aggregate report):

python3 scripts/run_paper_6m_harness.py --months 6 --cycles-per-month 12 --sleep-seconds 0
# or:
make paper-6m

Artifacts are written under data/reports/paper_6m/, including one consolidated paper_6m_harness_<timestamp>.json report.

Agent-vs-standard six-month comparison harness:

python3 scripts/run_paper_6m_agent_comparison.py --months 6 --cycles-per-month 12 --sleep-seconds 0
# or:
make paper-6m-compare

Comparison artifacts are written under data/reports/paper_6m_compare/, including paper_6m_agent_vs_standard_<timestamp>.json.

Ninety-day paper-trading harness (3 monthly slices, external-beta oriented):

python3 scripts/run_paper_90d_harness.py --days 90 --cycles-per-month 12 --sleep-seconds 0
# or:
make paper-90d

Certified-paper integration gate (marketed venues + certification evidence):

make certified-paper

World-class ops checklist (all 10 steps, one command):

python scripts/run_world_class_ops.py --config config/paper.yaml --quick

Governance and contract gates (recommended before PR/release):

make governance-check

Benchmark program and monthly proof artifact generation:

make benchmark-program

Live secret validation:

python scripts/validate_live_secrets.py --config config/live_canary.yaml --strict

FastAPI SSE stream surface (authenticated):

curl -N \
  -H "Authorization: Bearer <viewer-token>" \
  "http://localhost:8000/v1/stream/sse/orders?account_id=paper-main"

Deployment run-mode entrypoint (environment-driven):

PQTS_RUN_MODE=engine python3 scripts/run_mode_entrypoint.py --print-plan
PQTS_RUN_MODE=api PQTS_API_TOKENS="viewer-token:viewer" python3 scripts/run_mode_entrypoint.py --print-plan
PQTS_RUN_MODE=stream python3 scripts/run_mode_entrypoint.py --print-plan

PnL truth ledger + strategy auto-disable list:

python scripts/pnl_truth_ledger_report.py \
  --tca-db data/tca_records.csv \
  --lookback-days 30 \
  --min-trades 50 \
  --disable-threshold-net-alpha-usd 0 \
  --strict

🧪 Simulation Suite + Telemetry

Run multi-market, multi-strategy simulation suites and emit optimization telemetry:

make sim-suite
# or:
python scripts/run_simulation_suite.py \
  --markets crypto,equities,forex \
  --strategies market_making,funding_arbitrage,cross_exchange \
  --cycles-per-scenario 60 \
  --readiness-every 20 \
  --risk-profile balanced

Artifacts:

• suite report JSON: data/reports/simulation_suite_<timestamp>.json
• optimization leaderboard CSV: data/reports/simulation_leaderboard_<timestamp>.csv
• event telemetry log: data/analytics/simulation_events.jsonl

The dashboard now renders this telemetry in a dedicated Simulation Leaderboard panel.

Static leaderboard export (for GitHub Pages):

python scripts/export_simulation_leaderboard_site.py --reports-dir data/reports --output-dir site

Or publish docs + leaderboard via GitHub Actions:

gh workflow run "Publish Docs Site"

📂 Published Results

Public reproducible result bundles live under results/.

• baseline bundle: results/2026-03-09_sim_suite_baseline/
• additional bundles:
  • results/2026-03-09_crypto_market_making_short/
  • results/2026-03-09_crypto_funding_arbitrage_short/
  • results/2026-03-09_multi_market_market_making_short/
  • results/2026-03-09_baseline/ (historical)
  • results/2026-03-12_reference_crypto_trend_following/
  • results/2026-03-12_reference_crypto_funding_arbitrage/
  • results/2026-03-12_reference_multi_market_making/
  • results/2026-03-13_reference_crypto_trend_following/
  • results/2026-03-13_reference_crypto_funding_arbitrage/
  • results/2026-03-13_reference_multi_market_making/
• bundle schema/template: results/RESULT_TEMPLATE.md
• generated latest-reference summary: results/reference_performance_latest.json

Each bundle includes the command, inputs, key metrics, and chart artifacts.

Regenerate published reference bundles and sync README/docs callouts:

make reference-bundles

Trust + provenance program:

• Weekly benchmark automation: .github/workflows/benchmark-program.yml
• Latest benchmark matrix report: data/reports/benchmark_program/latest.json
• Monthly benchmark reports: data/reports/monthly/<YYYY-MM>/
• Certified-paper integration report: data/reports/certifications/latest.json
• External beta framework contract: docs/EXTERNAL_BETA_FRAMEWORK.md

Release readiness gate (blocks publish when beta/certification/provenance truth fails):

make release-readiness

🔔 Notifications (Telegram/Discord)

Incident automation can dispatch notifications directly:

python scripts/run_incident_automation.py \
  --discord-webhook-url "$PQTS_DISCORD_WEBHOOK_URL" \
  --telegram-bot-token "$PQTS_TELEGRAM_BOT_TOKEN" \
  --telegram-chat-id "$PQTS_TELEGRAM_CHAT_ID"

For direct/manual alerts:

python scripts/send_ops_notification.py --mode raw --message "PQTS heartbeat"

Execution drift report:

python scripts/execution_drift_report.py --tca-db data/tca_records.csv --lookback-days 30

Shadow parity + operational SLO flow:

# 1) Collect market/order/fill parity telemetry
python scripts/run_shadow_stream_worker.py --cycles 30 --sleep-seconds 1.0

# 2) Reconcile internal vs venue state (auto-halt on mismatch)
python scripts/run_reconciliation_daemon.py --cycles 12 --sleep-seconds 5.0 --halt-on-mismatch

# 3) Evaluate SLO health + route alerts
python scripts/slo_health_report.py

# 4) Weekly error-budget review
python scripts/weekly_error_budget_review.py --window-days 7

Additional artifacts:

• data/analytics/shadow_stream_events.jsonl
• data/analytics/stream_health.json
• data/analytics/reconciliation_incidents.jsonl
• data/alerts/slo_alerts.jsonl
• data/reports/slo_health_<timestamp>.json
• data/reports/error_budget_review_<timestamp>.json

Execution truth + promotion + canary ramp flow:

# 1) websocket market/order/fill ingestion
python scripts/run_ws_ingestion.py --cycles 30 --sleep-seconds 1.0

# 2) strategy tournament from partitioned data lake
python scripts/run_strategy_tournament.py \
  --start 2026-01-01T00:00:00Z \
  --end 2026-02-01T00:00:00Z \
  --sources binance:BTCUSDT,binance:ETHUSDT \
  --strategy-types market_making,funding_arbitrage

# 3) policy-driven canary allocation step (advance/hold/rollback/halt)
python scripts/run_canary_ramp.py

# 4) B2B control-plane usage + pricing readout
python scripts/control_plane_report.py

🎛️ Studio Surface

Launch the primary web Studio:

cd apps/web
npm install
npm run dev

Access at http://localhost:3000

Operator fallback (Dash):

python src/dashboard/start.py

Fallback access at http://localhost:8501

📈 Strategy Performance

Reference callout from latest reference bundle (auto-generated from results/reference_performance_latest.json):

Last generated (UTC): 2026-03-13 02:34:47

• 2026-03-13_reference_crypto_trend_following (bundle, csv, report)
  • avg_quality_score=0.8535
  • avg_fill_rate=1.0000
  • avg_reject_rate=0.0000
  • total_filled=36 / total_submitted=36

Bundle	Markets	Strategy	Quality	Fill	Reject
2026-03-13_reference_crypto_funding_arbitrage	crypto	funding_arbitrage	0.8199	1.0000	0.0000
2026-03-13_reference_crypto_trend_following	crypto	trend_following	0.8535	1.0000	0.0000
2026-03-13_reference_multi_market_making	crypto,equities,forex	market_making	0.8246	1.0000	0.0000

Strategy	Timeframe	Edge
Scalping	1m, 5m	Microstructure, order flow
Arbitrage	Real-time	Cross-exchange, funding rates
Trend Following	1h, 4h	Momentum + multi-timeframe
Mean Reversion	15m, 1h	RSI, Bollinger, Volume Profile
ML Ensemble	Variable	Random Forest, XGBoost, LSTM
Volume Profile	1h, 4h	POC, Value Area, HVN
Order Flow	Tick	Delta, whale detection
Liquidity Sweep	15m, 1h	Stop hunts, false breakouts

🧠 Architecture

PQTS now uses a canonical modular monolith layout:

• src/app/: composition root and runtime entrypoints
• src/contracts/: module and event contracts
• src/modules/: module descriptors and lifecycle hooks
• src/adapters/: external I/O adapter descriptors/loaders

Legacy packages (src/core/, src/execution/, src/analytics/, src/risk/, src/strategies/, etc.) remain active during migration and are wired through src/app/.

Performance-critical execution math is offloaded to Rust hotpaths (native/hotpath) with Python fallback for portability. Live canary defaults to runtime.performance.profile=low_latency and can enforce runtime.performance.require_native_hotpath=true so low-latency deployments fail fast if native kernels are missing. Build and verify with:

make native
make bench-exec

Latest benchmark artifacts are published in results/native_benchmarks/:

• Python fallback run: p95 submit latency 40.02ms
• Native hotpath run: p95 submit latency 14.15ms

Architecture tooling:

python tools/check_architecture_boundaries.py
python tools/print_architecture_map.py
python tools/scaffold_module.py order_intelligence --requires data,signals --provides flow_signals

Detailed rules and migration notes: docs/ARCHITECTURE.md

Repository layout guide: docs/REPO_STRUCTURE.md

📚 Documentation

• Architecture
• Repository Structure
• Codex Compliance
• Implementation Direction
• SRS
• Two-Week RYG Plan
• SRS Coverage Matrix
• SRS Gap Backlog
• Top 100 ROI Moves
• Development Summary
• Native Hotpath
• Agent Pilot API + SDK
• Live Money Roadmap
• System Overview
• World-Class Execution Pack
• Backtesting Guide
• Simulation Telemetry
• World-Class 30/60/90 Plan
• World-Class Next Steps Execution
• Max Utility + Revenue Playbook
• Strategy Patterns
• Incident Runbook
• Pricing And Packaging
• GTM 90-Day Plan
• Self-Serve Signup Spec
• Protheus Toybox Launch
• X Thread Template
• Engineering TODO
• Humans-Only Work
• 5-Minute Quickstart
• Architecture Diagram
• Benchmarks
• Reference Performance
• External Beta Framework
• Release Checklist
• Branch Protection Guidance
• PyPI Publishing Setup
• GitHub Pages Setup
• Reproducible Results Bundle Guide

🤝 Project Governance

• Contributing Guide
• Code of Conduct
• Security Policy
• Support
• Changelog
• Citation

📦 Releases

• Create a semantic version tag (for example vX.Y.Z) to trigger release + PyPI publish workflow.
• Release notes are generated automatically in GitHub Releases.

🎯 ROI Execution

• Generate the ranked Top-100 execution slice from current TODO metadata:
  • make top100-roi
• CI enforces freshness for:
  • docs/TOP_100_ROI_MOVES.md
  • docs/TOP_100_ROI_MOVES.json

🛠️ Configuration

Paper Trading

mode: paper_trading
markets:
  crypto:
    enabled: true
    exchanges:
      - name: binance
        api_key: ${BINANCE_TESTNET_API_KEY}
        api_secret: ${BINANCE_TESTNET_API_SECRET}
        testnet: true

Live Trading

mode: live
markets:
  crypto:
    enabled: true
    exchanges:
      - name: binance
        testnet: false
        api_key: ${BINANCE_API_KEY}
        api_secret: ${BINANCE_API_SECRET}
execution:
  require_live_client_order_id: true
  idempotency_ttl_seconds: 300.0
  strategy_disable_list_path: data/analytics/strategy_disable_list.json
  allocation_controls:
    enabled: true
    default_max_strategy_allocation_pct: 0.25
    default_max_venue_allocation_pct: 0.50
  rate_limits:
    binance:
      order_create:
        limit: 10
        window_seconds: 1.0
      order_cancel:
        limit: 10
        window_seconds: 1.0
      market_ticker:
        limit: 50
        window_seconds: 1.0

⚠️ Risk Disclaimer

Trading involves substantial risk. Past performance doesn't guarantee future results. Always start with paper trading. Any Sharpe/return claim should come from reproducible backtest or paper/live reports.

📄 License

MIT (see LICENSE)

---

Built by Protheus