@effect-uai/core 0.1.0

package/src/domain/Items.ts

@@ -0,0 +1,260 @@
+import { Schema } from "effect"
+
+// ---------------------------------------------------------------------------
+// Content blocks (inside Message.content)
+// ---------------------------------------------------------------------------
+
+export const InputText = Schema.Struct({
+  type: Schema.Literal("input_text"),
+  text: Schema.String,
+})
+export type InputText = typeof InputText.Type
+
+/**
+ * Where an image lives. `url` covers HTTP(S) URLs (the model fetches
+ * them); `base64` covers inline bytes embedded in the request. Provider
+ * encoders dispatch on `_tag`. File-id / uploaded-asset references are
+ * provider-specific and stay out of this union for now.
+ */
+export const ImageUrlSource = Schema.Struct({
+  _tag: Schema.Literal("url"),
+  url: Schema.String,
+})
+export type ImageUrlSource = typeof ImageUrlSource.Type
+
+/**
+ * Inline image bytes. `data` is **already base64-encoded** (matches what
+ * the wire formats expect; no double-encoding needed downstream).
+ * `media_type` is the MIME type, e.g. `"image/png"`.
+ */
+export const ImageBase64Source = Schema.Struct({
+  _tag: Schema.Literal("base64"),
+  media_type: Schema.String,
+  data: Schema.String,
+})
+export type ImageBase64Source = typeof ImageBase64Source.Type
+
+export const ImageSource = Schema.Union([ImageUrlSource, ImageBase64Source])
+export type ImageSource = typeof ImageSource.Type
+
+export const isImageUrlSource = (s: ImageSource): s is ImageUrlSource => s._tag === "url"
+export const isImageBase64Source = (s: ImageSource): s is ImageBase64Source => s._tag === "base64"
+
+/**
+ * User-provided image content block. Pair with `InputText` inside a
+ * `Message.content` array to ask "what's in this image?" style questions.
+ */
+export const InputImage = Schema.Struct({
+  type: Schema.Literal("input_image"),
+  source: ImageSource,
+})
+export type InputImage = typeof InputImage.Type
+
+// ---------------------------------------------------------------------------
+// Annotations - source / citation pointers attached to `output_text` blocks.
+// Mirrors OpenAI Responses API; other providers can omit or map onto these
+// shapes.
+// ---------------------------------------------------------------------------
+
+export const UrlCitation = Schema.Struct({
+  type: Schema.Literal("url_citation"),
+  url: Schema.String,
+  start_index: Schema.Number,
+  end_index: Schema.Number,
+  title: Schema.String,
+})
+export type UrlCitation = typeof UrlCitation.Type
+
+export const FileCitation = Schema.Struct({
+  type: Schema.Literal("file_citation"),
+  file_id: Schema.String,
+  index: Schema.Number,
+})
+export type FileCitation = typeof FileCitation.Type
+
+export const ContainerFileCitation = Schema.Struct({
+  type: Schema.Literal("container_file_citation"),
+  container_id: Schema.String,
+  file_id: Schema.String,
+  start_index: Schema.Number,
+  end_index: Schema.Number,
+})
+export type ContainerFileCitation = typeof ContainerFileCitation.Type
+
+export const FilePath = Schema.Struct({
+  type: Schema.Literal("file_path"),
+  file_id: Schema.String,
+  index: Schema.Number,
+})
+export type FilePath = typeof FilePath.Type
+
+export const Annotation = Schema.Union([UrlCitation, FileCitation, ContainerFileCitation, FilePath])
+export type Annotation = typeof Annotation.Type
+
+export const isUrlCitation = (a: Annotation): a is UrlCitation => a.type === "url_citation"
+export const isFileCitation = (a: Annotation): a is FileCitation => a.type === "file_citation"
+export const isContainerFileCitation = (a: Annotation): a is ContainerFileCitation =>
+  a.type === "container_file_citation"
+export const isFilePath = (a: Annotation): a is FilePath => a.type === "file_path"
+
+export const OutputText = Schema.Struct({
+  type: Schema.Literal("output_text"),
+  text: Schema.String,
+  annotations: Schema.optional(Schema.Array(Annotation)),
+})
+export type OutputText = typeof OutputText.Type
+
+/**
+ * Model-emitted refusal. Distinct from `output_text`: the model declined
+ * to answer rather than producing normal output. Pair with
+ * `stop_reason: "refusal"` on the surrounding `Turn`. Streamed via the
+ * `refusal_delta` `TurnEvent`.
+ */
+export const Refusal = Schema.Struct({
+  type: Schema.Literal("refusal"),
+  text: Schema.String,
+})
+export type Refusal = typeof Refusal.Type
+
+export const ContentBlock = Schema.Union([InputText, InputImage, OutputText, Refusal])
+export type ContentBlock = typeof ContentBlock.Type
+
+export const Role = Schema.Literals(["user", "assistant", "system"])
+export type Role = typeof Role.Type
+
+// ---------------------------------------------------------------------------
+// Provider passthrough - every Item type carries this opaque slot.
+// The framework never reads or interprets it; provider modules decode
+// their own data via their own typed readers (see e.g.
+// the `@effect-uai/responses` package).
+// ---------------------------------------------------------------------------
+
+const ProviderData = Schema.optional(Schema.Unknown)
+
+// ---------------------------------------------------------------------------
+// Items
+// ---------------------------------------------------------------------------
+
+export const Message = Schema.Struct({
+  type: Schema.Literal("message"),
+  role: Role,
+  content: Schema.Array(ContentBlock),
+  providerData: ProviderData,
+})
+export type Message = typeof Message.Type
+
+export const FunctionCall = Schema.Struct({
+  type: Schema.Literal("function_call"),
+  call_id: Schema.String,
+  name: Schema.String,
+  // JSON-encoded arguments string, mirroring OpenAI Responses API
+  arguments: Schema.String,
+  providerData: ProviderData,
+})
+export type FunctionCall = typeof FunctionCall.Type
+
+export const FunctionCallOutput = Schema.Struct({
+  type: Schema.Literal("function_call_output"),
+  call_id: Schema.String,
+  output: Schema.String,
+  providerData: ProviderData,
+})
+export type FunctionCallOutput = typeof FunctionCallOutput.Type
+
+/**
+ * Reasoning item - top-level, mirrors OpenAI Responses API. Common shape
+ * across providers covers `summary` (human-readable text) and `signature`
+ * (opaque round-trip blob - Anthropic's signed thinking, OpenAI's
+ * encrypted_content, etc.). Provider-specific fields go in `providerData`.
+ */
+export const Reasoning = Schema.Struct({
+  type: Schema.Literal("reasoning"),
+  id: Schema.optional(Schema.String),
+  summary: Schema.optional(Schema.String),
+  signature: Schema.optional(Schema.String),
+  providerData: ProviderData,
+})
+export type Reasoning = typeof Reasoning.Type
+
+export const Item = Schema.Union([Message, FunctionCall, FunctionCallOutput, Reasoning])
+export type Item = typeof Item.Type
+
+// ---------------------------------------------------------------------------
+// Type guards
+// ---------------------------------------------------------------------------
+
+export const isInputText = (block: ContentBlock): block is InputText => block.type === "input_text"
+export const isInputImage = (block: ContentBlock): block is InputImage =>
+  block.type === "input_image"
+export const isOutputText = (block: ContentBlock): block is OutputText =>
+  block.type === "output_text"
+export const isRefusal = (block: ContentBlock): block is Refusal => block.type === "refusal"
+
+export const isMessage = (item: Item): item is Message => item.type === "message"
+export const isFunctionCall = (item: Item): item is FunctionCall => item.type === "function_call"
+export const isFunctionCallOutput = (item: Item): item is FunctionCallOutput =>
+  item.type === "function_call_output"
+export const isReasoning = (item: Item): item is Reasoning => item.type === "reasoning"
+
+// ---------------------------------------------------------------------------
+// Usage and stop reason
+// ---------------------------------------------------------------------------
+
+export const InputTokensDetails = Schema.Struct({
+  cached_tokens: Schema.optional(Schema.Number),
+})
+export type InputTokensDetails = typeof InputTokensDetails.Type
+
+export const OutputTokensDetails = Schema.Struct({
+  reasoning_tokens: Schema.optional(Schema.Number),
+})
+export type OutputTokensDetails = typeof OutputTokensDetails.Type
+
+export const Usage = Schema.Struct({
+  input_tokens: Schema.optional(Schema.Number),
+  output_tokens: Schema.optional(Schema.Number),
+  total_tokens: Schema.optional(Schema.Number),
+  input_tokens_details: Schema.optional(InputTokensDetails),
+  output_tokens_details: Schema.optional(OutputTokensDetails),
+})
+export type Usage = typeof Usage.Type
+
+export const StopReason = Schema.Literals([
+  "stop",
+  "tool_calls",
+  "max_tokens",
+  "refusal",
+  /** Provider-side safety classifier flagged the output. */
+  "content_filter",
+  /** Server-enforced cap on tool calls per turn was hit. */
+  "max_tool_calls",
+])
+export type StopReason = typeof StopReason.Type
+
+// ---------------------------------------------------------------------------
+// Helper constructors
+// ---------------------------------------------------------------------------
+
+export const userText = (text: string): Message => ({
+  type: "message",
+  role: "user",
+  content: [{ type: "input_text", text }],
+})
+
+export const systemText = (text: string): Message => ({
+  type: "message",
+  role: "system",
+  content: [{ type: "input_text", text }],
+})
+
+export const assistantText = (text: string): Message => ({
+  type: "message",
+  role: "assistant",
+  content: [{ type: "output_text", text }],
+})
+
+export const functionCallOutput = (call_id: string, output: string): FunctionCallOutput => ({
+  type: "function_call_output",
+  call_id,
+  output,
+})

