lynkr 4.1.0 → 4.2.1

package/docs/LOCAL_EMBEDDINGS_PLAN.md

@@ -1,1024 +0,0 @@
-# Local Embeddings Support Plan (Ollama + llama.cpp)
-
-**Goal:** Add local embeddings support for Cursor IDE's @Codebase semantic search using Ollama and llama.cpp
-
-**Current State:**
-- Embeddings only work via OpenRouter or OpenAI (cloud-based)
-- Code location: `src/api/openai-router.js` lines 361-412
-- Hardcoded to use OpenRouter/OpenAI endpoints only
-
-**Target State:**
-- Support Ollama for embeddings (local, privacy-first)
-- Support llama.cpp for embeddings (local, GGUF models)
-- Allow users to run 100% local: Ollama chat + Ollama embeddings
-- Fallback to OpenRouter/OpenAI if local not configured
-
----
-
-## Architecture Overview
-
-### Current Flow
-```
-Cursor @Codebase request
-    ↓
-Lynkr /v1/embeddings endpoint
-    ↓
-Check: OpenRouter? → Yes → OpenRouter API
-           ↓ No
-    Check: OpenAI? → Yes → OpenAI API
-           ↓ No
-    Return 501 (Not Configured)
-```
-
-### New Flow
-```
-Cursor @Codebase request
-    ↓
-Lynkr /v1/embeddings endpoint
-    ↓
-determineEmbeddingProvider()
-    ↓
-    ├─→ Ollama → /api/embeddings (custom format)
-    ├─→ llama.cpp → /embeddings (OpenAI-compatible)
-    ├─→ OpenRouter → /api/v1/embeddings (existing)
-    └─→ OpenAI → /v1/embeddings (existing)
-```
-
----
-
-## API Format Differences
-
-### 1. Ollama Embeddings API
-
-**Endpoint:** `http://localhost:11434/api/embeddings`
-
-**Request Format:**
-```json
-{
-  "model": "nomic-embed-text",
-  "prompt": "The quick brown fox"
-}
-```
-
-**Response Format:**
-```json
-{
-  "embedding": [0.123, 0.456, ...],
-  "model": "nomic-embed-text"
-}
-```
-
-**Key Differences:**
-- ❌ Does NOT support batch inputs (only single prompt)
-- ❌ No usage statistics returned
-- ❌ Different response structure
-- ✅ Need to convert OpenAI format → Ollama format
-
-### 2. llama.cpp Embeddings API
-
-**Endpoint:** `http://localhost:8080/embeddings`
-
-**Request Format (OpenAI-compatible):**
-```json
-{
-  "input": "The quick brown fox",
-  "encoding_format": "float"
-}
-```
-
-**Response Format (OpenAI-compatible):**
-```json
-{
-  "object": "list",
-  "data": [
-    {
-      "object": "embedding",
-      "embedding": [0.123, 0.456, ...],
-      "index": 0
-    }
-  ],
-  "model": "loaded-model",
-  "usage": {
-    "prompt_tokens": 5,
-    "total_tokens": 5
-  }
-}
-```
-
-**Key Differences:**
-- ✅ OpenAI-compatible format
-- ✅ Supports batch inputs (array of strings)
-- ✅ Returns usage statistics
-- ✅ No conversion needed
-
-### 3. OpenRouter/OpenAI (Existing)
-
-Already implemented, no changes needed.
-
----
-
-## Implementation Plan
-
-### Phase 1: Configuration (30 minutes)
-
-#### 1.1 Add Environment Variables
-
-**File:** `src/config/index.js`
-
-**Add after line 85 (OpenRouter config):**
-```javascript
-// Ollama embeddings configuration
-const ollamaEmbeddingsEndpoint = process.env.OLLAMA_EMBEDDINGS_ENDPOINT ??
-  `${ollamaEndpoint}/api/embeddings`;
-const ollamaEmbeddingsModel = process.env.OLLAMA_EMBEDDINGS_MODEL ?? "nomic-embed-text";
-
-// llama.cpp embeddings configuration
-const llamacppEmbeddingsEndpoint = process.env.LLAMACPP_EMBEDDINGS_ENDPOINT ??
-  `${llamacppEndpoint}/embeddings`;
-```
-
-**Update config export (line 434-436):**
-```javascript
-ollama: {
-  endpoint: ollamaEndpoint,
-  model: ollamaModel,
-  timeout: Number.isNaN(ollamaTimeout) ? 120000 : ollamaTimeout,
-  // NEW: Embeddings config
-  embeddingsEndpoint: ollamaEmbeddingsEndpoint,
-  embeddingsModel: ollamaEmbeddingsModel,
-},
-```
-
-**Update llamacpp config (line 454-459):**
-```javascript
-llamacpp: {
-  endpoint: llamacppEndpoint,
-  model: llamacppModel,
-  timeout: Number.isNaN(llamacppTimeout) ? 120000 : llamacppTimeout,
-  apiKey: llamacppApiKey,
-  // NEW: Embeddings config
-  embeddingsEndpoint: llamacppEmbeddingsEndpoint,
-},
-```
-
-#### 1.2 Document in .env.example
-
-**File:** `.env.example`
-
-**Add after Ollama section (after line 28):**
-```bash
-# Ollama embeddings configuration
-# Embedding models for @Codebase semantic search (local, privacy-first)
-# Popular models:
-#   - nomic-embed-text (768 dim, 137M params, best all-around)
-#   - mxbai-embed-large (1024 dim, 335M params, higher quality)
-#   - all-minilm (384 dim, 23M params, fastest/smallest)
-#
-# Pull model: ollama pull nomic-embed-text
-# OLLAMA_EMBEDDINGS_MODEL=nomic-embed-text
-# OLLAMA_EMBEDDINGS_ENDPOINT=http://localhost:11434/api/embeddings
-```
-
-**Add after llama.cpp section (after line 162):**
-```bash
-# llama.cpp embeddings configuration
-# Requires an embedding model loaded in llama.cpp server
-# Start with: ./llama-server -m nomic-embed-text-v1.5.Q4_K_M.gguf --port 8080 --embedding
-# LLAMACPP_EMBEDDINGS_ENDPOINT=http://localhost:8080/embeddings
-```
-
----
-
-### Phase 2: Provider Detection (20 minutes)
-
-#### 2.1 Create Embedding Provider Router
-
-**File:** `src/api/openai-router.js`
-
-**Replace lines 361-375 with:**
-```javascript
-// Determine which provider to use for embeddings
-// Priority: Explicit request model > Configured embeddings > Same as chat provider > Fallback
-const embeddingConfig = determineEmbeddingProvider(model);
-
-if (!embeddingConfig) {
-  logger.warn("No embedding provider configured");
-  return res.status(501).json({
-    error: {
-      message: "Embeddings not configured. Set up one of: OPENROUTER_API_KEY, OPENAI_API_KEY, OLLAMA_EMBEDDINGS_MODEL, or LLAMACPP_EMBEDDINGS_ENDPOINT",
-      type: "not_implemented",
-      code: "embeddings_not_configured"
-    }
-  });
-}
-
-// Route to appropriate provider
-try {
-  let embeddingResponse;
-
-  switch (embeddingConfig.provider) {
-    case "ollama":
-      embeddingResponse = await generateOllamaEmbeddings(inputs, embeddingConfig);
-      break;
-
-    case "llamacpp":
-      embeddingResponse = await generateLlamaCppEmbeddings(inputs, embeddingConfig);
-      break;
-
-    case "openrouter":
-      embeddingResponse = await generateOpenRouterEmbeddings(inputs, embeddingConfig);
-      break;
-
-    case "openai":
-      embeddingResponse = await generateOpenAIEmbeddings(inputs, embeddingConfig);
-      break;
-
-    default:
-      throw new Error(`Unsupported embedding provider: ${embeddingConfig.provider}`);
-  }
-
-  logger.info({
-    provider: embeddingConfig.provider,
-    model: embeddingConfig.model,
-    duration: Date.now() - startTime,
-    embeddingCount: embeddingResponse.data?.length || 0,
-  }, "=== EMBEDDINGS RESPONSE ===");
-
-  res.json(embeddingResponse);
-
-} catch (error) {
-  logger.error({
-    error: error.message,
-    provider: embeddingConfig.provider,
-  }, "Embeddings generation failed");
-
-  res.status(500).json({
-    error: {
-      message: error.message || "Embeddings generation failed",
-      type: "server_error",
-      code: "embeddings_error"
-    }
-  });
-}
-```
-
-#### 2.2 Add Provider Detection Function
-
-**File:** `src/api/openai-router.js`
-
-**Add before the POST /embeddings handler:**
-```javascript
-/**
- * Determine which provider to use for embeddings
- * Priority:
- *   1. Explicit EMBEDDINGS_PROVIDER env var
- *   2. Same provider as MODEL_PROVIDER (if it supports embeddings)
- *   3. First available: OpenRouter > OpenAI > Ollama > llama.cpp
- */
-function determineEmbeddingProvider(requestedModel = null) {
-  const explicitProvider = process.env.EMBEDDINGS_PROVIDER?.trim();
-
-  // Priority 1: Explicit configuration
-  if (explicitProvider) {
-    switch (explicitProvider) {
-      case "ollama":
-        if (!config.ollama?.embeddingsModel) {
-          logger.warn("EMBEDDINGS_PROVIDER=ollama but OLLAMA_EMBEDDINGS_MODEL not set");
-          return null;
-        }
-        return {
-          provider: "ollama",
-          model: requestedModel || config.ollama.embeddingsModel,
-          endpoint: config.ollama.embeddingsEndpoint
-        };
-
-      case "llamacpp":
-        if (!config.llamacpp?.embeddingsEndpoint) {
-          logger.warn("EMBEDDINGS_PROVIDER=llamacpp but LLAMACPP_EMBEDDINGS_ENDPOINT not set");
-          return null;
-        }
-        return {
-          provider: "llamacpp",
-          model: requestedModel || "default",
-          endpoint: config.llamacpp.embeddingsEndpoint
-        };
-
-      case "openrouter":
-        if (!config.openrouter?.apiKey) {
-          logger.warn("EMBEDDINGS_PROVIDER=openrouter but OPENROUTER_API_KEY not set");
-          return null;
-        }
-        return {
-          provider: "openrouter",
-          model: requestedModel || config.openrouter.embeddingsModel,
-          apiKey: config.openrouter.apiKey,
-          endpoint: "https://openrouter.ai/api/v1/embeddings"
-        };
-
-      case "openai":
-        if (!config.openai?.apiKey) {
-          logger.warn("EMBEDDINGS_PROVIDER=openai but OPENAI_API_KEY not set");
-          return null;
-        }
-        return {
-          provider: "openai",
-          model: requestedModel || "text-embedding-ada-002",
-          apiKey: config.openai.apiKey,
-          endpoint: "https://api.openai.com/v1/embeddings"
-        };
-    }
-  }
-
-  // Priority 2: Same as chat provider (if supported)
-  const chatProvider = config.modelProvider?.type;
-
-  if (chatProvider === "openrouter" && config.openrouter?.apiKey) {
-    return {
-      provider: "openrouter",
-      model: requestedModel || config.openrouter.embeddingsModel,
-      apiKey: config.openrouter.apiKey,
-      endpoint: "https://openrouter.ai/api/v1/embeddings"
-    };
-  }
-
-  if (chatProvider === "ollama" && config.ollama?.embeddingsModel) {
-    return {
-      provider: "ollama",
-      model: requestedModel || config.ollama.embeddingsModel,
-      endpoint: config.ollama.embeddingsEndpoint
-    };
-  }
-
-  if (chatProvider === "llamacpp" && config.llamacpp?.embeddingsEndpoint) {
-    return {
-      provider: "llamacpp",
-      model: requestedModel || "default",
-      endpoint: config.llamacpp.embeddingsEndpoint
-    };
-  }
-
-  // Priority 3: First available provider
-  if (config.openrouter?.apiKey) {
-    return {
-      provider: "openrouter",
-      model: requestedModel || config.openrouter.embeddingsModel,
-      apiKey: config.openrouter.apiKey,
-      endpoint: "https://openrouter.ai/api/v1/embeddings"
-    };
-  }
-
-  if (config.openai?.apiKey) {
-    return {
-      provider: "openai",
-      model: requestedModel || "text-embedding-ada-002",
-      apiKey: config.openai.apiKey,
-      endpoint: "https://api.openai.com/v1/embeddings"
-    };
-  }
-
-  if (config.ollama?.embeddingsModel) {
-    return {
-      provider: "ollama",
-      model: requestedModel || config.ollama.embeddingsModel,
-      endpoint: config.ollama.embeddingsEndpoint
-    };
-  }
-
-  if (config.llamacpp?.embeddingsEndpoint) {
-    return {
-      provider: "llamacpp",
-      model: requestedModel || "default",
-      endpoint: config.llamacpp.embeddingsEndpoint
-    };
-  }
-
-  return null; // No provider available
-}
-```
-
----
-
-### Phase 3: Ollama Implementation (45 minutes)
-
-#### 3.1 Add Ollama Embeddings Function
-
-**File:** `src/api/openai-router.js`
-
-**Add after determineEmbeddingProvider:**
-```javascript
-/**
- * Generate embeddings using Ollama
- * Note: Ollama only supports single prompt, not batch
- */
-async function generateOllamaEmbeddings(inputs, config) {
-  const { model, endpoint } = config;
-
-  logger.info({
-    model,
-    endpoint,
-    inputCount: inputs.length
-  }, "Generating embeddings with Ollama");
-
-  // Ollama doesn't support batch, so we need to process one by one
-  const embeddings = [];
-
-  for (let i = 0; i < inputs.length; i++) {
-    const input = inputs[i];
-
-    try {
-      const response = await fetch(endpoint, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json"
-        },
-        body: JSON.stringify({
-          model: model,
-          prompt: input
-        })
-      });
-
-      if (!response.ok) {
-        const errorText = await response.text();
-        throw new Error(`Ollama embeddings error (${response.status}): ${errorText}`);
-      }
-
-      const data = await response.json();
-
-      embeddings.push({
-        object: "embedding",
-        embedding: data.embedding,
-        index: i
-      });
-
-    } catch (error) {
-      logger.error({
-        error: error.message,
-        input: input.substring(0, 100),
-        index: i
-      }, "Failed to generate Ollama embedding");
-      throw error;
-    }
-  }
-
-  // Convert to OpenAI format
-  return {
-    object: "list",
-    data: embeddings,
-    model: model,
-    usage: {
-      prompt_tokens: 0, // Ollama doesn't provide this
-      total_tokens: 0
-    }
-  };
-}
-```
-
----
-
-### Phase 4: llama.cpp Implementation (20 minutes)
-
-#### 4.1 Add llama.cpp Embeddings Function
-
-**File:** `src/api/openai-router.js`
-
-**Add after generateOllamaEmbeddings:**
-```javascript
-/**
- * Generate embeddings using llama.cpp
- * llama.cpp uses OpenAI-compatible format, so minimal conversion needed
- */
-async function generateLlamaCppEmbeddings(inputs, config) {
-  const { model, endpoint } = config;
-
-  logger.info({
-    model,
-    endpoint,
-    inputCount: inputs.length
-  }, "Generating embeddings with llama.cpp");
-
-  try {
-    const response = await fetch(endpoint, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json"
-      },
-      body: JSON.stringify({
-        input: inputs, // llama.cpp supports batch
-        encoding_format: "float"
-      })
-    });
-
-    if (!response.ok) {
-      const errorText = await response.text();
-      throw new Error(`llama.cpp embeddings error (${response.status}): ${errorText}`);
-    }
-
-    const data = await response.json();
-
-    // llama.cpp returns OpenAI-compatible format, but ensure consistency
-    return {
-      object: "list",
-      data: data.data || [],
-      model: model || data.model || "default",
-      usage: data.usage || {
-        prompt_tokens: 0,
-        total_tokens: 0
-      }
-    };
-
-  } catch (error) {
-    logger.error({
-      error: error.message,
-      endpoint
-    }, "Failed to generate llama.cpp embeddings");
-    throw error;
-  }
-}
-```
-
----
-
-### Phase 5: Refactor Existing Providers (15 minutes)
-
-#### 5.1 Extract OpenRouter Function
-
-**File:** `src/api/openai-router.js`
-
-**Add after generateLlamaCppEmbeddings:**
-```javascript
-/**
- * Generate embeddings using OpenRouter
- */
-async function generateOpenRouterEmbeddings(inputs, config) {
-  const { model, apiKey, endpoint } = config;
-
-  logger.info({
-    model,
-    inputCount: inputs.length
-  }, "Generating embeddings with OpenRouter");
-
-  const response = await fetch(endpoint, {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      "Authorization": `Bearer ${apiKey}`,
-      "HTTP-Referer": "https://github.com/vishalveerareddy123/Lynkr",
-      "X-Title": "Lynkr"
-    },
-    body: JSON.stringify({
-      model: model,
-      input: inputs,
-      encoding_format: "float"
-    })
-  });
-
-  if (!response.ok) {
-    const errorText = await response.text();
-    throw new Error(`OpenRouter embeddings error (${response.status}): ${errorText}`);
-  }
-
-  return await response.json();
-}
-
-/**
- * Generate embeddings using OpenAI
- */
-async function generateOpenAIEmbeddings(inputs, config) {
-  const { model, apiKey, endpoint } = config;
-
-  logger.info({
-    model,
-    inputCount: inputs.length
-  }, "Generating embeddings with OpenAI");
-
-  const response = await fetch(endpoint, {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      "Authorization": `Bearer ${apiKey}`
-    },
-    body: JSON.stringify({
-      model: model,
-      input: inputs,
-      encoding_format: "float"
-    })
-  });
-
-  if (!response.ok) {
-    const errorText = await response.text();
-    throw new Error(`OpenAI embeddings error (${response.status}): ${errorText}`);
-  }
-
-  return await response.json();
-}
-```
-
----
-
-### Phase 6: Update Documentation (20 minutes)
-
-#### 6.1 Update .env.example
-
-**Already covered in Phase 1.2**
-
-#### 6.2 Update README.md Cursor Section
-
-**File:** `README.md`
-
-**Update embeddings section (around line 1870):**
-```markdown
-### Enabling @Codebase Semantic Search (Optional)
-
-For Cursor's @Codebase semantic search, you need embeddings support.
-
-**⚡ Already using OpenRouter? You're all set!**
-
-If you configured `MODEL_PROVIDER=openrouter`, embeddings **work automatically** with the same `OPENROUTER_API_KEY` - no additional setup needed. OpenRouter handles both chat completions AND embeddings with one key.
-
-**🔧 Using a different provider? Choose your embeddings source:**
-
-You have 4 options, listed from most private to least:
-
-**Option A: Ollama (100% Local, FREE)**
-```bash
-# Install Ollama and pull embedding model
-ollama pull nomic-embed-text
-
-# Add to .env
-OLLAMA_EMBEDDINGS_MODEL=nomic-embed-text
-
-# That's it! Works with any chat provider (Databricks, Bedrock, etc.)
-# Cost: FREE, Privacy: 100% local, Quality: Good
-```
-
-**Option B: llama.cpp (100% Local, FREE)**
-```bash
-# Download embedding model (GGUF format)
-# e.g., nomic-embed-text-v1.5.Q4_K_M.gguf
-
-# Start llama.cpp with embedding support
-./llama-server -m nomic-embed-text-v1.5.Q4_K_M.gguf --port 8080 --embedding
-
-# Add to .env
-LLAMACPP_EMBEDDINGS_ENDPOINT=http://localhost:8080/embeddings
-
-# Cost: FREE, Privacy: 100% local, Quality: Good
-```
-
-**Option C: OpenRouter (Cloud, Cheapest)**
-```bash
-# Add to .env (if not already there)
-OPENROUTER_API_KEY=sk-or-v1-your-key-here
-
-# Optional: Specify embedding model
-OPENROUTER_EMBEDDINGS_MODEL=openai/text-embedding-3-small
-
-# Cost: $0.02 per 1M tokens (~$0.01-0.10/month), Privacy: Cloud, Quality: Excellent
-```
-
-**Option D: OpenAI Direct (Cloud)**
-```bash
-# Add to .env
-OPENAI_API_KEY=sk-your-key-here
-
-# Cost: $0.10 per 1M tokens, Privacy: Cloud, Quality: Excellent
-```
-
-**Restart Lynkr**, and @Codebase will work!
-```
-
-#### 6.3 Add Embedding Models Guide
-
-**File:** `README.md`
-
-**Add new section after Cursor setup:**
-```markdown
-### Embedding Models Guide
-
-Different embedding models have different characteristics:
-
-| Model | Provider | Size | Dimensions | Quality | Speed | Privacy |
-|-------|----------|------|------------|---------|-------|---------|
-| **nomic-embed-text** | Ollama/llama.cpp | 137M | 768 | ⭐⭐⭐⭐ | Fast | 100% local |
-| **mxbai-embed-large** | Ollama | 335M | 1024 | ⭐⭐⭐⭐⭐ | Medium | 100% local |
-| **all-minilm** | Ollama | 23M | 384 | ⭐⭐⭐ | Fastest | 100% local |
-| **text-embedding-3-small** | OpenRouter/OpenAI | - | 1536 | ⭐⭐⭐⭐⭐ | Fast | Cloud |
-| **text-embedding-3-large** | OpenRouter/OpenAI | - | 3072 | ⭐⭐⭐⭐⭐ | Medium | Cloud |
-| **text-embedding-ada-002** | OpenRouter/OpenAI | - | 1536 | ⭐⭐⭐⭐ | Fast | Cloud |
-| **voyage-code-2** | OpenRouter | - | 1536 | ⭐⭐⭐⭐⭐ | Medium | Cloud |
-
-**Recommendations:**
-- **Best for privacy**: `nomic-embed-text` (Ollama, 100% local, free)
-- **Best for quality**: `text-embedding-3-large` (OpenRouter, $0.13/1M tokens)
-- **Best for speed**: `all-minilm` (Ollama, 100% local, free, fastest)
-- **Best balance**: `text-embedding-3-small` (OpenRouter, $0.02/1M tokens)
-- **Best for code**: `voyage-code-2` (OpenRouter, $0.12/1M tokens)
-
-**Setup examples:**
-
-```bash
-# Privacy-first: 100% local
-MODEL_PROVIDER=ollama
-OLLAMA_MODEL=qwen2.5-coder:latest
-OLLAMA_EMBEDDINGS_MODEL=nomic-embed-text
-
-# Quality-first: Best models
-MODEL_PROVIDER=openrouter
-OPENROUTER_MODEL=anthropic/claude-3.5-sonnet
-OPENROUTER_EMBEDDINGS_MODEL=text-embedding-3-large
-
-# Cost-optimized: Cheapest cloud
-MODEL_PROVIDER=openrouter
-OPENROUTER_MODEL=openai/gpt-4o-mini
-OPENROUTER_EMBEDDINGS_MODEL=openai/text-embedding-3-small
-
-# Hybrid: Local chat, cloud embeddings
-MODEL_PROVIDER=ollama
-OLLAMA_MODEL=qwen2.5-coder:latest
-OPENROUTER_API_KEY=sk-or-v1-...
-OPENROUTER_EMBEDDINGS_MODEL=openai/text-embedding-3-small
-```
-```
-
----
-
-### Phase 7: Testing (30 minutes)
-
-#### 7.1 Update Test File
-
-**File:** `test/cursor-integration.test.js`
-
-**Add new test suite at the end (before closing}):**
-```javascript
-describe("Local Embeddings Support", () => {
-  it("should detect Ollama as embedding provider", () => {
-    process.env.MODEL_PROVIDER = "ollama";
-    process.env.OLLAMA_EMBEDDINGS_MODEL = "nomic-embed-text";
-    delete require.cache[require.resolve("../src/config")];
-    const config = require("../src/config");
-
-    assert.strictEqual(config.ollama.embeddingsModel, "nomic-embed-text");
-  });
-
-  it("should detect llama.cpp as embedding provider", () => {
-    process.env.MODEL_PROVIDER = "llamacpp";
-    process.env.LLAMACPP_EMBEDDINGS_ENDPOINT = "http://localhost:8080/embeddings";
-    delete require.cache[require.resolve("../src/config")];
-    const config = require("../src/config");
-
-    assert.strictEqual(config.llamacpp.embeddingsEndpoint, "http://localhost:8080/embeddings");
-  });
-
-  it("should prioritize explicit EMBEDDINGS_PROVIDER", () => {
-    process.env.MODEL_PROVIDER = "databricks";
-    process.env.EMBEDDINGS_PROVIDER = "ollama";
-    process.env.OLLAMA_EMBEDDINGS_MODEL = "nomic-embed-text";
-
-    delete require.cache[require.resolve("../src/config")];
-    delete require.cache[require.resolve("../src/api/openai-router")];
-
-    const config = require("../src/config");
-    assert.strictEqual(config.modelProvider.type, "databricks");
-    assert.strictEqual(config.ollama.embeddingsModel, "nomic-embed-text");
-  });
-
-  it("should default to same provider if it supports embeddings", () => {
-    process.env.MODEL_PROVIDER = "openrouter";
-    process.env.OPENROUTER_API_KEY = "sk-test";
-    process.env.OPENROUTER_EMBEDDINGS_MODEL = "text-embedding-3-small";
-    delete process.env.EMBEDDINGS_PROVIDER;
-
-    delete require.cache[require.resolve("../src/config")];
-    const config = require("../src/config");
-
-    assert.strictEqual(config.modelProvider.type, "openrouter");
-    assert.strictEqual(config.openrouter.embeddingsModel, "text-embedding-3-small");
-  });
-});
-```
-
-#### 7.2 Manual Testing Checklist
-
-**Test Ollama embeddings:**
-```bash
-# 1. Pull embedding model
-ollama pull nomic-embed-text
-
-# 2. Configure .env
-MODEL_PROVIDER=ollama
-OLLAMA_EMBEDDINGS_MODEL=nomic-embed-text
-
-# 3. Start Lynkr
-lynkr start
-
-# 4. Test embeddings endpoint
-curl -X POST http://localhost:8080/v1/embeddings \
-  -H "Content-Type: application/json" \
-  -d '{"input": "test embedding"}'
-
-# Expected: Returns embedding vector
-```
-
-**Test llama.cpp embeddings:**
-```bash
-# 1. Download and start llama.cpp
-./llama-server -m nomic-embed-text-v1.5.Q4_K_M.gguf --port 8080 --embedding
-
-# 2. Configure .env
-MODEL_PROVIDER=databricks
-LLAMACPP_EMBEDDINGS_ENDPOINT=http://localhost:8080/embeddings
-
-# 3. Test embeddings
-curl -X POST http://localhost:8080/v1/embeddings \
-  -H "Content-Type: application/json" \
-  -d '{"input": "test embedding"}'
-```
-
-**Test in Cursor:**
-```bash
-# 1. Configure Cursor to point to Lynkr
-# Settings → Models → OpenAI API
-# Base URL: http://localhost:8080/v1
-
-# 2. Try @Codebase search
-# In Cursor chat: "@Codebase where is authentication handled?"
-
-# Expected: Semantic search results
-```
-
----
-
-## File Changes Summary
-
-| File | Changes | Lines | Complexity |
-|------|---------|-------|------------|
-| `src/config/index.js` | Add embeddings config | +10 | Easy |
-| `src/api/openai-router.js` | Add provider detection + implementations | +400 | Medium |
-| `.env.example` | Document embedding models | +30 | Easy |
-| `README.md` | Update Cursor section | +100 | Easy |
-| `test/cursor-integration.test.js` | Add local embeddings tests | +50 | Easy |
-
-**Total:** ~590 lines of code
-
----
-
-## Complexity & Effort Estimates
-
-| Phase | Description | Complexity | Effort | Value |
-|-------|-------------|------------|--------|-------|
-| 1 | Configuration | 2/10 | 30 min | Required |
-| 2 | Provider Detection | 4/10 | 20 min | Core |
-| 3 | Ollama Implementation | 6/10 | 45 min | High |
-| 4 | llama.cpp Implementation | 3/10 | 20 min | High |
-| 5 | Refactor Existing | 2/10 | 15 min | Cleanup |
-| 6 | Documentation | 2/10 | 20 min | UX |
-| 7 | Testing | 3/10 | 30 min | Quality |
-
-**Total Effort:** ~3 hours
-**Overall Complexity:** 4/10 (medium)
-**Value:** HIGH (enables 100% local Cursor setup)
-
----
-
-## Priority Ranking
-
-### Must Have (Core Functionality)
-1. ✅ **Ollama support** - Most requested for privacy
-2. ✅ **llama.cpp support** - GGUF model compatibility
-3. ✅ **Provider detection** - Smart routing
-4. ✅ **Configuration** - User control
-
-### Should Have (Good UX)
-5. ✅ **Documentation** - User guidance
-6. ✅ **Error handling** - Helpful messages
-7. ✅ **Testing** - Quality assurance
-
-### Nice to Have (Future)
-8. ⚠️ **Caching** - Cache embeddings for repeated queries
-9. ⚠️ **Batch optimization** - Parallel Ollama requests
-10. ⚠️ **Auto-detection** - Detect installed embedding models
-
----
-
-## Benefits
-
-### For Privacy-Conscious Users
-- ✅ **100% local setup**: Ollama chat + Ollama embeddings
-- ✅ **No cloud dependencies**: Works offline
-- ✅ **No API costs**: FREE forever
-- ✅ **No data leakage**: Code never leaves machine
-
-### For Cost-Conscious Users
-- ✅ **Local embeddings FREE**: Ollama/llama.cpp
-- ✅ **Cloud fallback cheap**: OpenRouter $0.02/1M tokens
-- ✅ **Hybrid setup**: Local chat, cheap cloud embeddings
-
-### For All Users
-- ✅ **More choice**: 4 embedding providers
-- ✅ **Better control**: Explicit provider selection
-- ✅ **Consistent UX**: Works with any chat provider
-
----
-
-## Success Criteria
-
-### Functional Requirements
-- [ ] Ollama embeddings work with single and multiple inputs
-- [ ] llama.cpp embeddings work with batch inputs
-- [ ] Provider detection prioritizes correctly
-- [ ] Cursor @Codebase search works with local embeddings
-- [ ] Error messages are helpful
-
-### Quality Requirements
-- [ ] All tests pass (18 existing + 4 new = 22 total)
-- [ ] No breaking changes to existing OpenRouter/OpenAI
-- [ ] Documentation is clear and complete
-- [ ] Performance is acceptable (< 500ms per embedding)
-
-### User Experience
-- [ ] Setup takes < 5 minutes
-- [ ] Works out of the box with Ollama
-- [ ] Clear error messages when misconfigured
-- [ ] README examples are copy-pasteable
-
----
-
-## Risks & Mitigations
-
-| Risk | Impact | Mitigation |
-|------|--------|------------|
-| **Ollama doesn't support batch** | Medium | Loop through inputs sequentially |
-| **llama.cpp format changes** | Low | Use OpenAI-compatible mode |
-| **Embedding models not installed** | High | Clear setup instructions + error messages |
-| **Performance is slow** | Medium | Document model sizes, recommend lightweight models |
-| **Breaking existing OpenRouter** | High | Thorough testing, backward compatible |
-
----
-
-## Next Steps
-
-1. **Review this plan** - Get approval
-2. **Start with Phase 1** - Configuration (30 min)
-3. **Implement Phase 2** - Provider detection (20 min)
-4. **Implement Phase 3** - Ollama (45 min)
-5. **Implement Phase 4** - llama.cpp (20 min)
-6. **Complete remaining phases** - Refactor, docs, tests (65 min)
-7. **Test end-to-end** - Cursor @Codebase with local embeddings
-8. **Update changelog** - Document new feature
-
-**Total time:** ~3 hours of focused work
-
----
-
-## Questions to Answer Before Implementation
-
-1. **Should EMBEDDINGS_PROVIDER be required or auto-detected?**
-   - Recommendation: Auto-detect, allow override
-
-2. **Should we cache embeddings to avoid repeated API calls?**
-   - Recommendation: Not in MVP, add later if needed
-
-3. **Should we support multiple embedding models simultaneously?**
-   - Recommendation: No, one at a time
-
-4. **Should we validate embedding model is actually installed/running?**
-   - Recommendation: Yes, in error messages
-
-5. **Should we add embedding model benchmarks to docs?**
-   - Recommendation: Yes, quality/speed/size comparison
-
----
-
-## Alternative Approaches Considered
-
-### Approach A: Unified Embeddings Service
-**Pros:** Single endpoint handles all providers
-**Cons:** More complex, harder to debug
-**Decision:** ❌ Rejected - Too complex for MVP
-
-### Approach B: Separate /v1/embeddings/* Routes
-**Pros:** Clear separation, easy to extend
-**Cons:** Non-standard, breaks OpenAI compatibility
-**Decision:** ❌ Rejected - Breaks Cursor compatibility
-
-### Approach C: Provider-Specific Routing (Chosen)
-**Pros:** Clean, extensible, backward compatible
-**Cons:** Slightly more code
-**Decision:** ✅ Chosen - Best balance
-
----
-
-## Post-Implementation TODO
-
-- [ ] Add embeddings performance metrics to monitoring
-- [ ] Add embedding model benchmarks to docs
-- [ ] Consider adding embeddings caching layer
-- [ ] Add support for custom embedding endpoints
-- [ ] Add embedding model auto-download for Ollama
-- [ ] Add embedding dimension validation
-- [ ] Add support for normalized embeddings option
-- [ ] Consider adding batch optimization for Ollama (parallel requests)
-
----
-
-**Ready to implement? Let me know and I'll start with Phase 1!**