@effect-uai/core 0.15.0 → 0.17.0

package/src/decision-model/Decision.test.ts

@@ -0,0 +1,146 @@
+import { describe, it } from "@effect/vitest"
+import { Effect, Layer, Option, Ref, Schema } from "effect"
+import { expect, expectTypeOf } from "vitest"
+import * as AiError from "../domain/AiError.js"
+import * as Decision from "./Decision.js"
+import { decide, DecisionModel, type DecisionModelService } from "./DecisionModel.js"
+
+const triage = Decision.make({
+  inputSchema: Schema.Struct({ message: Schema.String }),
+  decisions: {
+    department: Decision.classify({
+      instructions: "Which team should handle this?",
+      criteria: { billing: "Payments, invoicing", technical: "Bugs, outages" },
+    }),
+    severity: Decision.rate({
+      instructions: "How severe is it?",
+      criteria: ["Cosmetic", "Degraded", "Blocking"],
+    }),
+    urgent: Decision.probability({ instructions: "Does this convey urgency?" }),
+  },
+})
+
+const fixture = {
+  department: { _tag: "Classify", labels: { billing: 0.62, technical: 0.38 } },
+  severity: { _tag: "Rate", levels: [0, 0.7, 0.3], legend: ["Cosmetic", "Degraded", "Blocking"] },
+  urgent: { _tag: "Probability", probability: 0.94 },
+} as const
+
+/**
+ * A fixed fixture cannot prove it satisfies the caller's `Answers<D>`. This is
+ * the boundary a provider casts at too, once it has decoded the wire.
+ */
+const fixed = <D extends Decision.Decisions>(
+  answers: Readonly<Record<string, Decision.Answer>>,
+): Decision.Answers<D> => answers as Decision.Answers<D>
+
+type Call = { readonly input: unknown; readonly model: string }
+
+/** A `DecisionModel` layer that records what reached it. */
+const recording = Effect.gen(function* () {
+  const calls = yield* Ref.make<ReadonlyArray<Call>>([])
+  const service: DecisionModelService = {
+    decide: (_definition, request) =>
+      Effect.as(
+        Ref.update(calls, (seen) => [...seen, { input: request.input, model: request.model }]),
+        { answers: fixed(fixture), usage: {} },
+      ),
+  }
+  return { calls, layer: Layer.succeed(DecisionModel, service) }
+})
+
+describe("the answer map is derived from the definition", () => {
+  it.effect("keeps each decision's label keys and rejects labels it never had", () =>
+    Effect.gen(function* () {
+      const { calls, layer } = yield* recording
+      const result = yield* decide(triage, {
+        model: "jev-latest",
+        input: { message: "hi" },
+      }).pipe(Effect.provide(layer))
+
+      expectTypeOf(result.answers.department.labels).toEqualTypeOf<{
+        readonly billing: number
+        readonly technical: number
+      }>()
+      // @ts-expect-error shipping is not a label of this decision
+      result.answers.department.labels.shipping
+      // @ts-expect-error a Probability answer has no labels
+      result.answers.urgent.labels
+
+      // `decide` forwards both arguments rather than dropping either.
+      expect(yield* Ref.get(calls)).toEqual([{ input: { message: "hi" }, model: "jev-latest" }])
+    }),
+  )
+
+  it("keeps the rubric as a tuple, so levels are positional rather than parsed", () => {
+    type Severity = (typeof triage)["decisions"]["severity"]
+    expectTypeOf<Decision.AnswerFor<Severity>["levels"]>().toEqualTypeOf<
+      readonly [number, number, number]
+    >()
+    expectTypeOf<Decision.AnswerFor<Severity>["legend"]>().toEqualTypeOf<
+      readonly ["Cosmetic", "Degraded", "Blocking"]
+    >()
+  })
+})
+
+describe("reading an answer", () => {
+  it("derives a Probability answer's distribution as [p, 1 - p]", () => {
+    const [yes, no] = Decision.probabilitiesOf(fixture.urgent)
+    expect(yes).toBeCloseTo(0.94, 10)
+    expect(no).toBeCloseTo(0.06, 10)
+  })
+
+  it("ranks labels best first and names the winner", () => {
+    expect(Decision.ranked(fixture.department)).toEqual([
+      { label: "billing", probability: 0.62 },
+      { label: "technical", probability: 0.38 },
+    ])
+    expect(Decision.winner(fixture.department)).toStrictEqual(Option.some("billing"))
+  })
+
+  it("has no winner for an empty label set", () => {
+    expect(Decision.winner({ _tag: "Classify", labels: {} })).toStrictEqual(Option.none())
+  })
+
+  it("reads a rubric by index and by expected value", () => {
+    expect(Decision.topLevel(fixture.severity)).toBe(1)
+    expect(Decision.expectedLevel(fixture.severity)).toBeCloseTo(1.3, 10)
+    expect(fixture.severity.legend[Decision.topLevel(fixture.severity)]).toBe("Degraded")
+  })
+
+  it("resolves a level tie to the lowest index", () => {
+    expect(Decision.topLevel({ _tag: "Rate", levels: [0.5, 0.5], legend: ["a", "b"] })).toBe(0)
+  })
+
+  it("computes certainty for every kind, including Probability", () => {
+    expect(Decision.confidence(fixture.urgent)).toBeCloseTo(0.67, 2)
+    expect(Decision.margin(fixture.urgent)).toBeCloseTo(0.88, 10)
+    expect(Decision.margin(fixture.department)).toBeCloseTo(0.24, 10)
+  })
+})
+
+describe("assertKinds", () => {
+  const supported = ["Classify", "Probability"] as const
+
+  it.effect("passes when every kind is supported", () => {
+    const { department, urgent } = triage.decisions
+    return Decision.assertKinds({ department, urgent }, supported, "nli")
+  })
+
+  it.effect("fails Unsupported and names every offender at once", () =>
+    Effect.gen(function* () {
+      const decisions = {
+        ...triage.decisions,
+        impact: Decision.rate({ instructions: "How bad?", criteria: ["low", "high"] }),
+      }
+      const error = yield* Effect.flip(Decision.assertKinds(decisions, supported, "nli"))
+
+      expect(error).toBeInstanceOf(AiError.Unsupported)
+      if (error._tag !== "Unsupported") return
+
+      expect(error.reason).toContain('"severity" is a Rate')
+      expect(error.reason).toContain('"impact" is a Rate')
+      expect(error.reason).not.toContain("department")
+    }),
+  )
+})

