@alexkroman1/aai-cli 6.3.0 → 6.4.0

package/dist/templates/transcription-workflow/client.tsx

@@ -33,6 +33,25 @@
  * never travel in one; this page contains no upload code because the SDK owns
  * that.
  *
+ * ## Two modes, and the toggle is the template's subject
+ *
+ * The desk offers both flows the agent declares, and the page is where the
+ * difference is legible: pick "while it uploads" and there is a run to watch
+ * before any bytes are in, pick "after it uploads" and there is not. They share
+ * everything else — one `<Form>`, one picker, one progress log, one transcript —
+ * because they take the same input and return the same shape, and the only thing
+ * the page chooses is which HOOK submits it.
+ *
+ * `useWorkflowStream` is the streaming half: it cuts the file with the cutter this
+ * template supplies (`cut-wav.ts`, which is `workflows/wav.ts` run in the browser),
+ * uploads each part under one group token, and wakes the run as each lands.
+ * `useWorkflowSubmit` is the classic half and is unchanged.
+ *
+ * Streaming is the DEFAULT because it is faster on any real recording. The classic
+ * path stays selectable because it is the shape to read first, and because it is
+ * the one that works on a file this browser cannot parse — the cutter needs a WAV
+ * header, where the server-side flow reaches the same conclusion in its first step.
+ *
  * ## Two waits, two bars
  *
  * A recording is the one input big enough that STORING it is itself a wait, and
