@effect-uai/core 0.3.0 → 0.5.0

package/src/transcriber/Transcriber.ts

@@ -0,0 +1,127 @@
+import { Context, Effect, Function, Stream } from "effect"
+import * as AiError from "../domain/AiError.js"
+import type { AudioFormat, AudioSource } from "../domain/Audio.js"
+import type { TranscriptEvent, TranscriptResult } from "../domain/Transcript.js"
+
+/**
+ * Cross-provider sync transcription request. Provider-specific
+ * extensions (Deepgram `keyterm[]`, ElevenLabs `diarize`, Google
+ * `adaptation`, …) live on each provider's typed request which extends
+ * this and narrows `model`.
+ */
+export type CommonTranscribeRequest = {
+  readonly audio: AudioSource
+  /** Model identifier. Each provider narrows to its typed literal union. */
+  readonly model: string
+  /** ISO-639-1 / BCP-47. Omit for autodetection (where supported). */
+  readonly language?: string
+  /**
+   * Vocab biasing. Single-string covers OpenAI/Whisper-style prompts;
+   * `terms[]` covers Deepgram `keyterm`, Google adaptation phrases, AWS
+   * `vocabularyName`. Providers ignore what they don't support.
+   */
+  readonly prompt?: string | { readonly terms: ReadonlyArray<string> }
+  readonly diarization?: boolean
+  readonly wordTimestamps?: boolean
+}
+
+/**
+ * Streaming-transcription request. `inputFormat` declares what the
+ * bytes in the input stream will look like — providers reject
+ * mismatches at stream startup with `AiError.InvalidRequest`.
+ */
+export type CommonStreamTranscribeRequest = Omit<CommonTranscribeRequest, "audio"> & {
+  readonly inputFormat: AudioFormat
+  readonly interimResults?: boolean
+  readonly vadEvents?: boolean
+}
+
+export type TranscriberService = {
+  /**
+   * One-shot transcription. Universal — AWS Transcribe (which has no
+   * native sync endpoint) emulates this by draining a streaming session
+   * internally.
+   */
+  readonly transcribe: (
+    request: CommonTranscribeRequest,
+  ) => Effect.Effect<TranscriptResult, AiError.AiError>
+  /**
+   * Live transcription as a Stream transformer. Consumes audio bytes
+   * from `audioIn`; emits `TranscriptEvent`s as they arrive. The
+   * underlying WS / gRPC connection is acquired on first pull and
+   * released when the output stream is finalized (success, failure, or
+   * interruption) via `Stream.scoped` — no explicit Scope handling at
+   * the call site.
+   *
+   * Gated by the `SttStreaming` capability marker on the top-level
+   * helper — providers without streaming-STT support don't ship the
+   * marker, so calls fail at `Effect.provide` with a type error.
+   */
+  readonly streamTranscriptionFrom: <E, R>(
+    audioIn: Stream.Stream<Uint8Array, E, R>,
+    request: CommonStreamTranscribeRequest,
+  ) => Stream.Stream<TranscriptEvent, AiError.AiError | E, R>
+}
+
+export class Transcriber extends Context.Service<Transcriber, TranscriberService>()(
+  "@betalyra/effect-uai/Transcriber",
+) {}
+
+/**
+ * Capability marker — provided by provider layers whose
+ * `streamTranscriptionFrom` is wired up at the wire level. Azure does
+ * not ship it (streaming-STT is SDK-internal). Calling
+ * `streamTranscriptionFrom` while only Azure's Layer is in scope fails
+ * at `Effect.provide` with a type error, not at runtime.
+ *
+ * Phantom — the value is `void`; providers register with
+ * `Layer.succeed(SttStreaming, undefined)`.
+ */
+export class SttStreaming extends Context.Service<SttStreaming, void>()(
+  "@betalyra/effect-uai/capability/SttStreaming",
+) {}
+
+/** One-shot transcription. */
+export const transcribe = (
+  request: CommonTranscribeRequest,
+): Effect.Effect<TranscriptResult, AiError.AiError, Transcriber> =>
+  Effect.flatMap(Transcriber.asEffect(), (t) => t.transcribe(request))
+
+/**
+ * Live transcription. Dual-arity: pipeable (data-last) and direct
+ * (data-first). Requires `SttStreaming` in R — providers without
+ * streaming support are a type error at provide time.
+ *
+ * @example
+ * ```ts
+ * // Pipeable — composes with other Stream operators
+ * mic.frames.pipe(
+ *   Transcriber.streamTranscriptionFrom(req),
+ *   Stream.filter((e) => e._tag === "final"),
+ * )
+ *
+ * // Direct
+ * Transcriber.streamTranscriptionFrom(mic.frames, req)
+ * ```
+ */
+export const streamTranscriptionFrom: {
+  (
+    request: CommonStreamTranscribeRequest,
+  ): <E, R>(
+    audioIn: Stream.Stream<Uint8Array, E, R>,
+  ) => Stream.Stream<TranscriptEvent, AiError.AiError | E, R | Transcriber | SttStreaming>
+  <E, R>(
+    audioIn: Stream.Stream<Uint8Array, E, R>,
+    request: CommonStreamTranscribeRequest,
+  ): Stream.Stream<TranscriptEvent, AiError.AiError | E, R | Transcriber | SttStreaming>
+} = Function.dual(
+  2,
+  <E, R>(audioIn: Stream.Stream<Uint8Array, E, R>, request: CommonStreamTranscribeRequest) =>
+    Stream.unwrap(
+      Effect.gen(function* () {
+        const t = yield* Transcriber.asEffect()
+        yield* SttStreaming.asEffect()
+        return t.streamTranscriptionFrom(audioIn, request)
+      }),
+    ),
+)

