@alexkroman1/aai-cli 6.10.1 → 7.0.0

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

@@ -151,7 +151,8 @@
  */
 
 import "@alexkroman1/aai-ui/styles.css";
-import type { WorkflowOutputOf } from "@alexkroman1/aai";
+import { countWords, formatDuration, plural } from "@alexkroman1/aai/utils";
+import type { WorkflowOutputOf } from "@alexkroman1/aai/workflow-api";
 import {
   Form,
   isTerminal,
@@ -162,19 +163,14 @@ import {
   useWorkflowRuns,
   useWorkflowStream,
   useWorkflowSubmit,
+  WORKFLOW_STATUS_LABELS,
   WorkflowFields,
   WorkflowProgress,
   type WorkflowRun,
 } from "@alexkroman1/aai-ui";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import type { transcribe } from "./agent.ts";
-import {
-  clock,
-  countWords,
-  stitchChunks,
-  TRANSCRIPT_STREAM,
-  type TranscriptChunk,
-} from "./workflows/stitch.ts";
+import { stitchChunks, TRANSCRIPT_STREAM, type TranscriptChunk } from "./workflows/stitch.ts";
 
 /**
  * What a finished run reports.
@@ -343,10 +339,10 @@ function TotalLatency({
         {running ? "Elapsed" : "Total latency"}
       </h2>
       <span className="flex flex-wrap items-baseline gap-x-3 gap-y-1">
-        <span className="text-sm tabular-nums">{duration(elapsedMs)}</span>
+        <span className="text-sm tabular-nums">{formatDuration(elapsedMs)}</span>
         {runMs !== undefined && outside !== undefined && (
           <span className="text-xs tabular-nums opacity-60">
-            {duration(outside)} before the run · {duration(runMs)} inside it
+            {formatDuration(outside)} before the run · {formatDuration(runMs)} inside it
           </span>
         )}
       </span>
@@ -647,9 +643,9 @@ function RunPanel({ run, onClear }: { run: WorkflowRun<Transcript>; onClear?: ()
       {run.status === "completed" && (
         <>
           <p className="text-xs opacity-60">
-            {run.output.segments} {run.output.segments === 1 ? "segment" : "segments"} ·{" "}
-            {duration(run.output.durationMs)} of audio · took {duration(run.output.elapsedMs)} ·{" "}
-            {run.output.words} words
+            {run.output.segments} {plural(run.output.segments, "segment")} ·{" "}
+            {formatDuration(run.output.durationMs)} of audio · took{" "}
+            {formatDuration(run.output.elapsedMs)} · {run.output.words} words
           </p>
           <pre className="whitespace-pre-wrap text-sm leading-relaxed">{run.output.transcript}</pre>
         </>
@@ -691,47 +687,26 @@ function LiveTranscript({ runId }: { runId: string }) {
   return (
     <div className="flex flex-col gap-2">
       <p className="text-xs opacity-60">
-        {countWords(transcript)} words so far · through {clock(covered)}
+        {countWords(transcript)} words so far · through {formatDuration(covered)}
       </p>
       <pre className="whitespace-pre-wrap text-sm leading-relaxed opacity-80">{transcript}</pre>
     </div>
   );
 }
 
-/**
- * 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.
  *
- * A `Record` keyed by the status union rather than a switch, so a status added
- * to the SDK is a compile error here instead of falling through a `default:`
- * into whichever line was last.
+ * `WORKFLOW_STATUS_LABELS` is the SDK's neutral map — a `Record` keyed by the
+ * status union rather than a switch, so a status added upstream is a compile
+ * error in one place every page inherits, and spreading a complete record cannot
+ * drop a key. Two of these keys are really this desk's: a page knows what its
+ * workflow does and the SDK does not.
  */
-const STATUS_LINE: Record<WorkflowRun["status"], string> = {
-  pending: "Queued",
+const STATUS_LINE = {
+  ...WORKFLOW_STATUS_LABELS,
   running: "Transcribing…",
   completed: "Transcript ready",
-  failed: "Failed",
-  cancelled: "Cancelled",
 };
 
 page({ name: "Transcription Desk", component: TranscriptionDesk });

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

@@ -8,13 +8,12 @@
  * 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:
+ * So this flow is three 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
+ *   pollTranscript     one step + a durable sleep, until the text comes back
  * ```
  *
  * **It is here to be compared against the other two, and it usually wins.** No
@@ -24,6 +23,21 @@
  * 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 endpoint is the SDK's; the STEPS are ours
+ *
+ * `stepTranscribeUpload` / `stepTranscribeSubmit` / `stepTranscribePoll` on
+ * `@alexkroman1/aai/step` own the URL, the raw-key auth, the windowed streaming
+ * upload, the PLURAL `speech_models` field and the failure classification. This file
+ * used to spell all of that out, and so did `spoken-summary` — the same ~200 lines
+ * twice, reworded, identical in behaviour, and drifting apart at the edges.
+ *
+ * What stays here is what a dependency cannot decide: how many steps to cut the job
+ * into, and therefore what is journaled and what a retry repeats. That is also
+ * structural rather than stylistic — the Workflow DevKit's builder transforms
+ * exactly the files under this `workflows/` directory, so a `"use step"` shipped
+ * inside the SDK would be transformed by nothing and would run inline with no
+ * journal and no retry, silently.
+ *
  * ## 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:
@@ -32,56 +46,23 @@
  * 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
+ * ## Three steps, not four, and the fourth was a wasted round trip
  *
- * `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. One window of READ-AHEAD keeps the store and the socket busy at the same
- * time; `windows` carries the argument.
+ * This used to poll `GET /v2/transcript/:id` for a status and then fetch the
+ * identical URL a second time to read the text the poll already had in its hand.
+ * {@link pollTranscript} answers with the transcript, so a finished job costs one
+ * request rather than two and the value journaled by the last poll IS the result.
  */
 
-import { throwFatalStepError, toStepError } from "@alexkroman1/aai/step-errors";
-import { readUpload, report, stepFetch, uploadInfo } from "@alexkroman1/aai/utils";
+import { report, TRANSCRIBE_API, uploadInfo } from "@alexkroman1/aai/step";
+import {
+  stepTranscribePollClassified,
+  stepTranscribeSubmitClassified,
+  stepTranscribeUploadClassified,
+} from "@alexkroman1/aai/step-errors";
+import { countWords, formatBytes } from "@alexkroman1/aai/utils";
 import { sleep } from "workflow";
-import { apiKeyOrFatal } from "./sync-api.ts";
-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"];
-
-/** 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;
+import { startClock, type Transcript } from "./transcribe.ts";
 
 /** How long between polls of a submitted job. */
 const POLL_INTERVAL = "10s";
@@ -89,9 +70,9 @@ 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.
+ * At {@link POLL_INTERVAL} this is an hour, 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;
 
@@ -109,15 +90,15 @@ export async function transcribeBatchFlow(input: { recording: string }): Promise
   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);
+    const progress = await pollTranscript(input.recording, job.id, startedAt);
+    if (progress.done) return progress.transcript;
     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}.`,
+      `read it directly with GET ${TRANSCRIBE_API}/v2/transcript/${job.id}.`,
   );
 }
 
@@ -134,28 +115,21 @@ export async function transcribeBatchFlow(input: { recording: string }): Promise
  * 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.
+ *
+ * The `Classified` callers on `@alexkroman1/aai/step-errors` are the SDK's own
+ * `stepTranscribe*` plus `throwStepError` and nothing else, which is what turns the
+ * SDK's `TranscribeError` into the DevKit's verdict: a missing key and a 400 stop, a
+ * 429 waits as long as the service asked. Every step here ends the same way for the
+ * same reason.
  */
 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 };
+  await report(
+    `Uploading ${stored.name || uploadId} (${formatBytes(stored.size)}) to the async API.`,
+  );
+  return await stepTranscribeUploadClassified(uploadId);
 }
 
 /** Retries beyond the default 3: an upload is the one call here worth another attempt. */
@@ -165,126 +139,51 @@ uploadToProvider.maxRetries = 5;
 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 };
+  const job = await stepTranscribeSubmitClassified(audioUrl);
+  await report(`Submitted — job ${job.id}.`);
+  return job;
 }
 
 /**
- * Ask once whether the job has finished.
+ * Ask once whether the job has finished, and read it when it has.
  *
  * `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.
