Merge pull request #37 from GoodbyePlanet/feat/pluggable-embedding-providers

feat: Add pluggable embedding providers (Jina, Voyage, OpenAI, Ollama)

Author: GoodbyePlanet

.env.example

@@ -1,5 +1,25 @@
-# Embeddings (Jina Code V2 via HuggingFace TEI)
-EMBEDDINGS_URL=http://localhost:8087
+# Embeddings provider — one of: jina | voyage | openai | ollama
+EMBEDDINGS_PROVIDER=jina
+
+# Jina Code V2 via HuggingFace TEI (default)
+JINA_URL=http://localhost:8087
+JINA_MODEL=jinaai/jina-embeddings-v2-base-code
+JINA_DIMENSIONS=768
+
+# Voyage AI — set EMBEDDINGS_PROVIDER=voyage to use
+# VOYAGE_API_KEY=
+# VOYAGE_MODEL=voyage-code-3
+# VOYAGE_DIMENSIONS=        # optional override (e.g. 256, 512, 1024, 2048)
+
+# OpenAI — set EMBEDDINGS_PROVIDER=openai to use
+# OPENAI_API_KEY=
+# OPENAI_EMBEDDING_MODEL=text-embedding-3-large
+# OPENAI_DIMENSIONS=        # optional override
+
+# Ollama — set EMBEDDINGS_PROVIDER=ollama to use
+# OLLAMA_URL=http://localhost:11434
+# OLLAMA_MODEL=nomic-embed-text
+# OLLAMA_DIMENSIONS=        # required for models not in the built-in table
 
 # Qdrant
 QDRANT_URL=http://localhost:6333
@@ -14,4 +34,4 @@ MCP_PORT=8090
 CONFIG_PATH=./config.yaml
 
 # GitHub token — requires repo:read (or contents:read for fine-grained tokens)
-GITHUB_TOKEN=
+GITHUB_TOKEN=

README.md

@@ -13,7 +13,7 @@ language queries or symbol name lookups.
 
 1. Fetches source files from configured GitHub repositories
 2. Parses code symbols (functions, classes, methods, components) using Tree-sitter
-3. Generates embeddings via Jina Code V2 (served by HuggingFace TEI)
+3. Generates embeddings via a pluggable provider — Jina Code V2 (TEI) by default, or Voyage / OpenAI / Ollama
 4. Stores vectors in Qdrant for fast semantic search
 5. Optionally indexes commit history into a separate Qdrant collection
 6. Exposes search and indexing tools through the MCP protocol (and a small HTTP API)
@@ -97,7 +97,7 @@ chunk with a vector embedding and a rich payload.
 - **Change detection** — compares the file's Git blob SHA to the last indexed value; unchanged files are skipped
 - **Parsing** — Tree-sitter walks the AST and emits `CodeSymbol` objects per language
 - **Embedding text** — built from signature, docstring, annotations, parent name, and source (truncated at ~6000 chars)
-- **Batching** — symbols are embedded in batches of 32 against the TEI server
+- **Batching** — batched per-provider (32 for Jina/TEI and Ollama, 128 for Voyage and OpenAI)
 - **Upsert** — vectors stored in Qdrant under deterministic UUIDs (per service / file / symbol / line)
 - **Cleanup** — entries for files no longer in the repo are deleted
 
@@ -158,19 +158,51 @@ any context where observing indexing progress matters.
 
 ## Environment variables
 
