@strav/brain 0.4.31 → 1.0.0-alpha.9

package/src/brain_manager.ts

@@ -1,158 +1,205 @@
-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))
-    }
-  }
+import type { Agent } from './agent.ts'
+import type { AgentResult } from './agent_result.ts'
+import { AgentRunner } from './agent_runner.ts'
+import { BrainError } from './brain_error.ts'
+import type { ModelTier } from './types.ts'
+import type {
+  ChatOptions,
+  ChatResult,
+  Message,
+  StreamEvent,
+} from './types.ts'
+import type { Provider, RunWithToolsOptions } from './provider.ts'
+import type { Tool } from './tool.ts'
+import { DEFAULT_TIERS } from './brain_config.ts'
+
+/** Container-aware Agent constructor resolver — `BrainProvider` installs one wired to `app.resolve(...)`. */
+export type AgentResolver = <A extends Agent>(cls: new (...args: never[]) => A) => A
+
+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
+}
 
-  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.`
-        )
+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) } },
+      )
     }
+    this.defaultProvider = options.default
+    this.providers = new Map(Object.entries(options.providers))
+    this.tiers = { ...DEFAULT_TIERS, ...(options.tiers ?? {}) }
+    this.defaultCache = options.defaultCache ?? false
   }
 
-  static get config(): BrainConfig {
-    if (!BrainManager._config) {
-      throw new ConfigurationError(
-        'BrainManager not configured. Resolve it through the container first.'
-      )
+  /** 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 BrainManager._config
+    return provider
   }
 
-  /** 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
+  /**
+   * 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)
   }
 
-  /** 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)
+  /**
+   * 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.
+   */
+  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)
   }
 
-  /** Get the configured memory settings. */
-  static get memoryConfig(): MemoryConfig {
-    return BrainManager._memoryConfig
+  /**
+   * 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.
+   */
+  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)
   }
 
-  /** Get the registered thread store, if any. */
-  static get threadStore(): ThreadStore | null {
-    return BrainManager._threadStore
+  /**
+   * Run an agentic loop: send `messages` + `tools` to the model;
+   * execute any tool the model calls; loop until the model returns
+   * a terminal `stop_reason` (`'end_turn'`) or `maxIterations` is hit.
+   *
+   * Throws `BrainError` when the configured provider doesn't
+   * implement `runWithTools` (V1: OpenAI / Gemini / DeepSeek providers
+   * don't yet — only `AnthropicProvider`).
+   */
+  async runTools(
+    input: string | readonly Message[],
+    tools: readonly Tool[],
+    options: RunWithToolsOptions = {},
+  ): Promise<AgentResult> {
+    const provider = this.provider(options.provider)
+    if (!provider.runWithTools) {
+      throw new BrainError(
+        `BrainManager.runTools: provider "${provider.name}" does not implement runWithTools. Use a provider that supports tool use (V1: Anthropic).`,
+        { context: { provider: provider.name } },
+      )
+    }
+    const messages = normalizeInput(input)
+    const resolved = this.applyDefaults(options) as RunWithToolsOptions
+    return provider.runWithTools(messages, tools, resolved)
   }
 
-  /** Register a thread store for persistence (e.g., DatabaseThreadStore). */
-  static useThreadStore(store: ThreadStore): void {
-    BrainManager._threadStore = store
+  /**
+   * Resolve an `Agent` subclass from the container and return an
+   * `AgentRunner` ready to receive `input(...)` and `run()`. Apps
+   * `@inject()`-decorate their Agent subclass so constructor
+   * injection of dependencies (Repositories, services, etc.) flows
+   * through normally.
+   */
+  agent<A extends Agent>(AgentClass: new (...args: never[]) => A, instance?: A): AgentRunner {
+    const agent = instance ?? this.resolveAgent(AgentClass)
+    return new AgentRunner(this, agent)
   }
 
-  /** Register a hook that runs before every completion. */
-  static before(hook: BeforeHook): void {
-    BrainManager._beforeHooks.push(hook)
-  }
+  // ─── Internal ────────────────────────────────────────────────────────────
 
-  /** Register a hook that runs after every completion. */
-  static after(hook: AfterHook): void {
-    BrainManager._afterHooks.push(hook)
+  private resolveAgent<A extends Agent>(AgentClass: new (...args: never[]) => A): A {
+    if (this.agentResolver) return this.agentResolver(AgentClass)
+    // Fallback: assume the Agent class is constructible without args.
+    // Apps that need DI on the agent register a resolver via
+    // `setAgentResolver` (BrainProvider wires this to the container).
+    return new (AgentClass as unknown as new () => A)()
   }
 
   /**
-   * Run a completion through the named provider, with before/after hooks.
-   * Used internally by AgentRunner and the `brain` helper.
+   * Internal — `BrainProvider` calls this at boot to plug in the
+   * container's resolution function so `brain.agent(MyAgent)` runs
+   * `app.resolve(MyAgent)` under the hood. Apps that build a
+   * `BrainManager` by hand for tests can leave this unset and pass
+   * a pre-constructed agent to `brain.agent(_, instance)`.
    */
-  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
+  setAgentResolver(resolver: AgentResolver): void {
+    this.agentResolver = resolver
   }
 
-  /**
-   * 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.
-   */
-  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().`
-      )
+  private agentResolver: AgentResolver | undefined
+
+  private applyDefaults(options: ChatOptions): ChatOptions {
+    const resolved: ChatOptions = { ...options }
+    if (resolved.model === undefined && resolved.tier !== undefined) {
+      resolved.model = this.tiers[resolved.tier]
+    }
+    if (resolved.cache === undefined && this.defaultCache) {
+      resolved.cache = true
     }
-    return provider.transcribe(request)
+    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,100 @@
-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
+      const manager = new BrainManager(options)
+      // Plug in the container so `brain.agent(MyAgent)` resolves
+      // its constructor deps through `@inject()` like every other
+      // injected class. The variance widening at the boundary
+      // (`never[]` ↔ `any[]`) is purely a TS typing artifact — the
+      // container call is identical to a direct `c.resolve(MyAgent)`.
+      manager.setAgentResolver(<A>(cls: new (...args: never[]) => A) =>
+        c.resolve(cls as unknown as new (...args: unknown[]) => A),
+      )
+      return manager
+    })
   }
 
   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/define_tool.ts

