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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strav/brain",
-  "version": "1.0.0-alpha.13",
+  "version": "1.0.0-alpha.14",
   "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",
@@ -23,7 +23,7 @@
     "@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.14",
     "openai": "^6.0.0"
   },
   "peerDependencies": {

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