codexa 0.4.0__py3-none-any.whl

semantic_code_intelligence/llm/cache.py

@@ -0,0 +1,219 @@
+"""LLM response cache — disk-backed cache with TTL expiration.
+
+Caches LLM responses keyed by a deterministic hash of the request
+parameters (provider, model, messages/prompt, temperature, max_tokens).
+Supports time-to-live (TTL) expiration and max-entry eviction.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from semantic_code_intelligence.llm.provider import LLMMessage, LLMResponse
+
+
+@dataclass
+class CacheEntry:
+    """A single cached LLM response with metadata."""
+
+    response: dict[str, Any]
+    timestamp: float
+    provider: str
+    model: str
+
+
+@dataclass
+class CacheStats:
+    """Cache performance statistics."""
+
+    hits: int = 0
+    misses: int = 0
+    evictions: int = 0
+    size: int = 0
+
+    @property
+    def hit_rate(self) -> float:
+        """Return cache hit rate as a percentage."""
+        total = self.hits + self.misses
+        if total == 0:
+            return 0.0
+        return (self.hits / total) * 100.0
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "hits": self.hits,
+            "misses": self.misses,
+            "evictions": self.evictions,
+            "size": self.size,
+            "hit_rate": round(self.hit_rate, 2),
+        }
+
+
+class LLMCache:
+    """Disk-backed LLM response cache with TTL and max-entry limits.
+
+    Cache entries are evicted when they exceed ``ttl_hours`` or when
+    the total number of entries exceeds ``max_entries`` (oldest first).
+    The cache is persisted as a JSON file to survive process restarts.
+    """
+
+    def __init__(
+        self,
+        cache_dir: str | Path | None = None,
+        ttl_hours: int = 24,
+        max_entries: int = 1000,
+    ) -> None:
+        self._entries: dict[str, dict[str, Any]] = {}
+        self._ttl_seconds: float = ttl_hours * 3600.0
+        self._max_entries: int = max_entries
+        self._stats = CacheStats()
+        self._cache_path: Path | None = None
+        if cache_dir is not None:
+            self._cache_path = Path(cache_dir) / "llm_cache.json"
+            self._load()
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def get(
+        self,
+        provider: str,
+        model: str,
+        messages: list[LLMMessage] | None = None,
+        prompt: str | None = None,
+        temperature: float = 0.2,
+        max_tokens: int = 2048,
+    ) -> LLMResponse | None:
+        """Look up a cached response.  Returns ``None`` on cache miss."""
+        key = self._make_key(provider, model, messages, prompt, temperature, max_tokens)
+        entry = self._entries.get(key)
+        if entry is None:
+            self._stats.misses += 1
+            return None
+
+        # Check TTL
+        age = time.time() - entry["timestamp"]
+        if age > self._ttl_seconds:
+            del self._entries[key]
+            self._stats.misses += 1
+            self._stats.evictions += 1
+            return None
+
+        self._stats.hits += 1
+        return self._dict_to_response(entry["response"])
+
+    def put(
+        self,
+        response: LLMResponse,
+        provider: str,
+        model: str,
+        messages: list[LLMMessage] | None = None,
+        prompt: str | None = None,
+        temperature: float = 0.2,
+        max_tokens: int = 2048,
+    ) -> None:
+        """Store a response in the cache."""
+        key = self._make_key(provider, model, messages, prompt, temperature, max_tokens)
+        self._entries[key] = {
+            "response": self._response_to_dict(response),
+            "timestamp": time.time(),
+            "provider": provider,
+            "model": model,
+        }
+        self._evict_if_needed()
+        self._stats.size = len(self._entries)
+
+    def clear(self) -> None:
+        """Remove all cache entries."""
+        self._entries.clear()
+        self._stats = CacheStats()
+
+    def save(self) -> None:
+        """Persist cache to disk."""
+        if self._cache_path is None:
+            return
+        self._cache_path.parent.mkdir(parents=True, exist_ok=True)
+        data = json.dumps(self._entries, indent=2, ensure_ascii=False)
+        self._cache_path.write_text(data, encoding="utf-8")
+
+    @property
+    def stats(self) -> CacheStats:
+        """Return current cache statistics."""
+        self._stats.size = len(self._entries)
+        return self._stats
+
+    @property
+    def size(self) -> int:
+        return len(self._entries)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _load(self) -> None:
+        """Load cache entries from disk, dropping expired entries."""
+        if self._cache_path is None or not self._cache_path.exists():
+            return
+        try:
+            raw = json.loads(self._cache_path.read_text(encoding="utf-8"))
+            if not isinstance(raw, dict):
+                return
+            now = time.time()
+            for key, entry in raw.items():
+                if not isinstance(entry, dict):
+                    continue
+                ts = entry.get("timestamp", 0.0)
+                if now - ts <= self._ttl_seconds:
+                    self._entries[key] = entry
+        except (json.JSONDecodeError, OSError):
+            pass
+
+    def _evict_if_needed(self) -> None:
+        """Evict oldest entries when the cache exceeds max size."""
+        while len(self._entries) > self._max_entries:
+            oldest_key = min(self._entries, key=lambda k: self._entries[k]["timestamp"])
+            del self._entries[oldest_key]
+            self._stats.evictions += 1
+
+    @staticmethod
+    def _make_key(
+        provider: str,
+        model: str,
+        messages: list[LLMMessage] | None,
+        prompt: str | None,
+        temperature: float,
+        max_tokens: int,
+    ) -> str:
+        """Create a deterministic cache key from request parameters."""
+        parts: list[str] = [provider, model, str(temperature), str(max_tokens)]
+        if messages is not None:
+            for msg in messages:
+                parts.append(f"{msg.role.value}:{msg.content}")
+        if prompt is not None:
+            parts.append(f"prompt:{prompt}")
+        raw = "\n".join(parts)
+        return hashlib.sha256(raw.encode("utf-8")).hexdigest()
+
+    @staticmethod
+    def _response_to_dict(response: LLMResponse) -> dict[str, Any]:
+        return {
+            "content": response.content,
+            "model": response.model,
+            "provider": response.provider,
+            "usage": response.usage,
+        }
+
+    @staticmethod
+    def _dict_to_response(data: dict[str, Any]) -> LLMResponse:
+        return LLMResponse(
+            content=data.get("content", ""),
+            model=data.get("model", ""),
+            provider=data.get("provider", ""),
+            usage=data.get("usage", {}),
+        )

semantic_code_intelligence/llm/cached_provider.py

@@ -0,0 +1,145 @@
+"""Cached LLM provider wrapper — adds caching and rate limiting to any provider.
+
+``CachedProvider`` wraps an existing :class:`LLMProvider` and transparently
+adds response caching and API-call rate limiting.  It is the primary
+integration point for the Phase 22 caching + rate limiting feature.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from semantic_code_intelligence.llm.cache import LLMCache
+from semantic_code_intelligence.llm.provider import LLMMessage, LLMProvider, LLMResponse
+from semantic_code_intelligence.llm.rate_limiter import RateLimiter
+
+
+class CachedProvider(LLMProvider):
+    """LLM provider wrapper that adds transparent caching and rate limiting.
+
+    Parameters
+    ----------
+    provider : LLMProvider
+        The underlying LLM provider to wrap.
+    cache : LLMCache | None
+        Response cache instance.  ``None`` disables caching.
+    rate_limiter : RateLimiter | None
+        Rate limiter instance.  ``None`` disables rate limiting.
+    """
+
+    def __init__(
+        self,
+        provider: LLMProvider,
+        cache: LLMCache | None = None,
+        rate_limiter: RateLimiter | None = None,
+    ) -> None:
+        self._provider = provider
+        self._cache = cache
+        self._rate_limiter = rate_limiter
+
+    # ------------------------------------------------------------------
+    # LLMProvider interface
+    # ------------------------------------------------------------------
+
+    @property
+    def name(self) -> str:
+        return self._provider.name
+
+    def complete(self, prompt: str, **kwargs: Any) -> LLMResponse:
+        temperature = kwargs.get("temperature", 0.2)
+        max_tokens = kwargs.get("max_tokens", 2048)
+
+        # 1. Check cache
+        if self._cache is not None:
+            cached = self._cache.get(
+                provider=self._provider.name,
+                model=getattr(self._provider, "model", ""),
+                prompt=prompt,
+                temperature=temperature,
+                max_tokens=max_tokens,
+            )
+            if cached is not None:
+                return cached
+
+        # 2. Rate limit
+        if self._rate_limiter is not None and self._rate_limiter.is_enabled:
+            self._rate_limiter.acquire(estimated_tokens=max_tokens)
+
+        # 3. Call underlying provider
+        response = self._provider.complete(prompt, **kwargs)
+
+        # 4. Record token usage
+        if self._rate_limiter is not None and self._rate_limiter.is_enabled:
+            total_tokens = response.usage.get("total_tokens", 0)
+            self._rate_limiter.record_usage(total_tokens)
+
+        # 5. Store in cache
+        if self._cache is not None:
+            self._cache.put(
+                response=response,
+                provider=self._provider.name,
+                model=getattr(self._provider, "model", ""),
+                prompt=prompt,
+                temperature=temperature,
+                max_tokens=max_tokens,
+            )
+
+        return response
+
+    def chat(self, messages: list[LLMMessage], **kwargs: Any) -> LLMResponse:
+        temperature = kwargs.get("temperature", 0.2)
+        max_tokens = kwargs.get("max_tokens", 2048)
+
+        # 1. Check cache
+        if self._cache is not None:
+            cached = self._cache.get(
+                provider=self._provider.name,
+                model=getattr(self._provider, "model", ""),
+                messages=messages,
+                temperature=temperature,
+                max_tokens=max_tokens,
+            )
+            if cached is not None:
+                return cached
+
+        # 2. Rate limit
+        if self._rate_limiter is not None and self._rate_limiter.is_enabled:
+            self._rate_limiter.acquire(estimated_tokens=max_tokens)
+
+        # 3. Call underlying provider
+        response = self._provider.chat(messages, **kwargs)
+
+        # 4. Record token usage
+        if self._rate_limiter is not None and self._rate_limiter.is_enabled:
+            total_tokens = response.usage.get("total_tokens", 0)
+            self._rate_limiter.record_usage(total_tokens)
+
+        # 5. Store in cache
+        if self._cache is not None:
+            self._cache.put(
+                response=response,
+                provider=self._provider.name,
+                model=getattr(self._provider, "model", ""),
+                messages=messages,
+                temperature=temperature,
+                max_tokens=max_tokens,
+            )
+
+        return response
+
+    def is_available(self) -> bool:
+        return self._provider.is_available()
+
+    # ------------------------------------------------------------------
+    # Extra helpers
+    # ------------------------------------------------------------------
+
+    @property
+    def inner(self) -> LLMProvider:
+        """Return the wrapped provider."""
+        return self._provider
+
+    def save_cache(self) -> None:
+        """Persist the cache to disk (no-op when caching is disabled)."""
+        if self._cache is not None:
+            self._cache.save()

