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

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

## Local Run

```bash
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:

```bash
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

```bash
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:

```bash
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:

```bash
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:

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

Machine-readable dry-run summary:

```bash
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:

```bash
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:

```bash
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:

```bash
.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:

```bash
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:

```bash
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:

```bash
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:

```bash
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`:

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

Expected `origin`:

```text
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`:

```sshconfig
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:

```bash
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:

```bash
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

```bash
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:

```bash
.venv/bin/python scripts/check_local_demo_readiness.py
```

## Docker

Repo-local compose:

```bash
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.