@strav/brain 0.4.30 → 1.0.0-alpha.8

package/src/providers/anthropic_provider.ts

@@ -1,281 +1,227 @@
-import { parseSSE } from '../utils/sse_parser.ts'
-import { retryableFetch, type RetryOptions } from '../utils/retry.ts'
-import { ExternalServiceError } from '@strav/kernel'
-import type {
-  AIProvider,
-  CompletionRequest,
-  CompletionResponse,
-  StreamChunk,
-  ProviderConfig,
-  Message,
-  ToolCall,
-  Usage,
-} from '../types.ts'
-
 /**
- * Anthropic Messages API provider.
+ * `AnthropicProvider` — implementation of `Provider` backed by the
+ * official `@anthropic-ai/sdk`.
  *
- * Translates the framework's normalized CompletionRequest/Response
- * to/from the Anthropic wire format. Uses raw `fetch()`.
+ * 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").
  */
-export class AnthropicProvider implements AIProvider {
-  readonly name: string
-  private apiKey: string
-  private baseUrl: string
-  private defaultModel: string
-  private defaultMaxTokens: number
-  private retryOptions: RetryOptions
 
-  constructor(config: ProviderConfig) {
-    this.name = 'anthropic'
-    this.apiKey = config.apiKey
-    this.baseUrl = (config.baseUrl ?? 'https://api.anthropic.com').replace(/\/$/, '')
-    this.defaultModel = config.model
-    this.defaultMaxTokens = config.maxTokens ?? 4096
-    this.retryOptions = {
-      maxRetries: config.maxRetries ?? 3,
-      baseDelay: config.retryBaseDelay ?? 1000,
-    }
-  }
-
-  async complete(request: CompletionRequest): Promise<CompletionResponse> {
-    const body = this.buildRequestBody(request, false)
+import Anthropic from '@anthropic-ai/sdk'
+import type { AnthropicProviderConfig } from '../brain_config.ts'
+import { DEFAULT_MODEL } from '../brain_config.ts'
+import type { Provider } from '../provider.ts'
+import type {
+  ChatOptions,
+  ChatResult,
+  ChatUsage,
+  Message,
+  StreamEvent,
+  SystemPrompt,
+} from '../types.ts'
 
-    const response = await retryableFetch(
-      'Anthropic',
-      `${this.baseUrl}/v1/messages`,
-      { method: 'POST', headers: this.buildHeaders(), body: JSON.stringify(body) },
-      this.retryOptions
-    )
+const EPHEMERAL_CACHE = { type: 'ephemeral' } as const
 
-    const data: any = await response.json()
-    return this.parseResponse(data)
+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 *stream(request: CompletionRequest): AsyncIterable<StreamChunk> {
-    const body = this.buildRequestBody(request, true)
-
-    const response = await retryableFetch(
-      'Anthropic',
-      `${this.baseUrl}/v1/messages`,
-      { method: 'POST', headers: this.buildHeaders(), body: JSON.stringify(body) },
-      this.retryOptions
-    )
-
-    if (!response.body) {
-      throw new ExternalServiceError('Anthropic', undefined, 'No stream body returned')
-    }
-
-    let currentBlockIndex = -1
-
-    for await (const sse of parseSSE(response.body)) {
-      if (sse.data === '[DONE]') break
-
-      let parsed: any
-      try {
-        parsed = JSON.parse(sse.data)
-      } catch {
-        continue
-      }
-
-      const type = parsed.type ?? sse.event
+  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)
+  }
 
-      if (type === 'content_block_start') {
-        currentBlockIndex = parsed.index ?? currentBlockIndex + 1
-        const block = parsed.content_block
-        if (block?.type === 'tool_use') {
-          yield {
-            type: 'tool_start',
-            toolCall: { id: block.id, name: block.name },
-            toolIndex: currentBlockIndex,
-          }
-        }
-      } else if (type === 'content_block_delta') {
-        const delta = parsed.delta
-        if (delta?.type === 'text_delta') {
-          yield { type: 'text', text: delta.text }
-        } else if (delta?.type === 'input_json_delta') {
-          yield {
-            type: 'tool_delta',
-            text: delta.partial_json,
-            toolIndex: parsed.index ?? currentBlockIndex,
-          }
-        }
-      } else if (type === 'content_block_stop') {
-        // If we were accumulating a tool call, signal end
-        if (currentBlockIndex >= 0) {
-          yield { type: 'tool_end', toolIndex: parsed.index ?? currentBlockIndex }
-        }
-      } else if (type === 'message_delta') {
-        const usage = parsed.usage
-        if (usage) {
-          yield {
-            type: 'usage',
-            usage: {
-              inputTokens: usage.input_tokens ?? 0,
-              outputTokens: usage.output_tokens ?? 0,
-              totalTokens: (usage.input_tokens ?? 0) + (usage.output_tokens ?? 0),
-            },
-          }
-        }
-      } else if (type === 'message_stop') {
-        yield { type: 'done' }
+  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),
+    }
   }
 
