🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org
Python agentai-societiesartificial-intelligencecommunicative-aicooperative-aideep-learninglarge-language-modelsmulti-agent-systemsnatural-language-processing
Jina reranking (#3788)
Yug Borana504855984cd1
diff --git a/camel/retrievers/__init__.py b/camel/retrievers/__init__.pyindex 00f7765bd..45e0f17a9 100644--- a/camel/retrievers/__init__.py+++ b/camel/retrievers/__init__.py@@ -15,6 +15,7 @@from .auto_retriever import AutoRetrieverfrom .base import BaseRetrieverfrom .bm25_retriever import BM25Retriever+from .jina_rerank_retriever import JinaRerankRetrieverfrom .cohere_rerank_retriever import CohereRerankRetrieverfrom .vector_retriever import VectorRetrieverfrom .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.pynew file mode 100644index 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_resultsdiff --git a/camel/types/__init__.py b/camel/types/__init__.pyindex 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.pyindex 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.pynew file mode 100644index 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.pynew file mode 100644index 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