@effect-uai/core 0.5.1 → 0.6.0

package/src/sandbox/SandboxError.ts

@@ -0,0 +1,140 @@
+import { Data, Duration } from "effect"
+
+/**
+ * Failed to provision a sandbox. Covers image pull failures, region
+ * unavailability, the provider being unreachable, etc. The provider's
+ * structured reason (if any) is on `reason`; the raw error from the
+ * underlying SDK is on `raw`.
+ */
+export class SandboxCreateFailed extends Data.TaggedError("SandboxCreateFailed")<{
+  provider: string
+  reason?: string
+  raw: unknown
+}> {}
+
+/**
+ * The requested sandbox id does not exist (or was already destroyed).
+ * Distinct from `SandboxCreateFailed` — this is for `attach` / `destroy` /
+ * `get`-style lookups against a stale id.
+ */
+export class SandboxNotFound extends Data.TaggedError("SandboxNotFound")<{
+  provider: string
+  id: string
+}> {}
+
+/**
+ * Caller tried to create a sandbox whose id is already taken. Providers
+ * that keyed by name (Microsandbox, Modal) surface this when a previous
+ * sandbox with the same name is still alive. Distinct from
+ * `SandboxCreateFailed` so callers can retry with `replace` semantics.
+ */
+export class SandboxAlreadyExists extends Data.TaggedError("SandboxAlreadyExists")<{
+  provider: string
+  id: string
+}> {}
+
+/**
+ * A shell exec inside the sandbox failed at the transport / SDK layer —
+ * i.e. the SDK couldn't deliver the command to the guest, or the guest
+ * agent itself errored. A non-zero exit code from the guest's command
+ * is NOT an error; it's an `ExecResult` with `exitCode !== 0`.
+ */
+export class SandboxExecFailed extends Data.TaggedError("SandboxExecFailed")<{
+  provider: string
+  reason?: string
+  raw: unknown
+}> {}
+
+/**
+ * A sandbox operation (create, exec, file op) exceeded its time budget.
+ * Carries the budget that was breached for observability.
+ */
+export class SandboxTimeout extends Data.TaggedError("SandboxTimeout")<{
+  provider: string
+  operation: "create" | "exec" | "filesystem" | "attach"
+  budget?: Duration.Duration
+  raw?: unknown
+}> {}
+
+/**
+ * Outbound network request from inside the sandbox was blocked by the
+ * configured egress policy (host not on allowlist, CIDR mismatch, etc.).
+ * Surfaced when the provider's SDK reports the denial back to the host
+ * — many providers simply let the request fail inside the guest and
+ * never report this to the host, in which case this error is never
+ * raised by the adapter.
+ */
+export class SandboxNetworkPolicyDenied extends Data.TaggedError("SandboxNetworkPolicyDenied")<{
+  provider: string
+  host?: string
+  reason?: string
+  raw: unknown
+}> {}
+
+/**
+ * Provider rejected the create / exec because account / org / project
+ * quota or concurrency limit was exceeded. Surfaced separately from
+ * `SandboxCreateFailed` so callers can back off and retry intelligently.
+ */
+export class SandboxQuotaExceeded extends Data.TaggedError("SandboxQuotaExceeded")<{
+  provider: string
+  reason?: string
+  raw: unknown
+}> {}
+
+/**
+ * Caller's request shape is malformed for the wired provider — e.g. a
+ * Dockerfile passed to a provider that only accepts registry refs, a
+ * hostname allowlist passed to a CIDR-only provider, etc. Adapters
+ * should also reject these at the request-schema layer where possible;
+ * this is the runtime fallback.
+ */
+export class SandboxInvalidRequest extends Data.TaggedError("SandboxInvalidRequest")<{
+  provider: string
+  param?: string
+  reason?: string
+  raw?: unknown
+}> {}
+
+/**
+ * Sandbox SDK could not authenticate against the provider. Subtype
+ * mirrors the model-side `AiError.AuthFailed` shape for consistency.
+ */
+export type SandboxAuthSubtype = "auth" | "permission" | "billing" | "quota"
+
+export class SandboxAuthFailed extends Data.TaggedError("SandboxAuthFailed")<{
+  provider: string
+  subtype: SandboxAuthSubtype
+  raw: unknown
+}> {}
+
+/**
+ * The wired provider does not implement the requested capability for
+ * this specific request. Distinct from `SandboxInvalidRequest` (the
+ * request shape is malformed) and from compile-time capability
+ * markers (`SandboxSnapshots`, `SandboxSecretInjection`, …) which gate
+ * blanket provider-level gaps.
+ *
+ * Reserved for request-data-dependent gaps where the provider supports
+ * the method in general but not for these inputs — e.g. passing
+ * `hosts: [...]` to a CIDR-only allowlist provider, or passing
+ * `dockerfile: ...` to a provider whose `SandboxCustomImage` marker
+ * was provided but which only accepts a flat Dockerfile string.
+ */
+export class SandboxUnsupported extends Data.TaggedError("SandboxUnsupported")<{
+  provider: string
+  capability: string
+  reason?: string
+}> {}
+
+export type SandboxError =
+  | SandboxCreateFailed
+  | SandboxNotFound
+  | SandboxAlreadyExists
+  | SandboxExecFailed
+  | SandboxTimeout
+  | SandboxNetworkPolicyDenied
+  | SandboxQuotaExceeded
+  | SandboxInvalidRequest
+  | SandboxAuthFailed
+  | SandboxUnsupported

