dao-ai 0.1.18__py3-none-any.whl → 0.1.19__py3-none-any.whl

dao_ai/genie/cache/in_memory_semantic.py

@@ -0,0 +1,871 @@
+"""
+In-memory semantic cache implementation for Genie SQL queries.
+
+This module provides a semantic cache that stores embeddings and cache entries
+entirely in memory, without requiring external database dependencies like PostgreSQL
+or Databricks Lakebase. It uses L2 distance for similarity search and supports
+dual embedding matching (question + conversation context).
+
+The cache supports conversation-aware embedding using a rolling window approach
+to capture context from recent conversation turns, improving accuracy for
+multi-turn conversations with anaphoric references.
+
+Use this when:
+- No external database access is available
+- Single-instance deployments (cache not shared across instances)
+- Cache persistence across restarts is not required
+- Cache sizes are moderate (hundreds to low thousands of entries)
+
+For multi-instance deployments or large cache sizes, use SemanticCacheService
+with PostgreSQL backend instead.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from threading import Lock
+from typing import Any
+
+import mlflow
+import numpy as np
+import pandas as pd
+from databricks.sdk import WorkspaceClient
+from databricks.sdk.service.sql import StatementResponse, StatementState
+from databricks_ai_bridge.genie import GenieResponse
+from loguru import logger
+
+from dao_ai.config import (
+    GenieInMemorySemanticCacheParametersModel,
+    LLMModel,
+    WarehouseModel,
+)
+from dao_ai.genie.cache.base import (
+    CacheResult,
+    GenieServiceBase,
+    SQLCacheEntry,
+)
+from dao_ai.genie.cache.semantic import (
+    get_conversation_history,
+)
+
+
+@dataclass
+class InMemoryCacheEntry:
+    """
+    In-memory cache entry storing embeddings and SQL query metadata.
+
+    This dataclass represents a single cache entry stored in memory, including
+    dual embeddings (question + context) for high-precision semantic matching.
+
+    Uses LRU (Least Recently Used) eviction strategy when capacity is reached.
+    """
+
+    genie_space_id: str
+    question: str
+    conversation_context: str
+    question_embedding: list[float]
+    context_embedding: list[float]
+    sql_query: str
+    description: str
+    conversation_id: str
+    created_at: datetime
+    last_accessed_at: datetime  # Track last access time for LRU eviction
+
+
+def l2_distance(a: list[float], b: list[float]) -> float:
+    """
+    Calculate L2 (Euclidean) distance between two embedding vectors.
+
+    This uses the same distance metric as PostgreSQL pg_vector to ensure
+    consistent behavior between in-memory and PostgreSQL caches.
+
+    Args:
+        a: First embedding vector
+        b: Second embedding vector
+
+    Returns:
+        L2 distance (0 = identical vectors, larger = more different)
+    """
+    return float(np.linalg.norm(np.array(a) - np.array(b)))
+
+
+def distance_to_similarity(distance: float) -> float:
+    """
+    Convert L2 distance to similarity score in range [0, 1].
+
+    Uses the formula: similarity = 1.0 / (1.0 + distance)
+    This matches the conversion used by PostgreSQL semantic cache.
+
+    Args:
+        distance: L2 distance value
+
+    Returns:
+        Similarity score where 1.0 = perfect match, approaching 0 = very different
+    """
+    return 1.0 / (1.0 + distance)
+
+
+class InMemorySemanticCacheService(GenieServiceBase):
+    """
+    In-memory semantic caching decorator using dual embeddings for similarity lookup.
+
+    This service caches the SQL query generated by Genie along with dual embeddings
+    (question + conversation context) for high-precision semantic matching. On
+    subsequent queries, it performs similarity search to find cached queries that
+    match both the question intent AND conversation context.
+
+    Cache entries are partitioned by genie_space_id to ensure queries from different
+    Genie spaces don't return incorrect cache hits.
+
+    On cache hit, it re-executes the cached SQL using the provided warehouse
+    to return fresh data while avoiding the Genie NL-to-SQL translation cost.
+
+    Example:
+        from dao_ai.config import GenieInMemorySemanticCacheParametersModel
+        from dao_ai.genie.cache import InMemorySemanticCacheService
+
+        cache_params = GenieInMemorySemanticCacheParametersModel(
+            warehouse=warehouse_model,
+            embedding_model="databricks-gte-large-en",
+            time_to_live_seconds=86400,  # 24 hours
+            similarity_threshold=0.85,
+            capacity=1000,  # Limit to 1000 entries
+        )
+        genie = InMemorySemanticCacheService(
+            impl=GenieService(Genie(space_id="my-space")),
+            parameters=cache_params,
+            workspace_client=workspace_client,
+        ).initialize()
+
+    Thread-safe: Uses a lock to protect cache operations.
+    """
+
+    impl: GenieServiceBase
+    parameters: GenieInMemorySemanticCacheParametersModel
+    workspace_client: WorkspaceClient | None
+    name: str
+    _embeddings: Any  # DatabricksEmbeddings
+    _cache: list[InMemoryCacheEntry]
+    _lock: Lock
+    _embedding_dims: int | None
+    _setup_complete: bool
+
+    def __init__(
+        self,
+        impl: GenieServiceBase,
+        parameters: GenieInMemorySemanticCacheParametersModel,
+        workspace_client: WorkspaceClient | None = None,
+        name: str | None = None,
+    ) -> None:
+        """
+        Initialize the in-memory semantic cache service.
+
+        Args:
+            impl: The underlying GenieServiceBase to delegate to on cache miss.
+                The space_id will be obtained from impl.space_id.
+            parameters: Cache configuration including warehouse, embedding model, and thresholds
+            workspace_client: Optional WorkspaceClient for retrieving conversation history.
+                If None, conversation context will not be used.
+            name: Name for this cache layer (for logging). Defaults to class name.
+        """
+        self.impl = impl
+        self.parameters = parameters
+        self.workspace_client = workspace_client
+        self.name = name if name is not None else self.__class__.__name__
+        self._embeddings = None
+        self._cache = []
+        self._lock = Lock()
+        self._embedding_dims = None
+        self._setup_complete = False
+
+    def initialize(self) -> "InMemorySemanticCacheService":
+        """
+        Eagerly initialize the cache service.
+
+        Call this during tool creation to:
+        - Validate configuration early (fail fast)
+        - Initialize embeddings model before any requests
+        - Avoid first-request latency from lazy initialization
+
+        Returns:
+            self for method chaining
+        """
+        self._setup()
+        return self
+
+    def _setup(self) -> None:
+        """Initialize embeddings model lazily."""
+        if self._setup_complete:
+            return
+
+        # Initialize embeddings
+        # Convert embedding_model to LLMModel if it's a string
+        embedding_model: LLMModel = (
+            LLMModel(name=self.parameters.embedding_model)
+            if isinstance(self.parameters.embedding_model, str)
+            else self.parameters.embedding_model
+        )
+        self._embeddings = embedding_model.as_embeddings_model()
+
+        # Auto-detect embedding dimensions if not provided
+        if self.parameters.embedding_dims is None:
+            sample_embedding: list[float] = self._embeddings.embed_query("test")
+            self._embedding_dims = len(sample_embedding)
+            logger.debug(
+                "Auto-detected embedding dimensions",
+                layer=self.name,
+                dims=self._embedding_dims,
+            )
+        else:
+            self._embedding_dims = self.parameters.embedding_dims
+
+        self._setup_complete = True
+        logger.debug(
+            "In-memory semantic cache initialized",
+            layer=self.name,
+            space_id=self.space_id,
+            dims=self._embedding_dims,
+            capacity=self.parameters.capacity,
+        )
+
+    @property
+    def warehouse(self) -> WarehouseModel:
+        """The warehouse used for executing cached SQL queries."""
+        return self.parameters.warehouse
+
+    @property
+    def time_to_live(self) -> timedelta | None:
+        """Time-to-live for cache entries. None means never expires."""
+        ttl = self.parameters.time_to_live_seconds
+        if ttl is None or ttl < 0:
+            return None
+        return timedelta(seconds=ttl)
+
+    @property
+    def similarity_threshold(self) -> float:
+        """Minimum similarity for cache hit (using L2 distance converted to similarity)."""
+        return self.parameters.similarity_threshold
+
+    @property
+    def embedding_dims(self) -> int:
+        """Dimension size for embeddings (auto-detected if not configured)."""
+        if self._embedding_dims is None:
+            raise RuntimeError(
+                "Embedding dimensions not yet initialized. Call _setup() first."
+            )
+        return self._embedding_dims
+
+    def _embed_question(
+        self, question: str, conversation_id: str | None = None
+    ) -> tuple[list[float], list[float], str]:
+        """
+        Generate dual embeddings: one for the question, one for the conversation context.
+
+        This enables separate matching of question similarity vs context similarity,
+        improving precision by ensuring both the question AND the conversation context
+        are semantically similar before returning a cached result.
+
+        Args:
+            question: The question to embed
+            conversation_id: Optional conversation ID for retrieving context
+
+        Returns:
+            Tuple of (question_embedding, context_embedding, conversation_context_string)
+            - question_embedding: Vector embedding of just the question
+            - context_embedding: Vector embedding of the conversation context (or zero vector if no context)
+            - conversation_context_string: The conversation context string (empty if no context)
+        """
+        conversation_context = ""
+
+        # If conversation context is enabled and available
+        if (
+            self.workspace_client is not None
+            and conversation_id is not None
+            and self.parameters.context_window_size > 0
+        ):
+            try:
+                # Retrieve conversation history
+                conversation_messages = get_conversation_history(
+                    workspace_client=self.workspace_client,
+                    space_id=self.space_id,
+                    conversation_id=conversation_id,
+                    max_messages=self.parameters.context_window_size
+                    * 2,  # Get extra for safety
+                )
+
+                # Build context string (just the "Previous:" messages, not the current question)
+                if conversation_messages:
+                    recent_messages = (
+                        conversation_messages[-self.parameters.context_window_size :]
+                        if len(conversation_messages)
+                        > self.parameters.context_window_size
+                        else conversation_messages
+                    )
+
+                    context_parts: list[str] = []
+                    for msg in recent_messages:
+                        if msg.content:
+                            content: str = msg.content
+                            if len(content) > 500:
+                                content = content[:500] + "..."
+                            context_parts.append(f"Previous: {content}")
+
+                    conversation_context = "\n".join(context_parts)
+
+                    # Truncate if too long
+                    estimated_tokens = len(conversation_context) / 4
+                    if estimated_tokens > self.parameters.max_context_tokens:
+                        target_chars = self.parameters.max_context_tokens * 4
+                        conversation_context = (
+                            conversation_context[:target_chars] + "..."
+                        )
+
+                logger.trace(
+                    "Using conversation context",
+                    layer=self.name,
+                    messages_count=len(conversation_messages),
+                    window_size=self.parameters.context_window_size,
+                )
+            except Exception as e:
+                logger.warning(
+                    "Failed to build conversation context, using question only",
+                    layer=self.name,
+                    error=str(e),
+                )
+                conversation_context = ""
+
+        # Generate dual embeddings
+        if conversation_context:
+            # Embed both question and context
+            embeddings: list[list[float]] = self._embeddings.embed_documents(
+                [question, conversation_context]
+            )
+            question_embedding = embeddings[0]
+            context_embedding = embeddings[1]
+        else:
+            # Only embed question, use zero vector for context
+            embeddings = self._embeddings.embed_documents([question])
+            question_embedding = embeddings[0]
+            context_embedding = [0.0] * len(question_embedding)  # Zero vector
+
+        return question_embedding, context_embedding, conversation_context
+
+    @mlflow.trace(name="semantic_search_in_memory")
+    def _find_similar(
+        self,
+        question: str,
+        conversation_context: str,
+        question_embedding: list[float],
+        context_embedding: list[float],
+        conversation_id: str | None = None,
+    ) -> tuple[SQLCacheEntry, float] | None:
+        """
+        Find a semantically similar cached entry using dual embedding matching.
+
+        This method matches BOTH the question AND the conversation context separately,
+        ensuring high precision by requiring both to be semantically similar.
+
+        Performs linear scan through all cache entries, filtering by space_id and
+        calculating L2 distances for similarity matching.
+
+        Args:
+            question: The original question (for logging)
+            conversation_context: The conversation context string
+            question_embedding: The embedding vector of just the question
+            context_embedding: The embedding vector of the conversation context
+            conversation_id: Optional conversation ID (for logging)
+
+        Returns:
+            Tuple of (SQLCacheEntry, combined_similarity_score) if found, None otherwise
+        """
+        ttl_seconds = self.parameters.time_to_live_seconds
+        ttl_disabled = ttl_seconds is None or ttl_seconds < 0
+
+        question_weight: float = self.parameters.question_weight
+        context_weight: float = self.parameters.context_weight
+
+        best_entry: InMemoryCacheEntry | None = None
+        best_question_sim: float = 0.0
+        best_context_sim: float = 0.0
+        best_combined_sim: float = 0.0
+
+        # Linear scan through all entries
+        with self._lock:
+            entries_to_delete: list[int] = []
+
+            for idx, entry in enumerate(self._cache):
+                # Filter by space_id (partition)
+                if entry.genie_space_id != self.space_id:
+                    continue
+
+                # Check TTL
+                is_valid = True
+                if not ttl_disabled:
+                    age = datetime.now() - entry.created_at
+                    is_valid = age.total_seconds() <= ttl_seconds
+
+                if not is_valid:
+                    # Mark for deletion
+                    entries_to_delete.append(idx)
+                    continue
+
+                # Calculate L2 distances and convert to similarities
+                question_distance = l2_distance(
+                    question_embedding, entry.question_embedding
+                )
+                context_distance = l2_distance(
+                    context_embedding, entry.context_embedding
+                )
+
+                question_sim = distance_to_similarity(question_distance)
+                context_sim = distance_to_similarity(context_distance)
+
+                # Calculate weighted combined similarity
+                combined_sim = (question_weight * question_sim) + (
+                    context_weight * context_sim
+                )
+
+                # Track best match
+                if combined_sim > best_combined_sim:
+                    best_entry = entry
+                    best_question_sim = question_sim
+                    best_context_sim = context_sim
+                    best_combined_sim = combined_sim
+
+            # Delete expired entries
+            for idx in reversed(entries_to_delete):
+                del self._cache[idx]
+                logger.trace(
+                    "Deleted expired entry",
+                    layer=self.name,
+                    index=idx,
+                )
+
+        # No entries found
+        if best_entry is None:
+            logger.info(
+                "Cache MISS (no entries)",
+                layer=self.name,
+                question=question[:50],
+                space=self.space_id,
+                delegating_to=type(self.impl).__name__,
+            )
+            return None
+
+        # Log best match info
+        logger.debug(
+            "Best match found",
+            layer=self.name,
+            question_sim=f"{best_question_sim:.4f}",
+            context_sim=f"{best_context_sim:.4f}",
+            combined_sim=f"{best_combined_sim:.4f}",
+            cached_question=best_entry.question[:50],
+            cached_context=best_entry.conversation_context[:80],
+        )
+
+        # Check BOTH similarity thresholds (dual embedding precision check)
+        if best_question_sim < self.parameters.similarity_threshold:
+            logger.info(
+                "Cache MISS (question similarity too low)",
+                layer=self.name,
+                question_sim=f"{best_question_sim:.4f}",
+                threshold=self.parameters.similarity_threshold,
+                delegating_to=type(self.impl).__name__,
+            )
+            return None
+
+        if best_context_sim < self.parameters.context_similarity_threshold:
+            logger.info(
+                "Cache MISS (context similarity too low)",
+                layer=self.name,
+                context_sim=f"{best_context_sim:.4f}",
+                threshold=self.parameters.context_similarity_threshold,
+                delegating_to=type(self.impl).__name__,
+            )
+            return None
+
+        # Cache HIT!
+        # Update last accessed time for LRU eviction
+        with self._lock:
+            best_entry.last_accessed_at = datetime.now()
+
+        cache_age_seconds = (datetime.now() - best_entry.created_at).total_seconds()
+        logger.info(
+            "Cache HIT",
+            layer=self.name,
+            question=question[:80],
+            conversation_id=conversation_id,
+            matched_question=best_entry.question[:80],
+            cache_age_seconds=round(cache_age_seconds, 1),
+            question_similarity=f"{best_question_sim:.4f}",
+            context_similarity=f"{best_context_sim:.4f}",
+            combined_similarity=f"{best_combined_sim:.4f}",
+            cached_sql=best_entry.sql_query[:80] if best_entry.sql_query else None,
+            ttl_seconds=self.parameters.time_to_live_seconds,
+        )
+
+        cache_entry = SQLCacheEntry(
+            query=best_entry.sql_query,
+            description=best_entry.description,
+            conversation_id=best_entry.conversation_id,
+            created_at=best_entry.created_at,
+        )
+        return cache_entry, best_combined_sim
+
+    def _store_entry(
+        self,
+        question: str,
+        conversation_context: str,
+        question_embedding: list[float],
+        context_embedding: list[float],
+        response: GenieResponse,
+    ) -> None:
+        """
+        Store a new cache entry with dual embeddings for this Genie space.
+
+        If capacity is set and reached, evicts least recently used entry (LRU).
+        """
+        now = datetime.now()
+        new_entry = InMemoryCacheEntry(
+            genie_space_id=self.space_id,
+            question=question,
+            conversation_context=conversation_context,
+            question_embedding=question_embedding,
+            context_embedding=context_embedding,
+            sql_query=response.query,
+            description=response.description,
+            conversation_id=response.conversation_id,
+            created_at=now,
+            last_accessed_at=now,  # Initialize to now; updated on cache hits (traditional LRU)
+        )
+
+        with self._lock:
+            # Enforce capacity limit (LRU eviction)
+            if self.parameters.capacity is not None:
+                # Count entries for this space_id
+                space_entries = [
+                    e for e in self._cache if e.genie_space_id == self.space_id
+                ]
+
+                while len(space_entries) >= self.parameters.capacity:
+                    # Find and remove least recently used entry for this space
+                    lru_idx = None
+                    lru_time = None
+
+                    for idx, entry in enumerate(self._cache):
+                        if entry.genie_space_id == self.space_id:
+                            if lru_time is None or entry.last_accessed_at < lru_time:
+                                lru_time = entry.last_accessed_at
+                                lru_idx = idx
+
+                    if lru_idx is not None:
+                        evicted = self._cache.pop(lru_idx)
+                        logger.trace(
+                            "Evicted LRU cache entry",
+                            layer=self.name,
+                            question=evicted.question[:50],
+                            capacity=self.parameters.capacity,
+                        )
+                        space_entries = [
+                            e for e in self._cache if e.genie_space_id == self.space_id
+                        ]
+                    else:
+                        break
+
+            self._cache.append(new_entry)
+            logger.debug(
+                "Stored cache entry",
+                layer=self.name,
+                question=question[:50],
+                context=conversation_context[:80],
+                sql=response.query[:50] if response.query else None,
+                space=self.space_id,
+                cache_size=len(
+                    [e for e in self._cache if e.genie_space_id == self.space_id]
+                ),
+                capacity=self.parameters.capacity,
+            )
+
+    @mlflow.trace(name="execute_cached_sql_in_memory_semantic")
+    def _execute_sql(self, sql: str) -> pd.DataFrame | str:
+        """Execute SQL using the warehouse and return results."""
+        client: WorkspaceClient = self.warehouse.workspace_client
+        warehouse_id: str = str(self.warehouse.warehouse_id)
+
+        statement_response: StatementResponse = (
+            client.statement_execution.execute_statement(
+                warehouse_id=warehouse_id,
+                statement=sql,
+                wait_timeout="30s",
+            )
+        )
+
+        if (
+            statement_response.status is not None
+            and statement_response.status.state != StatementState.SUCCEEDED
+        ):
+            error_msg: str = (
+                f"SQL execution failed: {statement_response.status.error.message}"
+                if statement_response.status.error is not None
+                else f"SQL execution failed with state: {statement_response.status.state}"
+            )
+            logger.error("SQL execution failed", layer=self.name, error=error_msg)
+            return error_msg
+
+        if statement_response.result and statement_response.result.data_array:
+            columns: list[str] = []
+            if (
+                statement_response.manifest
+                and statement_response.manifest.schema
+                and statement_response.manifest.schema.columns
+            ):
+                columns = [
+                    col.name
+                    for col in statement_response.manifest.schema.columns
+                    if col.name is not None
+                ]
+
+            data: list[list[Any]] = statement_response.result.data_array
+            if columns:
+                return pd.DataFrame(data, columns=columns)
+            else:
+                return pd.DataFrame(data)
+
+        return pd.DataFrame()
+
+    def ask_question(
+        self, question: str, conversation_id: str | None = None
+    ) -> CacheResult:
+        """
+        Ask a question, using semantic cache if a similar query exists.
+
+        On cache hit, re-executes the cached SQL to get fresh data.
+        Returns CacheResult with cache metadata.
+        """
+        return self.ask_question_with_cache_info(question, conversation_id)
+
+    @mlflow.trace(name="genie_in_memory_semantic_cache_lookup")
+    def ask_question_with_cache_info(
+        self,
+        question: str,
+        conversation_id: str | None = None,
+    ) -> CacheResult:
+        """
+        Ask a question with detailed cache hit information.
+
+        On cache hit, the cached SQL is re-executed to return fresh data, but the
+        conversation_id returned is the current conversation_id (not the cached one).
+
+        Args:
+            question: The question to ask
+            conversation_id: Optional conversation ID for context and continuation
+
+        Returns:
+            CacheResult with fresh response and cache metadata
+        """
+        # Ensure initialization (lazy init if initialize() wasn't called)
+        self._setup()
+
+        # Generate dual embeddings for the question and conversation context
+        question_embedding: list[float]
+        context_embedding: list[float]
+        conversation_context: str
+        question_embedding, context_embedding, conversation_context = (
+            self._embed_question(question, conversation_id)
+        )
+
+        # Check cache using dual embedding similarity
+        cache_result: tuple[SQLCacheEntry, float] | None = self._find_similar(
+            question,
+            conversation_context,
+            question_embedding,
+            context_embedding,
+            conversation_id,
+        )
+
+        if cache_result is not None:
+            cached, combined_similarity = cache_result
+            logger.debug(
+                "In-memory semantic cache hit",
+                layer=self.name,
+                combined_similarity=f"{combined_similarity:.3f}",
+                question=question[:50],
+                conversation_id=conversation_id,
+            )
+
+            # Re-execute the cached SQL to get fresh data
+            result: pd.DataFrame | str = self._execute_sql(cached.query)
+
+            # IMPORTANT: Use the current conversation_id (from the request), not the cached one
+            # This ensures the conversation continues properly
+            response: GenieResponse = GenieResponse(
+                result=result,
+                query=cached.query,
+                description=cached.description,
+                conversation_id=conversation_id
+                if conversation_id
+                else cached.conversation_id,
+            )
+
+            return CacheResult(response=response, cache_hit=True, served_by=self.name)
+
+        # Cache miss - delegate to wrapped service
+        logger.info(
+            "Cache MISS",
+            layer=self.name,
+            question=question[:80],
+            conversation_id=conversation_id,
+            space_id=self.space_id,
+            similarity_threshold=self.similarity_threshold,
+            delegating_to=type(self.impl).__name__,
+        )
+
+        result: CacheResult = self.impl.ask_question(question, conversation_id)
+
+        # Store in cache if we got a SQL query
+        if result.response.query:
+            logger.debug(
+                "Storing new cache entry",
+                layer=self.name,
+                question=question[:50],
+                conversation_id=conversation_id,
+                space=self.space_id,
+            )
+            self._store_entry(
+                question,
+                conversation_context,
+                question_embedding,
+                context_embedding,
+                result.response,
+            )
+        elif not result.response.query:
+            logger.warning(
+                "Not caching: response has no SQL query",
+                layer=self.name,
+                question=question[:50],
+            )
+
+        return CacheResult(response=result.response, cache_hit=False, served_by=None)
+
+    @property
+    def space_id(self) -> str:
+        return self.impl.space_id
+
+    def invalidate_expired(self) -> int:
+        """
+        Remove expired entries from the cache for this Genie space.
+
+        Returns 0 if TTL is disabled (entries never expire).
+        """
+        self._setup()
+        ttl_seconds = self.parameters.time_to_live_seconds
+
+        # If TTL is disabled, nothing can expire
+        if ttl_seconds is None or ttl_seconds < 0:
+            logger.trace(
+                "TTL disabled, no entries to expire",
+                layer=self.name,
+                space=self.space_id,
+            )
+            return 0
+
+        deleted = 0
+        with self._lock:
+            indices_to_delete: list[int] = []
+            now = datetime.now()
+
+            for idx, entry in enumerate(self._cache):
+                if entry.genie_space_id != self.space_id:
+                    continue
+
+                age = now - entry.created_at
+                if age.total_seconds() > ttl_seconds:
+                    indices_to_delete.append(idx)
+
+            # Delete in reverse order to preserve indices
+            for idx in reversed(indices_to_delete):
+                del self._cache[idx]
+                deleted += 1
+
+            logger.trace(
+                "Deleted expired entries",
+                layer=self.name,
+                deleted_count=deleted,
+                space=self.space_id,
+            )
+
+        return deleted
+
+    def clear(self) -> int:
+        """Clear all entries from the cache for this Genie space."""
+        self._setup()
+        deleted = 0
+
+        with self._lock:
+            # Find indices for this space
+            indices_to_delete: list[int] = []
+            for idx, entry in enumerate(self._cache):
+                if entry.genie_space_id == self.space_id:
+                    indices_to_delete.append(idx)
+
+            # Delete in reverse order
+            for idx in reversed(indices_to_delete):
+                del self._cache[idx]
+                deleted += 1
+
+            logger.debug(
+                "Cleared cache entries",
+                layer=self.name,
+                deleted_count=deleted,
+                space=self.space_id,
+            )
+
+        return deleted
+
+    @property
+    def size(self) -> int:
+        """Current number of entries in the cache for this Genie space."""
+        self._setup()
+        with self._lock:
+            return len([e for e in self._cache if e.genie_space_id == self.space_id])
+
+    def stats(self) -> dict[str, int | float | None]:
+        """Return cache statistics for this Genie space."""
+        self._setup()
+        ttl_seconds = self.parameters.time_to_live_seconds
+        ttl = self.time_to_live
+
+        with self._lock:
+            space_entries = [
+                e for e in self._cache if e.genie_space_id == self.space_id
+            ]
+            total = len(space_entries)
+
+            # If TTL is disabled, all entries are valid
+            if ttl_seconds is None or ttl_seconds < 0:
+                return {
+                    "size": total,
+                    "capacity": self.parameters.capacity,
+                    "ttl_seconds": None,
+                    "similarity_threshold": self.similarity_threshold,
+                    "expired_entries": 0,
+                    "valid_entries": total,
+                }
+
+            # Count expired entries
+            now = datetime.now()
+            expired = 0
+            for entry in space_entries:
+                age = now - entry.created_at
+                if age.total_seconds() > ttl_seconds:
+                    expired += 1
+
+            return {
+                "size": total,
+                "capacity": self.parameters.capacity,
+                "ttl_seconds": ttl.total_seconds() if ttl else None,
+                "similarity_threshold": self.similarity_threshold,
+                "expired_entries": expired,
+                "valid_entries": total - expired,
+            }