@joewinke/voice-pipeline

Generic, zero-dependency multi-pass voice cascade orchestrator. Walks an ordered list of PassDefinitions, threading each pass's output into the next pass's prompt context, with fallback-model retry on invalid JSON or missing required fields.

This is the shared generic core of the JAT ↔ JST voice stack. Domain-specific passes (JAT voice-organize: summary/kb/tasks; JST Scribe: medical/legal/realestate/therapy templates) live in each consuming app — only the orchestrator and the PassDefinition contract live here.

Install

npm install @joewinke/voice-pipeline

JAT consumes this package locally from the monorepo (file:../packages/voice-pipeline); JST consumes the published version from npm.

Usage

import { runCascade, CascadeError } from "@joewinke/voice-pipeline"

const passes = [
  {
    name: "summary",
    model: "gemma4:e2b-voice",
    fallbackModel: "gemma4:e2b",
    temperature: 0.1, // set explicitly — generic default is 0.2
    requiredFields: ["title", "summary"],
    buildPrompt: (ctx) => ({ system: "...", user: `...\n${ctx.transcript}` }),
    mergeOutput: (parsed) => ({ title: parsed.title, summary: parsed.summary }),
  },
]

const ctx = await runCascade({
  initialContext: { transcript },
  passes,
  classifyFn: async ({ prompt, model, numCtx, temperature }) => callLLM(...),
  parseFn: (jsonStr) => safeParse(jsonStr), // return null on failure
  onPartial: (phase, ctx, ms) => emitPartial(phase, ctx),
  log: (msg) => console.log(msg),
})

API

| Export | Description | |--------|-------------| | runCascade(args): Promise<PassContext> | Run the cascade. Throws CascadeError if a pass fails on both primary and fallback model. | | CascadeError | Error subclass with .passName and .reason. | | PassDefinition (type) | One pass: name, model, fallbackModel?, temperature? (default 0.2), numCtx? (default 45_000), buildPrompt, mergeOutput, requiredFields?. | | PassContext (type) | { transcript: string, [domainKey]: unknown } accumulator. |

The caller supplies classifyFn (the LLM call) and parseFn (JSON parse + repair), keeping this package free of any inference-provider or app coupling.

Versioning

Canonical source: packages/voice-pipeline in https://github.com/joewinke/jat. Changes are published to npm with a semver bump; JST picks them up via its ^x.y.z range. See ide/docs/voice-stack-unification.md for the cross-repo sharing model (jat-pecue).