@strav/brain 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+## 0.6.0
+
+### Added
+
+- **Memory management** — three-tier conversation memory system for long-running threads
+  - `thread.memory()` enables opt-in context window management
+  - **Working memory** — recent messages within token budget
+  - **Episodic memory** — LLM-generated summaries of compacted older messages
+  - **Semantic memory** — structured facts extracted from conversation, injected into system prompt
+- `TokenCounter` — approximate token estimation per provider (~4 chars/token)
+- `ContextBudget` — budget allocation across system prompt, summaries, facts, and working messages
+- `MemoryManager` — orchestrates compaction and fact extraction
+- `SemanticMemory` — in-memory fact store with `<known_facts>` prompt injection
+- `SummarizeStrategy` — LLM-powered compaction with optional fact extraction
+- `SlidingWindowStrategy` — drop oldest messages without summarization
+- `InMemoryThreadStore` — default `ThreadStore` implementation for dev/testing
+- `ThreadStore` interface — pluggable persistence (implement for database-backed storage)
+- `BrainManager.useThreadStore()` — register a thread store for persistence
+- `BrainManager.memoryConfig` / `BrainManager.threadStore` — accessors for memory configuration
+- `thread.id()` — set thread identifier for persistence
+- `thread.persist()` — enable auto-save to ThreadStore after each `send()`
+- `thread.facts` / `thread.episodicSummary` — access memory state
+- `thread.serializeMemory()` / `thread.restoreMemory()` — extended serialization with memory state
+- `BrainConfig.memory` — optional `MemoryConfig` field for global memory settings
+
+## 0.1.1
+
+### Changed
+
+- Applied consistent code formatting across all source files

package/README.md

