Skip to content

Commit 7cd63cf

Browse files
DongwahsDongwahs
committed
Initial public portfolio snapshot
0 parents  commit 7cd63cf

2,246 files changed

Lines changed: 545880 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/focused-tests.yml‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
name: Focused tests
2+
3+
on:
4+
push:
5+
branches: [master]
6+
pull_request:
7+
branches: [master]
8+
9+
jobs:
10+
kraken-maker-shadow:
11+
name: Kraken maker shadow unit tests
12+
runs-on: ubuntu-latest
13+
14+
steps:
15+
- name: Check out repository
16+
uses: actions/checkout@v4
17+
18+
- name: Set up Python
19+
uses: actions/setup-python@v5
20+
with:
21+
python-version: "3.11"
22+
23+
- name: Install CI dependencies
24+
run: python -m pip install PyJWT cryptography
25+
26+
- name: Run discoverable public tests
27+
env:
28+
PYTHONPATH: tests/ci_stubs
29+
run: python -m unittest discover -s tests
30+
31+
- name: Run focused Kraken maker test suite
32+
env:
33+
PYTHONPATH: tests/ci_stubs
34+
run: python -m unittest scripts.test_live_kraken_spot_frontier_maker_machinegun_shadow
35+
36+
- name: Run representative shadow and supervisor suites
37+
env:
38+
PYTHONPATH: tests/ci_stubs
39+
run: python -m unittest scripts.test_live_coinbase_spot_machinegun_shadow scripts.test_coinbase_rsi_shadow scripts.test_mt5_terminal_guard scripts.test_system_health_check

‎.gitignore‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Credentials — NEVER commit
2+
.env
3+
4+
# Local agent/tool state
5+
.claude/
6+
.qwen/
7+
coordination/
8+
memory/
9+
memory.md
10+
notes/
11+
repo-index.md
12+
13+
# Python bytecode
14+
__pycache__/
15+
*.pyc
16+
*.pyo
17+
18+
# Runtime state files (regenerated on start)
19+
canonical_launcher_state.json
20+
canonical_worker_state.json
21+
canonical_worker_refusal_state.json
22+
runtime_state.json
23+
.lab_telescope_last_seen
24+
brain.json
25+
symbol_learner.json
26+
27+
# Large log files
28+
*.log
29+
console_*.log
30+
shadow_*.log
31+
32+
# Generated outputs
33+
reports/
34+
data/candle_cache/
35+
scratch/
36+
debug_*.json
37+
*.bak
38+
scripts/_*
39+
scripts/ad_hoc/
40+
tmp*
41+
tmp_*
42+
temp_*
43+
44+
# Historical archives (not current truth)
45+
archive/
46+
backups/
47+
48+
# War room artifacts
49+
war_room_messages.json
50+
war_room_messages.archive.jsonl
51+
war_room_*.json
52+
53+
# OS files
54+
.DS_Store
55+
Thumbs.db
56+
57+
# IDE
58+
.vscode/
59+
.idea/

