@strav/brain 0.1.0

package/src/memory/token_counter.ts

@@ -0,0 +1,101 @@
+import type { Message, ContentBlock } from '../types.ts'
+
+/** Known context window sizes by model identifier. */
+const MODEL_CONTEXT_WINDOWS: Record<string, number> = {
+  // Anthropic
+  'claude-opus-4-20250514': 200_000,
+  'claude-sonnet-4-20250514': 200_000,
+  'claude-sonnet-4-5-20250514': 200_000,
+  'claude-haiku-3-5-20241022': 200_000,
+
+  // OpenAI
+  'gpt-4o': 128_000,
+  'gpt-4o-mini': 128_000,
+  'gpt-4-turbo': 128_000,
+  'gpt-4.1': 1_000_000,
+  'gpt-4.1-mini': 1_000_000,
+  'gpt-4.1-nano': 1_000_000,
+  o3: 200_000,
+  'o3-mini': 200_000,
+  'o4-mini': 200_000,
+
+  // DeepSeek
+  'deepseek-chat': 64_000,
+  'deepseek-reasoner': 64_000,
+}
+
+const DEFAULT_CONTEXT_WINDOW = 128_000
+
+/** Overhead tokens per message (role, formatting, separators). */
+const MESSAGE_OVERHEAD = 4
+
+/** Average characters per token for estimation. */
+const CHARS_PER_TOKEN = 4
+
+/**
+ * Approximate token counting without external dependencies.
+ *
+ * Uses character-based estimation (~4 chars per token) which is
+ * conservative enough for budget management. Exact counts are not
+ * needed — we just need to know when we're approaching the limit.
+ */
+export class TokenCounter {
+  /** Estimate token count for a string. */
+  static estimate(text: string): number {
+    if (!text) return 0
+    return Math.ceil(text.length / CHARS_PER_TOKEN)
+  }
+
+  /** Estimate token count for a Message array. */
+  static estimateMessages(messages: Message[]): number {
+    let total = 0
+
+    for (const msg of messages) {
+      total += MESSAGE_OVERHEAD
+      total += TokenCounter.estimateContent(msg.content)
+
+      if (msg.toolCalls) {
+        for (const call of msg.toolCalls) {
+          total += TokenCounter.estimate(call.name)
+          total += TokenCounter.estimate(JSON.stringify(call.arguments))
+          total += MESSAGE_OVERHEAD
+        }
+      }
+    }
+
+    return total
+  }
+
+  /** Get the context window size for a model, or the default fallback. */
+  static contextWindow(model: string): number {
+    // Exact match
+    if (MODEL_CONTEXT_WINDOWS[model] !== undefined) {
+      return MODEL_CONTEXT_WINDOWS[model]!
+    }
+
+    // Prefix match (e.g. 'claude-sonnet-4-20250514' matches 'claude-sonnet-4')
+    for (const [key, size] of Object.entries(MODEL_CONTEXT_WINDOWS)) {
+      if (model.startsWith(key) || key.startsWith(model)) {
+        return size
+      }
+    }
+
+    return DEFAULT_CONTEXT_WINDOW
+  }
+
+  /** Estimate tokens for message content (string or ContentBlock[]). */
+  private static estimateContent(content: string | ContentBlock[]): number {
+    if (typeof content === 'string') {
+      return TokenCounter.estimate(content)
+    }
+
+    let total = 0
+    for (const block of content) {
+      if (block.text) total += TokenCounter.estimate(block.text)
+      if (block.content) total += TokenCounter.estimate(block.content)
+      if (block.input) total += TokenCounter.estimate(JSON.stringify(block.input))
+      if (block.name) total += TokenCounter.estimate(block.name)
+    }
+    return total
+  }
+}

package/src/memory/types.ts

