@strav/brain 1.0.0-alpha.13 → 1.0.0-alpha.15

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@strav/brain",
-  "version": "1.0.0-alpha.13",
+  "version": "1.0.0-alpha.15",
   "description": "Strav AI module — unified Provider interface, BrainManager, threads, prompt caching, tools / agents / MCP. Anthropic + OpenAI providers; Gemini / DeepSeek follow.",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
-    "./mcp": "./src/mcp/index.ts"
+    "./mcp": "./src/mcp/index.ts",
+    "./zod": "./src/zod/index.ts"
   },
   "files": [
     "src",
@@ -23,11 +24,19 @@
     "@anthropic-ai/sdk": "^0.100.0",
     "@google/genai": "^2.7.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@strav/kernel": "1.0.0-alpha.13",
+    "@strav/kernel": "1.0.0-alpha.15",
     "openai": "^6.0.0"
   },
   "peerDependencies": {
-    "@types/bun": ">=1.3.14"
+    "@types/bun": ">=1.3.14",
+    "zod": "^4.0.0"
   },
-  "devDependencies": null
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "zod": "^4.4.3"
+  }
 }

package/src/brain_manager.ts

@@ -22,12 +22,14 @@
 import type { Agent } from './agent.ts'
 import type { AgentResult } from './agent_result.ts'
 import type { MCPServer } from './mcp_server.ts'
+import type { OutputSchema } from './output_schema.ts'
 import { AgentRunner } from './agent_runner.ts'
 import { BrainError } from './brain_error.ts'
 import type { ModelTier } from './types.ts'
 import type {
   ChatOptions,
   ChatResult,
+  GenerateResult,
   Message,
   StreamEvent,
 } from './types.ts'
@@ -166,6 +168,32 @@ export class BrainManager {
     return provider.runWithTools(messages, tools, resolved)
   }
 
+  /**
+   * Structured output. Sends `input` to the configured (or
+   * `options.provider`-overridden) provider with the JSON-Schema
+   * constraint described by `schema`; returns the parsed object.
+   *
+   * Throws `BrainError` when the chosen provider doesn't implement
+   * `generate`. All three V1 providers (Anthropic, OpenAI, Gemini)
+   * do.
+   */
+  async generate<T>(
+    input: string | readonly Message[],
+    schema: OutputSchema<T>,
+    options: ChatOptions = {},
+  ): Promise<GenerateResult<T>> {
+    const provider = this.provider(options.provider)
+    if (!provider.generate) {
+      throw new BrainError(
+        `BrainManager.generate: provider "${provider.name}" does not implement generate.`,
+        { context: { provider: provider.name } },
+      )
+    }
+    const messages = normalizeInput(input)
+    const resolved = this.applyDefaults(options)
+    return provider.generate<T>(messages, schema, resolved)
+  }
+
   /**
    * Resolve an `Agent` subclass from the container and return an
    * `AgentRunner` ready to receive `input(...)` and `run()`. Apps

package/src/index.ts

@@ -29,6 +29,7 @@ export {
 export { BrainProvider } from './brain_provider.ts'
 export { defineTool, type DefineToolSpec } from './define_tool.ts'
 export type { MCPServer, MCPServerToolConfig } from './mcp_server.ts'
+export type { OutputSchema } from './output_schema.ts'
 export { AnthropicProvider } from './providers/anthropic_provider.ts'
 export { GeminiProvider } from './providers/gemini_provider.ts'
 export { OpenAIProvider } from './providers/openai_provider.ts'
@@ -41,6 +42,7 @@ export type {
   ChatResult,
   ChatUsage,
   ContentBlock,
+  GenerateResult,
   MCPToolResultBlock,
   MCPToolUseBlock,
   Message,

package/src/output_schema.ts

@@ -0,0 +1,72 @@
+/**
+ * `OutputSchema<T>` — declarative description of a structured-output
+ * target. Apps pass one of these to `BrainManager.generate(...)` and
+ * get back a `GenerateResult<T>` whose `value` is the parsed JSON
+ * the model produced.
+ *
+ * Schema shape:
+ *   - `name` — short identifier; OpenAI requires it on
+ *     `response_format.json_schema.name`. Other providers ignore it
+ *     but apps should still set something stable and meaningful for
+ *     logs / telemetry.
+ *   - `description` — optional hint the model sees (some providers
+ *     surface it next to the schema; others embed it in the prompt
+ *     translation).
+ *   - `jsonSchema` — plain JSON Schema (draft 2020-12 compatible).
+ *     The framework deliberately doesn't depend on Zod; apps that
+ *     want Zod use `zod-to-json-schema` (or similar) at the call
+ *     site and feed the result here.
+ *   - `parse` — optional runtime validator/parser. When set, the
+ *     framework runs every model response through it before
+ *     returning. Apps that just want type-level inference (and
+ *     trust the model + provider validation) can omit it; the
+ *     return type is then `T` by type assertion only.
+ *
+ * Why no built-in Zod dep:
+ *   Same reason `Tool.inputSchema` is plain JSON Schema — Strav
+ *   doesn't pin apps to a schema library. A thin `@strav/brain-zod`
+ *   helper that produces `OutputSchema<T>` from a Zod schema is
+ *   straightforward to ship later without touching this file.
+ */
+
+export interface OutputSchema<T = unknown> {
+  /** Short identifier — provider-specific; some surface it, others ignore. */
+  name: string
+  /** Optional hint shown to the model alongside the schema. */
+  description?: string
+  /** JSON Schema describing the expected shape. */
+  jsonSchema: Record<string, unknown>
+  /** Optional runtime parser/validator. Apps that use Zod plug it in here. */
+  parse?(value: unknown): T
+}
+
+/**
+ * Shared helper used by every provider's `generate` implementation:
+ * parse the raw JSON response, run the optional `parse` hook, and
+ * wrap parse failures in `BrainError` with the raw text on `.context`
+ * so apps can inspect what came back when validation rejects.
+ */
+import { BrainError } from './brain_error.ts'
+
+export function parseGenerated<T>(text: string, schema: OutputSchema<T>): T {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(text)
+  } catch (cause) {
+    throw new BrainError(
+      `BrainProvider.generate: response was not valid JSON for schema "${schema.name}".`,
+      { context: { schema: schema.name, text }, cause },
+    )
+  }
+  if (schema.parse) {
+    try {
+      return schema.parse(parsed)
+    } catch (cause) {
+      throw new BrainError(
+        `BrainProvider.generate: response failed schema.parse for "${schema.name}".`,
+        { context: { schema: schema.name, text }, cause },
+      )
+    }
+  }
+  return parsed as T
+}

