quant-hq-operations-console
暂无简介
- License 许可
- Apache-2.0
- 最近更新
- 2026-10-24
- Stars
- ★ 0
- Forks
- 0
02 资源文件 1
- 参考文档skill.json373 B
03 SKILL.md 正文
quant-hq-operations-console
Quant Lab HQ Operations Console
Cinematic command-center for monitoring a 12-room / 24-agent quantitative research organization. All visual state comes from real PostgreSQL data via SSE — never simulated.
Architecture
Backend (CT106, /opt/cortexquant)
| File | Purpose |
|---|---|
src/quant_hq/rooms_schema.py |
SQLAlchemy models: ResearchAgent, ResearchMessage, ResearchExperiment, ResearchAuditLog, ResearchTask, ResearchPromotion, RoomType, PipelineStage |
src/quant_hq/rooms.py |
Room classes, ChiefQuantDirector, MessageBus, MemoryStore, QuantHQOrchestrator singleton |
src/quant_hq/events.py |
SSE router with _get_full_state() |
src/quant_hq/orchestrator.py |
Orchestration helpers |
src/quant_hq/schema.py |
Canonical enums (ResearchStage, AgentRole, TaskStatus) |
src/quant_hq/alpha_pipeline.py |
12-step alpha extraction: demeaning, variance, normalization, truncation, cross-sectional demean, expected return, orthogonalization, weighting, combination |
src/quant_hq/monitor.py |
DecayDetector (rolling Sharpe + sustained-period flagging), HMRegimeDetector (2-state Gaussian HMM + forward algorithm), PermissionGraph (room write/read permissions), MonitoringService (orchestration + feedback loop) |
src/ingestion/tg_schema.py |
Raw message storage, parsed signal storage, backfill checkpoints, metrics |
src/ingestion/tg_parser.py |
v2.0.0 — parses CKPscanner Scout Opportunity lists (symbol, direction, RSI15/4H, TSI15/4H, divergence, funding) |
src/ingestion/tg_service.py |
Telethon MTProto ingester with pagination + real-time listener |
src/ingestion/tg_publisher.py |
Routes parsed signals → creates ALTCOIN_SIGNAL_RECEIVED events → MessageBus → 10 rooms |
src/api/tg_routes.py |
Telegram ingestion endpoints (health, signals, stats, reparse) |
src/api/monitoring_routes.py |
Monitoring endpoints (decay, regime, DSR, permissions) |
src/api/alpha_routes.py |
12-step validation and combination endpoints |
main.py |
Entry point; starts scheduler, ingester, publisher, API |
Frontend (/console)
- Canvas facility map: Chief Quant Director center, 12 rooms in a circle
- Agent dots on rings inside each room
- Data packets animate along conduits when messages flow
- SSE-driven: no polling, no fake animation
12-Step Alpha Extraction Pipeline
Every signal must pass through all 12 steps before any further action. From the RuujSs "Unified Framework for Alpha Extraction and Signal Combination":
| Step | Math | What |
|---|---|---|
| 1 | X = R - mean(R) |
Linear demeaning (drift removal) |
| 2 | σ² = mean(X²) |
Variance estimation |
| 3 | Y = X / σ |
Return normalization (unit variance) |
| 4 | Y[:M-1] |
Time-series truncation |
| 5 | Λ = Y - mean(Y across N) |
Cross-sectional demeaning |
| 6 | Λ[:M-1] |
Final trimming |
| 7 | E = mean(R[-d:]) |
Expected return (forward-looking) |
| 8 | E_norm = E / σ |
Return normalization |
| 9 | E_norm = β·Λ + ε |
Residual extraction (orthogonalize) |
| 10 | w = ε / σ |
Signal weighting (inverse vol) |
| 11 | Σ|w| = 1 |
Weight normalization (gross exposure = 1) |
| 12 | Combined = Σ w(i)·S_i |
Combined signal |
Validation runs in AlphaExtractionPipeline.validate_signal() → returns (passed, results, output). Combine N signals via combine_signals().
Monitoring System
DecayDetector
Rolling Sharpe with sustained-period flagging. A single bad window is variance. N consecutive bad windows is a signal. From the RuujSs alpha engine article:
class DecayDetector:
def __init__(self, window_size=20, sustained_periods=3, decay_threshold=0.5):
...
def check_decay(self, research_id, live_returns) -> Tuple[bool, Dict]:
...
HMRegimeDetector
Two-state Gaussian HMM with forward algorithm for regime probability. Secondary correlation check catches what the model alone misses.
class HMRegimeDetector:
def __init__(self, n_states=2): ...
def fit(self, returns) -> bool: ...
def predict(self, returns) -> Dict: ... # {fitted, regime, confidence, divergence}
PermissionGraph
Enforces room-to-room write/read permissions at the data level. Maps each room to the set of statuses it can write and read.
class PermissionGraph:
WRITE_PERMISSIONS = {RoomType.QUANT_RESEARCH: {"CANDIDATE"}, ...}
READ_PERMISSIONS = {RoomType.QUANT_RESEARCH: {"CANDIDATE", "APPROVED", "FLAGGED"}, ...}
def can_write(self, room, status) -> bool: ...
def can_read(self, room, status) -> bool: ...
MonitoringService
Orchestrates decay + HMM + feedback. When decay or regime divergence is detected, sends HIGH priority messages to the research room.
class MonitoringService:
async def check_experiment(self, research_id, returns, baseline_sharpe) -> Dict: ...
async def _alert(self, research_id, alert_type, data): ...
Deflated Sharpe Ratio
Multiple-testing correction for strategy validation. Converts Sharpe into a probability that the strategy is not overfit.
def deflated_sharpe_ratio(sharpe, n_observations, skew=0.0, kurtosis=3.0, n_trials=1, alpha=0.05) -> Dict:
# Returns {dsr, probability, pass, expected_max_sr, threshold, n_trials}
Uses scipy.stats.norm (Bailey & Lopez de Prado expected max SR under null).
SSE Protocol
/api/quant-hq/events emits named SSE events:
state— full state snapshotaudit_log— incremental new audit eventsheartbeat— timestamp ping
Client uses addEventListener for named events. onmessage does NOT fire for named SSE events.
Common pitfalls
- Agent duplication on restart:
initialize()callsregister_agent()unconditionally — add a guard to check for existing agent before insert. - PSQL table name mismatch: model
__tablename__may be singular (research_audit_log) while raw psql uses plural. - Port bind failure on restart:
fuser -k 8080/tcpBEFORE restarting, or get[Errno 98] address already in use. - Shell quoting kills JSON: nested ssh/pct/bash -c with curl -d JSON mangles. Write to file, use
curl --data-binary @file. - State endpoint wrapper:
/api/quant-hq/statereturns{state: {...}}— console accessesdata.state. - Room initialization is lazy: only 5 of 12 rooms registered in
initialize(). Add missing room classes + init calls + agent registrations. - AsyncSessionLocal: always use async with context manager.
scipymust be in the venv, not system.pip install scipyinside the CT106 venv (/opt/cortexquant/venv), not the host. System pip won't put it where the FastAPI app can import it.python-multipartfor FastAPI POST bodies. FastAPI requires it for form data / JSON body parsing.pip install python-multipartin the venv.numpy.bool_is not JSON-serializable. Always wrap inbool()when returning from an API endpoint (e.g."pass": bool(probability >= threshold)).- Stale
__pycache__. Alwaysfind /opt/cortexquant -name __pycache__ -exec rm -rf {} +after patching.pyfiles, then restart. .envvspydantic-settings.settings.TELEGRAM_API_IDreads.envbutos.environ.get("TELEGRAM_API_ID")returns None until you manually load.env(e.g. for the Telethon ingester constructor).- Telegram session lock. Kill the running server BEFORE running auth interactively, or get
sqlite3.OperationalError: database is locked. - Auth codes expire in ~30s. Run auth directly on the server (not via background polls) and type code immediately.
- uvicorn
serve()blocks forever — background tasks must precede it. Any async work that must run for the lifetime of the server (e.g. a 7-day demo trading orchestrator, background reconcilers, cron-like jobs) must be started withasyncio.create_task(...)BEFOREawait server.serve(). Code afterserve()never executes. - Parser variable-name typo in success branch —
for p in parsed:instead offor p in parsed_results:silently breaks the main parse path. When patching parser loops, re-read the surrounding 5 lines after every edit to catch a wrong variable name — a NameError in the success branch is silent when the function returns early onNone. - Scout message regex must handle leading whitespace — CKPscanner emits lines like
1. ALCH-USDT | ...(2 spaces before number). A patternr"(\d+)\.\s+"matches zero lines. Always include\s*before numeric tokens in signal-line regexes. - MAX_POSITION_SIZE_PCT caps risk target —
position_size = (capital * risk_pct) / |entry - sl|is thenmin(position_size, max_pos). IfMAX_POSITION_SIZE_PCTis too tight (e.g. 5%), the position cap binds and actual risk falls well belowPER_TRADE_RISK_PCT. Set cap high enough (e.g. 50%) that it doesn't bind for realistic stops. - ML model can have negative R² — a trained GradientBoosting/RandomForest on financial OHLCV can score R² < 0 (worse than predicting the mean). The validation gate must check
val_r2 > 0before enabling trades; a saved model file is not proof of predictive power. - Fresh CKPscanner signals arrive in batches — one Scout message contains 20+ symbols, all with identical timestamps. Deduplicate by symbol (keep highest-confidence) and process as a single signal batch, not 20+ independent trades.
- CT services have no systemd/supervisorctl — CT106 runs processes via a custom launcher (
main.py). After code changes, the reliable restart isfuser -k 8080/tcp && PYTHONPATH=/opt/cortexquant nohup python main.py > /tmp/cq.log 2>&1 & disown, notsystemctl restart.
Dependencies (CT106 venv)
source /opt/cortexquant/venv/bin/activate
pip install numpy scipy scikit-learn hmmlearn telethon python-multipart pytest-asyncio
scipy— fordeflated_sharpe_ratio(norm.ppf, norm.cdf)scikit-learn— forhmmlearndependencyhmmlearn— Gaussian HMM for regime detectiontelethon— MTProto user-client for Telegrampython-multipart— FastAPI POST body parsingpytest-asyncio— async test support (v0.23.8 works best; v1.4.0 has mode=STRICT issues)
Regression tests
tests/test_quant_hq_agents.py — 6 tests. Run:
PYTHONPATH=/opt/cortexquant python3 tests/test_quant_hq_agents.py
Or: bash scripts/regression_test.sh
tests/test_tg.py — 9 parser tests + storage tests:
cd /opt/cortexquant && source venv/bin/activate && PYTHONPATH=/opt/cortexquant python3 -m pytest tests/test_tg.py -v
tests/pyproject.toml:
[tool.pytest.ini_options]
asyncio_mode = "auto"
Deployment (CT106 in LXC)
# Kill old process + free port
ssh pve 'pct exec 106 -- bash -c "fuser -k 8080/tcp 2>/dev/null; sleep 2"'
# Clear stale bytecode
ssh pve 'pct exec 106 -- bash -c "find /opt/cortexquant -name __pycache__ -exec rm -rf {} + 2>/dev/null"'
# Restart
ssh pve 'pct exec 106 -- bash -c "cd /opt/cortexquant && source venv/bin/activate && PYTHONPATH=/opt/cortexquant nohup python main.py > /tmp/cq.log 2>&1 & disown"'
# Verify
ssh pve 'pct exec 106 -- bash -c "sleep 4; curl -s http://localhost:8080/health"'
ssh pve 'pct exec 106 -- bash -c "curl -s http://localhost:8080/openapi.json | python3 -c \"import sys,json; d=json.load(sys.stdin); print(len(d[\\\"paths\\\"].keys()), \\\"endpoints\\\"}\""'
LIVE_TRADING=false always — research agents isolated from execution.
SSE protocol details (named events, client-side handling): see references/sse-protocol.md