LCORE-298: Conversation cache factory

docs/config.puml

@@ -29,7 +29,7 @@ class "CORSConfiguration" as src.models.config.CORSConfiguration {
 class "Configuration" as src.models.config.Configuration {
   authentication : Optional[AuthenticationConfiguration]
   authorization : Optional[AuthorizationConfiguration]
-  conversation_cache : Optional[ConversationCache]
+  conversation_cache : Optional[ConversationCacheConfiguration]
   customization : Optional[Customization]
   database : Optional[DatabaseConfiguration]
   inference : Optional[InferenceConfiguration]
@@ -43,7 +43,7 @@ class "Configuration" as src.models.config.Configuration {
 class "ConfigurationBase" as src.models.config.ConfigurationBase {
   model_config
 }
-class "ConversationCache" as src.models.config.ConversationCache {
+class "ConversationCacheConfiguration" as src.models.config.ConversationCacheConfiguration {
   memory : Optional[InMemoryCacheConfig]
   postgres : Optional[PostgreSQLDatabaseConfiguration]
   sqlite : Optional[SQLiteDatabaseConfiguration]
@@ -157,7 +157,7 @@ src.models.config.AuthenticationConfiguration --|> src.models.config.Configurati
 src.models.config.AuthorizationConfiguration --|> src.models.config.ConfigurationBase
 src.models.config.CORSConfiguration --|> src.models.config.ConfigurationBase
 src.models.config.Configuration --|> src.models.config.ConfigurationBase
-src.models.config.ConversationCache --|> src.models.config.ConfigurationBase
+src.models.config.ConversationCacheConfiguration --|> src.models.config.ConfigurationBase
 src.models.config.Customization --|> src.models.config.ConfigurationBase
 src.models.config.DatabaseConfiguration --|> src.models.config.ConfigurationBase
 src.models.config.InMemoryCacheConfig --|> src.models.config.ConfigurationBase

src/cache/__init__.py

@@ -0,0 +1 @@
+"""Various cache implementations."""

src/cache/cache.py

@@ -0,0 +1,110 @@
+"""Abstract class that is parent for all cache implementations."""
+
+from abc import ABC, abstractmethod
+
+from models.cache_entry import CacheEntry
+from utils.suid import check_suid
+
+
+class Cache(ABC):
+    """Abstract class that is parent for all cache implementations.
+
+    Cache entries are identified by compound key that consists of
+    user ID and conversation ID. Application logic must ensure that
+    user will be able to store and retrieve values that have the
+    correct user ID only. This means that user won't be able to
+    read or modify other users conversations.
+    """
+
+    # separator between parts of compond key
+    COMPOUND_KEY_SEPARATOR = ":"
+
+    @staticmethod
+    def _check_user_id(user_id: str, skip_user_id_check: bool) -> None:
+        """Check if given user ID is valid."""
+        if skip_user_id_check:
+            return
+        if not check_suid(user_id):
+            raise ValueError(f"Invalid user ID {user_id}")
+
+    @staticmethod
+    def _check_conversation_id(conversation_id: str) -> None:
+        """Check if given conversation ID is a valid UUID (including optional dashes)."""
+        if not check_suid(conversation_id):
+            raise ValueError(f"Invalid conversation ID {conversation_id}")
+
+    @staticmethod
+    def construct_key(
+        user_id: str, conversation_id: str, skip_user_id_check: bool
+    ) -> str:
+        """Construct key to cache."""
+        Cache._check_user_id(user_id, skip_user_id_check)
+        Cache._check_conversation_id(conversation_id)
+        return f"{user_id}{Cache.COMPOUND_KEY_SEPARATOR}{conversation_id}"
+
+    @abstractmethod
+    def get(
+        self, user_id: str, conversation_id: str, skip_user_id_check: bool
+    ) -> list[CacheEntry]:
+        """Abstract method to retrieve a value from the cache.
+
+        Args:
+            user_id: User identification.
+            conversation_id: Conversation ID unique for given user.
+            skip_user_id_check: Skip user_id suid check.
+
+        Returns:
+            The value (CacheEntry(s)) associated with the key, or None if not found.
+        """
+
+    @abstractmethod
+    def insert_or_append(
+        self,
+        user_id: str,
+        conversation_id: str,
+        cache_entry: CacheEntry,
+        skip_user_id_check: bool,
+    ) -> None:
+        """Abstract method to store a value in the cache.
+
+        Args:
+            user_id: User identification.
+            conversation_id: Conversation ID unique for given user.
+            cache_entry: The value to store.
+            skip_user_id_check: Skip user_id suid check.
+        """
+
+    @abstractmethod
+    def delete(
+        self, user_id: str, conversation_id: str, skip_user_id_check: bool
+    ) -> bool:
+        """Delete all entries for a given conversation.
+
+        Args:
+            user_id: User identification.
+            conversation_id: Conversation ID unique for given user.
+            skip_user_id_check: Skip user_id suid check.
+
+        Returns:
+            bool: True if entries were deleted, False if key wasn't found.
+        """
+
+    @abstractmethod
+    def list(self, user_id: str, skip_user_id_check: bool) -> list[str]:
+        """List all conversations for a given user_id.
+
+        Args:
+            user_id: User identification.
+            skip_user_id_check: Skip user_id suid check.
+
+        Returns:
+            A list of conversation ids from the cache
+        """
+
+    @abstractmethod
+    def ready(self) -> bool:
+        """Check if the cache is ready.
+
+        Returns:
+            True if the cache is ready, False otherwise.
+        """

src/cache/cache_error.py

@@ -0,0 +1,5 @@
+"""Any exception that can occur during cache operations."""
+
+
+class CacheError(Exception):
+    """Any exception that can occur during cache operations."""

src/cache/cache_factory.py

@@ -0,0 +1,35 @@
+"""Cache factory class."""
+
+import constants
+from models.config import ConversationCacheConfiguration
+from cache.cache import Cache
+from log import get_logger
+
+logger = get_logger("cache.cache_factory")
+
+
+# pylint: disable=R0903
+class CacheFactory:
+    """Cache factory class."""
+
+    @staticmethod
+    def conversation_cache(config: ConversationCacheConfiguration) -> Cache | None:
+        """Create an instance of Cache based on loaded configuration.
+
+        Returns:
+            An instance of `Cache` (either `PostgresCache` or `InMemoryCache`).
+        """
+        logger.info("Creating cache instance of type %s", config.type)
+        match config.type:
+            case constants.CACHE_TYPE_MEMORY:
+                return None
+            case constants.CACHE_TYPE_SQLITE:
+                return None
+            case constants.CACHE_TYPE_POSTGRES:
+                return None
+            case _:
+                raise ValueError(
+                    f"Invalid cache type: {config.type}. "
+                    f"Use '{constants.CACHE_TYPE_POSTGRES}' '{constants.CACHE_TYPE_SQLITE}' or "
+                    f"'{constants.CACHE_TYPE_MEMORY}' options."
+                )

src/configuration.py

@@ -19,9 +19,12 @@
     AuthenticationConfiguration,
     InferenceConfiguration,
     DatabaseConfiguration,
-    ConversationCache,
+    ConversationCacheConfiguration,
 )
 
+from cache.cache import Cache
+from cache.cache_factory import CacheFactory
+
 
 logger = logging.getLogger(__name__)
 
@@ -44,6 +47,7 @@ def __new__(cls, *args: Any, **kwargs: Any) -> "AppConfig":
     def __init__(self) -> None:
         """Initialize the class instance."""
         self._configuration: Optional[Configuration] = None
+        self._conversation_cache: Optional[Cache] = None
 
     def load_configuration(self, filename: str) -> None:
         """Load configuration from YAML file."""
@@ -126,7 +130,7 @@ def inference(self) -> InferenceConfiguration:
         return self._configuration.inference
 
     @property
-    def conversation_cache(self) -> ConversationCache:
+    def conversation_cache_configuration(self) -> ConversationCacheConfiguration:
         """Return conversation cache configuration."""
         if self._configuration is None:
             raise LogicError("logic error: configuration is not loaded")
@@ -139,5 +143,14 @@ def database_configuration(self) -> DatabaseConfiguration:
             raise LogicError("logic error: configuration is not loaded")
         return self._configuration.database
 
+    @property
+    def conversation_cache(self) -> Cache | None:
+        """Return the conversation cache."""
+        if self._conversation_cache is None and self._configuration is not None:
+            self._conversation_cache = CacheFactory.conversation_cache(
+                self._configuration.conversation_cache
+            )
+        return self._conversation_cache
+
 
 configuration: AppConfig = AppConfig()

src/models/cache_entry.py

@@ -0,0 +1,19 @@
+"""Model for conversation history cache entry."""
+
+from pydantic import BaseModel
+
+
+class CacheEntry(BaseModel):
+    """Model representing a cache entry.
+
+    Attributes:
+        query: The query string
+        response: The response string
+        provider: Provider identification
+        model: Model identification
+    """
+
+    query: str
+    response: str
+    provider: str
+    model: str

src/models/config.py

@@ -486,7 +486,7 @@ def check_default_model_and_provider(self) -> Self:
         return self
 
 
-class ConversationCache(ConfigurationBase):
+class ConversationCacheConfiguration(ConfigurationBase):
     """Conversation cache configuration."""
 
     type: Literal["memory", "sqlite", "postgres"] | None = None
@@ -542,7 +542,9 @@ class Configuration(ConfigurationBase):
     authorization: Optional[AuthorizationConfiguration] = None
     customization: Optional[Customization] = None
     inference: InferenceConfiguration = Field(default_factory=InferenceConfiguration)
-    conversation_cache: ConversationCache = Field(default_factory=ConversationCache)
+    conversation_cache: ConversationCacheConfiguration = Field(
+        default_factory=ConversationCacheConfiguration
+    )
 
     def dump(self, filename: str = "configuration.json") -> None:
         """Dump actual configuration into JSON file."""