-  // ── Private helpers ──────────────────────────────────────────────────────
-
-  private buildHeaders(): Record<string, string> {
-    return {
-      'content-type': 'application/json',
-      'x-api-key': this.apiKey,
-      'anthropic-version': '2023-06-01',
-    }
+  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
   }
 
-  private buildRequestBody(request: CompletionRequest, stream: boolean): Record<string, unknown> {
-    const body: Record<string, unknown> = {
-      model: request.model ?? this.defaultModel,
-      max_tokens: request.maxTokens ?? this.defaultMaxTokens,
-      messages: this.mapMessages(request.messages),
+  // ─── 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),
     }
 
-    if (stream) body.stream = true
-    if (request.system) body.system = request.system
-    if (request.temperature !== undefined) body.temperature = request.temperature
-    if (request.stopSequences?.length) body.stop_sequences = request.stopSequences
+    const system = toSystemParam(options.system)
+    if (system !== undefined) params.system = system
 
-    // Tools
-    if (request.tools?.length) {
-      body.tools = request.tools.map(t => ({
-        name: t.name,
-        description: t.description,
-        input_schema: t.parameters,
-      }))
+    if (options.thinking === 'adaptive') {
+      params.thinking = { type: 'adaptive' }
+    } else if (options.thinking === 'disabled') {
+      params.thinking = { type: 'disabled' }
     }
 
-    // Tool choice
-    if (request.toolChoice) {
-      if (request.toolChoice === 'auto') {
-        body.tool_choice = { type: 'auto' }
-      } else if (request.toolChoice === 'required') {
-        body.tool_choice = { type: 'any' }
-      } else {
-        body.tool_choice = { type: 'tool', name: request.toolChoice.name }
-      }
+    if (options.effort !== undefined) {
+      params.output_config = { effort: options.effort }
     }
 
-    // Structured output (using GA API with output_config)
-    if (request.schema) {
-      body.output_config = {
-        format: {
-          type: 'json_schema',
-          schema: request.schema
-        }
-      }
+    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
     }
 
-    return body
-  }
-
-  private mapMessages(messages: Message[]): any[] {
-    const result: any[] = []
-
-    for (const msg of messages) {
-      if (msg.role === 'tool') {
-        // Tool results go as user messages with tool_result content blocks
-        result.push({
-          role: 'user',
-          content: [
-            {
-              type: 'tool_result',
-              tool_use_id: msg.toolCallId,
-              content: typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content),
-            },
-          ],
-        })
-      } else if (msg.role === 'assistant') {
-        const content: any[] = []
-
-        // Add text content if present
-        const text = typeof msg.content === 'string' ? msg.content : ''
-        if (text) {
-          content.push({ type: 'text', text })
-        }
+    const betas = mergeBetas(this.betas, options.betas)
+    if (betas.length > 0) {
+      ;(params as { betas?: readonly string[] }).betas = betas
+    }
 
-        // Add tool use blocks
-        if (msg.toolCalls?.length) {
-          for (const tc of msg.toolCalls) {
-            content.push({
-              type: 'tool_use',
-              id: tc.id,
-              name: tc.name,
-              input: tc.arguments,
-            })
-          }
-        }
+    return params
+  }
 
-        result.push({
-          role: 'assistant',
-          content: content.length === 1 && content[0].type === 'text' ? content[0].text : content,
-        })
-      } else {
-        // User messages
-        result.push({
-          role: 'user',
-          content: typeof msg.content === 'string' ? msg.content : msg.content,
-        })
-      }
+  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,
     }
-
-    return result
   }
+}
 
-  private parseResponse(data: any): CompletionResponse {
-    let content = ''
-    const toolCalls: ToolCall[] = []
+// ─── Shape converters ─────────────────────────────────────────────────────
 
-    if (Array.isArray(data.content)) {
-      for (const block of data.content) {
-        if (block.type === 'text') {
-          content += block.text
-        } else if (block.type === 'tool_use') {
-          toolCalls.push({
-            id: block.id,
-            name: block.name,
-            arguments: block.input ?? {},
-          })
-        }
-      }
-    }
+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,
+  }
+}
 
-    const usage: Usage = {
-      inputTokens: data.usage?.input_tokens ?? 0,
-      outputTokens: data.usage?.output_tokens ?? 0,
-      totalTokens: (data.usage?.input_tokens ?? 0) + (data.usage?.output_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) => {
+      const param: Anthropic.TextBlockParam = { type: 'text', text: block.text }
+      if (block.cache) param.cache_control = EPHEMERAL_CACHE
+      return param
+    }),
+  }
+}
 
