@effect-uai/core 0.13.0 → 0.15.0

package/src/image-generator/ImageGenerator.ts

@@ -0,0 +1,165 @@
+import { Context, Data, Effect, Stream } from "effect"
+import type * as AiError from "../domain/AiError.js"
+import type {
+  AspectRatio,
+  GeneratedImage,
+  ImageResolution,
+  ImageSource,
+  ProviderData,
+} from "../domain/Image.js"
+
+export type { AspectRatio, GeneratedImage, ImageResolution, ProviderData } from "../domain/Image.js"
+
+/**
+ * Cross-provider text-to-image request. Shape and resolution are given
+ * as a ratio plus a tier rather than exact pixels: every provider takes
+ * one or derives the other. Exact dimensions, quality tiers, output
+ * encodings, and moderation knobs are vendor-specific and live on each
+ * provider's typed request.
+ */
+export type CommonImageGenerateRequest = {
+  readonly prompt: string
+  /** Each provider narrows this to its typed literal union. */
+  readonly model: string
+  readonly aspectRatio?: AspectRatio
+  readonly resolution?: ImageResolution
+  /** Default 1. Implementors without multi-image output fail `Unsupported` for more. */
+  readonly n?: number
+}
+
+/**
+ * Edit request: the same prompt-driven generation, conditioned on
+ * reference images. Separate from `generate` because the reference set
+ * is required here and absent there, and providers expose the two as
+ * distinct wire shapes. Per-provider caps on the array length apply.
+ */
+export type CommonImageEditRequest = CommonImageGenerateRequest & {
+  readonly images: ReadonlyArray<ImageSource>
+}
+
+/** Gated by {@link ImageStreaming}; `partialImages` is the preview-frame count. */
+export type CommonStreamImageRequest = CommonImageGenerateRequest & {
+  readonly partialImages: 1 | 2 | 3
+}
+
+/** The same previews, for an edit. Gated by {@link ImageStreaming}. */
+export type CommonStreamImageEditRequest = CommonImageEditRequest & {
+  readonly partialImages: 1 | 2 | 3
+}
+
+/** Optional throughout: not every provider bills or reports per token. */
+export type ImageUsage = {
+  readonly inputTokens?: number
+  readonly outputTokens?: number
+  readonly totalTokens?: number
+}
+
+export type ImageResponse = {
+  readonly images: ReadonlyArray<GeneratedImage>
+  readonly usage: ImageUsage
+  /**
+   * Response-level extras, keyed by provider name: the seed a request
+   * resolved to, timings, safety flags. Per-image extras live on each
+   * {@link GeneratedImage} instead. See `Image.ProviderData`.
+   */
+  readonly providerData?: ProviderData
+}
+
+/**
+ * Zero or more `PartialImage` previews, then exactly one `Complete`.
+ * `Complete` carries the `ImageResponse` fields flat, so it is
+ * assignable to `ImageResponse` and needs no unwrapping.
+ */
+export type ImageStreamEvent = Data.TaggedEnum<{
+  PartialImage: {
+    readonly image: ImageSource
+    /** Counts from 0 in emission order. */
+    readonly index: number
+  }
+  Complete: {
+    readonly images: ReadonlyArray<GeneratedImage>
+    readonly usage: ImageUsage
+  }
+}>
+
+/**
+ * Namespace of constructors, type guards, and matchers for
+ * `ImageStreamEvent`, provided by `Data.taggedEnum`.
+ */
+export const ImageStreamEvent = Data.taggedEnum<ImageStreamEvent>()
+
+export const isPartialImage = ImageStreamEvent.$is("PartialImage")
+export const isComplete = ImageStreamEvent.$is("Complete")
+
+export type ImageGeneratorService = {
+  /** Prompt in, images out. Universally supported. */
+  readonly generate: (
+    request: CommonImageGenerateRequest,
+  ) => Effect.Effect<ImageResponse, AiError.AiError>
+  /** Prompt plus reference images in, images out. Universally supported. */
+  readonly edit: (request: CommonImageEditRequest) => Effect.Effect<ImageResponse, AiError.AiError>
+  /**
+   * Preview frames as the image resolves, then the final response.
+   * Implementors without a partial-image wire return `Unsupported` and
+   * do NOT register {@link ImageStreaming}, so the top-level helper is
+   * a compile-time error against their Layer.
+   */
+  readonly streamGeneration: (
+    request: CommonStreamImageRequest,
+  ) => Stream.Stream<ImageStreamEvent, AiError.AiError>
+  /** {@link streamGeneration} conditioned on reference images. */
+  readonly streamEdit: (
+    request: CommonStreamImageEditRequest,
+  ) => Stream.Stream<ImageStreamEvent, AiError.AiError>
+}
+
+export class ImageGenerator extends Context.Service<ImageGenerator, ImageGeneratorService>()(
+  "@betalyra/effect-uai/ImageGenerator",
+) {}
+
+/**
+ * Capability marker for partial-image streaming. Phantom: the value is
+ * `void`, providers register with
+ * `Layer.succeed(ImageStreaming, undefined)`. Calling
+ * {@link streamGeneration} while only a non-streaming Layer is in scope
+ * fails at `Effect.provide` with a type error.
+ */
+export class ImageStreaming extends Context.Service<ImageStreaming, void>()(
+  "@betalyra/effect-uai/capability/ImageStreaming",
+) {}
+
+/** Text to image. */
+export const generate = (
+  request: CommonImageGenerateRequest,
+): Effect.Effect<ImageResponse, AiError.AiError, ImageGenerator> =>
+  Effect.flatMap(ImageGenerator, (g) => g.generate(request))
+
+/** Text plus reference images to image. */
+export const edit = (
+  request: CommonImageEditRequest,
+): Effect.Effect<ImageResponse, AiError.AiError, ImageGenerator> =>
+  Effect.flatMap(ImageGenerator, (g) => g.edit(request))
+
+/** Preview frames then the final response. Requires {@link ImageStreaming} in R. */
+export const streamGeneration = (
+  request: CommonStreamImageRequest,
+): Stream.Stream<ImageStreamEvent, AiError.AiError, ImageGenerator | ImageStreaming> =>
+  Stream.unwrap(
+    Effect.gen(function* () {
+      const g = yield* ImageGenerator
+      yield* ImageStreaming
+      return g.streamGeneration(request)
+    }),
+  )
+
+/** The same, conditioned on reference images. Requires {@link ImageStreaming} in R. */
+export const streamEdit = (
+  request: CommonStreamImageEditRequest,
+): Stream.Stream<ImageStreamEvent, AiError.AiError, ImageGenerator | ImageStreaming> =>
+  Stream.unwrap(
+    Effect.gen(function* () {
+      const g = yield* ImageGenerator
+      yield* ImageStreaming
+      return g.streamEdit(request)
+    }),
+  )