+ * not be where a provider's vocabulary is interpreted — a new status string would
+ * otherwise read as "not done yet" forever. A failed job is a terminal failure
+ * inside the SDK call, 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(
+export async function pollTranscript(
   uploadId: string,
   id: string,
   startedAt: number,
-): Promise<Transcript> {
+): Promise<{ done: false } | { done: true; transcript: 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);
+  const progress = await stepTranscribePollClassified(id);
+  if (!progress.done) {
+    await report(`Transcript ${id} is ${progress.status}.`);
+    return { done: false };
+  }
 
+  const stored = await uploadInfo(uploadId);
+  const transcript = progress.transcript.text;
   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,
+    done: true,
+    transcript: {
+      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 — the only one of the three flows that does
+      // not have to derive this from byte offsets.
+      durationMs: progress.transcript.durationMs,
+      // 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, with the next one already in flight.
- *
- * 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.
- *
- * **One window of READ-AHEAD**, which is the whole concurrency available here: the
- * consumer is a socket and the producer is the app's own store, and read-then-send
- * makes them strictly alternate — the store idles while bytes go out, and the socket
- * idles while the next window is fetched. Starting the next read before yielding the
- * current window overlaps them, so a gigabyte upload pays the larger of the two
- * rather than their sum. Exactly one, not a queue: a deeper buffer holds more of a
- * file this generator exists to avoid holding, and there is nothing to gain past
- * keeping both ends busy.
- */
-async function* windows(uploadId: string, size: number): AsyncGenerator<Uint8Array> {
-  const read = (at: number): Promise<Uint8Array> =>
-    readUpload(uploadId, { start: at, end: at + UPLOAD_WINDOW_BYTES }).then((slice) => slice.bytes);
-  let at = 0;
-  let next = at < size ? read(at) : undefined;
-  while (next !== undefined) {
-    const bytes = await next;
-    if (bytes.length === 0) return;
-    at += UPLOAD_WINDOW_BYTES;
-    // Issued BEFORE the yield, so the store is fetching while the socket sends.
-    next = at < size ? read(at) : undefined;
-    yield bytes;
-  }
-}
-
-/** 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`;
-}