effect-assistant 0.0.0-stage → 0.1.0

package/src/Chats.ts

@@ -0,0 +1,122 @@
+/**
+ * This module provides the `Chats` service, through which the app tells the library which chats
+ * exist.
+ *
+ * The app keeps its own record of each chat (its owner, its title, whether it was deleted) and
+ * decides when a chat is created: up front, or on its first message. The library asks `Chats`
+ * before it stores an input and before each model call. When the app reports a chat as deleted,
+ * the library deletes it as well (see `Assistant.delete`).
+ *
+ * @since 0.1.0
+ */
+import * as Context from "effect/Context"
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import { ChatId } from "./ChatId.ts"
+
+/**
+ * Schema for the reason a chat can't be used. `"NotFound"` means the app doesn't know the chat,
+ * and `"Deleted"` means the app deleted it.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const Reason = Schema.Literals(["NotFound", "Deleted"])
+
+/**
+ * The reason a chat can't be used.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Reason = typeof Reason.Type
+
+/**
+ * Represents the error that `get` fails with when a chat can't be used. It carries the chat's id
+ * and the {@link Reason}. An input for such a chat isn't stored.
+ *
+ * **Example** (Failing for an unknown chat)
+ *
+ * ```ts
+ * if (row === undefined) return yield* new GetChatError({ chatId, reason: "NotFound" })
+ * ```
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export class GetChatError extends Schema.Error<GetChatError>("effect-assistant/Chats/GetChatError")({
+  _tag: Schema.tag("GetChatError"),
+  chatId: ChatId,
+  reason: Reason
+}) {}
+
+/**
+ * Represents what the library needs to know about a chat, which is its id. The app's own record
+ * can carry more.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface ChatRecord {
+  readonly chatId: ChatId
+}
+
+/**
+ * Represents the app's chats, as the `Chats` service exposes them.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Service {
+  /** Returns the chat, or fails with a `GetChatError` that says why it can't be used. */
+  readonly get: (chatId: ChatId) => Effect.Effect<ChatRecord, GetChatError>
+}
+
+/**
+ * Service that tells the library which of the app's chats exist.
+ *
+ * **Details**
+ *
+ * By default every chat exists from its first input, and a chat is deleted only when its log
+ * says so (`ChatDeleted`). Provide your own implementation to have the app decide. Provide it
+ * where you provide the `ChatLog`, so the engine and your server see the same one.
+ *
+ * **Example** (Reading chats from the app's own table)
+ *
+ * ```ts
+ * import { type ChatId, Chats } from "effect-assistant"
+ * import * as Effect from "effect/Effect"
+ * import * as Layer from "effect/Layer"
+ * import * as SqlClient from "effect/sql/SqlClient"
+ *
+ * const ChatsLive = Layer.effect(
+ *   Chats.Chats,
+ *   Effect.gen(function* () {
+ *     const sql = yield* SqlClient.SqlClient
+ *
+ *     return {
+ *       get: Effect.fn(function* (chatId: ChatId.ChatId) {
+ *         const [row] = yield* sql<{ readonly deleted_at: number | null }>`
+ *           SELECT deleted_at FROM chats WHERE chat_id = ${chatId}
+ *         `.pipe(Effect.orDie)
+ *
+ *         if (row === undefined) {
+ *           return yield* new Chats.GetChatError({ chatId, reason: "NotFound" })
+ *         }
+ *         if (row.deleted_at !== null) {
+ *           return yield* new Chats.GetChatError({ chatId, reason: "Deleted" })
+ *         }
+ *
+ *         return { chatId }
+ *       })
+ *     }
+ *   })
+ * )
+ * ```
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export const Chats: Context.Reference<Service> = Context.Reference<Service>("effect-assistant/Chats", {
+  defaultValue: () => ({ get: (chatId) => Effect.succeed({ chatId }) })
+})

package/src/Compaction.ts

@@ -0,0 +1,224 @@
+/**
+ * This module provides what a long chat needs so that the model can read a summary in place of
+ * everything before it.
+ *
+ * The app decides when to compact, which model writes the summary, and what the summary says.
+ * Its handler reads the chat's entries, has a model write a summary, and stores the summary as one
+ * of the assistant's own events (see {@link Summary}). Its loop then reads the chat through
+ * {@link since}. {@link inputTokens} helps decide when the prompt has grown large enough to
+ * compact. The log keeps every entry, so the user still sees the whole chat.
+ *
+ * @since 0.1.0
+ */
+import type * as Prompt from "effect/ai/Prompt"
+import * as Option from "effect/Option"
+import * as Predicate from "effect/Predicate"
+import type * as Assistant from "./Assistant.ts"
+import * as AssistantActivity from "./AssistantActivity.ts"
+import * as AssistantEvent from "./AssistantEvent.ts"
+import * as BlockKit from "./BlockKit.ts"
+import * as Decision from "./Decision.ts"
+import { userText } from "./internal/history.ts"
+import { toJsonText } from "./internal/schema.ts"
+
+/**
+ * Represents the fields a summary event must have: its text and the last `seq` it covers.
+ *
+ * Entries after `throughSeq` are kept as they are, so an input that arrived while the summary was
+ * being written isn't lost.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Summary {
+  readonly _tag: string
+  readonly text: string
+  readonly throughSeq: number
+}
+
+/**
+ * Returns the number of input tokens used by the chat's last model call, which shows how large
+ * the prompt has grown. Returns 0 before the first call.
+ *
+ * @category utils
+ * @since 0.1.0
+ */
+export const inputTokens = (entries: ReadonlyArray<AssistantEvent.AnyEntry>): number => {
+  const last = entries.findLast(
+    ({ event }) =>
+      AssistantEvent.isLibraryEvent(event) && Predicate.isTagged(event, "ModelOutput") && event.usage !== undefined
+  )?.event
+
+  return last !== undefined && AssistantEvent.isLibraryEvent(last) && Predicate.isTagged(last, "ModelOutput")
+    ? (last.usage?.inputTokens.total ?? 0)
+    : 0
+}
+
+/**
+ * Returns the items that were open at `throughSeq` and are still open: decisions waiting for the
+ * user, blocks the user hasn't answered, and specialists that are working. The result is text for
+ * the model, or `None` when nothing is open.
+ *
+ * @category utils
+ * @since 0.1.0
+ */
+export const openItems = (
+  entries: ReadonlyArray<AssistantEvent.AnyEntry>,
+  throughSeq: number
+): Option.Option<string> => {
+  const seqOf = (found: (event: AssistantEvent.AnyEntry["event"]) => boolean) =>
+    entries.find(({ event }) => found(event))?.seq ?? Number.POSITIVE_INFINITY
+
+  const opened = (seq: number) => seq <= throughSeq
+
+  const decisions = [...Decision.fromEntries(entries).values()].flatMap((state) =>
+    state.outcome === undefined &&
+    opened(
+      seqOf(
+        (event) =>
+          AssistantEvent.isLibraryEvent(event) &&
+          Predicate.isTagged(event, "DecisionRequested") &&
+          event.id === state.request.id
+      )
+    )
+      ? [`- decision ${state.request.id}, for ${state.request.origin.tool}: ${toJsonText(state.request.origin.params)}`]
+      : []
+  )
+
+  const blocks = [...BlockKit.fromEntries(entries)].flatMap(([messageId, state]) => {
+    const shown = entries.find(
+      ({ event }) =>
+        AssistantEvent.isLibraryEvent(event) && Predicate.isTagged(event, "AssistantMessage") && event.id === messageId
+    )
+
+    const message = shown?.event
+
+    return state.open &&
+      shown !== undefined &&
+      opened(shown.seq) &&
+      message !== undefined &&
+      AssistantEvent.isLibraryEvent(message) &&
+      Predicate.isTagged(message, "AssistantMessage")
+      ? [`- message ${messageId}, a ${message.block?.kind} block: ${message.text}`]
+      : []
+  })
+
+  const specialists = [...AssistantActivity.fromEntries(entries).specialists.values()].flatMap((run) =>
+    opened(
+      seqOf(
+        (event) =>
+          AssistantEvent.isLibraryEvent(event) &&
+          Predicate.isTagged(event, "SpecialistStarted") &&
+          event.runId === run.runId
+      )
+    )
+      ? [`- your ${run.specialist} specialist (${run.runId}), working on: ${run.goal}`]
+      : []
+  )
+
+  const sections = [
+    decisions.length > 0 ? `Decisions waiting for the user:\n${decisions.join("\n")}` : "",
+    blocks.length > 0 ? `Blocks the user hasn't answered:\n${blocks.join("\n")}` : "",
+    specialists.length > 0 ? `Specialists still working:\n${specialists.join("\n")}` : ""
+  ].filter((section) => section.length > 0)
+
+  return sections.length === 0 ? Option.none() : Option.some(sections.join("\n\n"))
+}
+
+/**
+ * Returns the files the user attached up to `throughSeq`, as lines of text for the model, or
+ * `None` when there are none. A summary may leave out a file's id, which tools need.
+ *
+ * @category utils
+ * @since 0.1.0
+ */
+export const attachedFiles = (
+  entries: ReadonlyArray<AssistantEvent.AnyEntry>,
+  throughSeq: number
+): Option.Option<string> => {
+  const lines = entries.flatMap(({ seq, event }) =>
+    seq <= throughSeq && AssistantEvent.isLibraryEvent(event) && Predicate.isTagged(event, "UserMessage")
+      ? (event.attachments ?? []).map(AssistantEvent.attachmentLine)
+      : []
+  )
+
+  return lines.length === 0 ? Option.none() : Option.some(lines.join("\n"))
+}
+
+/**
+ * Creates a history view that starts at the last summary.
+ *
+ * **Details**
+ *
+ * `isSummary` identifies the app's summary events. The model reads the last summary, the files
+ * attached earlier ({@link attachedFiles}), and the items that are still open
+ * ({@link openItems}), followed by the entries after the summary. When the chat has no summary,
+ * the view returns every entry.
+ *
+ * **Example** (Compacting a long chat after each turn)
+ *
+ * ```ts
+ * import { AppEvent, Assistant, type AssistantEvent, Compaction } from "effect-assistant"
+ * import * as LanguageModel from "effect/ai/LanguageModel"
+ * import * as Effect from "effect/Effect"
+ * import * as Schema from "effect/Schema"
+ * import * as Stream from "effect/Stream"
+ *
+ * class Summary extends Schema.TaggedClass<Summary>()("Summary", {
+ *   text: Schema.String,
+ *   throughSeq: Schema.Int
+ * }) {}
+ *
+ * declare const transcript: (entries: ReadonlyArray<AssistantEvent.AnyEntry>) => string
+ *
+ * export const MyAssistant = Assistant.make("my-assistant", { events: [AppEvent.make(Summary)] })
+ *
+ * const MyAssistantLive = MyAssistant.toLayer((turn) => {
+ *   const compact = Effect.gen(function* () {
+ *     const chat = yield* MyAssistant.Chat
+ *     const entries = yield* chat.entries
+ *
+ *     if (Compaction.inputTokens(entries) < 100_000) return
+ *
+ *     const { text } = yield* LanguageModel.generateText({
+ *       prompt: `Summarize this chat:\n\n${transcript(entries)}`
+ *     })
+ *
+ *     yield* chat.append(Summary.make({ text, throughSeq: entries.at(-1)?.seq ?? 0 }))
+ *   })
+ *
+ *   // After the reply, so the user doesn't wait for the summary.
+ *   return Stream.concat(
+ *     turn.loop({ instructions: "Be brief.", history: Compaction.since(Schema.is(Summary)) }),
+ *     Stream.drain(Stream.fromEffect(compact))
+ *   )
+ * })
+ * ```
+ *
+ * @category utils
+ * @since 0.1.0
+ */
+export const since =
+  (isSummary: (event: unknown) => event is Summary) =>
+  <Events extends { readonly _tag: string }>(
+    entries: ReadonlyArray<Assistant.Entry<Events>>
+  ): ReadonlyArray<Assistant.Entry<Events> | Prompt.Message> => {
+    const last = entries.findLast(({ event }) => isSummary(event))?.event
+
+    if (last === undefined || !isSummary(last)) return entries
+
+    const open = Option.match(openItems(entries, last.throughSeq), {
+      onNone: () => "",
+      onSome: (items) => `\n\n<still_open>\n${items}\n</still_open>`
+    })
+
+    const files = Option.match(attachedFiles(entries, last.throughSeq), {
+      onNone: () => "",
+      onSome: (lines) => `\n\n<files_attached_earlier>\n${lines}\n</files_attached_earlier>`
+    })
+
+    return [
+      userText(`<earlier_in_this_chat>\n${last.text}\n</earlier_in_this_chat>${files}${open}`),
+      ...entries.filter(({ seq, event }) => seq > last.throughSeq && !isSummary(event))
+    ]
+  }