package/src/domain/Turn.ts

@@ -0,0 +1,174 @@
+import { Data, Effect, Result, Schema, Stream, pipe } from "effect"
+import * as StructuredFormat from "../structured-format/StructuredFormat.js"
+import {
+  FunctionCall,
+  FunctionCallOutput,
+  Item,
+  isOutputText,
+  isRefusal,
+  Message,
+  Reasoning,
+  StopReason,
+  Usage,
+} from "./Items.js"
+
+/**
+ * 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.
+ */
+export const Turn = Schema.Struct({
+  items: Schema.Array(Item),
+  usage: Usage,
+  stop_reason: StopReason,
+})
+export 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.
+ */
+export 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.
+ */
+export type InteractionEvent = TurnEvent | FunctionCallOutput
+
+export const isTurnComplete = (d: TurnEvent): d is Extract<TurnEvent, { type: "turn_complete" }> =>
+  d.type === "turn_complete"
+
+export const functionCalls = (turn: Turn): ReadonlyArray<FunctionCall> =>
+  turn.items.filter((i): i is FunctionCall => i.type === "function_call")
+
+export const reasonings = (turn: Turn): ReadonlyArray<Reasoning> =>
+  turn.items.filter((i): i is Reasoning => i.type === "reasoning")
+
+export const assistantMessages = (turn: Turn): ReadonlyArray<Message> =>
+  turn.items.filter((i): i is Message => i.type === "message" && i.role === "assistant")
+
+/**
+ * State stamped with the just-completed `Turn`. Recipes use this as the
+ * intermediate value between "turn lands" and "compute next state": extend
+ * `state.history` with the turn's items, and keep the assembled turn
+ * around for stop-reason / usage / function-call inspection.
+ *
+ * Generic over the recipe's state shape - any record carrying a
+ * `history: ReadonlyArray<Item>` field works.
+ */
+export type Cursor<S> = S & { readonly turn: Turn }
+
+/**
+ * Build a `Cursor<S>` from a state record and the just-completed turn.
+ * Extends `state.history` with `turn.items` and stamps the turn.
+ */
+export const cursor = <S extends { readonly history: ReadonlyArray<Item> }>(
+  state: S,
+  turn: Turn,
+): Cursor<S> => ({
+  ...state,
+  history: [...state.history, ...turn.items],
+  turn,
+})
+
+// ---------------------------------------------------------------------------
+// Stream operators
+// ---------------------------------------------------------------------------
+
+/**
+ * Project a `TurnEvent` stream onto its `text_delta` payloads. Other
+ * variants are dropped. Composes with `Lines.lines` +
+ * `decodeJsonLines` for prompted-JSONL streaming.
+ */
+export const textDeltas = <E, R>(
+  self: Stream.Stream<TurnEvent, E, R>,
+): Stream.Stream<string, E, R> =>
+  self.pipe(
+    Stream.filterMap((ev) =>
+      ev.type === "text_delta" ? Result.succeed(ev.text) : Result.failVoid,
+    ),
+  )
+
+// ---------------------------------------------------------------------------
+// Structured-output integration
+// ---------------------------------------------------------------------------
+
+/**
+ * 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.
+ */
+export class RefusalRejected extends Data.TaggedError("RefusalRejected")<{
+  readonly turn: Turn
+}> {}
+
+const lastAssistantContent = (turn: Turn): { readonly text: string; readonly refused: boolean } => {
+  const assistants = assistantMessages(turn)
+  const last = assistants[assistants.length - 1]
+  if (last === undefined) return { text: "", refused: false }
+  if (last.content.some(isRefusal)) return { text: "", refused: true }
+  const text = last.content
+    .filter(isOutputText)
+    .map((b) => b.text)
+    .join("")
+  return { text, refused: false }
+}
+
+/**
+ * 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.
+ */
+export const toStructured = <A>(
+  turn: Turn,
+  format: StructuredFormat.StructuredFormat<A>,
+): Effect.Effect<
+  A,
+  RefusalRejected | StructuredFormat.JsonParseError | StructuredFormat.StructuredDecodeError
+> =>
+  pipe(lastAssistantContent(turn), ({ text, refused }) =>
+    refused ? Effect.fail(new RefusalRejected({ turn })) : StructuredFormat.parseJson(format)(text),
+  )

