yuqei/ai-exchange
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
ai-exchange/RUNBOOK.md
T
Codex d7a4330d30 Add ICT book mainline governance docs
2026-05-21 08:27:12 +08:00

9.3 KiB
Raw Permalink Blame History

ai-exchange Runbook

Project Summary

  • Package name: ai-ict
  • Python version: >=3.11
  • Main local API port: 8000
  • Default branch observed during setup: main

Hard Mainline Requirement

Before running a development, deploy, or smoke loop for trading-analysis work, confirm that the requested slice follows:

  • docs/ICT交易全书_出版终校版.md
  • docs/AI_ICT_硬性主线约束_必须遵循ICT交易全书_2026-05-21_v1.md

Required product chain:

Range / Draw / Location
-> Liquidity / Sweep / Inducement / Path
-> Displacement / MSS / FVG / Retest / Session
-> backtest evidence
-> pre-market plan
-> intraday unique focus or no-trade reason
-> journal / study-notes feedback

If the work cannot map to that chain, do not deploy it as a trader-facing feature.

Setup

cd /home/yuqei/project/ai-exchange
test -d .venv || uv sync
test -f .env || cp .env.example .env

Local Run

cd /home/yuqei/project/ai-exchange
.venv/bin/python scripts/run_api_server.py

This serves the trading workbench at / and the training console at /training.

Alternative entrypoints already documented by the project:

python3 scripts/run_dev.py
python3 scripts/run_pipeline.py

scripts/run_dev.py is the persistent local dev API/dashboard entrypoint; scripts/run_pipeline.py runs the closed loop once and exits.

Test And Validation

cd /home/yuqei/project/ai-exchange
.venv/bin/python -m unittest discover -s tests/unit -p "test_*.py"
.venv/bin/python scripts/run_offline_checks.py
.venv/bin/python scripts/check_local_demo_readiness.py
.venv/bin/python scripts/check_trading_delivery_readiness.py
python3 scripts/run_migration_static_checks.py
python3 scripts/run_script_static_checks.py

Training Generator Prototype

The current generator work is a read-only offline prototype. It does not write Training cases to database-backed tables.

Show help:

cd /home/yuqei/project/ai-exchange
.venv/bin/python scripts/run_training_case_generator.py --help

Run the prototype against the tracked seed fixture and write a public draft package:

cd /home/yuqei/project/ai-exchange
.venv/bin/python scripts/run_training_case_generator.py \
  --input tests/fixtures/training_case_generator_seed_v1.json \
  --output /tmp/generated_training_case_drafts.json

Prototype intent:

  • Input is trading-derived seed events only
  • Output is a public Training case draft package
  • The prototype is offline, read-only, and rollback-friendly
  • Public output omits private solution material and keeps answer content empty

Historical Compatibility Repair

The current historical compatibility repair path is intentionally safe by default:

  • default mode is read-only scan
  • safe apply mode repairs signal invalidations, MSS/FVG meta compatibility fields, and liquidity safe merges limited to unreferenced supersets plus exact duplicate rows with identical sweep events
  • manual review still owns needs_sweep_reference_migration and keep_version_history groups

Dry-run scan:

cd /home/yuqei/project/ai-exchange
.venv/bin/python scripts/run_historical_compatibility_repair.py

Machine-readable dry-run summary:

cd /home/yuqei/project/ai-exchange
HISTORICAL_REPAIR_OUTPUT_JSON=1 .venv/bin/python scripts/run_historical_compatibility_repair.py

Apply only the safe automatic repairs:

cd /home/yuqei/project/ai-exchange
.venv/bin/python scripts/run_historical_compatibility_repair.py --apply-safe-repairs

Apply executable liquidity reference migrations only when duplicate-pool groups are exact duplicates and the dry-run plan shows no sweep timestamp conflicts:

cd /home/yuqei/project/ai-exchange
.venv/bin/python scripts/run_historical_compatibility_repair.py --apply-liquidity-reference-migrations

Trading Delivery Checklist

Use this locked trading delivery checklist before every market validation or deploy, so the trading module can be promoted without relying on chat memory.

must-run before every market validation or deploy:

.venv/bin/python -m unittest discover -s tests/unit -p "test_*.py"
.venv/bin/python scripts/run_offline_checks.py
.venv/bin/python scripts/check_local_demo_readiness.py
.venv/bin/python scripts/run_secret_static_checks.py
.venv/bin/python scripts/check_trading_delivery_readiness.py

Database gate:

READINESS_OUTPUT_JSON=1 .venv/bin/python scripts/run_database_readiness.py
HISTORICAL_REPAIR_OUTPUT_JSON=1 .venv/bin/python scripts/run_historical_compatibility_repair.py
.venv/bin/python scripts/run_historical_compatibility_repair.py --apply-safe-repairs
HISTORICAL_REPAIR_OUTPUT_JSON=1 .venv/bin/python scripts/run_historical_compatibility_repair.py
PIPELINE_OUTPUT_JSON=1 BACKTEST_REQUIRE_QUALITY_GATE=1 .venv/bin/python scripts/run_pipeline.py

