@strav/brain 1.0.0-alpha.9 → 1.0.1

package/src/zod/index.ts

@@ -0,0 +1,121 @@
+/**
+ * `@strav/brain/zod` — Zod-flavored helpers on top of the
+ * schema-library-agnostic core.
+ *
+ * The default `@strav/brain` import deliberately doesn't depend on
+ * Zod — `Tool.inputSchema` and `OutputSchema.jsonSchema` are plain
+ * JSON Schema so apps stay free to pick Ajv, Valibot, ArkType, or
+ * nothing at all. This sub-path opt-in adds two thin wrappers for
+ * apps that already use Zod:
+ *
+ *   - `outputSchema(z, opts?)` turns a Zod schema into an
+ *     `OutputSchema<z.infer<typeof z>>` — `jsonSchema` is derived
+ *     via Zod's built-in `z.toJSONSchema`, and `parse` is wired to
+ *     `z.parse`. Apps then pass the result straight to
+ *     `BrainManager.generate(input, schema)`.
+ *
+ *   - `tool({ name, description, input, execute })` turns a Zod
+ *     schema for the tool's input into a framework `Tool` — the
+ *     wrapper validates the model's raw input through the Zod
+ *     schema before calling the app's `execute`. Apps get inferred
+ *     types on `execute(input)` for free.
+ *
+ * `zod` is an optional peer dependency. Apps that don't use Zod
+ * don't install it, don't bundle it, and never import this
+ * sub-path — they keep using `defineTool` / hand-written
+ * `OutputSchema` literals with raw JSON Schema.
+ */
+
+import { z } from 'zod'
+import type { OutputSchema } from '../output_schema.ts'
+import type { Tool, ToolContext } from '../tool.ts'
+
+/**
+ * Options for `outputSchema`. `name` defaults to `'output'` —
+ * apps that surface multiple schemas in logs or to OpenAI's wire
+ * format should pass a stable, descriptive identifier.
+ */
+export interface OutputSchemaOptions {
+  /** Identifier — defaults to `'output'`. */
+  name?: string
+  /** Optional model-facing hint. Defaults to the Zod schema's `.describe(…)` if set. */
+  description?: string
+}
+
+/**
+ * Build an `OutputSchema<T>` from a Zod schema. The returned shape
+ * is ready to pass to `BrainManager.generate(...)`.
+ *
+ * ```ts
+ * const CityZ = z.object({ city: z.string(), population: z.number().int() })
+ * const { value } = await brain.generate('Capital of France?', outputSchema(CityZ, { name: 'city_answer' }))
+ * //      ^? { city: string; population: number }
+ * ```
+ */
+export function outputSchema<T>(
+  schema: z.ZodType<T>,
+  options: OutputSchemaOptions = {},
+): OutputSchema<T> {
+  const description = options.description ?? zodDescription(schema)
+  const result: OutputSchema<T> = {
+    name: options.name ?? 'output',
+    jsonSchema: z.toJSONSchema(schema) as Record<string, unknown>,
+    parse: (value) => schema.parse(value),
+  }
+  if (description !== undefined) result.description = description
+  return result
+}
+
+/**
+ * Spec passed to `tool(...)`. `execute` receives the model's input
+ * already validated + typed against `input` — no need to call
+ * `input.parse` manually.
+ */
+export interface ZodToolSpec<TInput, TOutput> {
+  name: string
+  description: string
+  input: z.ZodType<TInput>
+  execute(input: TInput, ctx: ToolContext): Promise<TOutput>
+}
+
+/**
+ * Build a framework `Tool` from a Zod-typed spec. The wrapper
+ * derives `inputSchema` via `z.toJSONSchema` and validates the
+ * model's raw input through `input.parse` before delegating to
+ * `execute`. Validation failures propagate as `ZodError`; the
+ * agentic loop wraps that into a `ToolExecutionError`.
+ *
+ * ```ts
+ * const search = tool({
+ *   name: 'search_orders',
+ *   description: 'Look up an order by id.',
+ *   input: z.object({ orderId: z.string() }),
+ *   async execute({ orderId }, ctx) {
+ *     //         ^? { orderId: string }
+ *     return await orders.find(orderId, ctx.context)
+ *   },
+ * })
+ * ```
+ */
+export function tool<TInput, TOutput>(
+  spec: ZodToolSpec<TInput, TOutput>,
+): Tool<TInput, TOutput> {
+  const jsonSchema = z.toJSONSchema(spec.input) as Record<string, unknown>
+  return {
+    name: spec.name,
+    description: spec.description,
+    inputSchema: jsonSchema,
+    async execute(raw: TInput, ctx: ToolContext): Promise<TOutput> {
+      const parsed = spec.input.parse(raw)
+      return spec.execute(parsed, ctx)
+    },
+  }
+}
+
+function zodDescription(schema: z.ZodType<unknown>): string | undefined {
+  // Zod stores `.describe(…)` on the schema's `_def`; surface it
+  // as the model-facing hint when callers don't pass one
+  // explicitly.
+  const def = (schema as unknown as { description?: string }).description
+  return typeof def === 'string' && def.length > 0 ? def : undefined
+}

