woodfireind/H3-ScriptGen

1---2language:3- en4library_name: peft5pipeline_tag: text-generation6license: apache-2.07base_model: Qwen/Qwen3.5-0.8B8tags:9- lora10- sft11- trl12- script-generation13- minimax-h314- video-generation15---16 17# H3-ScriptGen — MiniMax-H3 FL2VA scriptwriting LoRA18 19A PEFT LoRA adapter on **Qwen/Qwen3.5-0.8B** that writes **stage/camera directions for MiniMax H3** — one FL2VA scene beat per request, in the exact field structure the H3 video pipeline consumes (`ACTION`, `SHOT`, `STORYBOARD_PROMPT`, `H3_MODE: FL2VA`, `H3_VIDEO_PROMPT`, `overall_soundscape`, `non_diegetic_music`, `DURATION`). Each beat maps 1:1 to a storyboard still + one ~5 s H3 FL2V clip.20 21This is the **merged** adapter: it was **continue-trained from the previous `final/` adapter** (story craft + TVTropes) on 836 H3-format SFT rows, so it keeps the old screenplay/trope knowledge and adds the MiniMax-H3 prompt format on top. Per the project's own guidance, that continue-train is the "practical merge of skills" (see `docs/H3_FORMAT_README.md`) — it is *not* a weighted merge of two separately-trained LoRAs.22 23## Contents24 25| Artifact | Description |26|---|---|27| `adapter_model.safetensors` + `adapter_config.json` | **The merged adapter (final, epoch 2)** — load with PEFT |28| `tokenizer_config.json`, `tokenizer.json`, `chat_template.jinja` | Qwen3.5 tokenizer + chat template (from base) |29| `training_config.json` | Training metadata (`init_from: …/final`, base, hyperparams) |30| `checkpoint-105/` | Epoch-1 checkpoint (full trainer state, resumable) |31| `checkpoint-210/` | Epoch-2 checkpoint (== root adapter; full trainer state) |32| `scripts/` | `train_script_lora_h3.py`, `build_sft_from_scriptlib.py`, SFT dataset (`train_dataset.full.jsonl`, 836 rows) + seed examples |33| `docs/` | MiniMax H3 prompt guides (`VIDEO_PROMPT_base-en.txt`, `VIDEO_PROMPT_ref-en.txt`), `h3_prompt_format.py` (runtime field builders), `H3_FORMAT_README.md` |34 35## Base model36 37- **`Qwen/Qwen3.5-0.8B`** (Apache-2.0), 0.8B params, causal LM.38- LoRA: `r=16`, `alpha=32`, `dropout=0.1`, target modules `q/k/v/o_proj` + `gate/up/down_proj` (193 tensors, 193 = standard PEFT layout).39 40## Training41 42| Setting | Value |43|---|---|44| Format | `minimax-h3-fl2va-v1` (SFT, chat template) |45| Init | Continue-train from `models/script-lora/final` adapter |46| Data | `train_dataset.full.jsonl` — 836 rows from 102 screenplays (`scriptlib`) + TVTropes seeds + hand-written H3 examples |47| Epochs / steps | 2 / 210 |48| Learning rate | 1e-4 (cosine decay) |49| Max seq len | 1536 |50| Optimizer | AdamW (non-fused, XPU) |51| Device | Intel Arc A770 (XPU) |52 53Final metrics (from training log): `train_loss 0.7535`, final-step `mean_token_accuracy 0.8932`; token accuracy ranged ~0.86–0.91 over the run. `checkpoint-105` (epoch 1) and `checkpoint-210` (epoch 2) are both included; the root `adapter_model.safetensors` is identical to `checkpoint-210`.54 55## Output format (one beat)56 57```text58## SCENE {N} — {SLUGLINE}59ACTION: <1–2 sentences of visual action for ~5 s>60DIALOGUE — {NAME}: <line>            (at most 1 line, or omit if silent)61SHOT: <camera type + optional amplitude + speed, natural English>62STORYBOARD_PROMPT: <self-contained still-image prompt; no camera timeline>63H3_MODE: FL2VA64H3_VIDEO_PROMPT:65How the reference pictures align with the target video — Picture 1 (from Shot 1) aligns with the 0.00-second mark of the target video; Picture 2 (from Shot 1) aligns with the 5.00-second mark of the target video.66 67integrated_multimodal_description: [Shot 1] Live-action, cinematic, <opening composition matching the storyboard>. <continuous motion path Picture 1 → Picture 2; camera motion as natural English>. <dialogue as: the {name} (S1) says: <d>[English] line here</d>>68 69overall_soundscape: <ambience / physical sounds, or N/A>70 71non_diegetic_music: <audience-only score, or N/A>72LORA: <image-lora:strength, or "none">73AUDIO: <post-process sfx/music note, or "none">74DURATION: 575```76 77The `h3_video_prompt` and `storyboard_prompt` fields feed directly into the MiniMax H3 FL2V pipeline (storyboard panel N → panel N+1, `zvideo_h3_storyboard_fl2v`).78 79## Usage80 81```python82from peft import PeftModel83from transformers import AutoModelForCausalLM, AutoTokenizer84 85base = "Qwen/Qwen3.5-0.8B"86tok = AutoTokenizer.from_pretrained(base)87model = AutoModelForCausalLM.from_pretrained(base, torch_dtype="bfloat16")88model = PeftModel.from_pretrained(model, "woodfireind/H3-ScriptGen")89 90messages = [91    {"role": "system", "content": "You write ONE MiniMax-H3 FL2VA scene beat for Backlot."},92    {"role": "user", "content": "Premise: A courier delivers a package through a neon alley in the rain.\nWrite SCENE 1 now."},93]94text = tok.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)95out = tok.generate(tok(text, return_tensors="pt").input_ids, max_new_tokens=512)96print(tok.decode(out[0]))97```98 99The adapter also loads on llama.cpp / vLLM servers that support PEFT LoRA adapters on the same base model.100 101## Limitations102 103- **Small base (0.8B)** — strong on structure/format adherence; weaker than larger models on nuance, and token accuracy is ~0.9, so occasional malformed fields are expected. Validate output with `docs/h3_prompt_format.py` (`parse_scene_h3_fields`).104- **Text-only.** This adapter only produces prompt text. Producing video still requires the MiniMax H3 stack (GGUF DiT + VAE + text encoder); on this project's local stack the H3 pipeline has **no audio** (audio VAE dropped) and cut timing can drift ±2 s.105- **H3 prompt rules are exacting.** `H3_VIDEO_PROMPT` must keep the FL2VA alignment line, `<d>[Language] …</d>` dialogue tags, and speaker `(S1)` IDs. See `docs/VIDEO_PROMPT_base-en.txt`.106- **Training-data provenance.** The SFT set was built from an internal 102-screenplay corpus + TVTropes metadata + hand-written examples. Review rights before commercial redistribution of generated content.107- The H3 prompt-field structure follows MiniMax's public H3 prompt guides; using it to generate videos is subject to the MiniMax H3 Community License Agreement.108 109## License110 111Adapter weights are Apache-2.0 (matching the Qwen3.5-0.8B base). Training data is from an internal screenplay corpus — see provenance note above.112