# TI Coding Agent Probe Skill

Use this skill when the user wants to run or modify the TI coding-agent SFT probe experiments based on the ModelScope dataset `eigentom/ti_coding_agent_training_probe_20260624`. Hugging Face remains available as a fallback backend.

## Repository Contract

- Work in `/ssd/workspace/yi/ti_coding_agent_probe` on B300 unless the user says otherwise.
- Use the B300/g0049 machine-specific proxy for all network access:
  - `http_proxy=http://100.72.0.101:8888`
  - `https_proxy=http://100.72.0.101:8888`
  - `HF_ENDPOINT=https://hf-mirror.com`
- The default package mirrors are domestic China mirrors:
  - `PIP_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/`
  - `UV_DEFAULT_INDEX=https://mirrors.aliyun.com/pypi/simple/`
  - `UV_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/`
- When moving this repo to another machine, first verify or replace the proxy variables. The proxy values above are not portable cluster-wide defaults.
- Do not install Python packages globally. Use the repository-local `.venv` created by `scripts/setup_env.sh`.
- `scripts/setup_env.sh` installs `uv` inside `.venv`, then installs SWIFT from the submodule using SWIFT's documented source-install path: `uv pip install -e third_party/modelscope-swift --torch-backend=auto`.
- Default setup adds training extras: `deepspeed<0.19`, `liger-kernel`, `tensorboard`, and `nvitop`. Disable with `INSTALL_TRAINING_EXTRAS=0`.
- Install SWIFT optional all-dependencies only when explicitly needed: `INSTALL_SWIFT_ALL=1 ./scripts/setup_env.sh`.
- Do not start GPU training before checking GPU occupancy with `nvidia-smi`.
- Do not commit or upload `data/`, `models/`, `outputs/`, `runs/`, or `logs/`.

## Key Commands

Initialize the repo and environment:

```bash
git submodule update --init --recursive
./scripts/setup_env.sh
```

Download the training/eval probe dataset from ModelScope:

```bash
export MODELSCOPE_API_TOKEN=<modelscope-api-key>
./scripts/download_dataset.py
```

The downloader writes:

- `data/raw/training_probe/{train,validation}.jsonl.gz`
- `data/raw/training_probe/{train,validation}.parquet`
- `data/processed/training_probe/{train,validation}.jsonl`
- `data/processed/training_probe/{train,validation}.parquet`

Use Hugging Face fallback only when requested:

```bash
export DATASET_BACKEND=huggingface
export HF_ENDPOINT=https://hf-mirror.com
export HF_DATASET_REPO_ID=<owner>/ti_coding_agent_training_probe_20260624
./scripts/download_dataset.py
```

Download base models:

```bash
./scripts/download_models.sh
```

Model downloads use the current Hugging Face CLI:

```bash
hf download <model-id> --local-dir <dir> --max-workers <n>
```

Do not use the deprecated `huggingface-cli download` or the removed `--local-dir-use-symlinks` option. Tune download concurrency with `HF_DOWNLOAD_MAX_WORKERS`; pass an optional token with `HF_TOKEN`.

Run the full ordered experiment:

```bash
./scripts/run_all_experiments.sh
```

Run only one stage:

```bash
./scripts/train_qwen35_9b_lora.sh
./scripts/train_qwen35_9b_full.sh
./scripts/train_qwen36_27b_lora.sh
./scripts/train_qwen36_27b_full.sh
```

Open TensorBoard:

```bash
./scripts/tensorboard.sh
```

## Training Semantics

The dataset uses SWIFT-style chat messages. `system`, `user`, and `tool` messages should remain masked with `loss=false`; only assistant trajectories should contribute to loss. This keeps scaffold prompts and tool outputs as conditioning context rather than targets to memorize.

The default experiment uses:

- 1 epoch
- LoRA rank 32 for LoRA runs
- bf16 full fine-tuning for full runs
- full SFT learning rate `1e-5`
- LoRA learning rate `5e-5`
- warmup ratio `0.1`
- explicit cosine LR scheduler via `--lr_scheduler_type cosine`
- `max_length=262144`
- conservative per-device train batch size `1`
- default `NPROC_PER_NODE=8`, `CUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6,7`, and `DEEPSPEED=zero2`
- checkpoint save every 1000 steps
- validation every 1000 steps
- TensorBoard logging under `runs/`

Batch size is intentionally conservative because B300/g0049 has ~275GB per GPU but the default context length is 262144 tokens. Increase batch size from the shell only after checking memory:

```bash
export PER_DEVICE_BATCH_SIZE=2
export GRAD_ACCUM_STEPS=2
export LORA_PER_DEVICE_BATCH_SIZE=2
export FULL_PER_DEVICE_BATCH_SIZE=1
export QWEN35_9B_LORA_R32_PER_DEVICE_BATCH_SIZE=2
export QWEN36_27B_FULL_BF16_PER_DEVICE_BATCH_SIZE=1
export MAX_STEPS=10
```

Run-specific variables have the highest precedence, then global `PER_DEVICE_BATCH_SIZE` / `GRAD_ACCUM_STEPS`, then train-type defaults, then the safe default of 1.

Override model IDs or paths with:

```bash
export QWEN35_9B_MODEL_ID=<hf-id>
export QWEN36_27B_MODEL_ID=<hf-id>
export QWEN35_9B_MODEL_PATH=<local-path>
export QWEN36_27B_MODEL_PATH=<local-path>
```

## Megatron-SWIFT

Use `scripts/train_qwen36_27b_megatron_full.sh` for Megatron-SWIFT/MCore-Bridge full SFT. It follows the official `megatron sft` quick-start style and defaults to:

- `NPROC_PER_NODE=8`
- `CUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6,7`
- `MEGATRON_MODEL=Qwen/Qwen3.6-27B`
- `TENSOR_MODEL_PARALLEL_SIZE=4`
- `MICRO_BATCH_SIZE=1`
- `GLOBAL_BATCH_SIZE=8`
- `MAX_LENGTH=262144`
- `LR=1e-5`
- `LR_WARMUP_FRACTION=0.1`

For multi-node or shared-disk runs, keep `MODELSCOPE_CACHE` on shared storage. The default is `/mnt/beegfs/workspace/ti_coding_agent_probe/modelscope_cache`.