@@ -0,0 +1,82 @@
+# @stravigor/brain
+
+AI module for the [Strav](https://www.npmjs.com/package/@stravigor/core) framework. Provides a unified interface for AI providers with support for agents, threads, tool use, and multi-step workflows.
+
+## Install
+
+```bash
+bun add @stravigor/brain
+```
+
+Requires `@stravigor/core` as a peer dependency.
+
+## Providers
+
+- **Anthropic** (Claude)
+- **OpenAI** (GPT, also works with DeepSeek via custom `baseUrl`)
+
+## Usage
+
+```ts
+import { brain } from '@stravigor/brain'
+
+// One-shot chat
+const response = await brain.chat('Explain quantum computing')
+
+// Streaming
+for await (const chunk of brain.stream('Write a poem')) {
+  process.stdout.write(chunk.text)
+}
+
+// Structured output with Zod
+import { z } from 'zod'
+const result = await brain.generate('List 3 colors', {
+  schema: z.object({ colors: z.array(z.string()) }),
+})
+
+// Embeddings
+const vectors = await brain.embed('Hello world')
+```
+
+## Agents
+
+```ts
+import { Agent, defineTool } from '@stravigor/brain'
+
+class ResearchAgent extends Agent {
+  provider = 'anthropic'
+  model = 'claude-sonnet-4-20250514'
+  instructions = 'You are a research assistant.'
+  tools = [searchTool, summarizeTool]
+}
+
+const result = await brain.agent(ResearchAgent).input('Find info on Bun').run()
+```
+
+## Threads
+
+Multi-turn conversations with serialization support:
+
+```ts
+const thread = brain.thread({ provider: 'anthropic', model: 'claude-sonnet-4-20250514' })
+await thread.send('Hello')
+await thread.send('Tell me more')
+const saved = thread.serialize() // persist and restore later
+```
+
+## Workflows
+
+Orchestrate multi-agent pipelines:
+
+```ts
+const workflow = brain.workflow()
+  .step('research', ResearchAgent)
+  .step('summarize', SummaryAgent)
+  .parallel('review', [FactCheckAgent, StyleAgent])
+
+const result = await workflow.run('Analyze this topic')
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@strav/brain",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "AI module for the Strav framework",
+  "license": "MIT",
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts"
+  },
+  "files": [
+    "src/",
+    "package.json",
+    "tsconfig.json",
+    "CHANGELOG.md"
+  ],
+  "peerDependencies": {
+    "@strav/kernel": "0.1.0",
+    "@strav/workflow": "0.1.0"
+  },
+  "dependencies": {
+    "zod": "^3.25 || ^4.0"
+  },
+  "scripts": {
+    "test": "bun test tests/",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/agent.ts

@@ -0,0 +1,73 @@
+import type {
+  ToolDefinition,
+  ToolCall,
+  ToolCallRecord,
+  AgentResult,
+  OutputSchema,
+} from './types.ts'
+
+/**
+ * Base class for AI agents.
+ *
+ * Extend this class to define an agent with custom instructions,
+ * tools, structured output, and lifecycle hooks.
+ *
+ * @example
+ * class SupportAgent extends Agent {
+ *   provider = 'anthropic'
+ *   model = 'claude-sonnet-4-5-20250929'
+ *   instructions = 'You are a customer support agent.'
+ *   tools = [searchTool, lookupOrderTool]
+ *
+ *   output = z.object({
+ *     reply: z.string(),
+ *     category: z.enum(['billing', 'shipping', 'product', 'other']),
+ *   })
+ *
+ *   onToolCall(call: ToolCall) {
+ *     console.log(`Calling tool: ${call.name}`)
+ *   }
+ * }
+ */
+export abstract class Agent {
+  /** Provider name (e.g., 'anthropic', 'openai'). Falls back to config default. */
+  provider?: string
+
+  /** Model identifier. Falls back to the provider's configured default model. */
+  model?: string
+
+  /** System prompt / instructions for this agent. Supports `{{key}}` context interpolation. */
+  instructions: string = ''
+
+  /** Tools available to this agent during execution. */
+  tools?: ToolDefinition[]
+
+  /** Structured output schema (Zod or JSON Schema). When set, the final response is parsed and validated. */
+  output?: OutputSchema
+
+  /** Maximum tool-use loop iterations before forcing a stop. Falls back to config default (10). */
+  maxIterations?: number
+
+  /** Maximum tokens per completion request. Falls back to config default (4096). */
+  maxTokens?: number
+
+  /** Temperature for completion requests. Falls back to config default (0.7). */
+  temperature?: number
+
+  // ── Lifecycle hooks (optional) ───────────────────────────────────────────
+
+  /** Called before the first completion request. */
+  onStart?(input: string, context: Record<string, unknown>): void | Promise<void>
+
+  /** Called when the model requests a tool call, before execution. */
+  onToolCall?(call: ToolCall): void | Promise<void>
+
+  /** Called after a tool finishes execution. */
+  onToolResult?(call: ToolCallRecord): void | Promise<void>
+
+  /** Called when the agent run completes successfully. */
+  onComplete?(result: AgentResult): void | Promise<void>
+
+  /** Called when the agent run encounters an error. */
+  onError?(error: Error): void | Promise<void>
+}

package/src/brain_manager.ts

@@ -0,0 +1,136 @@
+import { inject, ConfigurationError, Configuration } from '@stravigor/kernel'
+import { AnthropicProvider } from './providers/anthropic_provider.ts'
+import { OpenAIProvider } from './providers/openai_provider.ts'
+import type {
+  AIProvider,
+  BrainConfig,
+  ProviderConfig,
+  CompletionRequest,
+  CompletionResponse,
+  BeforeHook,
+  AfterHook,
+} from './types.ts'
+import type { MemoryConfig, ThreadStore } from './memory/types.ts'
+
+/**
+ * Central AI configuration hub.
+ *
+ * Resolved once via the DI container — reads the AI config
+ * and initializes the appropriate provider drivers.
+ *
+ * @example
+ * app.singleton(BrainManager)
+ * app.resolve(BrainManager)
+ *
+ * // Plug in a custom provider
+ * BrainManager.useProvider(new OllamaProvider())
+ */
+@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.`
+        )
+    }
+  }
+
+  static get config(): BrainConfig {
+    if (!BrainManager._config) {
+      throw new ConfigurationError(
+        'BrainManager not configured. Resolve it through the container first.'
+      )
+    }
+    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
+  }
+
+  /** 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)
+  }
+
+  /** Register a hook that runs after every completion. */
+  static after(hook: AfterHook): void {
+    BrainManager._afterHooks.push(hook)
+  }
+
+  /**
+   * Run a completion through the named provider, with before/after hooks.
+   * Used internally by AgentRunner and the `brain` helper.
+   */
+  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
+  }
+
+  /** Clear all providers, hooks, and stores (for testing). */
+  static reset(): void {
+    BrainManager._providers.clear()
+    BrainManager._beforeHooks = []
+    BrainManager._afterHooks = []
+    BrainManager._threadStore = null
+    BrainManager._memoryConfig = {}
+  }
+}

package/src/brain_provider.ts

@@ -0,0 +1,16 @@
+import { ServiceProvider } from '@stravigor/kernel'
+import type { Application } from '@stravigor/kernel'
+import BrainManager from './brain_manager.ts'
+
+export default class BrainProvider extends ServiceProvider {
+  readonly name = 'brain'
+  override readonly dependencies = ['config']
+
+  override register(app: Application): void {
+    app.singleton(BrainManager)
+  }
+
+  override boot(app: Application): void {
+    app.resolve(BrainManager)
+  }
+}