effect-assistant 0.0.0-stage → 0.2.0

package/src/AssistantLoop.ts

@@ -0,0 +1,209 @@
+/**
+ * Runs the agent loop, which calls the model, runs its tool calls, and repeats.
+ *
+ * Most handlers use `turn.loop` or `run.loop`. This module is for a loop of your own: {@link run}
+ * runs the loop until the model is done, and {@link step} is one step, as a body for
+ * {@link loop}.
+ *
+ * Tools are a native toolkit (`effect/ai/Toolkit`) whose handlers come from the handler's layer.
+ * In a turn, the assistant's own tools (`send_user_message`, `wait`, and the specialist tools)
+ * are added to them.
+ *
+ * @since 0.1.0
+ */
+import type * as AiError from "effect/ai/AiError"
+import type * as LanguageModel from "effect/ai/LanguageModel"
+import type * as Prompt from "effect/ai/Prompt"
+import type * as Tool from "effect/ai/Tool"
+import type * as Toolkit from "effect/ai/Toolkit"
+import * as Effect from "effect/Effect"
+import * as Option from "effect/Option"
+import * as Stream from "effect/Stream"
+import type * as Instructions from "./Instructions.ts"
+import * as Loop from "./internal/loop.ts"
+import * as Toolkits from "./internal/toolkit.ts"
+
+/**
+ * Represents what the loop emits.
+ *
+ * For each model call, the loop emits the call's output. Then, for each of its tool calls, it
+ * emits a `ToolStarted` before the call runs and the call's result.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Event = Loop.Event
+
+/**
+ * Represents a chat's history as the model reads it.
+ *
+ * It holds the messages, and the last `seq` of the chat they cover.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type ChatHistory = Loop.ChatHistory
+
+/**
+ * Represents how a step went, for deciding what comes next.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type StepResult = Loop.StepResult
+
+/**
+ * Represents what a loop body emits, which is either a value or what to do next.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Step<A, S> = Loop.Step<A, S>
+
+/**
+ * Emits a value from a loop body.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const value = Loop.value
+
+/**
+ * Ends a loop body's step and continues the loop with the given state.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const next = Loop.next
+
+/**
+ * Ends the loop.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const stop = Loop.stop
+
+/**
+ * Runs a loop body from an initial state.
+ *
+ * It emits the body's values, and runs the body again with the state it passes to `next`, until
+ * the body calls `stop`.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const loop = Loop.loop
+
+type NoTools = Record<never, never>
+
+/**
+ * Extracts the services a toolkit's tools need when they run, which are their handlers and the
+ * services those handlers use.
+ *
+ * @category utility types
+ * @since 0.1.0
+ */
+export type ToolkitServices<T extends Record<string, Tool.Any>> = Tool.HandlersFor<T> | Toolkits.ToolServices<T>
+
+/**
+ * Represents the options for {@link step}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface StepOptions<T extends Record<string, Tool.Any> = NoTools> {
+  /** The full system prompt, like `turn.instructions(text)`, optionally with span attributes. */
+  readonly instructions: string | Instructions.Resolved
+  /**
+   * The tools the model can call, in addition to the assistant's own tools in a turn. Their
+   * handlers come from the layer.
+   */
+  readonly toolkit?: Toolkit.Toolkit<T> | undefined
+  /**
+   * The current history, read at the start of the step. It is either messages, or a chat's
+   * history (`turn.history()`), whose `throughSeq` the step's `ModelOutput` records as how far
+   * the model had read.
+   */
+  readonly history: Effect.Effect<ReadonlyArray<Prompt.Message> | ChatHistory>
+  /**
+   * Defaults to `"auto"`, where a step without a tool call ends the loop. Forcing a call
+   * (`"required"`, or a tool by name) is refused by newer models, and with extended thinking.
+   */
+  readonly toolChoice?: LanguageModel.ToolChoice<string> | undefined
+}
+
+/**
+ * Represents the options for {@link run}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Options<T extends Record<string, Tool.Any> = NoTools> extends StepOptions<T> {
+  /** The model calls allowed. Defaults to 16. */
+  readonly maxSteps?: number | undefined
+}
+
+const toolsOf = <T extends Record<string, Tool.Any>>(toolkit: Toolkit.Toolkit<T> | undefined) =>
+  Effect.map(Loop.TurnTools, (turn) => {
+    const own = toolkit === undefined ? Toolkits.empty : Toolkits.fromToolkit(toolkit)
+
+    return Option.match(turn, { onNone: () => own, onSome: (builtins) => Toolkits.merge(builtins, own) })
+  })
+
+/**
+ * Runs one step of the agent loop, as a body for {@link loop}.
+ *
+ * **Details**
+ *
+ * The step calls the model with the current history and emits its `ModelOutput`. It then runs
+ * the output's tool calls and emits a `ToolStarted` and a `ToolResult` for each. `then` receives
+ * the step's result and decides what comes next, with `AssistantLoop.next(state)` or
+ * `AssistantLoop.stop()`.
+ *
+ * A tool with Effect's `needsApproval` set fails the loop before the model is called: the
+ * library doesn't run calls that wait for approval (see the guide on involving the user).
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const step = <T extends Record<string, Tool.Any> = NoTools, S = never, E2 = never, R2 = never>(
+  options: StepOptions<T>,
+  then: (result: StepResult) => Stream.Stream<Step<never, S>, E2, R2>
+): Stream.Stream<Step<Event, S>, AiError.AiError | E2, LanguageModel.LanguageModel | ToolkitServices<T> | R2> =>
+  Stream.unwrap(Effect.map(toolsOf(options.toolkit), (toolkit) => Loop.step({ ...options, toolkit }, then)))
+
+/**
+ * Runs the agent loop as a stream.
+ *
+ * **Details**
+ *
+ * It runs {@link step} after step until the model is done and nothing new arrived while it
+ * worked, or until it has made `maxSteps` model calls.
+ *
+ * **Example** (A turn's loop with a step limit)
+ *
+ * ```ts
+ * import { AssistantLoop } from "effect-assistant"
+ * import * as Layer from "effect/Layer"
+ * import * as Stream from "effect/Stream"
+ *
+ * const instructions = "You help a small marketing team."
+ *
+ * const MyAssistantLive = MyAssistant.toLayer((turn) =>
+ *   AssistantLoop.run({
+ *     instructions: turn.instructions(instructions),
+ *     toolkit: MyTools, // the assistant's own tools are added to them
+ *     history: turn.history(),
+ *     maxSteps: 12
+ *   }).pipe(Stream.concat(turn.replyIfOwed({ instructions })))
+ * ).pipe(Layer.provide(MyToolsLive))
+ * ```
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const run = <T extends Record<string, Tool.Any> = NoTools>(
+  options: Options<T>
+): Stream.Stream<Event, AiError.AiError, LanguageModel.LanguageModel | ToolkitServices<T>> =>
+  Stream.unwrap(Effect.map(toolsOf(options.toolkit), (toolkit) => Loop.run({ ...options, toolkit })))

package/src/AssistantToolCall.ts

@@ -0,0 +1,40 @@
+/**
+ * Gives a tool the call it runs for.
+ *
+ * The {@link AssistantToolCall} service holds the call's id and the tool's name, and
+ * {@link idempotencyKey} derives a key for anything the call does outside the chat.
+ *
+ * @since 0.1.0
+ */
+import * as Context from "effect/Context"
+import type * as Effect from "effect/Effect"
+
+/**
+ * Service that describes the tool call a tool runs for.
+ *
+ * The agent loop provides it to every call.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export class AssistantToolCall extends Context.Service<
+  AssistantToolCall,
+  {
+    /** The call's id, as the model wrote it. It stays the same when a crash runs the call again. */
+    readonly callId: string
+    /** The tool's name. */
+    readonly tool: string
+  }
+>()("effect-assistant/AssistantToolCall") {}
+
+/**
+ * Gets an idempotency key for what the current tool call does outside the chat.
+ *
+ * The key is the same every time the call runs, and different for every other call.
+ *
+ * @category accessors
+ * @since 0.1.0
+ */
+export const idempotencyKey: Effect.Effect<string, never, AssistantToolCall> = AssistantToolCall.useSync(
+  (call) => `tool-call:${call.callId}`
+)