package/src/provider.ts

@@ -1,74 +0,0 @@
-/**
- * `Provider` — the contract every brain backend implements.
- *
- * Each concrete provider (Anthropic, OpenAI later, Gemini later,
- * DeepSeek later) wraps the vendor's SDK and translates the framework
- * shapes (`Message`, `ChatOptions`) into the vendor's native request,
- * then translates the response back into `ChatResult` / `StreamEvent`.
- *
- * Providers are values, not classes — apps use them via the
- * `BrainManager` facade. The interface is exported so apps that need
- * to plug in a custom provider (e.g. a local Ollama) can do so without
- * subclassing.
- */
-
-import type { AgentResult } from './agent_result.ts'
-import type { Tool } from './tool.ts'
-import type {
-  ChatOptions,
-  ChatResult,
-  Message,
-  StreamEvent,
-} from './types.ts'
-
-export interface RunWithToolsOptions extends ChatOptions {
-  /** Safety ceiling on tool-use round-trips. Default `10`. */
-  maxIterations?: number
-  /** Free-form context bag passed to every tool's `execute(input, ctx)`. */
-  context?: Record<string, unknown>
-}
-
-export interface Provider {
-  /** Identifier — matches the `config.brain.providers` key. */
-  readonly name: string
-
-  /**
-   * Generate a single reply. Awaits the full response; for
-   * token-by-token rendering use `stream()`.
-   */
-  chat(messages: readonly Message[], options?: ChatOptions): Promise<ChatResult>
-
-  /**
-   * Stream the reply as it's generated. The async iterable yields
-   * `text` events for each delta and a final `stop` event with usage
-   * + stop-reason. Apps that want the full collected message at the
-   * end pass the same `messages` to `chat()` instead; this surface is
-   * for UI streaming, not for "make one call and get the message".
-   */
-  stream(messages: readonly Message[], options?: ChatOptions): AsyncIterable<StreamEvent>
-
-  /**
-   * Count input tokens for a given message set + options. Used by
-   * apps that need to budget context before sending. Optional — not
-   * every provider exposes a cheap token-count endpoint, so the
-   * implementation may approximate.
-   */
-  countTokens?(messages: readonly Message[], options?: ChatOptions): Promise<number>
-
-  /**
-   * Agentic loop. Sends the `messages` + `tools` to the model;
-   * detects tool-use blocks in the response; runs the matching
-   * tool's `execute`; appends the result and re-asks. Loops until
-   * the model returns `stop_reason: 'end_turn'` (or its
-   * provider-specific equivalent) or `maxIterations` is hit.
-   *
-   * Optional on the interface so providers that don't (yet) support
-   * tool use can omit it; `BrainManager.runTools` throws a
-   * `BrainError` when the configured provider lacks the method.
-   */
-  runWithTools?(
-    messages: readonly Message[],
-    tools: readonly Tool[],
-    options?: RunWithToolsOptions,
-  ): Promise<AgentResult>
-}

package/src/providers/anthropic_provider.ts

