@aithos/sdk 0.1.0-alpha.43 → 0.1.0-alpha.44

package/README.md

@@ -55,6 +55,40 @@ const reply = await sdk.compute.invokeBedrock({
 console.log(reply.content);
 ```
 
+## Transcribing audio → text
+
+`sdk.compute.invokeTranscribe` turns an audio `Blob` into text through AWS
+Transcribe. It does one thing — audio → text — and **stores nothing**: it
+returns the transcript and you decide what to do with it (write it to an
+ethos, a PDS, your own database, email it, or throw it away).
+
+```ts
+// Browser: a Blob from MediaRecorder; backend: a Blob from a Buffer.
+const result = await sdk.compute.invokeTranscribe({
+  audio: blob,                          // Blob/File (Node 18+ has global Blob)
+  model: "transcribe:aws-fr-standard",  // default; also aws-en-standard
+  languageCode: "fr-FR",                // optional
+  // durationSecOverride: 127,          // REQUIRED on backends (no DOM probe)
+  onProgress: (s) => console.log(s.phase), // uploading → starting → processing → completed
+});
+
+console.log(result.text);          // "Bonjour, je voulais te dire que…"
+console.log(result.segments);      // [{ start_sec, end_sec, text }]
+console.log(result.creditsCharged);
+
+// Then YOU choose where it goes — the compute has no opinion:
+await myEthos.addRevision(result.text);   // or PDS, DB, email, nothing…
+```
+
+The core is isomorphic (Node + browser) and depends only on `Blob`, `fetch`
+and timers. Browser-only resilience is opt-in and framework-agnostic:
+`sdk.compute.transcribeDraft` (IndexedDB queue of recordings) and
+`sdk.compute.listLocalPendingTranscribes()` /
+`subscribeLocalPendingTranscribes()` / `resumeTranscribe(jobId)` recover jobs
+across reloads. React users get `useAithosTranscribePendingJobs(sdk.compute)`
+from `@aithos/sdk/react`. Advanced callers can drive the flow manually with
+`prepareTranscribe` / `startTranscribe` / `getTranscribeStatus`.
+
 ## Delegating compute to an agent — opt-in token spending
 
 To let an agent (or another user, or a third-party app) invoke Bedrock

package/dist/src/compute.d.ts

@@ -1,5 +1,6 @@
 import type { AithosAuth } from "./auth.js";
 import { type AithosSdkEndpoints } from "./endpoints.js";
+import { type LocalPendingEntry, type TranscribeDraftMeta, type TranscribeDraftRecord } from "./transcribe-resilience.js";
 export interface ComputeMessage {
     readonly role: "user" | "assistant";
     readonly content: string;
@@ -222,6 +223,138 @@ export interface InvokeSegmentationResult {
     readonly walletBalance: number;
     readonly auditId: string;
 }
+/**
+ * Stable cross-provider transcription model ids. The `transcribe:` prefix
+ * is part of the wire contract (mirrors `image:` for image models). New
+ * models can be added server-side without an SDK release; the union here
+ * gives autocomplete + type-checking for the common ones.
+ */
+export type TranscribeModelId = "transcribe:aws-fr-standard" | "transcribe:aws-en-standard";
+/** Progress callback states emitted by {@link ComputeNamespace.invokeTranscribe}. */
+export type TranscribeProgressState = {
+    readonly phase: "queued";
+} | {
+    readonly phase: "uploading";
+    readonly bytesUploaded: number;
+    readonly totalBytes: number;
+} | {
+    readonly phase: "starting";
+} | {
+    readonly phase: "processing";
+    readonly elapsedSec: number;
+} | {
+    readonly phase: "completed";
+};
+export interface TranscribeSegment {
+    readonly start_sec: number;
+    readonly end_sec: number;
+    readonly text: string;
+    readonly speaker_label?: string;
+}
+export interface TranscribeWord {
+    readonly start_sec: number;
+    readonly end_sec: number;
+    readonly content: string;
+    readonly confidence: number;
+}
+/** High-level args for the one-call {@link ComputeNamespace.invokeTranscribe}. */
+export interface InvokeTranscribeArgs {
+    /** Mandate id — optional for owner sessions, required for delegate sessions. */
+    readonly mandateId?: string;
+    /** The audio to transcribe. `Blob` is supported in both Node 18+ and browsers. */
+    readonly audio: Blob;
+    /** Model alias. Default `"transcribe:aws-fr-standard"`. */
+    readonly model?: TranscribeModelId;
+    /** AWS language code override (e.g. `"fr-FR"`). Defaults to the model alias's language. */
+    readonly languageCode?: string;
+    /** Speaker diarization. Default `false`. */
+    readonly diarization?: boolean;
+    /**
+     * Audio duration in seconds. REQUIRED on backends / non-browser runtimes
+     * (used for the wallet pre-debit estimate). In a browser it is probed
+     * automatically from the Blob when omitted; if probing fails the SDK
+     * falls back to a server-reconciled estimate of 0.
+     */
+    readonly durationSecOverride?: number;
+    /** Idempotency key for replay-safe retries (generated if omitted). */
+    readonly idempotencyKey?: string;
+    /** Progress callback (upload bytes, processing elapsed, …). */
+    readonly onProgress?: (state: TranscribeProgressState) => void;
+    /** Abort signal — cancels upload + polling. */
+    readonly signal?: AbortSignal;
+    /**
+     * Polling cadence override (ms) for the status loop. Defaults to an
+     * exponential backoff 2s → 15s. Mainly for tests.
+     */
+    readonly pollIntervalMs?: number;
+}
+export interface InvokeTranscribeResult {
+    readonly text: string;
+    readonly segments: readonly TranscribeSegment[];
+    readonly words: readonly TranscribeWord[];
+    readonly durationSec: number;
+    readonly languageCode: string;
+    readonly creditsCharged: number;
+    readonly walletBalance: number;
+    readonly auditId: string;
+    readonly jobId: string;
+    readonly fundedBy?: "sponsored" | "grant" | "purchase";
+    readonly sponsoredBy?: string;
+    readonly receiptId?: string;
+}
+export interface PrepareTranscribeArgs {
+    readonly contentType: string;
+    readonly durationSecEstimate?: number;
+    /** Selects the delegate signer for delegate sessions (not sent on the wire). */
+    readonly mandateId?: string;
+    readonly signal?: AbortSignal;
+}
+export interface PrepareTranscribeResult {
+    readonly jobId: string;
+    readonly uploadUrl: string;
+    readonly s3ObjectKey: string;
+    readonly expiresAt: number;
+}
+export interface StartTranscribeArgs {
+    readonly jobId: string;
+    readonly mandateId?: string;
+    readonly model: TranscribeModelId | string;
+    readonly durationSec: number;
+    readonly languageCode?: string;
+    readonly diarization?: boolean;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+export interface StartTranscribeResult {
+    readonly jobId: string;
+    readonly status: "running";
+    readonly estimatedCredits: number;
+    readonly walletBalance: number;
+    readonly fundedBy?: "sponsored" | "grant" | "purchase";
+    readonly receiptId?: string;
+}
+export type TranscribeStatusResult = {
+    readonly jobId: string;
+    readonly status: "running";
+    readonly elapsedSec: number;
+} | ({
+    readonly jobId: string;
+    readonly status: "completed";
+} & InvokeTranscribeResult) | {
+    readonly jobId: string;
+    readonly status: "failed";
+    readonly error: {
+        readonly code: string;
+        readonly message: string;
+    };
+};
+export interface TranscribeJobSummary {
+    readonly jobId: string;
+    readonly status: "prepared" | "running" | "completed" | "failed";
+    readonly createdAt: number;
+    readonly estimatedCredits?: number;
+    readonly creditsCharged?: number;
+}
 export interface ComputeNamespaceDeps {
     readonly auth: AithosAuth;
     readonly appDid: string;
@@ -309,5 +442,90 @@ export declare class ComputeNamespace {
      * Pricing: flat 5 000 mc per call (~$0.005 — Florence-2 is cheap).
      */
     invokeSegmentation(args: InvokeSegmentationArgs): Promise<InvokeSegmentationResult>;
+    /**
+     * Provision a transcription job and get a pre-signed S3 URL to PUT the
+     * audio to. No wallet debit. `mandateId` only selects the delegate
+     * signer (it is not part of the wire params for prepare).
+     */
+    prepareTranscribe(args: PrepareTranscribeArgs): Promise<PrepareTranscribeResult>;
+    /**
+     * Verify the uploaded audio, pre-debit the wallet, and launch the AWS
+     * Transcribe job. Returns immediately with `status: "running"`.
+     */
+    startTranscribe(args: StartTranscribeArgs): Promise<StartTranscribeResult>;
+    /**
+     * Poll a job's status. On completion the server finalises (reconcile +
+     * audit) and returns the transcript; a resumed poll after reconnect
+     * re-reads the transcript while it's still in the 24h output window.
+     */
+    getTranscribeStatus(args: {
+        readonly jobId: string;
+        readonly mandateId?: string;
+        readonly signal?: AbortSignal;
+    }): Promise<TranscribeStatusResult>;
+    /**
+     * List the caller's transcription jobs. Excludes terminal `completed`
+     * jobs unless `includeCompleted` is set — the resilience "what's still
+     * pending server-side" query.
+     */
+    listPendingTranscribes(args?: {
+        readonly includeCompleted?: boolean;
+        readonly mandateId?: string;
+        readonly signal?: AbortSignal;
+    }): Promise<{
+        readonly jobs: readonly TranscribeJobSummary[];
+    }>;
+    /**
+     * Transcribe an audio Blob to text in one call. Composes the four
+     * low-level methods: prepare → direct S3 upload → start → poll. Returns
+     * the transcript and stores NOTHING server-side beyond the ephemeral
+     * job — the consumer decides what to do with the result.
+     *
+     * Isomorphic: depends only on `Blob`, `fetch`/`XMLHttpRequest` and
+     * timers. On a backend, pass `durationSecOverride` (no Blob duration
+     * probing is possible without a DOM); in a browser the duration is
+     * probed automatically when omitted.
+     *
+     * Resilience: the job id is recorded in a localStorage tracker (browser)
+     * before upload, so `listLocalPendingTranscribes()` / `resumeTranscribe()`
+     * can recover a job whose result never arrived. In Node the tracker is a
+     * harmless in-memory no-op.
+     */
+    invokeTranscribe(args: InvokeTranscribeArgs): Promise<InvokeTranscribeResult>;
+    /**
+     * Resume polling an in-flight job by id — for recovery after a reload or
+     * crash. Returns the final result and clears the job from the local
+     * pending tracker. Throws if the job has already failed.
+     */
+    resumeTranscribe(jobId: string, opts?: {
+        readonly mandateId?: string;
+        readonly onProgress?: (state: TranscribeProgressState) => void;
+        readonly signal?: AbortSignal;
+        readonly pollIntervalMs?: number;
+    }): Promise<InvokeTranscribeResult>;
+    /** Snapshot of locally-tracked in-flight jobs (stable ref between mutations). */
+    listLocalPendingTranscribes(): readonly LocalPendingEntry[];
+    /** Stable snapshot for `useSyncExternalStore`-style consumers. */
+    getLocalPendingTranscribesSnapshot(): readonly LocalPendingEntry[];
+    /**
+     * Subscribe to changes in the local pending-jobs registry. Returns an
+     * unsubscribe function. Framework-agnostic: wrap it in a React
+     * `useSyncExternalStore`, a Vue effect, a Svelte store, etc.
+     */
+    subscribeLocalPendingTranscribes(listener: () => void): () => void;
+    /**
+     * IndexedDB-backed draft queue: persist a recording before any network
+     * call, upload it when the user confirms. Browser-only (methods reject
+     * with TranscribeDraftUnavailableError when IndexedDB is absent).
+     */
+    get transcribeDraft(): {
+        readonly save: (blob: Blob, meta?: TranscribeDraftMeta) => Promise<{
+            readonly draftId: string;
+        }>;
+        readonly list: () => Promise<readonly TranscribeDraftRecord[]>;
+        readonly get: (draftId: string) => Promise<TranscribeDraftRecord | null>;
+        readonly delete: (draftId: string) => Promise<void>;
+        readonly upload: (draftId: string, args: Omit<InvokeTranscribeArgs, "audio">) => Promise<InvokeTranscribeResult>;
+    };
 }
 //# sourceMappingURL=compute.d.ts.map