effect-assistant 0.0.0-stage → 0.1.0

package/src/Specialist.ts

@@ -0,0 +1,355 @@
+/**
+ * Defines specialists, which are focused agents an assistant hands work to in the background.
+ *
+ * A specialist has a definition, created with {@link make}, that gives its name and when to use
+ * it, and a handler, provided with its `toLayer`, that works on a {@link Brief} as a loop. The
+ * {@link Runner} service starts, steers, and stops a chat's specialist runs.
+ *
+ * @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 Context from "effect/Context"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as Schema from "effect/Schema"
+import type * as Scope from "effect/Scope"
+import * as Stream from "effect/Stream"
+import type * as AssistantLoop from "./AssistantLoop.ts"
+import type { ChatId } from "./ChatId.ts"
+import type { CurrentChat } from "./CurrentChat.ts"
+import type * as Instructions from "./Instructions.ts"
+import type { RunId } from "./RunId.ts"
+import type { Skill } from "./Skill.ts"
+
+const TypeId = "~effect-assistant/Specialist"
+
+/**
+ * Represents a specialist's definition.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Specialist<Name extends string = string> {
+  readonly [TypeId]: typeof TypeId
+  readonly name: Name
+  /** When to use the specialist. The assistant sees this. */
+  readonly description: string
+  /** The key of the specialist's handler, as `toLayer` provides it. */
+  readonly Handler: Context.Key<SpecialistHandler<Name>, Built>
+  /**
+   * Provides the specialist's handler. The handler may use the {@link RunServices} and the
+   * services its build Effect required (see {@link CheckServices}).
+   */
+  readonly toLayer: <R = never, RE = never, E = never, RX = never>(
+    build: (Handler<R, RE> | Effect.Effect<Handler<R, RE>, E, RX>) &
+      CheckServices<Exclude<R | RE, RunServices | RX | Tool.Handler<string>>>
+  ) => Layer.Layer<SpecialistHandler<Name>, never, Exclude<RX, Scope.Scope | CurrentChat> | ToolHandlers<R | RE>>
+}
+
+/**
+ * Represents the check `toLayer` applies to the services a handler uses.
+ *
+ * **Details**
+ *
+ * Every service a handler uses must be one the run (or turn) provides, or one its build Effect
+ * required, which the layer provides. A handler that uses any other service gets this type
+ * error, which names those services.
+ *
+ * @category utility types
+ * @since 0.1.0
+ */
+export type CheckServices<Undeclared> = [Undeclared] extends [never]
+  ? unknown
+  : {
+      readonly "~undeclaredServices": {
+        readonly error: "The handler uses services that neither the turn provides nor its build Effect requires"
+        readonly services: Undeclared
+      }
+    }
+
+/**
+ * Extracts the tool handlers (`Toolkit.toLayer`) that a handler's loop uses.
+ *
+ * They are requirements of the layer, so `Layer.provide(MyToolsLive)` provides them, and a
+ * missing one is a type error.
+ *
+ * @category utility types
+ * @since 0.1.0
+ */
+export type ToolHandlers<R> = Extract<R, Tool.Handler<string>>
+
+/**
+ * Represents any specialist.
+ *
+ * @category utility types
+ * @since 0.1.0
+ */
+export type Any = Specialist<any>
+
+/**
+ * Identifies a specialist's handler in a context.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface SpecialistHandler<Name extends string> {
+  readonly _SpecialistHandler: Name
+}
+
+/**
+ * Extracts the handlers that these specialists need.
+ *
+ * @category utility types
+ * @since 0.1.0
+ */
+export type HandlerOf<S> = S extends Specialist<infer Name> ? SpecialistHandler<Name> : never
+
+/**
+ * The services a run provides to its handler, which are its chat, the chat's runner, and the
+ * model.
+ *
+ * @category utility types
+ * @since 0.1.0
+ */
+export type RunServices = CurrentChat | Runner | LanguageModel.LanguageModel
+
+/**
+ * Represents the options for `run.loop`.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface LoopOptions<T extends Record<string, Tool.Any> = Record<never, never>, RS = never> {
+  readonly instructions: string | Instructions.Resolved
+  /** The loop's tools, as a native toolkit whose handlers come from the layer. */
+  readonly toolkit?: Toolkit.Toolkit<T> | undefined
+  /** Playbooks, listed as a catalog in the prompt and loaded with `load_skill` when one matches. */
+  readonly skills?: ReadonlyArray<Skill<RS>> | undefined
+  /** The model calls allowed per brief. Defaults to 8. */
+  readonly maxSteps?: number | undefined
+}
+
+/**
+ * Represents one run of a specialist on a brief, as its handler sees it.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Run {
+  readonly runId: RunId
+  /** The chat the run belongs to, which is the chat of the turn that spawned it. */
+  readonly chatId: ChatId
+  readonly brief: Brief
+  /**
+   * The run's history, with the brief, what the run did so far, and the messages sent to it since
+   * (follow-ups and steering). Read it before every model call, as the loop does.
+   */
+  readonly history: Effect.Effect<ReadonlyArray<Prompt.Message>>
+  /** Runs the agent loop over the run's history, with the given instructions, tools, and skills. */
+  readonly loop: <T extends Record<string, Tool.Any> = Record<never, never>, RS = never>(
+    options: LoopOptions<T, RS>
+  ) => Stream.Stream<
+    AssistantLoop.Event,
+    AiError.AiError,
+    LanguageModel.LanguageModel | AssistantLoop.ToolkitServices<T> | RS
+  >
+}
+
+/**
+ * Represents a specialist's handler, which works on a brief and returns a stream of what the loop
+ * did.
+ *
+ * It may return the stream from an Effect. `R` is the services the stream needs, and `RE` the
+ * services the Effect needs.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Handler<R = never, RE = R> = (
+  run: Run
+) =>
+  | Stream.Stream<AssistantLoop.Event, unknown, R>
+  | Effect.Effect<Stream.Stream<AssistantLoop.Event, unknown, R>, unknown, RE>
+
+/**
+ * Represents a specialist's handler as its layer provides it.
+ *
+ * `open` runs the build for a chat (once per chat activation, see `CurrentChat`) and returns
+ * the handler with the layer's services already provided.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Built {
+  readonly open: Effect.Effect<
+    (run: Run) => Stream.Stream<AssistantLoop.Event, unknown, RunServices>,
+    never,
+    Scope.Scope | CurrentChat
+  >
+}
+
+const toStream = <R, RE>(
+  result:
+    | Stream.Stream<AssistantLoop.Event, unknown, R>
+    | Effect.Effect<Stream.Stream<AssistantLoop.Event, unknown, R>, unknown, RE>
+): Stream.Stream<AssistantLoop.Event, unknown, R | RE> => (Effect.isEffect(result) ? Stream.unwrap(result) : result)
+
+/**
+ * Creates a specialist from its name and a description of when to use it.
+ *
+ * **Details**
+ *
+ * The specialist's `toLayer` provides its handler, which is usually `run.loop` with the
+ * specialist's own instructions and tools. List the specialist in `Assistant.make`'s
+ * `specialists`, and provide its layer to the assistant's.
+ *
+ * **Example** (Defining a research specialist)
+ *
+ * ```ts
+ * import { Assistant, Specialist } from "effect-assistant"
+ * import * as Layer from "effect/Layer"
+ *
+ * const Research = Specialist.make("research", {
+ *   description: "Researches past campaigns and orders. Give it the question and any context."
+ * })
+ *
+ * const ResearchLive = Research.toLayer((run) =>
+ *   run.loop({
+ *     instructions: "Answer with the findings and numbers the colleague needs, in a few lines.",
+ *     toolkit: ResearchTools
+ *   })
+ * ).pipe(Layer.provide(ResearchToolsLive))
+ *
+ * export const MyAssistant = Assistant.make("my-assistant", { specialists: [Research] })
+ *
+ * const MyAssistantLive = MyAssistant.toLayer((turn) => turn.loop({ instructions })).pipe(
+ *   Layer.provide(ResearchLive)
+ * )
+ * ```
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const make = <const Name extends string>(
+  name: Name,
+  options: {
+    /** When to use it. The assistant sees this. */
+    readonly description: string
+  }
+): Specialist<Name> => {
+  const Handler = Context.Service<SpecialistHandler<Name>, Built>(`effect-assistant/Specialist/${name}`)
+
+  // The signature checks what the handler uses (`CheckServices`); the layer's services, which the
+  // build required, are provided to it and to every run's stream, so what's left is the run
+  // services.
+  function toLayer<R = never, RE = never, E = never, RX = never>(
+    build: (Handler<R, RE> | Effect.Effect<Handler<R, RE>, E, RX>) &
+      CheckServices<Exclude<R | RE, RunServices | RX | Tool.Handler<string>>>
+  ): Layer.Layer<SpecialistHandler<Name>, never, Exclude<RX, Scope.Scope | CurrentChat> | ToolHandlers<R | RE>>
+  function toLayer(
+    build: Handler<any, any> | Effect.Effect<Handler<any, any>, unknown, any>
+  ): Layer.Layer<SpecialistHandler<Name>, never, any> {
+    return Layer.effect(
+      Handler,
+      Effect.gen(function* () {
+        const context = yield* Effect.context()
+
+        return {
+          // The build runs per chat activation, in the chat; here it only keeps the layer's
+          // services for it.
+          open: Effect.gen(function* () {
+            const handler = Effect.isEffect(build) ? yield* build : build
+
+            return (run: Run) => Stream.provideContext(toStream(handler(run)), context)
+          }).pipe(Effect.provideContext(context), Effect.orDie)
+        }
+      })
+    )
+  }
+
+  return { [TypeId]: TypeId, name, description: options.description, Handler, toLayer }
+}
+
+/**
+ * Schema for the brief the assistant gives a specialist.
+ *
+ * Only `goal` is required.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const Brief = Schema.Struct({
+  goal: Schema.String.annotate({ description: "What to find out or do." }),
+  context: Schema.optional(Schema.String).annotate({
+    description: "What it needs to know. It can't see this chat."
+  }),
+  successCriteria: Schema.optional(Schema.String).annotate({ description: "When it is done." }),
+  report: Schema.optional(Schema.String).annotate({
+    description: "What to put in the answer, and how."
+  }),
+  limits: Schema.optional(Schema.String).annotate({
+    description: "Hard limits for this job, like read-only or a deadline."
+  })
+})
+
+/**
+ * Represents the brief the assistant gives a specialist.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Brief = typeof Brief.Type
+
+/**
+ * Represents a request to start a specialist run in the runner's chat.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface SpawnRequest {
+  /** The specialist's name. */
+  readonly specialist: string
+  readonly brief: Brief
+}
+
+/**
+ * Represents why a run request can't be carried out.
+ *
+ * **Details**
+ *
+ * The `reason` says which request failed: `"UnknownSpecialist"` when `spawn` names no specialist
+ * of the assistant, `"RunNotFound"` when `message` names a run that is gone, and `"NotRunning"`
+ * when `stop` names a run that isn't running. The `message` is written for the model.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export class SpecialistError extends Schema.Error<SpecialistError>("effect-assistant/Specialist/SpecialistError")({
+  _tag: Schema.tag("SpecialistError"),
+  reason: Schema.Literals(["UnknownSpecialist", "RunNotFound", "NotRunning"]),
+  message: Schema.String
+}) {}
+
+/**
+ * Service that runs a chat's specialists and keeps finished runs warm for follow-ups.
+ *
+ * The engine provides it to every turn. The specialist tools use it, and a handler can too.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export class Runner extends Context.Service<
+  Runner,
+  {
+    /** Starts a run and returns its id. */
+    readonly spawn: (request: SpawnRequest) => Effect.Effect<RunId, SpecialistError>
+    /** Steers a running run, or continues a finished one. */
+    readonly message: (runId: RunId, text: string) => Effect.Effect<"steered" | "continued", SpecialistError>
+    /** Interrupts a running run. */
+    readonly stop: (runId: RunId) => Effect.Effect<void, SpecialistError>
+  }
+>()("effect-assistant/Specialist/Runner") {}