‎COMMAND_CENTER.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Trading Bots Command Center
2+
3+
**Public snapshot date:** 2026-05-01
4+
**Status:** Research and supervision infrastructure snapshot
5+
**Deployment posture:** Public repo is evidence and review material only; broker-connected runtime state and credentials are excluded.
6+
7+
This file is a recruiter-readable command-center summary for the public repository. It describes how the system is organized and what can be inspected without implying financial advice, trading recommendations, or future performance.
8+
9+
## Current Public Posture
10+
11+
| Surface | Status | Public evidence |
12+
| --- | --- | --- |
13+
| Focused unit path | Active | GitHub Actions runs the Kraken maker shadow test suite. |
14+
| Strategy evidence | Documented | [`docs/evidence/edge_registry.md`](./docs/evidence/edge_registry.md) preserves modeled results, limitations, and contrary evidence. |
15+
| Experiment protocol | Documented | [`docs/experiment-protocol.md`](./docs/experiment-protocol.md) describes the graduation ladder. |
16+
| Runtime boundaries | Documented | [`PUBLIC_REPO_BOUNDARIES.md`](./PUBLIC_REPO_BOUNDARIES.md) explains what is intentionally excluded from GitHub. |
17+
| Historical variants | Excluded | Older broker bot variants are intentionally not part of the public recruiter snapshot. |
18+
19+
## Operating Model
20+
21+
1. Define a strategy hypothesis.
22+
2. Test or shadow it under explicit gates.
23+
3. Preserve both useful and negative evidence.
24+
4. Promote only when the documented protocol is satisfied.
25+
5. Keep generated runtime state, credentials, broker sessions, and local logs outside the public repository.
26+
27+
## First-Read Files
28+
29+
| File | Why it matters |
30+
| --- | --- |
31+
| [`README.md`](./README.md) | Recruiter-facing overview and reading path. |
32+
| [`docs/evidence/edge_registry.md`](./docs/evidence/edge_registry.md) | Proof-board snapshot with limitations. |
33+
| [`scripts/test_live_kraken_spot_frontier_maker_machinegun_shadow.py`](./scripts/test_live_kraken_spot_frontier_maker_machinegun_shadow.py) | Highest-signal test surface in the current public repo. |
34+
| [`scripts/live_kraken_spot_frontier_maker_machinegun_shadow.py`](./scripts/live_kraken_spot_frontier_maker_machinegun_shadow.py) | Runner behavior covered by the focused test suite. |
35+
| [`scripts/README.md`](./scripts/README.md) | Curated guide for navigating the larger script inventory. |
36+
| [`PUBLIC_REPO_BOUNDARIES.md`](./PUBLIC_REPO_BOUNDARIES.md) | Scope, omissions, and privacy boundaries. |
37+
38+
## Review Notes
39+
40+
- Public evidence is a research filter, not a profit claim.
41+
- Backtests and shadow tests can fail under live market conditions.
42+
- Archived scripts may show historical exploration patterns and are not the current source of truth.
43+
- The current public proof path is intentionally narrow so visitors can verify at least one concrete behavior surface quickly.
44+
45+
## Next Public Polish
46+
47+
1. Keep expanding focused CI around one runner at a time.
48+
2. Move additional root helpers into `scripts/` as their role becomes clear.
49+
3. Add more evidence pages only when their assumptions and limitations can be stated cleanly.

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 Fred McCullough
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎PUBLIC_REPO_BOUNDARIES.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Public Repo Boundaries
2+
3+
This repository is the public proof layer for a larger local trading-research workspace. It is intentionally curated to show the engineering system, validation discipline, representative tested code, and safe evidence artifacts.
4+
5+
## Included
6+
7+
- Research and strategy code that can be reviewed without broker access.
8+
- Focused unit tests and GitHub Actions CI.
9+
- Architecture, experiment protocol, and operator documentation.
10+
- Evidence snapshots such as proof boards, performance reviews, and validation summaries.
11+
- Historical bot variants that help explain the project evolution.
12+
13+
## Excluded
14+
15+
- Credentials, API keys, tokens, account IDs, and private broker configuration.
16+
- Live or shadow runtime state, generated learning payloads, and account-specific snapshots.
17+
- Local logs, debug dumps, temporary probes, and generated reports.
18+
- Local agent settings, chat/task stores, and machine-specific orchestration files.
19+
- Any material that would expose private operating details rather than public engineering evidence.
20+
21+
## Why This Boundary Exists
22+
23+
The goal is to make the repository reviewable without publishing unsafe or noisy operating artifacts. A public portfolio repo should let a visitor inspect architecture, tests, validation methods, and representative implementation while keeping credentials, live-state payloads, and machine-local workflows private.
24+
25+
This boundary is part of the engineering standard: the system is designed to separate proof surfaces from operational state.

