DELTACORPS/bbold-btcusd-bot

BBOLD BTCUSD — Autonomous Institutional-Grade Cognitive Trading System

An AI that thinks, reasons, plans and trades like a top-tier human trader — with infinite patience and zero emotional error.

BBOLD is a cognitive trading organism for BTCUSD scalping (5–60 pip targets). It combines 21 specialised analytical modules, a 30+ model ML ensemble, neuro-symbolic confluence voting, non-repainting guarantees, and a self-learning loop (including nightly "Dream Mode" counterfactual replay).

---

📚 Documentation Set

Read in order:

1. PROJECT_CHARTER.md — The why and what: vision, goals, philosophy, risk guardrails, success metrics, feature catalogue.
2. ARCHITECTURE_AND_DESIGN.md — System-level how: pipeline, data flow, non-repainting design, anti-overfitting strategy, memory architecture, tech stack.
3. MODULE_SPECIFICATIONS.md — Per-file blueprint for every one of the 24 modules: classes, signatures, algorithms, dependencies, tests.
4. IMPLEMENTATION_PLAYBOOK.md — Execution roadmap: PR-by-PR build sequence, test plan, CI, quality gates, Definition of Done.
5. OPERATIONS_MANUAL.md — Production runbook: install, config, Docker/K8s, monitoring, retraining, backups, disaster recovery.

A non-programmer should be able to understand the system from these five documents. A senior engineer should be able to build it without asking a single clarifying question.

---

🧠 What Makes BBOLD Different

• Non-repainting by design — every indicator uses only closed bars (shift(1)); enforced by tests/test_no_lookahead.py.
• 18-stage confluence — no single module can fire a trade; weighted soft voting required.
• 30+ model ensemble — heterogeneous ML (RF, XGB, LightGBM, CatBoost, kNN, SVM, MLP, 1D-CNN, Tiny-LSTM, GRU, …) with walk-forward + adversarial validation.
• Self-learning loop — Bayesian weight updates after every trade; nightly retrain; counterfactual "Dream Mode".
• Four-tier memory — working (RAM), episodic (SQLite), semantic (FAISS), reflective (memory.md).
• Hard risk guardrails — circuit breakers cannot be overridden at runtime.
• Explainability first — every signal carries a reason chain (which modules voted + SHAP feature attribution).

---

🗂️ Codebase Structure

bbold-btcusd-bot/
├── data/                  # CSV inputs (5m/15m/30m/h1)
├── modules/               # 21 analytical engines + cognitive_brain
├── models/                # trained ML artefacts + FAISS index
├── tests/                 # mirrored test suite (≥ 80 % coverage)
├── dashboard/             # React frontend + Node.js backend
├── docs/                  # The 5 master documents
├── main.py                # Entry point
├── memory.md              # Persistent external reasoning log
└── requirements.txt

---

⚡ Quickstart

# 1. Clone & install
git clone <repo-url> bbold-btcusd-bot && cd bbold-btcusd-bot
python3.11 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# 2. Drop your CSV data into data/ (columns: datetime,open,high,low,close,volume)

# 3. Train the AI ensemble (first time only, ~30 min on 8 cores)
python modules/ai_engine.py --train

# 4. Run a historical replay
python main.py --mode replay --start 2024-01-01 --end 2024-06-30

# 5. Launch the dashboard
docker compose up -d redis
cd dashboard/backend  && npm install && npm start &
cd dashboard/frontend && npm install && npm start
# → open http://localhost:3000

Or, all-in-one with Docker:

docker compose up

---

🎯 Success Targets (v1.0)

Metric	Target
Directional accuracy (post-learning)	≥ 97 %
Sharpe ratio (annualised, backtest)	≥ 1.5
Profit factor	≥ 1.4
Max drawdown	≤ 8 %
Cycle latency	< 1 s
Repaint events	0
Test coverage	≥ 80 %

---

🛡️ Risk Guardrails (Hard)

• 0.5 % risk per trade
• 2 % max daily loss → SAFE MODE
• 8 % max drawdown → trading halted
• Min confluence 0.75 to trade
• Max 10 trades / day
• 1.5 × ATR stop / 2.5 × ATR target (R:R ≥ 1.66)

Full list in PROJECT_CHARTER.md §7.

---

📦 Tech Stack (summary)

Python 3.11 · pandas · scikit-learn · XGBoost · LightGBM · CatBoost · PyTorch (CPU) · FAISS · SHAP · Redis · SQLite · Node.js 18 · React 18 · TradingView Lightweight Charts · Docker · GitHub Actions.

Full justification in ARCHITECTURE_AND_DESIGN.md §7.

---

🛠️ Contributing / Building

Follow the PR sequence in IMPLEMENTATION_PLAYBOOK.md §3. Every PR must pass:

• ✅ Ruff (lint)
• ✅ mypy (types)
• ✅ pytest with coverage ≥ 80 %
• ✅ No-lookahead test

---

📄 License

TBD by owner.

---

👥 Stakeholders

Role	Document of Interest
Owner (non-programmer)	PROJECT_CHARTER.md + dashboard
Lead Developer	MODULE_SPECIFICATIONS.md + IMPLEMENTATION_PLAYBOOK.md
DevOps / SRE	OPERATIONS_MANUAL.md
Quant Researcher	ARCHITECTURE_AND_DESIGN.md
AI Engineer	MODULE_SPECIFICATIONS.md §ai_engine + OPERATIONS_MANUAL.md §7

---

Built to think. Built to learn. Built to last. — BBOLD