prism-mcp-server 4.2.0 → 4.6.0

package/dist/utils/llm/adapters/openai.js

@@ -0,0 +1,183 @@
+/**
+ * OpenAI Adapter (v4.5)
+ * ─────────────────────────────────────────────────────────────────────────────
+ * PURPOSE:
+ *   Implements LLMProvider using the official `openai` Node.js SDK.
+ *   A single adapter that covers FOUR deployment scenarios:
+ *
+ *   1. Cloud OpenAI (default)
+ *      apiKey  = OPENAI_API_KEY env var or dashboard setting
+ *      baseURL = https://api.openai.com/v1  (default)
+ *      Models: gpt-4o-mini (default text), text-embedding-3-small (embedding)
+ *
+ *   2. Ollama (local, open-source)
+ *      apiKey  = (not needed — leave blank)
+ *      baseURL = http://localhost:11434/v1
+ *      Models: any model you've pulled (e.g. llama3.2, nomic-embed-text)
+ *
+ *   3. LM Studio (local GUI)
+ *      apiKey  = (not needed — leave blank)
+ *      baseURL = http://localhost:1234/v1
+ *
+ *   4. vLLM / custom OpenAI-compatible server
+ *      apiKey  = (server-specific)
+ *      baseURL = http://<host>:<port>/v1
+ *
+ * EMBEDDING DIMENSION PARITY (768 dims):
+ *   Prism's SQLite (sqlite-vec) and Supabase (pgvector) schemas define
+ *   embedding columns as EXACTLY 768 dimensions. This was chosen to match
+ *   Gemini's native output size. All adapters MUST return 768-dim vectors.
+ *
+ *   OpenAI solution: text-embedding-3-* models support the `dimensions`
+ *   parameter via Matryoshka Representation Learning (MRL), which produces
+ *   a shorter but still high-quality vector. text-embedding-3-small at 768
+ *   dims outperforms text-embedding-ada-002 at its native 1536 dims.
+ *
+ *   WARNING for local models (Ollama / LM Studio):
+ *   Many locally-served models do NOT support the `dimensions` parameter.
+ *   We log a warning but do NOT throw — the error will surface at the DB
+ *   write boundary, which is the right place to enforce the constraint.
+ *   Choose a local embedding model that natively outputs 768 dims
+ *   (e.g. nomic-embed-text = 768, mxbai-embed-large = 1024 — avoid latter).
+ *
+ * CONFIG KEYS (Prism dashboard "AI Providers" tab OR environment variables):
+ *   openai_api_key         — API key (empty = localhost/Ollama mode)
+ *   openai_base_url        — Base URL (default: https://api.openai.com/v1)
+ *   openai_model           — Chat model (default: gpt-4o-mini)
+ *   openai_embedding_model — Embedding model (default: text-embedding-3-small)
+ */
+import OpenAI from "openai";
+import { getSettingSync } from "../../../storage/configStorage.js";
+import { debugLog } from "../../logger.js";
+// ─── Constants ────────────────────────────────────────────────────────────────
+// Must match Prism's DB schema (sqlite-vec and pgvector column sizes).
+// Changing this requires a DB migration — do not adjust casually.
+const EMBEDDING_DIMS = 768;
+// text-embedding-3-small has an 8191-token context window.
+// We use a conservative character-based cap to avoid needing a tokenizer.
+// 8000 chars ≈ 1500-2000 tokens for typical session summaries.
+const MAX_EMBEDDING_CHARS = 8000;
+export class OpenAIAdapter {
+    // The OpenAI SDK client — stateful, holds the API key + base URL.
+    // One instance per factory singleton = one instance per MCP server process.
+    client;
+    constructor() {
+        // Priority: dashboard setting → environment variable → empty string.
+        // This lets users configure keys via the dashboard without touching .env.
+        const apiKey = getSettingSync("openai_api_key", process.env.OPENAI_API_KEY ?? "");
+        const baseURL = getSettingSync("openai_base_url", "https://api.openai.com/v1");
+        // Detect local inference endpoints — these don't need a real API key.
+        // Ollama and LM Studio use local HTTP servers with no authentication.
+        const isLocal = baseURL.includes("localhost") || baseURL.includes("127.0.0.1");
+        // Fail construction if no key AND we're pointing at a real API endpoint.
+        // The factory will catch this and fall back to GeminiAdapter gracefully.
+        if (!apiKey && !isLocal) {
+            throw new Error("OpenAI API key is not set and base URL is not a local endpoint. " +
+                "Set OPENAI_API_KEY or configure a local base URL (e.g. http://localhost:11434/v1).");
+        }
+        this.client = new OpenAI({
+            // Ollama requires a non-empty string for apiKey even though it ignores it.
+            // "ollama" is the conventional placeholder in the Ollama docs.
+            apiKey: apiKey || "ollama",
+            baseURL,
+        });
+        debugLog(`[OpenAIAdapter] Initialized — baseURL=${baseURL}, keyless=${!apiKey}`);
+    }
+    // ─── Text Generation ─────────────────────────────────────────────────────
+    async generateText(prompt, systemInstruction) {
+        // Read model at call time (not constructor) so the user can hot-swap
+        // the model setting without restarting the server.
+        const model = getSettingSync("openai_model", "gpt-4o-mini");
+        // Build message array: optional system message first, then user prompt.
+        // This maps cleanly to Gemini's systemInstruction + user prompt pattern.
+        const messages = [];
+        if (systemInstruction) {
+            messages.push({ role: "system", content: systemInstruction });
+        }
+        messages.push({ role: "user", content: prompt });
+        debugLog(`[OpenAIAdapter] generateText — model=${model}, messages=${messages.length}`);
+        const response = await this.client.chat.completions.create({ model, messages });
+        // choices[0] is always the primary completion. ?? "" returns empty string
+        // on null content (e.g. if the model returned a function call instead).
+        return response.choices[0]?.message?.content ?? "";
+    }
+    // ─── Embedding Generation ────────────────────────────────────────────────
+    async generateEmbedding(text) {
+        // Guard: empty input produces a degenerate embedding — fail loudly.
+        if (!text || !text.trim()) {
+            throw new Error("Cannot generate embedding for empty text.");
+        }
+        // Read embedding model at call time for hot-swap support.
+        const model = getSettingSync("openai_embedding_model", "text-embedding-3-small");
+        // ── Truncation Guard ───────────────────────────────────────────────────
+        // text-embedding-3-small accepts up to 8191 tokens.
+        // We apply the same preventive truncation as GeminiAdapter so behavior
+        // is consistent regardless of which provider is active.
+        let inputText = text;
+        if (inputText.length > MAX_EMBEDDING_CHARS) {
+            debugLog(`[OpenAIAdapter] Embedding input truncated from ${inputText.length}` +
+                ` to ~${MAX_EMBEDDING_CHARS} chars (word-safe)`);
+            // Hard cut, then snap back to last word boundary (avoids mid-word splits)
+            inputText = inputText.substring(0, MAX_EMBEDDING_CHARS);
+            const lastSpace = inputText.lastIndexOf(" ");
+            if (lastSpace > 0)
+                inputText = inputText.substring(0, lastSpace);
+        }
+        debugLog(`[OpenAIAdapter] generateEmbedding — model=${model}, dims=${EMBEDDING_DIMS}`);
+        const response = await this.client.embeddings.create({
+            model,
+            input: inputText,
+            // `dimensions` triggers Matryoshka truncation — produces a 768-dim vector
+            // without the full 1536-dim generation + local truncation overhead.
+            // ONLY works with text-embedding-3-* models. ada-002 ignores this field.
+            dimensions: EMBEDDING_DIMS,
+        });
+        const embedding = response.data[0]?.embedding;
+        // Hard check: null/empty response means the API returned nothing useful.
+        if (!Array.isArray(embedding) || embedding.length === 0) {
+            throw new Error(`[OpenAIAdapter] Embedding response is empty for model "${model}"`);
+        }
+        // ── Dimension Warning (soft — not a hard throw) ────────────────────────
+        // Why soft? Local models (Ollama) may ignore `dimensions` and return their
+        // native size. A hard throw here would make Ollama completely unusable.
+        // The mismatch will be caught at the DB write boundary (pgvector/sqlite-vec
+        // will reject mismatched vector sizes with a clear error message).
+        if (embedding.length !== EMBEDDING_DIMS) {
+            console.warn(`[OpenAIAdapter] Embedding dimension mismatch: expected ${EMBEDDING_DIMS}, ` +
+                `got ${embedding.length}. ` +
+                `If using a local model, use one that natively outputs ${EMBEDDING_DIMS} dims ` +
+                `(e.g. nomic-embed-text) or supports the Matryoshka 'dimensions' parameter.`);
+        }
+        return embedding;
+    }
+    // ─── Image Description (VLM) ─────────────────────────────────────────────
+    /**
+     * Describe an image via the OpenAI Chat Completions vision API.
+     * Uses the chat model (gpt-4o-mini default) since OpenAI embeds vision
+     * into their chat API rather than a separate endpoint.
+     * Works with any OpenAI-compatible server that supports vision
+     * (Ollama with llava, LM Studio with vision models, etc.).
+     */
+    async generateImageDescription(imageBase64, mimeType, context) {
+        const model = getSettingSync("openai_model", "gpt-4o-mini");
+        const prompt = context
+            ? `Describe this image in rich detail for a developer knowledge base. User context: "${context}"`
+            : "Describe this image in rich detail for a developer knowledge base. Include: UI elements, visible text, architectural components, and key observations.";
+        const response = await this.client.chat.completions.create({
+            model,
+            max_tokens: 1024,
+            messages: [{
+                    role: "user",
+                    content: [
+                        {
+                            type: "image_url",
+                            // OpenAI vision requires the data-URI prefix
+                            image_url: { url: `data:${mimeType};base64,${imageBase64}` },
+                        },
+                        { type: "text", text: prompt },
+                    ],
+                }],
+        });
+        return response.choices[0]?.message?.content ?? "";
+    }
+}

