argo-search 1.0.1

package/scripts/adaptive.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+"""
+adaptive.py — Unified Search v2 自适应学习引擎
+
+增强（v2）：
+  - success × latency × cost 三维评分
+  - 7天滑动窗口
+  - SQLite 持久化（跨进程复用）
+  - 预算模式感知（高 cost 引擎在 budget 模式下降权）
+
+评分公式：
+  score = success_rate × latency_factor × cost_factor
+  latency_factor = min(1.0, 2000 / avg_latency_ms)  # 2s 内满分
+  cost_factor = free=1.0, low=0.85, paid=0.6
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sqlite3
+import threading
+import time
+from pathlib import Path
+from typing import Optional
+
+# ── 路径 ──────────────────────────────────────────────────────────────────────
+
+DB_DIR = Path.home() / ".cache" / "unified-search"
+DB_PATH = DB_DIR / "adaptive.db"
+WINDOW_DAYS = 7
+
+# ── 成本分级因子 ─────────────────────────────────────────────────────────────
+
+COST_FACTORS = {"free": 1.0, "low": 0.85, "paid": 0.6}
+
+
+class AdaptiveLearner:
+    """自适应学习引擎：追踪引擎表现并输出推荐分数。"""
+
+    def __init__(self):
+        self._lock = threading.Lock()
+        DB_DIR.mkdir(parents=True, exist_ok=True)
+        self._init_db()
+
+    def _connect(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(str(DB_PATH), timeout=10)
+        conn.execute("PRAGMA journal_mode=WAL")
+        return conn
+
+    def _init_db(self):
+        with self._connect() as conn:
+            conn.execute("""
+                CREATE TABLE IF NOT EXISTS engine_perf (
+                    engine TEXT NOT NULL,
+                    success INTEGER NOT NULL,
+                    latency_ms REAL NOT NULL,
+                    cost REAL NOT NULL DEFAULT 0.0,
+                    created_at REAL NOT NULL
+                )
+            """)
+            # 检查列是否存在（迁移）
+            cols = [r[1] for r in conn.execute("PRAGMA table_info(engine_perf)")]
+            if "created_at" not in cols:
+                conn.execute("ALTER TABLE engine_perf ADD COLUMN created_at REAL DEFAULT 0")
+            if "cost" not in cols:
+                conn.execute("ALTER TABLE engine_perf ADD COLUMN cost REAL DEFAULT 0.0")
+            # 检查索引
+            conn.execute("CREATE INDEX IF NOT EXISTS idx_perf_engine_time ON engine_perf(engine, created_at)")
+            # 清理过期数据
+            cutoff = time.time() - WINDOW_DAYS * 86400
+            conn.execute("DELETE FROM engine_perf WHERE created_at < ?", (cutoff,))
+
+    def record(self, engine: str, success: bool, latency_ms: float, cost: float = 0.0):
+        """记录一次引擎调用结果。"""
+        with self._lock:
+            with self._connect() as conn:
+                conn.execute(
+                    "INSERT INTO engine_perf (engine, success, latency_ms, cost, created_at) VALUES (?, ?, ?, ?, ?)",
+                    (engine, 1 if success else 0, latency_ms, cost, time.time()),
+                )
+                conn.commit()
+
+    def get_score(self, engine: str) -> float:
+        """获取引擎的综合推荐分数（0.0 ~ 1.0）。"""
+        with self._lock:
+            cutoff = time.time() - WINDOW_DAYS * 86400
+            with self._connect() as conn:
+                row = conn.execute(
+                    "SELECT COUNT(*), AVG(success), AVG(latency_ms), AVG(cost) FROM engine_perf WHERE engine = ? AND created_at > ?",
+                    (engine, cutoff),
+                ).fetchone()
+        total, avg_success, avg_latency, avg_cost = row
+        if not total or total == 0:
+            return 0.5  # 无数据时中性分
+
+        success_rate = avg_success or 0.5
+        latency_factor = min(1.0, 2000.0 / max(avg_latency or 2000, 1))
+        # 成本因子：平均成本越低越好
+        cost_factor = max(0.3, 1.0 - (avg_cost or 0.0) * 10)
+
+        return round(success_rate * latency_factor * cost_factor, 4)
+
+    def get_ranking(self) -> list[tuple[str, float]]:
+        """获取所有引擎的推荐排名（降序）。"""
+        with self._lock:
+            cutoff = time.time() - WINDOW_DAYS * 86400
+            with self._connect() as conn:
+                rows = conn.execute(
+                    "SELECT engine, COUNT(*), AVG(success), AVG(latency_ms), AVG(cost) "
+                    "FROM engine_perf WHERE created_at > ? GROUP BY engine",
+                    (cutoff,),
+                ).fetchall()
+
+        results = []
+        for engine, total, avg_success, avg_latency, avg_cost in rows:
+            if not total:
+                continue
+            success_rate = avg_success or 0.5
+            latency_factor = min(1.0, 2000.0 / max(avg_latency or 2000, 1))
+            cost_factor = max(0.3, 1.0 - (avg_cost or 0.0) * 10)
+            score = round(success_rate * latency_factor * cost_factor, 4)
+            results.append((engine, score))
+
+        results.sort(key=lambda x: -x[1])
+        return results
+
+    def get_stats(self) -> dict:
+        """获取所有引擎的统计信息。"""
+        ranking = self.get_ranking()
+        cutoff = time.time() - WINDOW_DAYS * 86400
+        with self._connect() as conn:
+            rows = conn.execute(
+                "SELECT engine, COUNT(*), AVG(success), AVG(latency_ms), AVG(cost) "
+                "FROM engine_perf WHERE created_at > ? GROUP BY engine",
+                (cutoff,),
+            ).fetchall()
+
+        stats = {}
+        for engine, total, avg_success, avg_latency, avg_cost in rows:
+            stats[engine] = {
+                "calls": total,
+                "success_rate": round(avg_success or 0, 3),
+                "avg_latency_ms": round(avg_latency or 0, 1),
+                "avg_cost": round(avg_cost or 0, 6),
+                "score": self.get_score(engine),
+            }
+        return stats
+
+    def should_use(self, engine: str, threshold: float = 0.3) -> bool:
+        """判断引擎是否值得使用（分数高于阈值）。"""
+        return self.get_score(engine) >= threshold
+
+
+# ── 模块级单例 ─────────────────────────────────────────────────────────────────
+
+_learner: Optional[AdaptiveLearner] = None
+
+
+def get_learner() -> AdaptiveLearner:
+    global _learner
+    if _learner is None:
+        _learner = AdaptiveLearner()
+    return _learner
+
+
+# ── CLI ────────────────────────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    import sys
+    learner = get_learner()
+    if len(sys.argv) > 1 and sys.argv[1] == "stats":
+        print(json.dumps(learner.get_stats(), ensure_ascii=False, indent=2))
+    elif len(sys.argv) > 1 and sys.argv[1] == "rank":
+        ranking = learner.get_ranking()
+        for engine, score in ranking:
+            print(f"{engine:<15} {score:.4f}")
+    else:
+        print("用法: python3 adaptive.py stats|rank")

package/scripts/benchmark.py

@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+"""
+benchmark.py — 性能测试
+
+对比 v2.0 各关键路径延迟：
+  - TF-IDF 路由
+  - 双层缓存（L1 / L2）
+  - 引擎执行
+  - RRF 融合
+"""
+from __future__ import annotations
+
+import json
+import sys
+import time
+import os
+
+SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, SCRIPT_DIR)
+
+from tfidf_router import get_router, semantic_route
+from cache import SearchCache
+from route import route_query
+
+
+def bench_tfidf(n: int = 100) -> dict:
+    """测试 TF-IDF 路由延迟。"""
+    router = get_router()
+    queries = ["英伟达财报", "Python异步编程", "基金推荐", "latest AI research",
+               "北京旅游攻略", "股票行情", "transformer paper", "美联储加息"]
+    t0 = time.perf_counter()
+    for _ in range(n):
+        for q in queries:
+            router.route(q, top_k=3)
+    elapsed = (time.perf_counter() - t0) * 1000
+    total = n * len(queries)
+    return {
+        "total_calls": total,
+        "total_ms": round(elapsed, 2),
+        "avg_ms": round(elapsed / total, 4),
+        "qps": round(total / (elapsed / 1000), 0),
+    }
+
+
+def bench_cache(n: int = 100) -> dict:
+    """测试双层缓存读写延迟。"""
+    cache = SearchCache()
+    # 预热
+    for i in range(10):
+        cache.set(f"query_{i}", "anysearch", 5,
+                  {"results": [{"title": f"result_{i}", "url": f"http://x/{i}"}]},
+                  domain="tech")
+
+    # GET 测试
+    t0 = time.perf_counter()
+    hits = 0
+    for _ in range(n):
+        for i in range(10):
+            hit = cache.get(f"query_{i}", "anysearch", 5, domain="tech")
+            if hit:
+                hits += 1
+    elapsed = (time.perf_counter() - t0) * 1000
+    total = n * 10
+    return {
+        "total_calls": total,
+        "hits": hits,
+        "hit_rate": round(hits / total, 3),
+        "total_ms": round(elapsed, 2),
+        "avg_ms": round(elapsed / total, 4),
+    }
+
+
+def bench_route(n: int = 50) -> dict:
+    """测试端到端路由决策延迟。"""
+    queries = ["英伟达最新财报", "Python 异步编程最佳实践", "2026年AI芯片行业竞争格局",
+               "基金定投策略", "笔记本电脑推荐", "latest transformer paper"]
+    t0 = time.perf_counter()
+    for _ in range(n):
+        for q in queries:
+            route_query(q)
+    elapsed = (time.perf_counter() - t0) * 1000
+    total = n * len(queries)
+    return {
+        "total_calls": total,
+        "total_ms": round(elapsed, 2),
+        "avg_ms": round(elapsed / total, 4),
+    }
+
+
+def main():
+    print("=" * 60)
+    print("Unified Search v2.0 — 性能基准测试")
+    print("=" * 60)
+
+    print("\n[1] TF-IDF 语义路由")
+    r1 = bench_tfidf()
+    print(f"  调用次数: {r1['total_calls']}")
+    print(f"  总耗时:   {r1['total_ms']}ms")
+    print(f"  单次延迟: {r1['avg_ms']}ms")
+    print(f"  吞吐:     {r1['qps']} qps")
+
+    print("\n[2] 双层缓存（L1/L2 读取）")
+    r2 = bench_cache()
+    print(f"  调用次数: {r2['total_calls']}")
+    print(f"  命中次数: {r2['hits']}")
+    print(f"  命中率:   {r2['hit_rate']}")
+    print(f"  总耗时:   {r2['total_ms']}ms")
+    print(f"  单次延迟: {r2['avg_ms']}ms")
+
+    print("\n[3] 端到端路由决策")
+    r3 = bench_route()
+    print(f"  调用次数: {r3['total_calls']}")
+    print(f"  总耗时:   {r3['total_ms']}ms")
+    print(f"  单次延迟: {r3['avg_ms']}ms")
+
+    print("\n" + "=" * 60)
+    # 目标验证
+    print("目标验证:")
+    print(f"  TF-IDF < 5ms:    {'✓' if r1['avg_ms'] < 5 else '✗'} ({r1['avg_ms']}ms)")
+    print(f"  缓存命中 < 0.1ms: {'✓' if r2['avg_ms'] < 0.1 else '✗'} ({r2['avg_ms']}ms)")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/cache.py

@@ -0,0 +1,374 @@
+#!/usr/bin/env python3
+"""
+cache.py — Unified Search v2 双层缓存引擎
+
+功能：
+  L1: 内存 LRU 热缓存（100 条），避免同进程重复查询
+  L2: SQLite 持久化缓存（TTL 可配置），跨进程复用
+  分级 TTL：financial / news / realtime / general / research / evergreen
+  大值 gzip 压缩（> 1KB）
+"""
+
+from __future__ import annotations
+
+import gzip
+import hashlib
+import json
+import os
+import sqlite3
+import threading
+import time
+from collections import OrderedDict
+from typing import Optional
+
+try:
+    from config import get_cache_config
+except ImportError:
+    import sys
+    from pathlib import Path
+    sys.path.insert(0, str(Path(__file__).parent))
+    from config import get_cache_config
+
+
+# ── 常量 ──────────────────────────────────────────────────────────────────────
+
+DEFAULT_DB_PATH = "~/.cache/unified-search/cache.db"
+DEFAULT_TTL = 3600
+MAX_MEMORY_ITEMS = 100
+MAX_DB_SIZE_MB = 100
+COMPRESSION_THRESHOLD = 1024
+COMPRESSION_LEVEL = 6
+
+# 分级 TTL（秒）
+CACHE_TIERS = {
+    "financial": 300,    # 5 分钟
+    "news": 600,         # 10 分钟
+    "realtime": 900,     # 15 分钟
+    "general": 3600,     # 1 小时
+    "research": 7200,    # 2 小时
+    "evergreen": 86400,  # 24 小时
+}
+
+# query domain → TTL tier 映射
+DOMAIN_TIER_MAP = {
+    "stock_query": "financial",
+    "fund_query": "financial",
+    "financial_news": "news",
+    "zhihu_content": "general",
+    "tech_deep": "research",
+    "news_realtime": "realtime",
+    "general_search": "general",
+    "stock": "financial",
+    "fund": "financial",
+    "news": "realtime",
+    "tech": "research",
+    "general": "general",
+    "auto": "general",
+}
+
+
+# ── LRU 内存缓存 ───────────────────────────────────────────────────────────────
+
+class LRUCache:
+    """基于 OrderedDict 的简单 LRU。"""
+
+    def __init__(self, max_size: int = MAX_MEMORY_ITEMS):
+        self._max_size = max_size
+        self._store: OrderedDict[str, dict] = OrderedDict()
+        self._hits = 0
+        self._misses = 0
+        self._lock = threading.RLock()
+
+    def get(self, key: str) -> Optional[dict]:
+        with self._lock:
+            if key in self._store:
+                self._hits += 1
+                self._store.move_to_end(key)
+                return self._store[key]
+            self._misses += 1
+            return None
+
+    def set(self, key: str, value: dict):
+        with self._lock:
+            if key in self._store:
+                self._store.move_to_end(key)
+                self._store[key] = value
+            else:
+                if len(self._store) >= self._max_size:
+                    self._store.popitem(last=False)
+                self._store[key] = value
+
+    def clear(self):
+        with self._lock:
+            self._store.clear()
+            self._hits = 0
+            self._misses = 0
+
+    @property
+    def stats(self) -> dict:
+        with self._lock:
+            return {
+                "hits": self._hits,
+                "misses": self._misses,
+                "size": len(self._store),
+                "hit_rate": round(self._hits / max(self._hits + self._misses, 1), 3),
+            }
+
+
+# ── SQLite 持久化缓存 ──────────────────────────────────────────────────────────
+
+class SQLiteCache:
+    """SQLite 持久化缓存，支持 TTL 过期、大小限制、gzip 压缩。"""
+
+    SCHEMA_VERSION = 2
+
+    def __init__(self, db_path: str = DEFAULT_DB_PATH, ttl: int = DEFAULT_TTL):
+        self._db_path = os.path.expanduser(db_path)
+        self._ttl = ttl
+        self._lock = threading.RLock()
+        self._hits = 0
+        self._misses = 0
+        os.makedirs(os.path.dirname(self._db_path), exist_ok=True)
+        self._init_db()
+
+    def _connect(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(self._db_path, timeout=10)
+        conn.execute("PRAGMA journal_mode=WAL")
+        conn.execute("PRAGMA synchronous=NORMAL")
+        return conn
+
+    def _init_db(self):
+        with self._connect() as conn:
+            conn.executescript("""
+                CREATE TABLE IF NOT EXISTS search_cache (
+                    key TEXT PRIMARY KEY,
+                    query TEXT NOT NULL,
+                    engine TEXT NOT NULL,
+                    max_results INTEGER NOT NULL,
+                    domain TEXT DEFAULT 'general',
+                    value_blob BLOB NOT NULL,
+                    compressed INTEGER DEFAULT 0,
+                    ttl INTEGER DEFAULT 3600,
+                    created_at REAL NOT NULL,
+                    accessed_at REAL NOT NULL
+                );
+                CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);
+            """)
+            # 迁移：添加可能缺失的列
+            cols = [r[1] for r in conn.execute("PRAGMA table_info(search_cache)")]
+            if "domain" not in cols:
+                conn.execute("ALTER TABLE search_cache ADD COLUMN domain TEXT DEFAULT 'general'")
+            if "ttl" not in cols:
+                conn.execute("ALTER TABLE search_cache ADD COLUMN ttl INTEGER DEFAULT 3600")
+            conn.executescript("""
+                CREATE INDEX IF NOT EXISTS idx_search_cache_expires ON search_cache(created_at);
+                CREATE INDEX IF NOT EXISTS idx_search_cache_domain ON search_cache(domain);
+            """)
+            conn.execute("INSERT OR REPLACE INTO meta(key, value) VALUES (?, ?)",
+                         ("schema_version", str(self.SCHEMA_VERSION)))
+
+    def _is_expired(self, created_at: float, ttl: int | None = None) -> bool:
+        return (time.time() - created_at) > (ttl if ttl is not None else self._ttl)
+
+    @staticmethod
+    def _serialize(value: dict) -> tuple[bytes, int]:
+        raw = json.dumps(value, ensure_ascii=False).encode("utf-8")
+        if len(raw) > COMPRESSION_THRESHOLD:
+            return gzip.compress(raw, COMPRESSION_LEVEL), 1
+        return raw, 0
+
+    @staticmethod
+    def _deserialize(blob: bytes, compressed: int) -> dict:
+        raw = gzip.decompress(blob) if compressed else blob
+        return json.loads(raw.decode("utf-8"))
+
+    def get(self, key: str) -> Optional[dict]:
+        with self._lock:
+            with self._connect() as conn:
+                row = conn.execute(
+                    "SELECT value_blob, compressed, created_at, ttl FROM search_cache WHERE key = ?",
+                    (key,),
+                ).fetchone()
+                if row is None:
+                    self._misses += 1
+                    return None
+                value_blob, compressed, created_at, ttl = row
+                if self._is_expired(created_at, ttl):
+                    conn.execute("DELETE FROM search_cache WHERE key = ?", (key,))
+                    conn.commit()
+                    self._misses += 1
+                    return None
+                conn.execute("UPDATE search_cache SET accessed_at = ? WHERE key = ?",
+                             (time.time(), key))
+                conn.commit()
+                self._hits += 1
+                return self._deserialize(value_blob, compressed)
+
+    def set(self, key: str, query: str, engine: str, max_results: int,
+            value: dict, domain: str = "general", ttl: int | None = None):
+        with self._lock:
+            blob, compressed = self._serialize(value)
+            now = time.time()
+            effective_ttl = ttl if ttl is not None else self._ttl
+            with self._connect() as conn:
+                conn.execute(
+                    """INSERT OR REPLACE INTO search_cache
+                       (key, query, engine, max_results, domain, value_blob, compressed, ttl, created_at, accessed_at)
+                       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+                    (key, query, engine, max_results, domain, blob, compressed, effective_ttl, now, now),
+                )
+                conn.commit()
+            self._evict_if_needed()
+
+    def _evict_if_needed(self):
+        """超过 100MB 时删除最旧的记录"""
+        if self.size_mb <= MAX_DB_SIZE_MB:
+            return
+        with self._connect() as conn:
+            target_mb = MAX_DB_SIZE_MB * 0.8
+            while self.size_mb > target_mb:
+                row = conn.execute("SELECT key FROM search_cache ORDER BY accessed_at ASC LIMIT 1").fetchone()
+                if not row:
+                    break
+                conn.execute("DELETE FROM search_cache WHERE key = ?", (row[0],))
+                conn.commit()
+
+    def clear(self, older_than_hours: int = 24):
+        with self._lock:
+            cutoff = time.time() - older_than_hours * 3600
+            with self._connect() as conn:
+                conn.execute("DELETE FROM search_cache WHERE created_at < ?", (cutoff,))
+                conn.commit()
+
+    @property
+    def stats(self) -> dict:
+        with self._lock:
+            with self._connect() as conn:
+                row = conn.execute("SELECT COUNT(*), SUM(LENGTH(value_blob)) FROM search_cache").fetchone()
+            return {
+                "hits": self._hits,
+                "misses": self._misses,
+                "hit_rate": round(self._hits / max(self._hits + self._misses, 1), 3),
+                "size_mb": round((row[1] or 0) / 1024 / 1024, 2),
+                "entries": row[0] or 0,
+            }
+
+    @property
+    def size_mb(self) -> float:
+        with self._connect() as conn:
+            row = conn.execute("SELECT SUM(LENGTH(value_blob)) FROM search_cache").fetchone()
+        return (row[0] or 0) / 1024 / 1024
+
+
+# ── 双层缓存入口 ───────────────────────────────────────────────────────────────
+
+class SearchCache:
+    """
+    双层缓存引擎：L1 LRU + L2 SQLite
+    缓存键 = SHA256(query + "|" + engine + "|" + str(max_results))[:32]
+    """
+
+    def __init__(self, db_path: str = DEFAULT_DB_PATH, ttl: int = DEFAULT_TTL):
+        cfg = get_cache_config()
+        self._db_path = os.path.expanduser(cfg.get("db_path", db_path))
+        self._ttl = cfg.get("ttl", ttl)
+        self._l1 = LRUCache(max_size=MAX_MEMORY_ITEMS)
+        self._l2 = SQLiteCache(db_path=self._db_path, ttl=self._ttl)
+
+    @staticmethod
+    def _key(query: str, engine: str, max_results: int) -> str:
+        raw = f"{query}|{engine}|{max_results}"
+        return hashlib.sha256(raw.encode("utf-8")).hexdigest()[:32]
+
+    @staticmethod
+    def resolve_ttl(domain: str = "general") -> int:
+        """根据 domain 返回 TTL（秒）。"""
+        tier = DOMAIN_TIER_MAP.get(domain, "general")
+        return CACHE_TIERS.get(tier, DEFAULT_TTL)
+
+    def get(self, query: str, engine: str, max_results: int,
+            domain: str = "general") -> Optional[dict]:
+        """先查 L1，未命中再查 L2。"""
+        key = self._key(query, engine, max_results)
+        hit = self._l1.get(key)
+        if hit is not None:
+            ttl = hit.get("_ttl", self.resolve_ttl(domain))
+            if time.time() - hit.get("_ts", 0) < ttl:
+                hit["_cache_level"] = "L1"
+                return hit
+            self._l1._store.pop(key, None)
+
+        hit = self._l2.get(key)
+        if hit is not None:
+            self._l1.set(key, hit)
+            hit["_cache_level"] = "L2"
+            return hit
+        return None
+
+    def set(self, query: str, engine: str, max_results: int, results: dict,
+            domain: str = "general", ttl: int | None = None):
+        """写入双层缓存。"""
+        key = self._key(query, engine, max_results)
+        effective_ttl = ttl if ttl is not None else self.resolve_ttl(domain)
+        value = {**results, "_domain": domain, "_ttl": effective_ttl, "_ts": time.time()}
+        self._l1.set(key, value)
+        self._l2.set(key, query, engine, max_results, value, domain=domain, ttl=effective_ttl)
+
+    def clear(self, older_than_hours: int = 24):
+        self._l2.clear(older_than_hours=older_than_hours)
+
+    @property
+    def stats(self) -> dict:
+        l1 = self._l1.stats
+        l2 = self._l2.stats
+        total_hits = l1["hits"] + l2["hits"]
+        return {
+            "hits": total_hits,
+            "misses": l1["misses"],
+            "hit_rate": round(total_hits / max(total_hits + l1["misses"], 1), 3),
+            "size_mb": l2["size_mb"],
+            "entries": l2["entries"],
+            "l1": l1,
+            "l2": l2,
+        }
+
+
+# ── CLI 入口 ──────────────────────────────────────────────────────────────────
+
+def _cli():
+    import argparse
+    parser = argparse.ArgumentParser(description="Unified Search v2 缓存管理")
+    sub = parser.add_subparsers(dest="cmd")
+    p_get = sub.add_parser("get")
+    p_get.add_argument("query")
+    p_get.add_argument("engine", nargs="?", default="auto")
+    p_get.add_argument("max_results", nargs="?", type=int, default=5)
+    p_get.add_argument("--domain", default="general")
+    p_set = sub.add_parser("set")
+    p_set.add_argument("query")
+    p_set.add_argument("engine")
+    p_set.add_argument("max_results", type=int)
+    p_set.add_argument("value_json")
+    p_set.add_argument("--domain", default="general")
+    p_clear = sub.add_parser("clear")
+    p_clear.add_argument("--older-than", type=int, default=24)
+    sub.add_parser("stats")
+    args = parser.parse_args()
+    cache = SearchCache()
+    if args.cmd == "get":
+        hit = cache.get(args.query, args.engine, args.max_results, domain=args.domain)
+        print(json.dumps({"hit": hit is not None, "data": hit}, ensure_ascii=False))
+    elif args.cmd == "set":
+        cache.set(args.query, args.engine, args.max_results, json.loads(args.value_json), domain=args.domain)
+        print('{"ok": true}')
+    elif args.cmd == "clear":
+        cache.clear(older_than_hours=args.older_than)
+        print('{"ok": true}')
+    elif args.cmd == "stats":
+        print(json.dumps(cache.stats, ensure_ascii=False, indent=2))
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    _cli()