Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
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.pyindex 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 dimstext-embedding-3-large → 3072 dimstext-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 annotationsimport asyncioimport mathimport os-from typing import ClassVar+from typing import Any, ClassVarclass 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 = modelself._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+@propertydef dimensions(self) -> int:- return self._DIMS.get(self._model, 1536)+ return self._dimensionsasync def embed(self, texts: list[str]) -> list[list[float]]:"""Embed a batch of texts using OpenAI.@@ -86,6 +135,7 @@ class OpenAIEmbedder:model = self._modeltimeout = self._timeout+ request_dimensions = self._request_dimensionsdef _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.pyindex 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 isrecovered from the repo/global config so the server matches the index itdiff --git a/tests/unit/test_persistence/test_openai_embedder.py b/tests/unit/test_persistence/test_openai_embedder.pyindex 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