@strav/brain 0.1.0

package/src/providers/openai_responses_provider.ts

@@ -0,0 +1,319 @@
+import { parseSSE } from '../utils/sse_parser.ts'
+import { retryableFetch, type RetryOptions } from '../utils/retry.ts'
+import { ExternalServiceError } from '@stravigor/kernel'
+import type {
+  AIProvider,
+  CompletionRequest,
+  CompletionResponse,
+  StreamChunk,
+  ProviderConfig,
+  Message,
+  ToolCall,
+  Usage,
+} from '../types.ts'
+
+/**
+ * OpenAI Responses API provider (`/v1/responses`).
+ *
+ * Drop-in replacement for the Chat Completions provider.
+ * Implements the same `AIProvider` interface so Thread, AgentRunner,
+ * and all Brain helpers work unchanged.
+ */
+export class OpenAIResponsesProvider implements AIProvider {
+  readonly name: string
+  private apiKey: string
+  private baseUrl: string
+  private defaultModel: string
+  private defaultMaxTokens?: number
+  private retryOptions: RetryOptions
+
+  constructor(config: ProviderConfig, name?: string) {
+    this.name = name ?? 'openai'
+    this.apiKey = config.apiKey
+    this.baseUrl = (config.baseUrl ?? 'https://api.openai.com').replace(/\/$/, '')
+    this.defaultModel = config.model
+    this.defaultMaxTokens = config.maxTokens
+    this.retryOptions = {
+      maxRetries: config.maxRetries ?? 3,
+      baseDelay: config.retryBaseDelay ?? 1000,
+    }
+  }
+
+  // ── Non-streaming completion ────────────────────────────────────────────
+
+  async complete(request: CompletionRequest): Promise<CompletionResponse> {
+    const body = this.buildRequestBody(request, false)
+
+    const response = await retryableFetch(
+      'OpenAI',
+      `${this.baseUrl}/v1/responses`,
+      { method: 'POST', headers: this.buildHeaders(), body: JSON.stringify(body) },
+      this.retryOptions
+    )
+
+    const data: any = await response.json()
+    return this.parseResponse(data)
+  }
+
+  // ── Streaming completion ────────────────────────────────────────────────
+
+  async *stream(request: CompletionRequest): AsyncIterable<StreamChunk> {
+    const body = this.buildRequestBody(request, true)
+
+    const response = await retryableFetch(
+      'OpenAI',
+      `${this.baseUrl}/v1/responses`,
+      { method: 'POST', headers: this.buildHeaders(), body: JSON.stringify(body) },
+      this.retryOptions
+    )
+
+    if (!response.body) {
+      throw new ExternalServiceError('OpenAI', undefined, 'No stream body returned')
+    }
+
+    // Track function call items by output_index for tool_start/tool_delta mapping
+    const toolIndexMap = new Map<number, { callId: string; name: string }>()
+    let toolCounter = 0
+
+    for await (const sse of parseSSE(response.body)) {
+      const eventType = sse.event ?? ''
+      let data: any
+
+      try {
+        data = JSON.parse(sse.data)
+      } catch {
+        continue
+      }
+
+      // ── Text content ──────────────────────────────────────────────
+      if (eventType === 'response.output_text.delta') {
+        yield { type: 'text', text: data.delta ?? '' }
+        continue
+      }
+
+      // ── Function call start ───────────────────────────────────────
+      if (eventType === 'response.output_item.added' && data.item?.type === 'function_call') {
+        const index = toolCounter++
+        toolIndexMap.set(data.output_index ?? index, {
+          callId: data.item.call_id ?? '',
+          name: data.item.name ?? '',
+        })
+        yield {
+          type: 'tool_start',
+          toolCall: { id: data.item.call_id ?? '', name: data.item.name ?? '' },
+          toolIndex: index,
+        }
+        continue
+      }
+
+      // ── Function call argument deltas ─────────────────────────────
+      if (eventType === 'response.function_call_arguments.delta') {
+        // Map output_index to our sequential toolIndex
+        const outputIdx = data.output_index ?? 0
+        let toolIdx = 0
+        for (const [oi] of toolIndexMap) {
+          if (oi === outputIdx) break
+          toolIdx++
+        }
+        yield { type: 'tool_delta', text: data.delta ?? '', toolIndex: toolIdx }
+        continue
+      }
+
+      // ── Function call arguments done ──────────────────────────────
+      if (eventType === 'response.function_call_arguments.done') {
+        const outputIdx = data.output_index ?? 0
+        let toolIdx = 0
+        for (const [oi] of toolIndexMap) {
+          if (oi === outputIdx) break
+          toolIdx++
+        }
+        yield { type: 'tool_end', toolIndex: toolIdx }
+        continue
+      }
+
+      // ── Response completed ────────────────────────────────────────
+      if (eventType === 'response.completed') {
+        const usage = data.response?.usage
+        if (usage) {
+          yield {
+            type: 'usage',
+            usage: {
+              inputTokens: usage.input_tokens ?? 0,
+              outputTokens: usage.output_tokens ?? 0,
+              totalTokens: usage.total_tokens ?? 0,
+            },
+          }
+        }
+        yield { type: 'done' }
+        break
+      }
+
+      // ── Error ─────────────────────────────────────────────────────
+      if (eventType === 'error') {
+        throw new ExternalServiceError('OpenAI', undefined, data.message ?? JSON.stringify(data))
+      }
+    }
+  }
+
+  // ── Private helpers ─────────────────────────────────────────────────────
+
+  private buildHeaders(): Record<string, string> {
+    return {
+      'content-type': 'application/json',
+      authorization: `Bearer ${this.apiKey}`,
+    }
+  }
+
+  private buildRequestBody(request: CompletionRequest, stream: boolean): Record<string, unknown> {
+    const body: Record<string, unknown> = {
+      model: request.model ?? this.defaultModel,
+      input: this.mapMessages(request.messages),
+    }
+
+    // System prompt → instructions
+    if (request.system) {
+      body.instructions = request.system
+    }
+
+    if (stream) body.stream = true
+    if (request.maxTokens ?? this.defaultMaxTokens) {
+      body.max_output_tokens = request.maxTokens ?? this.defaultMaxTokens
+    }
+    // Note: temperature is not supported by the Responses API for some models
+    // if (request.temperature !== undefined) body.temperature = request.temperature
+    if (request.stopSequences?.length) body.stop = request.stopSequences
+
+    // Tools
+    if (request.tools?.length) {
+      body.tools = request.tools.map(t => ({
+        type: 'function',
+        name: t.name,
+        description: t.description,
+        parameters: t.parameters,
+      }))
+    }
+
+    // Tool choice
+    if (request.toolChoice) {
+      if (typeof request.toolChoice === 'string') {
+        body.tool_choice = request.toolChoice
+      } else {
+        body.tool_choice = {
+          type: 'function',
+          name: request.toolChoice.name,
+        }
+      }
+    }
+
+    // Structured output
+    if (request.schema) {
+      body.text = {
+        format: {
+          type: 'json_schema',
+          name: 'response',
+          schema: request.schema,
+          strict: true,
+        },
+      }
+    }
+
+    return body
+  }
+
+  /**
+   * Translate Brain Message[] into Responses API input items.
+   *
+   * User messages → { role: 'user', content }
+   * Assistant messages → assistant message item + separate function_call items
+   * Tool messages → { type: 'function_call_output', call_id, output }
+   */
+  private mapMessages(messages: Message[]): any[] {
+    const items: any[] = []
+
+    for (const msg of messages) {
+      if (msg.role === 'user') {
+        items.push({
+          role: 'user',
+          content: typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content),
+        })
+      } else if (msg.role === 'assistant') {
+        const text = typeof msg.content === 'string' ? msg.content : ''
+
+        // Add assistant message item (only if there's text content)
+        if (text) {
+          items.push({
+            type: 'message',
+            role: 'assistant',
+            content: [{ type: 'output_text', text }],
+          })
+        }
+
+        // Add function_call items for any tool calls
+        if (msg.toolCalls?.length) {
+          for (const tc of msg.toolCalls) {
+            items.push({
+              type: 'function_call',
+              call_id: tc.id,
+              name: tc.name,
+              arguments: JSON.stringify(tc.arguments),
+            })
+          }
+        }
+      } else if (msg.role === 'tool') {
+        items.push({
+          type: 'function_call_output',
+          call_id: msg.toolCallId ?? '',
+          output: typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content),
+        })
+      }
+    }
+
+    return items
+  }
+
+  /**
+   * Parse a non-streaming Responses API response into Brain CompletionResponse.
+   */
+  private parseResponse(data: any): CompletionResponse {
+    const output: any[] = data.output ?? []
+    let content = ''
+    const toolCalls: ToolCall[] = []
+
+    for (const item of output) {
+      if (item.type === 'message' && item.role === 'assistant') {
+        for (const part of item.content ?? []) {
+          if (part.type === 'output_text') {
+            content += part.text ?? ''
+          }
+        }
+      } else if (item.type === 'function_call') {
+        let args: Record<string, unknown> = {}
+        try {
+          args = JSON.parse(item.arguments ?? '{}')
+        } catch {
+          args = item.arguments ? { _raw: item.arguments } : {}
+        }
+        toolCalls.push({
+          id: item.call_id ?? item.id ?? '',
+          name: item.name ?? '',
+          arguments: args,
+        })
+      }
+    }
+
+    const usage: Usage = {
+      inputTokens: data.usage?.input_tokens ?? 0,
+      outputTokens: data.usage?.output_tokens ?? 0,
+      totalTokens: data.usage?.total_tokens ?? 0,
+    }
+
+    let stopReason: CompletionResponse['stopReason'] = 'end'
+    if (toolCalls.length > 0) {
+      stopReason = 'tool_use'
+    } else if (data.status === 'incomplete') {
+      stopReason = 'max_tokens'
+    }
+
+    return { id: data.id ?? '', content, toolCalls, stopReason, usage, raw: data }
+  }
+}

