@they-juanreina/compost-cli 0.1.2 → 0.1.3

package/dist/router.js

@@ -1,4 +1,5 @@
 import { Command } from 'commander';
+import { registerAgreement } from './commands/agreement.js';
 import { registerBlame } from './commands/blame.js';
 import { registerChat } from './commands/chat.js';
 import { registerCode } from './commands/code.js';
@@ -7,15 +8,21 @@ import { registerCreate } from './commands/create.js';
 import { registerEndorse } from './commands/endorse.js';
 import { registerEvals } from './commands/evals.js';
 import { registerExport } from './commands/export.js';
+import { registerImport } from './commands/import.js';
 import { registerIngest } from './commands/ingest.js';
 import { registerInit } from './commands/init.js';
+import { registerJobs } from './commands/jobs.js';
+import { registerLabel } from './commands/label.js';
 import { registerMigrate } from './commands/migrate.js';
 import { registerModels } from './commands/models.js';
 import { registerQuery } from './commands/query.js';
+import { registerRecode } from './commands/recode.js';
 import { registerReindex } from './commands/reindex.js';
+import { registerRerun } from './commands/rerun.js';
 import { registerRescan } from './commands/rescan.js';
 import { registerSaturate } from './commands/saturate.js';
 import { registerSearch } from './commands/search.js';
+import { registerSecrets } from './commands/secrets.js';
 import { registerServe } from './commands/serve.js';
 import { registerSession } from './commands/session.js';
 import { registerSetup } from './commands/setup.js';
@@ -26,20 +33,24 @@ import { registerTag } from './commands/tag.js';
 import { registerTranscribe } from './commands/transcribe.js';
 import { registerValidate } from './commands/validate.js';
 import { registerWatch } from './commands/watch.js';
