@strav/brain 0.4.31 → 1.0.0-alpha.8

package/package.json

@@ -1,32 +1,29 @@
 {
   "name": "@strav/brain",
-  "version": "0.4.31",
+  "version": "1.0.0-alpha.8",
+  "description": "Strav AI module — unified Provider interface, BrainManager, threads, prompt caching. Anthropic provider in V1; OpenAI / Gemini / DeepSeek follow.",
   "type": "module",
-  "description": "AI module for the Strav framework",
-  "license": "MIT",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
   "exports": {
-    ".": "./src/index.ts",
-    "./*": "./src/*.ts"
+    ".": "./src/index.ts"
   },
   "files": [
-    "src/",
-    "package.json",
-    "tsconfig.json",
-    "CHANGELOG.md"
+    "src",
+    "README.md"
   ],
-  "peerDependencies": {
-    "@strav/kernel": "0.4.31"
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "publishConfig": {
+    "access": "public"
   },
   "dependencies": {
-    "@strav/mcp": "0.4.31",
-    "@strav/workflow": "0.4.31",
-    "zod": "^3.25 || ^4.0"
+    "@strav/kernel": "1.0.0-alpha.8",
+    "@anthropic-ai/sdk": "^0.100.0"
   },
-  "devDependencies": {
-    "@strav/http": "0.4.31"
+  "peerDependencies": {
+    "@types/bun": ">=1.3.14"
   },
-  "scripts": {
-    "test": "bun test tests/",
-    "typecheck": "tsc --noEmit"
-  }
+  "devDependencies": null
 }

package/src/brain_config.ts

@@ -0,0 +1,72 @@
+/**
+ * Brain configuration shape — what `config.brain` looks like.
+ *
+ * Mirrors the manager-pattern config used by other Strav packages
+ * (auth.guards, mail.transports, database.connections): a `default`
+ * provider key + a `providers` map keyed by name. Each provider entry
+ * carries its driver and driver-specific options.
+ *
+ * `tiers` map model-tier sugar (`fast` / `balanced` / `powerful`) to
+ * concrete model IDs. The `'fast' → claude-haiku-4-5` etc. defaults
+ * apply when this section is omitted; apps can rewire to point at,
+ * e.g., self-hosted Llama for the `fast` tier.
+ *
+ * `cache.auto` is the default for `ChatOptions.cache` when the call
+ * site doesn't pass one. Prompt caching is opt-in by default — apps
+ * that want every long request to cache flip this to `true`.
+ */
+
+import type { ModelTier } from './types.ts'
+
+/** Anthropic-specific driver config. */
+export interface AnthropicProviderConfig {
+  driver: 'anthropic'
+  /** API key. Required. Most apps source from `env('ANTHROPIC_API_KEY')`. */
+  apiKey: string
+  /** Optional override of the SDK's base URL — useful for proxies or test doubles. */
+  baseUrl?: string
+  /** Default model when neither `options.model` nor `options.tier` is passed. */
+  defaultModel?: string
+  /** Default `max_tokens` for `chat()` calls that don't specify one. */
+  defaultMaxTokens?: number
+  /** Optional beta headers added to every request from this provider. */
+  betas?: readonly string[]
+}
+
+export type ProviderConfig = AnthropicProviderConfig // | OpenAIProviderConfig | … (later slices)
+
+/** Cache-shape defaults applied when `ChatOptions.cache` is omitted. */
+export interface BrainCacheConfig {
+  /** Set `cache_control` on the last cacheable block on every request. Default `false`. */
+  auto?: boolean
+}
+
+export interface BrainConfigShape {
+  /** Name of the default provider; must exist in `providers`. */
+  default: string
+  /** Provider registry. Each entry is one configured backend. */
+  providers: Record<string, ProviderConfig>
+  /**
+   * Model-tier sugar. When omitted, the framework defaults apply:
+   *   - fast: 'claude-haiku-4-5'
+   *   - balanced: 'claude-sonnet-4-6'
+   *   - powerful: 'claude-opus-4-7'
+   */
+  tiers?: Partial<Record<ModelTier, string>>
+  /** Prompt-cache defaults. */
+  cache?: BrainCacheConfig
+}
+
+/**
+ * Framework-level tier defaults. Apps that don't override
+ * `config.brain.tiers` get these. Lives here so `BrainManager` and
+ * the docs both pull from one source.
+ */
+export const DEFAULT_TIERS: Record<ModelTier, string> = {
+  fast: 'claude-haiku-4-5',
+  balanced: 'claude-sonnet-4-6',
+  powerful: 'claude-opus-4-7',
+}
+
+/** The model the framework reaches for when nothing else is specified. */
+export const DEFAULT_MODEL = DEFAULT_TIERS.powerful

package/src/brain_error.ts

@@ -0,0 +1,29 @@
+/**
+ * `BrainError` — typed wrapper for failures originating in the brain
+ * stack. Provider-native errors (e.g. `Anthropic.RateLimitError`) are
+ * preserved on `.cause` so apps can `instanceof`-check them when they
+ * need provider-specific recovery; the wrapping just gives the
+ * framework a consistent `StravError` to render through the standard
+ * exception handler.
+ *
+ * Subclassing surface deferred — V1 has one error type. When a real
+ * use case appears for distinguishing "model refused" vs "rate
+ * limited" at the framework level (rather than `instanceof
+ * Anthropic.RateLimitError` at the call site), a typed hierarchy
+ * lands.
+ */
+
+import { StravError } from '@strav/kernel'
+
+export class BrainError extends StravError {
+  constructor(
+    message: string,
+    options: { context?: Record<string, unknown>; cause?: unknown } = {},
+  ) {
+    super(
+      message,
+      { code: 'brain.error', status: 500 },
+      { ...options },
+    )
+  }
+}

package/src/brain_manager.ts

@@ -1,158 +1,139 @@
-import { inject, ConfigurationError, Configuration } from '@strav/kernel'
-import { AnthropicProvider } from './providers/anthropic_provider.ts'
-import { OpenAIProvider } from './providers/openai_provider.ts'
-import type {
-  AIProvider,
-  BrainConfig,
-  ProviderConfig,
-  CompletionRequest,
-  CompletionResponse,
-  BeforeHook,
-  AfterHook,
-  TranscribeRequest,
-  TranscriptionResponse,
-} from './types.ts'
-import type { MemoryConfig, ThreadStore } from './memory/types.ts'
-
 /**
- * Central AI configuration hub.
+ * `BrainManager` — the per-app facade apps inject and call.
  *
- * Resolved once via the DI container — reads the AI config
- * and initializes the appropriate provider drivers.
+ * Holds the configured `Provider` registry + the default-provider key
+ * + the tier-to-model map. Apps call `chat / stream / countTokens`
+ * with framework-native types; the manager resolves which provider
+ * runs the call (default unless `options.provider` overrides),
+ * applies tier sugar (`options.tier` → concrete `model`), and
+ * delegates.
  *
- * @example
- * app.singleton(BrainManager)
- * app.resolve(BrainManager)
+ * Constructed by `BrainProvider` at boot from `config.brain`. Apps
+ * also build one inline for tests:
  *
- * // Plug in a custom provider
- * BrainManager.useProvider(new OllamaProvider())
+ * ```ts
+ * const brain = new BrainManager({
+ *   default: 'anthropic',
+ *   providers: { anthropic: stubProvider },
+ * })
+ * ```
  */
-@inject
-export default class BrainManager {
-  private static _config: BrainConfig
-  private static _providers = new Map<string, AIProvider>()
-  private static _beforeHooks: BeforeHook[] = []
-  private static _afterHooks: AfterHook[] = []
-  private static _threadStore: ThreadStore | null = null
-  private static _memoryConfig: MemoryConfig = {}
-
-  constructor(config: Configuration) {
-    BrainManager._config = {
-      default: config.get('ai.default', 'anthropic') as string,
-      providers: config.get('ai.providers', {}) as Record<string, ProviderConfig>,
-      maxTokens: config.get('ai.maxTokens', 4096) as number,
-      temperature: config.get('ai.temperature', 0.7) as number,
-      maxIterations: config.get('ai.maxIterations', 10) as number,
-    }
-
-    BrainManager._memoryConfig = config.get('ai.memory', {}) as MemoryConfig
-
-    for (const [name, providerConfig] of Object.entries(BrainManager._config.providers)) {
-      BrainManager._providers.set(name, BrainManager.createProvider(name, providerConfig))
-    }
-  }
 
-  private static createProvider(name: string, config: ProviderConfig): AIProvider {
-    const driver = config.driver ?? name
-    switch (driver) {
-      case 'anthropic':
-        return new AnthropicProvider(config)
-      case 'openai':
-        return new OpenAIProvider(config, name)
-      default:
-        throw new ConfigurationError(
-          `Unknown AI provider driver: ${driver}. Use BrainManager.useProvider() for custom providers.`
-        )
-    }
-  }
+import { BrainError } from './brain_error.ts'
+import type { ModelTier } from './types.ts'
+import type {
+  ChatOptions,
+  ChatResult,
+  Message,
+  StreamEvent,
+} from './types.ts'
+import type { Provider } from './provider.ts'
+import { DEFAULT_TIERS } from './brain_config.ts'
+
+export interface BrainManagerOptions {
+  /** Name of the default provider — must exist in `providers`. */
+  default: string
+  /** Provider registry keyed by name. */
+  providers: Record<string, Provider>
+  /** Tier-to-model overrides; merged on top of the framework defaults. */
+  tiers?: Partial<Record<ModelTier, string>>
+  /** Default for `ChatOptions.cache` when the call site doesn't pass one. */
+  defaultCache?: boolean
+}
 
-  static get config(): BrainConfig {
-    if (!BrainManager._config) {
-      throw new ConfigurationError(
-        'BrainManager not configured. Resolve it through the container first.'
+export class BrainManager {
+  readonly defaultProvider: string
+  private readonly providers: Map<string, Provider>
+  private readonly tiers: Record<ModelTier, string>
+  private readonly defaultCache: boolean
+
+  constructor(options: BrainManagerOptions) {
+    if (!options.providers[options.default]) {
+      throw new BrainError(
+        `BrainManager: default provider "${options.default}" is not registered.`,
+        { context: { default: options.default, available: Object.keys(options.providers) } },
       )
     }
-    return BrainManager._config
-  }
-
-  /** Get a provider by name, or the default provider. */
-  static provider(name?: string): AIProvider {
-    const key = name ?? BrainManager._config.default
-    const p = BrainManager._providers.get(key)
-    if (!p) throw new ConfigurationError(`AI provider "${key}" not configured.`)
-    return p
+    this.defaultProvider = options.default
+    this.providers = new Map(Object.entries(options.providers))
+    this.tiers = { ...DEFAULT_TIERS, ...(options.tiers ?? {}) }
+    this.defaultCache = options.defaultCache ?? false
   }
 
-  /** Swap or add a provider at runtime (e.g., for testing or a custom provider). */
-  static useProvider(provider: AIProvider): void {
-    BrainManager._providers.set(provider.name, provider)
-  }
-
-  /** Get the configured memory settings. */
-  static get memoryConfig(): MemoryConfig {
-    return BrainManager._memoryConfig
-  }
-
-  /** Get the registered thread store, if any. */
-  static get threadStore(): ThreadStore | null {
-    return BrainManager._threadStore
-  }
-
-  /** Register a thread store for persistence (e.g., DatabaseThreadStore). */
-  static useThreadStore(store: ThreadStore): void {
-    BrainManager._threadStore = store
-  }
-
-  /** Register a hook that runs before every completion. */
-  static before(hook: BeforeHook): void {
-    BrainManager._beforeHooks.push(hook)
+  /** Resolve a provider by name. Default when no name passed. Throws when unknown. */
+  provider(name?: string): Provider {
+    const key = name ?? this.defaultProvider
+    const provider = this.providers.get(key)
+    if (!provider) {
+      throw new BrainError(`BrainManager: no provider registered under "${key}".`, {
+        context: { requested: key, available: [...this.providers.keys()] },
+      })
+    }
+    return provider
   }
 
-  /** Register a hook that runs after every completion. */
-  static after(hook: AfterHook): void {
-    BrainManager._afterHooks.push(hook)
+  /**
+   * One-shot chat: send the messages, await the full reply.
+   *
+   * Accepts either a bare prompt string (treated as a single
+   * user-role message) or a typed `Message[]` for multi-turn /
+   * pre-built conversations.
+   */
+  async chat(input: string | readonly Message[], options: ChatOptions = {}): Promise<ChatResult> {
+    const messages = normalizeInput(input)
+    const resolved = this.applyDefaults(options)
+    return this.provider(options.provider).chat(messages, resolved)
   }
 
   /**
-   * Run a completion through the named provider, with before/after hooks.
-   * Used internally by AgentRunner and the `brain` helper.
+   * Stream the reply. Yields a `text` event per delta and a single
+   * terminal `stop` event with usage + stop-reason. Apps that want
+   * just the final message use `chat()` instead — this surface is
+   * for UI streaming.
    */
-  static async complete(
-    providerName: string | undefined,
-    request: CompletionRequest
-  ): Promise<CompletionResponse> {
-    for (const hook of BrainManager._beforeHooks) await hook(request)
-    const response = await BrainManager.provider(providerName).complete(request)
-    for (const hook of BrainManager._afterHooks) await hook(request, response)
-    return response
+  stream(
+    input: string | readonly Message[],
+    options: ChatOptions = {},
+  ): AsyncIterable<StreamEvent> {
+    const messages = normalizeInput(input)
+    const resolved = this.applyDefaults(options)
+    return this.provider(options.provider).stream(messages, resolved)
   }
 
   /**
-   * Transcribe audio through the named provider. Throws a clear
-   * ConfigurationError if the provider doesn't implement `transcribe()`
-   * (Anthropic, at time of writing). Hooks are not invoked — they're
-   * shaped for chat completions and don't carry an audio analogue.
+   * Count input tokens for the given messages + options. Returns
+   * `null` when the configured provider doesn't expose a token count
+   * helper (no `countTokens` method) — apps can fall back to a local
+   * estimator at the call site.
    */
-  static async transcribe(
-    providerName: string | undefined,
-    request: TranscribeRequest
-  ): Promise<TranscriptionResponse> {
-    const provider = BrainManager.provider(providerName)
-    if (!provider.transcribe) {
-      throw new ConfigurationError(
-        `AI provider "${provider.name}" does not support transcribe(). ` +
-          `Use the OpenAI or Google providers, or register a custom one via BrainManager.useProvider().`
-      )
+  async countTokens(
+    input: string | readonly Message[],
+    options: ChatOptions = {},
+  ): Promise<number | null> {
+    const provider = this.provider(options.provider)
+    if (!provider.countTokens) return null
+    const messages = normalizeInput(input)
+    const resolved = this.applyDefaults(options)
+    return provider.countTokens(messages, resolved)
+  }
+
+  // ─── Internal ────────────────────────────────────────────────────────────
+
+  private applyDefaults(options: ChatOptions): ChatOptions {
+    const resolved: ChatOptions = { ...options }
+    if (resolved.model === undefined && resolved.tier !== undefined) {
+      resolved.model = this.tiers[resolved.tier]
     }
-    return provider.transcribe(request)
+    if (resolved.cache === undefined && this.defaultCache) {
+      resolved.cache = true
+    }
+    return resolved
   }
+}
 
-  /** Clear all providers, hooks, and stores (for testing). */
-  static reset(): void {
-    BrainManager._providers.clear()
-    BrainManager._beforeHooks = []
-    BrainManager._afterHooks = []
-    BrainManager._threadStore = null
-    BrainManager._memoryConfig = {}
+function normalizeInput(input: string | readonly Message[]): readonly Message[] {
+  if (typeof input === 'string') {
+    return [{ role: 'user', content: input }]
   }
+  return input
 }

package/src/brain_provider.ts

@@ -1,16 +1,91 @@
-import { ServiceProvider } from '@strav/kernel'
-import type { Application } from '@strav/kernel'
-import BrainManager from './brain_manager.ts'
+/**
+ * `BrainProvider` — `ServiceProvider` that wires `BrainManager` into
+ * the container from `config.brain`.
+ *
+ * Reads the brain config at register time, instantiates every
+ * configured provider (today: just Anthropic), and binds a
+ * `BrainManager` singleton. Apps inject it the standard way:
+ *
+ * ```ts
+ * @inject()
+ * class GreetingService {
+ *   constructor(private readonly brain: BrainManager) {}
+ *
+ *   async greet(name: string): Promise<string> {
+ *     const { text } = await this.brain.chat(`Greet ${name} warmly.`)
+ *     return text
+ *   }
+ * }
+ * ```
+ *
+ * Eager construction is on purpose — a missing API key or unknown
+ * driver should fail at boot, not at the first call. The `boot()`
+ * step resolves the manager so `ConfigError`s surface before any
+ * request hits.
+ */
 
-export default class BrainProvider extends ServiceProvider {
-  readonly name = 'brain'
+import { type Application, ConfigError, ConfigRepository, ServiceProvider } from '@strav/kernel'
+import { BrainManager } from './brain_manager.ts'
+import type { BrainConfigShape, ProviderConfig } from './brain_config.ts'
+import { AnthropicProvider } from './providers/anthropic_provider.ts'
+import type { Provider } from './provider.ts'
+
+export class BrainProvider extends ServiceProvider {
+  override readonly name = 'brain'
   override readonly dependencies = ['config']
 
   override register(app: Application): void {
-    app.singleton(BrainManager)
+    app.singleton(BrainManager, (c) => {
+      const config = c.resolve(ConfigRepository).get('brain') as BrainConfigShape | undefined
+      if (!config) {
+        throw new ConfigError(
+          'BrainProvider: `config.brain` is missing. Add a `config/brain.ts` with at least `default` + `providers`.',
+        )
+      }
+      if (!config.providers || Object.keys(config.providers).length === 0) {
+        throw new ConfigError(
+          'BrainProvider: `config.brain.providers` must have at least one entry.',
+        )
+      }
+      if (!config.providers[config.default]) {
+        throw new ConfigError(
+          `BrainProvider: default provider "${config.default}" is not declared in config.brain.providers.`,
+        )
+      }
+
+      const providers: Record<string, Provider> = {}
+      for (const [name, entry] of Object.entries(config.providers)) {
+        providers[name] = buildProvider(name, entry)
+      }
+
+      const options: ConstructorParameters<typeof BrainManager>[0] = {
+        default: config.default,
+        providers,
+      }
+      if (config.tiers !== undefined) options.tiers = config.tiers
+      if (config.cache?.auto !== undefined) options.defaultCache = config.cache.auto
+      return new BrainManager(options)
+    })
   }
 
   override boot(app: Application): void {
+    // Force-resolve so config errors surface at boot, not on first call.
     app.resolve(BrainManager)
   }
 }
+
+function buildProvider(name: string, config: ProviderConfig): Provider {
+  switch (config.driver) {
+    case 'anthropic':
+      if (!config.apiKey) {
+        throw new ConfigError(
+          `BrainProvider: anthropic provider "${name}" is missing apiKey. Source from env('ANTHROPIC_API_KEY').`,
+        )
+      }
+      return new AnthropicProvider(name, config)
+    default:
+      throw new ConfigError(
+        `BrainProvider: unknown driver for provider "${name}". Known drivers: anthropic.`,
+      )
+  }
+}

package/src/index.ts

@@ -1,48 +1,32 @@
-export { default, default as BrainManager } from './brain_manager.ts'
+// Public API of @strav/brain.
+//
+// Foundation slice: Provider interface + AnthropicProvider, BrainManager,
+// Thread, BrainProvider service-wiring, prompt caching. Tools / agents /
+// MCP / embeddings / other providers (OpenAI/Google/DeepSeek) land in
+// follow-up slices.
 
-// Provider
-export { default as BrainProvider } from './brain_provider.ts'
-export { brain, AgentRunner, Thread } from './helpers.ts'
-export { Agent } from './agent.ts'
-export { defineTool, defineToolbox } from './tool.ts'
-export { defineMcpToolbox } from './mcp_toolbox.ts'
-export type { McpToolboxOptions } from './mcp_toolbox.ts'
-export { Workflow } from './workflow.ts'
+export {
+  type AnthropicProviderConfig,
+  type BrainCacheConfig,
+  type BrainConfigShape,
+  DEFAULT_MODEL,
+  DEFAULT_TIERS,
+  type ProviderConfig,
+} from './brain_config.ts'
+export { BrainError } from './brain_error.ts'
+export { BrainManager, type BrainManagerOptions } from './brain_manager.ts'
+export { BrainProvider } from './brain_provider.ts'
 export { AnthropicProvider } from './providers/anthropic_provider.ts'
-export { GoogleProvider } from './providers/google_provider.ts'
-export { OpenAIProvider } from './providers/openai_provider.ts'
-export { OpenAIResponsesProvider } from './providers/openai_responses_provider.ts'
-export { parseSSE } from './utils/sse_parser.ts'
-export { zodToJsonSchema } from './utils/schema.ts'
+export type { Provider } from './provider.ts'
+export { Thread, type ThreadOptions, type ThreadState } from './thread.ts'
 export type {
-  AIProvider,
-  BrainConfig,
-  ProviderConfig,
-  CompletionRequest,
-  CompletionResponse,
-  Message,
+  ChatOptions,
+  ChatResult,
+  ChatUsage,
   ContentBlock,
-  ToolCall,
-  ToolDefinition,
-  StreamChunk,
-  Usage,
-  AgentResult,
-  ToolCallRecord,
-  AgentEvent,
-  WorkflowResult,
-  EmbeddingResponse,
-  JsonSchema,
-  SSEEvent,
-  BeforeHook,
-  AfterHook,
-  SerializedThread,
-  SerializedAgentState,
-  SuspendedRun,
-  ToolCallResult,
-  OutputSchema,
+  Message,
+  ModelTier,
+  StreamEvent,
+  SystemPrompt,
+  TextBlock,
 } from './types.ts'
-export type { ChatOptions, GenerateOptions, GenerateResult, EmbedOptions } from './helpers.ts'
-export type { WorkflowContext } from './workflow.ts'
-
-// Memory
-export * from './memory/index.ts'

package/src/provider.ts

@@ -0,0 +1,48 @@
+/**
+ * `Provider` — the contract every brain backend implements.
+ *
+ * Each concrete provider (Anthropic, OpenAI later, Gemini later,
+ * DeepSeek later) wraps the vendor's SDK and translates the framework
+ * shapes (`Message`, `ChatOptions`) into the vendor's native request,
+ * then translates the response back into `ChatResult` / `StreamEvent`.
+ *
+ * Providers are values, not classes — apps use them via the
+ * `BrainManager` facade. The interface is exported so apps that need
+ * to plug in a custom provider (e.g. a local Ollama) can do so without
+ * subclassing.
+ */
+
+import type {
+  ChatOptions,
+  ChatResult,
+  Message,
+  StreamEvent,
+} from './types.ts'
+
+export interface Provider {
+  /** Identifier — matches the `config.brain.providers` key. */
+  readonly name: string
+
+  /**
+   * Generate a single reply. Awaits the full response; for
+   * token-by-token rendering use `stream()`.
+   */
+  chat(messages: readonly Message[], options?: ChatOptions): Promise<ChatResult>
+
+  /**
+   * Stream the reply as it's generated. The async iterable yields
+   * `text` events for each delta and a final `stop` event with usage
+   * + stop-reason. Apps that want the full collected message at the
+   * end pass the same `messages` to `chat()` instead; this surface is
+   * for UI streaming, not for "make one call and get the message".
+   */
+  stream(messages: readonly Message[], options?: ChatOptions): AsyncIterable<StreamEvent>
+
+  /**
+   * Count input tokens for a given message set + options. Used by
+   * apps that need to budget context before sending. Optional — not
+   * every provider exposes a cheap token-count endpoint, so the
+   * implementation may approximate.
+   */
+  countTokens?(messages: readonly Message[], options?: ChatOptions): Promise<number>
+}