@alexkroman1/aai-cli 6.10.1 → 6.11.0

package/dist/templates/call-audit/agent.ts

@@ -0,0 +1,158 @@
+// Copyright 2026 the AAI authors. MIT license.
+/**
+ * A WORKFLOW APP that audits a recorded call, with **ffmpeg in the pipeline on
+ * both sides of the model.**
+ *
+ * ```text
+ *   any recording  →  levelled PCM  →  cut at the pauses  →  transcript
+ *                        ffmpeg            ffmpeg               sync STT
+ *
+ *                  →  headline, risks, actions  →  a script  →  an MP3
+ *                          LLM Gateway              schema      TTS + ffmpeg
+ * ```
+ *
+ * ## Which template to read first
+ *
+ * This one is the deepest of the workflow apps, so it is the wrong place to start.
+ *
+ * - `link-digest` owns the SHAPE — `workflowApp()`, no session, no tools, a form
+ *   that starts a run and a page that watches it.
+ * - `transcription-workflow` owns the FAN-OUT — why the sync transcription
+ *   endpoint's 120-second cap forces one, and how a run survives dying on segment
+ *   27 of 60.
+ * - `spoken-summary` owns the audio ROUND TRIP — `stepSpeak`, `writeUpload`, and
+ *   why a page needs `api.download` rather than a URL.
+ *
+ * **What this template adds is a decoder**, and everything downstream changes
+ * because of it. `workflows/audit.ts` carries the table comparing it against
+ * `transcription-workflow` row by row; the summary is that normalizing FIRST lets
+ * the desk cut a recording *in its pauses* instead of every 90 seconds, which
+ * deletes the segment overlap, the seam-matching stitcher, the WAV header parser
+ * and one of the two provider caps it had to plan against.
+ *
+ * ## Five ffmpeg jobs, and each one is a decision
+ *
+ * `workflows/media.ts` is where they are built, and it is the file to read: every
+ * argv is a pure function, so the argv is a value a spec asserts on rather than a
+ * string embedded in a step that spawns.
+ *
+ * | | what it does | why it is not obvious |
+ * | --- | --- | --- |
+ * | `ffprobe` | what the file WAS | on a temp file, because a pipe cannot seek an m4a's trailing index |
+ * | `loudnorm` pass 1 | measure five numbers | `-f null -`: decode everything, write nothing |
+ * | `loudnorm` pass 2 | apply them | one linear gain, so speech does not pump |
+ * | `silencedetect` | find every pause | same pass as above — a filter chain, not a second decode |
+ * | `libmp3lame` | master the summary | 4.3 MB of WAV becomes ~110 KB |
+ *
+ * The two analyses read their answers back by **different routes**, and that is the
+ * single most surprising thing in the template: loudness arrives on stderr (one
+ * block, printed last, so the SDK's capped stderr TAIL holds it) and the pauses
+ * arrive in a FILE (one event per pause, so a tail would silently drop the
+ * earliest ones and the desk would mis-cut only long recordings). `media.ts`'s
+ * module doc carries it.
+ *
+ * ## What it needs
+ *
+ * - **`ASSEMBLYAI_API_KEY` in the agent env** — `.env` under `aai dev`,
+ *   `aai secret put ASSEMBLYAI_API_KEY` once deployed. `requiredEnv` below is what
+ *   makes a deploy check for it rather than letting the first run find out. One key
+ *   covers transcription, the model and the voice alike.
+ * - **Storage** (`aai storage enable`, Settings → Database in the studio, or
+ *   `DATABASE_URL` under `aai dev`). REQUIRED, unlike most workflow apps: an
+ *   upload's record is a row, and this desk both reads an upload and writes two.
+ * - **ffmpeg** — every deployed guest's image installs it (and `ffprobe` with it).
+ *   Under `aai dev` it is whatever is on `PATH`, or what `AAI_FFMPEG_PATH` /
+ *   `AAI_FFPROBE_PATH` name. That is the one place dev/prod parity is partial, so
+ *   a missing binary is reported as an instruction rather than as
+ *   `spawn ffmpeg ENOENT`.
+ *
+ * ## It is scriptable, which is the other half of having an API
+ *
+ * The page is one caller. Two requests do the same thing from a shell — upload,
+ * then start a run naming the id, with `wait` holding the request open:
+ *
+ * ```sh
+ * ID=$(curl -s -X POST "https://<your-agent>/workflows/uploads?name=call.m4a" \
+ *   -H 'content-type: audio/mp4' --data-binary @call.m4a | jq -r .id)
+ *
+ * curl -X POST https://<your-agent>/workflows/runs \
+ *   -H 'content-type: application/json' \
+ *   -d "{\"workflow\":\"audit\",\"wait\":60000,\"input\":{\"recording\":\"$ID\"}}"
+ * ```
+ *
+ * The spoken audit comes back as an upload id in the run's output; the byte route
+ * (`GET /workflows/uploads/<id>`) takes the same bearer every other route does.
+ */
+
+import { workflow, workflowApp } from "@alexkroman1/aai";
+import { ASSEMBLYAI_TTS_DEFAULT_VOICE, ASSEMBLYAI_TTS_VOICES } from "@alexkroman1/aai/tts";
+import { z } from "zod";
+import { auditFlow } from "./workflows/audit.ts";
+
+/**
+ * The voices the form offers.
+ *
+ * READ from the SDK's catalog rather than listed, because a wrong voice id is a
+ * SILENT failure — it is a free-form string the service rejects in band after the
+ * socket is open, so the synthesis simply produces nothing. Narrowed to the English
+ * ones because the audit is written in the transcript's language and the prompt does
+ * not translate; every voice in the catalog speaks exactly one.
+ */
+const VOICES = Object.entries(ASSEMBLYAI_TTS_VOICES)
+  .filter(([, spec]) => spec.language === "en")
+  .map(([id]) => id);
+
+/**
+ * The same list as a TUPLE, which is what `z.enum` takes.
+ *
+ * Destructured rather than cast: a `.map` produces an array, and
+ * `as [string, ...string[]]` would be a template teaching a cast. The default covers
+ * the empty case honestly — a catalog with no English voice falls back to the SDK's
+ * own default rather than rendering a picker with no options.
+ */
+const [FIRST_VOICE = ASSEMBLYAI_TTS_DEFAULT_VOICE, ...OTHER_VOICES] = VOICES;
+
+/**
+ * The declaration: schema, description, and the directive body.
+ *
+ * Exported so `WorkflowOutputOf<typeof audit>` names the output type in one place —
+ * including from `client.tsx`, where `import type` is erased and so bundles nothing
+ * server-side.
+ */
+export const audit = workflow({
+  description: "Level a call recording, transcribe it at its pauses, and audit what was said",
+  input: z.object({
+    // A plain string, because an upload id is what the run really receives. What
+    // makes it a file picker rather than a text box is the `uploads` line below.
+    //
+    // "Anything" is not marketing: the first step hands the file to ffmpeg, so the
+    // accepted set is ffmpeg's rather than this template's — a video's audio track
+    // included, since the conversion drops the video.
+    recording: z.string().describe("Any recording — WAV, MP3, M4A, or a video's audio track"),
+    // An enum, so the form renders a SELECT rather than a text box — which is the
+    // whole reason the list is derived above rather than left free-form. Optional,
+    // so the SDK's own default voice applies when nobody chooses.
+    voice: z
+      .enum([FIRST_VOICE, ...OTHER_VOICES])
+      .optional()
+      .describe("Voice to read the audit in"),
+  }),
+  // The one line that makes the form take a file: `<WorkflowFields>` renders a
+  // picker for this property, `useWorkflowSubmit` stores the chosen file, and the
+  // ingest step reads it back with `readUpload`.
+  uploads: ["recording"],
+  run: auditFlow,
+});
+
+export default workflowApp({
+  name: "Call Audit",
+  workflows: { audit },
+  // Checked at deploy time, so a missing key is a warning naming it rather than a run
+  // that fails on its third step. A workflow app declares no providers, so this is the
+  // only thing that can name the credential its steps read.
+  //
+  // ffmpeg is NOT here and cannot be: `requiredEnv` checks the agent's environment,
+  // and a binary on `PATH` is not an environment variable. The deployed guest always
+  // has one; under `aai dev` the failure names its own remedy.
+  requiredEnv: ["ASSEMBLYAI_API_KEY"],
+});