package/dist/utils/llm/adapters/traced.js

@@ -0,0 +1,190 @@
+/**
+ * TracingLLMProvider — OpenTelemetry Decorator (v4.6.0)
+ * ─────────────────────────────────────────────────────────────────────────────
+ * PURPOSE:
+ *   Wraps any LLMProvider with OTel span instrumentation without modifying
+ *   any of the three existing adapters (gemini.ts, openai.ts, anthropic.ts).
+ *
+ * PATTERN: Decorator (Gang of Four)
+ *   Implements LLMProvider and delegates every method call to the wrapped
+ *   `inner` provider, bookending each call with an OTel span.
+ *
+ * WHY NOT INSTRUMENT INSIDE THE ADAPTERS?
+ *   1. Single Responsibility — each adapter has one job: talk to its API.
+ *   2. DRY — the span pattern is identical across all three adapters.
+ *   3. Testability — this class can be tested with a mock inner provider.
+ *   4. Composability — future decorators (rate-limiting, caching) layer on
+ *      top without touching any adapter code.
+ *
+ * VLM METHOD OPTIONALITY:
+ *   TypeScript class methods always exist on the prototype — even optional ones.
+ *   To preserve the `generateImageDescription?` contract (so imageCaptioner.ts's
+ *   `if (llm.generateImageDescription)` check works correctly), we assign the
+ *   VLM method as an own-property in the constructor only when the inner
+ *   adapter supports it. Otherwise the property stays `undefined`.
+ *
+ * GDPR NOTE ON SPAN ATTRIBUTES:
+ *   We log character counts and dimensions — never the full prompt, embedding
+ *   vector, or base64 image content. A full prompt stored in Jaeger/Datadog
+ *   would be a GDPR compliance risk.
+ *
+ * SPAN HIERARCHY (example for session_search_memory):
+ *   ▼ mcp.call_tool (session_search_memory) [root — server.ts]
+ *     ▼ llm.generate_embedding               [this decorator]
+ *
+ * CONTEXT PROPAGATION:
+ *   AsyncLocalStorage (OTel's context mechanism) automatically parents these
+ *   spans to the active root span from server.ts. No explicit ref-passing needed.
+ *
+ * FILE LOCATION: src/utils/llm/adapters/traced.ts
+ * IMPORTS FROM:  ../provider.js  (one level up, in src/utils/llm/)
+ *                ../../telemetry.js (two levels up, in src/utils/)
+ * ─────────────────────────────────────────────────────────────────────────────
+ */
+import { SpanStatusCode, context, trace } from "@opentelemetry/api";
+import { getTracer } from "../../telemetry.js";
+export class TracingLLMProvider {
+    inner;
+    providerName;
+    /**
+     * The optional VLM method is declared here as a typed property so TypeScript
+     * knows about it. It is assigned (or left undefined) in the constructor body
+     * based on whether the inner adapter supports it.
+     *
+     * @see constructor for assignment logic
+     */
+    generateImageDescription;
+    /**
+     * @param inner        The actual LLM adapter (Gemini, OpenAI, or Anthropic).
+     * @param providerName Human-readable label used in span attributes.
+     *                     factory.ts passes e.g. "gemini", "openai", "anthropic".
+     */
+    constructor(inner, providerName) {
+        this.inner = inner;
+        this.providerName = providerName;
+        // ── VLM method: conditional own-property assignment ──────────────────
+        // REVIEWER NOTE: TypeScript class methods always appear on the prototype,
+        // which means `if (llm.generateImageDescription)` would always be truthy
+        // even if we wrote `generateImageDescription?() {}` as a class method.
+        // Assigning as an own-property in the constructor and leaving it undefined
+        // when the inner adapter has no VLM support is the correct TypeScript
+        // pattern for preserving optional interface method semantics.
+        if (inner.generateImageDescription) {
+            const innerVlm = inner.generateImageDescription.bind(inner);
+            const providerName = this.providerName; // capture for closure (avoids 'this' ambiguity)
+            this.generateImageDescription = async (imageBase64, mimeType, ctx) => {
+                /**
+                 * Span: llm.generate_image_description
+                 *
+                 * VLM calls are the most expensive operations in Prism (2–5 seconds).
+                 * We log the image size (bytes) as a cost proxy but NOT the base64
+                 * content itself — storing megabytes in OTLP backends causes OOM in
+                 * most collector configurations and violates GDPR data minimization.
+                 */
+                const span = getTracer().startSpan("llm.generate_image_description", {
+                    attributes: {
+                        "llm.provider": providerName,
+                        "llm.mime_type": mimeType,
+                        // Estimate decoded byte size from base64 length (base64 overhead ≈ 4/3)
+                        "llm.image_size_bytes": Math.round(imageBase64.length * 0.75),
+                    },
+                });
+                return context.with(trace.setSpan(context.active(), span), async () => {
+                    try {
+                        const result = await innerVlm(imageBase64, mimeType, ctx);
+                        span.setAttribute("llm.caption_len", result.length);
+                        span.setStatus({ code: SpanStatusCode.OK });
+                        return result;
+                    }
+                    catch (err) {
+                        span.recordException(err instanceof Error ? err : new Error(String(err)));
+                        span.setStatus({
+                            code: SpanStatusCode.ERROR,
+                            message: err instanceof Error ? err.message : String(err),
+                        });
+                        throw err;
+                    }
+                    finally {
+                        span.end();
+                    }
+                });
+            };
+        }
+        // If inner.generateImageDescription is undefined, this.generateImageDescription
+        // stays undefined (as declared above) — the property check in imageCaptioner.ts
+        // will correctly evaluate to false.
+    }
+    // ── generateText ──────────────────────────────────────────────────────────
+    async generateText(prompt, systemInstruction) {
+        /**
+         * Span: llm.generate_text
+         *
+         * `llm.text_len` (character count) is a cost proxy. We do NOT store the
+         * full prompt — it can contain session memory content (PII risk).
+         */
+        const span = getTracer().startSpan("llm.generate_text", {
+            attributes: {
+                "llm.provider": this.providerName,
+                "llm.text_len": prompt.length,
+            },
+        });
+        return context.with(trace.setSpan(context.active(), span), async () => {
+            try {
+                const result = await this.inner.generateText(prompt, systemInstruction);
+                span.setStatus({ code: SpanStatusCode.OK });
+                return result;
+            }
+            catch (err) {
+                span.recordException(err instanceof Error ? err : new Error(String(err)));
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: err instanceof Error ? err.message : String(err),
+                });
+                throw err;
+            }
+            finally {
+                // Always end the span — even on error — to prevent BatchSpanProcessor
+                // from holding a reference to a never-ending span object indefinitely.
+                span.end();
+            }
+        });
+    }
+    // ── generateEmbedding ─────────────────────────────────────────────────────
+    async generateEmbedding(text) {
+        /**
+         * Span: llm.generate_embedding
+         *
+         * Embeddings are the most frequent LLM calls in Prism — one fires
+         * asynchronously on every ledger save. The latency distribution in Jaeger
+         * reveals when to consider local embedding models (Ollama nomic-embed-text).
+         *
+         * `llm.embed_dim` lets us catch dimension mismatches before pgvector fails:
+         * if an adapter returns 384 dimensions instead of 768, it shows in the trace.
+         */
+        const span = getTracer().startSpan("llm.generate_embedding", {
+            attributes: {
+                "llm.provider": this.providerName,
+                "llm.embed_len": text.length,
+            },
+        });
+        return context.with(trace.setSpan(context.active(), span), async () => {
+            try {
+                const result = await this.inner.generateEmbedding(text);
+                span.setAttribute("llm.embed_dim", result.length);
+                span.setStatus({ code: SpanStatusCode.OK });
+                return result;
+            }
+            catch (err) {
+                span.recordException(err instanceof Error ? err : new Error(String(err)));
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: err instanceof Error ? err.message : String(err),
+                });
+                throw err;
+            }
+            finally {
+                span.end();
+            }
+        });
+    }
+}

