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

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.py
index 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_required
if 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.py
index 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.py
index a784d606c..6e0fa6f5b 100644
--- a/camel/retrievers/cohere_rerank_retriever.py
+++ b/camel/retrievers/cohere_rerank_retriever.py
@@ -15,7 +15,7 @@ import os
from typing import Any, Dict, List, Optional
from camel.retrievers import BaseRetriever
-from camel.utils import dependencies_required
+from camel.utils import api_keys_required, dependencies_required
DEFAULT_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.py
index 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, Union
from camel.embeddings import BaseEmbedding
from camel.retrievers import BaseRetriever, BM25Retriever, VectorRetriever
from camel.storages import BaseVectorStorage
+from camel.utils import dependencies_required
class 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.py
index 9f709a706..8e1d68baa 100644
--- a/camel/retrievers/jina_rerank_retriever.py
+++ b/camel/retrievers/jina_rerank_retriever.py
@@ -14,10 +14,9 @@
import os
from typing import Any, Dict, List, Union
-import requests
-
from camel.retrievers import BaseRetriever
from camel.types.enums import JinaRerankerModelType
+from camel.utils import api_keys_required, dependencies_required
DEFAULT_TOP_K_RESULTS = 1
JINA_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 reranking
documents = []
for item in retrieved_result:
diff --git a/camel/retrievers/vector_retriever.py b/camel/retrievers/vector_retriever.py
index 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_required
from camel.utils.chunker import BaseChunker, UnstructuredIOChunker
if 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.py
index 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 CohereRerankRetriever
def test_initialization():
- retriever = CohereRerankRetriever()
+ retriever = CohereRerankRetriever(api_key="test_key")
assert retriever.model_name == "rerank-multilingual-v2.0"
@pytest.fixture
def cohere_rerank():
- return CohereRerankRetriever()
+ return CohereRerankRetriever(api_key="test_key")
@pytest.fixture
diff --git a/test/retrievers/test_jina_rerank_retriever.py b/test/retrievers/test_jina_rerank_retriever.py
index 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 exists
os.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.py
new file mode 100644
index 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()