🐫 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
feat: add dependencies_required and api_keys_required decorators to camel/retrievers (#1043) (#4061)
cjp2014p20526b43e435
diff --git a/camel/retrievers/auto_retriever.py b/camel/retrievers/auto_retriever.pyindex 0376a671a..3b861839c 100644--- a/camel/retrievers/auto_retriever.py+++ b/camel/retrievers/auto_retriever.py@@ -32,7 +32,7 @@ from camel.storages import (TiDBStorage,)from camel.types import StorageType-from camel.utils import Constants+from camel.utils import Constants, dependencies_requiredif TYPE_CHECKING:from unstructured.documents.elements import Element@@ -117,6 +117,7 @@ class AutoRetriever:f"Unsupported vector storage type: {self.storage_type}")+ @dependencies_required('hashlib', 'os', 'unstructured.documents.elements')def _collection_name_generator(self, content: Union[str, "Element"]) -> str:@@ -165,6 +166,7 @@ class AutoRetriever:return collection_name+ @dependencies_required('unstructured.documents.elements')def run_vector_retriever(self,query: str,diff --git a/camel/retrievers/bm25_retriever.py b/camel/retrievers/bm25_retriever.pyindex 6818b8432..3b9d86d7a 100644--- a/camel/retrievers/bm25_retriever.py+++ b/camel/retrievers/bm25_retriever.py@@ -83,6 +83,7 @@ class BM25Retriever(BaseRetriever):else:self.bm25 = None+ @dependencies_required('numpy')def query(self,query: str,diff --git a/camel/retrievers/cohere_rerank_retriever.py b/camel/retrievers/cohere_rerank_retriever.pyindex a784d606c..6e0fa6f5b 100644--- a/camel/retrievers/cohere_rerank_retriever.py+++ b/camel/retrievers/cohere_rerank_retriever.py@@ -15,7 +15,7 @@ import osfrom typing import Any, Dict, List, Optionalfrom camel.retrievers import BaseRetriever-from camel.utils import dependencies_required+from camel.utils import api_keys_required, dependencies_requiredDEFAULT_TOP_K_RESULTS = 1@@ -34,6 +34,7 @@ class CohereRerankRetriever(BaseRetriever):"""@dependencies_required('cohere')+ @api_keys_required([("api_key", 'COHERE_API_KEY')])def __init__(self,model_name: str = "rerank-multilingual-v2.0",diff --git a/camel/retrievers/hybrid_retrival.py b/camel/retrievers/hybrid_retrival.pyindex af5098ee1..01fc35664 100644--- a/camel/retrievers/hybrid_retrival.py+++ b/camel/retrievers/hybrid_retrival.py@@ -16,6 +16,7 @@ from typing import Any, Dict, List, Optional, Unionfrom camel.embeddings import BaseEmbeddingfrom camel.retrievers import BaseRetriever, BM25Retriever, VectorRetrieverfrom camel.storages import BaseVectorStorage+from camel.utils import dependencies_requiredclass HybridRetriever(BaseRetriever):@@ -54,6 +55,7 @@ class HybridRetriever(BaseRetriever):self.vr.process(content=self.content_input_path)self.bm25.process(content_input_path=self.content_input_path)+ @dependencies_required('numpy')def _sort_rrf_scores(self,vector_retriever_results: List[Dict[str, Any]],diff --git a/camel/retrievers/jina_rerank_retriever.py b/camel/retrievers/jina_rerank_retriever.pyindex 9f709a706..8e1d68baa 100644--- a/camel/retrievers/jina_rerank_retriever.py+++ b/camel/retrievers/jina_rerank_retriever.py@@ -14,10 +14,9 @@import osfrom typing import Any, Dict, List, Union-import requests-from camel.retrievers import BaseRetrieverfrom camel.types.enums import JinaRerankerModelType+from camel.utils import api_keys_required, dependencies_requiredDEFAULT_TOP_K_RESULTS = 1JINA_RERANK_API_URL = "https://api.jina.ai/v1/rerank"@@ -41,6 +40,7 @@ class JinaRerankRetriever(BaseRetriever):https://jina.ai/reranker/"""+ @api_keys_required([("api_key", 'JINA_API_KEY')])def __init__(self,model_name: Union[JinaRerankerModelType, str] = (@@ -77,6 +77,7 @@ class JinaRerankRetriever(BaseRetriever):else:self.model_name = model_name+ @dependencies_required('requests')def query(self,query: str,@@ -102,6 +103,8 @@ class JinaRerankRetriever(BaseRetriever):Raises:requests.exceptions.RequestException: If the API request fails."""+ import requests+# Extract text content for rerankingdocuments = []for item in retrieved_result:diff --git a/camel/retrievers/vector_retriever.py b/camel/retrievers/vector_retriever.pyindex 6ecb6d5cc..daa8ee434 100644--- a/camel/retrievers/vector_retriever.py+++ b/camel/retrievers/vector_retriever.py@@ -26,7 +26,7 @@ from camel.storages import (VectorDBQuery,VectorRecord,)-from camel.utils import Constants+from camel.utils import Constants, dependencies_requiredfrom camel.utils.chunker import BaseChunker, UnstructuredIOChunkerif TYPE_CHECKING:@@ -70,6 +70,7 @@ class VectorRetriever(BaseRetriever):)self.uio: UnstructuredIO = UnstructuredIO()+ @dependencies_required('unstructured.documents.elements')def process(self,content: Union[str, "Element", IO[bytes]],diff --git a/test/retrievers/test_cohere_rerank_retriever.py b/test/retrievers/test_cohere_rerank_retriever.pyindex 69a19c103..a61427dd5 100644--- a/test/retrievers/test_cohere_rerank_retriever.py+++ b/test/retrievers/test_cohere_rerank_retriever.py@@ -19,13 +19,13 @@ from camel.retrievers import CohereRerankRetrieverdef test_initialization():- retriever = CohereRerankRetriever()+ retriever = CohereRerankRetriever(api_key="test_key")assert retriever.model_name == "rerank-multilingual-v2.0"@pytest.fixturedef cohere_rerank():- return CohereRerankRetriever()+ return CohereRerankRetriever(api_key="test_key")@pytest.fixturediff --git a/test/retrievers/test_jina_rerank_retriever.py b/test/retrievers/test_jina_rerank_retriever.pyindex a166e0fe2..19a1089ad 100644--- a/test/retrievers/test_jina_rerank_retriever.py+++ b/test/retrievers/test_jina_rerank_retriever.py@@ -36,7 +36,7 @@ def test_initialization_without_api_key():with patch.dict(os.environ, {}, clear=True):# Remove the JINA_API_KEY if it existsos.environ.pop("JINA_API_KEY", None)- with pytest.raises(ValueError, match="Must pass in Jina API key"):+ with pytest.raises(ValueError, match="JINA_API_KEY"):JinaRerankRetriever()diff --git a/test/retrievers/test_retrievers_decorators.py b/test/retrievers/test_retrievers_decorators.pynew file mode 100644index 000000000..88c15cf38--- /dev/null+++ b/test/retrievers/test_retrievers_decorators.py@@ -0,0 +1,159 @@+# ========= 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. =========+"""+Test that the following decorators are correctly applied to camel.retrievers:+@api_keys_required - should raise ValueError if value is missing+@dependencies_required - should raise ImportError if package/module is missing+"""++import os+from unittest.mock import patch++import pytest++fake_api_key = "fake_api_key"+++def _mock_missing(module_name: str):+ """+ Patch is_module_available to return False for a specific module.+ """+ original = __import__(+ 'camel.utils.commons', fromlist=['is_module_available']+ ).is_module_available++ def fake(m):+ if m == module_name:+ return False+ return original(m)++ return patch('camel.utils.commons.is_module_available', side_effect=fake)+++def test_auto_retriever_missing_dependency():+ """+ Raises ImportError when specified module is in @dependencies_required+ """+ from camel.retrievers import AutoRetriever++ with _mock_missing('hashlib'):+ with pytest.raises(ImportError, match="hashlib"):+ AutoRetriever._collection_name_generator()++ with _mock_missing('os'):+ with pytest.raises(ImportError, match="os"):+ AutoRetriever._collection_name_generator()++ with _mock_missing('unstructured.documents.elements'):+ with pytest.raises(+ ImportError, match="unstructured.documents.elements"+ ):+ AutoRetriever._collection_name_generator()++ with _mock_missing('unstructured.documents.elements'):+ with pytest.raises(+ ImportError, match="unstructured.documents.elements"+ ):+ AutoRetriever.run_vector_retriever()+++def test_bm25_retriever_missing_dependency():+ """+ Raises ImportError when specified module is in @dependencies_required+ """+ from camel.retrievers import BM25Retriever++ with _mock_missing('rank_bm25'):+ with pytest.raises(ImportError, match="rank_bm25"):+ BM25Retriever()++ with _mock_missing('numpy'):+ with pytest.raises(ImportError, match="numpy"):+ BM25Retriever.query()+++def test_cohere_rerank_retriever_missing_dependency():+ """+ Raises ImportError when specified module is in @dependencies_required.+ Include fake_api_key if function also has an @api_keys_required decorator+ This prevents test from returning ValueError instead of expected+ Failed: DID NOT RAISE <class 'ImportError'>+ if module is not in @dependencies_required list.+ """+ from camel.retrievers import CohereRerankRetriever++ with _mock_missing('cohere'):+ with pytest.raises(ImportError, match="cohere"):+ CohereRerankRetriever(api_key=fake_api_key)+++def test_hybrid_retrieval_missing_dependency():+ """+ Raises ImportError when specified module is in @dependencies_required+ """+ from camel.retrievers import HybridRetriever++ with _mock_missing('numpy'):+ with pytest.raises(ImportError, match="numpy"):+ HybridRetriever._sort_rrf_scores()+++def test_jina_rerank_retriever_missing_dependency():+ """+ Raises ImportError when specified module is in @dependencies_required+ """+ from camel.retrievers import JinaRerankRetriever++ with _mock_missing('requests'):+ with pytest.raises(ImportError, match="requests"):+ JinaRerankRetriever.query()+++def test_vector_retriever_missing_dependency():+ """+ Raises ImportError when specified module is in @dependencies_required+ """+ from camel.retrievers import VectorRetriever++ with _mock_missing('unstructured.documents.elements'):+ with pytest.raises(+ ImportError, match="unstructured.documents.elements"+ ):+ VectorRetriever.process()+++def test_cohere_rerank_retriever_api_keys():+ """+ Patch os.environ to hold no Values, and+ Input no API keys as function arguments:+ Check ValueError is returned for specific API keys by match=.+ """+ from camel.retrievers import CohereRerankRetriever++ with patch.dict(os.environ, {}, clear=True):+ with pytest.raises(ValueError, match='COHERE_API_KEY'):+ CohereRerankRetriever()+++def test_jina_rerank_retriever_api_keys():+ """+ Patch os.environ to hold no Values, and+ Input no API keys as function arguments:+ Check ValueError is returned for specific API keys by match=.+ """+ from camel.retrievers import JinaRerankRetriever++ with patch.dict(os.environ, {}, clear=True):+ with pytest.raises(ValueError, match='JINA_API_KEY'):+ JinaRerankRetriever()