package/dist/utils/llm/factory.js

@@ -0,0 +1,143 @@
+/**
+ * LLM Provider Factory (v4.4 — Split Provider Architecture)
+ * ─────────────────────────────────────────────────────────────────────────────
+ * PURPOSE:
+ *   Single point of resolution for the active LLMProvider.
+ *   Composes a TEXT adapter and an EMBEDDING adapter independently, returning
+ *   a single object that satisfies the LLMProvider interface. Consumers never
+ *   know the difference — getLLMProvider() behavior is unchanged.
+ *
+ * SPLIT PROVIDER ARCHITECTURE:
+ *   Two independent settings control text and embedding routing:
+ *
+ *   text_provider      — "gemini" (default) | "openai" | "anthropic"
+ *   embedding_provider — "auto" (default)   | "gemini" | "openai"
+ *
+ *   When embedding_provider = "auto":
+ *     * If text_provider is gemini or openai → use same provider for embeddings
+ *     * If text_provider is anthropic → auto-fallback to gemini for embeddings
+ *       (Anthropic has no native embedding API)
+ *
+ * EXAMPLE CONFIGURATIONS:
+ *   text_provider=gemini,    embedding_provider=auto   → Gemini+Gemini (default)
+ *   text_provider=openai,    embedding_provider=auto   → OpenAI+OpenAI
+ *   text_provider=anthropic, embedding_provider=auto   → Claude+Gemini (auto-bridge)
+ *   text_provider=anthropic, embedding_provider=openai → Claude+Ollama (cost-optimized)
+ *   text_provider=gemini,    embedding_provider=openai → Gemini+Ollama (mixed)
+ *
+ * SINGLETON + GRACEFUL DEGRADATION:
+ *   Same as before — instance cached per process, errors fall back to Gemini.
+ *   Provider switches require an MCP server restart.
+ *
+ * TESTING:
+ *   _resetLLMProvider() clears the singleton for test injection.
+ *
+ * ADDING NEW PROVIDERS:
+ *   1. Implement LLMProvider in src/utils/llm/adapters/<name>.ts
+ *   2. Add a case to buildTextAdapter() and/or buildEmbeddingAdapter() below
+ *   3. Add the option to the dashboard "AI Providers" tab
+ */
+import { getSettingSync } from "../../storage/configStorage.js";
+import { GeminiAdapter } from "./adapters/gemini.js";
+import { OpenAIAdapter } from "./adapters/openai.js";
+import { AnthropicAdapter } from "./adapters/anthropic.js";
+import { TracingLLMProvider } from "./adapters/traced.js";
+// Module-level singleton — one composed provider per MCP server process.
+let providerInstance = null;
+// ─── Adapter Builders ─────────────────────────────────────────────────────────
+// Separated from getLLMProvider() so they can be called independently for the
+// text and embedding halves of the composite provider.
+function buildTextAdapter(type) {
+    switch (type) {
+        case "anthropic": return new AnthropicAdapter();
+        case "openai": return new OpenAIAdapter();
+        case "gemini":
+        default: return new GeminiAdapter();
+    }
+}
+function buildEmbeddingAdapter(type) {
+    // Note: "anthropic" is intentionally absent from this switch.
+    // Anthropic has no embedding API, so it can never be an embedding provider.
+    // The factory resolves "auto" away from "anthropic" before calling this.
+    switch (type) {
+        case "openai": return new OpenAIAdapter();
+        case "gemini":
+        default: return new GeminiAdapter();
+    }
+}
+// ─── Factory ─────────────────────────────────────────────────────────────────
+/**
+ * Returns the singleton LLM provider, initializing it on first call.
+ *
+ * The returned object composes two independent adapters:
+ *   - generateText()      → text adapter (text_provider setting)
+ *   - generateEmbedding() → embedding adapter (embedding_provider setting)
+ *
+ * Consumers see no difference — the interface is identical to before.
+ */
+export function getLLMProvider() {
+    // Fast path: return cached composite instance
+    if (providerInstance)
+        return providerInstance;
+    // ── Resolve text provider ─────────────────────────────────────────────
+    const textType = getSettingSync("text_provider", "gemini");
+    // ── Resolve embedding provider ────────────────────────────────────────
+    let embedType = getSettingSync("embedding_provider", "auto");
+    if (embedType === "auto") {
+        // Anthropic has no embedding API — auto-bridge to Gemini.
+        // For all other text providers, use the same provider for embeddings.
+        embedType = textType === "anthropic" ? "gemini" : textType;
+        if (textType === "anthropic") {
+            console.info("[LLMFactory] text_provider=anthropic with embedding_provider=auto: " +
+                "routing embeddings to GeminiAdapter (Anthropic has no native embedding API). " +
+                "Set embedding_provider=openai in dashboard to use Ollama/OpenAI instead.");
+        }
+    }
+    try {
+        const textAdapter = buildTextAdapter(textType);
+        const embedAdapter = buildEmbeddingAdapter(embedType);
+        // Compose into a single LLMProvider-compatible object.
+        // Methods are bound to their respective adapter instances so `this`
+        // resolves correctly inside the adapter methods.
+        const composed = {
+            generateText: textAdapter.generateText.bind(textAdapter),
+            generateEmbedding: embedAdapter.generateEmbedding.bind(embedAdapter),
+        };
+        // Pass VLM support through from the text adapter if it exists.
+        // generateImageDescription is a text-generation concern (it calls the
+        // text/vision model, not the embedding model). The text adapter owns it.
+        if (textAdapter.generateImageDescription) {
+            composed.generateImageDescription = textAdapter.generateImageDescription.bind(textAdapter);
+        }
+        // ── v4.6.0: Wrap with OTel tracing decorator ─────────────────────────
+        // TracingLLMProvider is a zero-overhead no-op when otel_enabled=false.
+        // The text provider name is used as the primary span attribute label.
+        providerInstance = new TracingLLMProvider(composed, textType);
+        if (textType !== embedType) {
+            console.info(`[LLMFactory] Split provider: text=${textType}, embedding=${embedType}`);
+        }
+    }
+    catch (err) {
+        // Init failure (e.g. missing API key) → fall back to full Gemini provider.
+        // A crash here would silently kill the MCP server.
+        console.error(`[LLMFactory] Failed to initialise providers (text=${textType}, embed=${embedType}): ${err}. ` +
+            `Falling back to GeminiAdapter for both.`);
+        const fallback = new GeminiAdapter();
+        const fallbackComposed = {
+            generateText: fallback.generateText.bind(fallback),
+            generateEmbedding: fallback.generateEmbedding.bind(fallback),
+        };
+        if (fallback.generateImageDescription) {
+            fallbackComposed.generateImageDescription = fallback.generateImageDescription.bind(fallback);
+        }
+        providerInstance = new TracingLLMProvider(fallbackComposed, "gemini");
+    }
+    return providerInstance;
+}
+/**
+ * Reset the cached singleton.
+ * ONLY for unit tests — never call in production code.
+ */
+export function _resetLLMProvider() {
+    providerInstance = null;
+}