package/src/tool.ts

@@ -0,0 +1,50 @@
+import { zodToJsonSchema } from './utils/schema.ts'
+import type { ToolDefinition, JsonSchema } from './types.ts'
+
+/**
+ * Define a tool that an agent can invoke.
+ *
+ * Accepts either a Zod schema or a raw JSON Schema object
+ * for `parameters`. Zod schemas are automatically converted.
+ *
+ * @example
+ * const searchTool = defineTool({
+ *   name: 'search',
+ *   description: 'Search the database',
+ *   parameters: z.object({ query: z.string() }),
+ *   execute: async ({ query }) => {
+ *     return await db.search(query)
+ *   },
+ * })
+ */
+export function defineTool(config: {
+  name: string
+  description: string
+  parameters: any
+  execute: (args: any) => unknown | Promise<unknown>
+}): ToolDefinition {
+  return {
+    name: config.name,
+    description: config.description,
+    parameters: zodToJsonSchema(config.parameters) as JsonSchema,
+    execute: config.execute,
+  }
+}
+
+/**
+ * Group related tools into a named collection.
+ *
+ * A toolbox is simply a labeled array — useful for organizing
+ * tools by domain (e.g., database tools, API tools) and
+ * spreading them into an agent's `tools` array.
+ *
+ * @example
+ * const dbTools = defineToolbox('database', [searchTool, insertTool])
+ *
+ * class MyAgent extends Agent {
+ *   tools = [...dbTools, weatherTool]
+ * }
+ */
+export function defineToolbox(_name: string, tools: ToolDefinition[]): ToolDefinition[] {
+  return tools
+}