package/src/inbox/Inbox.test.ts

@@ -0,0 +1,52 @@
+import { describe, it } from "@effect/vitest"
+import { Effect, Fiber, Option, Queue } from "effect"
+import { TestClock } from "effect/testing"
+import { expect } from "vitest"
+import { drainBurst } from "./Inbox.js"
+
+describe("drainBurst", () => {
+  it.effect("resets the window on every arrival, so a burst outlives one settle", () =>
+    Effect.gen(function* () {
+      const queue = yield* Queue.unbounded<string>()
+      const burst = yield* Effect.forkChild(drainBurst(queue, "1 second"))
+
+      yield* Queue.offer(queue, "a")
+      yield* TestClock.adjust("900 millis")
+      yield* Queue.offer(queue, "b")
+      yield* TestClock.adjust("900 millis")
+      // 1.8s elapsed, more than one settle, and the burst is still open.
+      expect(burst.pollUnsafe()).toBeUndefined()
+
+      yield* TestClock.adjust("1 second")
+      expect(yield* Fiber.join(burst)).toEqual(["a", "b"])
+    }),
+  )
+
+  it.effect("waits for the first item without a deadline", () =>
+    Effect.gen(function* () {
+      const queue = yield* Queue.unbounded<string>()
+      const burst = yield* Effect.forkChild(drainBurst(queue, "1 second"))
+
+      yield* TestClock.adjust("1 hour")
+      expect(burst.pollUnsafe()).toBeUndefined()
+
+      yield* Queue.offer(queue, "late")
+      yield* TestClock.adjust("1 second")
+      expect(yield* Fiber.join(burst)).toEqual(["late"])
+    }),
+  )
+
+  it.effect("ends on the first quiet gap and leaves later items for the next drain", () =>
+    Effect.gen(function* () {
+      const queue = yield* Queue.unbounded<string>()
+      const burst = yield* Effect.forkChild(drainBurst(queue, "1 second"))
+
+      yield* Queue.offer(queue, "first")
+      yield* TestClock.adjust("1 second")
+      expect(yield* Fiber.join(burst)).toEqual(["first"])
+
+      yield* Queue.offer(queue, "second")
+      expect(yield* Queue.poll(queue)).toEqual(Option.some("second"))
+    }),
+  )
+})