package/dist/StructuredFormat-BWq5Hd1O.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"StructuredFormat-BWq5Hd1O.d.mts","names":[],"sources":["../src/structured-format/StructuredFormat.ts"],"mappings":";;;;;;;;;;;;;;;KAaY,gBAAA,qBAAqC,gBAAA,UAA0B,MAAA,IACzE,oBAAA,UAA8B,MAAA;;;;;;KAOpB,gBAAA;EAAA,SACD,IAAA;EAAA,SACA,WAAA;EAAA,SACA,MAAA,EAAQ,gBAAA,CAAiB,CAAA;EAXxB;;;;EAAA,SAgBD,MAAA;AAAA;;KAIC,WAAA;EAAA,SACD,IAAA,EAAM,aAAA;EAAA,SACN,OAAA;AAAA;AAAA,cACV,0BAAA;;;;;AAfD;;cAyBa,qBAAA,SAA8B,0BAAA;EAAA,SAChC,GAAA;EAAA,SACA,MAAA,EAAQ,aAAA,CAAc,WAAA;AAAA;AAAA,cAC5B,mBAAA;;;;;;AAhBL;cAsBa,cAAA,SAAuB,mBAAA;EAAA,SACzB,GAAA;EAAA,SACA,KAAA;AAAA;;;;AArBV;;cAiCY,gBAAA,aAA8B,MAAA,CAAO,KAAA,wBAChD,MAAA,EAAQ,CAAA,EACR,OAAA;EAAA,SACW,IAAA;EAAA,SACA,WAAA;EAAA,SACA,MAAA;AAAA,MAEV,gBAAA,CAAiB,CAAA;;;;;;cAyCP,MAAA,MACP,MAAA,EAAQ,gBAAA,CAAiB,CAAA,OAC5B,GAAA,cAAe,MAAA,CAAO,MAAA,CAAO,CAAA,EAAG,qBAAA;;;;;;cAoBtB,SAAA,MACP,MAAA,EAAQ,gBAAA,CAAiB,CAAA,OAC5B,GAAA,aAAc,MAAA,CAAO,MAAA,CAAO,CAAA,EAAG,cAAA,GAAiB,qBAAA;;;;;cAatC,eAAA,MACP,MAAA,EAAQ,gBAAA,CAAiB,CAAA,aAE3B,IAAA,EAAM,MAAA,CAAO,MAAA,SAAe,CAAA,EAAG,CAAA,MAC9B,MAAA,CAAO,MAAA,CAAO,CAAA,EAAG,CAAA,GAAI,cAAA,GAAiB,qBAAA,EAAuB,CAAA"}

