longcache 0.1.0__py3-none-any.whl

longcache/cli.py

@@ -0,0 +1,216 @@
+"""
+LongCache CLI — Command-line interface for cache management.
+
+Provides commands for viewing stats, clearing cache, inspecting
+entries, and exporting cache data.
+
+Usage:
+    longcache stats
+    longcache clear --namespace default
+    longcache clear --all
+    longcache inspect --query "refund"
+    longcache export --format json
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Optional
+
+import click
+
+from longcache.config import CacheConfig
+
+
+def _get_cache(config: Optional[CacheConfig] = None):
+    """Get a LongCache instance, lazily initialized."""
+    from longcache import LongCache
+
+    return LongCache(config or CacheConfig())
+
+
+@click.group()
+@click.version_option(version="0.1.0", prog_name="longcache")
+def main():
+    """
+    LongCache — Semantic similarity cache for LLM/RAG pipelines.
+
+    View stats, manage entries, and configure your cache from the command line.
+    """
+    pass
+
+
+@main.command()
+@click.option("--namespace", default=None, help="Namespace to show stats for.")
+@click.option("--db-path", default=".longcache/cache.db", help="Path to cache database.")
+def stats(namespace: Optional[str], db_path: str):
+    """
+    Show cache hit rate, estimated savings, and entry count.
+
+    Displays key metrics about your cache performance including
+    hit rate, estimated tokens saved, and estimated cost savings.
+
+    Examples:
+
+        longcache stats
+
+        longcache stats --namespace faq
+    """
+    config = CacheConfig(db_path=db_path, namespace=namespace or "default")
+    cache = _get_cache(config)
+
+    s = cache.stats()
+
+    click.echo("=" * 50)
+    click.echo("  LongCache Statistics")
+    click.echo("=" * 50)
+    click.echo(f"  Namespace:          {config.namespace}")
+    click.echo(f"  Cache Hits:         {s['hits']}")
+    click.echo(f"  Cache Misses:       {s['misses']}")
+    click.echo(f"  Hit Rate:           {s['hit_rate']:.1%}")
+    click.echo(f"  Total Entries:      {s['total_entries']}")
+    click.echo(f"  Est. Tokens Saved:  {s['estimated_tokens_saved']:,}")
+    click.echo(f"  Est. Cost Saved:    ${s['estimated_cost_saved_usd']:.4f}")
+    click.echo("=" * 50)
+
+
+@main.command()
+@click.option("--namespace", default=None, help="Namespace to clear.")
+@click.option("--all", "clear_all", is_flag=True, help="Clear ALL namespaces.")
+@click.option("--db-path", default=".longcache/cache.db", help="Path to cache database.")
+@click.confirmation_option(prompt="Are you sure you want to clear the cache?")
+def clear(namespace: Optional[str], clear_all: bool, db_path: str):
+    """
+    Clear cache entries by namespace or entirely.
+
+    Use --namespace to clear a specific namespace, or --all
+    to clear the entire cache across all namespaces.
+
+    Examples:
+
+        longcache clear --namespace faq
+
+        longcache clear --all
+    """
+    config = CacheConfig(db_path=db_path)
+    cache = _get_cache(config)
+
+    if clear_all:
+        count = cache.clear()
+        click.echo(f"Cleared entire cache: {count} entries deleted.")
+    elif namespace:
+        count = cache.invalidate(namespace)
+        click.echo(f"Cleared namespace '{namespace}': {count} entries deleted.")
+    else:
+        count = cache.invalidate()
+        click.echo(f"Cleared namespace '{config.namespace}': {count} entries deleted.")
+
+
+@main.command()
+@click.option("--query", required=True, help="Query text to search for similar cached entries.")
+@click.option("--namespace", default=None, help="Namespace to search in.")
+@click.option("--db-path", default=".longcache/cache.db", help="Path to cache database.")
+def inspect(query: str, namespace: Optional[str], db_path: str):
+    """
+    Inspect the nearest cached entry for a query.
+
+    Shows the most similar cached entry regardless of the
+    similarity threshold. Useful for debugging and understanding
+    what would be cached for a given query.
+
+    Examples:
+
+        longcache inspect --query "What is the refund policy?"
+
+        longcache inspect --query "refund" --namespace faq
+    """
+    config = CacheConfig(db_path=db_path, namespace=namespace or "default")
+    cache = _get_cache(config)
+
+    result = cache.inspect(query, namespace=namespace)
+
+    if result is None:
+        click.echo(f"No similar entries found for query: {query!r}")
+        return
+
+    click.echo("=" * 50)
+    click.echo("  Nearest Cached Entry")
+    click.echo("=" * 50)
+    click.echo(f"  ID:            {result['id']}")
+    click.echo(f"  Cached Query:  {result['query']!r}")
+    click.echo(f"  Namespace:     {result['namespace']}")
+    click.echo(f"  Hit Count:     {result['hit_count']}")
+    click.echo(f"  Created At:    {result['created_at']}")
+    click.echo(f"  Expires At:    {result['expires_at'] or 'Never'}")
+    click.echo(f"  Is Expired:    {result['is_expired']}")
+    click.echo("=" * 50)
+
+
+@main.command()
+@click.option(
+    "--format",
+    "export_format",
+    default="json",
+    type=click.Choice(["json"]),
+    help="Export format (currently only JSON supported).",
+)
+@click.option("--namespace", default=None, help="Only export entries from this namespace.")
+@click.option("--db-path", default=".longcache/cache.db", help="Path to cache database.")
+@click.option("--output", "-o", default=None, help="Output file path. Defaults to stdout.")
+def export(export_format: str, namespace: Optional[str], db_path: str, output: Optional[str]):
+    """
+    Export cache entries as JSON.
+
+    Dumps all cache entries (or entries from a specific namespace)
+    in JSON format. Useful for backup, migration, or analysis.
+
+    Examples:
+
+        longcache export --format json
+
+        longcache export --namespace faq -o faq_cache.json
+    """
+    config = CacheConfig(db_path=db_path, namespace=namespace or "default")
+    cache = _get_cache(config)
+
+    # Access the backend directly for export
+    from longcache.backends.sqlite import SQLiteCacheBackend
+
+    backend = cache.backend
+
+    if isinstance(backend, SQLiteCacheBackend):
+        entries = backend.export_all()
+    else:
+        # Generic fallback
+        ns = namespace or config.namespace
+        entries_raw = backend.list_entries(ns)
+        entries = [
+            {
+                "id": e.id,
+                "namespace": e.namespace,
+                "query": e.query,
+                "response": str(e.response),
+                "created_at": e.created_at,
+                "expires_at": e.expires_at,
+                "hit_count": e.hit_count,
+            }
+            for e in entries_raw
+        ]
+
+    # Filter by namespace if specified
+    if namespace:
+        entries = [e for e in entries if e.get("namespace") == namespace]
+
+    json_output = json.dumps(entries, indent=2, default=str)
+
+    if output:
+        with open(output, "w") as f:
+            f.write(json_output)
+        click.echo(f"Exported {len(entries)} entries to {output}")
+    else:
+        click.echo(json_output)
+
+
+if __name__ == "__main__":
+    main()

longcache/config.py

@@ -0,0 +1,127 @@
+"""
+Configuration for LongCache.
+
+Provides CacheConfig dataclass with sensible defaults,
+validation, and factory methods for construction from dicts or env vars.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field, asdict
+from typing import Optional
+
+
+@dataclass
+class CacheConfig:
+    """
+    Configuration for LongCache with sensible defaults.
+
+    Attributes:
+        similarity_threshold: Cosine similarity threshold for cache hits (0.0-1.0).
+            Higher = stricter matching. 0.92 is a good default for most RAG use cases.
+        ttl_seconds: Time-to-live for cache entries in seconds. 0 = no expiry.
+        max_entries: Maximum number of entries per namespace. Oldest entries
+            are evicted first when the limit is reached.
+        namespace: Default namespace for cache entries. Namespaces isolate
+            different applications or use cases sharing the same backend.
+        embedder_model: Sentence-transformers model name for local embedding.
+            Must be compatible with sentence-transformers library.
+        backend: Storage backend type. One of: "sqlite", "redis", "memory".
+        db_path: Path to the SQLite database file (only used when backend="sqlite").
+        redis_url: Redis connection URL (only used when backend="redis").
+        track_stats: Whether to track hit/miss statistics internally.
+    """
+
+    similarity_threshold: float = 0.92
+    ttl_seconds: int = 3600
+    max_entries: int = 10_000
+    namespace: str = "default"
+    embedder_model: str = "BAAI/bge-small-en-v1.5"
+    backend: str = "sqlite"
+    db_path: str = ".longcache/cache.db"
+    redis_url: str = "redis://localhost:6379/0"
+    track_stats: bool = True
+    faiss_index_type: str = "flat"
+    hnsw_m: int = 32
+    hnsw_ef_search: int = 64
+    model: str = ""
+    system_prompt: str = ""
+    temperature: float = -1.0
+
+    def __post_init__(self):
+        """Validate configuration values after initialization."""
+        if not 0.0 <= self.similarity_threshold <= 1.0:
+            raise ValueError(
+                f"similarity_threshold must be between 0.0 and 1.0, got {self.similarity_threshold}"
+            )
+        if self.ttl_seconds < 0:
+            raise ValueError(f"ttl_seconds must be >= 0, got {self.ttl_seconds}")
+        if self.max_entries < 1:
+            raise ValueError(f"max_entries must be >= 1, got {self.max_entries}")
+        if self.backend not in ("sqlite", "redis", "async_redis", "memory"):
+            raise ValueError(
+                f"backend must be one of 'sqlite', 'redis', 'async_redis', 'memory', "
+                f"got '{self.backend}'"
+            )
+
+    @classmethod
+    def from_dict(cls, data: dict) -> CacheConfig:
+        """
+        Create a CacheConfig from a dictionary.
+
+        Only keys that match CacheConfig fields are used; others are ignored.
+
+        Args:
+            data: Dictionary with configuration keys.
+
+        Returns:
+            CacheConfig instance with values from the dict.
+        """
+        valid_keys = {f.name for f in cls.__dataclass_fields__.values()}
+        filtered = {k: v for k, v in data.items() if k in valid_keys}
+        return cls(**filtered)
+
+    @classmethod
+    def from_env(cls, prefix: str = "LONGCACHE_") -> CacheConfig:
+        """
+        Create a CacheConfig from environment variables.
+
+        Environment variables are mapped by uppercasing the field name and
+        prepending the prefix. For example, similarity_threshold becomes
+        LONGCACHE_SIMILARITY_THRESHOLD.
+
+        Args:
+            prefix: Environment variable prefix. Defaults to "LONGCACHE_".
+
+        Returns:
+            CacheConfig instance with values from environment variables.
+        """
+        field_types = {f.name: f.type for f in cls.__dataclass_fields__.values()}
+        env_values = {}
+
+        for field_name in cls.__dataclass_fields__:
+            env_key = f"{prefix}{field_name.upper()}"
+            env_val = os.environ.get(env_key)
+            if env_val is not None:
+                # Cast to appropriate type
+                field_type = field_types[field_name]
+                if field_type == "float":
+                    env_values[field_name] = float(env_val)
+                elif field_type == "int":
+                    env_values[field_name] = int(env_val)
+                elif field_type == "bool":
+                    env_values[field_name] = env_val.lower() in ("true", "1", "yes")
+                else:
+                    env_values[field_name] = env_val
+
+        return cls(**env_values)
+
+    def to_dict(self) -> dict:
+        """
+        Convert the configuration to a dictionary.
+
+        Returns:
+            Dictionary representation of the configuration.
+        """
+        return asdict(self)

