kintsugi-rad, documented

What it is. Kintsugi Health R&D code that predicts depression (PHQ-9, 0–27) and anxiety (GAD-7, 0–21) from speech. One Whisper-based model scores 30 s audio windows; a CORAL ordinal loss, threshold tuning and Sn/Sp metrics with an indeterminate band sit on top. kirad/ is the library, research/stable/*/ holds the three model versions (DAM 1, 2, 3), scripts/launcher.py runs everything from one YAML. This copy is documented for retraining on data from Congo, Colombia, Jordan and Ukraine.

How to read this site.

You want	Go to
Follow one train run, function by function, with what goes in and out	Walkthrough
Each stage as a numbered path, with side paths	Code map
Every function of a file: calls / called by	Files
What the CSV, WAVs and batches must look like	Data contract
Architecture, CORAL loss, thresholds, metrics	Model, loss, metrics
DAM 1 vs 2 vs 3 and their hyperparameters	Experiments
Every fixed value in the code	Hardcoded values
What blocks a run today, English-only assumptions	Limitations
Signatures and full docstrings	API reference (left menu)

Every box and every function name links to its line in the code. Box descriptions are the first line of each docstring, read at build time: to change them, edit the code.

Stages, in execution order

flowchart LR st_prep["<b>0 · Before training (optional)</b><br/>run_whisper_asr.py<br/><i>optional</i>"] class st_prep opt click st_prep "code-map/#stage-prep" st_launch["<b>1 · Launch</b><br/>launcher.py ·<br/>launcher_utils.py ·<br/>utils.py<br/><i>steps 1–14</i>"] class st_launch main click st_launch "code-map/#stage-launch" st_data["<b>2 · Data</b><br/>datasets_and_dataloaders.py<br/>· dataset_utils.py ·<br/>augmentations.py ·<br/>constants.py<br/><i>steps 15–24</i>"] class st_data main st_launch ==> st_data click st_data "code-map/#stage-data" st_model["<b>3 · Model (DAM 1)</b><br/>mtl_mar_2024/model.py ·<br/>feature_extraction_whisper.py<br/>· base_models.py ·<br/>constants.py<br/><i>steps 25–31</i>"] class st_model main st_data ==> st_model click st_model "code-map/#stage-model" st_loss["<b>4 · Loss</b><br/>base_models.py · losses.py<br/>· utils.py<br/><i>steps 32–35</i>"] class st_loss main st_model ==> st_loss click st_loss "code-map/#stage-loss" st_metrics["<b>5 · Thresholds and metrics</b><br/>base_models.py ·<br/>ordinal_thresholding.py ·<br/>metrics.py<br/><i>steps 36–41</i>"] class st_metrics main st_loss ==> st_metrics click st_metrics "code-map/#stage-metrics" st_outputs["<b>6 · Outputs and analysis</b><br/>launcher_utils.py ·<br/>launcher.py · utils.py ·<br/>plotting.py<br/><i>steps 42–44</i>"] class st_outputs main st_metrics ==> st_outputs click st_outputs "code-map/#stage-outputs" st_variants["<b>7 · The other versions (DAM 2, DAM 3)</b><br/>mtl_jun_2024/model.py ·<br/>mtl_aug_2024/model.py ·<br/>base_models.py<br/><i>optional</i>"] class st_variants opt st_outputs -.-> st_variants click st_variants "code-map/#stage-variants" classDef main fill:#FFF4DC,stroke:#A67C1B,stroke-width:2px,color:#1A1A1A classDef opt fill:#F3F4F6,stroke:#B8BEC7,color:#555,stroke-dasharray:4 3 classDef edge fill:#FFFFFF,stroke:#1F7A5C,color:#1F7A5C,stroke-width:1.5px

Quick start

pip install -e .                    # env: envs/kipy-gpu-full.yaml
# 1. scripts/launcher.py: set wandb_entity / wandb_project (L172-173), drop "kipy" (L255)
# 2. edit research/stable/ordinal_regression_mtl_mar_2024/config.yaml (DAM 1), or a copy in the
#    same folder (or pass --experiment-dir), and set, per split,
#    df_or_dataset_version: <split>.csv and audio_root: <dir>; remove merge_rows_by_subject
python scripts/launcher.py train research/stable/ordinal_regression_mtl_mar_2024/config.yaml

Minimal data: train.csv, val.csv, test.csv with uuid, filename, phq, gad and a duration column in seconds (set duration_column; the config uses prompt_vad_trimmed_duration for train, prompt_vad_cut_duration for val/test), plus <audio_root>/<filename>.wav at 16 kHz, ≥ 30 s after VAD. W&B login is required. Details: Data contract, blockers: Limitations.