-| Variable                    | Default                               | Description                                |
-|-----------------------------|---------------------------------------|--------------------------------------------|
-| `GITHUB_TOKEN`              | *(required)*                          | GitHub token with repo read access         |
-| `QDRANT_URL`                | `http://localhost:6333`               | Qdrant connection URL                      |
-| `QDRANT_COLLECTION`         | `code_symbols`                        | Collection name for code symbol vectors    |
-| `QDRANT_COMMITS_COLLECTION` | `git_commits`                         | Collection name for commit message vectors |
-| `EMBEDDINGS_URL`            | `http://localhost:8087`               | Jina TEI URL                               |
-| `EMBEDDINGS_MODEL`          | `jinaai/jina-embeddings-v2-base-code` | Embedding model ID                         |
-| `EMBEDDINGS_DIMENSIONS`     | `768`                                 | Vector dimensions                          |
-| `GIT_HISTORY_MAX_COMMITS`   | `500`                                 | Max commits indexed per service            |
-| `MCP_TRANSPORT`             | `streamable-http`                     | One of `streamable-http`, `sse`, `stdio`   |
-| `MCP_HOST` / `MCP_PORT`     | `0.0.0.0` / `8090`                    | Server bind address                        |
-| `CONFIG_PATH`               | `./config.yaml`                       | Path to the services config file           |
+| Variable                    | Default                 | Description                                |
+|-----------------------------|-------------------------|--------------------------------------------|
+| `GITHUB_TOKEN`              | *(required)*            | GitHub token with repo read access         |
+| `QDRANT_URL`                | `http://localhost:6333` | Qdrant connection URL                      |
+| `QDRANT_COLLECTION`         | `code_symbols`          | Collection name for code symbol vectors    |
+| `QDRANT_COMMITS_COLLECTION` | `git_commits`           | Collection name for commit message vectors |
+| `EMBEDDINGS_PROVIDER`       | `jina`                  | One of `jina`, `voyage`, `openai`, `ollama` — see *Embedding providers* below |
+| `GIT_HISTORY_MAX_COMMITS`   | `500`                   | Max commits indexed per service            |
+| `MCP_TRANSPORT`             | `streamable-http`       | One of `streamable-http`, `sse`, `stdio`   |
+| `MCP_HOST` / `MCP_PORT`     | `0.0.0.0` / `8090`      | Server bind address                        |
+| `CONFIG_PATH`               | `./config.yaml`         | Path to the services config file           |
+
+## Embedding providers
+
+The embedding backend is selectable via `EMBEDDINGS_PROVIDER`. Default is `jina` so existing
+deployments keep working unchanged. Each provider derives its own vector dimensions from the
+configured model — no need to set dimensions manually unless you want to override.
+
+| Variable                 | Default                               | Applies to | Description                                                                       |
+|--------------------------|---------------------------------------|------------|-----------------------------------------------------------------------------------|
+| `JINA_URL`               | `http://localhost:8087`               | `jina`     | TEI base URL                                                                      |
+| `JINA_MODEL`             | `jinaai/jina-embeddings-v2-base-code` | `jina`     | Model ID served by TEI (informational — the running TEI container chooses)        |
+| `JINA_DIMENSIONS`        | `768`                                 | `jina`     | Vector dimensions of the TEI model                                                |
+| `VOYAGE_API_KEY`         | *(required if provider=voyage)*       | `voyage`   | Voyage AI API key                                                                 |
+| `VOYAGE_MODEL`           | `voyage-code-3`                       | `voyage`   | Voyage embedding model                                                            |
+| `VOYAGE_DIMENSIONS`      | *(native)*                            | `voyage`   | Optional override — Voyage code-3 supports `256` / `512` / `1024` / `2048`        |
+| `OPENAI_API_KEY`         | *(required if provider=openai)*       | `openai`   | OpenAI API key                                                                    |
+| `OPENAI_EMBEDDING_MODEL` | `text-embedding-3-large`              | `openai`   | OpenAI embedding model                                                            |
+| `OPENAI_DIMENSIONS`      | *(native)*                            | `openai`   | Optional override (text-embedding-3-* models support shrinking)                   |
+| `OLLAMA_URL`             | `http://localhost:11434`              | `ollama`   | Ollama base URL                                                                   |
+| `OLLAMA_MODEL`           | `nomic-embed-text`                    | `ollama`   | Ollama embedding model                                                            |
+| `OLLAMA_DIMENSIONS`      | *(native)*                            | `ollama`   | Required if using a model not in the built-in dimensions table                    |
+
+`voyage-code-3` outperforms `jinaai/jina-embeddings-v2-base-code` on most code retrieval benchmarks,
+so switching to Voyage is also a quality lever, not just a flexibility one.
+
+**Switching providers against an existing index:** if the new provider's vector size differs from
+the existing Qdrant collection, the server fails fast at startup with a clear error pointing at the
+offending collection. To switch, drop both collections (`code_symbols` and `git_commits`) via the
+Qdrant UI or API, then reindex. There is no automatic migration.
+
+**Hosted-only setup (no local TEI container):** in `docker-compose.yaml`, comment out the entire
+`jina-embeddings` service block, the `jina-embeddings` entry under `semcode.depends_on`, and the
+`JINA_URL` line under `semcode.environment`. Then set `EMBEDDINGS_PROVIDER` and the relevant API
+key in `.env`.
 
 ## Qdrant collections
 