‎README.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# Trading Bots Workspace - Quantitative Research & Execution Infrastructure
2+
3+
[![Focused tests](https://github.com/GalToast/trading-bots/actions/workflows/focused-tests.yml/badge.svg)](https://github.com/GalToast/trading-bots/actions/workflows/focused-tests.yml)
4+
5+
AI-assisted quantitative research system for testing trading ideas under explicit validation gates, runtime supervision, and evidence-preserving review.
6+
7+
This repository is best read as a decision-system 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.
8+
9+
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.
10+
11+
![Trading lane presentation](docs/assets/trading-lane-presentation.png)
12+
13+
## How to Review This Repo
14+
15+
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.
16+
17+
## What This Demonstrates
18+
19+
- Building a multi-lane automation system with shared runtime controls and supervised execution paths.
20+
- Turning messy strategy ideas into testable hypotheses with acceptance gates and failure records.
21+
- Using AI-native workflows to design, operate, test, and revise a real local research system without hiding the audit trail.
22+
- Separating public proof artifacts from local runtime state, credentials, broker-connected workflows, and generated logs.
23+
- Maintaining a green, focused CI path for the highest-signal unit surface in the current public snapshot.
24+
25+
## Proof Snapshot
26+
27+
| Proof surface | What it shows |
28+
| --- | --- |
29+
| [Focused CI](https://github.com/GalToast/trading-bots/actions/workflows/focused-tests.yml) | GitHub Actions runs the Kraken maker shadow unit test suite. |
30+
| [`scripts/test_live_kraken_spot_frontier_maker_machinegun_shadow.py`](./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. |
31+
| [`docs/evidence/edge_registry.md`](./docs/evidence/edge_registry.md) | Proof-board style registry of validated strategy families and backtest evidence. |
32+
| [`docs/experiment-protocol.md`](./docs/experiment-protocol.md) | The graduation ladder for moving ideas from hypothesis to validated strategy. |
33+
| [`docs/performance-review.md`](./docs/performance-review.md) | Performance review notes, including failure modes and limitations. |
34+
| [`COMMAND_CENTER.md`](./COMMAND_CENTER.md) | Runtime posture, deployment gates, and decision status snapshot. |
35+
36+
## System Model
37+
38+
The project combines research scripts, strategy runners, runtime monitors, and documentation into a controlled experimentation loop:
39+
40+
1. Generate a strategy hypothesis.
41+
2. Backtest or shadow-test it under explicit constraints.
42+
3. Record proof, failure, and ambiguity instead of only preserving wins.
43+
4. Promote only when the evidence meets the documented gate.
44+
5. Keep runtime state and broker-connected details out of the public tree.
45+
46+
![Trading bots system architecture](docs/assets/system-architecture.svg)
47+
48+
## Runtime Architecture
49+
50+
| Component | Role |
51+
| --- | --- |
52+
| `mt5_bot.py` | Canonical supervisor for monitored worker execution. |
53+
| `mt5_bot_v10.py` | Canonical worker containing trading loop, entries, and exits. |
54+
| `exit_manager.py` | Dynamic exit-policy companion. |
55+
| `monitor.py` | Watchdog and health-check surface. |
56+
| `brain.py` | Learning/adaptation logic; generated state is excluded from the public repo. |
57+
| `bot/` | Policy subroutines for admission, competition lane priority, exits, posture, symbol risk, and price structure. |
58+
| `scripts/live_kraken_spot_frontier_maker_machinegun_shadow.py` | Current focused Kraken maker shadow runner under unit coverage. |
59+
60+
## Repository Guide
61+
62+
| Path | Purpose |
63+
| --- | --- |
64+
| [`docs/QUICKSTART.md`](./docs/QUICKSTART.md) | Short orientation before touching broker-connected workflows. |
65+
| [`docs/trading-lane-presentation.html`](./docs/trading-lane-presentation.html) | Browser-readable presentation surface for the system model. |
66+
| [`docs/evidence/`](./docs/evidence/) | Public proof artifacts suitable for first-pass review. |
67+
| [`docs/assets/system-architecture.svg`](./docs/assets/system-architecture.svg) | Architecture diagram for the public review path. |
68+
| [`PUBLIC_REPO_BOUNDARIES.md`](./PUBLIC_REPO_BOUNDARIES.md) | What is public here, what stays private locally, and why. |
69+
| [`scripts/README.md`](./scripts/README.md) | Curated guide to the large scripts directory. |
70+
| [`scripts/`](./scripts/) | Research builders, runners, tests, and proof-board generators. |
71+
| [`tests/`](./tests/) | Discoverable public smoke tests for core policy modules and CI stubs. |
72+
| [`research/strategies/`](./research/strategies/) | Strategy prototypes and experiment families. |
73+
74+
## Recruiter Reading Path
75+
76+
Start with the CI badge, then read [`docs/experiment-protocol.md`](./docs/experiment-protocol.md) and [`docs/evidence/edge_registry.md`](./docs/evidence/edge_registry.md). After that, inspect the focused Kraken maker test and runner pair:
77+
78+
- [`scripts/test_live_kraken_spot_frontier_maker_machinegun_shadow.py`](./scripts/test_live_kraken_spot_frontier_maker_machinegun_shadow.py)
79+
- [`scripts/live_kraken_spot_frontier_maker_machinegun_shadow.py`](./scripts/live_kraken_spot_frontier_maker_machinegun_shadow.py)
80+
81+
Those files show the most concrete engineering signal: strategy behavior is specified, tested, and constrained before being treated as deployable.
82+
83+
## Disclaimer
84+
85+
This is research infrastructure. It is not financial advice, not a guarantee of trading performance, and not a recommendation to trade any instrument.

‎bot/__init__.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
"""Shared bot policy modules extracted from the monolith."""

0 commit comments

Comments
 (0)