package/src/inbox/Inbox.ts

@@ -0,0 +1,33 @@
+/**
+ * Input a long-lived agent reads between turns. A chat user rarely sends one
+ * tidy message: they type three lines in a row, then go quiet. The loop wants
+ * that as one batch, taken at a clean turn boundary.
+ */
+import { Array as Arr, type Duration, Effect, Option, Queue } from "effect"
+
+/**
+ * Block for the first item, then keep taking while the next one lands within
+ * `settle` of the previous. The window resets on every arrival, so a burst
+ * becomes one batch and a lone message followed by silence returns at once.
+ *
+ * A take that loses to the window is interrupted before it removes anything,
+ * so late arrivals stay queued for the next drain.
+ */
+export const drainBurst = <A, E>(
+  queue: Queue.Dequeue<A, E>,
+  settle: Duration.Input,
+): Effect.Effect<Arr.NonEmptyReadonlyArray<A>, E> => {
+  const settled = (
+    batch: Arr.NonEmptyReadonlyArray<A>,
+  ): Effect.Effect<Arr.NonEmptyReadonlyArray<A>, E> =>
+    Queue.take(queue).pipe(
+      Effect.timeoutOption(settle),
+      Effect.flatMap(
+        Option.match({
+          onNone: () => Effect.succeed(batch),
+          onSome: (item) => settled(Arr.append(batch, item)),
+        }),
+      ),
+    )
+  return Effect.flatMap(Queue.take(queue), (first) => settled([first]))
+}

package/src/index.ts

@@ -17,7 +17,11 @@ export * as Transcript from "./domain/Transcript.js"
 export * as Turn from "./domain/Turn.js"
 export * as Embedding from "./embedding-model/Embedding.js"
 export * as EmbeddingModel from "./embedding-model/EmbeddingModel.js"
+export * as ImageGenerator from "./image-generator/ImageGenerator.js"
 export * as LanguageModel from "./language-model/LanguageModel.js"
+export * as Messenger from "./messenger/Messenger.js"
+export * as MessengerAdapter from "./messenger/MessengerAdapter.js"
+export * as MessengerError from "./messenger/MessengerError.js"
 export * as MusicGenerator from "./music-generator/MusicGenerator.js"
 export * as Reranker from "./reranker/Reranker.js"
 export * as Memory from "./sandbox/Memory.js"
@@ -33,6 +37,7 @@ export * as WebSearch from "./web-search/WebSearch.js"
 export * as WebSearchTool from "./web-search/WebSearchTool.js"
 export * as Vector from "./math/Vector.js"
 export * as Tokenizer from "./tokenizer/Tokenizer.js"