package/src/Block.ts

@@ -0,0 +1,84 @@
+/**
+ * Defines UI blocks that an assistant can put in a message.
+ *
+ * A block is a bit of UI for when a structured answer is easier than typing, such as options to
+ * pick from, a yes or no, or a small input. The assistant fills in its `props`, and
+ * using the block sends back a value typed by its `answer` schema.
+ *
+ * @since 0.1.0
+ */
+import type * as Schema from "effect/Schema"
+
+/**
+ * Schema that a block's props or answer can use.
+ *
+ * It is any codec that needs no services, since the client decodes and encodes with it too.
+ *
+ * @category utility types
+ * @since 0.1.0
+ */
+export type Codec = Schema.Codec<any, any>
+
+/**
+ * Represents a kind of UI block.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Block<Kind extends string = string, Props extends Codec = Codec, Answer extends Codec = Codec> {
+  readonly kind: Kind
+  /** When to use the block. The assistant sees this. */
+  readonly description: string
+  /** The props the assistant fills in. */
+  readonly props: Props
+  /** What using the block sends back, or `undefined` for a display-only card. */
+  readonly answer: Answer | undefined
+}
+
+/**
+ * Represents any block, for generic constraints.
+ *
+ * @category utility types
+ * @since 0.1.0
+ */
+export type Any = Block
+
+/**
+ * Creates a block.
+ *
+ * **Details**
+ *
+ * A block without an `answer` schema is a display-only card. Put the block in the assistant's
+ * `BlockKit` so the assistant can use it.
+ *
+ * **Example** (Defining a block with options to pick from)
+ *
+ * ```ts
+ * import { Assistant, Block, BlockKit } from "effect-assistant"
+ * import * as Schema from "effect/Schema"
+ *
+ * const PickOne = Block.make("pick_one", {
+ *   description: "Options to pick from, when the user chooses between a few.",
+ *   props: Schema.Struct({ options: Schema.Array(Schema.String) }),
+ *   answer: Schema.Struct({ picked: Schema.String })
+ * })
+ *
+ * export const MyAssistant = Assistant.make("my-assistant", { blocks: BlockKit.make([PickOne]) })
+ * ```
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const make = <const Kind extends string, Props extends Codec, Answer extends Codec = Schema.Never>(
+  kind: Kind,
+  options: {
+    readonly description: string
+    readonly props: Props
+    readonly answer?: Answer | undefined
+  }
+): Block<Kind, Props, Answer> => ({
+  kind,
+  description: options.description,
+  props: options.props,
+  answer: options.answer
+})

package/src/BlockKit.ts

@@ -0,0 +1,298 @@
+/**
+ * Groups the blocks an assistant may put in its messages, and renders them on the client.
+ *
+ * A kit is created with {@link make} and passed to `Assistant.make`. {@link fromEntries} computes
+ * the state of every message's block from a chat's log, {@link closeStale} closes the blocks the
+ * user moved on from, and {@link toClient} creates a client-side renderer with one function per
+ * block kind.
+ *
+ * @since 0.1.0
+ */
+import * as Effect from "effect/Effect"
+import * as Option from "effect/Option"
+import * as Predicate from "effect/Predicate"
+import * as Schema from "effect/Schema"
+import * as AssistantEvent from "./AssistantEvent.ts"
+import type * as Block from "./Block.ts"
+import type * as ChatView from "./ChatView.ts"
+import { CurrentChat } from "./CurrentChat.ts"
+import * as InputId from "./InputId.ts"
+
+/**
+ * Represents a catalog of blocks, with a lookup by kind.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface BlockKit<Blocks extends Block.Any = Block.Any> {
+  readonly blocks: ReadonlyArray<Blocks>
+  readonly byKind: ReadonlyMap<string, Blocks>
+}
+
+/**
+ * Creates a kit from blocks.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const make = <const Blocks extends ReadonlyArray<Block.Any>>(blocks: Blocks): BlockKit<Blocks[number]> => ({
+  blocks,
+  byKind: new Map(blocks.map((block) => [block.kind, block]))
+})
+
+type KindOf<B> = B extends { readonly kind: infer K extends string } ? K : never
+
+type BlockOf<Kit extends BlockKit, K> = Extract<Kit["blocks"][number], { readonly kind: K }>
+
+type PropsOf<B> = B extends { readonly props: Schema.Top } ? B["props"]["Type"] : never
+
+type AnswerOf<B> = B extends { readonly answer: infer A } ? (A extends Schema.Top ? A["Type"] : never) : never
+
+/**
+ * Represents the state of a message's block.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface State {
+  readonly open: boolean
+  /** The user's answer, if they used the block. */
+  readonly answer: AssistantEvent.BlockAnswer | undefined
+}
+
+/**
+ * Returns the block states after one more event.
+ *
+ * @category utils
+ * @since 0.1.0
+ */
+export const apply = (
+  states: ReadonlyMap<string, State>,
+  event: { readonly _tag: string }
+): ReadonlyMap<string, State> => {
+  if (!AssistantEvent.isLibraryEvent(event)) return states
+
+  const close = (ids: ReadonlyArray<string>) => {
+    const open = ids.filter((id) => states.get(id)?.open === true)
+
+    if (open.length === 0) return states
+
+    const next = new Map(states)
+
+    for (const id of open) next.set(id, { open: false, answer: undefined })
+
+    return next
+  }
+
+  if (Predicate.isTagged(event, "BlocksClosed")) return close(event.messageIds)
+
+  if (Predicate.isTagged(event, "AssistantMessage")) {
+    const closed = close(event.closes ?? [])
+
+    return event.block === undefined ? closed : new Map(closed).set(event.id, { open: true, answer: undefined })
+  }
+
+  if (!Predicate.isTagged(event, "BlockAnswer") || states.get(event.messageId)?.open !== true) return states
+
+  return new Map(states).set(event.messageId, { open: false, answer: event })
+}
+
+/**
+ * Returns the state of every message's block, by message id.
+ *
+ * @category utils
+ * @since 0.1.0
+ */
+export const fromEntries = (entries: ReadonlyArray<AssistantEvent.AnyEntry>): ReadonlyMap<string, State> => {
+  let states: ReadonlyMap<string, State> = new Map()
+
+  for (const entry of entries) states = apply(states, entry.event)
+
+  return states
+}
+
+/**
+ * Returns the ids of the messages whose blocks are still open after the user typed the given
+ * number of messages without using them.
+ *
+ * **Details**
+ *
+ * These are the blocks {@link closeStale} closes.
+ *
+ * @category utils
+ * @since 0.1.0
+ */
+export const staleBlocks = (
+  entries: ReadonlyArray<AssistantEvent.AnyEntry>,
+  options: { readonly messages: number }
+): ReadonlyArray<string> => {
+  const open = [...fromEntries(entries)].flatMap(([id, state]) => (state.open ? [id] : []))
+
+  return open.filter((id) => {
+    const shown = entries.findIndex(
+      ({ event }) =>
+        AssistantEvent.isLibraryEvent(event) && Predicate.isTagged(event, "AssistantMessage") && event.id === id
+    )
+
+    if (shown === -1) return false
+
+    const typed = entries.slice(shown + 1).filter(({ event }) => Predicate.isTagged(event, "UserMessage")).length
+
+    return typed >= options.messages
+  })
+}
+
+/**
+ * Closes the blocks the user moved on from, which are still open after the given number of typed
+ * messages.
+ *
+ * **Details**
+ *
+ * Run it from a turn, before or after its loop. It records a `BlocksClosed` event, so every
+ * client folds the blocks closed.
+ *
+ * @see {@link staleBlocks} for the blocks it closes
+ *
+ * @category utils
+ * @since 0.1.0
+ */
+export const closeStale = Effect.fn(function* (options: { readonly messages: number }) {
+  const chat = yield* CurrentChat
+  const stale = staleBlocks(yield* chat.entries, options)
+
+  if (stale.length > 0) yield* chat.append(AssistantEvent.BlocksClosed.make({ messageIds: stale }))
+})
+
+/**
+ * Represents what a renderer receives for one block.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface RenderArgs<B> {
+  /**
+   * The id of the message the block is on. A block whose button calls your API can key the work
+   * on it, with the chat's id, so the work runs once per block.
+   */
+  readonly messageId: string
+  readonly text: string
+  readonly props: PropsOf<B>
+  /**
+   * Whether the block is open. It is `false` once the block is answered, with the block or in
+   * words; show it read-only then.
+   */
+  readonly open: boolean
+  /** The user's answer, if they used the block. */
+  readonly answer: AnswerOf<B> | undefined
+  /** Sends an answer. Only call it while `open`. */
+  readonly respond: (answer: AnswerOf<B>) => void
+}
+
+/**
+ * Represents a renderer for every kind in a kit.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Renderers<Kit extends BlockKit, Out> = {
+  readonly [K in KindOf<Kit["blocks"][number]>]: (args: RenderArgs<BlockOf<Kit, K>>) => Out
+}
+
+/**
+ * Represents the options for rendering one message's block.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface RenderOptions {
+  /** Submits an answer, for example over RPC. */
+  readonly respond: (answer: AssistantEvent.BlockAnswer) => void
+}
+
+/**
+ * Creates a client-side renderer for the blocks on a chat view's messages
+ * (`ChatView.AssistantMessage`).
+ *
+ * **Details**
+ *
+ * The renderers are type-checked, so every kind in the kit needs one, and each receives typed
+ * `props` and `answer`. A renderer's `respond` builds a `BlockAnswer` input, with the answer
+ * encoded by the block's answer schema, and passes it to the `respond` option to submit.
+ *
+ * The returned function returns `undefined` for a message without a block, or with a block it
+ * can't decode or has no renderer for.
+ *
+ * **Example** (Rendering blocks with React)
+ *
+ * ```tsx
+ * import { BlockKit } from "effect-assistant"
+ * import type { ReactNode } from "react"
+ *
+ * const Blocks = BlockKit.make([PickOne, OrderDraft])
+ *
+ * const renderBlock = BlockKit.toClient<typeof Blocks, ReactNode>(Blocks, {
+ *   pick_one: ({ props, open, respond }) =>
+ *     props.options.map((option) => (
+ *       <button key={option} disabled={!open} onClick={() => respond({ picked: option })}>
+ *         {option}
+ *       </button>
+ *     )),
+ *   // No answer schema: the button calls the app's own API with the props the user sees.
+ *   order_draft: ({ props }) => <button onClick={() => placeOrder(props)}>Place order</button>
+ * })
+ *
+ * // For each AssistantMessage in the chat's view:
+ * renderBlock(message, { respond: (answer) => submit(answer) })
+ * ```
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export function toClient<Kit extends BlockKit, Out>(
+  kit: Kit,
+  renderers: Renderers<Kit, Out>
+): (message: ChatView.AssistantMessage, options: RenderOptions) => Out | undefined
+// The overload above checks that every kind has a renderer; here each one takes any block's
+// arguments.
+export function toClient<Out>(
+  kit: BlockKit,
+  renderers: Readonly<Record<string, (args: RenderArgs<Block.Any>) => Out>>
+): (message: ChatView.AssistantMessage, options: RenderOptions) => Out | undefined {
+  return (message, options) => {
+    if (message.block === undefined) return undefined
+
+    const { kind } = message.block
+    const block = kit.byKind.get(kind)
+    const render = renderers[kind]
+
+    if (block === undefined || render === undefined) return undefined
+
+    const props = Schema.decodeUnknownOption(block.props)(message.block.props)
+
+    if (Option.isNone(props)) return undefined
+
+    const given = message.block.answer
+    const answerCodec = block.answer === undefined ? undefined : Schema.toCodecJson(block.answer)
+
+    const answer =
+      given === undefined || answerCodec === undefined ? Option.none() : Schema.decodeUnknownOption(answerCodec)(given)
+
+    return render({
+      messageId: message.id,
+      text: message.text,
+      props: props.value,
+      open: message.block.status === "open",
+      answer: Option.getOrUndefined(answer),
+      respond: (value) =>
+        options.respond(
+          AssistantEvent.BlockAnswer.make({
+            // A block takes one answer: the same id every time, so a second click is stored once.
+            id: InputId.fromKey(`${message.id}:answer`),
+            messageId: message.id,
+            kind,
+            value: answerCodec === undefined ? value : Schema.encodeUnknownSync(answerCodec)(value)
+          })
+        )
+    })
+  }
+}

package/src/ChatId.ts

@@ -0,0 +1,36 @@
+/**
+ * This module provides the id of a chat, which is `chat:` followed by a UUID.
+ *
+ * A chat id keys everything about a chat: its log, its cluster entity, and its trace session.
+ *
+ * @since 0.1.0
+ */
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import * as Uuid from "./internal/uuid.ts"
+
+/**
+ * Schema for chat ids of the form `` `chat:${uuid}` ``. The schema is branded, so a run id or a
+ * plain string can't be passed where a chat id is required.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const ChatId = Schema.TemplateLiteral(["chat:", Uuid.Uuid]).pipe(Schema.brand("~effect-assistant/ChatId"))
+
+/**
+ * Represents a chat id.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type ChatId = typeof ChatId.Type
+
+/**
+ * Creates a new random chat id using Effect's `Random`. Seed `Random` in tests to get the same ids
+ * on every run.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const make = (): Effect.Effect<ChatId> => Effect.map(Uuid.make, (uuid) => ChatId.make(`chat:${uuid}`))