package/src/types.ts

@@ -0,0 +1,182 @@
+// ── JSON Schema ──────────────────────────────────────────────────────────────
+
+/** Minimal recursive JSON Schema type. */
+export type JsonSchema = Record<string, unknown>
+
+// ── SSE ──────────────────────────────────────────────────────────────────────
+
+export interface SSEEvent {
+  event?: string
+  data: string
+}
+
+// ── Usage ────────────────────────────────────────────────────────────────────
+
+export interface Usage {
+  inputTokens: number
+  outputTokens: number
+  totalTokens: number
+}
+
+// ── Messages ─────────────────────────────────────────────────────────────────
+
+export interface ToolCall {
+  id: string
+  name: string
+  arguments: Record<string, unknown>
+}
+
+export interface ContentBlock {
+  type: 'text' | 'tool_use' | 'tool_result'
+  text?: string
+  id?: string
+  name?: string
+  input?: Record<string, unknown>
+  toolUseId?: string
+  content?: string
+}
+
+export interface Message {
+  role: 'user' | 'assistant' | 'tool'
+  content: string | ContentBlock[]
+  toolCalls?: ToolCall[]
+  toolCallId?: string
+}
+
+// ── Tool Definition ──────────────────────────────────────────────────────────
+
+export interface ToolDefinition {
+  name: string
+  description: string
+  parameters: JsonSchema
+  execute: (args: Record<string, unknown>) => unknown | Promise<unknown>
+}
+
+// ── Completion Request / Response ────────────────────────────────────────────
+
+export interface CompletionRequest {
+  model: string
+  messages: Message[]
+  system?: string
+  tools?: ToolDefinition[]
+  toolChoice?: 'auto' | 'required' | { name: string }
+  maxTokens?: number
+  temperature?: number
+  schema?: JsonSchema
+  stopSequences?: string[]
+}
+
+export interface CompletionResponse {
+  id: string
+  content: string
+  toolCalls: ToolCall[]
+  stopReason: 'end' | 'tool_use' | 'max_tokens' | 'stop_sequence'
+  usage: Usage
+  raw: unknown
+}
+
+// ── Streaming ────────────────────────────────────────────────────────────────
+
+export interface StreamChunk {
+  type: 'text' | 'tool_start' | 'tool_delta' | 'tool_end' | 'usage' | 'done'
+  text?: string
+  toolCall?: Partial<ToolCall>
+  toolIndex?: number
+  usage?: Usage
+}
+
+// ── Output Schema ────────────────────────────────────────────────────────────
+
+/** A schema that optionally validates data via `.parse()` (e.g., Zod schema). */
+export interface OutputSchema {
+  parse?: (data: unknown) => unknown
+  [key: string]: unknown
+}
+
+// ── Agent ────────────────────────────────────────────────────────────────────
+
+export interface ToolCallRecord {
+  name: string
+  arguments: Record<string, unknown>
+  result: unknown
+  duration: number
+}
+
+export interface AgentResult<T = any> {
+  data: T
+  text: string
+  toolCalls: ToolCallRecord[]
+  messages: Message[]
+  usage: Usage
+  iterations: number
+}
+
+export interface AgentEvent {
+  type: 'text' | 'tool_start' | 'tool_result' | 'iteration' | 'done'
+  text?: string
+  toolCall?: ToolCallRecord
+  iteration?: number
+  result?: AgentResult
+}
+
+// ── Workflow ──────────────────────────────────────────────────────────────────
+
+export interface WorkflowResult {
+  results: Record<string, AgentResult>
+  usage: Usage
+  duration: number
+}
+
+// ── Embedding ────────────────────────────────────────────────────────────────
+
+export interface EmbeddingResponse {
+  embeddings: number[][]
+  model: string
+  usage: { totalTokens: number }
+}
+
+// ── Provider ─────────────────────────────────────────────────────────────────
+
+export interface AIProvider {
+  readonly name: string
+  complete(request: CompletionRequest): Promise<CompletionResponse>
+  stream(request: CompletionRequest): AsyncIterable<StreamChunk>
+  embed?(input: string | string[], model?: string): Promise<EmbeddingResponse>
+}
+
+// ── Hooks ────────────────────────────────────────────────────────────────────
+
+export type BeforeHook = (request: CompletionRequest) => void | Promise<void>
+export type AfterHook = (
+  request: CompletionRequest,
+  response: CompletionResponse
+) => void | Promise<void>
+
+// ── Config ───────────────────────────────────────────────────────────────────
+
+export interface ProviderConfig {
+  driver: string
+  apiKey: string
+  model: string
+  baseUrl?: string
+  maxTokens?: number
+  temperature?: number
+  maxRetries?: number
+  retryBaseDelay?: number
+}
+
+export interface BrainConfig {
+  default: string
+  providers: Record<string, ProviderConfig>
+  maxTokens: number
+  temperature: number
+  maxIterations: number
+  memory?: import('./memory/types.ts').MemoryConfig
+}
+
+// ── Serialized Thread ────────────────────────────────────────────────────────
+
+export interface SerializedThread {
+  messages: Message[]
+  system?: string
+}

