pqts 0.1.5

Production-oriented quant research and execution platform.

PQTS - Protheus Quant Trading System

A professional-grade algorithmic trading platform for crypto, equities, and forex markets.

🚀 Features

• Multi-Market Support: Trade crypto, stocks, and forex from one platform
• 10 Strategy Channels: Scalping, arbitrage, trend following, mean reversion, ML, volume profile, regime detection, order flow, liquidity sweeps, multi-timeframe
• Universal Indicators: Technical analysis that works across all markets
• Risk Management: Institutional-grade position sizing (Kelly criterion) and drawdown controls
• Machine Learning: Ensemble models with online learning
• Backtesting Framework: Event-driven backtesting with realistic execution
• Real-time Dashboard: Live P&L and performance metrics
• Paper Trading: Test risk-free before going live
• Telegram/Discord Alerts: Incident, kill-switch, and daily PnL notification hooks

🏆 Why PQTS

PQTS is built for operational robustness first, not just strategy scripts.

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 (crypto/equities/forex)	✅	⚠️ Primarily crypto	✅	⚠️ Primarily crypto/market-making

🖼️ 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 with:

python scripts/generate_readme_media.py

📊 Quick Start

# Clone and setup
git clone https://github.com/jakerslam/pqts.git
cd pqts

# Recommended: bootstrap local venv + dependencies
make setup
source .venv/bin/activate
# Optional strict lock install:
# make setup-lock

# Copy environment template
cp .env.example .env
# Edit .env with your API keys

# Start dashboard
python src/dashboard/start.py

# Install published package:
pip install -U pqts

# Run paper trading
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 + dashboard + Redis + Postgres):

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

Dashboard: http://localhost:8501
API metrics (observability profile): http://localhost:8000/metrics
Prometheus (observability profile): http://localhost:9090
Grafana (observability profile): http://localhost:3000 (admin / admin) Docs site (GitHub Pages): https://jakerslam.github.io/pqts/ (requires Pages enablement in repo settings) Leaderboard fallback in-repo page: docs/leaderboard/index.html Latest release: v0.1.1

🌐 Web App Dashboard (Next.js)

The authenticated web surface lives in apps/web and now includes: 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: The dashboard defaults to port 8501; ensure this is exposed appropriately in your environment
• 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.

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

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-10_reference_crypto_trend_following/
  • results/2026-03-10_reference_crypto_funding_arbitrage/
  • results/2026-03-10_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

🔔 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

🎛️ Dashboard

Launch the real-time dashboard:

python src/dashboard/start.py

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-10 19:59:10

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

Bundle	Markets	Strategy	Quality	Fill	Reject
2026-03-10_reference_crypto_funding_arbitrage	crypto	funding_arbitrage	0.8221	1.0000	0.0000
2026-03-10_reference_crypto_trend_following	crypto	trend_following	0.8336	1.0000	0.0000
2026-03-10_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
• SRS Coverage Matrix
• SRS Gap Backlog
• Development Summary
• Native Hotpath
• 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
• 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 v0.1.1) to trigger release + PyPI publish workflow.
• Release notes are generated automatically in GitHub Releases.

🛠️ 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