xithead 1.1.0__py3-none-any.whl

xithead/__init__.py

@@ -0,0 +1,32 @@
+"""xithead - Claude Context Optimizer by Xtream-ITSolutions UG."""
+
+from xithead._version import __version__
+from xithead.claude_optimizer import ClaudeOptimizer, ClaudeOptimizerConfig, optimize_for_claude
+from xithead.cache import XitheadCache
+
+__all__ = [
+    "__version__",
+    "ClaudeOptimizer",
+    "ClaudeOptimizerConfig",
+    "optimize_for_claude",
+    "XitheadCache",
+]
+
+# Lazy import headroom symbols if available
+try:
+    from headroom import compress, HeadroomClient
+    __all__ += ["compress", "HeadroomClient"]
+except ImportError:
+    pass
+
+
+def start_proxy(host: str = "127.0.0.1", port: int = 8787, model: str = "claude-sonnet-4-6") -> None:
+    """Start the xithead optimization proxy. Convenience function."""
+    import os
+    os.environ.setdefault("XITHEAD_MODEL", model)
+    from xithead.proxy import create_app
+    import uvicorn
+    app = create_app()
+    print(f"[xithead] Proxy on http://{host}:{port} | Model: {model}")
+    print(f"[xithead] Dashboard: http://{host}:{port}/dashboard")
+    uvicorn.run(app, host=host, port=port)

xithead/_version.py

@@ -0,0 +1 @@
+__version__ = "1.1.0"

xithead/cache.py