longcache/core/__init__.py

@@ -0,0 +1,8 @@
+"""Core LongCache engine components."""
+
+from longcache.core.cache import LongCache
+from longcache.core.entry import CacheEntry
+from longcache.core.embedder import LocalEmbedder
+from longcache.core.index import SimilarityIndex
+
+__all__ = ["LongCache", "CacheEntry", "LocalEmbedder", "SimilarityIndex"]

longcache/core/base_embedder.py

@@ -0,0 +1,43 @@
+"""Abstract base class for all embedder implementations."""
+
+from __future__ import annotations
+from abc import ABC, abstractmethod
+import numpy as np
+
+
+class BaseEmbedder(ABC):
+    """
+    Abstract interface for embedding models.
+
+    All embedders must produce L2-normalized float32 vectors
+    of consistent dimension. The dimension is used to initialize
+    the FAISS index and must not change between calls.
+    """
+
+    @property
+    @abstractmethod
+    def dimension(self) -> int:
+        """Return the dimensionality of the embedding vectors."""
+        ...
+
+    @abstractmethod
+    def embed(self, text: str) -> np.ndarray:
+        """
+        Embed a single text string.
+
+        Returns:
+            L2-normalized float32 numpy array of shape (dimension,).
+        """
+        ...
+
+    def embed_batch(self, texts: list[str]) -> np.ndarray:
+        """
+        Embed multiple texts. Default: loop over embed().
+        Override for batched efficiency.
+
+        Returns:
+            float32 array of shape (len(texts), dimension).
+        """
+        import numpy as np
+
+        return np.stack([self.embed(t) for t in texts]).astype(np.float32)