Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

feat(embeddings): the OpenAI embedder honours a configured output width (#1254)

Sergei Iakhnitskii9eac101e96af
diff --git a/packages/core/src/repowise/core/providers/embedding/openai.py b/packages/core/src/repowise/core/providers/embedding/openai.py
index 3be251c72..5852603a6 100644
--- a/packages/core/src/repowise/core/providers/embedding/openai.py
+++ b/packages/core/src/repowise/core/providers/embedding/openai.py
@@ -20,6 +20,9 @@ Dimensions:
text-embedding-3-small → 1536 dims
text-embedding-3-large → 3072 dims
text-embedding-ada-002 → 1536 dims
+
+ REPOWISE_EMBEDDING_DIMS (or the ``dimensions`` arg) overrides the width and
+ is passed to the API so the returned vectors match. See ``OpenAIEmbedder``.
"""
from __future__ import annotations
@@ -27,7 +30,7 @@ from __future__ import annotations
import asyncio
import math
import os
-from typing import ClassVar
+from typing import Any, ClassVar
class OpenAIEmbedder:
@@ -37,6 +40,11 @@ class OpenAIEmbedder:
api_key: OpenAI API key. Falls back to OPENAI_API_KEY env var.
model: Embedding model name. Default: "text-embedding-3-small".
base_url: Optional custom base URL for OpenAI-compatible endpoints.
+ dimensions: Output width for a model not in ``_DIMS`` (e.g. a local
+ OpenAI-compatible embedder). Falls back to REPOWISE_EMBEDDING_DIMS,
+ then to the known-model table, then 1536. An overridden width is
+ also sent to the API so the returned vectors match the declaration;
+ an endpoint that does not implement the parameter ignores it.
"""
_DIMS: ClassVar[dict[str, int]] = {
@@ -54,6 +62,7 @@ class OpenAIEmbedder:
model: str = "text-embedding-3-small",
timeout: float = _DEFAULT_TIMEOUT,
base_url: str | None = None,
+ dimensions: int | None = None,
) -> None:
self._api_key = api_key or os.environ.get("OPENAI_API_KEY")
if not self._api_key:
@@ -63,11 +72,51 @@ class OpenAIEmbedder:
self._base_url = base_url or os.environ.get("OPENAI_BASE_URL")
self._model = model
self._timeout = timeout
+ # When the user overrides the width, request that width from the API too,
+ # so the returned vectors match the declaration instead of the model's
+ # default — otherwise the store is sized to a width the vectors never
+ # have. Servers that don't implement the parameter ignore it (returning
+ # their native width, which the override then correctly declares); one
+ # that can't honour it rejects the request loudly rather than silently
+ # returning a mismatched width. No model is special-cased here: the
+ # endpoint, not a hardcoded name table, decides what it accepts.
+ self._dimensions, self._request_dimensions = self._resolve_dimensions(dimensions, model)
self._client: object | None = None # cached; created once on first embed()
+ @classmethod
+ def _resolve_dimensions(cls, dimensions: int | None, model: str) -> tuple[int, int | None]:
+ """Resolve ``(declared_width, override)``.
+
+ ``override`` is the user-chosen width — explicit arg or
+ ``REPOWISE_EMBEDDING_DIMS`` — once validated, or ``None`` when the width
+ falls back to the known-model table. It doubles as the value to request
+ from the API: ``None`` means send no ``dimensions`` (keep the stock
+ request byte-identical). Precedence for the declared width:
+ explicit arg > REPOWISE_EMBEDDING_DIMS > known-model table > 1536.
+
+ A local OpenAI-compatible embedder (e.g. a self-hosted model) is not in
+ ``_DIMS``; without an override its width would silently default to 1536
+ and mismatch the store. Mirrors the Ollama/Gemini embedders, which
+ already honour REPOWISE_EMBEDDING_DIMS.
+ """
+ if dimensions is None:
+ env = os.environ.get("REPOWISE_EMBEDDING_DIMS")
+ if env:
+ try:
+ dimensions = int(env)
+ except ValueError:
+ # Match the message every other bad value raises below,
+ # instead of a raw "invalid literal for int()".
+ raise ValueError("dimensions must be a positive integer") from None
+ if dimensions is None:
+ return cls._DIMS.get(model, 1536), None
+ if isinstance(dimensions, bool) or not isinstance(dimensions, int) or dimensions <= 0:
+ raise ValueError("dimensions must be a positive integer")
+ return dimensions, dimensions
+
@property
def dimensions(self) -> int:
- return self._DIMS.get(self._model, 1536)
+ return self._dimensions
async def embed(self, texts: list[str]) -> list[list[float]]:
"""Embed a batch of texts using OpenAI.
@@ -86,6 +135,7 @@ class OpenAIEmbedder:
model = self._model
timeout = self._timeout
+ request_dimensions = self._request_dimensions
def _embed_sync() -> list[list[float]]:
import openai # type: ignore[import-untyped]
@@ -97,7 +147,10 @@ class OpenAIEmbedder:
timeout=timeout,
base_url=self._base_url,
)
- response = self._client.embeddings.create(model=model, input=texts) # type: ignore[union-attr]
+ create_kwargs: dict[str, Any] = {"model": model, "input": texts}
+ if request_dimensions is not None:
+ create_kwargs["dimensions"] = request_dimensions
+ response = self._client.embeddings.create(**create_kwargs) # type: ignore[union-attr]
raw_vectors = [list(item.embedding) for item in response.data]
return [_l2_normalize(v) for v in raw_vectors]
diff --git a/packages/server/src/repowise/server/mcp_server/_server.py b/packages/server/src/repowise/server/mcp_server/_server.py
index 33b6c9d15..716175119 100644
--- a/packages/server/src/repowise/server/mcp_server/_server.py
+++ b/packages/server/src/repowise/server/mcp_server/_server.py
@@ -140,9 +140,11 @@ def _embedder_kwargs(name: str) -> dict[str, Any]:
"""Map repowise embedding env vars onto an embedder's constructor kwargs.
Kept backend-agnostic: ``REPOWISE_EMBEDDING_MODEL`` applies to any embedder
- that accepts a ``model`` arg; ``REPOWISE_EMBEDDING_DIMS`` is gemini-specific
- (its constructor exposes ``output_dimensionality``). Anything not set here
- falls through to the embedder's own defaults.
+ that accepts a ``model`` arg. ``REPOWISE_EMBEDDING_DIMS`` is read directly by
+ the openai and ollama embedders in their own constructors; only gemini needs
+ it mapped here, because its constructor spells the width
+ ``output_dimensionality``. Anything not set here falls through to the
+ embedder's own defaults.
When the embedder needs an API key and the environment has none, the key is
recovered from the repo/global config so the server matches the index it
diff --git a/tests/unit/test_persistence/test_openai_embedder.py b/tests/unit/test_persistence/test_openai_embedder.py
index 34739f403..73c18c7d0 100644
--- a/tests/unit/test_persistence/test_openai_embedder.py
+++ b/tests/unit/test_persistence/test_openai_embedder.py
@@ -46,6 +46,42 @@ def test_dimensions_unknown_model_defaults_to_1536():
assert emb.dimensions == 1536
+def test_dimensions_explicit_override_wins_for_unknown_model():
+ emb = OpenAIEmbedder(api_key="k", model="local-embedder", dimensions=2560)
+ assert emb.dimensions == 2560
+
+
+def test_dimensions_from_env(monkeypatch):
+ monkeypatch.setenv("REPOWISE_EMBEDDING_DIMS", "2560")
+ emb = OpenAIEmbedder(api_key="k", model="local-embedder")
+ assert emb.dimensions == 2560
+
+
+def test_explicit_dimensions_beats_env(monkeypatch):
+ monkeypatch.setenv("REPOWISE_EMBEDDING_DIMS", "2560")
+ emb = OpenAIEmbedder(api_key="k", model="local-embedder", dimensions=1024)
+ assert emb.dimensions == 1024
+
+
+def test_env_overrides_known_model_width(monkeypatch):
+ # Precedence holds for a stock model too: the env wins over the table.
+ monkeypatch.setenv("REPOWISE_EMBEDDING_DIMS", "512")
+ emb = OpenAIEmbedder(api_key="k", model="text-embedding-3-small")
+ assert emb.dimensions == 512
+
+
[email protected]("bad", [0, -5, True])
+def test_invalid_dimensions_raises(bad):
+ with pytest.raises(ValueError, match="dimensions must be a positive integer"):
+ OpenAIEmbedder(api_key="k", model="local-embedder", dimensions=bad)
+
+
+def test_malformed_env_raises_the_same_message(monkeypatch):
+ monkeypatch.setenv("REPOWISE_EMBEDDING_DIMS", "abc")
+ with pytest.raises(ValueError, match="dimensions must be a positive integer"):
+ OpenAIEmbedder(api_key="k", model="local-embedder")
+
+
# ---------------------------------------------------------------------------
# Embedding
# ---------------------------------------------------------------------------
@@ -108,3 +144,44 @@ async def test_embed_passes_model_and_input():
assert captured[0]["model"] == "text-embedding-3-large"
assert captured[0]["input"] == ["test text"]
+
+
+# ---------------------------------------------------------------------------
+# Forwarding the width to the API
+# ---------------------------------------------------------------------------
+
+
+async def _capture_create_kwargs(emb: OpenAIEmbedder) -> dict:
+ captured: dict = {}
+
+ def fake_create(**kwargs):
+ captured.update(kwargs)
+ return _make_mock_response([[1.0, 0.0]])
+
+ with patch("openai.OpenAI") as mock_client:
+ mock_client.return_value.embeddings.create.side_effect = fake_create
+ await emb.embed(["text"])
+ return captured
+
+
+# The behaviour is model-agnostic: an override is declared *and* requested from
+# the API for any model; the model names below are only illustrative inputs.
+ "model",
+ ["text-embedding-3-small", "text-embedding-ada-002", "local-embedder"],
+)
+async def test_overridden_width_is_declared_and_sent(monkeypatch, model):
+ monkeypatch.setenv("REPOWISE_EMBEDDING_DIMS", "512")
+ emb = OpenAIEmbedder(api_key="k", model=model)
+ assert emb.dimensions == 512
+ kwargs = await _capture_create_kwargs(emb)
+ assert kwargs["dimensions"] == 512
+
+
+async def test_default_request_omits_dimensions():
+ # No override → the request stays byte-identical: no dimensions key, so a
+ # server that would reject the parameter is never sent it.
+ kwargs = await _capture_create_kwargs(
+ OpenAIEmbedder(api_key="k", model="text-embedding-3-small")
+ )
+ assert "dimensions" not in kwargs