prism-mcp-server 4.2.0 → 4.6.0

package/dist/utils/imageCaptioner.js

@@ -0,0 +1,240 @@
+/**
+ * Image Captioner (v4.5)
+ * ─────────────────────────────────────────────────────────────────────────────
+ * PURPOSE:
+ *   Fire-and-forget background pipeline that auto-captions images saved via
+ *   `session_save_image`. Connects the VLM adapter → handoff visual_memory →
+ *   session ledger → embedding backfill so images become semantically
+ *   searchable without any changes to the tool surface area.
+ *
+ * PIPELINE (all async, never blocks the MCP response):
+ *   1. Read vault file → base64
+ *   2. Size check (Anthropic: 5MB hard cap; all others: 20MB soft cap)
+ *   3. getLLMProvider().generateImageDescription(base64, mimeType, context)
+ *   4. storage.updateImageCaption(project, imageId, caption)   — patches handoff
+ *   5. storage.saveLedger(...)                                 — makes caption searchable
+ *   6. backfillEmbeddingsAsync(project)                        — vector-indexes caption
+ *
+ * DESIGN DECISIONS:
+ *   - `generateImageDescription` is optional on LLMProvider. If the active
+ *     provider doesn't support VLM (e.g. a text-only Ollama model), captioning
+ *     is skipped gracefully with a single log line.
+ *   - Errors are caught and logged; they never propagate. `session_save_image`
+ *     already returned successfully when this runs.
+ *   - The Anthropic 5MB limit is checked before calling the API. Gemini and
+ *     OpenAI accept up to ~20MB.
+ *   - The ledger entry embeds image ID and path in the `summary` string because
+ *     the ledger schema has no generic metadata column.
+ */
+import * as fs from "fs";
+import * as nodePath from "path";
+import { getLLMProvider } from "./llm/factory.js";
+import { getStorage } from "../storage/index.js";
+import { debugLog } from "./logger.js";
+import { PRISM_USER_ID } from "../config.js";
+import { getTracer } from "./telemetry.js";
+import { SpanStatusCode, context as otelContext, trace } from "@opentelemetry/api";
+// ─── Size Caps ────────────────────────────────────────────────────────────────
+/** Anthropic Messages API rejects base64 image payloads > 5MB */
+const ANTHROPIC_MAX_BYTES = 5 * 1024 * 1024;
+/** Gemini / OpenAI accept larger images; 20MB is a conservative safe cap */
+const DEFAULT_MAX_BYTES = 20 * 1024 * 1024;
+// ─── MIME Type Detection ──────────────────────────────────────────────────────
+const EXT_TO_MIME = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
+    ".gif": "image/gif",
+    ".svg": "image/svg+xml",
+};
+function getMimeType(filePath) {
+    const ext = nodePath.extname(filePath).toLowerCase();
+    return EXT_TO_MIME[ext] ?? "image/png";
+}
+// ─── Public API ───────────────────────────────────────────────────────────────
+/**
+ * Fire-and-forget wrapper. Call this from `session_save_image` after the
+ * file is in the vault and the handoff has been saved. Errors are swallowed.
+ *
+ * @param project     Project identifier
+ * @param imageId     Short UUID assigned by session_save_image (e.g. "a3f1b2c9")
+ * @param vaultPath   Absolute path to the copied file in ~/.prism-mcp/media/
+ * @param userContext User-provided description (passed as hint to the VLM)
+ */
+export function fireCaptionAsync(project, imageId, vaultPath, userContext) {
+    // ── v4.6.0: OTel worker span ──────────────────────────────────────────────
+    // We start the span here (not inside captionImageAsync) so it runs within
+    // the active OTel context that was propagated from the mcp.call_tool root
+    // span in server.ts. AsyncLocalStorage carries the context across the
+    // async boundary, making this a child of session_save_image in Jaeger.
+    //
+    // The parent (mcp.call_tool) typically ends at ~50ms when the MCP response
+    // is sent. This worker span continues until captioning completes (2–5s).
+    // In Jaeger, you will see the parent end first, then its child outlive it —
+    // this is the correct, expected representation of fire-and-forget async work.
+    const span = getTracer().startSpan("worker.vlm_caption", {
+        attributes: {
+            "worker.image_id": imageId,
+            "worker.project": project,
+        },
+    });
+    // context.with() propagates the OTel span into the async chain so any further
+    // nested spans (e.g. llm.generate_image_description inside TracingLLMProvider)
+    // are correctly parented as grandchildren of mcp.call_tool.
+    otelContext.with(trace.setSpan(otelContext.active(), span), () => {
+        captionImageAsync(project, imageId, vaultPath, userContext)
+            .then(() => {
+            span.setStatus({ code: SpanStatusCode.OK });
+        })
+            .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),
+            });
+            console.error(`[ImageCaptioner] Failed for [${imageId}]: ${err}`);
+        })
+            .finally(() => {
+            // Always end the span — even on VLM failure — to flush the BatchSpanProcessor.
+            span.end();
+        });
+    });
+}
+// ─── Core Pipeline ────────────────────────────────────────────────────────────
+async function captionImageAsync(project, imageId, vaultPath, userContext) {
+    // ── Step 1: Resolve provider ─────────────────────────────────────────────
+    const llm = getLLMProvider();
+    if (!llm.generateImageDescription) {
+        debugLog(`[ImageCaptioner] Active LLM provider does not support VLM — ` +
+            `captioning skipped for [${imageId}]. ` +
+            `Switch to Gemini, OpenAI (gpt-4o-mini+), or Anthropic to enable.`);
+        return;
+    }
+    // ── Step 2: Read file + size check ───────────────────────────────────────
+    if (!fs.existsSync(vaultPath)) {
+        debugLog(`[ImageCaptioner] Vault file not found: ${vaultPath}`);
+        return;
+    }
+    const fileBuffer = fs.readFileSync(vaultPath);
+    const fileSizeBytes = fileBuffer.length;
+    const mimeType = getMimeType(vaultPath);
+    // Detect active text provider to apply the correct size cap.
+    // We import getSettingSync lazily to avoid circular dependency issues.
+    const { getSettingSync } = await import("../storage/configStorage.js");
+    const textProvider = getSettingSync("text_provider", "gemini");
+    const maxBytes = textProvider === "anthropic" ? ANTHROPIC_MAX_BYTES : DEFAULT_MAX_BYTES;
+    if (fileSizeBytes > maxBytes) {
+        const limitMB = (maxBytes / 1024 / 1024).toFixed(0);
+        const actualMB = (fileSizeBytes / 1024 / 1024).toFixed(1);
+        console.warn(`[ImageCaptioner] Image [${imageId}] is ${actualMB}MB, exceeding ` +
+            `the ${textProvider} VLM limit (${limitMB}MB). Captioning skipped. ` +
+            (textProvider === "anthropic"
+                ? "Switch Embedding Provider to Gemini/OpenAI to caption larger images."
+                : "Consider resizing the image."));
+        return;
+    }
+    const imageBase64 = fileBuffer.toString("base64");
+    // ── Step 3: Generate caption via VLM ────────────────────────────────────
+    debugLog(`[ImageCaptioner] Captioning [${imageId}] via ${textProvider}…`);
+    const caption = await llm.generateImageDescription(imageBase64, mimeType, userContext);
+    if (!caption || caption.trim().length === 0) {
+        debugLog(`[ImageCaptioner] Empty caption returned for [${imageId}] — skipping storage.`);
+        return;
+    }
+    debugLog(`[ImageCaptioner] Caption generated for [${imageId}]: "${caption.slice(0, 80)}…"`);
+    // ── Step 4: Patch handoff visual_memory entry ─────────────────────────
+    await updateHandoffCaption(project, imageId, caption, vaultPath);
+    // ── Step 5: Persist as ledger entry (makes caption semantically searchable)
+    // NOTE: The ledger schema has no generic metadata column, so we embed the
+    // image context directly in the summary string for LLM-readable references.
+    const storage = await getStorage();
+    await storage.saveLedger({
+        project,
+        conversation_id: "vlm-captioner",
+        user_id: PRISM_USER_ID,
+        event_type: "learning",
+        summary: `[Visual Memory: ${imageId}]\n` +
+            `Path: ${vaultPath}\n` +
+            `User description: ${userContext}\n` +
+            `VLM Caption: ${caption}`,
+        keywords: [`image:${imageId}`, "visual_memory", "image_caption"],
+    });
+    // ── Step 6: Backfill embeddings (makes caption findable via vector search)
+    // ── Step 6: Embed the caption inline ────────────────────────────────
+    // We embed the caption directly here rather than calling backfillEmbeddingsHandler
+    // to avoid a circular import (imageCaptioner ↔ sessionMemoryHandlers).
+    // We already have getLLMProvider() in scope, so the embed cost is near-zero.
+    try {
+        const embedText = `[Visual Memory: ${imageId}] Description: ${userContext}. Caption: ${caption}`;
+        const embedding = await llm.generateEmbedding(embedText);
+        // Find the ledger entry we just saved and patch its embedding
+        const allEntries = await storage.getLedgerEntries({
+            project,
+            conversation_id: "vlm-captioner",
+        });
+        // Sort descending and take the most recent (the one we just inserted)
+        const latest = allEntries.sort((a, b) => new Date(b.created_at ?? 0).getTime() - new Date(a.created_at ?? 0).getTime())[0];
+        if (latest?.id) {
+            await storage.patchLedger(latest.id, { embedding: JSON.stringify(embedding) });
+            debugLog(`[ImageCaptioner] Caption embedded for ledger entry [${latest.id}].`);
+        }
+    }
+    catch (embedErr) {
+        // Non-fatal: caption still persists in the ledger as plain text and
+        // will be picked up by the next project-wide backfill sweep.
+        debugLog(`[ImageCaptioner] Embedding failed (will surface in next backfill): ${embedErr}`);
+    }
+    debugLog(`[ImageCaptioner] Pipeline complete for [${imageId}].`);
+}
+// ─── Handoff Patch ────────────────────────────────────────────────────────────
+/**
+ * Adds `caption` to the matching visual_memory entry inside the handoff JSON.
+ * Uses a read-modify-write because visual_memory is embedded in the handoff
+ * metadata JSON blob — there's no dedicated column to patch atomically.
+ *
+ * On version conflict (OCC), retries once with a fresh read. If both fail,
+ * logs and returns (the ledger entry still exists as a search fallback).
+ */
+async function updateHandoffCaption(project, imageId, caption, vaultPath) {
+    const storage = await getStorage();
+    for (let attempt = 1; attempt <= 2; attempt++) {
+        const context = await storage.loadContext(project, "quick", PRISM_USER_ID);
+        if (!context) {
+            debugLog(`[ImageCaptioner] No handoff context for "${project}" — skipping caption patch.`);
+            return;
+        }
+        const ctx = context;
+        const meta = ctx.metadata || {};
+        const vm = meta.visual_memory || [];
+        const entry = vm.find((e) => e.id === imageId);
+        if (!entry) {
+            debugLog(`[ImageCaptioner] Image [${imageId}] not found in visual_memory — skipping patch.`);
+            return;
+        }
+        // Mutate the entry in-memory, then save back
+        entry.caption = caption;
+        entry.caption_path = vaultPath;
+        entry.caption_at = new Date().toISOString();
+        const handoffUpdate = {
+            project,
+            user_id: PRISM_USER_ID,
+            metadata: meta,
+            last_summary: ctx.last_summary ?? null,
+            pending_todo: ctx.pending_todo ?? null,
+            active_decisions: ctx.active_decisions ?? null,
+            keywords: ctx.keywords ?? null,
+            key_context: ctx.key_context ?? null,
+            active_branch: ctx.active_branch ?? null,
+        };
+        const result = await storage.saveHandoff(handoffUpdate, ctx.version);
+        if (result.status !== "conflict") {
+            debugLog(`[ImageCaptioner] Handoff patched with caption for [${imageId}] (attempt ${attempt}).`);
+            return;
+        }
+        // OCC conflict — retry once with fresh version
+        debugLog(`[ImageCaptioner] OCC conflict patching [${imageId}], attempt ${attempt}. Retrying…`);
+    }
+    console.warn(`[ImageCaptioner] Could not patch handoff for [${imageId}] after 2 attempts. ` +
+        `Caption is still saved in the ledger and will surface via semantic search.`);
+}

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

