docs/H3_FORMAT_README.md

# Script-LoRA → MiniMax H3 format

## Data locations

| Path | Role |
|------|------|
| `../scriptlib/` | **102 screenplays** (`.txt`) — original training library |
| `../TVTropesData/` | Trope/title tables for scenario variety |
| `../final/` | Existing PEFT adapter (story craft + tropes, classic screenplay style) |
| `train_dataset.jsonl` | Hand-written H3 seed examples |
| `train_dataset.full.jsonl` | Built from scriptlib (+ tropes + seed) |

## Recommended path (continue-train, not merge-from-scratch)

The existing `final/` adapter already holds script + TVTropes knowledge. You do
**not** need a LoRA merge of two adapters unless you train a separate format-only
adapter. Prefer:

```bash
cd /home/bbear/Documents/OlympusServer/models/script-lora/h3-format

# Use the OlympusServer venv (system python lacks datasets/trl/peft)
VENV=/home/bbear/Documents/OlympusServer/.venv/bin/python

# 1) Build SFT rows from scriptlib (rewrite + premise) + TVTropes seeds
$VENV build_sft_from_scriptlib.py \
  --include-seed \
  --chunks-per-script 4 \
  --tropes 80 \
  --out train_dataset.full.jsonl

# 2) Continue-train from final/ → h3-v1 (does not overwrite final/)
# This host: torch is XPU-only → use --device xpu (not cuda)
$VENV train_script_lora_h3.py \
  --dataset train_dataset.full.jsonl \
  --init-from ../final \
  --epochs 2 \
  --lr 1e-4 \
  --device xpu
```

Output: `../h3-v1/`. Point the generation slot at that adapter after validation.

### Why not “merge” alone?

- **Weighted LoRA merge** needs two trained adapters. Today you have one (`final/`).
- **Continue-train** from `final/` on H3-format chat data is the practical merge of
  *skills*: old weights + new format supervision.
- Optional later: train a thin format-only LoRA and `add_weighted_adapter` with `final/`.

## Runtime (already live without retrain)

Backlot system prompts emit H3 FL2VA fields regardless of adapter:

- `backend/services/h3_prompt_format.py`
- `/generate/script`, `/generate/script/scene` → `h3_video_prompt`, `storyboard_prompt`

Guides: `optimization/h3-shrink/docs/VIDEO_PROMPT_{base,ref}-en.txt`