package/dist/Tool-DjVufH7i.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Tool-DjVufH7i.d.mts","names":[],"sources":["../src/tool/Tool.ts"],"mappings":";;;;;;;;;cAE0E,cAAA;;;;;;cAG7D,SAAA,SAAkB,cAAA;;;;;;;;;;KAmBnB,eAAA,oBAAmC,gBAAA,UAA0B,KAAA,IACvE,oBAAA,UAA8B,KAAA;;;AAvB0C;;;cA8B7D,gBAAA,aAA8B,MAAA,CAAO,KAAA,wBAChD,MAAA,EAAQ,CAAA,KACP,CAAA,GAAI,eAAA,CAAgB,CAAA;AAAA,KAIX,IAAA;EAAA,SACD,IAAA,EAAM,IAAA;EAAA,SACN,WAAA;EAAA,SACA,WAAA,EAAa,eAAA,CAAgB,KAAA;EAAA,SAC7B,GAAA,GAAM,KAAA,EAAO,KAAA,KAAU,MAAA,CAAO,MAAA,CAAO,MAAA,WAAiB,CAAA;;;;;;;WAOtD,MAAA;AAAA;;;;;;KAQC,cAAA;EAAA,SACD,IAAA;EAAA,SACA,WAAA;EAAA,SACA,WAAA,EAAa,MAAA;EAAA,SACb,MAAA;AAAA;AAAA,cAGE,IAAA,kDACX,IAAA,EAAM,IAAA,CAAK,IAAA,EAAM,KAAA,EAAO,MAAA,EAAQ,CAAA,MAC/B,IAAA,CAAK,IAAA,EAAM,KAAA,EAAO,MAAA,EAAQ,CAAA;AAAA,KAWjB,aAAA;EAAA,SACD,KAAA;EAAA,SACA,IAAA,EAAM,IAAA;EAAA,SACN,WAAA;EAAA,SACA,WAAA,EAAa,eAAA,CAAgB,KAAA;EAAA,SAC7B,GAAA,GAAM,KAAA,EAAO,KAAA,KAAU,MAAA,CAAO,MAAA,CAAO,KAAA,WAAgB,CAAA;EAAA,SACrD,QAAA,GAAW,MAAA,EAAQ,aAAA,CAAc,KAAA,MAAW,MAAA;EAAA,SAC5C,MAAA;AAAA;AAAA,cAGE,SAAA,yDACX,IAAA,EAAM,IAAA,CAAK,aAAA,CAAc,IAAA,EAAM,KAAA,EAAO,KAAA,EAAO,MAAA,EAAQ,CAAA,gBACpD,aAAA,CAAc,IAAA,EAAM,KAAA,EAAO,KAAA,EAAO,MAAA,EAAQ,CAAA;AAAA,KAEjC,gBAAA,YAA4B,aAAA,wBAAqC,CAAA;AAAA,KACjE,YAAA,YAAwB,IAAA,mBAAuB,CAAA;AAAA,KAC/C,WAAA,YAAuB,gBAAA,CAAiB,CAAA,IAAK,YAAA,CAAa,CAAA;AAAA,cAEzD,eAAA,MAAsB,CAAA,EAAG,WAAA,CAAY,CAAA,MAAK,CAAA,IAAK,gBAAA,CAAiB,CAAA;;;;;;cAQhE,aAAA,MACX,KAAA,EAAO,aAAA,CAAc,WAAA,CAAY,CAAA,OAChC,aAAA,CAAc,cAAA;;;;;;cAkBJ,OAAA,0CACX,IAAA,EAAM,IAAA,CAAK,IAAA,EAAM,KAAA,EAAO,MAAA,EAAQ,CAAA,GAChC,IAAA,EAAM,YAAA,KACL,MAAA,CAAO,MAAA,CAAO,kBAAA,EAAoB,SAAA,EAAW,CAAA"}

package/dist/Turn-OPaILVIB.d.mts