package/src/provider.ts

@@ -14,10 +14,12 @@
 
 import type { AgentResult } from './agent_result.ts'
 import type { MCPServer } from './mcp_server.ts'
+import type { OutputSchema } from './output_schema.ts'
 import type { Tool } from './tool.ts'
 import type {
   ChatOptions,
   ChatResult,
+  GenerateResult,
   Message,
   StreamEvent,
 } from './types.ts'
@@ -80,4 +82,21 @@ export interface Provider {
     tools: readonly Tool[],
     options?: RunWithToolsOptions,
   ): Promise<AgentResult>
+
+  /**
+   * Structured output. Sends `messages` to the model with a
+   * JSON-Schema constraint and returns the parsed object. Apps that
+   * supplied `schema.parse` get a runtime-validated value; otherwise
+   * the value is `T` by type assertion (the provider does its own
+   * upstream schema enforcement, but the framework doesn't validate).
+   *
+   * Optional on the interface so providers that lack a structured-
+   * output endpoint can omit it; `BrainManager.generate` throws a
+   * `BrainError` when the configured provider doesn't expose this.
+   */
+  generate?<T>(
+    messages: readonly Message[],
+    schema: OutputSchema<T>,
+    options?: ChatOptions,
+  ): Promise<GenerateResult<T>>
 }

package/src/providers/anthropic_provider.ts

@@ -35,6 +35,7 @@ import type {
   ChatResult,
   ChatUsage,
   ContentBlock,
+  GenerateResult,
   MCPToolResultBlock,
   MCPToolUseBlock,
   Message,
@@ -44,6 +45,7 @@ import type {
   ToolResultBlock,
   ToolUseBlock,
 } from '../types.ts'
+import { parseGenerated, type OutputSchema } from '../output_schema.ts'
 
 const EPHEMERAL_CACHE = { type: 'ephemeral' } as const
 
@@ -263,6 +265,29 @@ export class AnthropicProvider implements Provider {
     }
   }
 
