hanuscode 1.0.0__py3-none-any.whl

hanus/cache/response_cache.py

@@ -0,0 +1,560 @@
+# hanus/cache/response_cache.py
+"""
+Cache Inteligente de Respuestas.
+
+Funcionalidades:
+- Hash de consultas frecuentes del proyecto
+- Invalidación smart por cambios en código
+- TTL configurable por tipo de consulta
+- Estadísticas de hit/miss
+- Persistencia a disco
+"""
+from __future__ import annotations
+import json
+import hashlib
+import time
+import threading
+from dataclasses import dataclass, field, asdict
+from pathlib import Path
+from typing import Dict, List, Optional, Any, Set, Callable
+from datetime import datetime
+from collections import OrderedDict
+
+
+@dataclass
+class CacheEntry:
+    """Una entrada en el cache."""
+    key: str                          # Hash de la consulta
+    query: str                        # Query original (truncada)
+    response: str                     # Respuesta cacheada
+    model: str                        # Modelo usado
+    tokens_in: int                    # Tokens de entrada
+    tokens_out: int                   # Tokens de salida
+    created_at: float                 # Timestamp de creación
+    last_accessed: float              # Último acceso
+    access_count: int                 # Veces accedido
+    ttl: int                          # Time-to-live en segundos
+    files_hash: str                   # Hash de archivos involucrados
+    tags: List[str] = field(default_factory=list)  # Tags para categorización
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def is_expired(self) -> bool:
+        """Verifica si la entrada ha expirado."""
+        return time.time() > (self.created_at + self.ttl)
+
+    @property
+    def age_seconds(self) -> float:
+        """Edad de la entrada en segundos."""
+        return time.time() - self.created_at
+
+
+@dataclass
+class CacheStats:
+    """Estadísticas del cache."""
+    hits: int = 0
+    misses: int = 0
+    evictions: int = 0
+    invalidations: int = 0
+    total_tokens_saved: int = 0
+    total_queries: int = 0
+
+    @property
+    def hit_rate(self) -> float:
+        """Tasa de aciertos."""
+        total = self.hits + self.misses
+        return (self.hits / total * 100) if total > 0 else 0.0
+
+
+@dataclass
+class FileFingerprint:
+    """Huella digital de un archivo para invalidación."""
+    path: str
+    mtime: float
+    size: int
+    hash: str
+
+
+class ResponseCache:
+    """
+    Cache inteligente de respuestas con invalidación smart.
+
+    Features:
+    - Cache por hash de query + contexto
+    - Invalidación por cambios en archivos
+    - TTL configurable
+    - LRU eviction
+    - Estadísticas detalladas
+    - Thread-safe
+
+    Uso:
+        cache = ResponseCache()
+
+        # Intentar obtener del cache
+        entry = cache.get(query, model="gpt-4", files=["main.py"])
+        if entry:
+            return entry.response
+
+        # Guardar en cache
+        cache.set(query, response, model="gpt-4", tokens=(100, 200))
+    """
+
+    DEFAULT_TTL = 3600 * 24 * 7  # 7 días
+    MAX_ENTRIES = 1000
+    MAX_RESPONSE_SIZE = 50000    # 50KB max por respuesta
+
+    # TTLs por tipo de consulta
+    TTL_BY_TYPE = {
+        "code_generation": 3600 * 24 * 7,    # 7 días para código
+        "explanation": 3600 * 24 * 3,        # 3 días para explicaciones
+        "analysis": 3600 * 24 * 1,           # 1 día para análisis
+        "debugging": 3600 * 12,              # 12 horas para debugging
+        "search": 3600 * 6,                  # 6 horas para búsquedas
+        "default": 3600 * 24,                # 1 día por defecto
+    }
+
+    def __init__(
+        self,
+        cache_dir: Optional[Path] = None,
+        max_entries: int = MAX_ENTRIES,
+        default_ttl: int = DEFAULT_TTL,
+    ):
+        self.cache_dir = cache_dir or (Path.home() / ".hanus" / "cache")
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+
+        self.max_entries = max_entries
+        self.default_ttl = default_ttl
+
+        # Cache en memoria (LRU)
+        self._cache: OrderedDict[str, CacheEntry] = OrderedDict()
+        self._lock = threading.RLock()
+
+        # Fingerprints de archivos para invalidación
+        self._fingerprints: Dict[str, FileFingerprint] = {}
+
+        # Estadísticas
+        self._stats = CacheStats()
+
+        # Callbacks de invalidación
+        self._invalidation_callbacks: List[Callable[[str], None]] = []
+
+        # Cargar cache persistido
+        self._load_cache()
+
+    # ══════════════════════════════════════════════════════════════════════════
+    # API PÚBLICA
+    # ══════════════════════════════════════════════════════════════════════════
+
+    def get(
+        self,
+        query: str,
+        model: str = "",
+        files: Optional[List[str]] = None,
+        context: Optional[str] = None,
+    ) -> Optional[CacheEntry]:
+        """
+        Intenta obtener una respuesta del cache.
+
+        Args:
+            query: La consulta del usuario
+            model: Modelo usado (para verificar que coincide)
+            files: Lista de archivos involucrados
+            context: Contexto adicional para el hash
+
+        Returns:
+            CacheEntry si existe y es válido, None si no
+        """
+        key = self._compute_key(query, model, files, context)
+
+        with self._lock:
+            entry = self._cache.get(key)
+
+            if entry is None:
+                self._stats.misses += 1
+                self._stats.total_queries += 1
+                return None
+
+            # Verificar expiración
+            if entry.is_expired:
+                self._evict(key)
+                self._stats.misses += 1
+                self._stats.total_queries += 1
+                return None
+
+            # Verificar que los archivos no han cambiado
+            if files and self._files_changed(files, entry.files_hash):
+                self._evict(key)
+                self._stats.invalidations += 1
+                self._stats.misses += 1
+                self._stats.total_queries += 1
+                return None
+
+            # Verificar modelo
+            if model and entry.model != model:
+                self._stats.misses += 1
+                self._stats.total_queries += 1
+                return None
+
+            # Cache hit!
+            entry.last_accessed = time.time()
+            entry.access_count += 1
+
+            # Mover al final (LRU)
+            self._cache.move_to_end(key)
+
+            self._stats.hits += 1
+            self._stats.total_queries += 1
+            self._stats.total_tokens_saved += entry.tokens_out
+
+            return entry
+
+    def set(
+        self,
+        query: str,
+        response: str,
+        model: str = "",
+        tokens: tuple = (0, 0),
+        files: Optional[List[str]] = None,
+        context: Optional[str] = None,
+        ttl: Optional[int] = None,
+        tags: Optional[List[str]] = None,
+        query_type: str = "default",
+    ) -> CacheEntry:
+        """
+        Guarda una respuesta en el cache.
+
+        Args:
+            query: La consulta del usuario
+            response: La respuesta a cachear
+            model: Modelo usado
+            tokens: (tokens_in, tokens_out)
+            files: Lista de archivos involucrados
+            context: Contexto adicional
+            ttl: TTL personalizado (usa default si no se especifica)
+            tags: Tags para categorización
+            query_type: Tipo de consulta para determinar TTL
+
+        Returns:
+            La entrada creada
+        """
+        # Verificar tamaño
+        if len(response) > self.MAX_RESPONSE_SIZE:
+            response = response[:self.MAX_RESPONSE_SIZE] + "...[truncated]"
+
+        key = self._compute_key(query, model, files, context)
+        files_hash = self._compute_files_hash(files) if files else ""
+
+        # Determinar TTL
+        if ttl is None:
+            ttl = self.TTL_BY_TYPE.get(query_type, self.default_ttl)
+
+        entry = CacheEntry(
+            key=key,
+            query=query[:200],  # Truncar query para storage
+            response=response,
+            model=model,
+            tokens_in=tokens[0],
+            tokens_out=tokens[1],
+            created_at=time.time(),
+            last_accessed=time.time(),
+            access_count=0,
+            ttl=ttl,
+            files_hash=files_hash,
+            tags=tags or [],
+        )
+
+        with self._lock:
+            # Evictar si estamos al límite
+            while len(self._cache) >= self.max_entries:
+                self._evict_oldest()
+
+            self._cache[key] = entry
+
+            # Actualizar fingerprints de archivos
+            if files:
+                self._update_fingerprints(files)
+
+        # Guardar periódicamente
+        if len(self._cache) % 50 == 0:
+            self._save_cache()
+
+        return entry
+
+    def invalidate(
+        self,
+        file_path: Optional[str] = None,
+        pattern: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+    ) -> int:
+        """
+        Invalida entradas del cache.
+
+        Args:
+            file_path: Invalidar entradas que involucran este archivo
+            pattern: Invalidar entradas cuyo query coincide con el patrón
+            tags: Invalidar entradas con estos tags
+
+        Returns:
+            Número de entradas invalidadas
+        """
+        count = 0
+
+        with self._lock:
+            keys_to_evict = []
+
+            for key, entry in self._cache.items():
+                should_evict = False
+
+                # Por archivo
+                if file_path:
+                    if file_path in entry.query or file_path in str(entry.metadata.get("files", [])):
+                        should_evict = True
+
+                # Por patrón
+                if pattern and not should_evict:
+                    import re
+                    if re.search(pattern, entry.query, re.IGNORECASE):
+                        should_evict = True
+
+                # Por tags
+                if tags and not should_evict:
+                    if any(tag in entry.tags for tag in tags):
+                        should_evict = True
+
+                if should_evict:
+                    keys_to_evict.append(key)
+
+            for key in keys_to_evict:
+                self._evict(key)
+                count += 1
+                self._stats.invalidations += 1
+
+        if count > 0:
+            self._save_cache()
+
+        return count
+
+    def clear(self) -> int:
+        """
+        Limpia todo el cache.
+
+        Returns:
+            Número de entradas eliminadas
+        """
+        with self._lock:
+            count = len(self._cache)
+            self._cache.clear()
+            self._fingerprints.clear()
+            self._save_cache()
+            return count
+
+    def get_stats(self) -> Dict[str, Any]:
+        """Retorna estadísticas del cache."""
+        with self._lock:
+            return {
+                "hits": self._stats.hits,
+                "misses": self._stats.misses,
+                "hit_rate": f"{self._stats.hit_rate:.1f}%",
+                "evictions": self._stats.evictions,
+                "invalidations": self._stats.invalidations,
+                "total_tokens_saved": self._stats.total_tokens_saved,
+                "total_queries": self._stats.total_queries,
+                "entries": len(self._cache),
+                "max_entries": self.max_entries,
+                "files_tracked": len(self._fingerprints),
+            }
+
+    def get_top_queries(self, limit: int = 10) -> List[Dict]:
+        """Retorna las queries más accedidas."""
+        with self._lock:
+            sorted_entries = sorted(
+                self._cache.values(),
+                key=lambda e: e.access_count,
+                reverse=True
+            )[:limit]
+
+            return [
+                {
+                    "query": e.query[:100],
+                    "access_count": e.access_count,
+                    "age_hours": e.age_seconds / 3600,
+                    "tokens_saved": e.tokens_out * e.access_count,
+                }
+                for e in sorted_entries
+            ]
+
+    def add_invalidation_callback(self, callback: Callable[[str], None]) -> None:
+        """Añade un callback para cuando se invalida una entrada."""
+        self._invalidation_callbacks.append(callback)
+
+    # ══════════════════════════════════════════════════════════════════════════
+    # MÉTODOS PRIVADOS
+    # ══════════════════════════════════════════════════════════════════════════
+
+    def _compute_key(
+        self,
+        query: str,
+        model: str,
+        files: Optional[List[str]],
+        context: Optional[str],
+    ) -> str:
+        """Computa el hash key para una consulta."""
+        content = query.lower().strip()
+
+        if model:
+            content += f"|model:{model}"
+
+        if files:
+            # Solo incluir nombres de archivo, no contenido
+            content += f"|files:{','.join(sorted(files))}"
+
+        if context:
+            # Hash del contexto para evitar keys muy largas
+            context_hash = hashlib.md5(context.encode()).hexdigest()[:8]
+            content += f"|ctx:{context_hash}"
+
+        return hashlib.sha256(content.encode()).hexdigest()[:32]
+
+    def _compute_files_hash(self, files: List[str]) -> str:
+        """Computa un hash de los archivos involucrados."""
+        if not files:
+            return ""
+
+        content = "|".join(sorted(files))
+        return hashlib.md5(content.encode()).hexdigest()[:16]
+
+    def _files_changed(self, files: List[str], old_hash: str) -> bool:
+        """Verifica si los archivos han cambiado desde la última vez."""
+        if not files or not old_hash:
+            return False
+
+        for file_path in files:
+            fingerprint = self._fingerprints.get(file_path)
+
+            if fingerprint:
+                try:
+                    p = Path(file_path)
+                    if p.exists():
+                        if p.stat().st_mtime != fingerprint.mtime:
+                            return True
+                        if p.stat().st_size != fingerprint.size:
+                            return True
+                except Exception:
+                    pass
+
+        return False
+
+    def _update_fingerprints(self, files: List[str]) -> None:
+        """Actualiza los fingerprints de archivos."""
+        for file_path in files:
+            try:
+                p = Path(file_path)
+                if p.exists():
+                    stat = p.stat()
+                    self._fingerprints[file_path] = FileFingerprint(
+                        path=file_path,
+                        mtime=stat.st_mtime,
+                        size=stat.st_size,
+                        hash=hashlib.md5(p.read_bytes()).hexdigest()[:16]
+                    )
+            except Exception:
+                pass
+
+    def _evict(self, key: str) -> None:
+        """Evicta una entrada específica."""
+        if key in self._cache:
+            del self._cache[key]
+            self._stats.evictions += 1
+
+            # Notificar callbacks
+            for callback in self._invalidation_callbacks:
+                try:
+                    callback(key)
+                except Exception:
+                    pass
+
+    def _evict_oldest(self) -> None:
+        """Evicta la entrada más antigua (LRU)."""
+        if self._cache:
+            oldest_key = next(iter(self._cache))
+            self._evict(oldest_key)
+
+    def _load_cache(self) -> None:
+        """Carga el cache desde disco."""
+        cache_file = self.cache_dir / "response_cache.json"
+
+        if not cache_file.exists():
+            return
+
+        try:
+            data = json.loads(cache_file.read_text(encoding="utf-8"))
+
+            # Cargar entradas
+            for entry_data in data.get("entries", []):
+                entry = CacheEntry(**entry_data)
+                if not entry.is_expired:
+                    self._cache[entry.key] = entry
+
+            # Cargar fingerprints
+            for fp_data in data.get("fingerprints", []):
+                fp = FileFingerprint(**fp_data)
+                self._fingerprints[fp.path] = fp
+
+            # Cargar estadísticas
+            stats_data = data.get("stats", {})
+            self._stats = CacheStats(**stats_data)
+
+        except Exception as e:
+            print(f"[Cache] Error loading cache: {e}")
+
+    def _save_cache(self) -> None:
+        """Guarda el cache a disco."""
+        cache_file = self.cache_dir / "response_cache.json"
+
+        try:
+            # Solo guardar las 500 entradas más recientes
+            entries_to_save = list(self._cache.values())[-500:]
+
+            data = {
+                "entries": [asdict(e) for e in entries_to_save],
+                "fingerprints": [asdict(fp) for fp in self._fingerprints.values()],
+                "stats": asdict(self._stats),
+                "saved_at": datetime.now().isoformat(),
+            }
+
+            cache_file.write_text(
+                json.dumps(data, indent=2, ensure_ascii=False),
+                encoding="utf-8"
+            )
+
+        except Exception as e:
+            print(f"[Cache] Error saving cache: {e}")
+
+    def __len__(self) -> int:
+        return len(self._cache)
+
+    def __contains__(self, key: str) -> bool:
+        return key in self._cache
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# INSTANCIA GLOBAL
+# ══════════════════════════════════════════════════════════════════════════════
+
+_cache_instance: Optional[ResponseCache] = None
+
+
+def get_cache() -> ResponseCache:
+    """Obtiene la instancia global del cache."""
+    global _cache_instance
+    if _cache_instance is None:
+        _cache_instance = ResponseCache()
+    return _cache_instance
+
+
+def reset_cache() -> None:
+    """Resetea la instancia global del cache."""
+    global _cache_instance
+    if _cache_instance:
+        _cache_instance.clear()
+    _cache_instance = None