feat(api): add cache (#15)

* feat(api): add cache interface and valkey impl

The cache interface is composed of a class that forces
implementations to provide save, get, and delete methods.
Currently, the only implementation is valkey which has
a docker service limiting its memory. Application connects
to the cache instance via CACHE_HOST and CACHE_PORT
variables with CACHE_TTL_SECONDS set to 1h by default

* feat(api): cache in translate and detect

Now translate and detect routes will save the response
to cache and retrieve to reply faster to users. The cache
key is:
- translate:src_lang:tgt_lang:text
- detect:text

Where text is a sanitized version of the input text. By
sanitizations the app will do:
- Normalize Unicode characters (NFC form)
- Trim excess whitespaces
- Covert to lowercase

Author: hspedro

Dockerfile

@@ -14,6 +14,9 @@ COPY babeltron ./babeltron
 RUN poetry config virtualenvs.create false \
     && poetry install --without dev --no-interaction --no-ansi
 
+# Pin NumPy to a version below 2.0 to avoid compatibility issues
+RUN pip install numpy==1.26.4 --force-reinstall
+
 # Install CUDA-enabled PyTorch (replacing the CPU-only version)
 RUN pip uninstall -y torch torchvision torchaudio && \
     pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

Makefile

@@ -1,4 +1,4 @@
-.PHONY: check-poetry install test lint format help system-deps coverage coverage-html download-model download-model-m2m-small download-model-m2m-medium download-model-m2m-large download-model-nllb download-model-nllb-small download-model-nllb-medium download-model-nllb-large serve serve-prod docker-build docker-run docker compose-up compose-down pre-commit-install pre-commit-run docker-build-with-model docker-up docker-down
+.PHONY: check-poetry install test lint format help system-deps coverage coverage-html download-model download-model-m2m-small download-model-m2m-medium download-model-m2m-large download-model-nllb download-model-nllb-small download-model-nllb-medium download-model-nllb-large serve serve-prod docker-build docker-run docker compose-up compose-down pre-commit-install pre-commit-run docker-build-with-model docker-up docker-down test-cache test-cache-comprehensive
 
 # Define model path variable with default value, can be overridden by environment
 MODEL_PATH ?= ./models
@@ -242,3 +242,11 @@ docker compose-up: ## Start services with Docker Compose
 	@echo "Starting services with Docker Compose..."
 	@PORT=$(PORT) docker compose up -d
 	@echo "Services started successfully. API is available at http://localhost:$(PORT)/api/docs"
+
+test-cache: ## Run basic cache end-to-end tests
+	@echo "Running basic cache end-to-end tests..."
+	@BABELTRON_MODEL_TYPE=m2m100 ./tests/e2e_cache_test.sh
+
+test-cache-comprehensive: ## Run comprehensive cache end-to-end tests
+	@echo "Running comprehensive cache end-to-end tests..."
+	@BABELTRON_MODEL_TYPE=m2m100 ./tests/e2e_cache_comprehensive_test.sh

babeltron/app/cache/__init__.py

@@ -0,0 +1,45 @@
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class CacheInterface(ABC):
+    """
+    Abstract base class for cache interface.
+
+    Any concrete implementation must provide methods for:
+    - Save data to cache with a TTL
+    - Get data from cache
+    - Delete data from cache
+    """
+
+    @abstractmethod
+    def save(self, key: str, value: Any, ttl: int) -> None:
+        """
+        Save data to cache with a TTL.
+
+        Args:
+            key: The key to save the data to
+            value: The data to save
+            ttl: The time to live for the data
+        """
+        pass
+
+    @abstractmethod
+    def get(self, key: str) -> Any:
+        """
+        Get data from cache.
+
+        Args:
+            key: The key to retrieve the data from
+
+        Returns:
+            The data retrieved from cache
+        """
+        pass
+
+    @abstractmethod
+    def delete(self, key: str) -> None:
+        """
+        Delete data from cache.
+        """
+        pass

babeltron/app/cache/base.py

@@ -0,0 +1,118 @@
+import logging
+from typing import Generic, Optional, TypeVar, cast
+
+from babeltron.app.cache.base import CacheInterface
+from babeltron.app.cache.utils import generate_cache_key
+from babeltron.app.cache.valkey import ValkeyCache
+from babeltron.app.config import CACHE_TTL_SECONDS
+
+# Type variable for generic response types
+T = TypeVar("T")
+
+
+class CacheService(Generic[T]):
+    """
+    Service for caching translation and detection results
+    """
+
+    def __init__(
+        self,
+        cache_client: Optional[CacheInterface] = None,
+        ttl: int = CACHE_TTL_SECONDS,
+    ):
+        """
+        Initialize the cache service
+
+        Args:
+            cache_client: Optional cache client, defaults to ValkeyCache
+            ttl: Time to live for cache entries in seconds
+        """
+        self.cache = cache_client or ValkeyCache()
+        self.ttl = ttl
+        self.logger = logging.getLogger(__name__)
+
+    def get_translation(self, text: str, src_lang: str, tgt_lang: str) -> Optional[T]:
+        """
+        Get a cached translation result
+
+        Args:
+            text: The text to translate
+            src_lang: Source language
+            tgt_lang: Target language
+
+        Returns:
+            Cached translation result or None if not found
+        """
+        cache_key = generate_cache_key("translate", text, src_lang, tgt_lang)
+        self.logger.debug(f"Looking up translation in cache with key: {cache_key}")
+
+        cached_result = self.cache.get(cache_key)
+
+        if cached_result:
+            self.logger.info(f"Cache hit for translation: {src_lang} -> {tgt_lang}")
+            return cast(T, cached_result)
+
+        self.logger.info(f"Cache miss for translation: {src_lang} -> {tgt_lang}")
+        return None
+
+    def save_translation(
+        self, text: str, src_lang: str, tgt_lang: str, result: T
+    ) -> None:
+        """
+        Save a translation result to cache
+
+        Args:
+            text: The text that was translated
+            src_lang: Source language
+            tgt_lang: Target language
+            result: Translation result to cache
+        """
+        cache_key = generate_cache_key("translate", text, src_lang, tgt_lang)
+        self.logger.debug(f"Saving translation to cache with key: {cache_key}")
+
+        try:
+            self.cache.save(cache_key, result, self.ttl)
+            self.logger.info(f"Cached translation result: {src_lang} -> {tgt_lang}")
+        except Exception as e:
+            self.logger.error(f"Failed to cache translation result: {str(e)}")
+
+    def get_detection(self, text: str) -> Optional[T]:
+        """
+        Get a cached language detection result
+
+        Args:
+            text: The text to detect language for
+
+        Returns:
+            Cached detection result or None if not found
+        """
+        cache_key = generate_cache_key("detect", text)
+        self.logger.debug(
+            f"Looking up language detection in cache with key: {cache_key}"
+        )
+
+        cached_result = self.cache.get(cache_key)
+
+        if cached_result:
+            self.logger.info("Cache hit for language detection")
+            return cast(T, cached_result)
+
+        self.logger.info("Cache miss for language detection")
+        return None
+
+    def save_detection(self, text: str, result: T) -> None:
+        """
+        Save a language detection result to cache
+
+        Args:
+            text: The text that was analyzed
+            result: Detection result to cache
+        """
+        cache_key = generate_cache_key("detect", text)
+        self.logger.debug(f"Saving language detection to cache with key: {cache_key}")
+
+        try:
+            self.cache.save(cache_key, result, self.ttl)
+            self.logger.info("Cached language detection result")
+        except Exception as e:
+            self.logger.error(f"Failed to cache language detection result: {str(e)}")

babeltron/app/cache/service.py

@@ -0,0 +1,72 @@
+import hashlib
+import re
+import unicodedata
+from typing import Optional
+
+
+def sanitize_text(text: str) -> str:
+    """
+    Sanitize text for cache key generation:
+    1. Normalize Unicode characters to their canonical form
+    2. Preserve important punctuation
+    3. Trim excess whitespace
+    4. Convert to lowercase for consistency
+
+    Args:
+        text: The text to sanitize
+
+    Returns:
+        Sanitized text
+    """
+    # Normalize Unicode characters (NFC form)
+    normalized = unicodedata.normalize("NFC", text)
+
+    # Trim excess whitespace (replace multiple spaces with a single space)
+    # but preserve newlines and other meaningful spacing
+    trimmed = re.sub(r"\s+", " ", normalized).strip()
+
+    # Convert to lowercase for consistency
+    lowercased = trimmed.lower()
+
+    return lowercased
+
+
+def generate_cache_key(
+    prefix: str,
+    text: str,
+    src_lang: Optional[str] = None,
+    tgt_lang: Optional[str] = None,
+) -> str:
+    """
+    Generate a cache key for the given text and languages.
+
+    Args:
+        prefix: The prefix for the cache key (e.g., 'translate', 'detect')
+        text: The text to generate a key for
+        src_lang: Optional source language
+        tgt_lang: Optional target language
+
+    Returns:
+        A cache key string
+    """
+    # Sanitize the text
+    sanitized = sanitize_text(text)
+
+    # Build the key components
+    key_parts = [prefix]
+
+    if src_lang:
+        key_parts.append(src_lang)
+
+    if tgt_lang:
+        key_parts.append(tgt_lang)
+
+    key_parts.append(sanitized)
+
+    # Join the parts with a colon
+    key_string = ":".join(key_parts)
+
+    # Generate MD5 hash
+    md5_hash = hashlib.md5(key_string.encode("utf-8")).hexdigest()
+
+    return md5_hash