package/src/index.ts

@@ -0,0 +1,13 @@
+export * as AiError from "./domain/AiError.js"
+export * as Items from "./domain/Items.js"
+export * as Turn from "./domain/Turn.js"
+export * as LanguageModel from "./language-model/LanguageModel.js"
+export * as Loop from "./loop/Loop.js"
+export * as Match from "./match/Match.js"
+export * as Tool from "./tool/Tool.js"
+export * as Toolkit from "./tool/Toolkit.js"
+export * as JSONL from "./streaming/JSONL.js"
+export * as Lines from "./streaming/Lines.js"
+export * as SSE from "./streaming/SSE.js"
+export * as StructuredFormat from "./structured-format/StructuredFormat.js"
+export * as Metrics from "./observability/Metrics.js"

package/src/language-model/LanguageModel.ts

@@ -0,0 +1,73 @@
+import { Context, Effect, Stream } from "effect"
+import * as AiError from "../domain/AiError.js"
+import type { Item } from "../domain/Items.js"
+import type * as StructuredFormat from "../structured-format/StructuredFormat.js"
+import type { ToolDescriptor } from "../tool/Tool.js"
+import { isTurnComplete, type Turn, type TurnEvent } from "../domain/Turn.js"
+
+/**
+ * Cross-provider request shape. Every call carries its own `history` and
+ * `model` - models are not bound at layer construction. Anything specific
+ * to a single provider (reasoning effort, prompt caching, store flags,
+ * ...) lives in that provider's own request interface, which extends this.
+ */
+export interface CommonRequest {
+  readonly history: ReadonlyArray<Item>
+  /**
+   * Model identifier. Each provider narrows this to its typed literal union,
+   * so code that yields a typed provider tag gets autocompletion.
+   */
+  readonly model: string
+  readonly tools?: ReadonlyArray<ToolDescriptor>
+  readonly toolChoice?:
+    | "auto"
+    | "required"
+    | "none"
+    | { readonly type: "function"; readonly name: string }
+  readonly temperature?: number
+  readonly topP?: number
+  readonly maxOutputTokens?: number
+  /**
+   * Schema-bound JSON output. The provider constrains the wire to match the
+   * schema; pair with `Turn.toStructured` for runtime validation. Supported
+   * across all current providers (OpenAI Responses json_schema, Anthropic
+   * `output_config`, Gemini `responseJsonSchema`).
+   */
+  readonly structured?: StructuredFormat.StructuredFormat<unknown>
+}
+
+export interface LanguageModelService {
+  readonly streamTurn: (request: CommonRequest) => Stream.Stream<TurnEvent, AiError.AiError>
+}
+
+export class LanguageModel extends Context.Service<LanguageModel, LanguageModelService>()(
+  "@betalyra/effect-uai/LanguageModel",
+) {}
+
+/**
+ * Stream the deltas of a single turn.
+ */
+export const streamTurn = (
+  request: CommonRequest,
+): Stream.Stream<TurnEvent, AiError.AiError, LanguageModel> =>
+  Stream.unwrap(Effect.map(LanguageModel.asEffect(), (m) => m.streamTurn(request)))
+
+/**
+ * Run a single turn to completion and return the assembled `Turn`.
+ *
+ * Implementation: drain the delta stream and pluck the terminal
+ * `turn_complete` event. The provider is contractually required to emit
+ * exactly one such event as the last delta.
+ */
+export const turn = (request: CommonRequest): Effect.Effect<Turn, AiError.AiError, LanguageModel> =>
+  Effect.flatMap(Stream.runCollect(streamTurn(request)), (deltas) => {
+    const last = deltas[deltas.length - 1]
+    return last !== undefined && isTurnComplete(last)
+      ? Effect.succeed(last.turn)
+      : Effect.fail(
+          new AiError.Unavailable({
+            provider: "unknown",
+            raw: "Provider stream ended without a turn_complete event",
+          }),
+        )
+  })