package/src/sandbox/SandboxImage.ts

@@ -0,0 +1,26 @@
+import { ImageRef, SnapshotId } from "./Sandbox.js"
+
+/**
+ * Ergonomic constructors for {@link ImageRef}. `ImageRef.*` tagged
+ * constructors still exist (and are what pattern-matching code uses);
+ * these helpers are what end users reach for at the call site.
+ *
+ * @example
+ * ```ts
+ * import * as Image from "@effect-uai/core/SandboxImage"
+ *
+ * Image.auto                         // provider's house image
+ * Image.registry("python:3.12")      // OCI registry ref
+ * Image.snapshot("ml-warm-1")        // restore captured state (gated)
+ * Image.dockerfile("FROM ubuntu...") // build custom (gated)
+ * ```
+ */
+
+export const auto: ImageRef = ImageRef.Default()
+
+export const registry = (ref: string): ImageRef => ImageRef.Registry({ ref })
+
+export const snapshot = (id: SnapshotId | string): ImageRef =>
+  ImageRef.Snapshot({ id: SnapshotId(id) })
+
+export const dockerfile = (contents: string): ImageRef => ImageRef.Dockerfile({ contents })

package/src/sandbox/SandboxNetwork.ts

@@ -0,0 +1,34 @@
+import { NetworkPolicy } from "./Sandbox.js"
+
+/**
+ * Ergonomic constructors for {@link NetworkPolicy}. The tagged
+ * constructors under `Sandbox.NetworkPolicy.*` still exist (and are
+ * what pattern-matching code uses); these helpers are what end users
+ * reach for at the call site.
+ *
+ * @example
+ * ```ts
+ * import * as Network from "@effect-uai/core/SandboxNetwork"
+ *
+ * Network.open                                    // provider defaults apply
+ * Network.blocked                                 // airgapped — no egress
+ * Network.allowHosts("api.openai.com", "github.com")
+ * Network.allowCidrs("10.0.0.0/8")
+ * Network.allow({ hosts: [...], cidrs: [...] })   // combined allowlist
+ * ```
+ */
+
+export const open: NetworkPolicy = NetworkPolicy.Open()
+
+export const blocked: NetworkPolicy = NetworkPolicy.Blocked()
+
+export const allowHosts = (...hosts: ReadonlyArray<string>): NetworkPolicy =>
+  NetworkPolicy.Allowlist({ hosts })
+
+export const allowCidrs = (...cidrs: ReadonlyArray<string>): NetworkPolicy =>
+  NetworkPolicy.Allowlist({ cidrs })
+
+export const allow = (opts: {
+  readonly hosts?: ReadonlyArray<string>
+  readonly cidrs?: ReadonlyArray<string>
+}): NetworkPolicy => NetworkPolicy.Allowlist(opts)