package/src/decision-model/Decision.ts

@@ -0,0 +1,273 @@
+/**
+ * Typed questions about one input, answered with probabilities.
+ *
+ * A {@link Definition} pairs the shape being read with the questions asked of
+ * it. Build one at module scope and apply it per call with
+ * `DecisionModel.decide`.
+ *
+ * @experimental The model class this abstracts is new and the shape may change.
+ */
+import {
+  Array as A,
+  Effect,
+  Match,
+  Number as N,
+  Option,
+  Order,
+  Record,
+  type Schema,
+  pipe,
+} from "effect"
+import * as AiError from "../domain/AiError.js"
+import * as Probability from "../math/Probability.js"
+
+// ---------------------------------------------------------------------------
+// Criteria
+// ---------------------------------------------------------------------------
+
+/** Labels mapped to what each one means. */
+export type Labels = Readonly<Record<string, string>>
+
+/** An ordered rubric, lowest level first. */
+export type Levels = readonly [string, string, ...ReadonlyArray<string>]
+
+/** What a true and a false answer mean, when the boundary is subtle. */
+export type Boundary = { readonly true?: string; readonly false?: string }
+
+// ---------------------------------------------------------------------------
+// Decisions
+// ---------------------------------------------------------------------------
+
+export type ClassifyDecision<L extends Labels = Labels> = {
+  readonly _tag: "Classify"
+  readonly instructions: string
+  readonly criteria: L
+}
+
+export type RateDecision<V extends Levels = Levels> = {
+  readonly _tag: "Rate"
+  readonly instructions: string
+  readonly criteria: V
+}
+
+export type ProbabilityDecision = {
+  readonly _tag: "Probability"
+  readonly instructions: string
+  readonly criteria?: Boundary
+}
+
+export type Decision = ClassifyDecision | RateDecision | ProbabilityDecision
+
+/** Pick one label. Use {@link rate} when the options form a spectrum. */
+export const classify = <const L extends Labels>(decision: {
+  readonly instructions: string
+  readonly criteria: L
+}): ClassifyDecision<L> => ({ _tag: "Classify", ...decision })
+
+/** Place the input on an ordered rubric. */
+export const rate = <const V extends Levels>(decision: {
+  readonly instructions: string
+  readonly criteria: V
+}): RateDecision<V> => ({ _tag: "Rate", ...decision })
+
+/**
+ * How likely a statement is to hold. Named for its answer rather than for an
+ * act, unlike its siblings, so nobody reads the result as a boolean.
+ */
+export const probability = (decision: {
+  readonly instructions: string
+  readonly criteria?: Boundary
+}): ProbabilityDecision => ({ _tag: "Probability", ...decision })
+
+/** Decisions keyed by the name their answer comes back under. */
+export type Decisions = { readonly [name: string]: Decision }
+
+// ---------------------------------------------------------------------------
+// Definition
+// ---------------------------------------------------------------------------
+
+/**
+ * A reusable decision set bound to the shape it reads.
+ *
+ * `inputSchema` encodes the input on the way out, so a schema that omits a
+ * field keeps it from the model. That projection is the supported way to hold
+ * irrelevant or sensitive context out of a request.
+ */
+export type Definition<A_, D extends Decisions = Decisions> = {
+  readonly inputSchema: Schema.Codec<A_, unknown, any, never>
+  readonly decisions: D
+}
+
+/**
+ * Build a decision set. Declare it once at module scope: the questions and
+ * their rubrics are the reviewed artifact, the input changes per call.
+ *
+ * @example
+ * ```ts
+ * const triage = Decision.make({
+ *   inputSchema: Schema.Struct({ message: Schema.String }),
+ *   decisions: {
+ *     department: Decision.classify({
+ *       instructions: "Which team should handle this?",
+ *       criteria: { billing: "Payments, invoicing", technical: "Bugs, outages" },
+ *     }),
+ *   },
+ * })
+ * ```
+ */
+export const make = <
+  S extends Schema.Codec<any, any, any, never>,
+  const D extends Decisions,
+>(definition: {
+  readonly inputSchema: S
+  readonly decisions: D
+}): Definition<S["Type"], D> => definition
+
+// ---------------------------------------------------------------------------
+// Answers
+// ---------------------------------------------------------------------------
+
+/**
+ * Score contract for {@link ClassifyAnswer.labels} and
+ * {@link RateAnswer.levels}: probabilities sum to 1 within floating-point
+ * error and are comparable within one answer. Whether they are *calibrated*,
+ * so a stated 0.8 means right about 80% of the time, is a property of the
+ * Layer and is documented per provider. No implementor promises calibration
+ * across requests, across decision kinds, or between a statement and its
+ * negation: `P(claim) != 1 - P(not claim)`. A threshold fitted against one
+ * model does not transfer to another.
+ */
+export type ClassifyAnswer<L extends Labels = Labels> = {
+  readonly _tag: "Classify"
+  readonly labels: Readonly<Record<keyof L & string, number>>
+}
+
+export type RateAnswer<V extends Levels = Levels> = {
+  readonly _tag: "Rate"
+  /** Index-aligned with {@link RateAnswer.legend}. */
+  readonly levels: { readonly [K in keyof V]: number }
+  /** The rubric, echoed so an index reads back as prose. */
+  readonly legend: Readonly<V>
+}
+
+export type ProbabilityAnswer = {
+  readonly _tag: "Probability"
+  readonly probability: number
+}
+
+export type Answer = ClassifyAnswer | RateAnswer | ProbabilityAnswer
+
+/** The answer a decision determines, keeping its labels or rubric. */
+export type AnswerFor<D> = D extends {
+  readonly _tag: "Classify"
+  readonly criteria: infer L extends Labels
+}
+  ? ClassifyAnswer<L>
+  : D extends { readonly _tag: "Rate"; readonly criteria: infer V extends Levels }
+    ? RateAnswer<V>
+    : ProbabilityAnswer
+
+/** Answers keyed by their decision's name. */
+export type Answers<D extends Decisions> = { readonly [K in keyof D]: AnswerFor<D[K]> }
+
+// ---------------------------------------------------------------------------
+// Guards
+// ---------------------------------------------------------------------------
+
+/**
+ * Fail `AiError.Unsupported` naming every decision whose kind this provider
+ * cannot express. Bucket 1: omitting an answer would leave a hole where
+ * {@link Answers} promises a key.
+ *
+ * Reports all offenders at once, since the definition is known up front.
+ */
+export const assertKinds = (
+  decisions: Decisions,
+  supported: ReadonlyArray<Decision["_tag"]>,
+  provider: string,
+): Effect.Effect<void, AiError.AiError> => {
+  const offenders = pipe(
+    Record.toEntries(decisions),
+    A.filter(([, decision]) => !supported.includes(decision._tag)),
+    A.map(([name, decision]) => `"${name}" is a ${decision._tag}`),
+  )
+  return offenders.length === 0
+    ? Effect.void
+    : Effect.fail(
+        new AiError.Unsupported({
+          provider,
+          capability: "decision",
+          reason: `${provider} answers ${supported.join(" / ")} only; ${offenders.join(", ")}.`,
+        }),
+      )
+}
+
+// ---------------------------------------------------------------------------
+// Reading an answer
+// ---------------------------------------------------------------------------
+
+/** A `Probability` answer's implied distribution is `[p, 1 - p]`. */
+export const probabilitiesOf: (answer: Answer) => ReadonlyArray<number> = Match.type<Answer>().pipe(
+  Match.discriminatorsExhaustive("_tag")({
+    Classify: (answer) => Record.values(answer.labels),
+    Rate: (answer) => answer.levels,
+    Probability: (answer) => [answer.probability, 1 - answer.probability],
+  }),
+)
+
+/** See {@link Probability.confidence}. Defined for every kind. */
+export const confidence = (answer: Answer): number =>
+  Probability.confidence(probabilitiesOf(answer))
+
+/** See {@link Probability.margin}. Defined for every kind. */
+export const margin = (answer: Answer): number => Probability.margin(probabilitiesOf(answer))
+
+const byProbability = Order.mapInput(
+  Order.flip(Order.Number),
+  (outcome: { readonly probability: number }) => outcome.probability,
+)
+
+/**
+ * Labels best first. Ties keep first-seen order. Also the bridge to rank
+ * fusion: map to `label` and pass alongside another retriever's ordering.
+ */
+export const ranked = <L extends Labels>(
+  answer: ClassifyAnswer<L>,
+): ReadonlyArray<{ readonly label: keyof L & string; readonly probability: number }> =>
+  pipe(
+    Record.toEntries(answer.labels),
+    A.map(([label, probability]) => ({ label, probability })),
+    A.sort(byProbability),
+  )
+
+/** Highest-probability label. `None` only when the label set is empty. */
+export const winner = <L extends Labels>(
+  answer: ClassifyAnswer<L>,
+): Option.Option<keyof L & string> =>
+  pipe(
+    ranked(answer),
+    A.head,
+    Option.map((outcome) => outcome.label),
+  )
+
+/** Index of the highest-probability level. Ties resolve to the lowest. */
+export const topLevel = (answer: RateAnswer): number =>
+  pipe(
+    answer.levels as ReadonlyArray<number>,
+    A.reduce({ index: 0, probability: -Infinity }, (best, probability, index) =>
+      probability > best.probability ? { index, probability } : best,
+    ),
+    (best) => best.index,
+  )
+
+/**
+ * Probability-weighted mean of the level indices, so it can land between
+ * them. Weakly calibrated in practice: a summary, not a magnitude to
+ * interpolate. Use {@link topLevel} with `legend` to name a level instead.
+ */
+export const expectedLevel = (answer: RateAnswer): number =>
+  pipe(
+    answer.levels as ReadonlyArray<number>,
+    A.map((probability, index) => index * probability),
+    N.sumAll,
+  )

