Merge pull request #32 from vcon-dev/CON-43-litellm-embeddings

Enhance embedding functionality with LiteLLM support

Author: howethomas

.env.example

@@ -8,6 +8,10 @@ SUPABASE_ANON_KEY=your-anon-key-here
 # Optional: For service role operations (use carefully!)
 # SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
 
+# LiteLLM proxy (optional; used for embeddings when set)
+# LITELLM_PROXY_URL=http://localhost:4000
+# LITELLM_MASTER_KEY=sk-your-master-key
+
 # ============================================================================
 # Plugin Configuration
 # ============================================================================

docs/api/tools.md

@@ -72,15 +72,15 @@ Create a new vCon (Virtual Conversation) record.
 ```typescript
 {
   vcon_data: {
-    vcon: "0.3.0",           // vCon version
+    vcon: "0.4.0",           // vCon version
     uuid?: string,           // Auto-generated if not provided
     subject?: string,        // Conversation subject
     parties: Party[],        // At least one party required
     dialog?: Dialog[],       // Optional conversation content
     analysis?: Analysis[],   // Optional AI analysis
     attachments?: Attachment[], // Optional files
     extensions?: string[],   // Optional extensions
-    must_support?: string[]  // Optional requirements
+    critical?: string[]      // Optional: extensions that must be supported (v0.4.0)
   },
   metadata?: {
     basename?: string,
@@ -106,7 +106,7 @@ Create a new vCon (Virtual Conversation) record.
 ```typescript
 {
   "vcon_data": {
-    "vcon": "0.3.0",
+    "vcon": "0.4.0",
     "subject": "Customer Support Call",
     "parties": [
       {
@@ -146,7 +146,7 @@ Retrieve a vCon by UUID.
 {
   success: boolean,
   vcon: {
-    vcon: "0.3.0",
+    vcon: "0.4.0",
     uuid: string,
     created_at: string,
     updated_at?: string,
@@ -181,7 +181,7 @@ Update vCon metadata and top-level fields.
   updates: {
     subject?: string,
     extensions?: string[],
-    must_support?: string[],
+    critical?: string[],
     [key: string]: any
   },
   merge_strategy?: "replace" | "merge" | "append",  // Default: "merge"

docs/development/INGEST_AND_EMBEDDINGS.md

@@ -19,7 +19,7 @@ npm install
   - `SUPABASE_URL`
   - `SUPABASE_SERVICE_ROLE_KEY`
   - `VCON_S3_BUCKET` (optional, for S3 loading)
-  - `OPENAI_API_KEY` or `HF_API_TOKEN` (for embeddings)
+  - One embedding provider (see priority order below): `LITELLM_PROXY_URL`+`LITELLM_MASTER_KEY`, `OPENAI_API_KEY`, Azure vars, or `HF_API_TOKEN`
 
 ---
 
@@ -56,7 +56,7 @@ npm run sync:vcons -- /absolute/path/to/vcons
 Notes:
 - Use absolute directory paths. Files must end with `.vcon` extension.
 - The script is idempotent and skips vCons already in the database.
-- Handles both legacy (0.0.1-0.2.0) and current (0.3.0) vCon specs.
+- Handles both legacy (0.0.1-0.2.0) and current (0.4.0) vCon specs.
 
 ---
 
@@ -76,12 +76,11 @@ Analysis elements with `encoding='none'` are prioritized because they contain pl
 Environment variables (set in `.env` file or exported):
 - `SUPABASE_URL`
 - `SUPABASE_SERVICE_ROLE_KEY`
-- One provider (choose one):
-  - `OPENAI_API_KEY` (uses `text-embedding-3-small` with `dimensions=384`)
-  - or Azure OpenAI:
-    - `AZURE_OPENAI_EMBEDDING_ENDPOINT` (e.g., `https://your-resource.openai.azure.com`)
-    - `AZURE_OPENAI_EMBEDDING_API_KEY`
-  - or `HF_API_TOKEN` (Hugging Face Inference API with `sentence-transformers/all-MiniLM-L6-v2`)
+- One provider (auto-detected in priority order — first match wins):
+  1. **LiteLLM** (highest priority): `LITELLM_PROXY_URL` + `LITELLM_MASTER_KEY` (or `LITELLM_API_KEY`)
+  2. **Azure OpenAI**: `AZURE_OPENAI_EMBEDDING_ENDPOINT` + `AZURE_OPENAI_EMBEDDING_API_KEY`
+  3. **OpenAI**: `OPENAI_API_KEY` (uses `text-embedding-3-small` with `dimensions=384`)
+  4. **Hugging Face**: `HF_API_TOKEN` (uses `sentence-transformers/all-MiniLM-L6-v2`)
 
 #### Generate Embeddings
 
@@ -101,6 +100,9 @@ For more control, use the script directly:
 # Process 100 units (default)
 npx tsx scripts/embed-vcons.ts
 
+# Process with LiteLLM proxy (set LITELLM_PROXY_URL + LITELLM_MASTER_KEY in .env)
+npx tsx scripts/embed-vcons.ts --limit=500 --provider=litellm
+
 # Process 500 units with OpenAI
 npx tsx scripts/embed-vcons.ts --limit=500 --provider=openai
 

docs/development/embeddings.md

@@ -1,5 +1,7 @@
 # Supabase Semantic Search Implementation Guide
 
+> **⚠️ Historical reference document.** The SQL examples in Steps 1–2 below reflect an early 1536-dim / `text-embedding-ada-002` design. The current implementation uses **`text-embedding-3-small` at 384 dimensions**. For the authoritative setup, see [`docs/development/INGEST_AND_EMBEDDINGS.md`](./INGEST_AND_EMBEDDINGS.md).
+
 ## Overview
 
 This guide explains how to implement semantic search for vCon conversation content in Supabase PostgreSQL using the **pgvector** extension for vector similarity search.
@@ -48,18 +50,18 @@ SELECT * FROM pg_extension WHERE extname = 'vector';
 ```sql
 -- Add vector columns to existing tables
 ALTER TABLE vcons 
-ADD COLUMN subject_embedding vector(1536),  -- OpenAI ada-002 dimension
-ADD COLUMN subject_embedding_model TEXT DEFAULT 'text-embedding-ada-002',
+ADD COLUMN subject_embedding vector(384),  -- text-embedding-3-small dimension
+ADD COLUMN subject_embedding_model TEXT DEFAULT 'text-embedding-3-small',
 ADD COLUMN subject_embedding_updated_at TIMESTAMPTZ;
 
 ALTER TABLE dialog
-ADD COLUMN content_embedding vector(1536),
-ADD COLUMN content_embedding_model TEXT DEFAULT 'text-embedding-ada-002',
+ADD COLUMN content_embedding vector(384),
+ADD COLUMN content_embedding_model TEXT DEFAULT 'text-embedding-3-small',
 ADD COLUMN content_embedding_updated_at TIMESTAMPTZ;
 
 ALTER TABLE analysis
-ADD COLUMN summary_embedding vector(1536),
-ADD COLUMN summary_embedding_model TEXT DEFAULT 'text-embedding-ada-002',
+ADD COLUMN summary_embedding vector(384),
+ADD COLUMN summary_embedding_model TEXT DEFAULT 'text-embedding-3-small',
 ADD COLUMN summary_embedding_updated_at TIMESTAMPTZ;
 ```
 
@@ -79,9 +81,9 @@ CREATE TABLE vcon_embeddings (
     content_text TEXT NOT NULL, -- Original text that was embedded
 
     -- The embedding
-    embedding vector(1536) NOT NULL,
-    embedding_model TEXT NOT NULL DEFAULT 'text-embedding-ada-002',
-    embedding_dimension INTEGER NOT NULL DEFAULT 1536,
+    embedding vector(384) NOT NULL,
+    embedding_model TEXT NOT NULL DEFAULT 'text-embedding-3-small',
+    embedding_dimension INTEGER NOT NULL DEFAULT 384,
 
     -- Metadata
     created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
@@ -157,7 +159,7 @@ from supabase import create_client
 openai.api_key = "your-openai-key"
 supabase = create_client("your-supabase-url", "your-supabase-key")
 
-def generate_embedding(text: str, model: str = "text-embedding-ada-002") -> list[float]:
+def generate_embedding(text: str, model: str = "text-embedding-3-small") -> list[float]:
     """Generate embedding using OpenAI API."""
     response = openai.embeddings.create(
         input=text,
@@ -177,8 +179,8 @@ def embed_vcon_content(vcon_id: str, subject: str, dialog_texts: list[str]):
             'content_reference': None,
             'content_text': subject,
             'embedding': subject_embedding,
-            'embedding_model': 'text-embedding-ada-002',
-            'embedding_dimension': 1536
+            'embedding_model': 'text-embedding-3-small',
+            'embedding_dimension': 384
         }).execute()
 
     # Embed dialogs
@@ -264,7 +266,7 @@ serve(async (req) => {
 })
 ```
 
-See `docs/INGEST_AND_EMBEDDINGS.md` for the production-ready function (`supabase/functions/embed-vcons/index.ts`), environment variables, and Cron scheduling. This repository standardizes on 384‑dim embeddings to match the migrations and HNSW index.
+See [`docs/development/INGEST_AND_EMBEDDINGS.md`](./INGEST_AND_EMBEDDINGS.md) for the production-ready function (`supabase/functions/embed-vcons/index.ts`), environment variables, and Cron scheduling. This repository standardizes on 384‑dim embeddings to match the migrations and HNSW index.
 
 ---
 
@@ -275,7 +277,7 @@ See `docs/INGEST_AND_EMBEDDINGS.md` for the production-ready function (`supabase
 ```sql
 -- Function to search by semantic similarity
 CREATE OR REPLACE FUNCTION search_vcons_semantic(
-    query_embedding vector(1536),
+    query_embedding vector(384),
     match_threshold float DEFAULT 0.7,
     match_count int DEFAULT 20
 )

docs/guide/installation.md

@@ -532,14 +532,19 @@ curl "https://your-project.supabase.co/rest/v1/" \
 
 Complete list of supported environment variables:
 
+Embedding provider priority: **LiteLLM → Azure OpenAI → OpenAI → Hugging Face** (first configured wins).
+
 | Variable | Required | Description | Default |
 |----------|----------|-------------|---------|
 | `SUPABASE_URL` | ✅ Yes | Your Supabase project URL | - |
 | `SUPABASE_ANON_KEY` | ✅ Yes | Supabase anon public key | - |
 | `SUPABASE_SERVICE_ROLE_KEY` | ❌ No | Service role key (admin operations) | - |
-| `OPENAI_API_KEY` | ❌ No | OpenAI API key for embeddings | - |
+| `LITELLM_PROXY_URL` | ❌ No | LiteLLM proxy base URL — takes priority for embeddings | - |
+| `LITELLM_MASTER_KEY` | ❌ No | LiteLLM proxy API key (also accepted as `LITELLM_API_KEY`) | - |
+| `OPENAI_API_KEY` | ❌ No | OpenAI API key for embeddings (if LiteLLM not set) | - |
 | `AZURE_OPENAI_EMBEDDING_ENDPOINT` | ❌ No | Azure OpenAI base endpoint (e.g., https://your-resource.openai.azure.com) | - |
 | `AZURE_OPENAI_EMBEDDING_API_KEY` | ❌ No | Azure OpenAI API key | - |
+| `HF_API_TOKEN` | ❌ No | Hugging Face API token for embeddings (lowest priority fallback) | - |
 | `VCON_PLUGINS_PATH` | ❌ No | Comma-separated plugin paths | - |
 | `VCON_LICENSE_KEY` | ❌ No | Enterprise license key | - |
 | `MCP_SERVER_NAME` | ❌ No | Server name for MCP | `vcon-mcp-server` |

docs/guide/search.md

@@ -114,8 +114,6 @@ The vCon MCP server provides four search tools with different capabilities, from
 }
 ```
 
-**Note:** Automatic embedding generation from query text is not yet implemented. Use `search_vcons_content` for keyword-based search without embeddings.
-
 **Returns:** Similar conversations ranked by semantic similarity
 
 ---
@@ -287,8 +285,8 @@ Analysis with `encoding='json'` or `encoding='base64url'` typically contains:
 For semantic and hybrid search to work effectively, you need to generate embeddings for your vCons.
 
 See the following guides:
-- [INGEST_AND_EMBEDDINGS.md](./INGEST_AND_EMBEDDINGS.md) - Complete guide to embedding generation
-- [EMBEDDING_STRATEGY_UPGRADE.md](./EMBEDDING_STRATEGY_UPGRADE.md) - Details on which content is embedded
+- [INGEST_AND_EMBEDDINGS.md](../development/INGEST_AND_EMBEDDINGS.md) - Complete guide to embedding generation
+- [EMBEDDING_STRATEGY_UPGRADE.md](../development/EMBEDDING_STRATEGY_UPGRADE.md) - Details on which content is embedded
 
 **Quick start:**
 ```bash
@@ -387,6 +385,6 @@ npm run embeddings:check
 ## Related Documentation
 
 - [QUICK_START.md](../QUICK_START.md) - Getting started with vCon MCP
-- [INGEST_AND_EMBEDDINGS.md](./INGEST_AND_EMBEDDINGS.md) - Embedding generation
+- [INGEST_AND_EMBEDDINGS.md](../development/INGEST_AND_EMBEDDINGS.md) - Embedding generation
 - [SUPABASE_SEMANTIC_SEARCH_GUIDE.md](../SUPABASE_SEMANTIC_SEARCH_GUIDE.md) - Database search implementation
 

docs/reference/CORRECTED_SCHEMA.md

@@ -128,7 +128,7 @@ CREATE TABLE attachments (
     dialog INTEGER,  -- CORRECTED: Added dialog reference per spec Section 4.4.4
 
     -- Content fields
-    mimetype TEXT,
+    mediatype TEXT,  -- CORRECTED: v0.0.2+ renamed mimetype→mediatype
     filename TEXT,
     body TEXT,
     encoding TEXT CHECK (encoding IS NULL OR encoding IN ('base64url', 'json', 'none')), -- CORRECTED: Removed default, added constraint
@@ -265,9 +265,9 @@ CREATE INDEX idx_vcons_subject_trgm ON vcons USING gin (subject gin_trgm_ops);
 CREATE INDEX idx_parties_name_trgm ON parties USING gin (name gin_trgm_ops);
 
 -- Comments for documentation
-COMMENT ON TABLE vcons IS 'Main vCon container table - compliant with draft-ietf-vcon-vcon-core-00';
+COMMENT ON TABLE vcons IS 'Main vCon container table - compliant with draft-ietf-vcon-vcon-core-02 (v0.4.0)';
 COMMENT ON COLUMN vcons.extensions IS 'List of vCon extensions used (Section 4.1.3)';
-COMMENT ON COLUMN vcons.must_support IS 'List of incompatible extensions that must be supported (Section 4.1.4)';
+COMMENT ON COLUMN vcons.critical IS 'List of incompatible extensions that must be supported (Section 4.1.4); renamed from must_support in v0.4.0';
 
 COMMENT ON TABLE parties IS 'Party objects from vCon parties array (Section 4.2)';
 COMMENT ON COLUMN parties.uuid IS 'Unique identifier for participant across vCons (Section 4.2.12)';
@@ -322,9 +322,9 @@ BEGIN;
 
 -- 1. Add new required columns
 ALTER TABLE vcons ADD COLUMN IF NOT EXISTS extensions TEXT[];
-ALTER TABLE vcons ADD COLUMN IF NOT EXISTS must_support TEXT[];
-ALTER TABLE vcons ADD COLUMN IF NOT EXISTS appended JSONB DEFAULT '{}';
-ALTER TABLE vcons ALTER COLUMN vcon_version SET DEFAULT '0.3.0';
+ALTER TABLE vcons ADD COLUMN IF NOT EXISTS critical TEXT[];
+ALTER TABLE vcons ADD COLUMN IF NOT EXISTS amended JSONB DEFAULT '{}';
+ALTER TABLE vcons ALTER COLUMN vcon_version SET DEFAULT '0.4.0';
 
 ALTER TABLE parties ADD COLUMN IF NOT EXISTS did TEXT;
 ALTER TABLE parties ADD COLUMN IF NOT EXISTS uuid UUID;