docker-compose.yaml

@@ -12,6 +12,13 @@ services:
       timeout: 5s
       retries: 5
 
+  # Jina Code V2 served by HuggingFace Text Embeddings Inference. Default
+  # embedding backend. To use a hosted provider instead (Voyage / OpenAI) or a
+  # local Ollama install, set EMBEDDINGS_PROVIDER + the relevant API key in
+  # .env, then comment out:
+  #   1. this entire `jina-embeddings` service
+  #   2. the `jina-embeddings` entry under `semcode.depends_on`
+  #   3. the JINA_URL line under `semcode.environment`
   jina-embeddings:
     image: ghcr.io/huggingface/text-embeddings-inference:cpu-1.6
     platform: linux/amd64
@@ -35,7 +42,7 @@ services:
     env_file:
       - .env
     environment:
-      EMBEDDINGS_URL: http://jina-embeddings:80
+      JINA_URL: http://jina-embeddings:80
       QDRANT_URL: http://qdrant:6333
       MCP_HOST: 0.0.0.0
       FASTEMBED_CACHE_PATH: /fastembed_cache

server/config.py

@@ -23,14 +23,39 @@ def __init__(
         self.exclude = exclude
 
 
+EmbeddingsProviderName = Literal["jina", "voyage", "openai", "ollama"]
+
+
 class Settings(BaseSettings):
     model_config = {"env_file": ".env", "env_file_encoding": "utf-8", "extra": "ignore"}
 
-    embeddings_url: str = Field(default="http://localhost:8087", alias="EMBEDDINGS_URL")
-    embeddings_model: str = Field(
-        default="jinaai/jina-embeddings-v2-base-code", alias="EMBEDDINGS_MODEL"
+    embeddings_provider: EmbeddingsProviderName = Field(
+        default="jina", alias="EMBEDDINGS_PROVIDER"
+    )
+
+    # Jina (TEI / self-hosted HuggingFace text-embeddings-inference)
+    jina_url: str = Field(default="http://localhost:8087", alias="JINA_URL")
+    jina_model: str = Field(
+        default="jinaai/jina-embeddings-v2-base-code", alias="JINA_MODEL"
     )
-    embeddings_dimensions: int = Field(default=768, alias="EMBEDDINGS_DIMENSIONS")
+    jina_dimensions: int = Field(default=768, alias="JINA_DIMENSIONS")
+
+    # Voyage AI
+    voyage_api_key: str = Field(default="", alias="VOYAGE_API_KEY")
+    voyage_model: str = Field(default="voyage-code-3", alias="VOYAGE_MODEL")
+    voyage_dimensions: int | None = Field(default=None, alias="VOYAGE_DIMENSIONS")
+
+    # OpenAI
+    openai_api_key: str = Field(default="", alias="OPENAI_API_KEY")
+    openai_embedding_model: str = Field(
+        default="text-embedding-3-large", alias="OPENAI_EMBEDDING_MODEL"
+    )
+    openai_dimensions: int | None = Field(default=None, alias="OPENAI_DIMENSIONS")
+
+    # Ollama
+    ollama_url: str = Field(default="http://localhost:11434", alias="OLLAMA_URL")
+    ollama_model: str = Field(default="nomic-embed-text", alias="OLLAMA_MODEL")
+    ollama_dimensions: int | None = Field(default=None, alias="OLLAMA_DIMENSIONS")
 
     qdrant_url: str = Field(default="http://localhost:6333", alias="QDRANT_URL")
     qdrant_collection: str = Field(default="code_symbols", alias="QDRANT_COLLECTION")

server/embeddings/factory.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from server.config import settings
+from server.embeddings.base import EmbeddingProvider
+
+_provider: EmbeddingProvider | None = None
+
+
+def get_embedding_provider() -> EmbeddingProvider:
+    global _provider
+    if _provider is not None:
+        return _provider
+
+    name = settings.embeddings_provider
+    if name == "jina":
+        from server.embeddings.jina import JinaEmbeddingProvider
+
+        _provider = JinaEmbeddingProvider()
+    elif name == "voyage":
+        from server.embeddings.voyage import VoyageEmbeddingProvider
+
+        _provider = VoyageEmbeddingProvider()
+    elif name == "openai":
+        from server.embeddings.openai import OpenAIEmbeddingProvider
+
+        _provider = OpenAIEmbeddingProvider()
+    elif name == "ollama":
+        from server.embeddings.ollama import OllamaEmbeddingProvider
+
+        _provider = OllamaEmbeddingProvider()
+    else:
+        raise ValueError(
+            f"Unknown EMBEDDINGS_PROVIDER {name!r}. "
+            "Expected one of: jina, voyage, openai, ollama."
+        )
+    return _provider
+
+
+async def close_embedding_provider() -> None:
+    global _provider
+    if _provider is None:
+        return
+    close = getattr(_provider, "close", None)
+    if close is not None:
+        await close()
+    _provider = None

server/embeddings/jina.py

@@ -18,8 +18,8 @@ class JinaEmbeddingProvider(EmbeddingProvider):
     """Calls the self-hosted Jina Code V2 model via HuggingFace Text Embeddings Inference."""
 
     def __init__(self) -> None:
-        self._base_url = settings.embeddings_url.rstrip("/")
-        self._dims = settings.embeddings_dimensions
+        self._base_url = settings.jina_url.rstrip("/")
+        self._dims = settings.jina_dimensions
         self._client = httpx.AsyncClient(timeout=120.0)
 
     @property
@@ -58,20 +58,3 @@ async def embed_query(self, text: str) -> list[float]:
 
     async def close(self) -> None:
         await self._client.aclose()
-
-
-_provider: JinaEmbeddingProvider | None = None
-
-
-def get_embedding_provider() -> JinaEmbeddingProvider:
-    global _provider
-    if _provider is None:
-        _provider = JinaEmbeddingProvider()
-    return _provider
-
-
-async def close_embedding_provider() -> None:
-    global _provider
-    if _provider is not None:
-        await _provider.close()
-        _provider = None

server/embeddings/ollama.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+import logging
+
+import httpx
+
+from server.config import settings
+from server.embeddings.base import EmbeddingProvider
+
+logger = logging.getLogger(__name__)
+
+_EMBED_PATH = "/api/embed"
+_BATCH_SIZE = 32
+
+_NATIVE_DIMENSIONS: dict[str, int] = {
+    "nomic-embed-text": 768,
+    "mxbai-embed-large": 1024,
+    "all-minilm": 384,
+    "snowflake-arctic-embed": 1024,
+    "bge-m3": 1024,
+}
+
+
+class OllamaEmbeddingProvider(EmbeddingProvider):
+    """Ollama embeddings — see https://github.com/ollama/ollama/blob/main/docs/api.md#generate-embeddings."""
+
+    def __init__(self) -> None:
+        self._base_url = settings.ollama_url.rstrip("/")
+        self._model = settings.ollama_model
+        self._dims_override = settings.ollama_dimensions
+        if self._dims_override is not None:
+            self._dims = self._dims_override
+        elif self._model in _NATIVE_DIMENSIONS:
+            self._dims = _NATIVE_DIMENSIONS[self._model]
+        else:
+            raise RuntimeError(
+                f"Unknown Ollama model {self._model!r} — set OLLAMA_DIMENSIONS "
+                "to declare the output size, or use a known model "
+                f"({', '.join(sorted(_NATIVE_DIMENSIONS))})."
+            )
+        self._client = httpx.AsyncClient(timeout=120.0)
+
+    @property
+    def dimensions(self) -> int:
+        return self._dims
+
+    async def embed_batch(self, texts: list[str]) -> list[list[float]]:
+        if not texts:
+            return []
+        all_vectors: list[list[float]] = []
+        for i in range(0, len(texts), _BATCH_SIZE):
+            batch = texts[i : i + _BATCH_SIZE]
+            resp = await self._client.post(
+                f"{self._base_url}{_EMBED_PATH}",
+                json={"model": self._model, "input": batch},
+            )
+            resp.raise_for_status()
+            data = resp.json()
+            batch_vectors = data.get("embeddings", [])
+            if len(batch_vectors) != len(batch):
+                raise ValueError(
+                    f"Ollama returned {len(batch_vectors)} vectors for "
+                    f"{len(batch)} inputs — response may be malformed"
+                )
+            all_vectors.extend(batch_vectors)
+        return all_vectors
+
+    async def embed_query(self, text: str) -> list[float]:
+        vectors = await self.embed_batch([text])
+        return vectors[0] if vectors else []
+
+    async def close(self) -> None:
+        await self._client.aclose()