@@ -0,0 +1,42 @@
+/**
+ * `defineTool({ name, description, inputSchema, execute })` — typed
+ * factory mirroring `defineWorkflow` / `defineMachine` / `defineDurable`.
+ *
+ * ```ts
+ * const getWeather = defineTool({
+ *   name: 'get_weather',
+ *   description: 'Get current weather for a location.',
+ *   inputSchema: {
+ *     type: 'object',
+ *     properties: { city: { type: 'string' } },
+ *     required: ['city'],
+ *   },
+ *   execute: async ({ city }: { city: string }, ctx) => {
+ *     return weatherService.lookup(city, ctx.context.userId as string)
+ *   },
+ * })
+ * ```
+ *
+ * The generic parameters are usually inferred from `execute`'s first
+ * arg + return type; apps that want explicit typing pass them.
+ */
+
+import type { Tool, ToolContext } from './tool.ts'
+
+export interface DefineToolSpec<TInput, TOutput> {
+  name: string
+  description: string
+  inputSchema: Record<string, unknown>
+  execute(input: TInput, ctx: ToolContext): Promise<TOutput>
+}
+
+export function defineTool<TInput = unknown, TOutput = unknown>(
+  spec: DefineToolSpec<TInput, TOutput>,
+): Tool<TInput, TOutput> {
+  return {
+    name: spec.name,
+    description: spec.description,
+    inputSchema: spec.inputSchema,
+    execute: spec.execute,
+  }
+}

package/src/index.ts

@@ -1,48 +1,46 @@
-export { default, default as BrainManager } from './brain_manager.ts'
+// Public API of @strav/brain.
+//
+// V1: Provider interface + AnthropicProvider, BrainManager, Thread,
+// BrainProvider service-wiring, prompt caching.
+// V2 (this slice): tools + agents — defineTool, Agent base + AgentRunner,
+// BrainManager.runTools / .agent(Class), Provider.runWithTools.
+// Still deferred: MCP, embeddings, streaming agent loops, server-side
+// tools, structured outputs, other providers.
 
-// 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 { AgentResult } from './agent_result.ts'
+export { AgentRunner } from './agent_runner.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 {
+  type AgentResolver,
+  BrainManager,
+  type BrainManagerOptions,
+} from './brain_manager.ts'
+export { BrainProvider } from './brain_provider.ts'
+export { defineTool, type DefineToolSpec } from './define_tool.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, RunWithToolsOptions } from './provider.ts'
+export { Thread, type ThreadOptions, type ThreadState } from './thread.ts'
+export type { Tool, ToolContext } from './tool.ts'
+export { ToolExecutionError } from './tool_execution_error.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,
+  ToolResultBlock,
+  ToolUseBlock,
 } 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,74 @@
+/**
+ * `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 { AgentResult } from './agent_result.ts'
+import type { Tool } from './tool.ts'
+import type {
+  ChatOptions,
+  ChatResult,
+  Message,
+  StreamEvent,
+} from './types.ts'
+
+export interface RunWithToolsOptions extends ChatOptions {
+  /** Safety ceiling on tool-use round-trips. Default `10`. */
+  maxIterations?: number
+  /** Free-form context bag passed to every tool's `execute(input, ctx)`. */
+  context?: Record<string, unknown>
+}
+
+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>
+
+  /**
+   * Agentic loop. Sends the `messages` + `tools` to the model;
+   * detects tool-use blocks in the response; runs the matching
+   * tool's `execute`; appends the result and re-asks. Loops until
+   * the model returns `stop_reason: 'end_turn'` (or its
+   * provider-specific equivalent) or `maxIterations` is hit.
+   *
+   * Optional on the interface so providers that don't (yet) support
+   * tool use can omit it; `BrainManager.runTools` throws a
+   * `BrainError` when the configured provider lacks the method.
+   */
+  runWithTools?(
+    messages: readonly Message[],
+    tools: readonly Tool[],
+    options?: RunWithToolsOptions,
+  ): Promise<AgentResult>
+}