Centaur_Quant_Architecture/README.md

# 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):
  ```bash
  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):
   ```bash
   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
```bash
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.