+export * as Inbox from "./inbox/Inbox.js"
 export * as Loop from "./loop/Loop.js"
 export * as Retry from "./retry/Retry.js"
 export * as Tool from "./tool/Tool.js"
@@ -43,6 +48,7 @@ export * as Approval from "./tool/Approval.js"
 export * as HistoryCheck from "./tool/HistoryCheck.js"
 export * as JSONL from "./streaming/JSONL.js"
 export * as Lines from "./streaming/Lines.js"
+export * as Multipart from "./streaming/Multipart.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/messenger/Messenger.ts

@@ -0,0 +1,293 @@
+import { Brand, Context, Data, Effect, type Option, type Scope, Stream } from "effect"
+import type { MediaSource } from "../domain/Media.js"
+import type * as MessengerError from "./MessengerError.js"
+
+// ---------------------------------------------------------------------------
+// Identity
+// ---------------------------------------------------------------------------
+
+/** Where messages go. Providers mint these per their own scheme; core treats them opaquely. */
+export type ChannelId = Brand.Branded<string, "ChannelId">
+export const ChannelId = Brand.nominal<ChannelId>()
+
+/** One message inside a channel. Only a named message can be edited or reacted to. */
+export type MessageId = Brand.Branded<string, "MessageId">
+export const MessageId = Brand.nominal<MessageId>()
+
+/** The human (or bot) an event came from. */
+export type UserId = Brand.Branded<string, "UserId">
+export const UserId = Brand.nominal<UserId>()
+
+/** A sub-conversation inside a channel, where the platform has one. Opaque, provider-minted. */
+export type ThreadId = Brand.Branded<string, "ThreadId">
+export const ThreadId = Brand.nominal<ThreadId>()
+
+/**
+ * Where a conversation happens. `thread` is provider-interpreted: a Slack
+ * `thread_ts`, a Telegram forum topic, unset on Discord (where a thread is
+ * its own channel).
+ */
+export type ConversationRef = {
+  readonly channel: ChannelId
+  readonly thread?: ThreadId
+}
+
+export type MessageRef = {
+  readonly conversation: ConversationRef
+  readonly id: MessageId
+}
+
+/** Stable key for a conversation. Index per-conversation state with it. */
+export const conversationKey = (ref: ConversationRef): string =>
+  ref.thread === undefined ? ref.channel : `${ref.channel}/${ref.thread}`
+
+// ---------------------------------------------------------------------------
+// Inbound
+// ---------------------------------------------------------------------------
+
+/**
+ * What the world says to the agent. `raw` is the untouched platform payload,
+ * for everything the shared shape drops.
+ *
+ * `addressed` is the rule recipes branch on: a DM, a mention of the bot, or
+ * a reply to one of its messages. Each adapter owns that decision (and hides
+ * Telegram privacy mode / Discord intents behind it), and delivers `text`
+ * with the bot's own mention stripped.
+ *
+ * `Reaction.emoji` is the platform's own spelling, the same one `react`
+ * accepts: unicode where the platform speaks unicode, a shortcode where it
+ * speaks shortcodes.
+ */
+export type InboundEvent = Data.TaggedEnum<{
+  Message: {
+    readonly conversation: ConversationRef
+    readonly id: MessageId
+    readonly author: UserId
+    readonly text: string
+    readonly addressed: boolean
+    readonly replyTo?: MessageId
+    readonly raw: unknown
+  }
+  Reaction: {
+    readonly conversation: ConversationRef
+    readonly message: MessageId
+    readonly emoji: string
+    readonly author: UserId
+    readonly raw: unknown
+  }
+  Command: {
+    readonly conversation: ConversationRef
+    readonly name: string
+    readonly args: string
+    readonly author: UserId
+    readonly raw: unknown
+  }
+  Action: {
+    readonly conversation: ConversationRef
+    readonly actionId: string
+    readonly value?: string
+    readonly author: UserId
+    readonly raw: unknown
+  }
+}>
+
+export const InboundEvent = Data.taggedEnum<InboundEvent>()
+
+// ---------------------------------------------------------------------------
+// Outbound
+// ---------------------------------------------------------------------------
+
+/**
+ * What the agent says. `Text` is sent verbatim: each provider layer says
+ * which markup it expects (Telegram HTML, Slack markdown), and the prompt is
+ * where that gets decided. Nothing here converts. `Media` reuses the core
+ * {@link MediaSource}, so a URL, base64 or raw bytes all work; the adapter
+ * routes on `mimeType` (`image/*` to a photo endpoint, `audio/*` to an audio
+ * one, everything else to a file upload), which is why a URL source without
+ * a `mimeType` goes as a plain file. `Raw` bypasses the shape entirely and
+ * reaches the platform as-is: the escape hatch for buttons, cards and
+ * everything the verbs do not unify.
+ */
+export type OutboundBody = Data.TaggedEnum<{
+  Text: { readonly text: string }
+  Media: {
+    readonly media: MediaSource
+    readonly caption?: string
+    readonly filename?: string
+  }
+  Raw: { readonly payload: unknown }
+}>
+
+export const OutboundBody = Data.taggedEnum<OutboundBody>()
+
+/**
+ * A body plus the envelope fields true of any message. `replyTo` is ignored
+ * for a `Raw` body, which names its own wire fields.
+ */
+export type Outbound = {
+  readonly body: OutboundBody
+  readonly replyTo?: MessageId
+}
+
+export type OutboundOptions = { readonly replyTo?: MessageId }
+
+const envelope = (body: OutboundBody, options?: OutboundOptions): Outbound => ({
+  body,
+  ...(options?.replyTo !== undefined && { replyTo: options.replyTo }),
+})
+
+/** Text message. The overwhelmingly common case: `post(text("hi"))`. */
+export const text = (body: string, options?: OutboundOptions): Outbound =>
+  envelope(OutboundBody.Text({ text: body }), options)
+
+/** Media message. `caption` and `filename` describe the media, not the envelope. */
+export const media = (
+  source: MediaSource,
+  options?: OutboundOptions & { readonly caption?: string; readonly filename?: string },
+): Outbound =>
+  envelope(
+    OutboundBody.Media({
+      media: source,
+      ...(options?.caption !== undefined && { caption: options.caption }),
+      ...(options?.filename !== undefined && { filename: options.filename }),
+    }),
+    options,
+  )
+
+/** Platform payload, passed through untouched. */
+export const raw = (payload: unknown): Outbound => ({ body: OutboundBody.Raw({ payload }) })
+
+// ---------------------------------------------------------------------------
+// Ambient conversation targeting
+// ---------------------------------------------------------------------------
+
+/**
+ * The conversation the outbound verbs target. A tag with no default, so
+ * posting outside an established conversation is a compile error. Deep code
+ * (a tool posting progress, an approval resolver) inherits it rather than
+ * threading a ref down.
+ */
+export class CurrentConversation extends Context.Service<CurrentConversation, ConversationRef>()(
+  "@betalyra/effect-uai/Messenger/CurrentConversation",
+) {}
+
+/** Run `effect` against `ref`. Wrap a conversation fiber once; every nested post lands. */
+export const inConversation =
+  (ref: ConversationRef) =>
+  <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, Exclude<R, CurrentConversation>> =>
+    Effect.provideService(effect, CurrentConversation, ref)
+
+// ---------------------------------------------------------------------------
+// Service definition
+// ---------------------------------------------------------------------------
+
+/** Envelope of a streamed reply. `replyTo` lands on the first message it posts. */
+export type StreamOptions = OutboundOptions
+
+/** Platform ceilings, so recipes can see them before composing a message. */
+export type MessengerLimits = {
+  /** Longest single text message. */
+  readonly maxText: number
+  /** Longest caption on a media message. */
+  readonly maxCaption: number
+}
+
+/**
+ * Cross-platform messaging: one inbound stream, five outbound verbs.
+ *
+ * `events` is single-consumer and provider-owned. The connection opens when
+ * the layer is built and closes with its scope, so there is no connect /
+ * disconnect here, and reconnects, acks and callback answering all happen
+ * below this line.
+ *
+ * `post`, `typing` and `stream` target the ambient
+ * {@link CurrentConversation}; `edit` and `react` name a message outright.
+ */
+export type MessengerService = {
+  readonly events: Stream.Stream<InboundEvent, MessengerError.MessengerError>
+
+  /** Text past `limits.maxText` goes out as several messages; the id is the last. */
+  readonly post: (
+    msg: Outbound,
+  ) => Effect.Effect<MessageId, MessengerError.MessengerError, CurrentConversation>
+
+  readonly edit: (
+    msg: MessageRef,
+    next: Outbound,
+  ) => Effect.Effect<void, MessengerError.MessengerError>
+
+  /**
+   * `emoji` in the platform's own spelling, as its `Reaction` events deliver
+   * it. Nothing is translated; one the platform rejects fails
+   * `MessengerUnsupported`.
+   */
+  readonly react: (
+    msg: MessageRef,
+    emoji: string,
+  ) => Effect.Effect<void, MessengerError.MessengerError>
+
+  /** Activity indicator, kept alive by the adapter until the scope closes. */
+  readonly typing: Effect.Effect<
+    void,
+    MessengerError.MessengerError,
+    CurrentConversation | Scope.Scope
+  >
+
+  /**
+   * Progressive delivery of a text stream; the mechanism is the adapter's.
+   * The id is the last message posted, `None` when the stream had no text.
+   */
+  readonly stream: <E, R>(
+    deltas: Stream.Stream<string, E, R>,
+    options?: StreamOptions,
+  ) => Effect.Effect<
+    Option.Option<MessageId>,
+    MessengerError.MessengerError | E,
+    R | CurrentConversation
+  >
+
+  readonly limits: MessengerLimits
+}
+
+export class Messenger extends Context.Service<Messenger, MessengerService>()(
+  "@betalyra/effect-uai/Messenger",
+) {}
+
+// ---------------------------------------------------------------------------
+// Free helpers
+// ---------------------------------------------------------------------------
+
+export const events: Stream.Stream<InboundEvent, MessengerError.MessengerError, Messenger> =
+  Stream.unwrap(Effect.map(Messenger, (m) => m.events))
+
+export const post = (
+  msg: Outbound,
+): Effect.Effect<MessageId, MessengerError.MessengerError, Messenger | CurrentConversation> =>
+  Effect.flatMap(Messenger, (m) => m.post(msg))
+
+export const edit = (
+  msg: MessageRef,
+  next: Outbound,
+): Effect.Effect<void, MessengerError.MessengerError, Messenger> =>
+  Effect.flatMap(Messenger, (m) => m.edit(msg, next))
+
+export const react = (
+  msg: MessageRef,
+  emoji: string,
+): Effect.Effect<void, MessengerError.MessengerError, Messenger> =>
+  Effect.flatMap(Messenger, (m) => m.react(msg, emoji))
+
+export const typing: Effect.Effect<
+  void,
+  MessengerError.MessengerError,
+  Messenger | CurrentConversation | Scope.Scope
+> = Effect.flatMap(Messenger, (m) => m.typing)
+
+export const stream = <E, R>(
+  deltas: Stream.Stream<string, E, R>,
+  options?: StreamOptions,
+): Effect.Effect<
+  Option.Option<MessageId>,
+  MessengerError.MessengerError | E,
+  R | Messenger | CurrentConversation
+> => Effect.flatMap(Messenger, (m) => m.stream(deltas, options))