package/dist/templates/call-audit/client.tsx

@@ -0,0 +1,235 @@
+// Copyright 2026 the AAI authors. MIT license.
+/**
+ * The page: a form, a progress log, the audit, and a player.
+ *
+ * `link-digest` shows these primitives raw, `transcription-workflow` shows the form
+ * layer in full, and `spoken-summary` shows how a page plays a file the RUN
+ * produced. None of that is restated here — this page is deliberately the least
+ * novel file in the template, because the subject is the pipeline.
+ *
+ * Two things it does add, and both are about being honest about the pipeline:
+ *
+ * - **The PIPELINE panel.** A reader cannot tell from a transcript whether the desk
+ *   cut it in the pauses or fell back to cutting by arithmetic, and that difference
+ *   is exactly what explains a mangled word at a seam. So `blindCuts` is rendered
+ *   rather than hidden, alongside what the recording measured before levelling.
+ * - **`api.download`, not a URL.** The run's output carries an upload id. The
+ *   obvious `<audio src={`/workflows/uploads/${id}`}>` is wrong in a way that only
+ *   shows up after a deploy: the byte route takes the same `Authorization` header
+ *   every other route does, and neither `<audio src>` nor `<a href>` can send one.
+ *   So a page built on a URL works against `aai dev`, where there is no token, and
+ *   401s the moment the agent has one.
+ */
+
+import "@alexkroman1/aai-ui/styles.css";
+// ERASED at build time, so naming the agent's own type costs the browser bundle
+// nothing — and it is what stops this file restating a shape `workflows/audit.ts`
+// already declares.
+import type { WorkflowOutputOf } from "@alexkroman1/aai";
+import {
+  createWorkflowApi,
+  Form,
+  page,
+  SubmitButton,
+  UploadProgressBar,
+  useWorkflowSubmit,
+  WorkflowFields,
+  WorkflowProgress,
+} from "@alexkroman1/aai-ui";
+import { useEffect, useState } from "react";
+import type { audit } from "./agent.ts";
+
+/** What a completed run reports, derived from the workflow rather than restated. */
+type Audit = WorkflowOutputOf<typeof audit>;
+
+/**
+ * The workflow's name, as a page starts a run by one.
+ *
+ * A rename in `agent.ts` is a runtime 400 rather than a compile error, which is why
+ * `agent.test.ts` pins this string.
+ */
+const WORKFLOW = "audit";
+
+/**
+ * Hoisted out of the component deliberately.
+ *
+ * The hooks hold the client in a ref precisely so a fresh object per render cannot
+ * restart their watch, but building one in render is still a new `fetch` closure
+ * every time and reads as though it were free.
+ */
+const api = createWorkflowApi();
+
+/** `4:09`, from the milliseconds a run reports. */
+function duration(ms: number): string {
+  const total = Math.round(ms / 1000);
+  const minutes = Math.floor(total / 60);
+  return `${minutes}:${String(total % 60).padStart(2, "0")}`;
+}
+
+/**
+ * The finished run's audio, as something the browser will play.
+ *
+ * A hook rather than four lines in the component because the CLEANUP is the part
+ * worth keeping in one place: an object URL pins its blob for the life of the
+ * document, so it is revoked when the id changes and when the page goes away. The
+ * `cancelled` flag covers the other half — a second run settling while the first
+ * download is still in flight would otherwise set state from the stale one.
+ */
+function useAudioUrl(uploadId: string | undefined): { url?: string; error?: string } {
+  const [state, setState] = useState<{ url?: string; error?: string }>({});
+
+  useEffect(() => {
+    if (uploadId === undefined) {
+      setState({});
+      return;
+    }
+    let cancelled = false;
+    let objectUrl: string | undefined;
+    api
+      .download(uploadId)
+      .then((blob) => {
+        if (cancelled) return;
+        objectUrl = URL.createObjectURL(blob);
+        setState({ url: objectUrl });
+      })
+      .catch((err: unknown) => {
+        if (!cancelled) setState({ error: err instanceof Error ? err.message : String(err) });
+      });
+    return () => {
+      cancelled = true;
+      if (objectUrl !== undefined) URL.revokeObjectURL(objectUrl);
+    };
+  }, [uploadId]);
+
+  return state;
+}
+
+/** One labelled number in the pipeline panel. */
+function Stat({ label, value }: { label: string; value: string }) {
+  return (
+    <div className="flex flex-col">
+      <dt className="text-xs uppercase tracking-wide opacity-60">{label}</dt>
+      <dd className="text-sm">{value}</dd>
+    </div>
+  );
+}
+
+/** A list that renders nothing rather than an empty box — see `risks` in the schema. */
+function Findings({ title, items }: { title: string; items: string[] }) {
+  if (items.length === 0) return null;
+  return (
+    <section className="flex flex-col gap-1">
+      <h3 className="text-sm font-medium opacity-70">{title}</h3>
+      <ul className="flex list-disc flex-col gap-1 pl-5">
+        {items.map((item) => (
+          <li key={item}>{item}</li>
+        ))}
+      </ul>
+    </section>
+  );
+}
+
+export function App() {
+  // The generic is what makes `run.status === "completed"` narrow to a TYPED
+  // `run.output` instead of `unknown`.
+  const { submit, run, pending, upload, pauseUpload, resumeUpload, error } =
+    useWorkflowSubmit<Audit>(WORKFLOW, { api });
+  const output = run?.status === "completed" ? run.output : undefined;
+  const audio = useAudioUrl(output?.audio);
+
+  return (
+    <main className="mx-auto flex max-w-3xl flex-col gap-6 p-8">
+      <header className="flex flex-col gap-1">
+        <h1 className="text-2xl font-medium">Call Audit</h1>
+        <p className="text-sm opacity-70">
+          Upload a call recording — any format. It comes back levelled, transcribed at its pauses,
+          and audited for risks and actions.
+        </p>
+      </header>
+
+      <Form onSubmit={submit} error={error} className="flex flex-col gap-4">
+        {/* Every control, from the workflow's own input schema. See the module doc. */}
+        <WorkflowFields workflow={WORKFLOW} />
+        <SubmitButton pending={pending} pendingLabel="Auditing…">
+          Audit the call
+        </SubmitButton>
+      </Form>
+
+      {/* The upload is its own wait, and the one nothing else can describe: the run
+          does not EXIST until the bytes are in, so there is no run id and nothing
+          for `<WorkflowProgress>` to read. */}
+      <UploadProgressBar upload={upload} onPause={pauseUpload} onResume={resumeUpload} />
+
+      {/* What the run itself says, from `report()` in the workflow's steps — which
+          for this template is the ffmpeg narration: what the file was, what it
+          measured, how many pauses were found. */}
+      <WorkflowProgress runId={run?.runId} api={api} />
+
+      {run?.status === "failed" && <p className="text-red-600">That one failed: {run.error}</p>}
+
+      {output !== undefined && (
+        <article className="flex flex-col gap-6">
+          <div className="flex flex-col gap-1">
+            <h2 className="text-xl">{output.headline}</h2>
+            <p className="text-sm opacity-70">
+              {output.source} · {duration(output.durationMs)} · {output.words} words
+            </p>
+          </div>
+
+          {/* What the pipeline did, which is this template's subject. Rendered rather
+              than logged because `blindCuts` is the one number that explains a bad
+              seam, and a reader has no other way to know. */}
+          <dl className="grid grid-cols-2 gap-3 rounded border border-current/10 p-4 sm:grid-cols-3">
+            <Stat label="Source codec" value={output.codec} />
+            <Stat label="Loudness in" value={`${output.loudnessBefore} LUFS`} />
+            <Stat label="Speech" value={`${output.speechPercent}%`} />
+            <Stat label="Segments" value={String(output.segments)} />
+            <Stat
+              label="Cut in speech"
+              value={output.blindCuts === 0 ? "none" : String(output.blindCuts)}
+            />
+            <Stat label="Run time" value={duration(output.elapsedMs)} />
+          </dl>
+
+          <Findings title="Risks" items={output.risks} />
+          <Findings title="Actions" items={output.actions} />
+
+          <section className="flex flex-col gap-2">
+            <h3 className="text-sm font-medium opacity-70">
+              Read aloud · {duration(output.audioDurationMs)} ·{" "}
+              {Math.round(output.audioBytes / 1024)} KB
+            </h3>
+            {audio.error !== undefined && (
+              <p className="text-red-600">Could not load the audio: {audio.error}</p>
+            )}
+            {audio.url !== undefined && (
+              <>
+                {/* No `<track>`, and that is a judgement rather than an
+                    oversight: the spoken text is rendered in full immediately
+                    below this player, which is the same information a caption
+                    track would carry. `spoken-summary` serves a one-cue WebVTT
+                    data URL instead — worth reading for how, if a real track is
+                    what a page needs. */}
+                <audio controls src={audio.url} className="w-full" />
+                {/* `download` works on an object URL because the bytes are already in
+                    the tab; it is the href that could not carry the agent's bearer,
+                    not the attribute. */}
+                <a href={audio.url} download="audit.mp3" className="text-sm underline">
+                  Download audit.mp3
+                </a>
+              </>
+            )}
+            <p className="text-sm opacity-70">{output.spoken}</p>
+          </section>
+
+          <details className="text-sm">
+            <summary className="cursor-pointer opacity-70">Transcript</summary>
+            <p className="mt-2 whitespace-pre-wrap">{output.transcript}</p>
+          </details>
+        </article>
+      )}
+    </main>
+  );
+}
+
+page({ name: "Call Audit", component: App });