Add contextual VAD turn-event trainer

README.md

@@ -1,13 +1,15 @@
 ---
-title: Contextual Vad Turn Event Trainer
-emoji: 🐢
-colorFrom: yellow
-colorTo: purple
+title: Contextual VAD Turn Event Trainer
+colorFrom: blue
+colorTo: green
 sdk: gradio
-sdk_version: 6.14.0
-python_version: '3.13'
 app_file: app.py
 pinned: false
+license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Contextual VAD Turn Event Trainer
+
+Small CPU-friendly classifier for improving VAD events on top of an STT + LLM + TTS voice-agent pipeline.
+
+The Space trains a bootstrap model from synthetic event rows by default. Upload a CSV with the same feature schema and an `event_label` column to train on real call logs.

app.py

@@ -0,0 +1,257 @@
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+from typing import Any
+
+import gradio as gr
+from huggingface_hub import hf_hub_download
+
+from turn_event_model import (
+    DEFAULT_FEATURES,
+    EVENT_LABELS,
+    example_payload,
+    load_model,
+    predict_event,
+    push_model_to_hub,
+    train_turn_event_model,
+)
+
+
+MODEL_REPO_ID = os.environ.get("MODEL_REPO_ID", "somukandula/contextual-vad-turn-event-model")
+AUTO_TRAIN_ON_STARTUP = os.environ.get("AUTO_TRAIN_ON_STARTUP", "1") == "1"
+LOCAL_MODEL_DIR = Path("trained_model")
+LOCAL_MODEL_PATH = LOCAL_MODEL_DIR / "turn_event_model.joblib"
+
+MODEL = None
+STARTUP_STATUS = "Model not loaded yet."
+
+
+def try_download_model() -> bool:
+    global MODEL
+    try:
+        path = hf_hub_download(
+            repo_id=MODEL_REPO_ID,
+            filename="turn_event_model.joblib",
+            repo_type="model",
+        )
+        MODEL = load_model(path)
+        return True
+    except Exception:
+        return False
+
+
+def train_and_optionally_push(
+    csv_file: str | None = None,
+    n_samples: int = 12000,
+    model_repo_id: str = MODEL_REPO_ID,
+) -> tuple[str, dict[str, Any]]:
+    global MODEL
+    result = train_turn_event_model(
+        output_dir=LOCAL_MODEL_DIR,
+        csv_path=csv_file,
+        n_samples=int(n_samples),
+    )
+    MODEL = load_model(result.model_path)
+
+    hub_url = None
+    if os.environ.get("HF_TOKEN"):
+        hub_url = push_model_to_hub(result.output_dir, model_repo_id)
+
+    summary = {
+        "accuracy": result.metrics["accuracy"],
+        "n_rows": result.metrics["n_rows"],
+        "source": result.metrics["source"],
+        "model_repo": model_repo_id,
+        "hub_url": hub_url,
+    }
+    message = "Training complete."
+    if hub_url:
+        message += f" Pushed model to {hub_url}."
+    else:
+        message += " HF_TOKEN was not available, so the model stayed inside the Space runtime."
+    return message, summary
+
+
+def startup() -> None:
+    global MODEL, STARTUP_STATUS
+    if try_download_model():
+        STARTUP_STATUS = f"Loaded model from {MODEL_REPO_ID}."
+        return
+
+    if AUTO_TRAIN_ON_STARTUP:
+        message, summary = train_and_optionally_push(model_repo_id=MODEL_REPO_ID)
+        STARTUP_STATUS = f"{message} {json.dumps(summary)}"
+        return
+
+    STARTUP_STATUS = "No model found. Use Train to create one."
+
+
+def coerce_bool(value: bool) -> int:
+    return int(bool(value))
+
+
+def predict_from_controls(
+    vad_prob: float,
+    vad_active: bool,
+    speech_ms: float,
+    silence_ms: float,
+    energy: float,
+    stt_confidence: float,
+    stable_chars: float,
+    partial_chars: float,
+    stable_word_count: float,
+    words_since_pause: float,
+    ends_with_punctuation: bool,
+    ends_with_continuation: bool,
+    required_slots_filled: bool,
+    assistant_speaking: bool,
+    backchannel_like: bool,
+    tts_playback_ms: float,
+    tts_echo_risk: float,
+    time_since_user_started_ms: float,
+    time_since_assistant_started_ms: float,
+    recent_endpoint_candidate: bool,
+    expected_answer_type: str,
+) -> dict[str, Any]:
+    if MODEL is None:
+        return {"error": "Model is not loaded yet."}
+    payload = {
+        "vad_prob": vad_prob,
+        "vad_active": coerce_bool(vad_active),
+        "speech_ms": speech_ms,
+        "silence_ms": silence_ms,
+        "energy": energy,
+        "stt_confidence": stt_confidence,
+        "stable_chars": stable_chars,
+        "partial_chars": partial_chars,
+        "stable_word_count": stable_word_count,
+        "words_since_pause": words_since_pause,
+        "ends_with_punctuation": coerce_bool(ends_with_punctuation),
+        "ends_with_continuation": coerce_bool(ends_with_continuation),
+        "required_slots_filled": coerce_bool(required_slots_filled),
+        "assistant_speaking": coerce_bool(assistant_speaking),
+        "backchannel_like": coerce_bool(backchannel_like),
+        "tts_playback_ms": tts_playback_ms,
+        "tts_echo_risk": tts_echo_risk,
+        "time_since_user_started_ms": time_since_user_started_ms,
+        "time_since_assistant_started_ms": time_since_assistant_started_ms,
+        "recent_endpoint_candidate": coerce_bool(recent_endpoint_candidate),
+        "expected_answer_type": expected_answer_type,
+    }
+    return predict_event(MODEL, payload)
+
+
+def predict_from_json(payload_text: str) -> dict[str, Any]:
+    if MODEL is None:
+        return {"error": "Model is not loaded yet."}
+    try:
+        payload = json.loads(payload_text)
+    except json.JSONDecodeError as exc:
+        return {"error": f"Invalid JSON: {exc}"}
+    return predict_event(MODEL, payload)
+
+
+def train_from_upload(csv_file: str | None, n_samples: float, model_repo_id: str) -> tuple[str, dict[str, Any]]:
+    return train_and_optionally_push(
+        csv_file=csv_file,
+        n_samples=int(n_samples),
+        model_repo_id=model_repo_id.strip() or MODEL_REPO_ID,
+    )
+
+
+startup()
+
+with gr.Blocks() as demo:
+    gr.Markdown("# Contextual VAD Turn Event Model")
+    status = gr.Textbox(value=STARTUP_STATUS, label="Status", interactive=False)
+
+    with gr.Tab("Predict"):
+        with gr.Row():
+            with gr.Column():
+                vad_prob = gr.Slider(0, 1, value=0.91, step=0.01, label="VAD probability")
+                vad_active = gr.Checkbox(value=True, label="VAD active")
+                speech_ms = gr.Number(value=900, label="Speech ms")
+                silence_ms = gr.Number(value=0, label="Silence ms")
+                energy = gr.Slider(0, 1, value=0.82, step=0.01, label="Energy")
+                stt_confidence = gr.Slider(0, 1, value=0.84, step=0.01, label="STT confidence")
+                stable_chars = gr.Number(value=42, label="Stable chars")
+                partial_chars = gr.Number(value=52, label="Partial chars")
+                stable_word_count = gr.Number(value=8, label="Stable word count")
+                words_since_pause = gr.Number(value=6, label="Words since pause")
+            with gr.Column():
+                ends_with_punctuation = gr.Checkbox(value=False, label="Ends with punctuation")
+                ends_with_continuation = gr.Checkbox(value=False, label="Ends with continuation")
+                required_slots_filled = gr.Checkbox(value=False, label="Required slots filled")
+                assistant_speaking = gr.Checkbox(value=True, label="Assistant speaking")
+                backchannel_like = gr.Checkbox(value=False, label="Backchannel-like text")
+                tts_playback_ms = gr.Number(value=2300, label="TTS playback ms")
+                tts_echo_risk = gr.Slider(0, 1, value=0.12, step=0.01, label="TTS echo risk")
+                time_since_user_started_ms = gr.Number(value=900, label="User started ms ago")
+                time_since_assistant_started_ms = gr.Number(value=2300, label="Assistant started ms ago")
+                recent_endpoint_candidate = gr.Checkbox(value=False, label="Recent endpoint candidate")
+                expected_answer_type = gr.Dropdown(
+                    ["yes_no", "slot_fill", "open_ended", "confirmation"],
+                    value="open_ended",
+                    label="Expected answer type",
+                )
+
+        predict_button = gr.Button("Predict", variant="primary")
+        prediction = gr.JSON(label="Prediction")
+        predict_button.click(
+            fn=predict_from_controls,
+            inputs=[
+                vad_prob,
+                vad_active,
+                speech_ms,
+                silence_ms,
+                energy,
+                stt_confidence,
+                stable_chars,
+                partial_chars,
+                stable_word_count,
+                words_since_pause,
+                ends_with_punctuation,
+                ends_with_continuation,
+                required_slots_filled,
+                assistant_speaking,
+                backchannel_like,
+                tts_playback_ms,
+                tts_echo_risk,
+                time_since_user_started_ms,
+                time_since_assistant_started_ms,
+                recent_endpoint_candidate,
+                expected_answer_type,
+            ],
+            outputs=prediction,
+        )
+
+    with gr.Tab("JSON"):
+        payload = gr.Textbox(
+            value=json.dumps(example_payload(), indent=2),
+            lines=18,
+            label="Payload",
+        )
+        json_button = gr.Button("Predict JSON", variant="primary")
+        json_prediction = gr.JSON(label="Prediction")
+        json_button.click(fn=predict_from_json, inputs=payload, outputs=json_prediction)
+
+    with gr.Tab("Train"):
+        csv_upload = gr.File(label="Training CSV", file_types=[".csv"], type="filepath")
+        sample_count = gr.Number(value=12000, label="Synthetic rows")
+        repo_id = gr.Textbox(value=MODEL_REPO_ID, label="Model repo")
+        train_button = gr.Button("Train", variant="primary")
+        train_message = gr.Textbox(label="Training result", interactive=False)
+        train_metrics = gr.JSON(label="Metrics")
+        train_button.click(
+            fn=train_from_upload,
+            inputs=[csv_upload, sample_count, repo_id],
+            outputs=[train_message, train_metrics],
+        )
+
+
+if __name__ == "__main__":
+    demo.launch()
+