package/src/utils/retry.ts

@@ -0,0 +1,100 @@
+import { ExternalServiceError } from '@stravigor/kernel'
+
+export interface RetryOptions {
+  maxRetries?: number
+  baseDelay?: number
+  maxDelay?: number
+  retryableStatuses?: number[]
+}
+
+const DEFAULT_RETRYABLE = [429, 500, 502, 503, 529]
+
+/**
+ * Fetch with automatic retry and exponential backoff for transient errors.
+ *
+ * Retries on 429 (rate limit), 5xx, and network failures.
+ * Parses the `retry-after` header when available; otherwise uses
+ * exponential backoff with jitter.
+ *
+ * Returns the successful `Response`. On final failure, throws
+ * `ExternalServiceError` with the last status and body.
+ */
+export async function retryableFetch(
+  service: string,
+  url: string,
+  init: RequestInit,
+  options?: RetryOptions
+): Promise<Response> {
+  const maxRetries = options?.maxRetries ?? 3
+  const baseDelay = options?.baseDelay ?? 1000
+  const maxDelay = options?.maxDelay ?? 60_000
+  const retryable = options?.retryableStatuses ?? DEFAULT_RETRYABLE
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    let response: Response
+
+    try {
+      response = await fetch(url, init)
+    } catch (err) {
+      // Network error (DNS, connection refused, etc.)
+      if (attempt === maxRetries) {
+        throw new ExternalServiceError(
+          service,
+          undefined,
+          err instanceof Error ? err.message : String(err)
+        )
+      }
+      await sleep(backoffDelay(attempt, baseDelay, maxDelay))
+      continue
+    }
+
+    if (response.ok) return response
+
+    // Non-retryable status — fail immediately
+    if (!retryable.includes(response.status)) {
+      const text = await response.text()
+      throw new ExternalServiceError(service, response.status, text)
+    }
+
+    // Retryable status — wait and retry (unless last attempt)
+    if (attempt === maxRetries) {
+      const text = await response.text()
+      throw new ExternalServiceError(service, response.status, text)
+    }
+
+    const delay = parseRetryAfter(response) ?? backoffDelay(attempt, baseDelay, maxDelay)
+    await sleep(delay)
+  }
+
+  // Unreachable, but satisfies TypeScript
+  throw new ExternalServiceError(service, undefined, 'Retry loop exited unexpectedly')
+}
+
+/**
+ * Parse the `retry-after` header into milliseconds.
+ * Supports both delta-seconds ("2") and HTTP-date formats.
+ */
+function parseRetryAfter(response: Response): number | null {
+  const header = response.headers.get('retry-after')
+  if (!header) return null
+
+  const seconds = Number(header)
+  if (!Number.isNaN(seconds)) return seconds * 1000
+
+  // HTTP-date format
+  const date = Date.parse(header)
+  if (!Number.isNaN(date)) return Math.max(0, date - Date.now())
+
+  return null
+}
+
+/** Exponential backoff with jitter: base * 2^attempt + random jitter, capped at maxDelay. */
+function backoffDelay(attempt: number, baseDelay: number, maxDelay: number): number {
+  const exp = baseDelay * 2 ** attempt
+  const jitter = Math.random() * baseDelay
+  return Math.min(exp + jitter, maxDelay)
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}

package/src/utils/schema.ts

@@ -0,0 +1,27 @@
+import type { JsonSchema } from '../types.ts'
+
+/**
+ * Convert a Zod schema to a JSON Schema object.
+ *
+ * Detection logic:
+ * - If the input has a `toJSONSchema()` method (Zod v4+), use it directly
+ * - If the input is already a plain object (raw JSON Schema), return as-is
+ * - null/undefined pass through unchanged
+ *
+ * The `$schema` meta-field is stripped from the output since
+ * AI provider APIs don't expect it.
+ */
+export function zodToJsonSchema(schema: any): JsonSchema {
+  if (schema == null) return schema
+
+  // Zod v4+: native toJSONSchema() method
+  if (typeof schema.toJSONSchema === 'function') {
+    const jsonSchema = schema.toJSONSchema()
+    // Strip the $schema meta-field — providers don't need it
+    const { $schema, ...rest } = jsonSchema
+    return rest as JsonSchema
+  }
+
+  // Already a plain JSON Schema object
+  return schema as JsonSchema
+}