package/src/CurrentChat.ts

@@ -0,0 +1,47 @@
+/**
+ * This module provides the `CurrentChat` service, which gives code that runs inside a chat
+ * access to that chat: its id, its entries, and a way to append to it.
+ *
+ * A turn's handler, its tools, and its specialists' runs get the chat with `yield* CurrentChat`.
+ * Inside a specialist's run, it is the chat the run belongs to, which is the chat of the turn
+ * that spawned the run. The service doesn't carry an assistant's event types, so code that
+ * doesn't know the assistant, such as a shared tool, can use it. Code that knows the assistant
+ * can use `MyAssistant.Chat`, which is the same chat typed with the assistant's events.
+ *
+ * @since 0.1.0
+ */
+import * as Context from "effect/Context"
+import type * as Effect from "effect/Effect"
+import type * as AssistantEvent from "./AssistantEvent.ts"
+import type { ChatId } from "./ChatId.ts"
+
+/**
+ * Service that represents the chat the current code runs in.
+ *
+ * **Details**
+ *
+ * In a turn, it is the chat the turn runs in. In a specialist's run, and in its handler's build,
+ * it is the chat the run belongs to: the chat of the turn that spawned the run. A run's tools
+ * read and append to that chat.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export class CurrentChat extends Context.Service<
+  CurrentChat,
+  {
+    readonly chatId: ChatId
+    /**
+     * The chat's entries so far, in order. They include the library's events and the assistant's
+     * own events, decoded; check for these with `Schema.is(MyEvent)` or `instanceof`. An app event
+     * that no longer decodes is left out.
+     */
+    readonly entries: Effect.Effect<ReadonlyArray<AssistantEvent.AnyEntry>>
+    /**
+     * Appends events after the chat's last entry and sends them to the chat's subscribers. The
+     * events can be the library's or the assistant's own (registered with its `events` option),
+     * such as a summary. An event that wakes a turn is handled by the next turn.
+     */
+    readonly append: (...events: ReadonlyArray<{ readonly _tag: string }>) => Effect.Effect<void>
+  }
+>()("effect-assistant/CurrentChat") {}

