causaliq-knowledge 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

causaliq_knowledge/llm/cache.py

@@ -0,0 +1,380 @@
+"""
+LLM-specific cache encoder and data structures.
+
+This module provides the LLMEntryEncoder for caching LLM requests and
+responses with rich metadata for analysis.
+
+Note: This module stays in causaliq-knowledge (LLM-specific).
+The base cache infrastructure will migrate to causaliq-core.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from causaliq_knowledge.cache.encoders import JsonEncoder
+
+if TYPE_CHECKING:  # pragma: no cover
+    from causaliq_knowledge.cache.token_cache import TokenCache
+
+
+@dataclass
+class LLMTokenUsage:
+    """Token usage statistics for an LLM request.
+
+    Attributes:
+        input: Number of tokens in the prompt.
+        output: Number of tokens in the completion.
+        total: Total tokens (input + output).
+    """
+
+    input: int = 0
+    output: int = 0
+    total: int = 0
+
+
+@dataclass
+class LLMMetadata:
+    """Metadata for a cached LLM response.
+
+    Attributes:
+        provider: LLM provider name (openai, anthropic, etc.).
+        timestamp: When the original request was made (ISO format).
+        latency_ms: Response time in milliseconds.
+        tokens: Token usage statistics.
+        cost_usd: Estimated cost of the request in USD.
+        cache_hit: Whether this was served from cache.
+    """
+
+    provider: str = ""
+    timestamp: str = ""
+    latency_ms: int = 0
+    tokens: LLMTokenUsage = field(default_factory=LLMTokenUsage)
+    cost_usd: float = 0.0
+    cache_hit: bool = False
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialisation."""
+        return {
+            "provider": self.provider,
+            "timestamp": self.timestamp,
+            "latency_ms": self.latency_ms,
+            "tokens": asdict(self.tokens),
+            "cost_usd": self.cost_usd,
+            "cache_hit": self.cache_hit,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> LLMMetadata:
+        """Create from dictionary."""
+        tokens_data = data.get("tokens", {})
+        return cls(
+            provider=data.get("provider", ""),
+            timestamp=data.get("timestamp", ""),
+            latency_ms=data.get("latency_ms", 0),
+            tokens=LLMTokenUsage(
+                input=tokens_data.get("input", 0),
+                output=tokens_data.get("output", 0),
+                total=tokens_data.get("total", 0),
+            ),
+            cost_usd=data.get("cost_usd", 0.0),
+            cache_hit=data.get("cache_hit", False),
+        )
+
+
+@dataclass
+class LLMResponse:
+    """LLM response data for caching.
+
+    Attributes:
+        content: The full text response from the LLM.
+        finish_reason: Why generation stopped (stop, length, etc.).
+        model_version: Actual model version used.
+    """
+
+    content: str = ""
+    finish_reason: str = "stop"
+    model_version: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialisation."""
+        return {
+            "content": self.content,
+            "finish_reason": self.finish_reason,
+            "model_version": self.model_version,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> LLMResponse:
+        """Create from dictionary."""
+        return cls(
+            content=data.get("content", ""),
+            finish_reason=data.get("finish_reason", "stop"),
+            model_version=data.get("model_version", ""),
+        )
+
+
+@dataclass
+class LLMCacheEntry:
+    """Complete LLM cache entry with request, response, and metadata.
+
+    Attributes:
+        model: The model name requested.
+        messages: The conversation messages.
+        temperature: Sampling temperature.
+        max_tokens: Maximum tokens in response.
+        response: The LLM response data.
+        metadata: Rich metadata for analysis.
+    """
+
+    model: str = ""
+    messages: list[dict[str, Any]] = field(default_factory=list)
+    temperature: float = 0.0
+    max_tokens: int | None = None
+    response: LLMResponse = field(default_factory=LLMResponse)
+    metadata: LLMMetadata = field(default_factory=LLMMetadata)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialisation."""
+        return {
+            "cache_key": {
+                "model": self.model,
+                "messages": self.messages,
+                "temperature": self.temperature,
+                "max_tokens": self.max_tokens,
+            },
+            "response": self.response.to_dict(),
+            "metadata": self.metadata.to_dict(),
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> LLMCacheEntry:
+        """Create from dictionary."""
+        cache_key = data.get("cache_key", {})
+        return cls(
+            model=cache_key.get("model", ""),
+            messages=cache_key.get("messages", []),
+            temperature=cache_key.get("temperature", 0.0),
+            max_tokens=cache_key.get("max_tokens"),
+            response=LLMResponse.from_dict(data.get("response", {})),
+            metadata=LLMMetadata.from_dict(data.get("metadata", {})),
+        )
+
+    @classmethod
+    def create(
+        cls,
+        model: str,
+        messages: list[dict[str, Any]],
+        content: str,
+        *,
+        temperature: float = 0.0,
+        max_tokens: int | None = None,
+        finish_reason: str = "stop",
+        model_version: str = "",
+        provider: str = "",
+        latency_ms: int = 0,
+        input_tokens: int = 0,
+        output_tokens: int = 0,
+        cost_usd: float = 0.0,
+    ) -> LLMCacheEntry:
+        """Create a cache entry with common parameters.
+
+        Args:
+            model: The model name requested.
+            messages: The conversation messages.
+            content: The response content.
+            temperature: Sampling temperature.
+            max_tokens: Maximum tokens in response.
+            finish_reason: Why generation stopped.
+            model_version: Actual model version.
+            provider: LLM provider name.
+            latency_ms: Response time in milliseconds.
+            input_tokens: Number of input tokens.
+            output_tokens: Number of output tokens.
+            cost_usd: Estimated cost in USD.
+
+        Returns:
+            Configured LLMCacheEntry.
+        """
+        return cls(
+            model=model,
+            messages=messages,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            response=LLMResponse(
+                content=content,
+                finish_reason=finish_reason,
+                model_version=model_version or model,
+            ),
+            metadata=LLMMetadata(
+                provider=provider,
+                timestamp=datetime.now(timezone.utc).isoformat(),
+                latency_ms=latency_ms,
+                tokens=LLMTokenUsage(
+                    input=input_tokens,
+                    output=output_tokens,
+                    total=input_tokens + output_tokens,
+                ),
+                cost_usd=cost_usd,
+                cache_hit=False,
+            ),
+        )
+
+
+class LLMEntryEncoder(JsonEncoder):
+    """Encoder for LLM cache entries.
+
+    Extends JsonEncoder with LLM-specific convenience methods for
+    encoding/decoding LLMCacheEntry objects.
+
+    The encoder stores data in the standard JSON tokenised format,
+    achieving 50-70% compression through the shared token dictionary.
+
+    Example:
+        >>> from causaliq_knowledge.cache import TokenCache
+        >>> from causaliq_knowledge.llm.cache import (
+        ...     LLMEntryEncoder, LLMCacheEntry,
+        ... )
+        >>> with TokenCache(":memory:") as cache:
+        ...     encoder = LLMEntryEncoder()
+        ...     entry = LLMCacheEntry.create(
+        ...         model="gpt-4",
+        ...         messages=[{"role": "user", "content": "Hello"}],
+        ...         content="Hi there!",
+        ...         provider="openai",
+        ...     )
+        ...     blob = encoder.encode(entry.to_dict(), cache)
+        ...     data = encoder.decode(blob, cache)
+        ...     restored = LLMCacheEntry.from_dict(data)
+    """
+
+    def encode_entry(self, entry: LLMCacheEntry, cache: TokenCache) -> bytes:
+        """Encode an LLMCacheEntry to bytes.
+
+        Convenience method that handles to_dict conversion.
+
+        Args:
+            entry: The cache entry to encode.
+            cache: TokenCache for token dictionary.
+
+        Returns:
+            Encoded bytes.
+        """
+        return self.encode(entry.to_dict(), cache)
+
+    def decode_entry(self, blob: bytes, cache: TokenCache) -> LLMCacheEntry:
+        """Decode bytes to an LLMCacheEntry.
+
+        Convenience method that handles from_dict conversion.
+
+        Args:
+            blob: Encoded bytes.
+            cache: TokenCache for token dictionary.
+
+        Returns:
+            Decoded LLMCacheEntry.
+        """
+        data = self.decode(blob, cache)
+        return LLMCacheEntry.from_dict(data)
+
+    def generate_export_filename(
+        self, entry: LLMCacheEntry, cache_key: str
+    ) -> str:
+        """Generate a human-readable filename for export.
+
+        Creates a filename from model name and query details, with a
+        short hash suffix for uniqueness.
+
+        For edge queries, extracts node names for format:
+            {model}_{node_a}_{node_b}_edge_{hash}.json
+
+        For other queries, uses prompt excerpt:
+            {model}_{prompt_excerpt}_{hash}.json
+
+        Args:
+            entry: The cache entry to generate filename for.
+            cache_key: The cache key (hash) for uniqueness suffix.
+
+        Returns:
+            Human-readable filename with .json extension.
+
+        Example:
+            >>> encoder = LLMEntryEncoder()
+            >>> entry = LLMCacheEntry.create(
+            ...     model="gpt-4",
+            ...     messages=[{"role": "user", "content": "smoking and lung"}],
+            ...     content="Yes...",
+            ... )
+            >>> encoder.generate_export_filename(entry, "a1b2c3d4e5f6")
+            'gpt4_smoking_lung_edge_a1b2.json'
+        """
+        import re
+
+        # Sanitize model name (alphanumeric only, lowercase)
+        model = re.sub(r"[^a-z0-9]", "", entry.model.lower())
+        if len(model) > 15:
+            model = model[:15]
+
+        # Extract user message content
+        prompt = ""
+        for msg in entry.messages:
+            if msg.get("role") == "user":
+                prompt = msg.get("content", "")
+                break
+
+        # Try to extract node names for edge queries
+        # Look for patterns like "X and Y", "X cause Y", "between X and Y"
+        prompt_lower = prompt.lower()
+        slug = ""
+
+        # Pattern: "between X and Y" or "X and Y"
+        match = re.search(r"(?:between\s+)?(\w+)\s+and\s+(\w+)", prompt_lower)
+        if match:
+            node_a = match.group(1)[:15]
+            node_b = match.group(2)[:15]
+            slug = f"{node_a}_{node_b}_edge"
+
+        # Fallback: extract first significant words from prompt
+        if not slug:
+            # Remove common words, keep alphanumeric
+            cleaned = re.sub(r"[^a-z0-9\s]", "", prompt_lower)
+            words = [
+                w
+                for w in cleaned.split()
+                if w
+                not in ("the", "a", "an", "is", "are", "does", "do", "can")
+            ]
+            slug = "_".join(words[:4])
+            if len(slug) > 30:
+                slug = slug[:30].rstrip("_")
+
+        # Short hash suffix for uniqueness (4 chars)
+        hash_suffix = cache_key[:4] if cache_key else "0000"
+
+        # Build filename
+        parts = [p for p in [model, slug, hash_suffix] if p]
+        return "_".join(parts) + ".json"
+
+    def export_entry(self, entry: LLMCacheEntry, path: Path) -> None:
+        """Export an LLMCacheEntry to a JSON file.
+
+        Args:
+            entry: The cache entry to export.
+            path: Destination file path.
+        """
+        self.export(entry.to_dict(), path)
+
+    def import_entry(self, path: Path) -> LLMCacheEntry:
+        """Import an LLMCacheEntry from a JSON file.
+
+        Args:
+            path: Source file path.
+
+        Returns:
+            Imported LLMCacheEntry.
+        """
+        data = self.import_(path)
+        return LLMCacheEntry.from_dict(data)

{causaliq_knowledge-0.2.0.dist-info → causaliq_knowledge-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: causaliq-knowledge
-Version: 0.2.0
+Version: 0.3.0
 Summary: Incorporating LLM and human knowledge into causal discovery
 Author-email: CausalIQ <info@causaliq.com>
 Maintainer-email: CausalIQ <info@causaliq.com>
@@ -89,10 +89,10 @@ Currently implemented releases:
 
 - **Release v0.1.0 - Foundation LLM**: Simple LLM queries to 1 or 2 LLMs about edge existence and orientation to support graph averaging
 - **Release v0.2.0 - Additional LLMs**: Support for 7 LLM providers (Groq, Gemini, OpenAI, Anthropic, DeepSeek, Mistral, Ollama)
+- **Release v0.3.0 - LLM Caching** *(in development)*: SQLite-based response caching with CLI tools for cache management
 
 Planned:
 
-- **Release v0.3.0 - LLM Caching**: Caching of LLM queries and responses
 - **Release v0.4.0 - LLM Context**: Variable/role/literature etc context
 - **Release v0.5.0 - Algorithm integration**: Integration into structure learning algorithms
 - **Release v0.6.0 - Legacy Reference**: Support for legacy approaches of deriving knowledge from reference networks

{causaliq_knowledge-0.2.0.dist-info → causaliq_knowledge-0.3.0.dist-info}/RECORD

@@ -1,10 +1,16 @@
-causaliq_knowledge/__init__.py,sha256=IcoxZ6fjiN6VrniikCUZhHkxf2D1eGixtLWNrvKevN0,851
+causaliq_knowledge/__init__.py,sha256=3m-1i0_giGiTzvJj_8lDrMrvpDvnPD3IBOGlU3ZmxfM,843
 causaliq_knowledge/base.py,sha256=GBG-sftOKkmUoQzTpm6anDTjP-2nInRZN_36dxoYhvk,2917
-causaliq_knowledge/cli.py,sha256=2c8WYxF4T_-R8hDIo9JiZCx59fVbXHCCln66UGLqirs,13169
+causaliq_knowledge/cli.py,sha256=FjdlpQ62Mm4SjWGLAaXnPdv8hYh73-IUweLQAhrBw9k,25010
 causaliq_knowledge/models.py,sha256=tWGf186ASwO8NHiN97pEOLuBJmJI6Q9jvpU0mYZNdS0,4058
+causaliq_knowledge/cache/__init__.py,sha256=Av92YdCdVTRt9TmB2edRsIFDxq3f1Qi0daq0sFV1rp0,549
+causaliq_knowledge/cache/token_cache.py,sha256=dURih1jr0csVBxU1pCtmcjV48GnQeCnVGi3j1E0KY7Q,21845
+causaliq_knowledge/cache/encoders/__init__.py,sha256=gZ7gw96paFDbnJuc4v1aJsEJfVinI4zc03tXyFvfZxo,461
+causaliq_knowledge/cache/encoders/base.py,sha256=jK7--Or3lVp1UkKghKYFo_gKJp0HsMxosL_8eYL7RQQ,2679
+causaliq_knowledge/cache/encoders/json_encoder.py,sha256=44mcYpT6vJaJT9ZwtnWwdxCvTXIFyoeolqyiAXrgH1o,15110
 causaliq_knowledge/llm/__init__.py,sha256=30AL0h64zIkXoiqhMY7gjaf7mrtwtwMW38vzhns0My4,1663
 causaliq_knowledge/llm/anthropic_client.py,sha256=dPFHYGWL4xwQCtmQuGwGY4DBKSINOgOS-11ekznaiXo,8719
-causaliq_knowledge/llm/base_client.py,sha256=Dg5s9FqtTScliEK9MJ2_B0atTNwRRMNscv9gai6sEB4,7090
+causaliq_knowledge/llm/base_client.py,sha256=o2qWu2_ttKMHT4isdkY4VUjma3B3jtdx1vhOLXVFLX4,12249
+causaliq_knowledge/llm/cache.py,sha256=gBjZaYNJZ8HF54Hk25RWGVOvdBFwVPAv78_GYaanRTc,12723
 causaliq_knowledge/llm/deepseek_client.py,sha256=ZcOpgnYa66XHjiTaF5ekR_BtosRYvVmzlIafp_Gsx_A,3543
 causaliq_knowledge/llm/gemini_client.py,sha256=XJMq9sPo7zExrALSr2rIRHLheSPqKo8ENG0KtdJ1cjw,9924
 causaliq_knowledge/llm/groq_client.py,sha256=PnTXqtMF1Km9DY4HiCZXQ6LeOzdjZtQJaeuGe1GbeME,7531
@@ -14,9 +20,9 @@ causaliq_knowledge/llm/openai_client.py,sha256=MJmB6P32TZESMlXhn9d0-b3vFWXmf7ojH
 causaliq_knowledge/llm/openai_compat_client.py,sha256=L8ZW5csuhUePq4mt3EGOUqhR3tleFmM72UlhPBsgIMQ,9518
 causaliq_knowledge/llm/prompts.py,sha256=bJ9iVGKUfTfLi2eWh-FFM4cNzk5Ux4Z0x8R6Ia27Dbo,6598
 causaliq_knowledge/llm/provider.py,sha256=VDEv-1esT_EgJk_Gwlfl4423ojglOxzPCBCFbOFE4DQ,15184
-causaliq_knowledge-0.2.0.dist-info/licenses/LICENSE,sha256=vUFUzQnti-D-MLSi9NxFlsFYOKwU25sxxH7WgJOQFIs,1084
-causaliq_knowledge-0.2.0.dist-info/METADATA,sha256=NxnJJjL6hED91fu0DlclGSoeiji8litmEsy1sS_lt_0,8726
-causaliq_knowledge-0.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-causaliq_knowledge-0.2.0.dist-info/entry_points.txt,sha256=8iQjiMgFxZszRWwSTGHvoOBb_OBUkMmwvH3PzgsH-Cc,104
-causaliq_knowledge-0.2.0.dist-info/top_level.txt,sha256=GcxQf4BQAGa38i2-j8ylk2FmnBHtEZ9-8bSt-7Uka7k,19
-causaliq_knowledge-0.2.0.dist-info/RECORD,,
+causaliq_knowledge-0.3.0.dist-info/licenses/LICENSE,sha256=vUFUzQnti-D-MLSi9NxFlsFYOKwU25sxxH7WgJOQFIs,1084
+causaliq_knowledge-0.3.0.dist-info/METADATA,sha256=MIE-z6VqrnzuhHpU8j0DzxB48zwyDIobseO2SltVe-0,8774
+causaliq_knowledge-0.3.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+causaliq_knowledge-0.3.0.dist-info/entry_points.txt,sha256=8iQjiMgFxZszRWwSTGHvoOBb_OBUkMmwvH3PzgsH-Cc,104
+causaliq_knowledge-0.3.0.dist-info/top_level.txt,sha256=GcxQf4BQAGa38i2-j8ylk2FmnBHtEZ9-8bSt-7Uka7k,19
+causaliq_knowledge-0.3.0.dist-info/RECORD,,

{causaliq_knowledge-0.2.0.dist-info → causaliq_knowledge-0.3.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (80.10.2)
 Root-Is-Purelib: true
 Tag: py3-none-any