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(embedding): declare a model's width without sending dimensions (#1857)
NullSense3adea76e3ec0
diff --git a/packages/core/src/repowise/core/providers/embedding/openai.py b/packages/core/src/repowise/core/providers/embedding/openai.pyindex 11a5a1269..adf23efb0 100644--- a/packages/core/src/repowise/core/providers/embedding/openai.py+++ b/packages/core/src/repowise/core/providers/embedding/openai.py@@ -22,7 +22,13 @@ Dimensions:text-embedding-ada-002 → 1536 dimsREPOWISE_EMBEDDING_DIMS (or the ``dimensions`` arg) overrides the width and- is passed to the API so the returned vectors match. See ``OpenAIEmbedder``.+ is passed to the API so the returned vectors match — for a model that+ supports a variable (Matryoshka) width.++ REPOWISE_EMBEDDING_DECLARED_DIMS (or the ``declared_dimensions`` arg)+ overrides the width *without* passing it to the API, for a model whose+ width is fixed and that rejects the ``dimensions`` parameter outright.+ See ``OpenAIEmbedder``."""from __future__ import annotations@@ -44,9 +50,18 @@ class OpenAIEmbedder:base_url: Optional custom base URL for OpenAI-compatible endpoints.dimensions: Output width for a model not in ``_DIMS`` (e.g. a localOpenAI-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.+ then to ``declared_dimensions``, then to the known-model table,+ then 1536. Also sent to the API as the ``dimensions`` parameter,+ for a model that supports reshaping its output (Matryoshka); an+ endpoint that does not implement the parameter ignores it.+ declared_dimensions: Output width for a model whose width is fixed+ and that rejects the ``dimensions`` parameter — e.g. NVIDIA's+ Nemotron-3-Embed-1B, which 400s with "does not support Matryoshka+ embeddings; dimensions must be unset" if it's sent at all. Falls+ back to REPOWISE_EMBEDDING_DECLARED_DIMS. Unlike ``dimensions``,+ never sent to the API — it only tells this adapter, and therefore+ the vector store, what width to expect. Ignored when ``dimensions``+ (or REPOWISE_EMBEDDING_DIMS) is also set."""_DIMS: ClassVar[dict[str, int]] = {@@ -66,6 +81,7 @@ class OpenAIEmbedder:timeout: float | None = None,base_url: str | None = None,dimensions: int | None = None,+ declared_dimensions: int | None = None,) -> None:self._api_key = api_key or os.environ.get("OPENAI_API_KEY")if not self._api_key:@@ -77,47 +93,70 @@ class OpenAIEmbedder:self._timeout = resolve_embedding_timeout(timeout, self._DEFAULT_TIMEOUT, provider_env="OPENAI_EMBEDDING_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)+ # When the user overrides the width via `dimensions`, 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.+ #+ # `declared_dimensions` exists for the model that can't honour it and+ # doesn't reject it loudly either — it rejects the request outright,+ # because the parameter asks for reshaping (Matryoshka) support the+ # model doesn't have. There, the only way to tell repowise the real+ # width is to declare it without ever sending it. Neither knob hardcodes+ # a model name: the operator declares the width for whatever model+ # they're pointing at, and the endpoint decides what it accepts.+ self._dimensions, self._request_dimensions, self._dims_declared_only = (+ self._resolve_dimensions(dimensions, declared_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)``.+ def _resolve_dimensions(+ cls, dimensions: int | None, declared_dimensions: int | None, model: str+ ) -> tuple[int, int | None, bool]:+ """Resolve ``(declared_width, request_override, declared_only)``.- ``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.+ ``request_override`` is the value to send the API as the ``dimensions``+ parameter, or ``None`` to keep the request byte-identical to the stock+ call. ``declared_only`` is True when the width came from+ ``declared_dimensions`` / ``REPOWISE_EMBEDDING_DECLARED_DIMS`` rather+ than from ``dimensions`` / ``REPOWISE_EMBEDDING_DIMS`` or the ``_DIMS``+ table — kept only so :meth:`embed`'s width-mismatch error can name the+ setting that actually chose the number.++ Precedence for the declared width: explicit ``dimensions=`` >+ ``REPOWISE_EMBEDDING_DIMS`` > explicit ``declared_dimensions=`` >+ ``REPOWISE_EMBEDDING_DECLARED_DIMS`` > the ``_DIMS`` table > 1536.+ The first two are also requested from the API; the last three never+ are, ``_DIMS`` because it is not a user override at all, and+ ``declared_dimensions`` because it exists specifically for a model+ that must never receive the parameter.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+ ``_DIMS``; without a declared width its width would silently default to+ 1536 and mismatch the store. Mirrors the Ollama/Gemini embedders, whichalready 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+ dimensions = _parse_dimensions_env(env)+ if dimensions is not None:+ width = _validate_dimensions(dimensions)+ return width, width, False++ if declared_dimensions is None:+ env = os.environ.get("REPOWISE_EMBEDDING_DECLARED_DIMS")+ if env:+ declared_dimensions = _parse_dimensions_env(env)+ if declared_dimensions is not None:+ width = _validate_dimensions(declared_dimensions)+ return width, None, True++ return cls._DIMS.get(model, 1536), None, False@propertydef dimensions(self) -> int:@@ -142,6 +181,7 @@ class OpenAIEmbedder:timeout = self._timeoutrequest_dimensions = self._request_dimensionsexpected_dimensions = self._dimensions+ dims_declared_only = self._dims_declared_onlydef _embed_sync() -> list[list[float]]:import openai # type: ignore[import-untyped]@@ -166,22 +206,52 @@ class OpenAIEmbedder:f"Set REPOWISE_EMBEDDING_DIMS={actual} to match the server's"f" native output, or remove the override to use the model's default.")+ elif dims_declared_only:+ hint = (+ f"The width {expected_dimensions} came from REPOWISE_EMBEDDING_DECLARED_DIMS"+ f" (or declared_dimensions=), which is deliberately never sent as the API's"+ f" 'dimensions' parameter. Set it to {actual} to match what the server"+ f" actually returns, or — if this endpoint does accept the parameter after"+ f" all — switch to REPOWISE_EMBEDDING_DIMS={actual} instead."+ )else:hint = (f"The width {expected_dimensions} came from the built-in _DIMS table for"f" {model!r}. Add or update OpenAIEmbedder._DIMS[{model!r}] = {actual},"f" or set REPOWISE_EMBEDDING_DIMS={actual}.")+ reason = (+ "The endpoint likely ignored the 'dimensions' parameter."+ if request_dimensions is not None+ else "Nothing told this endpoint to produce that width — it never was."+ )raise ValueError(f"OpenAIEmbedder declared {expected_dimensions}-dimensional vectors but the"- f" API returned {actual} (model={model!r}). The endpoint likely ignored"- f" the 'dimensions' parameter. {hint}"+ f" API returned {actual} (model={model!r}). {reason} {hint}")return [_l2_normalize(v) for v in raw_vectors]return await asyncio.to_thread(_embed_sync)+def _validate_dimensions(value: int) -> int:+ """Raise the one message every bad width — explicit or from env — shares."""+ if isinstance(value, bool) or not isinstance(value, int) or value <= 0:+ raise ValueError("dimensions must be a positive integer")+ return value+++def _parse_dimensions_env(raw: str) -> int:+ """Parse an env var's dimensions value, or raise the same message a bad+ explicit ``dimensions=`` / ``declared_dimensions=`` does.+ """+ try:+ parsed = int(raw)+ except ValueError:+ raise ValueError("dimensions must be a positive integer") from None+ return _validate_dimensions(parsed)++def _l2_normalize(vec: list[float]) -> list[float]:"""L2-normalize a vector to unit length (cosine similarity = dot product)."""norm = math.sqrt(sum(x * x for x in vec))diff --git a/tests/unit/test_persistence/test_openai_embedder.py b/tests/unit/test_persistence/test_openai_embedder.pyindex ab066965b..70623182a 100644--- a/tests/unit/test_persistence/test_openai_embedder.py+++ b/tests/unit/test_persistence/test_openai_embedder.py@@ -82,6 +82,61 @@ def test_malformed_env_raises_the_same_message(monkeypatch):OpenAIEmbedder(api_key="k", model="local-embedder")+# ---------------------------------------------------------------------------+# declared_dimensions / REPOWISE_EMBEDDING_DECLARED_DIMS — declare a width+# without ever sending it, for a model that rejects the 'dimensions' param.+# ---------------------------------------------------------------------------+++def test_declared_dimensions_sets_width_without_a_dimensions_override():+ emb = OpenAIEmbedder(api_key="k", model="nemotron-embed-1b", declared_dimensions=2048)+ assert emb.dimensions == 2048+ assert emb._request_dimensions is None+++def test_declared_dimensions_from_env(monkeypatch):+ monkeypatch.setenv("REPOWISE_EMBEDDING_DECLARED_DIMS", "2048")+ emb = OpenAIEmbedder(api_key="k", model="nemotron-embed-1b")+ assert emb.dimensions == 2048+ assert emb._request_dimensions is None+++def test_dimensions_arg_beats_declared_dimensions_arg():+ # A model that DOES accept the parameter still takes the send-it path when+ # both are given — declared_dimensions is the fallback for one that can't.+ emb = OpenAIEmbedder(+ api_key="k", model="local-embedder", dimensions=1024, declared_dimensions=2048+ )+ assert emb.dimensions == 1024+ assert emb._request_dimensions == 1024+++def test_embedding_dims_env_beats_declared_dimensions_env(monkeypatch):+ monkeypatch.setenv("REPOWISE_EMBEDDING_DIMS", "1024")+ monkeypatch.setenv("REPOWISE_EMBEDDING_DECLARED_DIMS", "2048")+ emb = OpenAIEmbedder(api_key="k", model="local-embedder")+ assert emb.dimensions == 1024+ assert emb._request_dimensions == 1024+++def test_declared_dimensions_arg_beats_declared_dimensions_env(monkeypatch):+ monkeypatch.setenv("REPOWISE_EMBEDDING_DECLARED_DIMS", "4096")+ emb = OpenAIEmbedder(api_key="k", model="nemotron-embed-1b", declared_dimensions=2048)+ assert emb.dimensions == 2048++[email protected]("bad", [0, -5, True])+def test_invalid_declared_dimensions_raises(bad):+ with pytest.raises(ValueError, match="dimensions must be a positive integer"):+ OpenAIEmbedder(api_key="k", model="nemotron-embed-1b", declared_dimensions=bad)+++def test_malformed_declared_dimensions_env_raises_the_same_message(monkeypatch):+ monkeypatch.setenv("REPOWISE_EMBEDDING_DECLARED_DIMS", "abc")+ with pytest.raises(ValueError, match="dimensions must be a positive integer"):+ OpenAIEmbedder(api_key="k", model="nemotron-embed-1b")++def test_timeout_from_shared_env(monkeypatch):monkeypatch.setenv("REPOWISE_EMBEDDING_TIMEOUT", "180")assert OpenAIEmbedder(api_key="k", model="local-embedder")._timeout == 180.0@@ -230,6 +285,37 @@ async def test_default_request_omits_dimensions():assert "dimensions" not in kwargs+async def test_declared_only_width_is_never_sent():+ emb = OpenAIEmbedder(api_key="k", model="nemotron-embed-1b", declared_dimensions=2048)+ kwargs = await _capture_create_kwargs(emb)+ assert "dimensions" not in kwargs+++async def test_declared_only_width_is_never_sent_even_to_a_strict_endpoint():+ # nvidia/Nemotron-3-Embed-1B's own behaviour, reproduced: a fake endpoint+ # that 400s the instant 'dimensions' shows up in the request at all, since+ # the model isn't Matryoshka-capable and has no default width to fall back+ # to. This is the case _DIMS/REPOWISE_EMBEDDING_DIMS cannot serve — sending+ # the override at all breaks the request, so the only usable path is one+ # that declares the width without ever asking the API to produce it.+ emb = OpenAIEmbedder(api_key="k", model="nemotron-embed-1b", declared_dimensions=2048)++ def fake_create(**kwargs):+ if "dimensions" in kwargs:+ raise ValueError(+ "Model 'nemotron-embed-1b' does not support Matryoshka embeddings; "+ "dimensions must be unset"+ )+ return _make_mock_response([[1.0] + [0.0] * 2047])++ with patch("openai.OpenAI") as mock_client:+ mock_client.return_value.embeddings.create.side_effect = fake_create+ result = await emb.embed(["hello"])++ assert len(result) == 1+ assert len(result[0]) == 2048++# ---------------------------------------------------------------------------# Width verification — the check added in fix/embedder-width-verification# ---------------------------------------------------------------------------@@ -273,6 +359,26 @@ async def test_embed_raises_when_api_returns_wrong_width_with_user_override(monkassert "REPOWISE_EMBEDDING_DIMS" in msg+async def test_embed_raises_when_api_returns_wrong_width_with_declared_only_override(monkeypatch):+ # Declared via declared_dimensions= (never sent). The error message should+ # reference REPOWISE_EMBEDDING_DECLARED_DIMS, not _DIMS or the sent-width+ # hint — neither would tell this user what to change.+ emb = OpenAIEmbedder(api_key="k", model="nemotron-embed-1b", declared_dimensions=2048)+ assert emb.dimensions == 2048++ with patch("openai.OpenAI") as mock_client:+ mock_client.return_value.embeddings.create.return_value = _make_mock_response(+ [[1.0, 0.0, 0.0]]+ )+ with pytest.raises(ValueError, match="2048") as exc_info:+ await emb.embed(["hello"])++ msg = str(exc_info.value)+ assert "3" in msg+ assert "REPOWISE_EMBEDDING_DECLARED_DIMS" in msg+ assert "_DIMS table" not in msg++async def test_embed_width_check_is_skipped_for_empty_response():# embed([]) short-circuits before the API call and returns []; the guard# must not fire on the empty list itself.