@@ -1,194 +0,0 @@
-import { i as ImageSource } from "./Image-BZmKfIdq.mjs";
-import { d as Item, g as Reasoning, o as FunctionCall, p as Message, s as FunctionCallOutput, x as Usage } from "./Items-CB8Bo3FI.mjs";
-import { i as StructuredFormat, n as JsonParseError, r as StructuredDecodeError } from "./StructuredFormat-BWq5Hd1O.mjs";
-import { Effect, Schema, Stream } from "effect";
-import * as _$effect_Types0 from "effect/Types";
-import * as _$effect_Cause0 from "effect/Cause";
-
-//#region src/domain/Turn.d.ts
-declare namespace Turn_d_exports {
-  export { InteractionEvent, RefusalRejected, Turn, TurnEvent, appendTurn, assistantMessages, functionCalls, isTurnComplete, reasonings, textDeltas, toStructured };
-}
-/**
- * The result of a single LLM generation. A turn produces zero or more items
- * (typically one assistant message and zero or more function_call items)
- * and reports usage + a stop reason.
- */
-declare const Turn: Schema.Struct<{
-  readonly items: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
-    readonly type: Schema.Literal<"message">;
-    readonly role: Schema.Literals<readonly ["user", "assistant", "system"]>;
-    readonly content: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
-      readonly type: Schema.Literal<"input_text">;
-      readonly text: Schema.String;
-    }>, Schema.Struct<{
-      readonly type: Schema.Literal<"input_image">;
-      readonly source: Schema.Schema<ImageSource>;
-    }>, Schema.Struct<{
-      readonly type: Schema.Literal<"output_text">;
-      readonly text: Schema.String;
-      readonly annotations: Schema.optional<Schema.$Array<Schema.Union<readonly [Schema.Struct<{
-        readonly type: Schema.Literal<"url_citation">;
-        readonly url: Schema.String;
-        readonly start_index: Schema.Number;
-        readonly end_index: Schema.Number;
-        readonly title: Schema.String;
-      }>, Schema.Struct<{
-        readonly type: Schema.Literal<"file_citation">;
-        readonly file_id: Schema.String;
-        readonly index: Schema.Number;
-      }>, Schema.Struct<{
-        readonly type: Schema.Literal<"container_file_citation">;
-        readonly container_id: Schema.String;
-        readonly file_id: Schema.String;
-        readonly start_index: Schema.Number;
-        readonly end_index: Schema.Number;
-      }>, Schema.Struct<{
-        readonly type: Schema.Literal<"file_path">;
-        readonly file_id: Schema.String;
-        readonly index: Schema.Number;
-      }>]>>>;
-    }>, Schema.Struct<{
-      readonly type: Schema.Literal<"refusal">;
-      readonly text: Schema.String;
-    }>]>>;
-    readonly providerData: Schema.optional<Schema.Unknown>;
-  }>, Schema.Struct<{
-    readonly type: Schema.Literal<"function_call">;
-    readonly call_id: Schema.String;
-    readonly name: Schema.String;
-    readonly arguments: Schema.String;
-    readonly providerData: Schema.optional<Schema.Unknown>;
-  }>, Schema.Struct<{
-    readonly type: Schema.Literal<"function_call_output">;
-    readonly call_id: Schema.String;
-    readonly output: Schema.String;
-    readonly providerData: Schema.optional<Schema.Unknown>;
-  }>, Schema.Struct<{
-    readonly type: Schema.Literal<"reasoning">;
-    readonly id: Schema.optional<Schema.String>;
-    readonly summary: Schema.optional<Schema.String>;
-    readonly signature: Schema.optional<Schema.String>;
-    readonly providerData: Schema.optional<Schema.Unknown>;
-  }>]>>;
-  readonly usage: Schema.Struct<{
-    readonly input_tokens: Schema.optional<Schema.Number>;
-    readonly output_tokens: Schema.optional<Schema.Number>;
-    readonly total_tokens: Schema.optional<Schema.Number>;
-    readonly input_tokens_details: Schema.optional<Schema.Struct<{
-      readonly cached_tokens: Schema.optional<Schema.Number>;
-    }>>;
-    readonly output_tokens_details: Schema.optional<Schema.Struct<{
-      readonly reasoning_tokens: Schema.optional<Schema.Number>;
-    }>>;
-  }>;
-  readonly stop_reason: Schema.Literals<readonly ["stop", "tool_calls", "max_tokens", "refusal", "content_filter", "max_tool_calls"]>;
-}>;
-type Turn = typeof Turn.Type;
-/**
- * Canonical events emitted while a single turn is being generated. Most
- * variants are streaming deltas (text, reasoning, tool-call args); the
- * terminal `turn_complete` carries the assembled `Turn`. Lifecycle members
- * aren't deltas, hence the union name.
- */
-type TurnEvent = {
-  readonly type: "text_delta";
-  readonly text: string;
-} | {
-  readonly type: "reasoning_delta";
-  readonly text: string;
-  /**
-   * `trace` is the model's raw chain-of-thought; `summary` is a
-   * model-written summary intended for display. OpenAI Responses emits
-   * both as separate wire events; Anthropic and Gemini only emit
-   * `trace`. Consumers who just want any reasoning text match once;
-   * those who want only summaries filter `kind === "summary"`.
-   */
-  readonly kind: "trace" | "summary";
-}
-/**
- * The model declined to answer. `text` is the (streamed) explanation.
- * Distinct from the failure channel: a refusal is normal model output and
- * the stream still completes with `turn_complete`. OpenAI Responses emits
- * this; Anthropic surfaces refusals via `stop_reason`, and Gemini collapses
- * them into `finishReason: SAFETY` - both go without a `refusal_delta`.
- */
-| {
-  readonly type: "refusal_delta";
-  readonly text: string;
-} | {
-  readonly type: "tool_call_start";
-  readonly call_id: string;
-  readonly name: string;
-} | {
-  readonly type: "tool_call_args_delta";
-  readonly call_id: string;
-  readonly delta: string;
-}
-/**
- * Mid-stream cumulative usage. Carries the full `Usage` (including cache
- * token fields when the provider surfaces them) so consumers can drive
- * live budget / cost tracking without waiting for `turn_complete`.
- * Anthropic emits this on `message_start` and `message_delta`; other
- * providers may not emit any `usage_update` and only deliver usage via
- * `turn_complete.turn.usage`.
- */
-| {
-  readonly type: "usage_update";
-  readonly usage: Usage;
-} | {
-  readonly type: "turn_complete";
-  readonly turn: Turn;
-};
-/**
- * What flows out of an agent loop body to its consumer per turn: every
- * `TurnEvent` the provider emits (including the terminal `turn_complete`
- * carrying the assembled `Turn`), plus the output of any tool the loop ran.
- * Both variants carry a `type` discriminator.
- */
-type InteractionEvent = TurnEvent | FunctionCallOutput;
-declare const isTurnComplete: (d: TurnEvent) => d is Extract<TurnEvent, {
-  type: "turn_complete";
-}>;
-declare const functionCalls: (turn: Turn) => ReadonlyArray<FunctionCall>;
-declare const reasonings: (turn: Turn) => ReadonlyArray<Reasoning>;
-declare const assistantMessages: (turn: Turn) => ReadonlyArray<Message>;
-/**
- * Append a completed turn and optional follow-up items to a state record's
- * history. Recipes use this at the point where structured tool results are
- * converted to model-facing `FunctionCallOutput`s.
- */
-declare const appendTurn: <S extends {
-  readonly history: ReadonlyArray<Item>;
-}>(state: S, turn: Turn, items?: ReadonlyArray<Item>) => S;
-/**
- * Project a `TurnEvent` stream onto its `text_delta` payloads. Other
- * variants are dropped. Composes with `Lines.lines` +
- * `decodeJsonLines` for prompted-JSONL streaming.
- */
-declare const textDeltas: <E, R>(self: Stream.Stream<TurnEvent, E, R>) => Stream.Stream<string, E, R>;
-declare const RefusalRejected_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
-  readonly _tag: "RefusalRejected";
-} & Readonly<A>;
-/**
- * The assistant message on the just-completed turn was a refusal block,
- * not an `output_text` payload. Returned by `toStructured` to short-circuit
- * decoding before `JSON.parse` / schema validation runs.
- */
-declare class RefusalRejected extends RefusalRejected_base<{
-  readonly turn: Turn;
-}> {}
-/**
- * Validate a completed `Turn` against a `StructuredFormat`. Concatenates
- * `output_text` blocks on the last assistant message, then runs
- * `JSON.parse` + the format's schema validation.
- *
- * Three failure modes:
- * - `RefusalRejected` — the assistant emitted a refusal block.
- * - `JsonParseError` — the assembled text wasn't valid JSON.
- * - `StructuredDecodeError` — the JSON didn't match the schema.
- */
-declare const toStructured: <A>(turn: Turn, format: StructuredFormat<A>) => Effect.Effect<A, RefusalRejected | JsonParseError | StructuredDecodeError>;
-//#endregion
-export { Turn_d_exports as a, functionCalls as c, textDeltas as d, toStructured as f, TurnEvent as i, isTurnComplete as l, RefusalRejected as n, appendTurn as o, Turn as r, assistantMessages as s, InteractionEvent as t, reasonings as u };
-//# sourceMappingURL=Turn-OPaILVIB.d.mts.map