package/src/speech-synthesizer/SpeechSynthesizer.test.ts

@@ -106,6 +106,95 @@ describe("SpeechSynthesizer capability marker (compile-time)", () => {
   })
 })
 
+describe("SpeechSynthesizer.synthesizeDialogue", () => {
+  const dialogueReq: SpeechSynthesizer.CommonSynthesizeDialogueRequest = {
+    model: "mock-tts",
+    turns: [
+      { voiceId: "voice-a", text: "Hi" },
+      { voiceId: "voice-b", text: "Hello" },
+    ],
+  }
+
+  it("returns the scripted AudioBlob", async () => {
+    const mock = MockSpeechSynthesizer.layer({ dialogueBlobs: [blob] })
+    const result = await Effect.runPromise(
+      SpeechSynthesizer.synthesizeDialogue(dialogueReq).pipe(Effect.provide(mock.layer)),
+    )
+    expect(result.bytes).toEqual(blob.bytes)
+  })
+
+  it("records the request on the synthesizeDialogue call channel", async () => {
+    const mock = MockSpeechSynthesizer.layer({ dialogueBlobs: [blob] })
+    const program = Effect.gen(function* () {
+      yield* SpeechSynthesizer.synthesizeDialogue(dialogueReq)
+      return yield* mock.recorder
+    })
+    const rec = await Effect.runPromise(program.pipe(Effect.provide(mock.layer)))
+    expect(rec.synthesizeDialogueCalls.length).toBe(1)
+    expect(rec.synthesizeDialogueCalls[0]!.turns.length).toBe(2)
+    expect(rec.synthesizeCalls.length).toBe(0)
+  })
+
+  it("emits scripted chunks for streamSynthesizeDialogue", async () => {
+    const mock = MockSpeechSynthesizer.layer({
+      streamSynthesizeDialogueChunks: [[chunk(7), chunk(8)]],
+    })
+    const out = await Effect.runPromise(
+      Stream.runCollect(SpeechSynthesizer.streamSynthesizeDialogue(dialogueReq)).pipe(
+        Effect.provide(mock.layer),
+      ),
+    )
+    expect(out.map((c) => Array.from(c.bytes))).toEqual([[7], [8]])
+  })
+})
+
+describe("MultiSpeakerTts capability marker (compile-time)", () => {
+  const dialogueReq: SpeechSynthesizer.CommonSynthesizeDialogueRequest = {
+    model: "mock-tts",
+    turns: [{ voiceId: "a", text: "Hi" }],
+  }
+
+  it("requires `MultiSpeakerTts` on the R channel of synthesizeDialogue", () => {
+    const eff = SpeechSynthesizer.synthesizeDialogue(dialogueReq)
+    expectTypeOf(eff).toEqualTypeOf<
+      Effect.Effect<
+        AudioBlob,
+        AiError.AiError,
+        SpeechSynthesizer.SpeechSynthesizer | SpeechSynthesizer.MultiSpeakerTts
+      >
+    >()
+  })
+
+  it("requires `MultiSpeakerTts` on the R channel of streamSynthesizeDialogue", () => {
+    const s = SpeechSynthesizer.streamSynthesizeDialogue(dialogueReq)
+    expectTypeOf(s).toEqualTypeOf<
+      Stream.Stream<
+        AudioChunk,
+        AiError.AiError,
+        SpeechSynthesizer.SpeechSynthesizer | SpeechSynthesizer.MultiSpeakerTts
+      >
+    >()
+  })
+
+  it("a layer without the marker leaves `MultiSpeakerTts` unsatisfied in R", () => {
+    const noMarker = MockSpeechSynthesizer.layerWithoutMultiSpeaker({})
+    const program = SpeechSynthesizer.synthesizeDialogue(dialogueReq).pipe(
+      Effect.provide(noMarker.layer),
+    )
+    expectTypeOf(program).toEqualTypeOf<
+      Effect.Effect<AudioBlob, AiError.AiError, SpeechSynthesizer.MultiSpeakerTts>
+    >()
+  })
+
+  it("a full layer (with marker) clears R to never", () => {
+    const fullMock = MockSpeechSynthesizer.layer({ dialogueBlobs: [blob] })
+    const program = SpeechSynthesizer.synthesizeDialogue(dialogueReq).pipe(
+      Effect.provide(fullMock.layer),
+    )
+    expectTypeOf(program).toEqualTypeOf<Effect.Effect<AudioBlob, AiError.AiError, never>>()
+  })
+})
+
 describe("SpeechSynthesizer.streamSynthesisFrom", () => {
   const ssfReq: SpeechSynthesizer.CommonStreamSynthesizeRequest = {
     model: "mock-tts",

package/src/speech-synthesizer/SpeechSynthesizer.ts

@@ -2,6 +2,34 @@ import { Context, Effect, Function, Stream } from "effect"
 import * as AiError from "../domain/AiError.js"
 import type { AudioBlob, AudioChunk, AudioFormat } from "../domain/Audio.js"
 
+/**
+ * Phonetic alphabets accepted by `CustomPronunciation`. Not every
+ * provider supports every alphabet — adapters translate or warn+drop
+ * unsupported entries.
+ *
+ * - `ipa` — universal lowest common denominator (Google, ElevenLabs,
+ *   Inworld, Deepgram, Cartesia, MiniMax).
+ * - `x-sampa` — Google Cloud TTS.
+ * - `cmu-arpabet` — ElevenLabs `eleven_flash_v2` / `eleven_english_v1`.
+ */
+export type PhoneticEncoding = "ipa" | "x-sampa" | "cmu-arpabet"
+
+/**
+ * Per-phrase pronunciation override. The same shape unifies the
+ * structured-field providers (Google) and the inline-markup providers
+ * (ElevenLabs SSML, Inworld `/ipa/`, Deepgram, Cartesia, MiniMax) — the
+ * adapter does the wire translation.
+ *
+ * Unsupported alphabets are dropped at the adapter with a structured
+ * `logWarning` (one per call). The audio still renders, just without
+ * the override.
+ */
+export type CustomPronunciation = {
+  readonly phrase: string
+  readonly pronunciation: string
+  readonly encoding: PhoneticEncoding
+}
+
 /**
  * Cross-provider synthesis request. Provider-specific extensions
  * (ElevenLabs `stability` / `similarity_boost`, Cartesia `emotion`,
@@ -23,6 +51,14 @@ export type CommonSynthesizeRequest = {
   readonly outputFormat?: AudioFormat
   readonly speed?: number
   readonly languageCode?: string
+  /**
+   * Phoneme overrides for specific phrases. 7 of 9 TTS providers
+   * support some form of this; adapters either translate to a
+   * structured field, rewrite `text` inline, or `warn+drop` per-entry
+   * for alphabets they don't accept. OpenAI rejects non-empty arrays
+   * with `Unsupported`.
+   */
+  readonly pronunciations?: ReadonlyArray<CustomPronunciation>
 }
 
 /**
@@ -36,6 +72,34 @@ export type CommonSynthesizeRequest = {
  */
 export type CommonStreamSynthesizeRequest = Omit<CommonSynthesizeRequest, "text">
 
+/**
+ * One turn in a multi-speaker dialogue.
+ *
+ * `styleDescription` and `speed` are honored by providers that expose
+ * per-turn knobs (Hume Octave-2) and silently ignored by others
+ * (ElevenLabs `/v1/text-to-dialogue` accepts `{voice_id, text}` only;
+ * Google Gemini TTS multi-speaker has no per-turn styling).
+ */
+export type DialogueTurn = {
+  readonly voiceId: string
+  readonly text: string
+  readonly styleDescription?: string
+  readonly speed?: number
+}
+
+/**
+ * Cross-provider dialogue request. Same return type as `synthesize` —
+ * one continuous `AudioBlob`. Per-turn timing metadata is not exposed
+ * in the common shape (only Hume returns it natively).
+ */
+export type CommonSynthesizeDialogueRequest = {
+  readonly model: string
+  readonly turns: ReadonlyArray<DialogueTurn>
+  readonly outputFormat?: AudioFormat
+  readonly languageCode?: string
+  readonly pronunciations?: ReadonlyArray<CustomPronunciation>
+}
+
 export type SpeechSynthesizerService = {
   /** One-shot. Full text in, full audio bytes out. Universally supported. */
   readonly synthesize: (
@@ -62,6 +126,26 @@ export type SpeechSynthesizerService = {
     textIn: Stream.Stream<string, E, R>,
     request: CommonStreamSynthesizeRequest,
   ) => Stream.Stream<AudioChunk, AiError.AiError | E, R>
+  /**
+   * One-shot multi-speaker dialogue. Turn array in, single `AudioBlob`
+   * out. Providers without native dialogue support return
+   * `AiError.Unsupported` and do NOT ship the `MultiSpeakerTts` marker
+   * — calls via the top-level helper become a compile-time error.
+   */
+  readonly synthesizeDialogue: (
+    request: CommonSynthesizeDialogueRequest,
+  ) => Effect.Effect<AudioBlob, AiError.AiError>
+  /**
+   * Chunked-streaming variant of `synthesizeDialogue`. Same input,
+   * audio chunks emitted as the wire delivers them. Providers that
+   * synthesize the whole dialogue server-side may fall back to a
+   * single-chunk wrap of the sync result.
+   *
+   * Gated by `MultiSpeakerTts` at the top-level helper.
+   */
+  readonly streamSynthesizeDialogue: (
+    request: CommonSynthesizeDialogueRequest,
+  ) => Stream.Stream<AudioChunk, AiError.AiError>
 }
 
 export class SpeechSynthesizer extends Context.Service<
@@ -83,6 +167,19 @@ export class TtsIncrementalText extends Context.Service<TtsIncrementalText, void
   "@betalyra/effect-uai/capability/TtsIncrementalText",
 ) {}
 
+/**
+ * Capability marker for multi-speaker dialogue. Shipped by provider
+ * Layers whose `synthesizeDialogue` is wired to a native multi-speaker
+ * endpoint (ElevenLabs `/v1/text-to-dialogue`, Hume `/v0/tts` with
+ * `utterances[]`, Google Cloud TTS Gemini TTS `multiSpeakerMarkup`).
+ * Other providers leave the marker unregistered so the top-level
+ * `synthesizeDialogue` / `streamSynthesizeDialogue` helpers fail to
+ * satisfy R against those Layers — compile-time error.
+ */
+export class MultiSpeakerTts extends Context.Service<MultiSpeakerTts, void>()(
+  "@betalyra/effect-uai/capability/MultiSpeakerTts",
+) {}
+
 /** One-shot synthesis. */
 export const synthesize = (
   request: CommonSynthesizeRequest,
@@ -129,3 +226,30 @@ export const streamSynthesisFrom: {
       }),
     ),
 )
