scribe/training/README.md

CarePath Scribe research pipeline

This package is the training-to-private-staging path for Vietnamese medical transcription and grounded SOAP notes. It is research-only: it does not change the production provider, persist CarePath consultation audio, or authorize a model for clinical use.

Start with the evidence and limitations in ../research/README.md. The five generated Colab notebooks are documented in notebooks/README.md.

Pipeline

1. Validate data rights, immutable source revisions, split fingerprints, and frozen manifests.
2. Benchmark the current single-best Gipformer output and direct PhoWhisper LoRA on untouched ViMedCSS evaluation splits. The near-miss contract is recorded, but its sequence-ranking trainer remains fail-closed after the plain LoRA gate instead of approximating the paper with non-equivalent hypotheses or loss.
3. Compare Gipformer alone, real-error GEC with lexical RAC, and GEC with a balanced clean/PiDA-style phonetic mixture. TTS remains locked until the text-only candidate passes.
4. Translate/adapt MTS-Dialog and ACI-BENCH training rows with the deterministic CKey teacher, reject ungrounded rows, and train one Qwen3-4B QLoRA adapter for fact extraction and grounded SOAP writing.
5. Evaluate critical facts and frozen safety cases, assemble independently accepted transcript and SOAP components, reload the bundle with FastAPI TestClient, and optionally upload it to a private Hugging Face model repo.

Candidate metrics and mock smoke results are evidence about orchestration only. They are never substituted for real Colab WER, PIER, latency, VRAM, or model quality evidence.

Colab setup

Use a private Colab notebook with a GPU runtime. Add these values through Colab Secrets and enable notebook access for each secret:

• GITHUB_TOKEN: read access to the private CarePath repository.
• LLM_API_KEY: CKey access for paid SOAP data preparation and the independent teacher baseline.
• HF_TOKEN: access to the destination private Hugging Face model repository.

Do not place tokens in CAREPATH_REPO_URL, notebook source, output cells, or Git remote URLs. The bootstrap uses GIT_ASKPASS and keeps public research audio in the ephemeral /content cache. Checkpoints and accepted text/model artifacts go to MyDrive/carepath_artifacts/.

The owner approved the listed public datasets for private research-only use on 2026-07-13. ViMedCSS, VietMed, MTS-Dialog, ACI-BENCH, MedEV, and the Qwen base model are pinned to exact revisions and hashes. Notebook 00 re-verifies those locks and prepares the public SOAP text under ephemeral /content/carepath_data; source drift fails closed. This approval does not cover patient data, clinical use, production, commercial promotion, or the unresolved MedEV repository license.

Select a profile before running the notebooks in numeric order:

import os

os.environ["CAREPATH_PROFILE"] = "pilot"  # smoke, pilot, research-full, replicate
os.environ["CAREPATH_CONFIRM_PAID"] = "1"
os.environ["CAREPATH_QLORA_BACKEND"] = "unsloth"  # default; use "hf" explicitly

smoke is the default and needs no paid confirmation. reproduction is a separate paper-ablation profile; it additionally requires accepted PiDA evidence and explicit reproduction confirmation before synthetic/TTS work. Its near-miss stage currently exits with a structured not_implemented blocker if the plain LoRA gate passes; it never claims a contrastive result.

QLoRA backend and dependency boundary

CAREPATH_QLORA_BACKEND accepts exactly unsloth or hf. Real paid GEC and SOAP QLoRA default to unsloth; hf is the explicit reference-backend opt-out. Invalid values fail immediately. An Unsloth import, setup, resume, or training failure also fails the selected run instead of silently retrying with HF, so the recorded backend and timing remain trustworthy. Mock training remains lightweight and does not require the fast stack.

The optional training-fast extra pins unsloth==2026.7.2, unsloth-zoo==2026.7.2, transformers==4.56.2, trl==0.22.2, and datasets[audio]==4.3.0. These packages move together at the trainer/model boundary, so exact pins avoid an unreviewed compatibility combination. They are not runtime dependencies: only paid QLoRA cells in notebooks 02 and 03 install the extra. The normal training extra remains sufficient for mock/CPU work and notebooks 00, 01, and 04. The reproduction profile still adds training-tts.

Local proof

Run local checks with the repository Python 3.12 environment:

.\.venv\Scripts\python.exe scribe/research/download_papers.py --check
.\.venv\Scripts\python.exe -m pytest scribe/training/tests
.\.venv\Scripts\python.exe scribe/training/scripts/build_notebooks.py --check
.\.venv\Scripts\python.exe scribe/training/scripts/baseline_report.py --check
.\.venv\Scripts\python.exe scribe/training/scripts/run_pipeline.py --config scribe/training/configs/smoke-v2.json --stage all
.\.venv\Scripts\python.exe scribe/training/scripts/run_soap_pipeline.py --config scribe/training/configs/soap-smoke-v1.json --stage all

The smoke profile uses frozen synthetic fixtures and mock adapters. Mock artifacts are deliberately refused by the serving-bundle exporters.

Owner L4 acceptance (pending)

Run the following proof separately for GEC and SOAP; local mock checks cannot satisfy it:

1. Make two temporary 20-step configs that differ only in run/output identity.
2. On the same Colab L4, run one with CAREPATH_QLORA_BACKEND=hf and one with CAREPATH_QLORA_BACKEND=unsloth. Keep the input rows and order, exact base revision, seed, batch size, gradient accumulation, sequence length, dtype, and runtime image fixed.
3. Record GPU identity, runtime image, wall time, steps/second, peak VRAM, exact package versions, and SHA-256 hashes for the config, data manifest, checkpoints, saved adapter, and generated training_run.json. For fixed 20-step runs, calculate ((unsloth_steps_per_second / hf_steps_per_second) - 1) * 100; both GEC and SOAP must be at least 20%.
4. Start a fresh L4 runtime, reinstall the pinned extras, load each saved Unsloth adapter from Drive without the original trainer object, and run the existing prediction/evaluation stage.
5. For each task, run long enough to write a checkpoint, interrupt the runtime, reconnect, and verify the same backend resumes from the latest checkpoint without changing the locked base revision.

Keep the benchmark logs, adapter-reload output, and before/after checkpoint paths with the story validation record. Until they are recorded, acceleration, reload, and resume platform proof remain pending.

Private upload

Notebook 04 assembles and stages only components that independently passed their gates. Publishing remains a separate, explicit action:

python scribe/training/scripts/publish_scribe_bundle.py `
  --bundle /content/drive/MyDrive/carepath_artifacts/<run-id>/accepted_scribe_bundle `
  --repo-id tranth3truong/carepath-scribe-research `
  --confirm-private-upload

The uploader verifies the research bundle and refuses a public destination. Production promotion still requires a separate data-rights decision, qualified Vietnamese clinician review, and an explicit rollout decision.