@strav/brain 1.0.0-alpha.8 → 1.0.1

package/src/drivers/gemini/index.ts

@@ -0,0 +1 @@
+export { GeminiBrainDriver } from './gemini_brain_driver.ts'

package/src/drivers/minimax/index.ts

@@ -0,0 +1 @@
+export { MiniMaxBrainDriver } from './minimax_brain_driver.ts'

package/src/drivers/minimax/minimax_brain_driver.ts

@@ -0,0 +1,84 @@
+/**
+ * `MiniMaxBrainDriver` — `OpenAICompatBrainDriver` pointed at
+ * MiniMax's OpenAI-compatible endpoint at `https://api.minimax.io/v1`.
+ *
+ * MiniMax (M2, abab line) speaks the OpenAI Chat Completions wire
+ * format and supports function-calling, so the OpenAI-compat base
+ * already covers chat / stream / generate (via `json_object`) /
+ * runWithToolsAndSchema (via tool-forcing).
+ *
+ * MiniMax has a `reasoning_split=true` flag that surfaces the
+ * assistant's reasoning trace on a separate `reasoning_details`
+ * field. Not wired in V1 — `effort` / `thinking` are stripped by
+ * the OpenAI-compat `buildParams` override and apps reach for
+ * reasoning surfaces via the Anthropic / Gemini / OpenAI Responses
+ * drivers.
+ *
+ * `embed` / `transcribe` are not exposed via the compatibility
+ * endpoint; the inherited stubs are replaced with explicit
+ * `BrainError`s so apps see a clear message instead of a wire 404.
+ */
+
+import type OpenAI from 'openai'
+import type { MiniMaxProviderConfig } from '../../brain_config.ts'
+import { BrainError } from '../../brain_error.ts'
+import type { ResolveMcpToolsOptions } from '../../mcp/resolve_mcp_tools.ts'
+import type {
+  AudioSource,
+  EmbedOptions,
+  EmbedResult,
+  TranscribeOptions,
+  TranscribeResult,
+} from '../../types.ts'
+import { OpenAICompatBrainDriver } from '../openai_compat/openai_compat_brain_driver.ts'
+
+const DEFAULT_MINIMAX_MODEL = 'MiniMax-M2'
+const DEFAULT_MINIMAX_BASE_URL = 'https://api.minimax.io/v1'
+
+export interface MiniMaxProviderOptions {
+  client?: OpenAI
+  /**
+   * Internal seam — tests inject a stub MCP client factory so MCP
+   * tool resolution doesn't dial the network. Real apps leave it
+   * unset; the provider uses the default `MCPClient`.
+   */
+  mcpClientFactory?: ResolveMcpToolsOptions['clientFactory']
+}
+
+export class MiniMaxBrainDriver extends OpenAICompatBrainDriver {
+  constructor(name: string, config: MiniMaxProviderConfig, options: MiniMaxProviderOptions = {}) {
+    super(
+      name,
+      {
+        driver: 'openai',
+        apiKey: config.apiKey,
+        baseUrl: config.baseUrl ?? DEFAULT_MINIMAX_BASE_URL,
+        defaultModel: config.defaultModel ?? DEFAULT_MINIMAX_MODEL,
+        ...(config.defaultMaxTokens !== undefined
+          ? { defaultMaxTokens: config.defaultMaxTokens }
+          : {}),
+      },
+      options,
+    )
+  }
+
+  override async embed(
+    _texts: readonly string[],
+    _options?: EmbedOptions,
+  ): Promise<EmbedResult<OpenAI.CreateEmbeddingResponse>> {
+    throw new BrainError(
+      `MiniMaxBrainDriver.embed: MiniMax's OpenAI-compatibility endpoint does not expose embeddings. Route embed calls to a provider with native support — OpenAI / Gemini / Ollama.`,
+      { context: { provider: this.name } },
+    )
+  }
+
+  override async transcribe(
+    _audio: AudioSource,
+    _options?: TranscribeOptions,
+  ): Promise<TranscribeResult<OpenAI.Audio.TranscriptionCreateResponse>> {
+    throw new BrainError(
+      "MiniMaxBrainDriver.transcribe: MiniMax's OpenAI-compatibility endpoint does not expose audio transcription. Route transcribe calls to a provider with native support — OpenAI / Ollama / Gemini.",
+      { context: { provider: this.name } },
+    )
+  }
+}