-const VERSION = '0.1.2';
+const VERSION = '0.1.3';
 export function buildProgram() {
     const program = new Command();
     program
         .name('compost')
         .description('Local-first, AI-first research analysis harness for coding agents and humans.')
         .version(VERSION, '-V, --version')
-        .option('--human', 'Pretty-print output for human eyes (JSON is the default — agents parse it directly).')
+        .option('--human', 'Force human-readable output (auto-on at a TTY; JSON when piped or called by an agent).')
+        .option('--json', 'Force machine-readable JSON output (overrides TTY auto-detection).')
         .showHelpAfterError()
         .configureHelp({ sortSubcommands: true });
     registerInit(program);
     registerIngest(program);
+    registerImport(program);
     registerTranscribe(program);
+    registerLabel(program);
     registerWatch(program);
+    registerJobs(program);
     registerSnap(program);
     registerStatus(program);
     registerBlame(program);
@@ -51,8 +62,12 @@ export function buildProgram() {
     registerValidate(program);
     registerTag(program);
     registerCode(program);
+    registerRecode(program);
+    registerAgreement(program);
+    registerRerun(program);
     registerSynthesize(program);
     registerSearch(program);
+    registerSecrets(program);
     registerSession(program);
     registerCreate(program);
     registerEndorse(program);

package/dist/router.js.map

@@ -1 +1 @@
-{"version":3,"file":"router.js","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"router.js","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@they-juanreina/compost-cli",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Compost CLI engine. Subcommand router, JSON-out, harness loop runner.",
   "type": "module",
   "repository": {
@@ -16,7 +16,14 @@
     "compost": "./bin/compost.js"
   },
   "exports": {
-    ".": "./dist/index.js"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./engine": {
+      "types": "./dist/engine.d.ts",
+      "default": "./dist/engine.js"
+    }
   },
   "files": [
     "bin",
@@ -32,9 +39,9 @@
     "chokidar": "^4.0.0",
     "commander": "^12.1.0",
     "smol-toml": "^1.3.0",
-    "@they-juanreina/compost-evals": "0.1.2",
-    "@they-juanreina/compost-provenance": "0.1.2",
-    "@they-juanreina/compost-retrieval": "0.1.2"
+    "@they-juanreina/compost-evals": "0.1.3",
+    "@they-juanreina/compost-provenance": "0.1.3",
+    "@they-juanreina/compost-retrieval": "0.1.3"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.11",

package/templates/config.toml

@@ -38,9 +38,14 @@ include_drafts = "marked"
 [evals]
 storage = "sqlite"
 
-# LLM providers. Add API keys via env vars; compost reads `api_key_env`.
+# LLM providers. `api_key_env` is the NAME of an environment variable, never the
+# key itself — compost reads the value from the environment (or, transparently,
+# from the OS keychain / ~/.compost/secrets.env via `compost secrets set`).
+# NEVER paste a raw key here: this file lives in the (shared) seed. See
+# SECURITY.md → "Storing your tokens".
 [providers.ollama]
 base_url = "http://localhost:11434"
+# timeout_ms = 300000  # uncomment for very large local models (slow first load)
 
 [providers.lmstudio]
 base_url = "http://localhost:1234/v1"

package/transcriber/app/diarization.py

@@ -8,6 +8,7 @@ and gating low-confidence sessions — is pure and fully unit-tested.
 
 from __future__ import annotations
 
+import re
 from dataclasses import dataclass
 from functools import lru_cache
 from typing import Any, Protocol
@@ -129,6 +130,23 @@ def _load_pyannote(token_present: bool) -> DiarizationBackend:  # pragma: no cov
     return PyannoteBackend()
 
 
+_PYANNOTE_LABEL_RE = re.compile(r"^SPEAKER_(\d+)$")
+
+
+def normalize_speaker_label(label: str) -> str:
+    """Canonicalize a diarization speaker label to the schema's ``^S[0-9]+$`` form.
+
+    pyannote emits cluster labels like ``SPEAKER_00`` / ``SPEAKER_01``; the
+    transcript schema (schema/transcript.schema.json $defs.speaker.id and
+    $defs.utterance.speaker_id) requires ``S{n}`` — e.g. ``S0``, ``S1``. Leading
+    zeros are dropped (``SPEAKER_00`` → ``S0``). Already-canonical labels
+    (``S1``) and the ``S?`` orphan sentinel pass through unchanged, so this is
+    idempotent and safe to apply at the single write point in ``align()``.
+    """
+    m = _PYANNOTE_LABEL_RE.match(label)
+    return f"S{int(m.group(1))}" if m else label
+
+
 def _overlap_ms(a_start: int, a_end: int, b_start: int, b_end: int) -> int:
     return max(0, min(a_end, b_end) - max(a_start, b_start))
 
@@ -220,11 +238,20 @@ def assign_speaker(utterance: dict[str, Any], turns: list[Turn]) -> tuple[str, f
     return winner[0], min(winner[1] / u_dur, 1.0)
 
 
-def detect_overlaps(turns: list[Turn], min_overlap_ms: int = 200) -> list[dict[str, Any]]:
-    """Find regions where two turns overlap; emit `overlap` cues."""
+def detect_overlaps(
+    turns: list[Turn], min_overlap_ms: int = 200, start_index: int = 1
+) -> list[dict[str, Any]]:
+    """Find regions where two turns overlap; emit `overlap` cues.
+
+    Cue ids use the schema's uniform ``CUE-[0-9]{3,}`` space (the cue ``kind``
+    already distinguishes overlap cues from ASR-tag cues, so a typed ``CUE-OV-``
+    prefix would both duplicate that and violate the id pattern). ``start_index``
+    lets the caller continue numbering past any cues already in cues[] so the
+    overlap and tag-derived cues share one collision-free id sequence.
+    """
     cues: list[dict[str, Any]] = []
     ordered = sorted(turns, key=lambda t: t.start_ms)
-    idx = 1
+    idx = start_index
     for i in range(len(ordered)):
         for j in range(i + 1, len(ordered)):
             a, b = ordered[i], ordered[j]
@@ -237,7 +264,7 @@ def detect_overlaps(turns: list[Turn], min_overlap_ms: int = 200) -> list[dict[s
             if ov_end - ov_start >= min_overlap_ms:
                 cues.append(
                     {
-                        "id": f"CUE-OV-{idx:03d}",
+                        "id": f"CUE-{idx:03d}",
                         "kind": "overlap",
                         "start_ms": ov_start,
                         "end_ms": ov_end,
@@ -267,12 +294,15 @@ def align(transcript: dict[str, Any], turns: list[Turn]) -> dict[str, Any]:
             rescued = _nearest_turn_speaker(utt["start_ms"], utt["end_ms"], turns)
             if rescued is not None:
                 speaker = rescued  # confidence stays 0.0 (fallback marker)
-        utt["speaker_id"] = speaker
+        # Canonicalize pyannote's SPEAKER_NN labels to the schema's S{n} form at
+        # the single write point so speakers[].id (derived from these) and every
+        # utterances[].speaker_id agree with ^S[0-9]+$.
+        utt["speaker_id"] = normalize_speaker_label(speaker)
         utt.setdefault("diarization", {})["confidence"] = round(conf, 3)
         confidences.append(conf)
 
     cues = transcript.setdefault("cues", [])
-    cues.extend(detect_overlaps(turns))
+    cues.extend(detect_overlaps(turns, start_index=len(cues) + 1))
 
     mean_conf = sum(confidences) / len(confidences) if confidences else 0.0
     if mean_conf < DIARIZATION_CONFIDENCE_FLOOR:

package/transcriber/app/legacy_cli.py

@@ -0,0 +1,90 @@
+"""Native (host) legacy-ingest entrypoint (#184).
+
+Mirrors `app.transcribe_cli` for documents: runs the pure ingestors in
+`app.legacy.ingest` in a host Python venv so PDF/DOCX/PPTX/CSV/XLSX/TXT ingest
+works WITHOUT the Docker transcriber (demoted to a fallback). Shares the exact
+write + response shape as the `/legacy-ingest` route so the Node legacy-worker
+treats native and Docker results identically.
+
+Usage:
+    python -m app.legacy_cli --seed-path <seed> --source-path <file> \
+        [--text-col COL] [--speaker-col COL] [--sheet NAME]
+Prints exactly one JSON line; exit 0 on ok/empty, 1 on failure.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from .legacy import ingest as ingest_legacy
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(prog="compost-legacy-native")
+    p.add_argument("--seed-path", required=True)
+    p.add_argument("--source-path", required=True)
+    p.add_argument("--text-col", default=None)
+    p.add_argument("--speaker-col", default=None)
+    p.add_argument("--sheet", default=None)
+    args = p.parse_args(argv)
+
+    src = Path(args.source_path)
+    seed = Path(args.seed_path)
+    if not src.exists():
+        print(json.dumps({"status": "failed", "kind": "invalid_input", "error": f"source not found: {src}"}))
+        return 1
+    if not seed.exists():
+        print(json.dumps({"status": "failed", "kind": "invalid_input", "error": f"seed not found: {seed}"}))
+        return 1
+
+    kwargs: dict[str, str] = {}
+    if args.text_col is not None:
+        kwargs["text_col"] = args.text_col
+    if args.speaker_col is not None:
+        kwargs["speaker_col"] = args.speaker_col
+    if args.sheet is not None:
+        kwargs["sheet"] = args.sheet
+
+    try:
+        doc = ingest_legacy(src, **kwargs)
+    except ValueError as e:  # unsupported ext / missing column
+        print(json.dumps({"status": "failed", "kind": "invalid_input", "error": str(e)}))
+        return 1
+    except RuntimeError as e:  # missing optional dep (python-docx, openpyxl, …)
+        print(json.dumps({"status": "failed", "kind": "dep_missing", "error": str(e)}))
+        return 1
+
+    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."
+        )
+
+    print(
+        json.dumps(
+            {
+                "status": "ok" if utt_count > 0 else "empty",
+                "source_path": str(src),
+                "normalized_path": str(out_path),
+                "utterance_count": utt_count,
+                "text_col_resolved": prov.get("text_col_resolved"),
+                "warnings": warnings,
+            }
+        )
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/transcriber/app/pipeline.py

@@ -23,7 +23,7 @@ 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
+from .vad import VAD, VADBackend, silences_to_schema, utterance_energies
 
 SCHEMA_VERSION = "1.0"
 DEFAULT_TRANSCRIBER_VERSION = "compost-transcriber@0.1.0"
@@ -122,9 +122,9 @@ def run_pipeline(
 
     duration_ms = probe_duration_ms(source_path)
 
-    # 1. VAD — speech segments + first-class silences
+    # 1. VAD — speech segments (carry per-segment RMS energy) + first-class silences
     vad = VAD(backend=backends.vad)
-    _, silences = vad.segment(source_path, duration_ms)
+    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)
@@ -145,13 +145,16 @@ def run_pipeline(
         "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",
-            "frame_capture": None,
-            "frame_annotation": None,
         },
     }
 
@@ -169,8 +172,11 @@ def run_pipeline(
     # 7. Silence semantic typing (after_question / thinking / interruption / …)
     type_all_silences(transcript)
 
-    # 8. Prosody hints per utterance (deterministic, cheap)
-    annotate_prosody(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
 

package/transcriber/app/prosody.py

@@ -31,6 +31,11 @@ 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

package/transcriber/app/vad.py

@@ -23,6 +23,10 @@ MIN_FIRST_CLASS_SILENCE_MS = 1500
 class Segment:
     start_ms: int
     end_ms: int
+    # Mean RMS energy over the segment's waveform (raw amplitude, ~0..1; speech
+    # peaks well below 1.0). `None` when the backend doesn't report it — the
+    # prosody stage then leaves volume at "normal" rather than guessing.
+    energy: float | None = None
 
     @property
     def duration_ms(self) -> int:
@@ -30,7 +34,10 @@ class Segment:
 
 
 class VADBackend(Protocol):
-    def speech_timestamps(self, audio_path: str) -> list[dict[str, int]]: ...
+    def speech_timestamps(self, audio_path: str) -> list[dict[str, Any]]:
+        """Return speech segments as ``{"start_ms", "end_ms"}`` dicts, optionally
+        with a float ``"energy"`` (mean RMS over the segment)."""
+        ...
 
 
 SILERO_SAMPLE_RATE = 16000
@@ -60,7 +67,7 @@ class SileroBackend:  # pragma: no cover - needs torch + weights
         self._read_audio = read_audio
         self._get_speech_timestamps = get_speech_timestamps
 
-    def speech_timestamps(self, audio_path: str) -> list[dict[str, int]]:
+    def speech_timestamps(self, audio_path: str) -> list[dict[str, Any]]:
         wav = self._read_audio(audio_path, sampling_rate=SILERO_SAMPLE_RATE)
         raw = self._get_speech_timestamps(
             wav,
@@ -68,15 +75,23 @@ class SileroBackend:  # pragma: no cover - needs torch + weights
             sampling_rate=SILERO_SAMPLE_RATE,
             return_seconds=False,
         )
-        # `raw` is a list of {start, end} in samples; convert to ms.
+        # `raw` is a list of {start, end} in samples; convert to ms and compute
+        # the mean RMS energy over each segment's waveform window (#9 → #13).
+        # `wav` is a mono float tensor in [-1, 1]; RMS = sqrt(mean(x^2)).
         ms_per_sample = 1000 / SILERO_SAMPLE_RATE
-        return [
-            {
-                "start_ms": int(seg["start"] * ms_per_sample),
-                "end_ms": int(seg["end"] * ms_per_sample),
-            }
-            for seg in raw
-        ]
+        out: list[dict[str, Any]] = []
+        for seg in raw:
+            start_sample, end_sample = int(seg["start"]), int(seg["end"])
+            window = wav[start_sample:end_sample]
+            rms = float(window.pow(2).mean().sqrt()) if window.numel() else 0.0
+            out.append(
+                {
+                    "start_ms": int(seg["start"] * ms_per_sample),
+                    "end_ms": int(seg["end"] * ms_per_sample),
+                    "energy": rms,
+                }
+            )
+        return out
 
 
 @lru_cache(maxsize=1)
@@ -130,6 +145,55 @@ def silences_to_schema(silences: list[Segment]) -> list[dict[str, Any]]:
     return out
 
 
+def utterance_energies(
+    speech: list[Segment],
+    utterances: list[dict[str, Any]],
+) -> dict[str, float]:
+    """Map utterance id → mean VAD RMS energy, normalized 0..1 across the session.
+
+    Pure. Feeds ``prosody.annotate_prosody(transcript, energies=...)`` so the
+    low|normal|high volume bucketing actually runs (without this signal volume
+    defaults to "normal" for every utterance).
+
+    Each utterance's raw energy is the overlap-duration-weighted mean RMS of the
+    speech segments it spans; segments with no energy reading are ignored. Raw
+    speech RMS peaks far below 1.0, so applying prosody's fixed 0.33/0.66 split
+    to raw values would bucket everything as "low" — we normalize by the loudest
+    utterance in the session so the split is meaningful and reproducible.
+    Utterances with no overlapping energy-bearing segment are omitted, so the
+    caller reports "normal" rather than guessing.
+
+    TODO(#13): normalization is per-session (global max) and prosody's
+    VOLUME_LOW/HIGH are global constants, so a soft speaker's loudest moment
+    still reads quieter than a loud speaker's baseline. Per-speaker
+    normalization (group by ``utterance["speaker_id"]`` and normalize within
+    each speaker) would make the buckets speaker-relative. Out of scope here.
+    """
+    raw: dict[str, float] = {}
+    for utt in utterances:
+        uid = utt.get("id")
+        if uid is None:
+            continue
+        u_start, u_end = utt.get("start_ms", 0), utt.get("end_ms", 0)
+        weighted_sum = 0.0
+        total_overlap = 0
+        for seg in speech:
+            if seg.energy is None:
+                continue
+            overlap = min(u_end, seg.end_ms) - max(u_start, seg.start_ms)
+            if overlap <= 0:
+                continue
+            weighted_sum += seg.energy * overlap
+            total_overlap += overlap
+        if total_overlap > 0:
+            raw[uid] = weighted_sum / total_overlap
+
+    peak = max(raw.values(), default=0.0)
+    if peak <= 0:
+        return {}
+    return {uid: value / peak for uid, value in raw.items()}
+
+
 class VAD:
     def __init__(self, backend: VADBackend | None = None):
         self._backend = backend
@@ -140,6 +204,13 @@ class VAD:
     def segment(self, audio_path: str, total_duration_ms: int) -> tuple[list[Segment], list[Segment]]:
         """Return (speech_segments, first_class_silences)."""
         raw = self._get_backend().speech_timestamps(audio_path)
-        speech = [Segment(int(t["start_ms"]), int(t["end_ms"])) for t in raw]
+        speech = [
+            Segment(
+                int(t["start_ms"]),
+                int(t["end_ms"]),
+                float(t["energy"]) if t.get("energy") is not None else None,
+            )
+            for t in raw
+        ]
         silences = speech_to_silences(speech, total_duration_ms)
         return speech, silences