Skip to content

armgit / camel

Public Imported from GitHub
0

🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org

Jina reranking (#3788)

Yug Borana504855984cd1
diff --git a/camel/retrievers/__init__.py b/camel/retrievers/__init__.py
index 00f7765bd..45e0f17a9 100644
--- a/camel/retrievers/__init__.py
+++ b/camel/retrievers/__init__.py
@@ -15,6 +15,7 @@
from .auto_retriever import AutoRetriever
from .base import BaseRetriever
from .bm25_retriever import BM25Retriever
+from .jina_rerank_retriever import JinaRerankRetriever
from .cohere_rerank_retriever import CohereRerankRetriever
from .vector_retriever import VectorRetriever
from .hybrid_retrival import HybridRetriever
@@ -24,6 +25,7 @@ __all__ = [
'VectorRetriever',
'AutoRetriever',
'BM25Retriever',
+ 'JinaRerankRetriever',
'CohereRerankRetriever',
'HybridRetriever',
]
diff --git a/camel/retrievers/jina_rerank_retriever.py b/camel/retrievers/jina_rerank_retriever.py
new file mode 100644
index 000000000..9f709a706
--- /dev/null
+++ b/camel/retrievers/jina_rerank_retriever.py
@@ -0,0 +1,146 @@
+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========
+import os
+from typing import Any, Dict, List, Union
+
+import requests
+
+from camel.retrievers import BaseRetriever
+from camel.types.enums import JinaRerankerModelType
+
+DEFAULT_TOP_K_RESULTS = 1
+JINA_RERANK_API_URL = "https://api.jina.ai/v1/rerank"
+
+
+class JinaRerankRetriever(BaseRetriever):
+ r"""An implementation of the `BaseRetriever` using the `Jina AI Reranker`
+ model.
+
+ This retriever uses Jina AI's reranking API to re-order retrieved documents
+ based on their relevance to the query. It supports multilingual retrieval
+ across 100+ languages.
+
+ Attributes:
+ model_name (Union[JinaRerankerModelType, str]): The model name to use
+ for re-ranking.
+ api_key (str, optional): The API key for authenticating with the
+ Jina AI service.
+
+ References:
+ https://jina.ai/reranker/
+ """
+
+ def __init__(
+ self,
+ model_name: Union[JinaRerankerModelType, str] = (
+ JinaRerankerModelType.JINA_RERANKER_V2_BASE_MULTILINGUAL
+ ),
+ api_key: str | None = None,
+ ) -> None:
+ r"""Initializes an instance of the JinaRerankRetriever. This
+ constructor sets up the API key for interacting with the Jina AI
+ Reranker API.
+
+ Args:
+ model_name (Union[JinaRerankerModelType, str]): The name of the
+ model to be used for re-ranking. Can be a JinaRerankerModelType
+ enum value or a string. Defaults to
+ `JinaRerankerModelType.JINA_RERANKER_V2_BASE_MULTILINGUAL`.
+ api_key (Optional[str]): The API key for authenticating requests
+ to the Jina AI API. If not provided, the method will attempt to
+ retrieve the key from the environment variable 'JINA_API_KEY'.
+
+ Raises:
+ ValueError: If the API key is neither passed as an argument nor
+ set in the environment variable.
+ """
+ self.api_key = api_key or os.environ.get("JINA_API_KEY")
+ if not self.api_key:
+ raise ValueError(
+ "Must pass in Jina API key or specify via JINA_API_KEY"
+ " environment variable."
+ )
+ # Handle both enum and string values for model_name
+ if isinstance(model_name, JinaRerankerModelType):
+ self.model_name = model_name.value
+ else:
+ self.model_name = model_name
+
+ def query(
+ self,
+ query: str,
+ retrieved_result: list[dict[str, Any]],
+ top_k: int = DEFAULT_TOP_K_RESULTS,
+ ) -> List[Dict[str, Any]]:
+ r"""Queries and compiles results using the Jina AI re-ranking model.
+
+ Args:
+ query (str): Query string for information retriever.
+ retrieved_result (List[Dict[str, Any]]): The content to be
+ re-ranked, should be the output from `BaseRetriever` like
+ `VectorRetriever`. Each dict should have a 'text' key
+ containing the document text.
+ top_k (int, optional): The number of top results to return during
+ retrieval. Must be a positive integer. Defaults to
+ `DEFAULT_TOP_K_RESULTS`.
+
+ Returns:
+ List[Dict[str, Any]]: Concatenated list of the query results,
+ each containing the original data plus a 'similarity score'.
+
+ Raises:
+ requests.exceptions.RequestException: If the API request fails.
+ """
+ # Extract text content for reranking
+ documents = []
+ for item in retrieved_result:
+ if isinstance(item, dict):
+ # Try common keys for text content
+ text = item.get('text') or item.get('content') or str(item)
+ else:
+ text = str(item)
+ documents.append(text)
+
+ headers = {
+ "Authorization": f"Bearer {self.api_key}",
+ "Content-Type": "application/json",
+ }
+
+ payload = {
+ "model": self.model_name,
+ "query": query,
+ "documents": documents,
+ "top_n": top_k,
+ }
+
+ response = requests.post(
+ JINA_RERANK_API_URL,
+ headers=headers,
+ json=payload,
+ timeout=30,
+ )
+ response.raise_for_status()
+
+ rerank_response = response.json()
+
+ formatted_results = []
+ for result in rerank_response.get("results", []):
+ index = result.get("index", 0)
+ relevance_score = result.get("relevance_score", 0.0)
+
+ selected_chunk = retrieved_result[index].copy()
+ selected_chunk['similarity score'] = relevance_score
+ formatted_results.append(selected_chunk)
+
+ return formatted_results
diff --git a/camel/types/__init__.py b/camel/types/__init__.py
index fd51f23a4..4a1975654 100644
--- a/camel/types/__init__.py
+++ b/camel/types/__init__.py
@@ -16,6 +16,7 @@ from .enums import (
EmbeddingModelType,
GeminiEmbeddingTaskType,
HuggingFaceRepoType,
+ JinaRerankerModelType,
ModelPlatformType,
ModelType,
OpenAIBackendRole,
@@ -83,6 +84,7 @@ __all__ = [
'ParsedChatCompletion',
'HuggingFaceRepoType',
'GeminiEmbeddingTaskType',
+ 'JinaRerankerModelType',
'NOT_GIVEN',
'NotGiven',
'BaseMCPRegistryConfig',
diff --git a/camel/types/enums.py b/camel/types/enums.py
index c25cd9f48..77c347246 100644
--- a/camel/types/enums.py
+++ b/camel/types/enums.py
@@ -2106,6 +2106,32 @@ class JinaReturnFormat(Enum):
TEXT = "text"
+class JinaRerankerModelType(str, Enum):
+ r"""Model types for Jina AI Reranker.
+
+ These models are available through the Jina AI Reranker API for
+ re-ranking documents based on their relevance to a query.
+
+ For more information, please refer to:
+ https://jina.ai/reranker/
+ """
+
+ JINA_RERANKER_V2_BASE_MULTILINGUAL = "jina-reranker-v2-base-multilingual"
+ r"""Multilingual reranker model supporting 100+ languages. (Default)"""
+
+ JINA_RERANKER_V1_BASE_EN = "jina-reranker-v1-base-en"
+ r"""English base reranker model."""
+
+ JINA_RERANKER_V1_TINY_EN = "jina-reranker-v1-tiny-en"
+ r"""Lightweight English reranker model for faster inference."""
+
+ JINA_RERANKER_V1_TURBO_EN = "jina-reranker-v1-turbo-en"
+ r"""High-performance English reranker model."""
+
+ JINA_COLBERT_V2 = "jina-colbert-v2"
+ r"""ColBERT-based reranker for token-level matching."""
+
+
class HuggingFaceRepoType(str, Enum):
DATASET = "dataset"
MODEL = "model"
diff --git a/examples/retrievers/jina_rerank_example.py b/examples/retrievers/jina_rerank_example.py
new file mode 100644
index 000000000..85a234de3
--- /dev/null
+++ b/examples/retrievers/jina_rerank_example.py
@@ -0,0 +1,106 @@
+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========
+"""
+Example demonstrating the use of JinaRerankRetriever for re-ranking
+retrieved documents using Jina AI's reranker model.
+
+Prerequisites:
+ - Set `JINA_API_KEY` environment variable or pass it directly
+ - Get your API key from https://jina.ai/
+
+Usage:
+ python examples/retrievers/jina_rerank_example.py
+"""
+
+from camel.retrievers import JinaRerankRetriever
+
+
+def main():
+ # Sample documents to demonstrate reranking
+ sample_documents = [
+ {
+ 'text': """CAMEL is an open-source library for building
+ communicative AI agents. It enables multi-agent collaboration
+ through role-playing and task decomposition.""",
+ 'metadata': {'source': 'camel_docs', 'page': 1},
+ },
+ {
+ 'text': """The weather forecast shows sunny skies with
+ temperatures reaching 75°F. A perfect day for outdoor
+ activities and picnics.""",
+ 'metadata': {'source': 'weather', 'page': 1},
+ },
+ {
+ 'text': """AI alignment research focuses on ensuring that
+ artificial intelligence systems behave in accordance with
+ human values and intentions. This is crucial for safe AI
+ development.""",
+ 'metadata': {'source': 'ai_safety', 'page': 1},
+ },
+ {
+ 'text': """Large language models have revolutionized natural
+ language processing. They can understand and generate
+ human-like text across many domains.""",
+ 'metadata': {'source': 'llm_overview', 'page': 1},
+ },
+ {
+ 'text': """Multi-agent systems allow multiple AI entities to
+ work together on complex tasks. CAMEL provides tools for
+ building such collaborative agent frameworks.""",
+ 'metadata': {'source': 'multi_agent', 'page': 1},
+ },
+ ]
+
+ # Initialize the Jina Reranker
+ # API key will be read from JINA_API_KEY environment variable
+ jina_reranker = JinaRerankRetriever(
+ model_name="jina-reranker-v2-base-multilingual"
+ )
+
+ # Query to search for
+ query = "How do AI agents collaborate in CAMEL framework?"
+
+ print(f"Query: {query}\n")
+ print("=" * 60)
+
+ # Before reranking - show original order
+ print("\nOriginal document order (by initial retrieval):")
+ for i, doc in enumerate(sample_documents):
+ print(f" {i + 1}. {doc['text'][:80]}...")
+
+ # Rerank the documents using Jina AI
+ print("\n" + "=" * 60)
+ print("\nReranked results (by Jina AI relevance):")
+
+ reranked_results = jina_reranker.query(
+ query=query,
+ retrieved_result=sample_documents,
+ top_k=3, # Return top 3 most relevant
+ )
+
+ for i, result in enumerate(reranked_results):
+ print(f"\n Rank {i + 1} (Score: {result['similarity score']:.4f}):")
+ print(f" Source: {result['metadata']['source']}")
+ print(f" Text: {result['text'][:100]}...")
+
+ print("\n" + "=" * 60)
+ print("\nThe reranker has reordered documents by relevance to the query.")
+ print(
+ "Notice how documents about CAMEL and multi-agent"
+ "systems are ranked higher."
+ )
+
+
+if __name__ == "__main__":
+ main()
diff --git a/test/retrievers/test_jina_rerank_retriever.py b/test/retrievers/test_jina_rerank_retriever.py
new file mode 100644
index 000000000..a166e0fe2
--- /dev/null
+++ b/test/retrievers/test_jina_rerank_retriever.py
@@ -0,0 +1,167 @@
+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========
+import os
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from camel.retrievers import JinaRerankRetriever
+
+
+def test_initialization():
+ with patch.dict(os.environ, {"JINA_API_KEY": "test_key"}):
+ retriever = JinaRerankRetriever()
+ assert retriever.model_name == "jina-reranker-v2-base-multilingual"
+ assert retriever.api_key == "test_key"
+
+
+def test_initialization_with_custom_model():
+ with patch.dict(os.environ, {"JINA_API_KEY": "test_key"}):
+ retriever = JinaRerankRetriever(model_name="jina-reranker-v1-base-en")
+ assert retriever.model_name == "jina-reranker-v1-base-en"
+
+
+def test_initialization_without_api_key():
+ with patch.dict(os.environ, {}, clear=True):
+ # Remove the JINA_API_KEY if it exists
+ os.environ.pop("JINA_API_KEY", None)
+ with pytest.raises(ValueError, match="Must pass in Jina API key"):
+ JinaRerankRetriever()
+
+
+def test_initialization_with_explicit_api_key():
+ retriever = JinaRerankRetriever(api_key="explicit_key")
+ assert retriever.api_key == "explicit_key"
+
+
+def jina_rerank():
+ return JinaRerankRetriever(api_key="test_key")
+
+
+def mock_retrieved_result():
+ return [
+ {
+ 'similarity score': 0.85,
+ 'content path': "/path/to/doc1.pdf",
+ 'metadata': {
+ 'filetype': 'application/pdf',
+ 'page_number': 1,
+ },
+ 'text': """CAMEL is a framework for building multi-agent systems.
+ It provides tools for creating autonomous AI agents that can
+ collaborate and communicate effectively.""",
+ },
+ {
+ 'similarity score': 0.75,
+ 'content path': "/path/to/doc2.pdf",
+ 'metadata': {
+ 'filetype': 'application/pdf',
+ 'page_number': 5,
+ },
+ 'text': """The weather today is sunny with a high of 75 degrees.
+ Perfect conditions for outdoor activities.""",
+ },
+ {
+ 'similarity score': 0.70,
+ 'content path': "/path/to/doc3.pdf",
+ 'metadata': {
+ 'filetype': 'application/pdf',
+ 'page_number': 10,
+ },
+ 'text': """Developing aligned AI systems is crucial for achieving
+ desired objectives while avoiding unintended consequences.
+ Research in AI alignment focuses on safety and ethics.""",
+ },
+ ]
+
+
+@patch('requests.post')
+def test_query(mock_post, jina_rerank, mock_retrieved_result):
+ # Create mock response
+ mock_response = MagicMock()
+ mock_response.json.return_value = {
+ "results": [
+ {"index": 2, "relevance_score": 0.95},
+ {"index": 0, "relevance_score": 0.88},
+ ]
+ }
+ mock_response.raise_for_status = MagicMock()
+ mock_post.return_value = mock_response
+
+ query = "AI alignment and safety research"
+ result = jina_rerank.query(
+ query=query, retrieved_result=mock_retrieved_result, top_k=2
+ )
+
+ # Verify the request was called correctly
+ mock_post.assert_called_once()
+ call_args = mock_post.call_args
+ assert call_args[0][0] == "https://api.jina.ai/v1/rerank"
+ assert call_args[1]["headers"]["Authorization"] == "Bearer test_key"
+ assert call_args[1]["json"]["query"] == query
+ assert call_args[1]["json"]["top_n"] == 2
+ assert (
+ call_args[1]["json"]["model"] == "jina-reranker-v2-base-multilingual"
+ )
+
+ # Verify results
+ assert len(result) == 2
+ assert result[0]["similarity score"] == 0.95
+ assert "AI alignment" in result[0]["text"]
+ assert result[1]["similarity score"] == 0.88
+ assert "CAMEL" in result[1]["text"]
+
+
+@patch('requests.post')
+def test_query_with_content_key(mock_post, jina_rerank):
+ # Test with 'content' key instead of 'text'
+ retrieved_result = [
+ {'content': 'Document about machine learning', 'id': 1},
+ {'content': 'Document about deep learning', 'id': 2},
+ ]
+
+ mock_response = MagicMock()
+ mock_response.json.return_value = {
+ "results": [{"index": 0, "relevance_score": 0.9}]
+ }
+ mock_response.raise_for_status = MagicMock()
+ mock_post.return_value = mock_response
+
+ result = jina_rerank.query(
+ query="machine learning", retrieved_result=retrieved_result, top_k=1
+ )
+
+ assert len(result) == 1
+ assert result[0]["similarity score"] == 0.9
+
+
+@patch('requests.post')
+def test_query_default_top_k(mock_post, jina_rerank, mock_retrieved_result):
+ mock_response = MagicMock()
+ mock_response.json.return_value = {
+ "results": [{"index": 0, "relevance_score": 0.85}]
+ }
+ mock_response.raise_for_status = MagicMock()
+ mock_post.return_value = mock_response
+
+ # Don't pass top_k, should default to 1
+ result = jina_rerank.query(
+ query="test query", retrieved_result=mock_retrieved_result
+ )
+
+ call_args = mock_post.call_args
+ assert call_args[1]["json"]["top_n"] == 1
+ assert len(result) == 1