@@ -59,6 +78,7 @@ import {
   SubmitButton,
   UploadProgressBar,
   useWorkflowRuns,
+  useWorkflowStream,
   useWorkflowSubmit,
   WorkflowFields,
   WorkflowProgress,
@@ -66,6 +86,7 @@ import {
 } from "@alexkroman1/aai-ui";
 import { useEffect, useState } from "react";
 import type { transcribe } from "./agent.ts";
+import { ApiHelp } from "./api-help.tsx";
 
 /**
  * What a finished run reports.
@@ -76,15 +97,66 @@ import type { transcribe } from "./agent.ts";
  */
 type Transcript = WorkflowOutputOf<typeof transcribe>;
 
-/** The workflow this page drives. Matches the key in `workflowApp({ workflows })`. */
-const WORKFLOW = "transcribe";
+/**
+ * The three workflows this page drives, keyed by the mode that picks one.
+ *
+ * The STRINGS matter: a page starts a run by name, so a rename in `agent.ts` is a
+ * runtime 400 rather than a compile error. `agent.test.ts` pins all three.
+ */
+const WORKFLOWS = {
+  streaming: "transcribeStream",
+  classic: "transcribe",
+  batch: "transcribeBatch",
+} as const;
+
+/** Which flow the form submits through. */
+type Mode = keyof typeof WORKFLOWS;
+
+/**
+ * What each mode is called, and what picking it changes.
+ *
+ * The notes are the template's actual subject, so they say what the trade IS rather
+ * than which is "best" — the answer depends on the file and the link, and the whole
+ * reason all three ship is that a reader can run them over the same recording.
+ */
+const MODES: readonly { mode: Mode; label: string; note: string }[] = [
+  {
+    mode: "streaming",
+    label: "While it uploads",
+    note: "Sync API. The run starts first and transcribes each segment as its bytes land, so progress is visible while the file is still moving.",
+  },
+  {
+    mode: "classic",
+    label: "After it uploads",
+    note: "Sync API. Store the whole recording, then fan out over it. The simplest shape, and the quickest on a fast link.",
+  },
+  {
+    mode: "batch",
+    label: "Let the provider do it",
+    note: "Async API. One job, no cutting, no seams — and it accepts MP3 and M4A, which the two above refuse.",
+  },
+];
 
 /** Most past runs the history list shows. */
 const HISTORY_LIMIT = 10;
 
 function TranscriptionDesk() {
-  const { submit, run, upload, pending, error, reset } = useWorkflowSubmit<Transcript>(WORKFLOW);
-  const history = useWorkflowRuns<Transcript>(WORKFLOW, { limit: HISTORY_LIMIT });
+  const [mode, setMode] = useState<Mode>("streaming");
+  // ALL THREE hooks are called every render, because a hook may not be conditional —
+  // and that costs nothing here: none of them does anything until its `submit` is
+  // called, and `useWorkflowRun` underneath them holds no id until then either.
+  const streamed = useWorkflowStream<Transcript>(WORKFLOWS.streaming);
+  const stored = useWorkflowSubmit<Transcript>(WORKFLOWS.classic);
+  const batched = useWorkflowSubmit<Transcript>(WORKFLOWS.batch);
+  // The batch flow uploads the same way the classic one does — the id comes from the
+  // store — so it is the SAME hook against a different workflow. Only the streaming
+  // mode needs the other one, because only it needs the id before the bytes.
+  const active = mode === "streaming" ? streamed : mode === "batch" ? batched : stored;
+  const { submit, run, upload, pending, error, reset } = active;
+  // History is per WORKFLOW, so the list follows the mode: two flows that produce
+  // the same output are still two different things to have run, and merging them
+  // would put a run under a heading that cannot explain it.
+  const history = useWorkflowRuns<Transcript>(WORKFLOWS[mode], { limit: HISTORY_LIMIT });
   // Which past run the reader is looking at, if any. Its own state rather than
   // a route, because a workflow app is one page and a run id is not a place.
   const [openId, setOpenId] = useState<string | undefined>(undefined);
@@ -110,10 +182,14 @@ function TranscriptionDesk() {
         </p>
       </header>
 
-      {/* No mapping: the collected values already match the input schema. */}
+      <ModePicker mode={mode} onPick={setMode} disabled={pending} />
+
+      {/* No mapping: the collected values already match the input schema. All three
+          workflows declare `recording` as an upload, so the same picker serves every
+          mode — how the bytes travel is not a question to ask a person. */}
       <Form onSubmit={(values) => submit(values)} error={error}>
         {/* The NAME, so the schema is fetched here rather than by this page. */}
-        <WorkflowFields workflow={WORKFLOW} />
+        <WorkflowFields workflow={WORKFLOWS[mode]} />
         {/* Unguarded on purpose: it renders nothing until there are bytes in
             flight, and nothing again once they have landed. */}
         <UploadProgressBar upload={upload} />
@@ -128,10 +204,58 @@ function TranscriptionDesk() {
         openId={openId}
         onOpen={(runId) => setOpenId((current) => (current === runId ? undefined : runId))}
       />
+
+      {/* The most useful thing about a workflow app is the least discoverable:
+          this page is one caller of an ordinary HTTP API. See `api-help.tsx`. */}
+      <ApiHelp />
     </main>
   );
 }
 
+/**
+ * Which flow submits, as two radios.
+ *
+ * Radios rather than a toggle or a select, because the choice has a REASON per
+ * option and a radio group is the one control with room to show it — the note
+ * under each label is what makes this a decision rather than a switch somebody
+ * flips to see what happens.
+ *
+ * Disabled while a submission is in flight: the two hooks hold separate run state,
+ * so switching mid-run would swap the panel for the other hook's (empty) one and
+ * read as the run having vanished.
+ */
+function ModePicker({
+  mode,
+  onPick,
+  disabled,
+}: {
+  mode: Mode;
+  onPick: (next: Mode) => void;
+  disabled: boolean;
+}) {
+  return (
+    <fieldset className="flex flex-col gap-3" disabled={disabled}>
+      <legend className="text-sm font-medium uppercase tracking-[1.2px]">Transcribe</legend>
+      {MODES.map((option) => (
+        <label key={option.mode} className="flex items-start gap-3 text-sm">
+          <input
+            type="radio"
+            name="mode"
+            className="mt-1"
+            value={option.mode}
+            checked={mode === option.mode}
+            onChange={() => onPick(option.mode)}
+          />
+          <span className="flex flex-col gap-0.5">
+            <span>{option.label}</span>
+            <span className="text-xs opacity-70">{option.note}</span>
+          </span>
+        </label>
+      ))}
+    </fieldset>
+  );
+}
+
 /**
  * Every recent run, newest first, with its transcript one click away.
  *
@@ -220,7 +344,8 @@ function RunPanel({ run, onClear }: { run: WorkflowRun<Transcript>; onClear?: ()
       {run.status === "completed" && (
         <>
           <p className="text-xs opacity-60">
-            {run.output.segments} segments · {Math.round(run.output.durationMs / 1000)}s ·{" "}
+            {run.output.segments} {run.output.segments === 1 ? "segment" : "segments"} ·{" "}
+            {duration(run.output.durationMs)} of audio · took {duration(run.output.elapsedMs)} ·{" "}
             {run.output.words} words
           </p>
           <pre className="whitespace-pre-wrap text-sm leading-relaxed">{run.output.transcript}</pre>
@@ -231,6 +356,27 @@ function RunPanel({ run, onClear }: { run: WorkflowRun<Transcript>; onClear?: ()
   );
 }
 
+/**
+ * A duration a person can read.
+ *
+ * `${Math.round(ms / 1000)}s` was what this printed, and an hour-long recording came
+ * out as `3746s` — which a reader asked whether they should parse as 37.46 seconds.
+ * A raw second count stops being readable at about ninety of them, and the recordings
+ * this desk is FOR are the ones past that.
+ *
+ * The hours component is omitted when it is zero rather than padded to `0:02:26`, so
+ * a two-minute clip reads as `2:26` and only a long one grows a field.
+ */
+function duration(ms: number): string {
+  const total = Math.max(0, Math.round(ms / 1000));
+  const seconds = String(total % 60).padStart(2, "0");
+  const minutes = Math.floor(total / 60) % 60;
+  const hours = Math.floor(total / 3600);
+  return hours > 0
+    ? `${hours}:${String(minutes).padStart(2, "0")}:${seconds}`
+    : `${minutes}:${seconds}`;
+}
+
 /**
  * One line describing where a run has got to.
  *

package/dist/templates/transcription-workflow/workflows/batch.ts

@@ -0,0 +1,279 @@
+// Copyright 2026 the AAI authors. MIT license.
+/**
+ * The third desk: hand the whole recording to AssemblyAI's ASYNC API and wait.
+ *
+ * The other two flows exist because of one provider limit: the SYNC endpoint answers
+ * inside the request and pays for it with a hard 120-second, 40 MB cap, so a long
+ * recording has to be cut up and fanned out — and this template's whole subject is
+ * the two ways to arrange that. The async API has no such cap. You submit a job, it
+ * answers with an id in milliseconds, and the transcript is ready minutes later.
+ *
+ * So this flow is four steps and no arithmetic:
+ *
+ * ```text
+ *   uploadToProvider   one step   →  the file, streamed, and the URL it answered
+ *   createJob          one step   →  the transcript id
+ *   pollTranscript     one step + a durable sleep, until it is done
+ *   readTranscript     one step   →  the text
+ * ```
+ *
+ * **It is here to be compared against the other two, and it usually wins.** No
+ * segment planning, no seam stitching, no concurrency to tune, no WAV-only
+ * restriction — the provider accepts compressed audio, so an m4a straight off a
+ * phone works where both sync flows refuse it. What you give up is control of the
+ * inside: the latency is the provider's queue rather than your fan-out, and there is
+ * nothing to report between "submitted" and "done" except the job's own status.
+ *
+ * ## The one thing that makes this a WORKFLOW rather than a request
+ *
+ * The wait. A job takes minutes, and nothing about an HTTP request survives minutes:
+ * the poll has to outlive the process that started it, which is exactly what a
+ * durable `sleep` is. `recap-workflow` ports Temporal's `polling` sample for this
+ * shape and its module doc carries the argument; this is the same pattern with the
+ * poll bounded by attempts rather than by a deadline.
+ *
+ * ## The upload STREAMS out of our own store
+ *
+ * `readUpload` hands back bytes, and a two-hour recording is not a value this process
+ * can hold — so the body sent to `/v2/upload` is an async iterable of windows, which
+ * `stepFetch` accepts precisely for this. Nothing is buffered beyond one window.
+ *
+ * That is also why the step that does it is the step the DevKit retries: a streaming
+ * body is consumed once, so a retry has to re-read the upload from the start, which
+ * it does.
+ */
+
+import { throwFatalStepError, toStepError } from "@alexkroman1/aai/step-errors";
+import { readUpload, report, requireStepEnv, stepFetch, uploadInfo } from "@alexkroman1/aai/utils";
+import { sleep } from "workflow";
+import { countWords, startClock, type Transcript } from "./transcribe.ts";
+
+/** The async API's base. */
+const API = "https://api.assemblyai.com";
+
+/**
+ * The models this desk asks for, best first.
+ *
+ * `speech_models`, PLURAL and an array. The singular `speech_model` is deprecated on
+ * the async API and answers **400** for any current model name — which is how this
+ * was found: the first live run of this flow failed on it, and the API said so in
+ * exactly those words. Note the streaming API still uses the singular field, so the
+ * two are not interchangeable and neither is "the" spelling.
+ *
+ * Omitting it entirely is also legal and routes to the default; naming it is what
+ * pins the model so a default change does not silently move this template's output.
+ */
+const MODELS = ["universal-3-5-pro"];
+
+/** The key a step reads out of the agent env. Declared in `agent.ts`'s `requiredEnv`. */
+const API_KEY_ENV = "ASSEMBLYAI_API_KEY";
+
+/** How much of our stored upload one outbound window carries. */
+const UPLOAD_WINDOW_BYTES = 4 * 1024 * 1024;
+
+/** How long a single request may take. The upload is not one of these — see below. */
+const REQUEST_TIMEOUT_MS = 60_000;
+
+/**
+ * How long the upload leg may take.
+ *
+ * Its own budget because it is the one request whose duration is a function of the
+ * FILE rather than of the service: a gigabyte at 8 MB/s is over two minutes, and a
+ * deadline sized for a JSON round trip would cancel exactly the uploads this flow
+ * exists to handle.
+ */
+const UPLOAD_TIMEOUT_MS = 30 * 60_000;
+
+/** How long between polls of a submitted job. */
+const POLL_INTERVAL = "10s";
+
+/**
+ * Polls before the run gives up on a job.
+ *
+ * At {@link POLL_INTERVAL} this is an hour, which is well past what the async API
+ * takes for any recording it accepts. Bounded rather than endless because a job that
+ * never leaves `queued` is a run that would otherwise be replayed forever.
+ */
+const MAX_POLLS = 360;
+
+/** Transcribe a recording through the async API. */
+export async function transcribeBatchFlow(input: { recording: string }): Promise<Transcript> {
+  "use workflow";
+
+  const startedAt = await startClock();
+  const { audioUrl } = await uploadToProvider(input.recording);
+  const job = await createJob(audioUrl);
+
+  for (let poll = 0; poll < MAX_POLLS; poll += 1) {
+    const status = await pollTranscript(job.id);
+    if (status.done) return await readTranscript(input.recording, job.id, startedAt);
+    await sleep(POLL_INTERVAL);
+  }
+  // A plain throw: this is the BODY, where the fatal/retryable distinction has
+  // nothing to apply to — see `stream.ts`'s `abandon` for the same reasoning.
+  throw new Error(
+    `Transcript ${job.id} was still unfinished after ${MAX_POLLS} polls. It is not lost — ` +
+      `read it directly with GET ${API}/v2/transcript/${job.id}.`,
+  );
+}
+
+/**
+ * Upload the recording to the provider and answer with the URL it gave.
+ *
+ * Its own step, and that was a MEASUREMENT rather than a judgement. It began as one
+ * step doing both calls, on the argument that an `upload_url` is useless alone and
+ * expires — and the first live run showed what that costs: the create call failed on
+ * a deprecated field, and the DevKit retried the whole step five times, re-uploading
+ * 24 MB on every attempt for a fault in a JSON body. A retry that repeats the
+ * expensive half to fix the cheap half is not a retry.
+ *
+ * So the URL is journaled after all. The risk that made that look wrong is real but
+ * far smaller: if it expires before the next step runs, the run fails and a fresh one
+ * re-uploads — which is what would have happened anyway, once, instead of five times.
+ */
+export async function uploadToProvider(uploadId: string): Promise<{ audioUrl: string }> {
+  "use step";
+
+  const apiKey = apiKeyOrFatal();
+  const stored = await uploadInfo(uploadId);
+  await report(`Uploading ${stored.name || uploadId} (${mb(stored.size)}) to the async API.`);
+
+  const uploaded = await stepFetch(`${API}/v2/upload`, {
+    method: "POST",
+    headers: { Authorization: apiKey, "Content-Type": "application/octet-stream" },
+    // An async iterable, not bytes: this file may be gigabytes, and nothing here holds
+    // more than one window of it. See the module doc.
+    body: windows(uploadId, stored.size),
+    signal: AbortSignal.timeout(UPLOAD_TIMEOUT_MS),
+  });
+  if (!uploaded.ok) throw await failure(uploaded, "Upload");
+  const { upload_url: audioUrl } = (await uploaded.json()) as { upload_url?: string };
+  if (!audioUrl) {
+    return throwFatalStepError(new Error("The async API accepted the upload but named no URL."));
+  }
+  return { audioUrl };
+}
+
+/** Retries beyond the default 3: an upload is the one call here worth another attempt. */
+uploadToProvider.maxRetries = 5;
+
+/** Create the transcription job, and answer with the id that outlives this run. */
+export async function createJob(audioUrl: string): Promise<{ id: string }> {
+  "use step";
+
+  const created = await stepFetch(`${API}/v2/transcript`, {
+    method: "POST",
+    headers: { Authorization: apiKeyOrFatal(), "Content-Type": "application/json" },
+    body: JSON.stringify({ audio_url: audioUrl, speech_models: MODELS }),
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+  });
+  if (!created.ok) throw await failure(created, "Submit");
+  const { id } = (await created.json()) as { id?: string };
+  if (!id) return throwFatalStepError(new Error("The async API created no transcript id."));
+
+  await report(`Submitted transcript ${id}.`);
+  return { id };
+}
+
+/**
+ * Ask once whether the job has finished.
+ *
+ * `done` rather than the raw status, because the BODY branches on it and a body must
+ * not be the place a provider's vocabulary is interpreted — a new status string would
+ * otherwise be read as "not done yet" forever. A failed job is a terminal failure
+ * here, not a `done: true` the caller has to re-check.
+ */
+export async function pollTranscript(id: string): Promise<{ done: boolean; status: string }> {
+  "use step";
+
+  const res = await stepFetch(`${API}/v2/transcript/${id}`, {
+    headers: { Authorization: apiKeyOrFatal() },
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+  });
+  if (!res.ok) throw await failure(res, `Transcript ${id}`);
+  const body = (await res.json()) as { status?: string; error?: string };
+  const status = body.status ?? "unknown";
+  if (status === "error") {
+    // The provider has decided; no number of polls changes it.
+    return throwFatalStepError(
+      new Error(
+        `The async API could not transcribe that recording: ${body.error ?? "no reason given"}`,
+      ),
+    );
+  }
+  await report(`Transcript ${id} is ${status}.`);
+  return { done: status === "completed", status };
+}
+
+/** Read the finished transcript, and report it the way both sync flows do. */
+export async function readTranscript(
+  uploadId: string,
+  id: string,
+  startedAt: number,
+): Promise<Transcript> {
+  "use step";
+
+  const res = await stepFetch(`${API}/v2/transcript/${id}`, {
+    headers: { Authorization: apiKeyOrFatal() },
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+  });
+  if (!res.ok) throw await failure(res, `Transcript ${id}`);
+  const body = (await res.json()) as { text?: string; audio_duration?: number };
+  const transcript = (body.text ?? "").trim();
+  const stored = await uploadInfo(uploadId);
+
+  return {
+    source: stored.name || uploadId,
+    // ONE, and it is not a fudge: the async API transcribed the recording in one
+    // piece, which is the difference this flow is here to show. A reader comparing
+    // the three sees 7 segments, 7 segments, and 1.
+    segments: 1,
+    // The provider's own measurement, in seconds — the only one of the three flows
+    // that does not have to derive this from byte offsets.
+    durationMs: Math.round((body.audio_duration ?? 0) * 1000),
+    // Wall clock, the same way both sync flows measure it — see `startClock`. For
+    // this flow it is mostly the provider's queue, which is exactly the thing a
+    // reader comparing the three wants to see.
+    elapsedMs: Date.now() - startedAt,
+    words: countWords(transcript),
+    transcript,
+  };
+}
+
+/**
+ * The stored upload as a sequence of windows.
+ *
+ * A generator rather than one `readUpload`, because the whole point is that the file
+ * is never held: each window is read, sent, and dropped. `readUpload` clamps to what
+ * is stored, so the loop ends on the real end of the file even if `size` moved.
+ */
+async function* windows(uploadId: string, size: number): AsyncGenerator<Uint8Array> {
+  for (let at = 0; at < size; at += UPLOAD_WINDOW_BYTES) {
+    const slice = await readUpload(uploadId, { start: at, end: at + UPLOAD_WINDOW_BYTES });
+    if (slice.bytes.length === 0) return;
+    yield slice.bytes;
+  }
+}
+
+/** The API key, or a terminal failure — three more attempts find the same gap. */
+function apiKeyOrFatal(): string {
+  try {
+    return requireStepEnv(API_KEY_ENV);
+  } catch (err: unknown) {
+    return throwFatalStepError(err);
+  }
+}
+
+/** A failed call, classified for the DevKit — see `sync-api.ts` for the three-way rule. */
+async function failure(res: Response, what: string): Promise<Error> {
+  const body = (await res.json().catch(() => ({}))) as { error?: string };
+  return toStepError(
+    res,
+    `${what} failed: HTTP ${res.status}${body.error ? ` — ${body.error}` : ""}`,
+  );
+}
+
+/** A size a person can read, because the number that matters is the scale. */
+function mb(bytes: number): string {
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}