package/dist/Turn-OPaILVIB.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Turn-OPaILVIB.d.mts","names":[],"sources":["../src/domain/Turn.ts"],"mappings":";;;;;;;;;;;;;;;;cAmBa,IAAA,EAAI,MAAA,CAAA,MAAA;EAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAKL,IAAA,UAAc,IAAA,CAAK,IAAA;;;;;;;KAQnB,SAAA;EAAA,SACG,IAAA;EAAA,SAA6B,IAAA;AAAA;EAAA,SAE7B,IAAA;EAAA,SACA,IAAA;;;;;;;;WAQA,IAAA;AAAA;;;;;;;;;WASA,IAAA;EAAA,SAAgC,IAAA;AAAA;EAAA,SAChC,IAAA;EAAA,SAAkC,OAAA;EAAA,SAA0B,IAAA;AAAA;EAAA,SAC5D,IAAA;EAAA,SAAuC,OAAA;EAAA,SAA0B,KAAA;AAAA;;;;;;;;;;WASjE,IAAA;EAAA,SAA+B,KAAA,EAAO,KAAA;AAAA;EAAA,SACtC,IAAA;EAAA,SAAgC,IAAA,EAAM,IAAA;AAAA;;;;;;;KAQzC,gBAAA,GAAmB,SAAA,GAAY,kBAAA;AAAA,cAE9B,cAAA,GAAkB,CAAA,EAAG,SAAA,KAAY,CAAA,IAAK,OAAA,CAAQ,SAAA;EAAa,IAAA;AAAA;AAAA,cAG3D,aAAA,GAAiB,IAAA,EAAM,IAAA,KAAO,aAAA,CAAc,YAAA;AAAA,cAG5C,UAAA,GAAc,IAAA,EAAM,IAAA,KAAO,aAAA,CAAc,SAAA;AAAA,cAGzC,iBAAA,GAAqB,IAAA,EAAM,IAAA,KAAO,aAAA,CAAc,OAAA;;;;;;cAQhD,UAAA;EAAA,SAAmC,OAAA,EAAS,aAAA,CAAc,IAAA;AAAA,GACrE,KAAA,EAAO,CAAA,EACP,IAAA,EAAM,IAAA,EACN,KAAA,GAAO,aAAA,CAAc,IAAA,MACpB,CAAA;;;;;;cAcU,UAAA,SACX,IAAA,EAAM,MAAA,CAAO,MAAA,CAAO,SAAA,EAAW,CAAA,EAAG,CAAA,MACjC,MAAA,CAAO,MAAA,SAAe,CAAA,EAAG,CAAA;AAAA,cAKzB,oBAAA;;;;;;;;cAWU,eAAA,SAAwB,oBAAA;EAAA,SAC1B,IAAA,EAAM,IAAA;AAAA;;;;;;;;;;;cAyBJ,YAAA,MACX,IAAA,EAAM,IAAA,EACN,MAAA,EAAQ,gBAAA,CAAkC,CAAA,MACzC,MAAA,CAAO,MAAA,CACR,CAAA,EACA,eAAA,GAAkB,cAAA,GAAkC,qBAAA"}