🐫 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
<a id="camel.caches.semantic_cache"></a>
<a id="camel.caches.semantic_cache.SemanticCache"></a>
## SemanticCache
```python
class SemanticCache(BaseCache):
```
A semantic cache implementation that uses vector similarity to find
cached responses for semantically similar queries.
This cache generates embeddings for queries and stores them in a vector
database. When looking up a query, it finds the most similar cached query
using vector similarity search and returns the corresponding response if
the similarity exceeds the threshold.
**Parameters:**
- **embedding_model** (BaseEmbedding): The embedding model to use for generating query embeddings.
- **vector_storage** (BaseVectorStorage): The vector storage backend for storing and searching query embeddings.
- **similarity_threshold** (float): The minimum similarity score (0.0-1.0) required for a cache hit. Higher values require closer matches. (default: :obj:`0.85`)
- **cache_enabled** (bool): Whether the cache is enabled. (default: :obj:`True`)
<a id="camel.caches.semantic_cache.SemanticCache.__init__"></a>
### __init__
```python
def __init__(
self,
embedding_model: BaseEmbedding,
vector_storage: BaseVectorStorage,
similarity_threshold: float = 0.85,
cache_enabled: bool = True
):
```
Initialize the semantic cache.
**Parameters:**
- **embedding_model** (BaseEmbedding): The embedding model for queries.
- **vector_storage** (BaseVectorStorage): The vector storage backend.
- **similarity_threshold** (float): Minimum similarity for cache hit.
- **cache_enabled** (bool): Whether the cache is enabled initially.
<a id="camel.caches.semantic_cache.SemanticCache.similarity_threshold"></a>
### similarity_threshold
```python
def similarity_threshold(self):
```
**Returns:**
float: The similarity threshold (0.0-1.0).
<a id="camel.caches.semantic_cache.SemanticCache.similarity_threshold"></a>
### similarity_threshold
```python
def similarity_threshold(self, value: float):
```
Set the similarity threshold for cache hits.
**Parameters:**
- **value** (float): The new threshold value (0.0-1.0).
<a id="camel.caches.semantic_cache.SemanticCache.enabled"></a>
### enabled
```python
def enabled(self):
```
**Returns:**
bool: True if cache is enabled.
<a id="camel.caches.semantic_cache.SemanticCache.enabled"></a>
### enabled
```python
def enabled(self, value: bool):
```
Enable or disable the cache.
**Parameters:**
- **value** (bool): True to enable, False to disable.
<a id="camel.caches.semantic_cache.SemanticCache.size"></a>
### size
```python
def size(self):
```
**Returns:**
int: The number of cached entries.
<a id="camel.caches.semantic_cache.SemanticCache.hit_rate"></a>
### hit_rate
```python
def hit_rate(self):
```
**Returns:**
float: Cache hit rate (0.0-1.0), or 0.0 if no lookups yet.
<a id="camel.caches.semantic_cache.SemanticCache.stats"></a>
### stats
```python
def stats(self):
```
**Returns:**
Dict[str, Any]: Dictionary containing cache statistics including
hits, misses, hit rate, and size.
<a id="camel.caches.semantic_cache.SemanticCache._query_similar"></a>
### _query_similar
```python
def _query_similar(self, query: str, top_k: int = 1):
```
Internal helper to query vector storage for similar entries.
This consolidates the common logic of embedding generation and
vector storage querying used by get, get_with_score, and find_similar.
**Parameters:**
- **query** (str): The query to search for.
- **top_k** (int): Number of results to return. (default: :obj:`1`) (default: 1)
**Returns:**
Optional[List]: List of query results from vector storage,
or None if query fails or is empty.
<a id="camel.caches.semantic_cache.SemanticCache._result_to_cache_record"></a>
### _result_to_cache_record
```python
def _result_to_cache_record(self, result):
```
Convert a vector storage result to a CacheRecord.
**Parameters:**
- **result**: A query result from vector storage.
**Returns:**
CacheRecord: The converted cache record.
<a id="camel.caches.semantic_cache.SemanticCache._normalize_similarity"></a>
### _normalize_similarity
```python
def _normalize_similarity(self, score: float):
```
Normalize similarity score to 0.0-1.0 range.
Different vector storage backends may return similarity scores in
different ranges. This method ensures consistent behavior by clamping
scores to the expected 0.0-1.0 range.
**Parameters:**
- **score** (float): Raw similarity score from storage backend.
**Returns:**
float: Normalized similarity score between 0.0 and 1.0.
<a id="camel.caches.semantic_cache.SemanticCache.get"></a>
### get
```python
def get(self, query: str):
```
Retrieve a cached response for a semantically similar query.
Generates an embedding for the query and searches the vector storage
for similar cached queries. Returns the cached response if a match
is found with similarity >= threshold.
**Parameters:**
- **query** (str): The query to look up in the cache.
**Returns:**
Optional[str]: The cached response if a similar query is found
with sufficient similarity, None otherwise.
<a id="camel.caches.semantic_cache.SemanticCache.get_with_score"></a>
### get_with_score
```python
def get_with_score(self, query: str):
```
Retrieve cached response with similarity score and full record.
Similar to get(), but returns additional information about the match.
**Parameters:**
- **query** (str): The query to look up in the cache.
**Returns:**
Optional[tuple[str, float, CacheRecord]]: A tuple of
(response, similarity_score, cache_record) if found,
None otherwise.
<a id="camel.caches.semantic_cache.SemanticCache.set"></a>
### set
```python
def set(
self,
query: str,
response: str,
**kwargs: Any
):
```
Store a query-response pair in the cache.
Generates an embedding for the query and stores it along with the
response in the vector storage. If a semantically similar query
already exists (above the similarity threshold), the old entry is
deleted and replaced with the new one.
**Parameters:**
- **query** (str): The query text.
- **response** (str): The response to cache. **kwargs (Any): Additional arguments. Supports: - metadata (Dict[str, Any]): Additional metadata to store.
**Returns:**
Optional[str]: The unique ID assigned to this cache entry,
or None if cache is disabled.
<a id="camel.caches.semantic_cache.SemanticCache.delete"></a>
### delete
```python
def delete(self, entry_id: str):
```
Delete a specific cache entry by its ID.
**Parameters:**
- **entry_id** (str): The unique ID of the cache entry to delete.
**Returns:**
bool: True if the entry was deleted, False if not found.
<a id="camel.caches.semantic_cache.SemanticCache.clear"></a>
### clear
```python
def clear(self):
```
Remove all entries from the cache.
<a id="camel.caches.semantic_cache.SemanticCache.find_similar"></a>
### find_similar
```python
def find_similar(self, query: str, top_k: int = 5):
```
Find the top-k most similar cached queries.
This method returns similar entries regardless of whether they
meet the similarity threshold.
**Parameters:**
- **query** (str): The query to search for.
- **top_k** (int): Number of results to return. (default: :obj:`5`) (default: 5)
**Returns:**
List[tuple[CacheRecord, float]]: List of (record, similarity)
tuples sorted by similarity in descending order.
<a id="camel.caches.semantic_cache.SemanticCache.__repr__"></a>
### __repr__
```python
def __repr__(self):
```