package/src/ToolDiscovery.ts

@@ -0,0 +1,187 @@
+/**
+ * Turns a catalog toolkit into two tools, so the prompt doesn't carry every tool definition.
+ *
+ * `search_tools` finds tools by what the model needs to do and returns their names, descriptions,
+ * and input schemas. `execute_tool` validates an input and runs one of them. {@link make} returns
+ * the two tools as a native toolkit, and {@link layer} their handlers.
+ *
+ * @since 0.1.0
+ */
+import * as Response from "effect/ai/Response"
+import * as Tool from "effect/ai/Tool"
+import * as Toolkit from "effect/ai/Toolkit"
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import { AssistantToolCall } from "./AssistantToolCall.ts"
+import { toJson } from "./internal/schema.ts"
+import * as Toolkits from "./internal/toolkit.ts"
+
+const words = (text: string): ReadonlySet<string> =>
+  new Set(
+    text
+      .toLowerCase()
+      .split(/[^a-z0-9]+/)
+      .filter((word) => word.length >= 3)
+  )
+
+const score = (query: ReadonlySet<string>, text: string): number => {
+  const target = [...words(text)]
+
+  const matches = (word: string) =>
+    target.some((t) => t === word || (word.length >= 4 && (t.startsWith(word) || word.startsWith(t))))
+
+  return [...query].filter(matches).length
+}
+
+// Everything when nothing matches, so the model can pick or search again.
+const search = (tools: ReadonlyArray<Tool.Any>, query: string, limit: number): ReadonlyArray<Tool.Any> => {
+  const queryWords = words(query)
+
+  const ranked = tools
+    .flatMap((tool) => {
+      const hits = score(queryWords, `${tool.name} ${Tool.getDescription(tool) ?? ""}`)
+
+      return hits > 0 ? [{ tool, score: hits }] : []
+    })
+    .sort((a, b) => b.score - a.score)
+
+  return (ranked.length > 0 ? ranked.map((hit) => hit.tool) : tools).slice(0, limit)
+}
+
+const SearchTools = Tool.make("search_tools", {
+  description:
+    "Search for more tools by what you need to do. Returns their names, descriptions, and input schemas; call one with execute_tool.",
+  parameters: Schema.Struct({
+    query: Schema.String.annotate({ description: "What you need to do, in a few words." })
+  }),
+  success: Schema.Array(
+    Schema.Struct({
+      name: Schema.String,
+      description: Schema.optional(Schema.String),
+      inputSchema: Schema.Json
+    })
+  )
+})
+
+const ExecuteTool = Tool.make("execute_tool", {
+  description: "Run a tool found with search_tools. Pass its name and an input matching its input schema.",
+  parameters: Schema.Struct({
+    name: Schema.String,
+    input: Schema.Record(Schema.String, Schema.Json)
+  }),
+  success: Schema.Json,
+  // The tool's failure is this call's, so the loop sees it failed (a `wait: true` message doesn't
+  // end the turn).
+  failure: Schema.Json,
+  dependencies: [AssistantToolCall]
+})
+
+// A tool's requirements are a covariant phantom type, so one that needs nothing is one that needs
+// any.
+const requiring =
+  <R>() =>
+  <N extends string, C extends (Tool.Any extends Tool.Tool<string, infer K, unknown> ? K : never), R0>(
+    tool: Tool.Tool<N, C, R0>
+  ): Tool.Tool<N, C, R0 | R> =>
+    tool
+
+/**
+ * Creates the `search_tools` and `execute_tool` tools over a catalog toolkit, as a native toolkit.
+ *
+ * **Details**
+ *
+ * Merge the toolkit into the loop's, and provide {@link layer} for the same catalog, which has
+ * the tools' handlers. A catalog tool's services are `execute_tool`'s, so the turn provides them
+ * as it does for any tool.
+ *
+ * `execute_tool` doesn't run a tool that needs the user's decision; keep such tools in the loop's
+ * toolkit directly.
+ *
+ * **Example** (Finding rarely used tools when needed)
+ *
+ * ```ts
+ * import { ToolDiscovery } from "effect-assistant"
+ * import * as Toolkit from "effect/ai/Toolkit"
+ * import * as Layer from "effect/Layer"
+ *
+ * // OfficeTools is a big toolkit, found when needed. CommonTools stays in the prompt.
+ * const OfficeDiscovery = ToolDiscovery.make(OfficeTools)
+ * const OfficeDiscoveryLive = ToolDiscovery.layer(OfficeTools).pipe(Layer.provide(OfficeToolsLive))
+ *
+ * const MyAssistantLive = MyAssistant.toLayer((turn) =>
+ *   turn.loop({
+ *     instructions,
+ *     toolkit: Toolkit.merge(CommonTools, OfficeDiscovery)
+ *   })
+ * ).pipe(Layer.provide([CommonToolsLive, OfficeDiscoveryLive]))
+ * ```
+ *
+ * @see {@link layer} for the tools' handlers
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const make = <T extends Record<string, Tool.Any>>(
+  // Only its type is used here, for `execute_tool`'s services: `layer` runs its tools.
+  _catalog: Toolkit.Toolkit<T>
+) => Toolkit.make(SearchTools, requiring<Toolkits.ToolServices<T>>()(ExecuteTool))
+
+/**
+ * Creates the layer with the handlers of the `search_tools` and `execute_tool` tools over a
+ * catalog toolkit.
+ *
+ * **Details**
+ *
+ * The layer needs the catalog's handlers. It provides the handlers of the toolkit that
+ * {@link make} returns for the same catalog: handlers are keyed by tool name, so the two calls
+ * don't need to share a value. Give both the same catalog.
+ *
+ * @see {@link make} for the toolkit and an example
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layer = <T extends Record<string, Tool.Any>>(catalog: Toolkit.Toolkit<T>) =>
+  make(catalog).toLayer(
+    Effect.gen(function* () {
+      const resolved = yield* catalog
+      const definitions = Object.values(resolved.tools)
+
+      return {
+        search_tools: ({ query }) =>
+          Effect.sync(() =>
+            search(definitions, query, 5).map((tool) => ({
+              name: tool.name,
+              description: Tool.getDescription(tool),
+              inputSchema: toJson(Tool.getJsonSchema(tool))
+            }))
+          ),
+        execute_tool: Effect.fnUntraced(function* ({ name, input }) {
+          // Named after the call that runs it: the same id when a crash runs that call again.
+          const outer = yield* AssistantToolCall
+
+          const call = Response.makePart("tool-call", {
+            id: `${outer.callId}:${name}`,
+            name,
+            params: input,
+            providerExecuted: false
+          })
+
+          // A call that needs the user's decision parks only as a call the model made itself,
+          // where it can ask for it.
+          if (yield* Toolkits.needsDecision(resolved, call, [])) {
+            return yield* Effect.fail(
+              Toolkits.failed(
+                `${name} needs the user's decision, so it can't run through execute_tool.`,
+                "NeedsDecision"
+              ).result
+            )
+          }
+
+          const { outcome, result } = yield* Toolkits.runNative(resolved, call)
+
+          return outcome === "failure" ? yield* Effect.fail(result) : result
+        })
+      }
+    })
+  )

package/src/ToolFailure.ts

@@ -0,0 +1,74 @@
+/**
+ * Defines the failure a tool returns to the model.
+ *
+ * A {@link ToolFailure} carries a message the model reads and adapts to, such as "No office named
+ * Paris", instead of failing the turn. Tools declare it as their `failure` schema and fail with
+ * {@link fail}.
+ *
+ * @since 0.1.0
+ */
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+
+/**
+ * Represents a tool's failure, written for the model.
+ *
+ * It holds a message that says what went wrong and, optionally, a `reason` the model can tell
+ * apart, such as `"NotFound"` or `"OverBudget"`. The library's own reasons are PascalCase, like
+ * `"NeedsDecision"`.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export class ToolFailure extends Schema.Error<ToolFailure>("effect-assistant/ToolFailure/ToolFailure")({
+  _tag: Schema.tag("ToolFailure"),
+  message: Schema.String,
+  reason: Schema.optional(Schema.String)
+}) {}
+
+/**
+ * Fails a tool's handler with a message for the model.
+ *
+ * **Details**
+ *
+ * The tool must declare `failure: ToolFailure.ToolFailure`. The model reads the failure as the
+ * call's result, with its `reason` when one is given.
+ *
+ * **Example** (Failing a tool call the model can correct)
+ *
+ * ```ts
+ * import { ToolFailure } 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 Schema from "effect/Schema"
+ *
+ * const budgets = new Map([["Oslo", 1200]])
+ *
+ * const BudgetTools = Toolkit.make(
+ *   Tool.make("office_budget", {
+ *     description: "The budget left for an office.",
+ *     parameters: Schema.Struct({ office: Schema.String }),
+ *     success: Schema.Number,
+ *     failure: ToolFailure.ToolFailure
+ *   })
+ * )
+ *
+ * const BudgetToolsLive = BudgetTools.toLayer({
+ *   office_budget: ({ office }) =>
+ *     Effect.fromNullishOr(budgets.get(office)).pipe(
+ *       Effect.catch(() => ToolFailure.fail(`No office named ${office}.`, { reason: "NotFound" }))
+ *     )
+ * })
+ * ```
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const fail = (
+  message: string,
+  options?: { readonly reason?: string | undefined }
+): Effect.Effect<never, ToolFailure> =>
+  Effect.fail(
+    options?.reason === undefined ? new ToolFailure({ message }) : new ToolFailure({ message, reason: options.reason })
+  )