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
"""Unit tests for OpenAIEmbedder.
All tests mock openai.OpenAI — no real API calls are made.
"""
from __future__ import annotations
import math
from unittest.mock import MagicMock, patch
import pytest
pytest.importorskip("openai", reason="openai SDK not installed")
from repowise.core.providers.embedding.openai import OpenAIEmbedder
# ---------------------------------------------------------------------------
# Construction
# ---------------------------------------------------------------------------
def test_missing_api_key_raises(monkeypatch):
monkeypatch.delenv("OPENAI_API_KEY", raising=False)
with pytest.raises(ValueError, match="OpenAI API key required"):
OpenAIEmbedder(api_key=None)
def test_api_key_from_env(monkeypatch):
monkeypatch.setenv("OPENAI_API_KEY", "sk-test")
emb = OpenAIEmbedder()
assert emb._api_key == "sk-test"
def test_dimensions_small():
emb = OpenAIEmbedder(api_key="k", model="text-embedding-3-small")
assert emb.dimensions == 1536
def test_dimensions_large():
emb = OpenAIEmbedder(api_key="k", model="text-embedding-3-large")
assert emb.dimensions == 3072
def test_dimensions_unknown_model_defaults_to_1536():
emb = OpenAIEmbedder(api_key="k", model="some-future-model")
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
@pytest.mark.parametrize("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")
# ---------------------------------------------------------------------------
# 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
@pytest.mark.parametrize("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
def test_provider_env_beats_shared_env(monkeypatch):
monkeypatch.setenv("REPOWISE_EMBEDDING_TIMEOUT", "180")
monkeypatch.setenv("OPENAI_EMBEDDING_TIMEOUT", "45")
assert OpenAIEmbedder(api_key="k", model="local-embedder")._timeout == 45.0
def test_explicit_timeout_beats_env(monkeypatch):
monkeypatch.setenv("REPOWISE_EMBEDDING_TIMEOUT", "180")
assert OpenAIEmbedder(api_key="k", model="local-embedder", timeout=5)._timeout == 5.0
def test_hosted_default_is_unchanged(monkeypatch):
# Pins the value, not the wiring: the env knob exists so this can stay put,
# since it also bounds the retried query path.
monkeypatch.delenv("REPOWISE_EMBEDDING_TIMEOUT", raising=False)
monkeypatch.delenv("OPENAI_EMBEDDING_TIMEOUT", raising=False)
assert OpenAIEmbedder(api_key="k")._timeout == 10.0
@pytest.mark.parametrize("bad", ["abc", "30s", "0", "-5", "inf", "nan"])
def test_a_malformed_env_value_falls_back_instead_of_breaking_the_run(monkeypatch, bad):
# build_embedder turns any construction error into a keyless 8-wide store,
# so raising here would make a typo silently destroy retrieval for setups
# that worked before the variable was honoured at all.
monkeypatch.setenv("REPOWISE_EMBEDDING_TIMEOUT", bad)
assert OpenAIEmbedder(api_key="k", model="local-embedder")._timeout == 10.0
@pytest.mark.parametrize("bad", [0, -5, float("inf"), float("nan"), True, "30"])
def test_an_invalid_explicit_timeout_raises(bad):
with pytest.raises(ValueError, match="timeout must be a positive number"):
OpenAIEmbedder(api_key="k", model="local-embedder", timeout=bad)
# ---------------------------------------------------------------------------
# Embedding
# ---------------------------------------------------------------------------
def _make_mock_embedding(values: list[float]) -> MagicMock:
item = MagicMock()
item.embedding = values
return item
def _make_mock_response(vectors: list[list[float]]) -> MagicMock:
response = MagicMock()
response.data = [_make_mock_embedding(v) for v in vectors]
return response
async def test_embed_empty_returns_empty():
emb = OpenAIEmbedder(api_key="k")
result = await emb.embed([])
assert result == []
async def test_embed_returns_normalized_vectors():
# dimensions=3 so the declared width matches the 3-wide fake vector.
raw = [1.0, 0.0, 0.0]
emb = OpenAIEmbedder(api_key="k", dimensions=3)
with patch("openai.OpenAI") as mock_client:
mock_client.return_value.embeddings.create.return_value = _make_mock_response([raw])
result = await emb.embed(["hello"])
assert len(result) == 1
norm = math.sqrt(sum(x * x for x in result[0]))
assert abs(norm - 1.0) < 1e-6
async def test_embed_batch_returns_correct_count():
# dimensions=2 so the declared width matches the 2-wide fake vectors.
texts = ["a", "b", "c"]
raw_vecs = [[1.0, 0.0], [0.0, 1.0], [0.707, 0.707]]
emb = OpenAIEmbedder(api_key="k", dimensions=2)
with patch("openai.OpenAI") as mock_client:
mock_client.return_value.embeddings.create.return_value = _make_mock_response(raw_vecs)
result = await emb.embed(texts)
assert len(result) == 3
async def test_embed_passes_model_and_input():
# dimensions=2 so the fake 2-wide response passes the width guard.
emb = OpenAIEmbedder(api_key="k", model="text-embedding-3-large", dimensions=2)
captured: list = []
def fake_create(**kwargs):
captured.append({"model": kwargs["model"], "input": kwargs["input"]})
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(["test text"])
assert captured[0]["model"] == "text-embedding-3-large"
assert captured[0]["input"] == ["test text"]
# ---------------------------------------------------------------------------
# kind="query"|"document" — REPOWISE_EMBED_QUERY_PREFIX / _DOC_PREFIX
# ---------------------------------------------------------------------------
async def _captured_input(emb: OpenAIEmbedder, *, kind: str) -> list[str]:
captured: dict = {}
def fake_create(**kwargs):
captured.update(kwargs)
return _make_mock_response([[1.0] + [0.0] * (emb.dimensions - 1)])
with patch("openai.OpenAI") as mock_client:
mock_client.return_value.embeddings.create.side_effect = fake_create
await emb.embed(["hello"], kind=kind)
return captured["input"]
async def test_no_prefix_configured_leaves_the_request_byte_identical(monkeypatch):
# A fresh embedder per call: OpenAIEmbedder caches its SDK client on first
# use, so a second call on the same instance would talk to the first
# call's mock, not the one this call just configured.
monkeypatch.delenv("REPOWISE_EMBED_QUERY_PREFIX", raising=False)
monkeypatch.delenv("REPOWISE_EMBED_DOC_PREFIX", raising=False)
assert await _captured_input(OpenAIEmbedder(api_key="k"), kind="query") == ["hello"]
assert await _captured_input(OpenAIEmbedder(api_key="k"), kind="document") == ["hello"]
async def test_query_prefix_applied_only_to_query_kind(monkeypatch):
monkeypatch.setenv("REPOWISE_EMBED_QUERY_PREFIX", "query: ")
monkeypatch.delenv("REPOWISE_EMBED_DOC_PREFIX", raising=False)
assert await _captured_input(OpenAIEmbedder(api_key="k"), kind="query") == ["query: hello"]
assert await _captured_input(OpenAIEmbedder(api_key="k"), kind="document") == ["hello"]
async def test_document_prefix_applied_only_to_document_kind(monkeypatch):
monkeypatch.delenv("REPOWISE_EMBED_QUERY_PREFIX", raising=False)
monkeypatch.setenv("REPOWISE_EMBED_DOC_PREFIX", "passage: ")
assert await _captured_input(OpenAIEmbedder(api_key="k"), kind="document") == [
"passage: hello"
]
assert await _captured_input(OpenAIEmbedder(api_key="k"), kind="query") == ["hello"]
async def test_prefix_applies_to_every_text_in_the_batch(monkeypatch):
monkeypatch.setenv("REPOWISE_EMBED_QUERY_PREFIX", "query: ")
monkeypatch.delenv("REPOWISE_EMBED_DOC_PREFIX", raising=False)
emb = OpenAIEmbedder(api_key="k", dimensions=1)
captured: dict = {}
def fake_create(**kwargs):
captured.update(kwargs)
return _make_mock_response([[1.0], [1.0]])
with patch("openai.OpenAI") as mock_client:
mock_client.return_value.embeddings.create.side_effect = fake_create
await emb.embed(["alpha", "beta"], kind="query")
assert captured["input"] == ["query: alpha", "query: beta"]
async def test_default_kind_is_document():
# embed()'s default kind matches the Embedder protocol's default, so a
# caller that doesn't think about retrieval direction gets the document
# framing — the safer default, since most existing callers upsert.
import inspect
sig = inspect.signature(OpenAIEmbedder.embed)
assert sig.parameters["kind"].default == "document"
# ---------------------------------------------------------------------------
# Forwarding the width to the API
# ---------------------------------------------------------------------------
async def _capture_create_kwargs(emb: OpenAIEmbedder) -> dict:
captured: dict = {}
def fake_create(**kwargs):
captured.update(kwargs)
# Return a vector of the declared width so the new width guard doesn't fire.
return _make_mock_response([[1.0] + [0.0] * (emb.dimensions - 1)])
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.
@pytest.mark.parametrize(
"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
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
# ---------------------------------------------------------------------------
async def test_embed_raises_when_api_returns_wrong_width_from_dims_table():
# Declared via _DIMS (user never chose the number). The error message should
# mention _DIMS so the user knows where to look.
emb = OpenAIEmbedder(api_key="k", model="text-embedding-3-small")
assert emb.dimensions == 1536 # from _DIMS table
with patch("openai.OpenAI") as mock_client:
# Fake API silently ignores 'dimensions' and returns its native 3-wide vector.
mock_client.return_value.embeddings.create.return_value = _make_mock_response(
[[1.0, 0.0, 0.0]]
)
with pytest.raises(ValueError, match="1536") as exc_info:
await emb.embed(["hello"])
msg = str(exc_info.value)
assert "3" in msg # actual width named
assert "_DIMS" in msg # points at the table, not the user
async def test_embed_raises_when_api_returns_wrong_width_with_user_override(monkeypatch):
# Declared via REPOWISE_EMBEDDING_DIMS (user explicitly set it). The error
# message should reference REPOWISE_EMBEDDING_DIMS so they know what to change.
monkeypatch.setenv("REPOWISE_EMBEDDING_DIMS", "512")
emb = OpenAIEmbedder(api_key="k", model="text-embedding-3-small")
assert emb.dimensions == 512 # from env override
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="512") as exc_info:
await emb.embed(["hello"])
msg = str(exc_info.value)
assert "3" in msg
assert "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.
emb = OpenAIEmbedder(api_key="k")
assert await emb.embed([]) == []