package/dist/utils/llm/provider.js

@@ -0,0 +1,25 @@
+/**
+ * LLM Provider Interface (v4.5)
+ * ─────────────────────────────────────────────────────────────────────────────
+ * PURPOSE:
+ *   Defines the contract that ALL LLM adapters must satisfy.
+ *   This is the single seam in Prism's AI layer — the only thing consumers
+ *   (compaction, summarization, embedding, security scan, briefing) need to
+ *   know about. They never reference a specific model or SDK.
+ *
+ * DESIGN PHILOSOPHY:
+ *   Keep the interface intentionally minimal. Prism only needs two LLM
+ *   capabilities for its own internal operations. Adding more methods here
+ *   would force every future adapter to implement things it doesn't need.
+ *
+ * ADAPTER IMPLEMENTATIONS (src/utils/llm/adapters/):
+ *   - gemini.ts    → Google Gemini (default; all methods including VLM)
+ *   - openai.ts    → OpenAI Cloud + Ollama + LM Studio + vLLM
+ *   - anthropic.ts → Anthropic Claude (VLM supported; embeddings unsupported)
+ *
+ * FACTORY RESOLUTION:
+ *   Never instantiate adapters directly. Always call:
+ *     import { getLLMProvider } from "../llm/factory.js";
+ *     const llm = getLLMProvider();
+ */
+export {};