Use --apply-safe-repairs only when the dry-run output shows safe candidates. After the second dry-run, manual review is still required for needs_sweep_reference_migration and keep_version_history, and backtest_quality_gate.passed must be true before promotion.

Deploy and health check:

docker compose -p ai-ict -f /root/deploy/ai-ict/docker-compose.yml down --remove-orphans
docker compose -p ai-ict -f /root/deploy/ai-ict/docker-compose.yml up -d --build
docker compose -p ai-ict -f /root/deploy/ai-ict/docker-compose.yml ps
test "$(docker ps --filter label=com.docker.compose.project=ai-ict --format '{{.Names}}' | wc -l | tr -d ' ')" = "1"
test "$(docker ps --filter name=^/ai-ict$ --format '{{.Names}}' | wc -l | tr -d ' ')" = "1"
test "$(docker inspect -f '{{.State.Health.Status}}' ai-ict)" = "healthy"
curl -fsS http://127.0.0.1:8000/health
curl -fsS "http://127.0.0.1:8000/trading/candidates?instrument_id=1&limit=1"

Post-deploy observe:

READINESS_OUTPUT_JSON=1 .venv/bin/python scripts/run_database_readiness.py
REPORTS_OUTPUT_JSON=1 .venv/bin/python scripts/run_reports.py

The paper execution boundary remains in force here: run_pipeline.py and the execution path are still paper-only, and any API 5xx, Docker unhealthy state, or non-empty readiness reasons should stop promotion immediately.

For one-command rehearsal orchestration, use scripts/run_trading_delivery_rehearsal.py; it runs checklist drift validation, historical repair gating, readiness plus auto-backfill, guarded pipeline, optional deploy/health-check, and post-deploy observe in one scripted flow.

Rollback trigger:

git rev-parse HEAD
docker compose -p ai-ict -f /root/deploy/ai-ict/docker-compose.yml logs --tail=100 ai-ict
git worktree add /tmp/ai-ict-rollback <last-known-good-sha>
cd /tmp/ai-ict-rollback && AI_ICT_DEPLOY_PASSWORD=<set-in-shell> AI_ICT_DEPLOY_USE_SUDO=1 .venv/bin/python scripts/deploy_with_password.py --host 192.168.3.90 --user yuqei --port 22 --remote-path /home/yuqei/project/ai-exchange --remote-archive /home/yuqei/ai-ict-deploy.tgz
rm -rf /tmp/ai-ict-rollback

Record the current commit as the last-known-good SHA before deploy. If any gate above fails, capture logs first, then redeploy from the clean rollback worktree rather than mutating the active development checkout.

Git Remote

This repo is currently configured to use SSH for origin:

cd /home/yuqei/project/ai-exchange
git remote -v

Expected origin:

origin  gitea-water:yuqei/ai-exchange.git (fetch)
origin  gitea-water:yuqei/ai-exchange.git (push)

The SSH host alias is provided by /root/.ssh/config:

Host gitea-water
  HostName 192.168.3.90
  Port 2222
  User git
  IdentityFile /root/.ssh/water_audit_gitea_ed25519
  IdentitiesOnly yes
  StrictHostKeyChecking accept-new

Recommended checks before pushing:

ssh -T -o BatchMode=yes gitea-water
git ls-remote gitea-water:yuqei/ai-exchange.git HEAD
git push origin main

If origin is accidentally changed back to HTTP, restore SSH with:

cd /home/yuqei/project/ai-exchange
git remote set-url origin gitea-water:yuqei/ai-exchange.git

Avoid using the old HTTP remote here unless HTTP credentials are explicitly configured for the current shell user.

Local Docker deployment

Use the single-set local Docker deployment policy for local server deployment:

  • deploy directory /root/deploy/ai-ict
  • compose project ai-ict
  • container ai-ict
  • exactly one active deployment set
  • one active ai-ict container
  • do not create a second local stack
docker compose -p ai-ict -f /root/deploy/ai-ict/docker-compose.yml down --remove-orphans
docker compose -p ai-ict -f /root/deploy/ai-ict/docker-compose.yml up -d --build
docker compose -p ai-ict -f /root/deploy/ai-ict/docker-compose.yml ps
test "$(docker ps --filter label=com.docker.compose.project=ai-ict --format '{{.Names}}' | wc -l | tr -d ' ')" = "1"
test "$(docker ps --filter name=^/ai-ict$ --format '{{.Names}}' | wc -l | tr -d ' ')" = "1"
test "$(docker inspect -f '{{.State.Health.Status}}' ai-ict)" = "healthy"

Check the documented local demo readiness without starting containers; this offline check does not invoke Docker:

.venv/bin/python scripts/check_local_demo_readiness.py

Docker

Repo-local compose:

cd /home/yuqei/project/ai-exchange
docker compose up -d --build
docker compose ps

Notes

  • Existing services in docker-compose.yml: ai-ict
  • Existing mapped port in docker-compose.yml: 8000:8000
  • Use SESSION.md for the exact next step instead of relying on conversation memory.
Reference in New Issue View Git Blame Copy Permalink