package/src/Decision.ts

@@ -0,0 +1,241 @@
+/**
+ * Lets the user approve or decline a tool call the assistant can't make on its own, such as
+ * placing an order or publishing a post.
+ *
+ * When the model calls a tool marked with Effect's `needsApproval`, the call is parked instead of
+ * run. The model asks the user with the decision {@link block}, and the user's answer to that
+ * block runs the call or declines it. {@link fromEntries} computes where every decision in a
+ * chat's log stands.
+ *
+ * @since 0.1.0
+ */
+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 * as Block from "./Block.ts"
+import * as DecisionId from "./DecisionId.ts"
+import type { InputId } from "./InputId.ts"
+
+/**
+ * The kind of the decision block.
+ *
+ * @category utils
+ * @since 0.1.0
+ */
+export const kind = "decision"
+
+/**
+ * Schema for the decision block's props, which list the decisions it asks for and, optionally,
+ * its buttons' labels.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const Props = Schema.Struct({
+  // Plain strings: a strict tool schema with the id's pattern is too much for some providers; the
+  // ids are checked against the decisions waiting when the message is sent.
+  decisionIds: Schema.Array(Schema.String).check(Schema.isMinLength(1)).annotate({
+    description:
+      "The decisions to ask for: each waiting call's decisionId. Several go in one block when the user decides them together."
+  }),
+  approveLabel: Schema.optional(Schema.String).annotate({
+    description: 'The approve button, like "Place order".'
+  }),
+  declineLabel: Schema.optional(Schema.String).annotate({
+    description: 'The decline button, like "Cancel".'
+  })
+})
+
+/**
+ * Represents the decision block's props.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Props = typeof Props.Type
+
+/**
+ * Schema for the decision block's answer, which holds an outcome for every decision the block
+ * asks for, by id.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const Answer = Schema.Struct({
+  decisions: Schema.Record(Schema.String, AssistantEvent.DecisionOutcome)
+})
+
+/**
+ * Represents the decision block's answer.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Answer = typeof Answer.Type
+
+/**
+ * Block with approve and decline buttons for the decisions waiting for the user.
+ *
+ * **Details**
+ *
+ * Put it in the assistant's `BlockKit`. An assistant with a tool that needs a decision must have
+ * it. The client renders it like any other block, with the calls from {@link fromEntries} (their
+ * tool and params).
+ *
+ * **Example** (Asking the user before placing an order)
+ *
+ * ```ts
+ * import { Assistant, BlockKit, Decision } from "effect-assistant"
+ * import * as Tool from "effect/ai/Tool"
+ * import * as Toolkit from "effect/ai/Toolkit"
+ * import * as Effect from "effect/Effect"
+ * import * as Layer from "effect/Layer"
+ * import * as Schema from "effect/Schema"
+ *
+ * export const Shop = Assistant.make("shop", { blocks: BlockKit.make([Decision.block]) })
+ *
+ * const OrderTools = Toolkit.make(
+ *   Tool.make("place_order", {
+ *     description: "Places an order.",
+ *     parameters: Schema.Struct({ sku: Schema.String, quantity: Schema.Int }),
+ *     success: Schema.Struct({ reference: Schema.String }),
+ *     needsApproval: true
+ *   })
+ * )
+ *
+ * const OrderToolsLive = OrderTools.toLayer({
+ *   place_order: () => Effect.succeed({ reference: "R-1042" })
+ * })
+ *
+ * // The call waits until the user answers the decision block.
+ * const ShopLive = Shop.toLayer((turn) =>
+ *   turn.loop({ instructions: "You place orders for the team.", toolkit: OrderTools })
+ * ).pipe(Layer.provide(OrderToolsLive))
+ * ```
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const block = Block.make(kind, {
+  description:
+    "Approve / decline buttons for decisions waiting for the user: a call of yours that waits for their decision. The only way such a decision is made: write what they decide on (the call's key facts), and put the decision ids in decisionIds.",
+  props: Props,
+  answer: Answer
+})
+
+/**
+ * Creates an answer that gives every decision the block asks for the same outcome.
+ *
+ * This is what an "Approve" or "Decline" button sends.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const answerAll = (props: Props, outcome: AssistantEvent.DecisionOutcome): Answer => ({
+  decisions: Object.fromEntries(props.decisionIds.map((id) => [id, outcome]))
+})
+
+/**
+ * Represents the state of a decision.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface State {
+  readonly request: AssistantEvent.DecisionRequested
+  /** How the user decided, or `undefined` while the decision waits. */
+  readonly outcome: AssistantEvent.DecisionOutcome | undefined
+  /** The id of the answer that decided it. */
+  readonly answer: InputId | undefined
+  /** Whether its `DecisionResolved` is stored. A workflow's decision has been passed on by then. */
+  readonly resolved: boolean
+  /** The approved call's result, once the call has run. */
+  readonly result: AssistantEvent.ToolResult | undefined
+}
+
+const decodeAnswer = Schema.decodeUnknownOption(Answer)
+
+/**
+ * Returns the decision 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 update = (id: string, f: (state: State) => State) => {
+    const state = states.get(id)
+
+    return state === undefined ? states : new Map(states).set(id, f(state))
+  }
+
+  if (Predicate.isTagged(event, "DecisionRequested")) {
+    return states.has(event.id)
+      ? states
+      : new Map(states).set(event.id, {
+          request: event,
+          outcome: undefined,
+          answer: undefined,
+          resolved: false,
+          result: undefined
+        })
+  }
+
+  if (Predicate.isTagged(event, "DecisionResolved")) {
+    return update(event.id, (state) => ({
+      ...state,
+      outcome: event.outcome,
+      answer: event.answer,
+      resolved: true
+    }))
+  }
+
+  // A stored decision answer was checked against its block when it was submitted: the first one
+  // for a decision decides it.
+  if (Predicate.isTagged(event, "BlockAnswer") && event.kind === kind) {
+    return Option.match(decodeAnswer(event.value), {
+      onNone: () => states,
+      onSome: ({ decisions }) => {
+        const next = new Map(states)
+
+        for (const [id, outcome] of Object.entries(decisions)) {
+          const state = states.get(id)
+
+          if (state !== undefined && state.outcome === undefined) next.set(id, { ...state, outcome, answer: event.id })
+        }
+
+        return next
+      }
+    })
+  }
+
+  if (Predicate.isTagged(event, "ToolResult")) {
+    const id = DecisionId.fromCallId(event.callId)
+    const state = states.get(id)
+
+    return state !== undefined && Predicate.isTagged(state.request.origin, "Call") && state.outcome === "approved"
+      ? update(id, (current) => ({ ...current, result: event }))
+      : states
+  }
+
+  return states
+}
+
+/**
+ * Returns every decision in the log and where it stands, by id.
+ *
+ * @category utils
+ * @since 0.1.0
+ */
+export const fromEntries = (entries: ReadonlyArray<AssistantEvent.AnyEntry>): ReadonlyMap<string, State> => {
+  let all: ReadonlyMap<string, State> = new Map()
+
+  for (const entry of entries) all = apply(all, entry.event)
+
+  return all
+}

package/src/DecisionId.ts

@@ -0,0 +1,46 @@
+/**
+ * This module provides the id of a decision the user is asked to make, which is `decision:`
+ * followed by a UUID.
+ *
+ * The model passes the id to a decision block, and the user's answer refers to it.
+ *
+ * @since 0.1.0
+ */
+import * as Schema from "effect/Schema"
+import * as Uuid from "./internal/uuid.ts"
+
+/**
+ * Schema for decision ids of the form `` `decision:${uuid}` ``, branded.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const DecisionId = Schema.TemplateLiteral(["decision:", Uuid.Uuid]).pipe(
+  Schema.brand("~effect-assistant/DecisionId")
+)
+
+/**
+ * Represents a decision id.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type DecisionId = typeof DecisionId.Type
+
+/**
+ * Creates the decision id for a key. The same key always gives the same id, so a decision that is
+ * requested again is stored only once.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const fromKey = (key: string): DecisionId => DecisionId.make(`decision:${Uuid.fromKey(key)}`)
+
+/**
+ * Returns the decision id for a tool call that waits for the user's decision, derived from the
+ * call's id.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const fromCallId = (callId: string): DecisionId => fromKey(`tool-call:${callId}`)