@they-juanreina/compost-cli 0.1.1 → 0.1.3

package/transcriber/app/pipeline.py

@@ -0,0 +1,210 @@
+"""Transcription pipeline orchestrator (#v0.1-01).
+
+Composes the already-tested deterministic stages into a single transcript.json:
+
+    duration probe → VAD speech/silences → ASR → diarization align →
+    cue parser → silence typer → prosody → final transcript
+
+Each stage accepts injectable backends so the route, the worker, and the tests
+all share one orchestration codepath. The route in `routes/transcribe.py`
+provides real backends; tests pass fakes.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .asr import ASRConfig, Transcriber, WhisperBackend
+from .cue_parser import parse_transcript_cues
+from .diarization import DiarizationBackend, Diarizer, align
+from .prosody import annotate_prosody
+from .silence_typer import type_all_silences
+from .vad import VAD, VADBackend, silences_to_schema, utterance_energies
+
+SCHEMA_VERSION = "1.0"
+DEFAULT_TRANSCRIBER_VERSION = "compost-transcriber@0.1.0"
+
+
+@dataclass
+class PipelineConfig:
+    asr: ASRConfig
+    transcriber_version: str = DEFAULT_TRANSCRIBER_VERSION
+    asr_model_tag: str = "whisper-large-v3-turbo-event-tags"
+    diarizer_tag: str = "pyannote-audio@3.3"
+    vad_tag: str = "silero-vad@5.0"
+
+
+@dataclass
+class PipelineBackends:
+    """Inject concrete or fake backends. Route wires real ones; tests inject fakes."""
+
+    vad: VADBackend | None = None
+    asr: WhisperBackend | None = None
+    diarization: DiarizationBackend | None = None
+
+
+def probe_duration_ms(source_path: str) -> int:
+    """Return the duration of an audio/video file in milliseconds via ffprobe.
+
+    Falls back to 0 if ffprobe is missing or the file is unreadable; the caller
+    can decide whether to error or proceed (silence segmentation against
+    duration=0 produces no trailing silence, which is fine).
+    """
+    try:
+        result = subprocess.run(
+            [
+                "ffprobe",
+                "-v",
+                "error",
+                "-show_entries",
+                "format=duration",
+                "-of",
+                "default=noprint_wrappers=1:nokey=1",
+                source_path,
+            ],
+            capture_output=True,
+            text=True,
+            timeout=30,
+            check=False,
+        )
+        if result.returncode != 0:
+            return 0
+        return int(float(result.stdout.strip()) * 1000)
+    except (FileNotFoundError, ValueError, subprocess.TimeoutExpired):
+        return 0
+
+
+def _speakers_from_utterances(utterances: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Distinct speakers seen in the utterances; first speaker tagged as moderator,
+    the rest as participants (researcher overrides this in the UI for now).
+    """
+    seen: dict[str, dict[str, Any]] = {}
+    for u in utterances:
+        sid = u.get("speaker_id", "S?")
+        if sid in seen:
+            continue
+        seen[sid] = {"id": sid, "name": sid, "type": "participant"}
+    # First seen → moderator by convention. Researcher can override post-hoc.
+    if seen:
+        first = next(iter(seen))
+        seen[first]["type"] = "moderator"
+    return list(seen.values())
+
+
+def _detect_language(asr_lang: str | None, configured: str | None) -> str:
+    """Prefer ASR-detected, then configured hint, then 'und' (undetermined)."""
+    if asr_lang:
+        return asr_lang
+    if configured:
+        return configured
+    return "und"
+
+
+def run_pipeline(
+    seed_path: str,
+    session_id: str,
+    source_path: str,
+    config: PipelineConfig,
+    backends: PipelineBackends,
+) -> dict[str, Any]:
+    """Run every stage and return the final transcript dict.
+
+    Side-effect-free except for backends' own model loading. The route writes
+    the result to disk separately so this function is testable as pure
+    transformation given the backends.
+    """
+    if not Path(source_path).exists():
+        raise FileNotFoundError(f"source not found: {source_path}")
+
+    duration_ms = probe_duration_ms(source_path)
+
+    # 1. VAD — speech segments (carry per-segment RMS energy) + first-class silences
+    vad = VAD(backend=backends.vad)
+    speech, silences = vad.segment(source_path, duration_ms)
+
+    # 2. ASR — utterances with word timings, may contain event tags inline
+    asr = Transcriber(config=config.asr, backend=backends.asr)
+    asr_result = asr.transcribe(source_path)
+
+    # 3. Initial transcript shell
+    transcript: dict[str, Any] = {
+        "schema_version": SCHEMA_VERSION,
+        "kind": "session",
+        "session_id": session_id,
+        "source": _relative_source(seed_path, source_path),
+        "language": _detect_language(asr_result.language, config.asr.language),
+        "duration_ms": duration_ms,
+        "modality": _modality(source_path),
+        "speakers": [],
+        "utterances": asr_result.utterances,
+        "silences": silences_to_schema(silences),
+        "cues": [],
+        "frames": [],
+        "glossary_refs": [],
+        # frame_capture / frame_annotation are omitted (not null): the schema
+        # types provenance fields as strings and the convention is "absent when
+        # not applicable". run_pipeline does no frame capture/annotation; those
+        # stages (frames.py / frame_annotation.py) add their own provenance when
+        # they run.
+        "provenance": {
+            "transcriber": config.transcriber_version,
+            "asr_model": config.asr_model_tag,
+            "diarizer": config.diarizer_tag,
+            "audio_cues": f"{config.vad_tag} + whisper-events",
+        },
+    }
+
+    # 4. Diarization — assign speaker_id per utterance + overlap cues
+    diarizer = Diarizer(backend=backends.diarization)
+    turns = diarizer.diarize(source_path)
+    align(transcript, turns)
+
+    # 5. Speakers list, derived from the diarized utterances
+    transcript["speakers"] = _speakers_from_utterances(transcript["utterances"])
+
+    # 6. Cue parser — strip [laughter]/[sigh]/etc from utterance text into cues[]
+    parse_transcript_cues(transcript)
+
+    # 7. Silence semantic typing (after_question / thinking / interruption / …)
+    type_all_silences(transcript)
+
+    # 8. Prosody hints per utterance (deterministic, cheap). Volume bucketing
+    # needs the per-utterance VAD RMS energy signal mapped from the speech
+    # segments; without it volume would default to "normal" for every utterance.
+    energies = utterance_energies(speech, transcript["utterances"])
+    annotate_prosody(transcript, energies)
+
+    return transcript
+
+
+def _relative_source(seed_path: str, source_path: str) -> str:
+    """Return a seed-relative path for transcript.source if the source lives
+    inside the seed; otherwise return the absolute path unchanged.
+    """
+    try:
+        return str(Path(source_path).relative_to(Path(seed_path).parent))
+    except ValueError:
+        return source_path
+
+
+def _modality(source_path: str) -> list[str]:
+    """Coarse modality flag from file extension. Video files imply both audio
+    and video tracks (the player will only render video if present).
+    """
+    ext = Path(source_path).suffix.lower()
+    if ext in {".mp4", ".mov", ".mkv", ".webm", ".avi", ".m4v"}:
+        return ["audio", "video"]
+    return ["audio"]
+
+
+def write_transcript(seed_path: str, session_id: str, transcript: dict[str, Any]) -> str:
+    """Write transcript.json to sessions/<session_id>/. Returns the path."""
+    out_dir = Path(seed_path) / "sessions" / session_id
+    out_dir.mkdir(parents=True, exist_ok=True)
+    out_path = out_dir / "transcript.json"
+    out_path.write_text(json.dumps(transcript, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    return str(out_path)

package/transcriber/app/pptx_export.py

@@ -0,0 +1,42 @@
+"""PPTX deck export (#66).
+
+Turns a report deck-spec (built by cli/src/exporters/report.ts → buildDeckSpec)
+into a .pptx: one slide per entry, bullets as body, citations as slide notes.
+Branding (title color) is configurable per seed. python-pptx is lazily imported.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def export_deck(spec: list[dict[str, Any]], out_path: str, branding: dict[str, Any] | None = None) -> str:
+    try:
+        from pptx import Presentation  # type: ignore
+        from pptx.util import Pt  # type: ignore
+    except ImportError as e:
+        raise RuntimeError("python-pptx not installed (pip install -e '.[legacy]')") from e
+
+    branding = branding or {}
+    prs = Presentation()
+    title_only = prs.slide_layouts[5]  # title + content area
+
+    for slide_spec in spec:
+        slide = prs.slides.add_slide(title_only)
+        slide.shapes.title.text = slide_spec.get("title", "")
+        # bullets in a textbox
+        body = slide.placeholders[0] if slide_spec.get("title") is None else None
+        tb = slide.shapes.add_textbox(Pt(40), Pt(120), Pt(640), Pt(360)).text_frame
+        tb.word_wrap = True
+        for i, bullet in enumerate(slide_spec.get("bullets", [])):
+            p = tb.paragraphs[0] if i == 0 else tb.add_paragraph()
+            p.text = str(bullet)
+        # citations → slide notes
+        notes = slide_spec.get("notes", "")
+        if notes:
+            slide.notes_slide.notes_text_frame.text = notes
+        _ = body
+        _ = branding
+
+    prs.save(out_path)
+    return out_path

package/transcriber/app/prosody.py

@@ -0,0 +1,128 @@
+"""Prosody hint extractor (#13).
+
+Deterministic per-utterance hints derived from word timings, optional VAD
+energy, and speech rate. No ML model — cheap, reproducible context.
+
+Output shape (matches transcript.schema.json #/$defs/prosody):
+    {"volume": "low|normal|high", "pace": "slow|normal|fast", "hesitations": int}
+
+Thresholds are module constants, documented here for reproducibility:
+
+  pace (words per second over the utterance span):
+    < 2.0  → slow
+    > 3.3  → fast
+    else   → normal
+
+  volume (mean VAD RMS energy, normalized 0..1; requires the energy signal
+  from Silero VAD, issue #9). When energy is unavailable we report "normal"
+  rather than guess:
+    < 0.33 → low
+    > 0.66 → high
+    else   → normal
+
+  hesitations = filler tokens + immediate word repetitions + long
+  intra-utterance gaps (> 400 ms between consecutive words).
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+PACE_SLOW_WPS = 2.0
+PACE_FAST_WPS = 3.3
+# Volume thresholds applied to the normalized 0..1 energy. These are GLOBAL
+# constants, not per-speaker. The energy signal is session-normalized in
+# vad.utterance_energies(); a soft speaker's loudest moment can still read below
+# a loud speaker's baseline. TODO(#13): per-speaker normalization would make
+# these buckets speaker-relative — see vad.utterance_energies for the plan.
+VOLUME_LOW = 0.33
+VOLUME_HIGH = 0.66
+HESITATION_GAP_MS = 400
+
+# Multilingual (es-CO + en) filler set.
+_FILLERS = {
+    "uh",
+    "um",
+    "eh",
+    "em",
+    "este",
+    "esto",
+    "mmm",
+    "hmm",
+    "like",
+    "pues",
+}
+_FILLER_PHRASES = ("o sea", "you know", "es decir")
+
+_WORD_RE = re.compile(r"[^\W\d_]+", re.UNICODE)
+
+
+def _pace(text: str, start_ms: int, end_ms: int) -> str:
+    duration_s = max((end_ms - start_ms) / 1000.0, 1e-6)
+    n_words = len(_WORD_RE.findall(text))
+    wps = n_words / duration_s
+    if wps < PACE_SLOW_WPS:
+        return "slow"
+    if wps > PACE_FAST_WPS:
+        return "fast"
+    return "normal"
+
+
+def _volume(energy: float | None) -> str:
+    if energy is None:
+        return "normal"
+    if energy < VOLUME_LOW:
+        return "low"
+    if energy > VOLUME_HIGH:
+        return "high"
+    return "normal"
+
+
+def _count_hesitations(text: str, words: list[dict[str, Any]] | None) -> int:
+    count = 0
+    tokens = [t.lower() for t in _WORD_RE.findall(text)]
+
+    # filler single tokens
+    count += sum(1 for t in tokens if t in _FILLERS)
+
+    # filler phrases
+    lowered = text.lower()
+    for phrase in _FILLER_PHRASES:
+        count += lowered.count(phrase)
+
+    # immediate repetitions ("yo yo", "the the")
+    for a, b in zip(tokens, tokens[1:], strict=False):
+        if a == b and len(a) > 1:
+            count += 1
+
+    # long gaps between consecutive words
+    if words:
+        for prev, nxt in zip(words, words[1:], strict=False):
+            if nxt.get("s", 0) - prev.get("e", 0) > HESITATION_GAP_MS:
+                count += 1
+
+    return count
+
+
+def extract_prosody(utterance: dict[str, Any], energy: float | None = None) -> dict[str, Any]:
+    """Compute {volume, pace, hesitations} for a single utterance dict."""
+    text = utterance.get("text", "")
+    return {
+        "volume": _volume(energy),
+        "pace": _pace(text, utterance["start_ms"], utterance["end_ms"]),
+        "hesitations": _count_hesitations(text, utterance.get("words")),
+    }
+
+
+def annotate_prosody(
+    transcript: dict[str, Any],
+    energies: dict[str, float] | None = None,
+) -> dict[str, Any]:
+    """Attach `prosody` to every utterance. `energies` maps utterance id → mean
+    VAD RMS energy (0..1) when available. Mutates and returns the transcript.
+    """
+    energies = energies or {}
+    for utt in transcript.get("utterances", []):
+        utt["prosody"] = extract_prosody(utt, energies.get(utt.get("id")))
+    return transcript

package/transcriber/app/routes/__init__.py

@@ -0,0 +1 @@
+"""HTTP route modules. Each subsystem (#9-#15) mounts its own router."""

package/transcriber/app/routes/legacy.py

@@ -0,0 +1,117 @@
+"""POST /legacy-ingest — normalize a legacy document into a transcript.json.
+
+The Node-side legacy-worker (cli/src/loops/legacy_worker.ts) pulls
+`legacy-ingest` jobs from the queue and POSTs each here. The route dispatches
+by file extension to the pure ingestors in `app/legacy.py`, then writes the
+normalized JSON to `<seed>/legacy/<basename>.json`.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from fastapi import APIRouter, HTTPException, status
+from pydantic import BaseModel, Field
+
+from ..legacy import ingest as ingest_legacy
+
+router = APIRouter()
+
+
+class LegacyIngestRequest(BaseModel):
+    seed_path: str = Field(..., description="Absolute path to the seed root.")
+    source_path: str = Field(..., description="Absolute path to the asset to ingest.")
+    # CSV/XLSX column mapping — if text_col is None, the ingestor auto-detects
+    # from the header (text → transcript → content → utterance → quote →
+    # message → body, then first-column fallback). Node-side workers may also
+    # consult a `<source_path>.compost.json` sidecar that takes precedence.
+    text_col: str | None = Field(
+        None,
+        description="Column holding the utterance text (CSV/XLSX). Auto-detected if None.",
+    )
+    speaker_col: str | None = Field(None, description="Optional column for speaker label.")
+    sheet: str | None = Field(None, description="Optional XLSX sheet name (defaults to active).")
+
+
+class LegacyIngestResponse(BaseModel):
+    source_path: str
+    normalized_path: str
+    utterance_count: int
+    status: str  # ok | empty | failed
+    text_col_resolved: str | None = None  # which column was actually used (CSV/XLSX)
+    warnings: list[str] = []  # surfaced UX hints (e.g. xlsx un-evaluated formulas)
+
+
+@router.post(
+    "/legacy-ingest",
+    response_model=LegacyIngestResponse,
+    status_code=status.HTTP_200_OK,
+    summary="Normalize a PDF/DOCX/PPTX/CSV/XLSX/TXT/MD into a transcript-shaped JSON.",
+)
+def post_legacy_ingest(req: LegacyIngestRequest) -> LegacyIngestResponse:
+    src = Path(req.source_path)
+    seed = Path(req.seed_path)
+    if not src.exists():
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"source not found: {req.source_path}",
+        )
+    if not seed.exists():
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"seed not found: {req.seed_path}",
+        )
+
+    kwargs: dict[str, Any] = {}
+    if req.text_col is not None:
+        kwargs["text_col"] = req.text_col
+    if req.speaker_col is not None:
+        kwargs["speaker_col"] = req.speaker_col
+    if req.sheet is not None:
+        kwargs["sheet"] = req.sheet
+
+    try:
+        doc = ingest_legacy(src, **kwargs)
+    except ValueError as e:
+        # Unsupported ext or missing column — surface as 422 so the worker
+        # can mark the job failed and the CLI can show the researcher what's wrong.
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            detail=f"invalid_input: {e}",
+        ) from e
+    except RuntimeError as e:
+        # Missing optional dep (python-docx, openpyxl, etc.) — 503 so the
+        # CLI can route to `compost setup --fix`.
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail=f"dep_missing: {e}",
+        ) from e
+
+    # Write normalized JSON under <seed>/legacy/<basename>.json
+    legacy_dir = seed / "legacy"
+    legacy_dir.mkdir(parents=True, exist_ok=True)
+    out_path = legacy_dir / f"{src.stem}.json"
+    out_path.write_text(json.dumps(doc, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+
+    utt_count = len(doc.get("utterances", []))
+    prov = doc.get("provenance", {})
+    warnings: list[str] = []
+    skipped = prov.get("xlsx_rows_skipped_empty_text", 0)
+    if skipped > 0:
+        warnings.append(
+            f"{skipped} XLSX row(s) had data in other columns but an empty text cell — "
+            "likely an un-evaluated formula. Open the file in Excel once, or export to CSV."
+        )
+    return LegacyIngestResponse(
+        source_path=req.source_path,
+        normalized_path=str(out_path),
+        utterance_count=utt_count,
+        status="ok" if utt_count > 0 else "empty",
+        text_col_resolved=prov.get("text_col_resolved"),
+        warnings=warnings,
+    )
+
+
+__all__ = ["router", "LegacyIngestRequest", "LegacyIngestResponse"]

package/transcriber/app/routes/transcribe.py

@@ -0,0 +1,133 @@
+"""POST /transcribe — orchestrate the full descriptive pipeline (v0.1-01).
+
+Body shape mirrors the CLI's `TranscriberClient.transcribe()` contract: the
+client passes the seed root, the session id, and the absolute source path
+(already moved into `sessions/<sid>/source.<ext>` by the inbox watcher).
+
+The route returns the transcript path and a status code the worker uses to
+either commit the job, requeue for retry, or surface needs_speaker_labels to
+the researcher.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from pydantic import BaseModel, Field
+
+from ..asr import ASRConfig
+from ..pipeline import (
+    PipelineBackends,
+    PipelineConfig,
+    run_pipeline,
+    write_transcript,
+)
+
+router = APIRouter()
+
+
+class TranscribeRequest(BaseModel):
+    """JSON body for POST /transcribe."""
+
+    seed_path: str = Field(..., description="Absolute path to the seed root (Seeds/<name>/).")
+    session_id: str = Field(..., pattern=r"^[A-Za-z0-9_-]+$")
+    source_path: str = Field(..., description="Absolute path to the audio/video file.")
+    language: str | None = Field(None, description="Optional language hint (e.g. 'es-CO').")
+    model_name: str = Field("large-v3-turbo", description="Whisper model id.")
+    device: str = Field("auto", description="Device: auto | cpu | cuda | mps.")
+    compute_type: str = Field("int8", description="Compute precision (int8|float16|float32).")
+
+
+class TranscribeResponse(BaseModel):
+    """Response shape mirroring `TranscriberClient.TranscribeResponse`."""
+
+    session_id: str
+    transcript_path: str
+    status: str  # ok | needs_speaker_labels | failed_transcription
+
+
+def _build_backends() -> PipelineBackends:
+    """Resolve real backends from the environment.
+
+    Each backend is lazy-loaded by its own module; this function just decides
+    *which* backend to inject. In production all three are None → each module
+    falls back to its real implementation (WhisperX / pyannote / Silero). In
+    tests we override via FastAPI's `app.dependency_overrides`.
+    """
+    return PipelineBackends(vad=None, asr=None, diarization=None)
+
+
+def _build_pipeline_config(req: TranscribeRequest) -> PipelineConfig:
+    asr = ASRConfig(
+        model_name=req.model_name,
+        device=req.device,
+        compute_type=req.compute_type,
+        language=req.language,
+        event_tags=True,
+    )
+    return PipelineConfig(asr=asr)
+
+
+@router.post(
+    "/transcribe",
+    response_model=TranscribeResponse,
+    status_code=status.HTTP_200_OK,
+    summary="Run the descriptive transcription pipeline on a session's source media.",
+)
+def post_transcribe(
+    req: TranscribeRequest,
+    backends: Annotated[PipelineBackends, Depends(_build_backends)],
+) -> TranscribeResponse:
+    if not Path(req.source_path).exists():
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"source not found: {req.source_path}",
+        )
+    if not Path(req.seed_path).exists():
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"seed not found: {req.seed_path}",
+        )
+
+    config = _build_pipeline_config(req)
+
+    try:
+        transcript = run_pipeline(
+            seed_path=req.seed_path,
+            session_id=req.session_id,
+            source_path=req.source_path,
+            config=config,
+            backends=backends,
+        )
+    except RuntimeError as e:
+        # Backend missing weights → distinguishable from generic failure so the
+        # CLI can suggest `compost setup --fix`.
+        if "asr extra" in str(e).lower() or "HUGGINGFACE_TOKEN" in str(e):
+            raise HTTPException(
+                status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+                detail=f"model_missing: {e}",
+            ) from e
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"failed_transcription: {e}",
+        ) from e
+
+    transcript_path = write_transcript(req.seed_path, req.session_id, transcript)
+
+    return TranscribeResponse(
+        session_id=req.session_id,
+        transcript_path=transcript_path,
+        status=transcript.get("status", "ok"),
+    )
+
+
+def hf_token_present() -> bool:
+    """Helper exposed for the /compost-setup doctor: whether a HuggingFace
+    token is on the environment (does NOT validate it works against pyannote)."""
+    return bool(os.environ.get("HUGGINGFACE_TOKEN") or os.environ.get("HF_TOKEN"))
+
+
+__all__ = ["router", "TranscribeRequest", "TranscribeResponse", "hf_token_present"]