package/src/decision-model/DecisionModel.ts

@@ -0,0 +1,53 @@
+import { Context, Effect } from "effect"
+import type * as AiError from "../domain/AiError.js"
+import type * as Decision from "./Decision.js"
+
+/** Optional throughout: not every backing reports token counts. */
+export type DecideUsage = {
+  readonly inputTokens?: number
+  readonly outputTokens?: number
+}
+
+export type DecideResponse<D extends Decision.Decisions = Decision.Decisions> = {
+  readonly answers: Decision.Answers<D>
+  readonly usage: DecideUsage
+}
+
+/**
+ * Cross-provider decide request. The input is billed once for the whole
+ * definition, so batching decisions is cheaper than repeating the input.
+ */
+export type CommonDecideRequest<A> = {
+  readonly input: A
+  /** Each provider narrows this to its typed literal union. */
+  readonly model: string
+}
+
+export type DecisionModelService = {
+  readonly decide: <A, D extends Decision.Decisions>(
+    definition: Decision.Definition<A, D>,
+    request: CommonDecideRequest<A>,
+  ) => Effect.Effect<DecideResponse<D>, AiError.AiError>
+}
+
+/**
+ * Answering typed questions about an input with probabilities instead of
+ * generating text. The model reports beliefs; the decision stays in the
+ * caller's code.
+ *
+ * Implementor contract: answer every decision or fail. Omitting one leaves a
+ * hole where {@link DecideResponse} promises a key, so a kind the backing
+ * cannot express is rejected up front with `Decision.assertKinds`.
+ *
+ * @experimental The model class this abstracts is new and the shape may change.
+ */
+export class DecisionModel extends Context.Service<DecisionModel, DecisionModelService>()(
+  "@betalyra/effect-uai/DecisionModel",
+) {}
+
+/** Answer a definition's decisions about one input in one call. */
+export const decide = <A, D extends Decision.Decisions>(
+  definition: Decision.Definition<A, D>,
+  request: CommonDecideRequest<A>,
+): Effect.Effect<DecideResponse<D>, AiError.AiError, DecisionModel> =>
+  Effect.flatMap(DecisionModel, (m) => m.decide(definition, request))

