Add model caching infrastructure (#35)

Implemented singleton model cache with LRU eviction:

1. backend/core/model_cache.py:
- Singleton pattern for global cache
- Thread-safe operations
- LRU eviction policy
- Memory limit enforcement
- Cache statistics tracking

2. backend/config/cache_config.py:
- Configurable cache limits
- Model size estimates
- Enable/disable toggle

3. backend/tests/test_model_cache.py:
- 7 comprehensive tests
- Tests singleton, LRU, memory limits
- Statistics validation

Features:
- Max 10 models cached
- Max 8GB memory usage
- Automatic LRU eviction
- Thread-safe access
- Real-time statistics

Part 1 of 2 - Next: Integrate with detectors

Part of #35

backend/config/cache_config.py

@@ -0,0 +1,36 @@
+"""
+Cache configuration for VeriFile-X model caching.
+"""
+from typing import Dict, Any
+
+
+class CacheConfig:
+    """Model cache configuration."""
+    
+    # Maximum number of models to cache
+    MAX_MODELS = 10
+    
+    # Maximum memory usage in MB
+    MAX_MEMORY_MB = 8000  # 8GB
+    
+    # Enable/disable caching
+    ENABLE_CACHE = True
+    
+    # Cache eviction policy
+    EVICTION_POLICY = "lru"  # least-recently-used
+    
+    # Model size estimates (in MB)
+    MODEL_SIZES = {
+        'stable-diffusion-2-1': 4000,
+        'clip-vit-b-32': 350,
+    }
+    
+    @classmethod
+    def to_dict(cls) -> Dict[str, Any]:
+        """Convert config to dictionary."""
+        return {
+            'max_models': cls.MAX_MODELS,
+            'max_memory_mb': cls.MAX_MEMORY_MB,
+            'enable_cache': cls.ENABLE_CACHE,
+            'eviction_policy': cls.EVICTION_POLICY,
+        }

backend/core/model_cache.py

@@ -0,0 +1,203 @@
+"""
+Singleton model cache manager for VeriFile-X.
+
+Provides thread-safe model caching with LRU eviction to improve
+performance by avoiding repeated model loading.
+"""
+import threading
+from typing import Any, Dict, Optional, OrderedDict
+from collections import OrderedDict as OrderedDictType
+import time
+from backend.core.logger import setup_logger
+
+logger = setup_logger(__name__)
+
+
+class ModelCache:
+    """Singleton model cache with LRU eviction and memory limits."""
+    
+    _instance = None
+    _lock = threading.Lock()
+    
+    def __new__(cls):
+        """Ensure only one instance exists (singleton pattern)."""
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = super().__new__(cls)
+                    cls._instance._initialized = False
+        return cls._instance
+    
+    def __init__(self):
+        """Initialize cache on first creation."""
+        if self._initialized:
+            return
+        
+        self._cache: OrderedDictType[str, Dict[str, Any]] = OrderedDict()
+        self._lock = threading.Lock()
+        self._stats = {
+            'hits': 0,
+            'misses': 0,
+            'evictions': 0,
+            'total_memory_mb': 0.0
+        }
+        
+        # Configuration (can be overridden)
+        self.max_models = 10
+        self.max_memory_mb = 8000  # 8GB
+        self.enable_cache = True
+        
+        self._initialized = True
+        logger.info("ModelCache initialized")
+    
+    def get(self, key: str) -> Optional[Any]:
+        """
+        Get model from cache.
+        
+        Args:
+            key: Model identifier (e.g., 'stable-diffusion-2-1')
+            
+        Returns:
+            Cached model or None if not found
+        """
+        if not self.enable_cache:
+            return None
+        
+        with self._lock:
+            if key in self._cache:
+                # Move to end (most recently used)
+                self._cache.move_to_end(key)
+                self._stats['hits'] += 1
+                
+                model_info = self._cache[key]
+                logger.debug(
+                    f"Cache HIT: {key} "
+                    f"(size: {model_info['size_mb']:.1f}MB, "
+                    f"age: {time.time() - model_info['timestamp']:.1f}s)"
+                )
+                return model_info['model']
+            else:
+                self._stats['misses'] += 1
+                logger.debug(f"Cache MISS: {key}")
+                return None
+    
+    def set(self, key: str, model: Any, size_mb: float):
+        """
+        Store model in cache.
+        
+        Args:
+            key: Model identifier
+            model: Model object to cache
+            size_mb: Estimated memory size in MB
+        """
+        if not self.enable_cache:
+            return
+        
+        with self._lock:
+            # Check if we need to evict
+            while (len(self._cache) >= self.max_models or 
+                   self._stats['total_memory_mb'] + size_mb > self.max_memory_mb):
+                if not self._cache:
+                    logger.warning("Cannot cache: size exceeds max_memory_mb")
+                    return
+                self._evict_lru()
+            
+            # Store model
+            self._cache[key] = {
+                'model': model,
+                'size_mb': size_mb,
+                'timestamp': time.time()
+            }
+            self._cache.move_to_end(key)
+            self._stats['total_memory_mb'] += size_mb
+            
+            logger.info(
+                f"Cached model: {key} "
+                f"(size: {size_mb:.1f}MB, "
+                f"total: {self._stats['total_memory_mb']:.1f}MB)"
+            )
+    
+    def _evict_lru(self):
+        """Evict least recently used model."""
+        if not self._cache:
+            return
+        
+        # Remove first item (least recently used)
+        key, model_info = self._cache.popitem(last=False)
+        self._stats['total_memory_mb'] -= model_info['size_mb']
+        self._stats['evictions'] += 1
+        
+        logger.info(
+            f"Evicted LRU model: {key} "
+            f"(freed: {model_info['size_mb']:.1f}MB)"
+        )
+        
+        # Clean up model if it has cleanup method
+        if hasattr(model_info['model'], 'cleanup'):
+            try:
+                model_info['model'].cleanup()
+            except Exception as e:
+                logger.warning(f"Error cleaning up {key}: {e}")
+    
+    def clear(self):
+        """Clear all cached models."""
+        with self._lock:
+            count = len(self._cache)
+            memory_freed = self._stats['total_memory_mb']
+            
+            # Clean up all models
+            for key, model_info in self._cache.items():
+                if hasattr(model_info['model'], 'cleanup'):
+                    try:
+                        model_info['model'].cleanup()
+                    except Exception as e:
+                        logger.warning(f"Error cleaning up {key}: {e}")
+            
+            self._cache.clear()
+            self._stats['total_memory_mb'] = 0.0
+            
+            logger.info(
+                f"Cleared cache: {count} models, "
+                f"{memory_freed:.1f}MB freed"
+            )
+    
+    def stats(self) -> Dict[str, Any]:
+        """
+        Get cache statistics.
+        
+        Returns:
+            Dictionary with cache metrics
+        """
+        with self._lock:
+            total_requests = self._stats['hits'] + self._stats['misses']
+            hit_rate = (self._stats['hits'] / total_requests 
+                       if total_requests > 0 else 0.0)
+            
+            return {
+                'total_models': len(self._cache),
+                'memory_mb': self._stats['total_memory_mb'],
+                'max_memory_mb': self.max_memory_mb,
+                'cache_hits': self._stats['hits'],
+                'cache_misses': self._stats['misses'],
+                'hit_rate': hit_rate,
+                'evictions': self._stats['evictions'],
+                'enabled': self.enable_cache,
+                'models': list(self._cache.keys())
+            }
+    
+    def reset_stats(self):
+        """Reset statistics counters."""
+        with self._lock:
+            self._stats['hits'] = 0
+            self._stats['misses'] = 0
+            self._stats['evictions'] = 0
+            logger.info("Cache statistics reset")
+
+
+# Global cache instance
+_cache = ModelCache()
+
+
+def get_model_cache() -> ModelCache:
+    """Get the global model cache instance."""
+    return _cache

backend/tests/test_model_cache.py

@@ -0,0 +1,150 @@
+"""
+Tests for model cache system.
+"""
+import pytest
+import time
+from backend.core.model_cache import ModelCache, get_model_cache
+
+
+def test_cache_singleton():
+    """Test that ModelCache is a singleton."""
+    cache1 = ModelCache()
+    cache2 = ModelCache()
+    cache3 = get_model_cache()
+    
+    assert cache1 is cache2
+    assert cache2 is cache3
+    
+    # All should reference the same instance
+    cache1.set('test', 'value', 1.0)
+    assert cache2.get('test') == 'value'
+    assert cache3.get('test') == 'value'
+
+
+def test_cache_basic_operations():
+    """Test basic cache get/set operations."""
+    cache = ModelCache()
+    cache.clear()
+    
+    # Cache miss
+    assert cache.get('model1') is None
+    
+    # Cache set
+    cache.set('model1', {'data': 'test'}, 100.0)
+    
+    # Cache hit
+    result = cache.get('model1')
+    assert result == {'data': 'test'}
+    
+    # Statistics
+    stats = cache.stats()
+    assert stats['total_models'] == 1
+    assert stats['memory_mb'] == 100.0
+    assert stats['cache_hits'] >= 1
+    assert stats['cache_misses'] >= 1
+
+
+def test_cache_lru_eviction():
+    """Test LRU eviction when cache is full."""
+    cache = ModelCache()
+    cache.clear()
+    cache.max_models = 3  # Small limit for testing
+    
+    # Add 3 models
+    cache.set('model1', 'data1', 100.0)
+    cache.set('model2', 'data2', 100.0)
+    cache.set('model3', 'data3', 100.0)
+    
+    assert cache.stats()['total_models'] == 3
+    
+    # Access model1 to make it recently used
+    cache.get('model1')
+    
+    # Add 4th model - should evict model2 (least recently used)
+    cache.set('model4', 'data4', 100.0)
+    
+    assert cache.stats()['total_models'] == 3
+    assert cache.get('model1') is not None  # Still there (recently used)
+    assert cache.get('model2') is None       # Evicted
+    assert cache.get('model3') is not None  # Still there
+    assert cache.get('model4') is not None  # Newly added
+
+
+def test_cache_memory_limit():
+    """Test memory limit enforcement."""
+    cache = ModelCache()
+    cache.clear()
+    cache.max_memory_mb = 500  # 500MB limit
+    cache.max_models = 10
+    
+    # Add models totaling 300MB
+    cache.set('model1', 'data1', 100.0)
+    cache.set('model2', 'data2', 100.0)
+    cache.set('model3', 'data3', 100.0)
+    
+    assert cache.stats()['memory_mb'] == 300.0
+    
+    # Try to add 300MB more (total would be 600MB > 500MB limit)
+    cache.set('model4', 'data4', 300.0)
+    
+    # Should have evicted models to stay under limit
+    stats = cache.stats()
+    assert stats['memory_mb'] <= 500.0
+    assert stats['evictions'] >= 1
+
+
+def test_cache_clear():
+    """Test cache clearing."""
+    cache = ModelCache()
+    
+    cache.set('model1', 'data1', 100.0)
+    cache.set('model2', 'data2', 100.0)
+    
+    assert cache.stats()['total_models'] == 2
+    
+    cache.clear()
+    
+    stats = cache.stats()
+    assert stats['total_models'] == 0
+    assert stats['memory_mb'] == 0.0
+    assert cache.get('model1') is None
+    assert cache.get('model2') is None
+
+
+def test_cache_statistics():
+    """Test cache statistics tracking."""
+    cache = ModelCache()
+    cache.clear()
+    cache.reset_stats()
+    
+    # Generate some cache activity
+    cache.get('missing')  # miss
+    cache.set('model1', 'data', 100.0)
+    cache.get('model1')  # hit
+    cache.get('model1')  # hit
+    cache.get('missing2')  # miss
+    
+    stats = cache.stats()
+    
+    assert stats['cache_hits'] >= 2
+    assert stats['cache_misses'] >= 2
+    assert stats['hit_rate'] > 0
+    assert 'models' in stats
+    assert 'model1' in stats['models']
+
+
+def test_cache_disabled():
+    """Test cache when disabled."""
+    cache = ModelCache()
+    cache.enable_cache = False
+    
+    # Set should not cache
+    cache.set('model1', 'data1', 100.0)
+    
+    # Get should return None
+    assert cache.get('model1') is None
+    
+    # Re-enable
+    cache.enable_cache = True
+    cache.set('model2', 'data2', 100.0)
+    assert cache.get('model2') == 'data2'