@@ -1,397 +0,0 @@
-/**
- * `AnthropicProvider` — implementation of `Provider` backed by the
- * official `@anthropic-ai/sdk`.
- *
- * Responsibilities:
- *   1. Hold a singleton `Anthropic` client instance for the
- *      configured API key + base URL.
- *   2. Translate the framework's `ChatOptions` / `Message` shapes
- *      into Anthropic's `MessageCreateParams` (system as `TextBlock[]`
- *      with `cache_control` when requested; messages with per-block
- *      cache flags translated likewise; `thinking` mapped to
- *      `ThinkingConfigParam`; `effort` placed under `output_config`).
- *   3. Translate the response back to `ChatResult` — flatten the
- *      content blocks into a single `text` string, surface usage with
- *      cache-hit counters, and pass the raw `Message` through on `.raw`.
- *   4. Stream via `client.messages.stream()` and yield the framework
- *      `StreamEvent` union — `text` deltas plus a terminal `stop`
- *      event with usage + stop reason.
- *
- * Errors from the SDK propagate; apps that want provider-specific
- * recovery can `instanceof Anthropic.RateLimitError` etc. The brain
- * facade wraps the call site in `BrainError` only for invariants the
- * facade owns (e.g. "no provider configured").
- */
-
-import Anthropic from '@anthropic-ai/sdk'
-import type { AgentResult } from '../agent_result.ts'
-import type { AnthropicProviderConfig } from '../brain_config.ts'
-import { DEFAULT_MODEL } from '../brain_config.ts'
-import type { Provider, RunWithToolsOptions } from '../provider.ts'
-import type { Tool } from '../tool.ts'
-import { ToolExecutionError } from '../tool_execution_error.ts'
-import type {
-  ChatOptions,
-  ChatResult,
-  ChatUsage,
-  ContentBlock,
-  Message,
-  StreamEvent,
-  SystemPrompt,
-  TextBlock,
-  ToolResultBlock,
-  ToolUseBlock,
-} from '../types.ts'
-
-const EPHEMERAL_CACHE = { type: 'ephemeral' } as const
-
-export class AnthropicProvider implements Provider {
-  readonly name: string
-  private readonly client: Anthropic
-  private readonly defaultModel: string
-  private readonly defaultMaxTokens: number
-  private readonly betas: readonly string[]
-
-  constructor(
-    name: string,
-    config: AnthropicProviderConfig,
-    options: { client?: Anthropic } = {},
-  ) {
-    this.name = name
-    this.defaultModel = config.defaultModel ?? DEFAULT_MODEL
-    this.defaultMaxTokens = config.defaultMaxTokens ?? 4096
-    this.betas = config.betas ?? []
-    // `client` injection point — tests pass a stub; apps that want a
-    // pre-configured SDK instance (custom retry, fetch transport, etc.)
-    // build their own and hand it over here.
-    this.client =
-      options.client ??
-      new Anthropic({
-        apiKey: config.apiKey,
-        ...(config.baseUrl !== undefined ? { baseURL: config.baseUrl } : {}),
-      })
-  }
-
-  async chat(messages: readonly Message[], options: ChatOptions = {}): Promise<ChatResult> {
-    const params = this.buildParams(messages, options)
-    const response = await this.client.messages.create(params)
-    return this.toChatResult(response)
-  }
-
-  async *stream(
-    messages: readonly Message[],
-    options: ChatOptions = {},
-  ): AsyncIterable<StreamEvent> {
-    const params = this.buildParams(messages, options)
-    const stream = this.client.messages.stream(params)
-    for await (const event of stream) {
-      if (
-        event.type === 'content_block_delta' &&
-        event.delta.type === 'text_delta'
-      ) {
-        yield { type: 'text', delta: event.delta.text }
-      }
-    }
-    const final = await stream.finalMessage()
-    yield {
-      type: 'stop',
-      stopReason: final.stop_reason,
-      usage: toUsage(final.usage),
-    }
-  }
-
-  async countTokens(
-    messages: readonly Message[],
-    options: ChatOptions = {},
-  ): Promise<number> {
-    const base = this.buildParams(messages, options)
-    // count_tokens only accepts a subset of MessageCreateParams; build
-    // a focused payload that matches what apps actually need to budget.
-    const result = await this.client.messages.countTokens({
-      model: base.model,
-      messages: base.messages,
-      ...(base.system !== undefined ? { system: base.system } : {}),
-      ...(base.thinking !== undefined ? { thinking: base.thinking } : {}),
-    })
-    return result.input_tokens
-  }
-
-  /**
-   * Agentic loop. Send → detect tool_use blocks → execute → append
-   * tool_result → re-send, until the model returns `end_turn` or
-   * the iteration ceiling is hit.
-   *
-   * Tools are passed once on every call — Anthropic doesn't carry
-   * tool state across requests; the model rediscovers them from the
-   * `tools` array each turn. Apps that care about cache hits keep
-   * the tool list stable across runs.
-   */
-  async runWithTools(
-    messages: readonly Message[],
-    tools: readonly Tool[],
-    options: RunWithToolsOptions = {},
-  ): Promise<AgentResult> {
-    const maxIterations = options.maxIterations ?? 10
-    const toolMap = new Map<string, Tool>(tools.map((t) => [t.name, t]))
-    const workingMessages: Message[] = [...messages]
-    const aggregated: ChatUsage = {
-      inputTokens: 0,
-      outputTokens: 0,
-      cacheReadTokens: 0,
-      cacheCreationTokens: 0,
-    }
-    let iterations = 0
-    let lastStopReason: string | null = null
-
-    while (true) {
-      const params = this.buildParams(workingMessages, options)
-      params.tools = tools.map((t) => ({
-        name: t.name,
-        description: t.description,
-        input_schema: t.inputSchema as Anthropic.Tool.InputSchema,
-      }))
-
-      const response = await this.client.messages.create(params)
-      addUsage(aggregated, response.usage)
-      lastStopReason = response.stop_reason ?? null
-
-      // Append the assistant turn verbatim from the SDK shape so
-      // tool_use blocks survive to the next request unchanged.
-      workingMessages.push({
-        role: 'assistant',
-        content: fromAnthropicContent(response.content),
-      })
-
-      if (response.stop_reason !== 'tool_use') {
-        return {
-          text: collectText(response.content),
-          messages: workingMessages,
-          iterations,
-          stopReason: lastStopReason ?? 'end_turn',
-          usage: aggregated,
-        }
-      }
-
-      // Execute every tool_use block in the response and append the
-      // results in a single user-role turn. The SDK's API expects all
-      // tool_result blocks for a given assistant turn to land in the
-      // same user message.
-      const toolUseBlocks = response.content.filter(
-        (b): b is Anthropic.ToolUseBlock => b.type === 'tool_use',
-      )
-      const resultBlocks: ContentBlock[] = []
-      for (const block of toolUseBlocks) {
-        const tool = toolMap.get(block.name)
-        if (!tool) {
-          throw new ToolExecutionError(
-            block.name,
-            block.id,
-            new Error(`Tool "${block.name}" is not registered.`),
-          )
-        }
-        let output: unknown
-        try {
-          output = await tool.execute(block.input, {
-            callId: block.id,
-            context: options.context ?? {},
-          })
-        } catch (cause) {
-          throw new ToolExecutionError(block.name, block.id, cause)
-        }
-        const resultBlock: ToolResultBlock = {
-          type: 'tool_result',
-          toolUseId: block.id,
-          content: typeof output === 'string' ? output : JSON.stringify(output),
-        }
-        resultBlocks.push(resultBlock)
-      }
-      workingMessages.push({ role: 'user', content: resultBlocks })
-
-      iterations++
-      if (iterations >= maxIterations) {
-        return {
-          text: collectText(response.content),
-          messages: workingMessages,
-          iterations,
-          stopReason: 'max_iterations',
-          usage: aggregated,
-        }
-      }
-    }
-  }
-
-  // ─── Param translation ──────────────────────────────────────────────────
-
-  private buildParams(
-    messages: readonly Message[],
-    options: ChatOptions,
-  ): Anthropic.MessageCreateParamsNonStreaming {
-    const model = options.model ?? this.defaultModel
-    const params: Anthropic.MessageCreateParamsNonStreaming = {
-      model,
-      max_tokens: options.maxTokens ?? this.defaultMaxTokens,
-      messages: messages.map(toMessageParam),
-    }
-
-    const system = toSystemParam(options.system)
-    if (system !== undefined) params.system = system
-
-    if (options.thinking === 'adaptive') {
-      params.thinking = { type: 'adaptive' }
-    } else if (options.thinking === 'disabled') {
-      params.thinking = { type: 'disabled' }
-    }
-
-    if (options.effort !== undefined) {
-      params.output_config = { effort: options.effort }
-    }
-
-    if (options.cache === true) {
-      // Top-level auto-cache the last cacheable block. Maps to the
-      // SDK's `cache_control` shorthand on the request body.
-      ;(params as { cache_control?: { type: 'ephemeral' } }).cache_control = EPHEMERAL_CACHE
-    }
-
-    const betas = mergeBetas(this.betas, options.betas)
-    if (betas.length > 0) {
-      ;(params as { betas?: readonly string[] }).betas = betas
-    }
-
-    return params
-  }
-
-  private toChatResult(message: Anthropic.Message): ChatResult<Anthropic.Message> {
-    const text = message.content
-      .filter((b): b is Anthropic.TextBlock => b.type === 'text')
-      .map((b) => b.text)
-      .join('')
-    return {
-      text,
-      model: message.model,
-      stopReason: message.stop_reason,
-      usage: toUsage(message.usage),
-      raw: message,
-    }
-  }
-}
-
-// ─── Shape converters ─────────────────────────────────────────────────────
-
-function toUsage(u: Anthropic.Usage): ChatUsage {
-  return {
-    inputTokens: u.input_tokens,
-    outputTokens: u.output_tokens,
-    cacheReadTokens: u.cache_read_input_tokens ?? 0,
-    cacheCreationTokens: u.cache_creation_input_tokens ?? 0,
-  }
-}
-
-function toMessageParam(message: Message): Anthropic.MessageParam {
-  if (typeof message.content === 'string') {
-    return { role: message.role, content: message.content }
-  }
-  return {
-    role: message.role,
-    content: message.content.map((block): Anthropic.ContentBlockParam => {
-      if (block.type === 'tool_use') {
-        return {
-          type: 'tool_use',
-          id: block.id,
-          name: block.name,
-          input: block.input as Record<string, unknown>,
-        }
-      }
-      if (block.type === 'tool_result') {
-        const param: Anthropic.ToolResultBlockParam = {
-          type: 'tool_result',
-          tool_use_id: block.toolUseId,
-          content:
-            typeof block.content === 'string'
-              ? block.content
-              : block.content.map((b) => ({ type: 'text', text: b.text }) as Anthropic.TextBlockParam),
-        }
-        if (block.isError) param.is_error = true
-        return param
-      }
-      const text: Anthropic.TextBlockParam = { type: 'text', text: block.text }
-      if (block.cache) text.cache_control = EPHEMERAL_CACHE
-      return text
-    }),
-  }
-}
-
-function toSystemParam(
-  system: SystemPrompt | undefined,
-): string | Anthropic.TextBlockParam[] | undefined {
-  if (system === undefined) return undefined
-  if (typeof system === 'string') return system
-  if (Array.isArray(system)) {
-    return system.map((block) => {
-      const param: Anthropic.TextBlockParam = { type: 'text', text: block.text }
-      if (block.cache) param.cache_control = EPHEMERAL_CACHE
-      return param
-    })
-  }
-  const param: Anthropic.TextBlockParam = { type: 'text', text: system.text }
-  if (system.cache) param.cache_control = EPHEMERAL_CACHE
-  return [param]
-}
-
-function mergeBetas(
-  providerBetas: readonly string[],
-  callBetas: readonly string[] | undefined,
-): readonly string[] {
-  if (!callBetas || callBetas.length === 0) return providerBetas
-  const seen = new Set<string>()
-  const out: string[] = []
-  for (const b of providerBetas) {
-    if (seen.has(b)) continue
-    seen.add(b)
-    out.push(b)
-  }
-  for (const b of callBetas) {
-    if (seen.has(b)) continue
-    seen.add(b)
-    out.push(b)
-  }
-  return out
-}
-
-function addUsage(acc: ChatUsage, u: Anthropic.Usage): void {
-  acc.inputTokens += u.input_tokens
-  acc.outputTokens += u.output_tokens
-  acc.cacheReadTokens += u.cache_read_input_tokens ?? 0
-  acc.cacheCreationTokens += u.cache_creation_input_tokens ?? 0
-}
-
-function collectText(content: Anthropic.ContentBlock[]): string {
-  return content
-    .filter((b): b is Anthropic.TextBlock => b.type === 'text')
-    .map((b) => b.text)
-    .join('')
-}
-
-/**
- * Translate the SDK's response content blocks back into framework
- * `ContentBlock`s for storage in `workingMessages`. We preserve
- * `text` and `tool_use` blocks verbatim; other server-side block
- * types (thinking, server tool blocks) are dropped — V1 doesn't
- * surface them, and re-sending them as part of the assistant turn
- * could confuse the model.
- */
-function fromAnthropicContent(content: Anthropic.ContentBlock[]): ContentBlock[] {
-  const out: ContentBlock[] = []
-  for (const block of content) {
-    if (block.type === 'text') {
-      out.push({ type: 'text', text: block.text } satisfies TextBlock)
-    } else if (block.type === 'tool_use') {
-      out.push({
-        type: 'tool_use',
-        id: block.id,
-        name: block.name,
-        input: block.input,
-      } satisfies ToolUseBlock)
-    }
-  }
-  return out
-}