Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
"""Tests for Jina AI Embedder"""
from unittest.mock import MagicMock, patch
import pytest
from openviking.models.embedder import JinaDenseEmbedder
from openviking.models.embedder.jina_embedders import (
JINA_MODEL_DIMENSIONS,
)
from openviking.models.model_error import ModelError, ModelErrorKind
from openviking_cli.utils.config.embedding_config import EmbeddingModelConfig
class TestJinaDenseEmbedder:
"""Test cases for JinaDenseEmbedder"""
def test_init_requires_api_key(self):
"""Test that api_key is required"""
with pytest.raises(ValueError, match="api_key is required"):
JinaDenseEmbedder(model_name="jina-embeddings-v5-text-small")
def test_init_with_api_key(self):
"""Test initialization with api_key"""
embedder = JinaDenseEmbedder(
model_name="jina-embeddings-v5-text-small",
api_key="test-api-key",
)
assert embedder.api_key == "test-api-key"
assert embedder.model_name == "jina-embeddings-v5-text-small"
assert embedder.api_base == "https://api.jina.ai/v1"
def test_init_with_custom_api_base(self):
"""Test initialization with custom api_base"""
embedder = JinaDenseEmbedder(
model_name="jina-embeddings-v5-text-small",
api_key="test-api-key",
api_base="https://custom.api.jina.ai/v1",
)
assert embedder.api_base == "https://custom.api.jina.ai/v1"
def test_default_dimension_v5_small(self):
"""Test default dimension for jina-embeddings-v5-text-small"""
embedder = JinaDenseEmbedder(
model_name="jina-embeddings-v5-text-small",
api_key="test-api-key",
)
assert embedder.get_dimension() == 1024
def test_default_dimension_v5_nano(self):
"""Test default dimension for jina-embeddings-v5-text-nano"""
embedder = JinaDenseEmbedder(
model_name="jina-embeddings-v5-text-nano",
api_key="test-api-key",
)
assert embedder.get_dimension() == 768
def test_custom_dimension(self):
"""Test custom dimension for Matryoshka reduction"""
embedder = JinaDenseEmbedder(
model_name="jina-embeddings-v5-text-small",
api_key="test-api-key",
dimension=256,
)
assert embedder.get_dimension() == 256
def test_model_dimensions_constant(self):
"""Test JINA_MODEL_DIMENSIONS constant"""
assert "jina-embeddings-v5-text-small" in JINA_MODEL_DIMENSIONS
assert "jina-embeddings-v5-text-nano" in JINA_MODEL_DIMENSIONS
assert JINA_MODEL_DIMENSIONS["jina-embeddings-v5-text-small"] == 1024
assert JINA_MODEL_DIMENSIONS["jina-embeddings-v5-text-nano"] == 768
@patch("openviking.models.embedder.jina_embedders.openai.OpenAI")
def test_embed_single_text(self, mock_openai_class):
"""Test embedding a single text"""
# Setup mock
mock_client = MagicMock()
mock_openai_class.return_value = mock_client
mock_embedding = MagicMock()
mock_embedding.embedding = [0.1] * 1024
mock_response = MagicMock()
mock_response.data = [mock_embedding]
mock_client.embeddings.create.return_value = mock_response
# Create embedder and embed
embedder = JinaDenseEmbedder(
model_name="jina-embeddings-v5-text-small",
api_key="test-api-key",
)
result = embedder.embed("Hello world")
# Verify
assert result.dense_vector is not None
assert len(result.dense_vector) == 1024
mock_client.embeddings.create.assert_called_once()
@patch("openviking.models.embedder.jina_embedders.openai.OpenAI")
def test_embed_with_dimension(self, mock_openai_class):
"""Test embedding with custom dimension parameter"""
mock_client = MagicMock()
mock_openai_class.return_value = mock_client
mock_embedding = MagicMock()
mock_embedding.embedding = [0.1] * 768
mock_response = MagicMock()
mock_response.data = [mock_embedding]
mock_client.embeddings.create.return_value = mock_response
embedder = JinaDenseEmbedder(
model_name="jina-embeddings-v5-text-small",
api_key="test-api-key",
dimension=768,
)
embedder.embed("Hello world")
# Check dimensions was passed
call_kwargs = mock_client.embeddings.create.call_args[1]
assert call_kwargs["dimensions"] == 768
@patch("openviking.models.embedder.jina_embedders.openai.OpenAI")
def test_embed_with_task(self, mock_openai_class):
"""Jina embedder should include task in extra_body when configured."""
mock_client = MagicMock()
mock_openai_class.return_value = mock_client
mock_embedding = MagicMock()
mock_embedding.embedding = [0.1] * 1024
mock_response = MagicMock()
mock_response.data = [mock_embedding]
mock_client.embeddings.create.return_value = mock_response
# Pass task directly
embedder = JinaDenseEmbedder(
model_name="jina-embeddings-v5-text-small",
api_key="test-api-key",
query_param="retrieval.query",
)
embedder.embed("Hello world", is_query=True)
call_kwargs = mock_client.embeddings.create.call_args[1]
assert "extra_body" in call_kwargs
assert call_kwargs["extra_body"]["task"] == "retrieval.query"
@patch("openviking.models.embedder.jina_embedders.openai.OpenAI")
def test_code_model_uses_code_task_defaults(self, mock_openai_class):
"""Jina code models should use code-specific default task names."""
mock_client = MagicMock()
mock_openai_class.return_value = mock_client
mock_embedding = MagicMock()
mock_embedding.embedding = [0.1] * 1024
mock_response = MagicMock()
mock_response.data = [mock_embedding]
mock_client.embeddings.create.return_value = mock_response
embedder = JinaDenseEmbedder(
model_name="jina-code-embeddings-1.5b",
api_key="test-api-key",
)
embedder.embed("Write a binary search in Python", is_query=True)
call_kwargs = mock_client.embeddings.create.call_args[1]
assert call_kwargs["extra_body"]["task"] == "nl2code.query"
@patch("openviking.models.embedder.jina_embedders.openai.OpenAI")
def test_code_model_keeps_explicit_task_override(self, mock_openai_class):
"""Explicit task params should override the model-specific defaults."""
mock_client = MagicMock()
mock_openai_class.return_value = mock_client
mock_embedding = MagicMock()
mock_embedding.embedding = [0.1] * 1024
mock_response = MagicMock()
mock_response.data = [mock_embedding]
mock_client.embeddings.create.return_value = mock_response
embedder = JinaDenseEmbedder(
model_name="jina-code-embeddings-1.5b",
api_key="test-api-key",
query_param="custom.query",
document_param="custom.passage",
)
embedder.embed("Write a binary search in Python", is_query=True)
call_kwargs = mock_client.embeddings.create.call_args[1]
assert call_kwargs["extra_body"]["task"] == "custom.query"
@patch("openviking.models.embedder.jina_embedders.openai.OpenAI")
def test_embed_with_late_chunking(self, mock_openai_class):
"""Test embedding with late_chunking parameter"""
mock_client = MagicMock()
mock_openai_class.return_value = mock_client
mock_embedding = MagicMock()
mock_embedding.embedding = [0.1] * 1024
mock_response = MagicMock()
mock_response.data = [mock_embedding]
mock_client.embeddings.create.return_value = mock_response
embedder = JinaDenseEmbedder(
model_name="jina-embeddings-v5-text-small",
api_key="test-api-key",
late_chunking=True,
)
embedder.embed("Hello world")
# Check extra_body was passed with late_chunking
call_kwargs = mock_client.embeddings.create.call_args[1]
assert "extra_body" in call_kwargs
assert call_kwargs["extra_body"]["late_chunking"] is True
@patch("openviking.models.embedder.jina_embedders.openai.OpenAI")
def test_embed_api_error(self, mock_openai_class):
"""Test embedding with API error"""
import openai
mock_client = MagicMock()
mock_openai_class.return_value = mock_client
error = openai.APIError(
message="Test API error",
request=MagicMock(),
body=None,
)
mock_client.embeddings.create.side_effect = error
embedder = JinaDenseEmbedder(
model_name="jina-embeddings-v5-text-small",
api_key="test-api-key",
)
with pytest.raises(ModelError, match="Jina API error") as raised:
embedder.embed("Hello world")
assert raised.value.kind is ModelErrorKind.UNKNOWN
assert raised.value.provider == "jina"
assert raised.value.__cause__.__cause__ is error
def test_build_extra_body_none(self):
"""Test _build_extra_body returns None when no params set"""
embedder = JinaDenseEmbedder(
model_name="jina-embeddings-v5-text-small",
api_key="test-api-key",
query_param=None,
document_param=None,
)
assert embedder._build_extra_body() is None
@patch("openviking.models.embedder.jina_embedders.openai.OpenAI")
def test_build_extra_body_with_params(self, mock_openai_class):
"""_build_extra_body should include task and late_chunking."""
mock_client = MagicMock()
mock_openai_class.return_value = mock_client
embedder = JinaDenseEmbedder(
model_name="jina-embeddings-v5-text-small",
api_key="test-api-key",
document_param="retrieval.passage",
late_chunking=True,
)
extra_body = embedder._build_extra_body(is_query=False)
assert extra_body["task"] == "retrieval.passage"
assert extra_body["late_chunking"] is True
def test_dimension_validation_exceeds_max(self):
"""Test that requesting dimension exceeding model max raises ValueError"""
with pytest.raises(ValueError, match="exceeds maximum"):
JinaDenseEmbedder(
model_name="jina-embeddings-v5-text-nano",
api_key="test-key",
dimension=1024, # nano max is 768
)
def test_dimension_validation_within_range(self):
"""Test that requesting dimension within model max works"""
embedder = JinaDenseEmbedder(
model_name="jina-embeddings-v5-text-nano",
api_key="test-key",
dimension=256,
)
assert embedder.get_dimension() == 256
@patch("openviking.models.embedder.jina_embedders.openai.OpenAI")
def test_422_task_error_actionable_message(self, mock_openai_class):
"""422 error mentioning 'task' should preserve the actionable provider message."""
import openai
mock_client = MagicMock()
mock_openai_class.return_value = mock_client
error = openai.BadRequestError(
message="Validation error",
response=MagicMock(status_code=422, headers={}),
body={"detail": "Input should be 'nl2code.query' ... task"},
)
mock_client.embeddings.create.side_effect = error
embedder = JinaDenseEmbedder(
model_name="jina-code-embeddings-1.5b",
api_key="test-key",
)
with pytest.raises(ModelError, match="query_param.*document_param"):
embedder.embed("hello")
def test_code_model_dimensions(self):
"""Code models should have correct default dimensions."""
embedder_1_5b = JinaDenseEmbedder(
model_name="jina-code-embeddings-1.5b",
api_key="test-key",
)
assert embedder_1_5b.get_dimension() == 1024
embedder_0_5b = JinaDenseEmbedder(
model_name="jina-code-embeddings-0.5b",
api_key="test-key",
)
assert embedder_0_5b.get_dimension() == 768
@pytest.mark.parametrize("model", sorted(JINA_MODEL_DIMENSIONS))
def test_config_default_dimension_matches_embedder(self, model):
"""Without an explicit dimension, the schema must match the vectors Jina returns."""
config = EmbeddingModelConfig(provider="jina", api_key="test-key", model=model)
embedder = JinaDenseEmbedder(model_name=model, api_key="test-key")
assert config.get_effective_dimension() == embedder.get_dimension()