requirements.txt

@@ -0,0 +1,7 @@
+gradio>=4.44.0
+huggingface_hub>=0.24.0
+joblib>=1.3.0
+numpy>=1.24.0
+pandas>=2.0.0
+scikit-learn>=1.3.0
+

sample_training_schema.csv

@@ -0,0 +1,5 @@
+vad_prob,speech_ms,silence_ms,energy,stt_confidence,stable_chars,partial_chars,stable_word_count,words_since_pause,tts_playback_ms,tts_echo_risk,time_since_user_started_ms,time_since_assistant_started_ms,recent_endpoint_candidate,vad_active,ends_with_punctuation,ends_with_continuation,required_slots_filled,assistant_speaking,backchannel_like,expected_answer_type,event_label
+0.91,900,0,0.82,0.84,42,52,8,6,2300,0.12,900,2300,0,1,0,0,0,1,0,open_ended,interruption_confirmed
+0.08,2600,950,0.10,0.88,90,0,16,4,0,0,2600,0,0,0,1,0,1,0,0,slot_fill,turn_committed
+0.78,310,0,0.58,0.68,6,8,1,1,2200,0.20,310,2200,0,1,0,0,0,1,1,open_ended,backchannel_detected
+

turn_event_model.py

@@ -0,0 +1,524 @@
+from __future__ import annotations
+
+import json
+import math
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import joblib
+import numpy as np
+import pandas as pd
+from huggingface_hub import HfApi
+from sklearn.compose import ColumnTransformer
+from sklearn.impute import SimpleImputer
+from sklearn.linear_model import LogisticRegression
+from sklearn.metrics import accuracy_score, classification_report, confusion_matrix
+from sklearn.model_selection import train_test_split
+from sklearn.pipeline import Pipeline
+from sklearn.preprocessing import OneHotEncoder, StandardScaler
+
+
+EVENT_LABELS = [
+    "listening",
+    "speech_started",
+    "endpoint_candidate",
+    "turn_committed",
+    "user_resumed",
+    "interruption_started",
+    "interruption_confirmed",
+    "backchannel_detected",
+    "false_alarm",
+]
+
+NUMERIC_FEATURES = [
+    "vad_prob",
+    "speech_ms",
+    "silence_ms",
+    "energy",
+    "stt_confidence",
+    "stable_chars",
+    "partial_chars",
+    "stable_word_count",
+    "words_since_pause",
+    "tts_playback_ms",
+    "tts_echo_risk",
+    "time_since_user_started_ms",
+    "time_since_assistant_started_ms",
+    "recent_endpoint_candidate",
+    "vad_active",
+    "ends_with_punctuation",
+    "ends_with_continuation",
+    "required_slots_filled",
+    "assistant_speaking",
+    "backchannel_like",
+]
+
+CATEGORICAL_FEATURES = ["expected_answer_type"]
+FEATURE_COLUMNS = NUMERIC_FEATURES + CATEGORICAL_FEATURES
+
+DEFAULT_FEATURES: dict[str, Any] = {
+    "vad_prob": 0.0,
+    "speech_ms": 0.0,
+    "silence_ms": 0.0,
+    "energy": 0.0,
+    "stt_confidence": 0.0,
+    "stable_chars": 0.0,
+    "partial_chars": 0.0,
+    "stable_word_count": 0.0,
+    "words_since_pause": 0.0,
+    "tts_playback_ms": 0.0,
+    "tts_echo_risk": 0.0,
+    "time_since_user_started_ms": 0.0,
+    "time_since_assistant_started_ms": 0.0,
+    "recent_endpoint_candidate": 0,
+    "vad_active": 0,
+    "ends_with_punctuation": 0,
+    "ends_with_continuation": 0,
+    "required_slots_filled": 0,
+    "assistant_speaking": 0,
+    "backchannel_like": 0,
+    "expected_answer_type": "open_ended",
+}
+
+
+@dataclass
+class TrainResult:
+    model_path: str
+    output_dir: str
+    metrics: dict[str, Any]
+
+
+def clamp(value: float, low: float, high: float) -> float:
+    return float(max(low, min(high, value)))
+
+
+def jitter(rng: np.random.Generator, center: float, spread: float, low: float, high: float) -> float:
+    return clamp(rng.normal(center, spread), low, high)
+
+
+def randint(rng: np.random.Generator, low: int, high: int) -> int:
+    return int(rng.integers(low, high + 1))
+
+
+def chance(rng: np.random.Generator, p: float) -> int:
+    return int(rng.random() < p)
+
+
+def choice(rng: np.random.Generator, values: list[str]) -> str:
+    return str(rng.choice(values))
+
+
+def base_row(rng: np.random.Generator) -> dict[str, Any]:
+    return {
+        **DEFAULT_FEATURES,
+        "expected_answer_type": choice(
+            rng,
+            ["yes_no", "slot_fill", "open_ended", "confirmation"],
+        ),
+    }
+
+
+def row_for_label(label: str, rng: np.random.Generator) -> dict[str, Any]:
+    row = base_row(rng)
+
+    if label == "listening":
+        row.update(
+            vad_prob=jitter(rng, 0.12, 0.08, 0.0, 0.35),
+            vad_active=0,
+            silence_ms=jitter(rng, 120, 120, 0, 500),
+            energy=jitter(rng, 0.12, 0.08, 0, 0.35),
+            stt_confidence=jitter(rng, 0.05, 0.08, 0, 0.25),
+            assistant_speaking=chance(rng, 0.25),
+        )
+
+    elif label == "speech_started":
+        row.update(
+            vad_prob=jitter(rng, 0.82, 0.1, 0.55, 1.0),
+            vad_active=1,
+            speech_ms=jitter(rng, 95, 45, 20, 190),
+            silence_ms=jitter(rng, 0, 20, 0, 80),
+            energy=jitter(rng, 0.72, 0.15, 0.35, 1.0),
+            partial_chars=randint(rng, 0, 10),
+            stt_confidence=jitter(rng, 0.25, 0.15, 0, 0.55),
+            assistant_speaking=0,
+            time_since_user_started_ms=jitter(rng, 100, 45, 20, 200),
+        )
+
+    elif label == "endpoint_candidate":
+        continuation = chance(rng, 0.35)
+        row.update(
+            vad_prob=jitter(rng, 0.18, 0.1, 0.0, 0.45),
+            vad_active=0,
+            speech_ms=jitter(rng, 1800, 900, 350, 6000),
+            silence_ms=jitter(rng, 450, 180, 180, 900),
+            energy=jitter(rng, 0.18, 0.1, 0.0, 0.45),
+            stt_confidence=jitter(rng, 0.74, 0.12, 0.35, 0.97),
+            stable_chars=randint(rng, 12, 120),
+            partial_chars=randint(rng, 0, 40),
+            stable_word_count=randint(rng, 3, 24),
+            words_since_pause=randint(rng, 2, 12),
+            ends_with_punctuation=chance(rng, 0.35),
+            ends_with_continuation=continuation,
+            required_slots_filled=chance(rng, 0.45),
+            assistant_speaking=0,
+        )
+
+    elif label == "turn_committed":
+        answer_type = choice(rng, ["yes_no", "slot_fill", "confirmation", "open_ended"])
+        row.update(
+            expected_answer_type=answer_type,
+            vad_prob=jitter(rng, 0.08, 0.07, 0.0, 0.28),
+            vad_active=0,
+            speech_ms=jitter(rng, 2600, 1400, 250, 9000),
+            silence_ms=jitter(rng, 950, 330, 420, 2200),
+            energy=jitter(rng, 0.1, 0.07, 0.0, 0.28),
+            stt_confidence=jitter(rng, 0.88, 0.08, 0.6, 0.99),
+            stable_chars=randint(rng, 6 if answer_type == "yes_no" else 30, 180),
+            partial_chars=randint(rng, 0, 8),
+            stable_word_count=randint(rng, 1 if answer_type == "yes_no" else 6, 36),
+            words_since_pause=randint(rng, 1, 8),
+            ends_with_punctuation=chance(rng, 0.8),
+            ends_with_continuation=chance(rng, 0.04),
+            required_slots_filled=chance(rng, 0.85),
+            assistant_speaking=0,
+        )
+
+    elif label == "user_resumed":
+        row.update(
+            vad_prob=jitter(rng, 0.86, 0.09, 0.6, 1.0),
+            vad_active=1,
+            speech_ms=jitter(rng, 250, 150, 60, 850),
+            silence_ms=jitter(rng, 20, 25, 0, 100),
+            energy=jitter(rng, 0.76, 0.14, 0.4, 1.0),
+            stt_confidence=jitter(rng, 0.55, 0.2, 0.12, 0.9),
+            partial_chars=randint(rng, 4, 45),
+            stable_chars=randint(rng, 0, 35),
+            stable_word_count=randint(rng, 0, 8),
+            recent_endpoint_candidate=1,
+            assistant_speaking=0,
+        )
+
+    elif label == "interruption_started":
+        row.update(
+            vad_prob=jitter(rng, 0.82, 0.11, 0.55, 1.0),
+            vad_active=1,
+            speech_ms=jitter(rng, 170, 80, 60, 380),
+            silence_ms=jitter(rng, 0, 15, 0, 60),
+            energy=jitter(rng, 0.72, 0.16, 0.3, 1.0),
+            stt_confidence=jitter(rng, 0.32, 0.18, 0.0, 0.7),
+            partial_chars=randint(rng, 0, 25),
+            stable_chars=randint(rng, 0, 10),
+            tts_playback_ms=jitter(rng, 1800, 1000, 200, 8000),
+            tts_echo_risk=jitter(rng, 0.22, 0.15, 0, 0.55),
+            assistant_speaking=1,
+            time_since_assistant_started_ms=jitter(rng, 1800, 1000, 200, 8000),
+        )
+
+    elif label == "interruption_confirmed":
+        row.update(
+            vad_prob=jitter(rng, 0.91, 0.07, 0.68, 1.0),
+            vad_active=1,
+            speech_ms=jitter(rng, 1050, 550, 420, 3600),
+            silence_ms=jitter(rng, 0, 20, 0, 80),
+            energy=jitter(rng, 0.82, 0.12, 0.45, 1.0),
+            stt_confidence=jitter(rng, 0.8, 0.12, 0.45, 0.99),
+            partial_chars=randint(rng, 12, 140),
+            stable_chars=randint(rng, 10, 120),
+            stable_word_count=randint(rng, 2, 24),
+            words_since_pause=randint(rng, 1, 12),
+            tts_playback_ms=jitter(rng, 2400, 1400, 250, 10000),
+            tts_echo_risk=jitter(rng, 0.16, 0.12, 0, 0.45),
+            assistant_speaking=1,
+            backchannel_like=chance(rng, 0.05),
+            time_since_assistant_started_ms=jitter(rng, 2400, 1400, 250, 10000),
+        )
+
+    elif label == "backchannel_detected":
+        row.update(
+            vad_prob=jitter(rng, 0.78, 0.11, 0.5, 1.0),
+            vad_active=1,
+            speech_ms=jitter(rng, 310, 160, 80, 900),
+            silence_ms=jitter(rng, 0, 20, 0, 80),
+            energy=jitter(rng, 0.58, 0.17, 0.25, 1.0),
+            stt_confidence=jitter(rng, 0.68, 0.17, 0.25, 0.96),
+            stable_chars=randint(rng, 2, 12),
+            partial_chars=randint(rng, 0, 18),
+            stable_word_count=randint(rng, 1, 3),
+            words_since_pause=randint(rng, 1, 3),
+            tts_playback_ms=jitter(rng, 2200, 1400, 250, 9000),
+            tts_echo_risk=jitter(rng, 0.2, 0.15, 0, 0.55),
+            assistant_speaking=1,
+            backchannel_like=1,
+        )
+
+    elif label == "false_alarm":
+        row.update(
+            vad_prob=jitter(rng, 0.62, 0.18, 0.25, 0.95),
+            vad_active=chance(rng, 0.75),
+            speech_ms=jitter(rng, 90, 80, 0, 260),
+            silence_ms=jitter(rng, 20, 40, 0, 150),
+            energy=jitter(rng, 0.48, 0.22, 0.05, 0.95),
+            stt_confidence=jitter(rng, 0.1, 0.1, 0, 0.35),
+            stable_chars=randint(rng, 0, 4),
+            partial_chars=randint(rng, 0, 8),
+            stable_word_count=0,
+            tts_playback_ms=jitter(rng, 1600, 1400, 0, 8000),
+            tts_echo_risk=jitter(rng, 0.82, 0.14, 0.45, 1.0),
+            assistant_speaking=chance(rng, 0.8),
+        )
+
+    row["event_label"] = label
+    return row
+
+
+def generate_synthetic_dataset(n_samples: int = 12000, seed: int = 7) -> pd.DataFrame:
+    rng = np.random.default_rng(seed)
+    weights = np.array([0.22, 0.08, 0.14, 0.16, 0.08, 0.08, 0.09, 0.08, 0.07])
+    labels = rng.choice(EVENT_LABELS, size=n_samples, p=weights / weights.sum())
+    rows = [row_for_label(str(label), rng) for label in labels]
+    return pd.DataFrame(rows)
+
+
+def coerce_schema(df: pd.DataFrame) -> pd.DataFrame:
+    out = df.copy()
+    for column, default in DEFAULT_FEATURES.items():
+        if column not in out.columns:
+            out[column] = default
+    for column in NUMERIC_FEATURES:
+        out[column] = pd.to_numeric(out[column], errors="coerce").fillna(DEFAULT_FEATURES[column])
+    out["expected_answer_type"] = out["expected_answer_type"].fillna("open_ended").astype(str)
+    return out
+
+
+def build_pipeline() -> Pipeline:
+    numeric_pipeline = Pipeline(
+        steps=[
+            ("imputer", SimpleImputer(strategy="median")),
+            ("scaler", StandardScaler()),
+        ]
+    )
+    categorical_pipeline = Pipeline(
+        steps=[
+            ("imputer", SimpleImputer(strategy="most_frequent")),
+            ("onehot", OneHotEncoder(handle_unknown="ignore")),
+        ]
+    )
+    preprocessor = ColumnTransformer(
+        transformers=[
+            ("num", numeric_pipeline, NUMERIC_FEATURES),
+            ("cat", categorical_pipeline, CATEGORICAL_FEATURES),
+        ]
+    )
+    classifier = LogisticRegression(
+        max_iter=1200,
+        class_weight="balanced",
+        n_jobs=1,
+    )
+    return Pipeline(steps=[("preprocess", preprocessor), ("classifier", classifier)])
+
+
+def split_train_test(df: pd.DataFrame) -> tuple[pd.DataFrame, pd.DataFrame, pd.Series, pd.Series]:
+    x = df[FEATURE_COLUMNS]
+    y = df["event_label"].astype(str)
+    try:
+        return train_test_split(x, y, test_size=0.2, random_state=42, stratify=y)
+    except ValueError:
+        return train_test_split(x, y, test_size=0.2, random_state=42)
+
+
+def train_turn_event_model(
+    output_dir: str | Path = "trained_model",
+    csv_path: str | Path | None = None,
+    n_samples: int = 12000,
+    seed: int = 7,
+) -> TrainResult:
+    output = Path(output_dir)
+    output.mkdir(parents=True, exist_ok=True)
+
+    if csv_path:
+        df = pd.read_csv(csv_path)
+        if "event_label" not in df.columns:
+            raise ValueError("Training CSV must contain an event_label column.")
+        source = f"uploaded_csv:{Path(csv_path).name}"
+    else:
+        df = generate_synthetic_dataset(n_samples=n_samples, seed=seed)
+        source = f"synthetic_bootstrap:n={n_samples}:seed={seed}"
+
+    df = coerce_schema(df)
+    df = df[df["event_label"].isin(EVENT_LABELS)].copy()
+    if df.empty:
+        raise ValueError("No usable training rows after schema coercion.")
+
+    x_train, x_test, y_train, y_test = split_train_test(df)
+    model = build_pipeline()
+    model.fit(x_train, y_train)
+
+    y_pred = model.predict(x_test)
+    labels_in_test = sorted(set(y_test) | set(y_pred))
+    report = classification_report(
+        y_test,
+        y_pred,
+        labels=labels_in_test,
+        output_dict=True,
+        zero_division=0,
+    )
+    matrix = confusion_matrix(y_test, y_pred, labels=labels_in_test).tolist()
+    metrics = {
+        "accuracy": float(accuracy_score(y_test, y_pred)),
+        "n_rows": int(len(df)),
+        "n_train": int(len(x_train)),
+        "n_test": int(len(x_test)),
+        "source": source,
+        "labels": labels_in_test,
+        "classification_report": report,
+        "confusion_matrix": matrix,
+    }
+
+    model_path = output / "turn_event_model.joblib"
+    joblib.dump(model, model_path)
+    (output / "feature_schema.json").write_text(
+        json.dumps(
+            {
+                "feature_columns": FEATURE_COLUMNS,
+                "numeric_features": NUMERIC_FEATURES,
+                "categorical_features": CATEGORICAL_FEATURES,
+                "default_features": DEFAULT_FEATURES,
+                "event_labels": EVENT_LABELS,
+            },
+            indent=2,
+        )
+    )
+    (output / "metrics.json").write_text(json.dumps(metrics, indent=2))
+    (output / "example_payload.json").write_text(json.dumps(example_payload(), indent=2))
+    (output / "README.md").write_text(model_card(metrics))
+
+    return TrainResult(str(model_path), str(output), metrics)
+
+
+def model_card(metrics: dict[str, Any]) -> str:
+    accuracy = metrics.get("accuracy", 0.0)
+    source = metrics.get("source", "unknown")
+    return f"""---
+library_name: scikit-learn
+tags:
+- voice-agent
+- vad
+- turn-taking
+- tabular-classification
+- generated_from_trainer
+license: mit
+---
+
+# Contextual VAD Turn Event Model
+
+This is a small scikit-learn classifier that predicts higher-level voice-agent events from derived VAD, STT, TTS, and dialogue-state features.
+
+It is designed to sit on top of a streaming STT + LLM + TTS pipeline and produce probabilities for:
+
+- `listening`
+- `speech_started`
+- `endpoint_candidate`
+- `turn_committed`
+- `user_resumed`
+- `interruption_started`
+- `interruption_confirmed`
+- `backchannel_detected`
+- `false_alarm`
+
+Training source: `{source}`
+
+Validation accuracy: `{accuracy:.4f}`
+
+## Intended use
+
+Use this as a bootstrap policy model. Replace the synthetic bootstrap data with real call-frame logs before production use.
+
+## Files
+
+- `turn_event_model.joblib`: scikit-learn pipeline.
+- `feature_schema.json`: feature names and defaults.
+- `metrics.json`: validation metrics.
+- `example_payload.json`: one valid inference payload.
+"""
+
+
+def example_payload() -> dict[str, Any]:
+    payload = DEFAULT_FEATURES.copy()
+    payload.update(
+        {
+            "vad_prob": 0.91,
+            "vad_active": 1,
+            "speech_ms": 900,
+            "silence_ms": 0,
+            "energy": 0.82,
+            "stt_confidence": 0.84,
+            "stable_chars": 42,
+            "partial_chars": 52,
+            "stable_word_count": 8,
+            "words_since_pause": 6,
+            "assistant_speaking": 1,
+            "tts_playback_ms": 2300,
+            "tts_echo_risk": 0.12,
+            "time_since_assistant_started_ms": 2300,
+            "expected_answer_type": "open_ended",
+        }
+    )
+    return payload
+
+
+def load_model(model_path: str | Path) -> Pipeline:
+    return joblib.load(model_path)
+
+
+def normalize_payload(payload: dict[str, Any]) -> pd.DataFrame:
+    row = DEFAULT_FEATURES.copy()
+    row.update({k: v for k, v in payload.items() if v is not None})
+    for key in NUMERIC_FEATURES:
+        value = row.get(key, DEFAULT_FEATURES[key])
+        if isinstance(value, bool):
+            row[key] = int(value)
+        else:
+            try:
+                number = float(value)
+                row[key] = 0.0 if math.isnan(number) else number
+            except (TypeError, ValueError):
+                row[key] = DEFAULT_FEATURES[key]
+    row["expected_answer_type"] = str(row.get("expected_answer_type", "open_ended"))
+    return pd.DataFrame([row])[FEATURE_COLUMNS]
+
+
+def predict_event(model: Pipeline, payload: dict[str, Any]) -> dict[str, Any]:
+    x = normalize_payload(payload)
+    classes = list(model.classes_)
+    probabilities = model.predict_proba(x)[0]
+    ranked = sorted(
+        [
+            {"event": str(label), "probability": float(prob)}
+            for label, prob in zip(classes, probabilities)
+        ],
+        key=lambda item: item["probability"],
+        reverse=True,
+    )
+    return {
+        "event": ranked[0]["event"],
+        "confidence": ranked[0]["probability"],
+        "probabilities": ranked,
+    }
+
+
+def push_model_to_hub(output_dir: str | Path, model_repo_id: str) -> str:
+    token = os.environ.get("HF_TOKEN")
+    if not token:
+        raise RuntimeError("HF_TOKEN is required to push the trained model to the Hub.")
+    api = HfApi(token=token)
+    api.create_repo(repo_id=model_repo_id, repo_type="model", exist_ok=True)
+    api.upload_folder(
+        folder_path=str(output_dir),
+        repo_id=model_repo_id,
+        repo_type="model",
+        commit_message="Train contextual VAD turn-event model",
+    )
+    return f"https://huggingface.co/{model_repo_id}"
+