package/src/domain/AiError.ts

@@ -100,6 +100,15 @@ export class Unsupported extends Data.TaggedError("Unsupported")<{
   reason?: string
 }> {}
 
+/**
+ * A long-lived session hit the provider's lifetime cap. Distinct from
+ * `Unavailable`: reconnecting works, retrying the same session does not.
+ */
+export class SessionExpired extends Data.TaggedError("SessionExpired")<{
+  provider: string
+  raw?: unknown
+}> {}
+
 export type AiError =
   | RateLimited
   | Unavailable
@@ -112,6 +121,7 @@ export type AiError =
   | IncompleteTurn
   | GenerationFailed
   | Unsupported
+  | SessionExpired
 
 const withReason = (base: string, reason: string | undefined): string =>
   reason === undefined ? base : `${base}: ${reason}`
@@ -136,5 +146,6 @@ export const describe: (e: AiError) => string = Match.type<AiError>().pipe(
     IncompleteTurn: () => "the provider stream ended without completing",
     GenerationFailed: (e) => e.message ?? `${e.provider} failed mid-generation`,
     Unsupported: (e) => withReason(`${e.provider} does not support ${e.capability}`, e.reason),
+    SessionExpired: (e) => `the ${e.provider} session reached its lifetime limit`,
   }),
 )