@@ -0,0 +1,128 @@
+/**
+ * Anthropic Adapter (v4.5)
+ * ─────────────────────────────────────────────────────────────────────────────
+ * PURPOSE:
+ *   Implements LLMProvider using Anthropic's official @anthropic-ai/sdk.
+ *   Covers Claude 3.5 Sonnet, Claude 3 Haiku, Claude 3 Opus, etc.
+ *
+ * EMBEDDING LIMITATION:
+ *   Anthropic does NOT offer a native text embedding API.
+ *   Their official recommendation is Voyage AI (voyage-3, voyage-3-lite).
+ *   `generateEmbedding()` throws an explicit, actionable error rather than
+ *   silently returning garbage — the factory's auto-resolution logic means
+ *   this should never be called in practice (see factory.ts).
+ *
+ * VLM CAPABILITY:
+ *   Claude 3.5 Sonnet, Opus, and Haiku all support vision natively via the
+ *   Messages API `image` content block. This adapter implements
+ *   `generateImageDescription` (5MB base64 payload limit enforced in
+ *   imageCaptioner.ts before the API call reaches this adapter).
+ *
+ * FACTORY RESOLUTION:
+ *   When `text_provider = "anthropic"` and `embedding_provider = "auto"`,
+ *   the factory automatically routes embeddings to the Gemini adapter.
+ *   Users who want explicit control set `embedding_provider = "gemini"` or
+ *   `embedding_provider = "openai"` in the Mind Palace dashboard.
+ *
+ * CONFIG KEYS (Prism dashboard "AI Providers" tab):
+ *   anthropic_api_key  — Required. Claude API key (sk-ant-...)
+ *   anthropic_model    — Chat model (default: claude-3-5-sonnet-20241022)
+ *
+ * MODEL SUGGESTIONS:
+ *   claude-3-5-sonnet-20241022   — Best quality for compaction & summarization
+ *   claude-3-haiku-20240307      — Fastest & cheapest; good for briefings
+ *   claude-3-opus-20240229       — Most capable; use for complex fact merging
+ */
+import Anthropic from "@anthropic-ai/sdk";
+import { getSettingSync } from "../../../storage/configStorage.js";
+import { debugLog } from "../../logger.js";
+// ─── Constants ────────────────────────────────────────────────────────────────
+// Default to Claude 3.5 Sonnet — best quality/cost ratio for the tasks
+// Prism performs (compaction, briefing, fact merging, security scan).
+const DEFAULT_MODEL = "claude-3-5-sonnet-20241022";
+// Max output tokens for all Prism text-generation tasks.
+// 4096 is sufficient for compaction summaries; raise if needed.
+const MAX_TOKENS = 4096;
+export class AnthropicAdapter {
+    client;
+    constructor() {
+        const apiKey = getSettingSync("anthropic_api_key", process.env.ANTHROPIC_API_KEY ?? "");
+        if (!apiKey) {
+            throw new Error("AnthropicAdapter requires an API key. " +
+                "Set ANTHROPIC_API_KEY or configure it in the Mind Palace dashboard.");
+        }
+        this.client = new Anthropic({ apiKey });
+        debugLog("[AnthropicAdapter] Initialized");
+    }
+    // ─── Text Generation ─────────────────────────────────────────────────────
+    async generateText(prompt, systemInstruction) {
+        const model = getSettingSync("anthropic_model", DEFAULT_MODEL);
+        debugLog(`[AnthropicAdapter] generateText — model=${model}`);
+        // Anthropic's Messages API uses system as a top-level field (not a message role).
+        // This maps cleanly to LLMProvider's systemInstruction parameter.
+        const response = await this.client.messages.create({
+            model,
+            max_tokens: MAX_TOKENS,
+            ...(systemInstruction ? { system: systemInstruction } : {}),
+            messages: [{ role: "user", content: prompt }],
+        });
+        // Extract text from the first ContentBlock.
+        // Anthropic returns an array of content blocks; we only use text blocks.
+        const block = response.content[0];
+        if (!block || block.type !== "text") {
+            throw new Error(`[AnthropicAdapter] Unexpected response content type: ${block?.type ?? "empty"}`);
+        }
+        return block.text;
+    }
+    // ─── Embedding Generation (Not Supported) ────────────────────────────────
+    async generateEmbedding(_text) {
+        // This method should never be reached in normal operation:
+        //   - factory.ts auto-resolves embedding_provider away from "anthropic"
+        //   - The dashboard UI warns users if they select anthropic + auto
+        //
+        // If a user somehow bypasses the factory (e.g. by constructing this class
+        // directly in a test), they get a clear, actionable error rather than a
+        // silent zero-vector or crash.
+        throw new Error("AnthropicAdapter does not support text embeddings. " +
+            "Anthropic has no native embedding API. " +
+            "In the Mind Palace dashboard, set 'Embedding Provider' to Gemini or OpenAI/Ollama. " +
+            "When using Ollama locally, 'nomic-embed-text' is a free, high-quality option.");
+    }
+    // ─── Image Description (VLM) ─────────────────────────────────────────────
+    /**
+     * Describe an image using the Anthropic Messages API vision capability.
+     * Claude 3.5 Sonnet (and Haiku/Opus) accept `image` content blocks with a
+     * base64 `source`. imageCaptioner.ts enforces the 5MB payload limit before
+     * this method is ever called.
+     */
+    async generateImageDescription(imageBase64, mimeType, context) {
+        const model = getSettingSync("anthropic_model", DEFAULT_MODEL);
+        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.";
+        debugLog(`[AnthropicAdapter] generateImageDescription — model=${model}`);
+        const response = await this.client.messages.create({
+            model,
+            max_tokens: 1024,
+            messages: [{
+                    role: "user",
+                    content: [
+                        {
+                            type: "image",
+                            source: {
+                                type: "base64",
+                                // Anthropic requires the media_type to be a specific union type;
+                                // cast to `any` since mimeType is validated to be a supported
+                                // image format by imageCaptioner.ts before reaching here.
+                                media_type: mimeType,
+                                data: imageBase64,
+                            },
+                        },
+                        { type: "text", text: prompt },
+                    ],
+                }],
+        });
+        const block = response.content[0];
+        return block?.type === "text" ? block.text : "";
+    }
+}

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

