ai-exchange/RUNBOOK.md

ai-exchange Runbook

Project Summary

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

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

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
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 only signal invalidations plus MSS/FVG meta compatibility fields
• liquidity duplicate groups are reported for manual review and are not auto-merged

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

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.

Docker

Repo-local compose:

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

Documented single-set local deployment policy from the repo README:

cd /root/deploy/ai-ict
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

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.