Centaur Quant Architecture

Hybrid quantitative trading system for MetaTrader 5 — a deterministic Smart Money Concepts (SMC) executor paired with a probabilistic LLM analyst. The AI advises; it never vetoes execution.

Status: v2.0.0 — production-ready release · License: MIT · Docs: 00_CONCEPT/

---

1. Overview & Architecture (The Centaur)

A centaur is half deterministic, half probabilistic — exactly like this system.

Agent	Layer	Role
Executor (deterministic)	MQL5/	Symbol normalization, strict OB+FVG scanning, anti-veto sizing, dynamic trade management, SDP telemetry
Router / Gateway	Python/router/	Persistent TCP bridge: SDP framing, AI advisory dispatch, telemetry wiring
Probability Analyst (probabilistic)	Python/models/	LLM evaluation of setups (OpenAI / Google GenAI; neutral fallback)
Data Harvest Core	Python/database/ + Database/	Persists every score → execution → outcome for calibration

Closed feedback loop:

Setup_Detected ──► AI_Advisory (score 0-100) ──► Trade_Opened ──► dynamic management
        ▲                                                              │
        └────────────── Trade_Closed (net PnL, R-multiple) ◄────────────┘
                                        │
                                   TelemetryDB (SQLite/PostgreSQL)

---

2. Non-Negotiable Tenets

1. Anti-Veto Principle — AI scores scale position risk only (≥70 full, 50–69 half, <50 quarter with a defined floor). They never block baseline algorithmic execution; on AI failure a neutral 40.0 keeps the pipeline trading at minimum risk.
2. Standardized Data Protocol (SDP v1.0) — one ratified JSON envelope schema (sdp_version, timestamp, symbol, timeframe, action_type, algorithmic_confidence_score, payload). CSDPEncoder is the only permitted JSON serializer in the MQL5 codebase.
3. Multi-Asset Dynamic Normalization — zero hardcoded per-symbol point buffers. All distances, SL/TP, lot sizes, and noise thresholds are resolved at runtime from SymbolInfo*() and ATR (CSymbolNormalizer).
4. Non-Blocking TCP/IP Transport — every socket operation is bounded by explicit timeouts (connect 3 s, send 1 s, read ≤2 s); the MT5 event loop never hangs when the Python backend is offline.

---

3. Repository Layout

Centaur_Quant_Architecture/
├── 00_CONCEPT/                  # Charter, BOOTSTRAP (DRP), PROGRESS (telemetry log)
├── Database/schema.sql          # Production PostgreSQL DDL + v_feedback view
├── MQL5/
│   ├── Experts/CentaurQuant.mq5 # Composition root (all modules wired)
│   └── Include/
│       ├── Core/CSymbolNormalizer.mqh
│       ├── Network/CSDPEncoder.mqh, CSocketClient.mqh
│       ├── Data/DataHarvester.mqh, ContextPackager.mqh
│       └── Execution/COrderBlockScanner.mqh, COrderExecutor.mqh, CHistoryTracker.mqh
└── Python/
    ├── router/main.py           # Central gateway (TCP 127.0.0.1:5555)
    ├── models/analyzer.py       # MarketAnalyzer (LLM evaluation engine)
    ├── database/telemetry.py    # TelemetryDB (SQLite feedback loop)
    └── tests/test_sdp_schema.py # QA harness (3/3 green)

---

4. System Requirements & Setup

MetaTrader 5

• Any recent build (sockets + CTrade required).
• Copy the MQL5/ tree into your terminal's MQL5/ folder (or open the project folder in MetaEditor) and compile CentaurQuant.mq5 (0 errors / 0 warnings expected).

Python 3.9+

• sqlite3, socket, threading, json — standard library.
• Optional LLM SDKs (the router degrades to the neutral 40.0 fallback without them):

  pip install openai google-genai
  

TCP Port

• Default bind: 127.0.0.1:5555 (router --host/--port overrides; EA inputs must match).

---

5. Quick Start Guide

1. Start the gateway (from the Python/ folder):

   python router/main.py
   

   Optional env: PROVIDER=openai|google, OPENAI_API_KEY/GEMINI_API_KEY, MODEL, CENTAUR_DB_PATH (default centaur_telemetry.db).
2. Attach the EA in MT5: CentaurQuant → inputs Host=127.0.0.1, Port=5555, Magic=<yours>, RiskPercent → enable AutoTrading.
3. Monitor:
   • Router console: [Setup_Detected], [AI_Advisory], >>> [Trade_Opened/Closed].
   • Telemetry: sqlite3 centaur_telemetry.db "SELECT * FROM trades;".
   • Project state: 00_CONCEPT/PROGRESS.md.

QA

python -m unittest tests.test_sdp_schema   # 3/3 tests OK

---

6. Resynchronization Protocol (for AI-assisted maintenance)

See 00_CONCEPT/BOOTSTRAP.md — any future session can regain full context by running the Dynamic Resynchronization Protocol (scan → read → internalize → verify → acknowledge).

---

7. License

MIT — see LICENSE. Free to use, modify, and distribute; trading use is at your own risk.