@@ -0,0 +1,152 @@
+/**
+ * Gemini Adapter (v4.5)
+ * ─────────────────────────────────────────────────────────────────────────────
+ * PURPOSE:
+ *   Implements LLMProvider using Google's @google/generative-ai SDK.
+ *   This is Prism's DEFAULT adapter and the result of consolidating LLM logic
+ *   that was previously scattered across 6 different files into a single,
+ *   well-guarded implementation.
+ *
+ * BEFORE v4.4 (scattered):
+ *   - src/utils/embeddingApi.ts   → generateEmbedding logic
+ *   - src/utils/googleAi.ts       → analyzePaperWithGemini text generation
+ *   - compactionHandler.ts        → direct new GoogleGenerativeAI() instantiation
+ *   - factMerger.ts               → direct new GoogleGenerativeAI() instantiation
+ *   - briefing.ts                 → direct new GoogleGenerativeAI() instantiation
+ *   - healthCheck.ts              → direct new GoogleGenerativeAI() instantiation
+ *
+ * AFTER v4.4 (consolidated here):
+ *   All embedding guards, model constants, and SDK calls live in one place.
+ *   All consumers call getLLMProvider() instead of touching the SDK directly.
+ *
+ * MODELS:
+ *   Text:      gemini-2.0-flash       — fast, matches all prior hardcoded usages
+ *   Embedding: gemini-embedding-001   — replaced text-embedding-004 (deprecated 2026-01)
+ *              Uses Matryoshka Representation Learning (MRL) at 768 dims.
+ *              Requires v1beta API endpoint (NOT v1).
+ *
+ * SDK NOTE:
+ *   Still using @google/generative-ai@^0.24.1 (NOT the newer @google/genai).
+ *   This is intentional — upgrading the SDK at the same time as introducing
+ *   the abstraction layer would conflate two sources of behavioral change.
+ *   SDK upgrade is a separate, future task.
+ */
+import { GoogleGenerativeAI, TaskType, } from "@google/generative-ai";
+import { GOOGLE_API_KEY } from "../../../config.js";
+import { debugLog } from "../../logger.js";
+// ─── Model Constants ──────────────────────────────────────────────────────────
+// Defined as constants (not hardcoded strings) so external reviewers can see
+// all model choices at a glance, and future changes only need one edit.
+const TEXT_MODEL = "gemini-2.0-flash"; // chat/instruction-following model
+const EMBEDDING_MODEL = "gemini-embedding-001"; // vector embedding model (MRL-enabled)
+const EMBEDDING_DIMS = 768; // fixed output dims — must match DB schema
+// ─── Embedding Truncation Constants ──────────────────────────────────────────
+// gemini-embedding-001 supports up to ~2048 tokens.
+// We use a character-based limit (not token-based) because:
+//   1. JS string.length returns UTF-16 code units, not tokens
+//   2. Token counting would require an extra API call or tokenizer dependency
+//   3. 8000 chars ≈ 1500-2000 tokens for typical prose — safely under the limit
+// The word-boundary snap prevents splitting mid-word or mid-surrogate-pair.
+const MAX_EMBEDDING_CHARS = 8000;
+export class GeminiAdapter {
+    // The underlying Google SDK client — initialized once per adapter instance.
+    // The factory ensures only one adapter instance exists per process.
+    ai;
+    constructor() {
+        // Fail fast at construction time rather than at the first API call.
+        // The factory catches this error and falls back gracefully.
+        if (!GOOGLE_API_KEY) {
+            throw new Error("GeminiAdapter requires GOOGLE_API_KEY. " +
+                "Set this environment variable to enable LLM features.");
+        }
+        this.ai = new GoogleGenerativeAI(GOOGLE_API_KEY);
+    }
+    // ─── Text Generation ─────────────────────────────────────────────────────
+    async generateText(prompt, systemInstruction) {
+        // getGenerativeModel() is lightweight — it just binds model name + options.
+        // The HTTP call happens inside generateContent() below.
+        const model = this.ai.getGenerativeModel({
+            model: TEXT_MODEL,
+            // Only spread systemInstruction if provided — avoids sending an empty field
+            // which could confuse some model versions.
+            ...(systemInstruction ? { systemInstruction } : {}),
+        });
+        const result = await model.generateContent(prompt);
+        // result.response.text() extracts the first candidate's text content.
+        // This matches the prior behavior in all 6 migrated call sites.
+        return result.response.text();
+    }
+    // ─── Embedding Generation ────────────────────────────────────────────────
+    async generateEmbedding(text) {
+        // Guard: empty string would produce a useless/degenerate embedding.
+        // Better to fail loudly here than store a zero-vector in the DB.
+        if (!text || !text.trim()) {
+            throw new Error("Cannot generate embedding for empty text.");
+        }
+        // ── Truncation Guard ───────────────────────────────────────────────────
+        // gemini-embedding-001 has a ~2048 token context window.
+        // Long session summaries (esp. code-heavy ones) can easily exceed this.
+        // We truncate proactively rather than let the API return a 400 error.
+        let inputText = text;
+        if (inputText.length > MAX_EMBEDDING_CHARS) {
+            debugLog(`[GeminiAdapter] Embedding input truncated from ${inputText.length}` +
+                ` to ~${MAX_EMBEDDING_CHARS} chars (word-safe)`);
+            // Step 1: hard cut at the character limit
+            inputText = inputText.substring(0, MAX_EMBEDDING_CHARS);
+            // Step 2: snap back to the last word boundary to avoid:
+            //   a) splitting a word mid-character (readability)
+            //   b) splitting a UTF-16 surrogate pair (correctness)
+            const lastSpace = inputText.lastIndexOf(" ");
+            if (lastSpace > 0) {
+                inputText = inputText.substring(0, lastSpace);
+            }
+        }
+        // ── API Version Pin ────────────────────────────────────────────────────
+        // gemini-embedding-001 is ONLY available on the v1beta endpoint.
+        // Using the default v1 endpoint returns a 404/model-not-found error.
+        // This was a known breaking change when migrating from text-embedding-004.
+        const model = this.ai.getGenerativeModel({ model: EMBEDDING_MODEL }, { apiVersion: "v1beta" });
+        debugLog(`[GeminiAdapter] Generating ${EMBEDDING_DIMS}-dim embedding` +
+            ` for ${inputText.length} chars`);
+        // ── Request Construction ───────────────────────────────────────────────
+        // outputDimensionality is a valid API field (Matryoshka truncation) but
+        // lags in the TypeScript type definitions as of @google/generative-ai@0.24.1.
+        // We use a type assertion on the full object rather than a spread-cast hack
+        // to keep the code readable while satisfying tsc.
+        const request = {
+            content: {
+                role: "user", // "user" role is required by the embedding API
+                parts: [{ text: inputText }],
+            },
+            taskType: TaskType.SEMANTIC_SIMILARITY, // optimizes for cosine similarity search
+            outputDimensionality: EMBEDDING_DIMS, // MRL truncation to 768 dims
+        };
+        const result = await model.embedContent(request);
+        const values = result.embedding.values;
+        // ── Dimension Enforcement ──────────────────────────────────────────────
+        // Hard check: throwing here is better than silently writing a wrong-size
+        // vector to the DB, which would corrupt the pgvector/sqlite-vec index.
+        if (!Array.isArray(values) || values.length !== EMBEDDING_DIMS) {
+            throw new Error(`Embedding dimension mismatch: expected ${EMBEDDING_DIMS},` +
+                ` got ${values?.length ?? "unknown"}`);
+        }
+        return values;
+    }
+    // ─── Image Description (VLM) ─────────────────────────────────────────────
+    /**
+     * Describe an image using Gemini's native multimodal capability.
+     * gemini-2.0-flash handles images alongside text — the same model used for
+     * text generation, so no extra SDK initialization is needed.
+     */
+    async generateImageDescription(imageBase64, mimeType, context) {
+        const model = this.ai.getGenerativeModel({ model: TEXT_MODEL });
+        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 result = await model.generateContent([
+            { inlineData: { data: imageBase64, mimeType } },
+            prompt,
+        ]);
+        return result.response.text();
+    }
+}