package/src/drivers/ollama/index.ts

@@ -0,0 +1 @@
+export { OllamaBrainDriver } from './ollama_brain_driver.ts'

package/src/drivers/ollama/ollama_brain_driver.ts

@@ -0,0 +1,86 @@
+/**
+ * `OllamaBrainDriver` — `OpenAICompatBrainDriver` pointed at a local
+ * Ollama server's OpenAI-compatible `/v1` endpoint.
+ *
+ * Why this matters: Ollama (and the wider local-LLM ecosystem —
+ * LM Studio, llama.cpp's server, vLLM, TGI) lets apps run
+ * inference on-device or on-prem. Two real use cases:
+ *
+ *   - **Privacy.** Data never leaves the machine / the customer's
+ *     network — table stakes for regulated workloads.
+ *   - **Dev / test.** Build agents without burning API credits or
+ *     needing a cloud key at all. Run the test suite against a
+ *     local `llama3.2:1b` for free; ship to a hosted provider in
+ *     prod.
+ *
+ * Inherits the OpenAI-compat overrides (strip `reasoning_effort`,
+ * `json_object`-mode generate with schema-in-system-prompt,
+ * throws on combined tools + schema) from the base. Only adds:
+ *
+ *   - Constructor with Ollama defaults — base URL
+ *     `http://localhost:11434/v1`, placeholder API key `'ollama'`
+ *     (the SDK demands a non-empty string; Ollama ignores it).
+ *
+ * `defaultModel` is required because Ollama models are
+ * user-installed via `ollama pull <model>` — no universal default
+ * exists. Tool calling depends on the underlying model; pick a
+ * function-calling-tuned model (`llama3.2`, `qwen2.5`, `mistral`)
+ * for `runWithTools` to behave.
+ *
+ * The same provider works against any OpenAI-compatible local
+ * server by overriding `baseUrl` — LM Studio (`:1234/v1`),
+ * llama.cpp's server (`:8080/v1`), vLLM, TGI, remote Ollama on
+ * another host. The driver name is `ollama` for ergonomic reasons;
+ * the implementation is "any OpenAI-compatible local server."
+ *
+ * Local inference has no upstream prompt cache, so the default
+ * `mapUsage` (cache fields → 0) is correct without override.
+ * `countTokens` not implemented (Ollama doesn't expose a count
+ * endpoint).
+ */
+
+import type OpenAI from 'openai'
+import type { OllamaProviderConfig } from '../../brain_config.ts'
+import type { ResolveMcpToolsOptions } from '../../mcp/resolve_mcp_tools.ts'
+import { OpenAICompatBrainDriver } from '../openai_compat/openai_compat_brain_driver.ts'
+
+const DEFAULT_OLLAMA_BASE_URL = 'http://localhost:11434/v1'
+const DEFAULT_OLLAMA_API_KEY = 'ollama'
+
+export interface OllamaProviderOptions {
+  client?: OpenAI
+  /**
+   * Internal seam — tests inject a stub MCP client factory so MCP
+   * tool resolution doesn't dial the network. Real apps leave it
+   * unset; the provider uses the default `MCPClient`.
+   */
+  mcpClientFactory?: ResolveMcpToolsOptions['clientFactory']
+}
+
+export class OllamaBrainDriver extends OpenAICompatBrainDriver {
+  constructor(
+    name: string,
+    config: OllamaProviderConfig,
+    options: OllamaProviderOptions = {},
+  ) {
+    super(
+      name,
+      {
+        driver: 'openai',
+        apiKey: config.apiKey ?? DEFAULT_OLLAMA_API_KEY,
+        baseUrl: config.baseUrl ?? DEFAULT_OLLAMA_BASE_URL,
+        defaultModel: config.defaultModel,
+        ...(config.defaultMaxTokens !== undefined
+          ? { defaultMaxTokens: config.defaultMaxTokens }
+          : {}),
+        ...(config.defaultEmbedModel !== undefined
+          ? { defaultEmbedModel: config.defaultEmbedModel }
+          : {}),
+        ...(config.defaultTranscribeModel !== undefined
+          ? { defaultTranscribeModel: config.defaultTranscribeModel }
+          : {}),
+      },
+      options,
+    )
+  }
+}

package/src/drivers/openai/index.ts

@@ -0,0 +1 @@
+export { OpenAIBrainDriver } from './openai_brain_driver.ts'