semantic_code_intelligence/llm/conversation.py

@@ -0,0 +1,190 @@
+"""Conversation memory — persistent multi-turn chat sessions.
+
+Provides:
+- **ConversationSession**: an ordered list of LLMMessage turns with metadata,
+  serialisable to / from disk.
+- **SessionStore**: manages multiple named sessions under ``.codexa/sessions/``
+  with create, resume, list, and delete operations.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from semantic_code_intelligence.llm.provider import LLMMessage, MessageRole
+from semantic_code_intelligence.utils.logging import get_logger
+
+logger = get_logger("llm.conversation")
+
+
+# ---------------------------------------------------------------------------
+# Conversation session
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ConversationSession:
+    """A multi-turn conversation with an LLM."""
+
+    session_id: str = field(default_factory=lambda: uuid.uuid4().hex[:12])
+    title: str = ""
+    messages: list[LLMMessage] = field(default_factory=list)
+    created_at: float = field(default_factory=time.time)
+    updated_at: float = field(default_factory=time.time)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    # --- turn management ---
+
+    def add_message(self, role: MessageRole, content: str) -> LLMMessage:
+        """Append a message to the conversation."""
+        msg = LLMMessage(role=role, content=content)
+        self.messages.append(msg)
+        self.updated_at = time.time()
+        return msg
+
+    def add_user(self, content: str) -> LLMMessage:
+        """Append a user message to the session."""
+        return self.add_message(MessageRole.USER, content)
+
+    def add_assistant(self, content: str) -> LLMMessage:
+        """Append an assistant message to the session."""
+        return self.add_message(MessageRole.ASSISTANT, content)
+
+    def add_system(self, content: str) -> LLMMessage:
+        """Append a system message to the session."""
+        return self.add_message(MessageRole.SYSTEM, content)
+
+    @property
+    def turn_count(self) -> int:
+        """Number of user+assistant exchanges."""
+        return sum(1 for m in self.messages if m.role in (MessageRole.USER, MessageRole.ASSISTANT))
+
+    @property
+    def last_message(self) -> LLMMessage | None:
+        """Return the most recent message, or None if empty."""
+        return self.messages[-1] if self.messages else None
+
+    def get_messages_for_llm(self, max_turns: int | None = None) -> list[LLMMessage]:
+        """Return messages formatted for LLM consumption.
+
+        Always includes system messages.  When *max_turns* is specified, keeps
+        the most recent user/assistant pairs to stay within context budget.
+        """
+        system_msgs = [m for m in self.messages if m.role == MessageRole.SYSTEM]
+        conversation = [m for m in self.messages if m.role != MessageRole.SYSTEM]
+
+        if max_turns is not None and len(conversation) > max_turns * 2:
+            conversation = conversation[-(max_turns * 2):]
+
+        return system_msgs + conversation
+
+    # --- serialisation ---
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize the conversation session to a plain dictionary."""
+        return {
+            "session_id": self.session_id,
+            "title": self.title,
+            "messages": [{"role": m.role.value, "content": m.content} for m in self.messages],
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+            "metadata": self.metadata,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ConversationSession:
+        """Reconstruct a conversation session from a dictionary."""
+        messages = [
+            LLMMessage(role=MessageRole(m["role"]), content=m["content"])
+            for m in data.get("messages", [])
+        ]
+        return cls(
+            session_id=data["session_id"],
+            title=data.get("title", ""),
+            messages=messages,
+            created_at=data.get("created_at", time.time()),
+            updated_at=data.get("updated_at", time.time()),
+            metadata=data.get("metadata", {}),
+        )
+
+
+# ---------------------------------------------------------------------------
+# Session store (persistent, file-backed)
+# ---------------------------------------------------------------------------
+
+SESSIONS_DIR = "sessions"
+
+
+class SessionStore:
+    """File-backed store for conversation sessions.
+
+    Sessions live under ``<project_root>/.codexa/sessions/<id>.json``.
+    """
+
+    def __init__(self, project_root: Path) -> None:
+        from semantic_code_intelligence.config.settings import AppConfig
+
+        self._dir = AppConfig.config_dir(project_root) / SESSIONS_DIR
+        self._dir.mkdir(parents=True, exist_ok=True)
+
+    def _session_path(self, session_id: str) -> Path:
+        # Sanitise session_id to prevent path traversal
+        safe_id = "".join(c for c in session_id if c.isalnum() or c in "-_")
+        return self._dir / f"{safe_id}.json"
+
+    def save(self, session: ConversationSession) -> Path:
+        """Persist a session to disk."""
+        path = self._session_path(session.session_id)
+        path.write_text(json.dumps(session.to_dict(), indent=2), encoding="utf-8")
+        logger.debug("Saved session %s (%d messages)", session.session_id, len(session.messages))
+        return path
+
+    def load(self, session_id: str) -> ConversationSession | None:
+        """Load a session by ID.  Returns *None* if not found."""
+        path = self._session_path(session_id)
+        if not path.exists():
+            return None
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+            return ConversationSession.from_dict(data)
+        except (json.JSONDecodeError, KeyError, TypeError):
+            logger.warning("Corrupt session file %s", path)
+            return None
+
+    def list_sessions(self) -> list[dict[str, Any]]:
+        """Return a summary of all stored sessions (newest first)."""
+        sessions: list[dict[str, Any]] = []
+        for p in self._dir.glob("*.json"):
+            try:
+                data = json.loads(p.read_text(encoding="utf-8"))
+                sessions.append({
+                    "session_id": data["session_id"],
+                    "title": data.get("title", ""),
+                    "turns": len(data.get("messages", [])),
+                    "created_at": data.get("created_at", 0),
+                    "updated_at": data.get("updated_at", 0),
+                })
+            except (json.JSONDecodeError, KeyError, TypeError):
+                continue
+        sessions.sort(key=lambda s: s["updated_at"], reverse=True)
+        return sessions
+
+    def delete(self, session_id: str) -> bool:
+        """Delete a session file.  Returns True if it existed."""
+        path = self._session_path(session_id)
+        if path.exists():
+            path.unlink()
+            return True
+        return False
+
+    def get_or_create(self, session_id: str | None = None) -> ConversationSession:
+        """Load an existing session or create a new one."""
+        if session_id:
+            existing = self.load(session_id)
+            if existing:
+                return existing
+        return ConversationSession()