feat: add executable CosyVoice lifecycle (#11)

Author: cheeweijie

.github/workflows/instavar-voice-contract.yml

@@ -17,7 +17,7 @@ jobs:
         uses: actions/checkout@v5
         with:
           repository: instavar/instavar-voice-evaluation
-          ref: 56b32c954e950fe915d4c6595c0630985576a9b7
+          ref: d63ab559a8e0592bd373f9b51421040b540fb2b7
           path: .instavar-voice-evaluation
       - uses: actions/setup-python@v6
         with:
@@ -26,3 +26,7 @@ jobs:
         run: python .instavar-voice-evaluation/main.py validate-repository "$GITHUB_WORKSPACE"
       - name: Validate historical run evidence
         run: python .instavar-voice-evaluation/main.py validate historical historical-run.json
+      - name: Validate executable lifecycle backend
+        run: python .instavar-voice-evaluation/main.py validate-backend instavar-voice-backend.json
+      - name: Test lifecycle wrapper without model dependencies
+        run: python -m unittest tests/test_lifecycle_backend.py -v

INSTAVAR_VOICE_CONFORMANCE.md

@@ -1,6 +1,8 @@
 # Instavar Voice conformance
 
-This repository declares its model-specific adaptation and runtime surface in `instavar-voice-capabilities.json`. The manifest uses the public [Instavar Voice evaluation contract](https://github.com/instavar/instavar-voice-evaluation) pinned by CI to merge commit `56b32c954e950fe915d4c6595c0630985576a9b7`.
+This repository declares its model-specific adaptation and runtime surface in `instavar-voice-capabilities.json`. The manifest and executable [`instavar-voice-backend.json`](instavar-voice-backend.json) PyTorch LoRA recipe use the public [Instavar Voice evaluation contract](https://github.com/instavar/instavar-voice-evaluation) pinned by CI to merge commit `d63ab559a8e0592bd373f9b51421040b540fb2b7`.
+
+The executable recipe proves that the external CosyVoice checkout equals its recorded upstream revision plus exactly the companion patch set. It applies explicit `MAX_EPOCH` and `LEARNING_RATE` values after loading the full model graph, audits grouped splits, selects one safe adapter, reloads it in a fresh process, evaluates the frozen plan, and packages evidence. A DeepSpeed run must use the same learning rate in its JSON optimizer configuration. The merged vLLM path remains outside this PyTorch lifecycle and needs a separate matched equivalence run.
 
 Capability schema 1.2 records each LoRA lifecycle stage separately and preserves the six invalid emotion-control rows as a negative lifecycle result. It also names the exact blockers for a matched base-model comparison.
 

README.md

@@ -186,6 +186,28 @@ The upstream `cosyvoice3.yaml` sets `max_epoch: 200`. If you pass a custom confi
 
 ## Evaluation
 
+### Executable Instavar Voice lifecycle
+
+[`instavar-voice-backend.json`](instavar-voice-backend.json) binds the PyTorch
+LoRA path to a five-stage executable recipe. Preflight verifies that the
+external CosyVoice checkout equals its recorded upstream commit plus exactly
+the four companion patches. The trainer now accepts explicit `--max_epoch` and
+`--learning_rate` overrides after loading the full HyperPyYAML model graph. The
+lifecycle requires both values, preventing the earlier 20-versus-200 epoch
+mismatch and an implicit optimizer-rate mismatch from recurring silently. For
+DeepSpeed, the JSON optimizer rate must equal `LEARNING_RATE`.
+Set `DEEPSPEED_CONFIG` only when `TRAIN_ENGINE=deepspeed`; the PyTorch DDP path
+does not require it.
+
+The lifecycle audits grouped raw splits, writes model output under its unique
+work directory, promotes only one exact adapter directory, strips optimizer
+state from the inference package, reloads in a fresh process, runs the frozen
+evaluation plan, and packages provenance. Validate it with evaluator merge
+`d63ab559a8e0592bd373f9b51421040b540fb2b7`. Use the companion tools directly;
+do not copy them into the external checkout, because unexpected checkout files
+fail provenance verification. A pass covers the PyTorch adapter path only. The
+merged vLLM path still requires a separate matched equivalence lifecycle.
+
 ### Frozen multi-prompt runtime evaluation
 
 Use `tools/run_evaluation_suite.py` to execute a complete Instavar Voice plan

instavar-voice-backend.json

@@ -0,0 +1,50 @@
+{
+  "schema_version": "1.2.0",
+  "backend_id": "cosyvoice3-lora-pytorch",
+  "capability_binding": {
+    "manifest": "instavar-voice-capabilities.json",
+    "adaptation": "lora",
+    "runtime_ids": ["pytorch"]
+  },
+  "required_environment": [
+    { "name": "COSYVOICE_DIR", "purpose": "Pinned CosyVoice checkout with the exact companion patch set applied." },
+    { "name": "PRETRAINED_DIR", "purpose": "Pinned local Fun-CosyVoice3-0.5B runtime model directory." },
+    { "name": "BASE_LLM_CHECKPOINT", "purpose": "Pinned base llm.pt used to initialize LoRA training." },
+    { "name": "QWEN_PRETRAIN_DIR", "purpose": "Pinned CosyVoice-BlankEN tokenizer and configuration directory." },
+    { "name": "TRAIN_CONFIG", "purpose": "CosyVoice3 HyperPyYAML training configuration." },
+    { "name": "MAX_EPOCH", "purpose": "Explicit positive train_conf.max_epoch override applied after loading the full model config." },
+    { "name": "LEARNING_RATE", "purpose": "Explicit positive LoRA optimizer learning rate." },
+    { "name": "TRAIN_DATA_LIST", "purpose": "Prepared CosyVoice parquet training data list." },
+    { "name": "CV_DATA_LIST", "purpose": "Prepared CosyVoice parquet cross-validation data list." },
+    { "name": "RAW_TRAIN_JSONL", "purpose": "Raw training split used for grouped corpus audit." },
+    { "name": "RAW_VALIDATION_JSONL", "purpose": "Raw validation split used for grouped corpus audit." },
+    { "name": "RAW_TEST_JSONL", "purpose": "Raw test split used for grouped corpus audit." },
+    { "name": "REFERENCE_AUDIO", "purpose": "Authorized reference-speaker audio for reload and held-out synthesis." },
+    { "name": "REFERENCE_TEXT", "purpose": "Transcript matching the authorized reference audio." },
+    { "name": "SELECTED_ADAPTER_NAME", "purpose": "Single safe LoRA checkpoint directory selected for reload." },
+    { "name": "GENERATION_PLAN", "purpose": "Frozen Instavar Voice generation plan containing this candidate." },
+    { "name": "CANDIDATE_ID", "purpose": "Candidate identifier present in the frozen generation plan." },
+    { "name": "TRAIN_ENGINE", "purpose": "Explicit torch_ddp or deepspeed training engine." }
+  ],
+  "commands": {
+    "preflight": ["{python}", "scripts/instavar_voice_lifecycle.py", "preflight"],
+    "train": ["{python}", "scripts/instavar_voice_lifecycle.py", "train"],
+    "infer": ["{python}", "scripts/instavar_voice_lifecycle.py", "infer"],
+    "evaluate": ["{python}", "scripts/instavar_voice_lifecycle.py", "evaluate"],
+    "package": ["{python}", "scripts/instavar_voice_lifecycle.py", "package"]
+  },
+  "expected_artifacts": {
+    "preflight": ["preflight/preflight.json"],
+    "train": ["train/selected-adapter.tar"],
+    "infer": ["infer/candidate.wav"],
+    "evaluate": ["evaluate/evaluation-bundle.tar"],
+    "package": ["package/adapter-package.tar"]
+  },
+  "timeout_seconds": {
+    "preflight": 1800,
+    "train": 86400,
+    "infer": 3600,
+    "evaluate": 21600,
+    "package": 1800
+  }
+}