Trading Bots Workspace - Quantitative Research & Execution Infrastructure

Developed by Fred McCullough

AI-assisted quantitative research system for testing trading ideas under explicit validation gates, runtime supervision, and evidence-preserving review.

This repository is best read as a paper/experimental systems-research case study, not as a profit claim. The engineering focus is hypothesis design, experiment control, telemetry, risk limits, watchdog supervision, and proof surfaces that keep both positive and negative evidence visible.

In this snapshot, "AI-assisted" means LLM-assisted system design, review, and iteration around rule-based/adaptive trading infrastructure. It does not claim a trained predictive model or autonomous black-box trading agent.

Public Framing

For recruiter, client, or public review, this project should be evaluated as automation and research infrastructure:

• Not live-performance marketing: dollar figures in public evidence files are modeled, paper, shadow, or backtest accounting unless explicitly labeled otherwise.
• Not financial advice: nothing here recommends trading any instrument or deploying any strategy.
• Not a black-box prediction claim: the public signal is the system of tests, telemetry, guardrails, promotion gates, and falsification records.
• Not a complete local runtime dump: broker-connected state, credentials, private logs, generated payloads, and local runtime artifacts are intentionally excluded.

The hiring signal is the ability to build deterministic harnesses around noisy systems, preserve contrary evidence, and keep risk controls visible.

How to Review This Repo

If you have 5 minutes, check the CI badge, skim the system diagram, and read the Proof Snapshot. If you have 15 minutes, read the experiment protocol and edge registry, then inspect the focused Kraken maker test. If you want the technical core, compare the focused test with the runner it covers.

What This Demonstrates

• Building a multi-lane automation system with shared runtime controls and supervised execution paths.
• Turning messy strategy ideas into testable hypotheses with acceptance gates and failure records.
• Using AI-native workflows to design, operate, test, and revise a real local research system without hiding the audit trail.
• Separating public proof artifacts from local runtime state, credentials, broker-connected workflows, and generated logs.
• Maintaining a green, focused CI path for the highest-signal unit surface in the current public snapshot.

Proof Snapshot

Proof surface	What it shows
Focused CI	GitHub Actions runs the Kraken maker shadow unit test suite.
scripts/test_live_kraken_spot_frontier_maker_machinegun_shadow.py	Focused tests for maker/taker accounting, spread gates, min-notional guards, reentry cooldowns, and exit behavior.
docs/evidence/edge_registry.md	Proof-board style registry of validated strategy families and backtest evidence.
docs/experiment-protocol.md	The graduation ladder for moving ideas from hypothesis to validated strategy.
docs/performance-review.md	Performance review notes, including failure modes and limitations.
COMMAND_CENTER.md	Runtime posture, deployment gates, and decision status snapshot.

The Throughline

I build systems that turn ambiguous real-world signals into bounded operational decisions. In this workspace, that means classifying market tape conditions into profit modes, runtime guards, and survivability-aware controller decisions.

System Model

The project combines research scripts, strategy runners, runtime monitors, and documentation into a controlled experimentation loop:

1. Generate a strategy hypothesis.
2. Backtest or shadow-test it under explicit constraints.
3. Record proof, failure, and ambiguity instead of only preserving wins.
4. Promote only when the evidence meets the documented gate.
5. Keep runtime state and broker-connected details out of the public tree.

Runtime Architecture

Component	Role
mt5_bot.py	Canonical supervisor for monitored worker execution.
mt5_bot_v10.py	Compatibility shim re-exporting the bot/mt5/ package API (see below); kept so existing entry points keep working.
exit_manager.py	Dynamic exit-policy companion.
monitor.py	Watchdog and health-check surface.
brain.py	Learning/adaptation logic; generated state is excluded from the public repo.
bot/	Policy subroutines for admission, competition lane priority, exits, posture, symbol risk, and price structure.
scripts/live_kraken_spot_frontier_maker_machinegun_shadow.py	Current focused Kraken maker shadow runner under unit coverage.

MT5 worker package (bot/mt5/)

The former 11,344-line mt5_bot_v10.py monolith is now a package of 14 modules; mt5_bot_v10.py itself is a compatibility shim that re-exports the package's public API. The eight names rebound at runtime (mt5_connected, _brain, _learner, _tick_cache_cycle, consecutive_wins, consecutive_losses, total_pnl, trades) are single-sourced in state.py, and the shim delegates to them live via module __getattr__/__dir__ (PEP 562) — covered by tests/test_bot_mt5_shared_state.py.

Module	Role
state.py	Shared mutable runtime state (single source for runtime-rebound names).
config.py	Tuning constants for the MT5 worker.
log.py	Primitive logging / JSONL helpers (leaf module).
market_data.py	MT5 connection, bar/tick caches, broker-state markers.
indicators.py	Pure technical-indicator math (RSI/ATR/EMA); unit-tested.
sessions.py	Symbol/session classifiers; unit-tested.
signals.py	Signal generation (momentum, regime, mean reversion, price action).
risk.py	Risk measurement: stress, sizing, margin safety (no order execution).
positions.py	Position-state helpers.
book.py	Position book: entries, exits, defense and rearm logic.
journal.py	Trade/behavior records, snapshots, runtime state files.
strategy_lab.py	Experimental strategy-lab lane logic.
runner.py	Main worker loop and process entry helpers.

Repository Guide

Path	Purpose
docs/QUICKSTART.md	Short orientation before touching broker-connected workflows.
docs/trading-lane-presentation.html	Browser-readable presentation surface for the system model.
docs/evidence/	Public proof artifacts suitable for first-pass review.
docs/assets/system-architecture.svg	Architecture diagram for the public review path.
PUBLIC_REPO_BOUNDARIES.md	What is public here, what stays private locally, and why.
scripts/README.md	Curated guide to the large scripts directory.
scripts/	Research builders, runners, tests, and proof-board generators.
tests/	Discoverable public smoke tests for core policy modules and CI stubs.
research/strategies/	Strategy prototypes and experiment families.
configs/	Strategy parameter configs from tuning/research runs (e.g. configs/hungry_hippo_eurusd_live.json). The _live / _shadow / _deploy suffixes name the parameter set's intended lane, not recorded brokerage results — these files are experiment inputs (step sizes, close rules, rearm policies), not profit claims.

Recruiter Reading Path

Start with the CI badge, then read docs/experiment-protocol.md and docs/evidence/edge_registry.md. After that, inspect the focused Kraken maker test and runner pair:

• scripts/test_live_kraken_spot_frontier_maker_machinegun_shadow.py
• scripts/live_kraken_spot_frontier_maker_machinegun_shadow.py

Those files show the most concrete engineering signal: strategy behavior is specified, tested, and constrained before being treated as deployable.

Disclaimer

This is paper/experimental research infrastructure. It is not financial advice, not a guarantee of trading performance, not a live brokerage performance claim, and not a recommendation to trade any instrument.