+  async generate<T>(
+    messages: readonly Message[],
+    schema: OutputSchema<T>,
+    options: ChatOptions = {},
+  ): Promise<GenerateResult<T>> {
+    const params = this.buildParams(messages, options) as Anthropic.MessageCreateParamsNonStreaming
+    params.output_config = {
+      ...(params.output_config ?? {}),
+      format: { type: 'json_schema', schema: schema.jsonSchema },
+    }
+    const response = await this.client.messages.create(params)
+    const text = collectText(response.content)
+    const value = parseGenerated(text, schema)
+    return {
+      value,
+      text,
+      model: response.model,
+      stopReason: response.stop_reason,
+      usage: toUsage(response.usage),
+      raw: response,
+    }
+  }
+
   // ─── Param translation ──────────────────────────────────────────────────
 
   private buildParams(

package/src/providers/gemini_provider.ts

@@ -61,6 +61,7 @@ import { BrainError } from '../brain_error.ts'
 import type { GeminiProviderConfig } from '../brain_config.ts'
 import type { MCPServer } from '../mcp_server.ts'
 import { resolveMcpTools, type ResolveMcpToolsOptions } from '../mcp/resolve_mcp_tools.ts'
+import { parseGenerated, type OutputSchema } from '../output_schema.ts'
 import type { Provider, RunWithToolsOptions } from '../provider.ts'
 import type { Tool } from '../tool.ts'
 import { ToolExecutionError } from '../tool_execution_error.ts'
@@ -69,6 +70,7 @@ import type {
   ChatResult,
   ChatUsage,
   ContentBlock,
+  GenerateResult,
   Message,
   StreamEvent,
   SystemPrompt,
@@ -272,6 +274,31 @@ export class GeminiProvider implements Provider {
     }
   }
 
+  async generate<T>(
+    messages: readonly Message[],
+    schema: OutputSchema<T>,
+    options: ChatOptions = {},
+  ): Promise<GenerateResult<T>> {
+    const params = this.buildParams(messages, options, [])
+    params.config = {
+      ...(params.config ?? {}),
+      responseMimeType: 'application/json',
+      responseJsonSchema: schema.jsonSchema,
+    }
+    const response = await this.models.generateContent(params)
+    const candidate = response.candidates?.[0]
+    const text = candidateText(candidate)
+    const value = parseGenerated(text, schema)
+    return {
+      value,
+      text,
+      model: response.modelVersion ?? params.model,
+      stopReason: candidate?.finishReason ? String(candidate.finishReason) : null,
+      usage: toUsage(response.usageMetadata),
+      raw: response,
+    }
+  }
+
   // ─── Param translation ──────────────────────────────────────────────────
 
   private buildParams(

package/src/providers/openai_provider.ts

@@ -53,6 +53,7 @@ import { BrainError } from '../brain_error.ts'
 import type { OpenAIProviderConfig } from '../brain_config.ts'
 import type { MCPServer } from '../mcp_server.ts'
 import { resolveMcpTools, type ResolveMcpToolsOptions } from '../mcp/resolve_mcp_tools.ts'
+import { parseGenerated, type OutputSchema } from '../output_schema.ts'
 import type { Provider, RunWithToolsOptions } from '../provider.ts'
 import type { Tool } from '../tool.ts'
 import { ToolExecutionError } from '../tool_execution_error.ts'
@@ -61,6 +62,7 @@ import type {
   ChatResult,
   ChatUsage,
   ContentBlock,
+  GenerateResult,
   Message,
   StreamEvent,
   SystemPrompt,
@@ -257,6 +259,35 @@ export class OpenAIProvider implements Provider {
     }
   }
 
+  async generate<T>(
+    messages: readonly Message[],
+    schema: OutputSchema<T>,
+    options: ChatOptions = {},
+  ): Promise<GenerateResult<T>> {
+    const params = this.buildParams(messages, options, [])
+    params.response_format = {
+      type: 'json_schema',
+      json_schema: {
+        name: schema.name,
+        ...(schema.description !== undefined ? { description: schema.description } : {}),
+        schema: schema.jsonSchema,
+        strict: true,
+      },
+    }
+    const response = await this.client.chat.completions.create(params)
+    const choice = response.choices[0]
+    const text = choice?.message?.content ?? ''
+    const value = parseGenerated(text, schema)
+    return {
+      value,
+      text,
+      model: response.model,
+      stopReason: choice?.finish_reason ?? null,
+      usage: toUsage(response.usage),
+      raw: response,
+    }
+  }
+
   // ─── Param translation ──────────────────────────────────────────────────
 
   private buildParams(

package/src/types.ts

@@ -200,3 +200,18 @@ export interface ChatResult<Raw = unknown> {
 export type StreamEvent =
   | { type: 'text'; delta: string }
   | { type: 'stop'; stopReason: string | null; usage: ChatUsage }
+
+/**
+ * Result of a structured-output call. `value` is the parsed JSON
+ * shaped to the `OutputSchema<T>` passed in. `text` is the raw JSON
+ * string the model produced (useful for logging / debugging when
+ * `parse` rejects). `raw` is the provider's full native response.
+ */
+export interface GenerateResult<T = unknown, Raw = unknown> {
+  value: T
+  text: string
+  model: string
+  stopReason: string | null
+  usage: ChatUsage
+  raw: Raw
+}

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
+}