+
+/**
+ * One-shot multi-speaker dialogue. Requires `MultiSpeakerTts` in R —
+ * providers without dialogue support are a compile-time error.
+ */
+export const synthesizeDialogue = (
+  request: CommonSynthesizeDialogueRequest,
+): Effect.Effect<AudioBlob, AiError.AiError, SpeechSynthesizer | MultiSpeakerTts> =>
+  Effect.gen(function* () {
+    const s = yield* SpeechSynthesizer.asEffect()
+    yield* MultiSpeakerTts.asEffect()
+    return yield* s.synthesizeDialogue(request)
+  })
+
+/**
+ * Chunked-streaming variant. Same R requirement as `synthesizeDialogue`.
+ */
+export const streamSynthesizeDialogue = (
+  request: CommonSynthesizeDialogueRequest,
+): Stream.Stream<AudioChunk, AiError.AiError, SpeechSynthesizer | MultiSpeakerTts> =>
+  Stream.unwrap(
+    Effect.gen(function* () {
+      const s = yield* SpeechSynthesizer.asEffect()
+      yield* MultiSpeakerTts.asEffect()
+      return s.streamSynthesizeDialogue(request)
+    }),
+  )

package/src/testing/MockProvider.ts

@@ -1,7 +1,11 @@
 import { Array as Arr, Duration, Effect, Layer, Match, Option, Ref, Schedule, Stream } from "effect"
 import * as AiError from "../domain/AiError.js"
