gordon-lab

Purpose

gordon-lab is the Python research lab for strategy discovery, walk-forward validation, ablation, and ML experiments. It is not a deployed service — it runs no production container, holds no exchange keys, and places no orders. Its sole role is to find and validate edge; the v7 runtime (gordon-bot + gordon-executor) executes it. The lab connects to Postgres via the gordon_lab_reader role, which has INSERT/UPDATE/DELETE revoked at the DB layer on both market_data.* and trading.*. Any accidental write path fails with psycopg.errors.InsufficientPrivilege — intentional and unrevertable by the application.

Version

Field	Value
Version	0.1.0
Port	None — not a service
DB role	gordon_lab_reader (read-only)

CLI

Entry point: python -m gordon_lab

Usage: python -m gordon_lab [OPTIONS] COMMAND [ARGS]...

  Gordon Lab — Read-only research CLI for the Gordon trading system.

Options:
  --db TEXT  Database URL override (default: $GORDON_DATABASE_URL).

Commands:
  validate           Data quality report for a symbol
  info               Row counts and ranges for all stored market data
  fracdiff-scan      Scan fractional differentiation parameters
  fit-regime         Fit HMM regime model to a symbol
  analyze-regime     Analyse regime candidates vs fitted regimes
  train-meta-labeler Train CPCV meta-labeler model
  export-onnx        Export trained model to ONNX format

Example:

python -m gordon_lab validate --symbol BTCUSDT
python -m gordon_lab info
python -m gordon_lab fit-regime --symbol BTCUSDT --n-states 3

Database access

Action	Detail
Reader	market_data.* and trading.* — read-only
Writer	None — INSERT/UPDATE/DELETE revoked at DB layer (migration 0016)
Connection	GORDON_LAB_DATABASE_URL must use gordon_lab_reader role

Market data is provisioned by gordon-data (sole writer). The lab never seeds, ingests, or backfills — those operations moved to gordon-data at story 06.

Prometheus metrics

None. gordon-lab is not a deployed service and exposes no metrics.

Key env vars

Variable	Purpose
GORDON_LAB_DATABASE_URL	Read-only Postgres DSN; must use gordon_lab_reader role

Invariants

• Read-only on the database. gordon_lab_reader role has writes revoked DB-side. Do not weaken.
• Not a runtime service. Does not run in production, does not hold exchange keys, does not serve APIs.
• Not the backtest engine. Backtests run in gordon-manager via the shared ExecutionModel trait. Do not reimplement execution logic in Python.
• Not the indicator library. Production indicators and strategies live in gordon-strategy (Rust). Python indicators here are exploratory only.
• Multi-asset + walk-forward mandatory. No single-asset, no random-split results. Every candidate validated on BTC/ETH/SOL minimum across expanding windows.
• Net-of-fees always. Results without the cost model applied are invalid.
• Promotion pipeline: Level 1 (Sharpe > 0.5, walk-forward consistency > 50%) → Level 2 (max DD < 30%, positive CAGR with full cost model) → port conclusions to Rust in gordon-strategy → testnet paper trade (30+ trades) → micro live → full allocation.

Status

Phase 2 complete (2026-04-15). Backend close-out audit pass 1 done (2026-04-22). Not a migration target — no phase in flight. Planned future evolution: lab becomes a REST consumer of gordon-data (removing Postgres as a cross-service coupling point), deferred until post-v7 cutover.

Related

• gordon-data — sole writer of market data the lab reads
• gordon-strategy — target for validated research (Rust strategies)
• gordon-manager — runs backtests via ExecutionModel trait