@@ -0,0 +1,68 @@
+import type { Message } from '../types.ts'
+
+// ── Configuration ───────────────────────────────────────────────────────────
+
+export interface MemoryConfig {
+  /** Max tokens for the entire context window (default: auto-detect from model). */
+  maxContextTokens?: number
+  /** Strategy: 'sliding_window' | 'summarize' (default: 'summarize'). */
+  strategy?: string
+  /** Reserve this fraction of context for the response (default: 0.25). */
+  responseReserve?: number
+  /** Min messages to keep in working memory before compacting (default: 4). */
+  minWorkingMessages?: number
+  /** Number of oldest messages to compact per cycle (default: 10). */
+  compactionBatchSize?: number
+  /** Enable semantic fact extraction during compaction (default: true). */
+  extractFacts?: boolean
+}
+
+// ── Compaction Strategy ─────────────────────────────────────────────────────
+
+export interface CompactionResult {
+  /** Summary text replacing the compacted messages. */
+  summary: string
+  /** Facts extracted during compaction (if enabled). */
+  facts?: Fact[]
+  /** Token count of the summary. */
+  summaryTokens: number
+}
+
+export interface CompactionStrategy {
+  readonly name: string
+  compact(
+    messages: Message[],
+    options: { provider: string; model: string; existingSummary?: string; extractFacts?: boolean }
+  ): Promise<CompactionResult>
+}
+
+// ── Thread Store ────────────────────────────────────────────────────────────
+
+export interface SerializedMemoryThread {
+  id: string
+  messages: Message[]
+  system?: string
+  summary?: string
+  facts?: Fact[]
+  metadata?: Record<string, unknown>
+  createdAt: string
+  updatedAt: string
+}
+
+export interface ThreadStore {
+  save(thread: SerializedMemoryThread): Promise<void>
+  load(id: string): Promise<SerializedMemoryThread | null>
+  delete(id: string): Promise<void>
+  list(options?: { limit?: number; offset?: number }): Promise<SerializedMemoryThread[]>
+}
+
+// ── Semantic Memory ─────────────────────────────────────────────────────────
+
+export interface Fact {
+  key: string
+  value: string
+  source: 'extracted' | 'explicit'
+  confidence: number
+  createdAt: string
+  updatedAt: string
+}

package/src/providers/anthropic_provider.ts

@@ -0,0 +1,276 @@
+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'
+
+/**
+ * Anthropic Messages API provider.
+ *
+ * Translates the framework's normalized CompletionRequest/Response
+ * to/from the Anthropic wire format. Uses raw `fetch()`.
+ */
+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)
+
+    const response = await retryableFetch(
+      'Anthropic',
+      `${this.baseUrl}/v1/messages`,
+      { method: 'POST', headers: this.buildHeaders(), body: JSON.stringify(body) },
+      this.retryOptions
+    )
+
+    const data: any = await response.json()
+    return this.parseResponse(data)
+  }
+
+  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
+
+      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' }
+      }
+    }
+  }
+
+  // ── Private helpers ──────────────────────────────────────────────────────
+
+  private buildHeaders(): Record<string, string> {
+    return {
+      'content-type': 'application/json',
+      'x-api-key': this.apiKey,
+      'anthropic-version': '2023-06-01',
+    }
+  }
+
+  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),
+    }
+
+    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
+
+    // Tools
+    if (request.tools?.length) {
+      body.tools = request.tools.map(t => ({
+        name: t.name,
+        description: t.description,
+        input_schema: t.parameters,
+      }))
+    }
+
+    // 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 }
+      }
+    }
+
+    // Structured output
+    if (request.schema) {
+      body.output_format = { type: 'json_schema', schema: request.schema }
+    }
+
+    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 })
+        }
+
+        // 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,
+            })
+          }
+        }
+
+        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,
+        })
+      }
+    }
+
+    return result
+  }
+
+  private parseResponse(data: any): CompletionResponse {
+    let content = ''
+    const toolCalls: ToolCall[] = []
+
+    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 ?? {},
+          })
+        }
+      }
+    }
+
+    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),
+    }
+
+    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
+    }
+
+    return {
+      id: data.id ?? '',
+      content,
+      toolCalls,
+      stopReason,
+      usage,
+      raw: data,
+    }
+  }
+}