@@ -0,0 +1,260 @@
+"""XitheadCache - Multi-layer caching for maximum Claude token savings."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import sqlite3
+import time
+from pathlib import Path
+from typing import Any
+
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS cache (
+    key         TEXT PRIMARY KEY,
+    value       TEXT NOT NULL,
+    created_at  REAL NOT NULL,
+    last_hit    REAL,
+    hits        INTEGER DEFAULT 0,
+    ttl         REAL NOT NULL DEFAULT 604800
+);
+CREATE INDEX IF NOT EXISTS idx_created ON cache(created_at);
+CREATE INDEX IF NOT EXISTS idx_last_hit ON cache(last_hit);
+
+CREATE TABLE IF NOT EXISTS stats (
+    id          INTEGER PRIMARY KEY CHECK (id = 1),
+    total_sets  INTEGER DEFAULT 0,
+    total_gets  INTEGER DEFAULT 0,
+    total_hits  INTEGER DEFAULT 0,
+    total_misses INTEGER DEFAULT 0,
+    tokens_saved INTEGER DEFAULT 0,
+    cost_saved_usd REAL DEFAULT 0.0
+);
+INSERT OR IGNORE INTO stats (id) VALUES (1);
+"""
+
+
+class XitheadCache:
+    """Multi-layer cache: memory → SQLite.
+
+    Layer 1: In-memory LRU (instant, survives within process)
+    Layer 2: SQLite (persistent across restarts, ~100µs per lookup)
+
+    Features:
+    - Per-entry TTL (frequently-hit entries get longer TTL automatically)
+    - Hit-rate tracking across restarts
+    - LRU eviction in memory layer
+    - Automatic DB vacuum when size exceeds limit
+    """
+
+    DEFAULT_TTL   = 86400 * 7   # 7 days baseline
+    HOT_TTL       = 86400 * 30  # 30 days for frequently-hit entries (≥5 hits)
+    WARM_TTL      = 86400 * 14  # 14 days for entries with ≥2 hits
+
+    def __init__(
+        self,
+        cache_dir: Path | None = None,
+        max_memory_entries: int = 2000,
+        ttl_seconds: int | None = None,
+        max_db_size_mb: int = 500,
+    ) -> None:
+        self._dir = cache_dir or (Path.home() / ".xithead" / "cache")
+        self._dir.mkdir(parents=True, exist_ok=True)
+        self._db_path = self._dir / "xithead_cache.db"
+        self._memory: dict[str, tuple[float, float, Any]] = {}  # key → (ts, expiry, value)
+        self._access_order: list[str] = []  # LRU tracking
+        self._max_memory = max_memory_entries
+        self._default_ttl = ttl_seconds or self.DEFAULT_TTL
+        self._max_db_mb = max_db_size_mb
+        self._init_db()
+        self._maybe_vacuum()
+
+    def _init_db(self) -> None:
+        with sqlite3.connect(self._db_path) as conn:
+            conn.executescript(_SCHEMA)
+            conn.commit()
+
+    def _maybe_vacuum(self) -> None:
+        """Clean up expired entries and vacuum if DB is too large."""
+        try:
+            with sqlite3.connect(self._db_path) as conn:
+                now = time.time()
+                # Delete expired entries
+                conn.execute("DELETE FROM cache WHERE created_at + ttl < ?", (now,))
+                conn.commit()
+                size_mb = self._db_path.stat().st_size / 1024 / 1024
+                if size_mb > self._max_db_mb:
+                    # Delete least recently hit entries until under limit
+                    conn.execute(
+                        "DELETE FROM cache WHERE key IN ("
+                        "  SELECT key FROM cache ORDER BY COALESCE(last_hit, created_at) ASC"
+                        "  LIMIT (SELECT COUNT(*)/4 FROM cache)"
+                        ")"
+                    )
+                    conn.execute("VACUUM")
+                    conn.commit()
+        except Exception:
+            pass
+
+    # ------------------------------------------------------------------
+    # Key generation
+    # ------------------------------------------------------------------
+
+    def key(self, *parts: Any) -> str:
+        payload = json.dumps(parts, sort_keys=True, default=str)
+        return hashlib.sha256(payload.encode()).hexdigest()
+
+    # ------------------------------------------------------------------
+    # Get / Set
+    # ------------------------------------------------------------------
+
+    def get(self, key: str) -> Any | None:
+        now = time.time()
+
+        # L1: memory
+        if key in self._memory:
+            ts, expiry, val = self._memory[key]
+            if now < expiry:
+                self._lru_touch(key)
+                return val
+            del self._memory[key]
+
+        # L2: SQLite
+        try:
+            with sqlite3.connect(self._db_path) as conn:
+                row = conn.execute(
+                    "SELECT value, created_at, ttl, hits FROM cache WHERE key = ?", (key,)
+                ).fetchone()
+                if row:
+                    value_str, created_at, ttl, hits = row
+                    if now - created_at < ttl:
+                        # Promote TTL for hot entries
+                        new_ttl = self._promote_ttl(hits + 1)
+                        conn.execute(
+                            "UPDATE cache SET hits = hits + 1, last_hit = ?, ttl = ? WHERE key = ?",
+                            (now, new_ttl, key),
+                        )
+                        conn.execute(
+                            "UPDATE stats SET total_gets = total_gets + 1, total_hits = total_hits + 1"
+                        )
+                        conn.commit()
+                        val = json.loads(value_str)
+                        self._lru_set(key, created_at, created_at + new_ttl, val)
+                        return val
+                    # Expired
+                    conn.execute("DELETE FROM cache WHERE key = ?", (key,))
+                    conn.execute("UPDATE stats SET total_misses = total_misses + 1")
+                    conn.commit()
+        except Exception:
+            pass
+
+        try:
+            with sqlite3.connect(self._db_path) as conn:
+                conn.execute("UPDATE stats SET total_gets = total_gets + 1, total_misses = total_misses + 1")
+                conn.commit()
+        except Exception:
+            pass
+        return None
+
+    def set(self, key: str, value: Any, ttl: int | None = None) -> None:
+        now = time.time()
+        effective_ttl = ttl or self._default_ttl
+        expiry = now + effective_ttl
+
+        # L1
+        self._lru_set(key, now, expiry, value)
+
+        # L2
+        try:
+            with sqlite3.connect(self._db_path) as conn:
+                conn.execute(
+                    "INSERT OR REPLACE INTO cache (key, value, created_at, ttl) VALUES (?, ?, ?, ?)",
+                    (key, json.dumps(value, default=str), now, effective_ttl),
+                )
+                conn.execute("UPDATE stats SET total_sets = total_sets + 1")
+                conn.commit()
+        except Exception:
+            pass
+
+    def record_savings(self, tokens_saved: int, cost_usd: float) -> None:
+        """Track cumulative savings across restarts."""
+        try:
+            with sqlite3.connect(self._db_path) as conn:
+                conn.execute(
+                    "UPDATE stats SET tokens_saved = tokens_saved + ?, cost_saved_usd = cost_saved_usd + ?",
+                    (tokens_saved, cost_usd),
+                )
+                conn.commit()
+        except Exception:
+            pass
+
+    # ------------------------------------------------------------------
+    # Stats
+    # ------------------------------------------------------------------
+
+    def stats(self) -> dict[str, Any]:
+        try:
+            with sqlite3.connect(self._db_path) as conn:
+                total = conn.execute("SELECT COUNT(*) FROM cache").fetchone()[0]
+                hot = conn.execute("SELECT COUNT(*) FROM cache WHERE hits >= 5").fetchone()[0]
+                st = conn.execute(
+                    "SELECT total_hits, total_misses, total_sets, tokens_saved, cost_saved_usd FROM stats WHERE id=1"
+                ).fetchone()
+                hits, misses, sets, tok_saved, cost_saved = st or (0, 0, 0, 0, 0.0)
+                size_bytes = self._db_path.stat().st_size if self._db_path.exists() else 0
+                total_lookups = (hits or 0) + (misses or 0)
+                return {
+                    "total_entries":  total,
+                    "hot_entries":    hot,       # ≥5 hits each
+                    "memory_entries": len(self._memory),
+                    "total_hits":     hits or 0,
+                    "total_misses":   misses or 0,
+                    "hit_rate":       round((hits or 0) / total_lookups, 4) if total_lookups else 0.0,
+                    "tokens_saved":   tok_saved or 0,
+                    "cost_saved_usd": round(cost_saved or 0.0, 4),
+                    "db_size_mb":     round(size_bytes / 1024 / 1024, 2),
+                }
+        except Exception:
+            return {}
+
+    def clear(self) -> None:
+        self._memory.clear()
+        self._access_order.clear()
+        try:
+            with sqlite3.connect(self._db_path) as conn:
+                conn.execute("DELETE FROM cache")
+                conn.execute("UPDATE stats SET total_hits=0, total_misses=0, total_sets=0")
+                conn.commit()
+        except Exception:
+            pass
+
+    # ------------------------------------------------------------------
+    # LRU helpers
+    # ------------------------------------------------------------------
+
+    def _lru_touch(self, key: str) -> None:
+        try:
+            self._access_order.remove(key)
+        except ValueError:
+            pass
+        self._access_order.append(key)
+
+    def _lru_set(self, key: str, ts: float, expiry: float, value: Any) -> None:
+        if key in self._memory:
+            self._lru_touch(key)
+        else:
+            if len(self._memory) >= self._max_memory:
+                # Evict least-recently-used
+                evict = self._access_order.pop(0)
+                self._memory.pop(evict, None)
+            self._access_order.append(key)
+        self._memory[key] = (ts, expiry, value)
+
+    @staticmethod
+    def _promote_ttl(hits: int) -> float:
+        if hits >= 5:
+            return XitheadCache.HOT_TTL
+        if hits >= 2:
+            return XitheadCache.WARM_TTL
+        return XitheadCache.DEFAULT_TTL