-    let stopReason: CompletionResponse['stopReason'] = 'end'
-    switch (data.stop_reason) {
-      case 'tool_use':
-        stopReason = 'tool_use'
-        break
-      case 'max_tokens':
-        stopReason = 'max_tokens'
-        break
-      case 'stop_sequence':
-        stopReason = 'stop_sequence'
-        break
-    }
+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]
+}
 
-    return {
-      id: data.id ?? '',
-      content,
-      toolCalls,
-      stopReason,
-      usage,
-      raw: data,
-    }
+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
 }

package/src/thread.ts

@@ -0,0 +1,99 @@
+/**
+ * `Thread` — multi-turn conversation that retains its message history
+ * across calls. Built on top of `BrainManager.chat` (no provider
+ * coupling); apps that want a stateless one-shot use
+ * `BrainManager.chat` directly.
+ *
+ * State model: the thread owns an append-only `messages` array. Each
+ * `send(text)` appends a user turn, calls `brain.chat`, appends the
+ * assistant reply, and returns the assistant's text. The full message
+ * history is serializable via `toJSON()` so apps can persist a thread
+ * across requests (e.g. one row per conversation in Postgres).
+ *
+ * What's NOT here in V1:
+ *   - Auto-compaction. Long threads accumulate without bound; apps
+ *     that need bounded context handle this themselves (prune
+ *     `thread.messages` in place, or use the underlying provider's
+ *     server-side compaction feature once that ships in V2).
+ *   - Streaming `send`. The thread's `send()` is awaited-fully; for
+ *     token-by-token streaming in a conversation, call
+ *     `brain.stream(thread.messages.concat(newUser))` directly.
+ */
+
+import type { BrainManager } from './brain_manager.ts'
+import type { ChatOptions, Message, SystemPrompt } from './types.ts'
+
+export interface ThreadOptions {
+  /** System prompt — applied to every `send()` call. Supports cache flags. */
+  system?: SystemPrompt
+  /** Per-thread `ChatOptions` defaults — merged with per-call overrides on `send()`. */
+  options?: ChatOptions
+}
+
+/** Serializable snapshot. What `toJSON()` produces / `fromJSON()` accepts. */
+export interface ThreadState {
+  messages: Message[]
+  system?: SystemPrompt
+  options?: ChatOptions
+}
+
+export class Thread {
+  /** Append-only conversation history. Read-only — mutate via `send()` (or pass through `toJSON`). */
+  readonly messages: Message[] = []
+  readonly system?: SystemPrompt
+  readonly options?: ChatOptions
+  private readonly brain: BrainManager
+
+  constructor(brain: BrainManager, opts: ThreadOptions = {}) {
+    this.brain = brain
+    if (opts.system !== undefined) this.system = opts.system
+    if (opts.options !== undefined) this.options = opts.options
+  }
+
+  /**
+   * Append a user turn, call the model, append the assistant reply,
+   * and return the reply text. Per-call options override the
+   * thread's defaults; `system` always comes from the thread.
+   */
+  async send(text: string, options: ChatOptions = {}): Promise<string> {
+    this.messages.push({ role: 'user', content: text })
+    const merged: ChatOptions = {
+      ...(this.options ?? {}),
+      ...options,
+      // System is owned by the thread; per-call `system` is ignored
+      // intentionally so a caller can't drift the conversation
+      // mid-thread by changing the system prompt every turn.
+      ...(this.system !== undefined ? { system: this.system } : {}),
+    }
+    const result = await this.brain.chat(this.messages, merged)
+    this.messages.push({ role: 'assistant', content: result.text })
+    return result.text
+  }
+
+  /** Number of turns. Each `send()` adds 2 (user + assistant). */
+  get length(): number {
+    return this.messages.length
+  }
+
+  /** Serialize to a plain object — pass to `Thread.fromJSON` to restore. */
+  toJSON(): ThreadState {
+    const state: ThreadState = { messages: [...this.messages] }
+    if (this.system !== undefined) state.system = this.system
+    if (this.options !== undefined) state.options = this.options
+    return state
+  }
+
+  /**
+   * Restore a thread from a serialized snapshot. The `BrainManager`
+   * is passed in fresh — only the conversation state lives on disk;
+   * the manager is rebuilt at app boot.
+   */
+  static fromJSON(brain: BrainManager, state: ThreadState): Thread {
+    const options: ThreadOptions = {}
+    if (state.system !== undefined) options.system = state.system
+    if (state.options !== undefined) options.options = state.options
+    const thread = new Thread(brain, options)
+    for (const m of state.messages) thread.messages.push(m)
+    return thread
+  }
+}