package/src/domain/Realtime.ts

@@ -0,0 +1,101 @@
+/**
+ * Types for a duplex speech-to-speech session: one long-lived connection the
+ * server drives, rather than a caller-driven turn.
+ *
+ * Only what both OpenAI Realtime and Gemini Live do natively lives here. VAD
+ * knobs, truncation, resumption, thinking, grounding and noise reduction are
+ * provider-typed on each adapter's request.
+ */
+import { Data, type Duration } from "effect"
+import type { AudioFormat } from "./Audio.js"
+import type { ImageSource } from "./Image.js"
+import type { HistoryItem, ToolCall, ToolCallOutput, Usage } from "./Items.js"
+import type { ToolDescriptor } from "../tool/Tool.js"
+
+/**
+ * What the caller pushes into a live session.
+ *
+ * - `Audio`: encoded per `request.inputFormat`. The adapter neither paces nor
+ *   buffers; send at real time.
+ * - `Text`: role `system` maps to a system item where the provider has one and
+ *   fails `Unsupported` where it does not.
+ * - `Interrupt`: cancel the response in flight.
+ * - `VideoFrame`: gated by the `RealtimeVideoInput` marker.
+ * - `ActivityStart` / `ActivityEnd`: manual turn detection only; `ActivityEnd`
+ *   also asks for a response. Dropped with a warning on a `"server"` session.
+ * - `PlaybackPosition`: how much of a response the user actually heard, so the
+ *   adapter can trim the rest from context. A no-op where the wire has no
+ *   truncate.
+ */
+export type RealtimeInput = Data.TaggedEnum<{
+  Audio: { readonly bytes: Uint8Array }
+  Text: { readonly text: string; readonly role?: "user" | "system" }
+  ToolResult: { readonly output: ToolCallOutput }
+  Interrupt: {}
+  VideoFrame: { readonly frame: ImageSource }
+  ActivityStart: {}
+  ActivityEnd: {}
+  PlaybackPosition: { readonly responseId: string; readonly playedMs: number }
+}>
+
+export const RealtimeInput = Data.taggedEnum<RealtimeInput>()
+
+/**
+ * What the session emits. Every `AudioDelta` and `OutputTranscriptDelta` is
+ * bracketed by `ResponseStarted` and `ResponseDone` carrying the same
+ * `responseId`.
+ *
+ * - `InputTranscript`: transcription of the user's own speech.
+ * - `SpeechStarted` / `SpeechStopped`: sparse. OpenAI emits them, Gemini
+ *   does not.
+ * - `Interrupted`: stop and flush playback now. Always precedes the
+ *   `ResponseDone { reason: "interrupted" }` for that response.
+ * - `ToolCallCancelled`: calls of an interrupted response that will never be
+ *   answered.
+ * - `ResumptionHandle`: Gemini only; pass it back as `request.resume`.
+ * - `SessionEnding`: the connection is about to close on the server's terms.
+ * - `Error`: non-fatal. A fatal error fails the stream instead.
+ */
+export type RealtimeEvent = Data.TaggedEnum<{
+  ResponseStarted: { readonly responseId: string }
+  AudioDelta: { readonly responseId: string; readonly bytes: Uint8Array }
+  OutputTranscriptDelta: { readonly responseId: string; readonly text: string }
+  InputTranscript: { readonly text: string; readonly final: boolean }
+  SpeechStarted: {}
+  SpeechStopped: {}
+  ToolCall: { readonly responseId: string; readonly call: ToolCall }
+  ToolCallCancelled: { readonly callIds: ReadonlyArray<string> }
+  Interrupted: { readonly responseId: string }
+  ResponseDone: {
+    readonly responseId: string
+    readonly reason: "complete" | "interrupted" | "cancelled" | "error"
+    readonly usage?: Usage
+  }
+  ResumptionHandle: { readonly handle: string }
+  SessionEnding: { readonly timeLeft?: Duration.Duration }
+  Error: { readonly code?: string; readonly message: string }
+}>
+
+export const RealtimeEvent = Data.taggedEnum<RealtimeEvent>()
+
+/**
+ * Cross-provider session setup. Each adapter extends this, narrowing `model`
+ * and adding its own knobs.
+ */
+export type CommonSessionRequest = {
+  readonly model: string
+  readonly instructions?: string
+  readonly voiceId?: string
+  /** `Toolkit.descriptors(toolkit)`. Immutable for the connection on Gemini. */
+  readonly tools?: ReadonlyArray<ToolDescriptor>
+  readonly inputFormat: AudioFormat
+  readonly outputFormat: AudioFormat
+  /** Who decides a turn ended. Defaults to `"server"`. */
+  readonly turnDetection?: "server" | "manual"
+  /** Transcribe the user's own audio. Defaults to `true`. */
+  readonly transcribeInput?: boolean
+  /** Text-only conversation seed. */
+  readonly history?: ReadonlyArray<HistoryItem>
+  /** A `ResumptionHandle` from a previous session. `Unsupported` off Gemini. */
+  readonly resume?: string
+}