-import { type Item, isOutputText } from "../domain/Items.js"
-import { LanguageModel, type LanguageModelService } from "../language-model/LanguageModel.js"
+import { type HistoryItem, isOutputText } from "../domain/Items.js"
+import {
+  LanguageModel,
+  type LanguageModelService,
+  turnFromStream,
+} from "../language-model/LanguageModel.js"
 import { type Turn, TurnEvent } from "../domain/Turn.js"
 
 export type MockOptions = {
@@ -14,7 +18,7 @@ export type MockOptions = {
 }
 
 export type Call = {
-  readonly history: ReadonlyArray<Item>
+  readonly history: ReadonlyArray<HistoryItem>
   readonly turn: Turn
 }
 
@@ -32,24 +36,25 @@ export type MockRecorder = {
 // Pure projection: Turn → ReadonlyArray<TurnEvent>
 // ---------------------------------------------------------------------------
 
-const itemToDeltas: (item: Item) => ReadonlyArray<TurnEvent> = Match.type<Item>().pipe(
-  Match.discriminators("type")({
-    message: (m): ReadonlyArray<TurnEvent> =>
-      m.role === "assistant"
-        ? m.content.filter(isOutputText).map((b) => TurnEvent.TextDelta({ text: b.text }))
-        : [],
-    function_call: (fc) => [
-      TurnEvent.ToolCallStart({ call_id: fc.call_id, name: fc.name }),
-      TurnEvent.ToolCallArgsDelta({ call_id: fc.call_id, delta: fc.arguments }),
-    ],
-    function_call_output: () => [],
-    reasoning: (r) =>
-      r.summary !== undefined
-        ? [TurnEvent.ReasoningDelta({ text: r.summary, kind: "summary" as const })]
-        : [],
-  }),
-  Match.exhaustive,
-)
+const itemToDeltas: (item: HistoryItem) => ReadonlyArray<TurnEvent> =
+  Match.type<HistoryItem>().pipe(
+    Match.discriminators("type")({
+      message: (m): ReadonlyArray<TurnEvent> =>
+        m.role === "assistant"
+          ? m.content.filter(isOutputText).map((b) => TurnEvent.TextDelta({ text: b.text }))
+          : [],
+      function_call: (fc) => [
+        TurnEvent.ToolCallStart({ call_id: fc.call_id, name: fc.name }),
+        TurnEvent.ToolCallArgsDelta({ call_id: fc.call_id, delta: fc.arguments }),
+      ],
+      function_call_output: () => [],
+      reasoning: (r) =>
+        r.summary !== undefined
+          ? [TurnEvent.ReasoningDelta({ text: r.summary, kind: "summary" as const })]
+          : [],
+    }),
+    Match.exhaustive,
+  )
 
 const turnToDeltas = (turn: Turn): ReadonlyArray<TurnEvent> => [
   ...turn.items.flatMap(itemToDeltas),
@@ -81,8 +86,8 @@ const buildService = (
   options: MockOptions | undefined,
   cursor: Ref.Ref<number>,
   record: (call: Call) => Effect.Effect<void>,
-): LanguageModelService => ({
-  streamTurn: (request) =>
+): LanguageModelService => {
+  const streamTurn: LanguageModelService["streamTurn"] = (request) =>
     Stream.unwrap(
       Ref.getAndUpdate(cursor, (n) => n + 1).pipe(
         Effect.flatMap(
@@ -96,8 +101,9 @@ const buildService = (
             }),
         ),
       ),
-    ),
-})
+    )
+  return { streamTurn, turn: turnFromStream(streamTurn) }
+}
 
 // ---------------------------------------------------------------------------
 // Recorder handle. Unsafe Ref is local: it backs both the `record` write