screenforge 0.4.0__py3-none-any.whl

common/cache/cache_manager.py

@@ -0,0 +1,300 @@
+import os
+
+os.environ["HF_ENDPOINT"] = "https://hf-mirror.com"
+os.environ["HF_HUB_DISABLE_SYMLINKS_WARNING"] = "1"
+os.environ["TRANSFORMERS_VERBOSITY"] = "error"
+
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+import numpy as np
+from numpy.linalg import norm
+
+from common.logs import log
+from config.config import CACHE_EXACT_MATCH_THRESHOLD, CACHE_SIMILARITY_THRESHOLD
+
+from .cache_hash import compute_instruction_hash, compute_ui_hash
+from .cache_stats import CacheStats
+from .cache_storage import cleanup_expired_entries, load_cache, save_cache
+from .embedding_loader import EmbeddingModelLoader
+
+
+class CacheManager:
+    def __init__(
+        self,
+        cache_dir: str = ".cache",
+        enabled: bool = False,
+        ttl_days: int = 365,
+        max_size_mb: int = 100,
+    ):
+        self._cache_dir = cache_dir
+        self._enabled = enabled
+        self._ttl_seconds = ttl_days * 24 * 60 * 60
+        self._stats = CacheStats(cache_dir)
+        self._model_loader = EmbeddingModelLoader()
+
+    @property
+    def enabled(self) -> bool:
+        return self._enabled
+
+    @enabled.setter
+    def enabled(self, value: bool) -> None:
+        self._enabled = value
+
+    def _get_model(self):
+        return self._model_loader.load()
+
+    def _get_embedding(self, text: str) -> Optional[list]:
+        # Returns None when the ML stack (sentence_transformers) is unavailable,
+        # so callers can fall back to exact-key-only behavior instead of crashing.
+        model = self._get_model()
+        if model is None:
+            return None
+        return model.encode(text).tolist()
+
+    def _cosine_similarity(self, vec1: list, vec2: list) -> float:
+        v1, v2 = np.array(vec1), np.array(vec2)
+        norm1, norm2 = norm(v1), norm(v2)
+        if norm1 == 0 or norm2 == 0:
+            return 0.0
+        return float(np.dot(v1, v2) / (norm1 * norm2))
+
+    def _cosine_similarity_batch(
+        self, query_vec: list, candidate_vecs: List[list]
+    ) -> List[tuple]:
+        if not candidate_vecs:
+            return []
+        q = np.array(query_vec)
+        q_norm = norm(q)
+        if q_norm == 0:
+            return []
+
+        candidates = np.stack(candidate_vecs)
+        candidate_norms = norm(candidates, axis=1)
+        scores = np.zeros(len(candidate_vecs))
+
+        valid_indices = candidate_norms > 0
+        if np.any(valid_indices):
+            scores[valid_indices] = np.dot(candidates[valid_indices], q) / (
+                candidate_norms[valid_indices] * q_norm
+            )
+
+        return list(enumerate(scores.tolist()))
+
+    def _hybrid_search(
+        self,
+        instruction: str,
+        target_ui_hash: Optional[str],
+        cache_type: str,
+        platform: str,
+        threshold: float,
+        exact_key: str,
+    ) -> Optional[Dict]:
+        if not self._enabled:
+            return None
+
+        try:
+            cache_data = load_cache(self._cache_dir)
+            cache_data = cleanup_expired_entries(cache_data, self._ttl_seconds)
+            entries = cache_data.get("entries", {})
+            if not entries:
+                self._stats.increment_miss()
+                return None
+
+            if exact_key in entries:
+                matched_entry = entries[exact_key]
+                if matched_entry.get("platform") == platform:
+                    saved_time = matched_entry.get("metadata", {}).get("llm_latency", 0.0)
+                    log.info(f"[Exact Cache Hit] {cache_type} matched ({platform})")
+                    if saved_time > 0:
+                        log.info(f"[Cache] Saved {saved_time:.2f}s of LLM inference time")
+                    matched_entry["metadata"]["last_accessed"] = datetime.now(timezone.utc).isoformat()
+                    matched_entry["metadata"]["access_count"] = matched_entry["metadata"].get("access_count", 0) + 1
+                    save_cache(self._cache_dir, cache_data)
+                    self._stats.increment_hit()
+                    return matched_entry.get("decision")
+
+            current_vector = self._get_embedding(instruction)
+            if current_vector is None:
+                # ML stack unavailable: exact-key already missed above, and we
+                # can't do semantic similarity without embeddings. Treat as miss.
+                self._stats.increment_miss()
+                return None
+            candidate_entries = []
+            candidate_vectors = []
+            for key, entry in entries.items():
+                if entry.get("type") != cache_type:
+                    continue
+                if entry.get("platform") != platform:
+                    continue
+                if target_ui_hash and entry.get("ui_hash") != target_ui_hash:
+                    continue
+                past_vector = entry.get("instruction_vector")
+                if not past_vector:
+                    continue
+                candidate_entries.append(entry)
+                candidate_vectors.append(past_vector)
+            if not candidate_vectors:
+                log.debug("[Cache Miss] No candidate vectors to compare")
+                self._stats.increment_miss()
+                return None
+            scores = self._cosine_similarity_batch(current_vector, candidate_vectors)
+            if not scores:
+                log.debug("[Cache Miss] No similarity scores computed")
+                self._stats.increment_miss()
+                return None
+            best_idx, best_score = max(scores, key=lambda s: s[1])
+            if best_score >= threshold:
+                matched_entry = candidate_entries[best_idx]
+                past_inst = matched_entry.get("instruction")
+                saved_time = matched_entry.get("metadata", {}).get("llm_latency", 0.0)
+                log.info(f"[Semantic Cache Hit] {cache_type} matched, similarity: {best_score:.2%} ({platform})")
+                log.info(f"[Cache] Query: '{instruction}' | Matched: '{past_inst}'")
+                if saved_time > 0:
+                    log.info(f"[Cache] Saved {saved_time:.2f}s of LLM inference time")
+                matched_entry["metadata"]["last_accessed"] = datetime.now(timezone.utc).isoformat()
+                matched_entry["metadata"]["access_count"] = matched_entry["metadata"].get("access_count", 0) + 1
+                save_cache(self._cache_dir, cache_data)
+                self._stats.increment_hit()
+                return matched_entry.get("decision")
+            log.debug(f"[Cache Miss] Best similarity {best_score:.2%} below threshold {threshold:.2%}")
+            self._stats.increment_miss()
+            return None
+        except Exception as e:
+            log.error(f"[Cache Error] Retrieval failed: {e}")
+            return None
+
+    def _set_hybrid(
+        self,
+        instruction: str,
+        decision: Dict,
+        ui_hash: Optional[str],
+        cache_type: str,
+        platform: str,
+        exact_key: str,
+        llm_latency: float = 0.0,
+    ) -> bool:
+        if not self._enabled:
+            return False
+        try:
+            cache_data = load_cache(self._cache_dir)
+            entries = cache_data.setdefault("entries", {})
+            current_vector = self._get_embedding(instruction)
+            keys_to_delete = []
+            for k, v in entries.items():
+                if v.get("type") != cache_type:
+                    continue
+                if v.get("platform") != platform:
+                    continue
+                is_same_decision = v.get("decision") == decision
+                is_same_instruction = v.get("instruction") == instruction
+                if cache_type == "L1-Action":
+                    if is_same_instruction and is_same_decision and v.get("ui_hash") != ui_hash:
+                        keys_to_delete.append(k)
+                elif cache_type == "L2-SimpleQA":
+                    past_vector = v.get("instruction_vector")
+                    if current_vector is not None and past_vector and is_same_decision:
+                        sim = self._cosine_similarity(current_vector, past_vector)
+                        if sim > CACHE_EXACT_MATCH_THRESHOLD:
+                            v["metadata"]["last_accessed"] = datetime.now(timezone.utc).isoformat()
+                            v["metadata"]["access_count"] = v["metadata"].get("access_count", 0) + 1
+                            save_cache(self._cache_dir, cache_data)
+                            return True
+            for k in keys_to_delete:
+                del entries[k]
+            entry = {
+                "type": cache_type,
+                "platform": platform,
+                "instruction": instruction,
+                "instruction_vector": current_vector,
+                "decision": decision,
+                "metadata": {
+                    "created_at": datetime.now(timezone.utc).isoformat(),
+                    "last_accessed": datetime.now(timezone.utc).isoformat(),
+                    "access_count": 1,
+                    "ttl_seconds": self._ttl_seconds,
+                    "llm_latency": round(llm_latency, 2),
+                },
+            }
+            if ui_hash is not None:
+                entry["ui_hash"] = ui_hash
+            entries[exact_key] = entry
+            save_cache(self._cache_dir, cache_data)
+            return True
+        except Exception as e:
+            log.error(f"[Cache Error] Write failed: {e}")
+            return False
+
+    def get(self, instruction: str, ui_json: Dict[str, Any], platform: str) -> Optional[Dict[str, Any]]:
+        try:
+            ui_hash = compute_ui_hash(ui_json)
+            inst_hash = compute_instruction_hash(instruction)
+            exact_key = f"L1_{platform}_{inst_hash}_{ui_hash}"
+            return self._hybrid_search(
+                instruction, ui_hash, "L1-Action", platform, CACHE_SIMILARITY_THRESHOLD, exact_key
+            )
+        except Exception as e:
+            log.error(f"[Cache Error] get() failed: {e}")
+            return None
+
+    def set(
+        self,
+        instruction: str,
+        ui_json: Dict[str, Any],
+        decision: Dict[str, Any],
+        platform: str,
+        llm_latency: float = 0.0,
+    ) -> bool:
+        try:
+            ui_hash = compute_ui_hash(ui_json)
+            inst_hash = compute_instruction_hash(instruction)
+            exact_key = f"L1_{platform}_{inst_hash}_{ui_hash}"
+            return self._set_hybrid(
+                instruction, decision, ui_hash, "L1-Action", platform, exact_key, llm_latency
+            )
+        except Exception as e:
+            log.error(f"[Cache Error] set() failed: {e}")
+            return False
+
+    def get_chat_simple(self, instruction: str, platform: str) -> Optional[Dict[str, Any]]:
+        try:
+            inst_hash = compute_instruction_hash(instruction)
+            exact_key = f"L2_{platform}_{inst_hash}"
+            return self._hybrid_search(
+                instruction, None, "L2-SimpleQA", platform, 0.88, exact_key
+            )
+        except Exception as e:
+            log.error(f"[Cache Error] get_chat_simple() failed: {e}")
+            return None
+
+    def set_chat_simple(
+        self,
+        instruction: str,
+        decision: Dict[str, Any],
+        platform: str,
+        llm_latency: float = 0.0,
+    ) -> bool:
+        try:
+            inst_hash = compute_instruction_hash(instruction)
+            exact_key = f"L2_{platform}_{inst_hash}"
+            return self._set_hybrid(
+                instruction, decision, None, "L2-SimpleQA", platform, exact_key, llm_latency
+            )
+        except Exception as e:
+            log.error(f"[Cache Error] set_chat_simple() failed: {e}")
+            return False
+
+    def clear(self) -> bool:
+        try:
+            save_cache(self._cache_dir, {"version": "1.2", "entries": {}})
+            return True
+        except Exception as e:
+            log.error(f"[Cache Error] clear() failed: {e}")
+            return False
+
+    def get_stats(self) -> Dict[str, Any]:
+        try:
+            return self._stats.to_dict()
+        except Exception as e:
+            log.error(f"[Cache Error] get_stats() failed: {e}")
+            return {}

common/cache/cache_stats.py

@@ -0,0 +1,133 @@
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from filelock import FileLock
+
+
+class CacheStats:
+    def __init__(self, cache_dir: str = ".cache"):
+        self._cache_dir = cache_dir
+        self._total_queries = 0
+        self._cache_hits = 0
+        self._cache_misses = 0
+        self._total_api_calls_saved = 0
+        self._first_cache_date = None
+        self._last_cache_date = None
+        self._load_stats()
+
+    @property
+    def total_queries(self) -> int:
+        return self._total_queries
+
+    @property
+    def cache_hits(self) -> int:
+        return self._cache_hits
+
+    @property
+    def cache_misses(self) -> int:
+        return self._cache_misses
+
+    @property
+    def hit_rate(self) -> float:
+        if self._total_queries == 0:
+            return 0.0
+        return self._cache_hits / self._total_queries
+
+    @property
+    def total_api_calls_saved(self) -> int:
+        return self._total_api_calls_saved
+
+    @property
+    def first_cache_date(self) -> Optional[str]:
+        return self._first_cache_date
+
+    @property
+    def last_cache_date(self) -> Optional[str]:
+        return self._last_cache_date
+
+    def increment_query(self) -> None:
+        self._total_queries += 1
+        self._update_last_cache_date()
+        self._save_stats()
+
+    def increment_hit(self) -> None:
+        self._total_queries += 1
+        self._cache_hits += 1
+        self._total_api_calls_saved += 1
+        self._update_last_cache_date()
+        self._save_stats()
+
+    def increment_miss(self) -> None:
+        self._total_queries += 1
+        self._cache_misses += 1
+        self._update_last_cache_date()
+        self._save_stats()
+
+    def _update_first_cache_date(self) -> None:
+        if not self._first_cache_date:
+            self._first_cache_date = datetime.now(timezone.utc).isoformat()
+
+    def _update_last_cache_date(self) -> None:
+        self._last_cache_date = datetime.now(timezone.utc).isoformat()
+        self._update_first_cache_date()
+
+    def _load_stats(self) -> None:
+        stats_path = Path(self._cache_dir) / "cache_stats.json"
+        os.makedirs(self._cache_dir, exist_ok=True)
+        lock = FileLock(f"{stats_path}.lock")
+
+        try:
+            with lock:
+                if not stats_path.exists():
+                    return
+                with open(stats_path, "r", encoding="utf-8") as f:
+                    data = json.load(f)
+            self._total_queries = data.get("total_queries", 0)
+            self._cache_hits = data.get("cache_hits", 0)
+            self._cache_misses = data.get("cache_misses", 0)
+            self._total_api_calls_saved = data.get("total_api_calls_saved", 0)
+            self._first_cache_date = data.get("first_cache_date")
+            self._last_cache_date = data.get("last_cache_date")
+        except (json.JSONDecodeError, IOError):
+            pass
+
+    def _save_stats(self) -> None:
+        stats_path = Path(self._cache_dir) / "cache_stats.json"
+        temp_path = stats_path.with_suffix(".tmp")
+        os.makedirs(self._cache_dir, exist_ok=True)
+        lock = FileLock(f"{stats_path}.lock")
+
+        data = {
+            "total_queries": self._total_queries,
+            "cache_hits": self._cache_hits,
+            "cache_misses": self._cache_misses,
+            "hit_rate": (self._cache_hits / self._total_queries) if self._total_queries > 0 else 0.0,
+            "total_api_calls_saved": self._total_api_calls_saved,
+            "first_cache_date": self._first_cache_date,
+            "last_cache_date": self._last_cache_date
+        }
+        try:
+            with lock:
+                with open(temp_path, "w", encoding="utf-8") as f:
+                    json.dump(data, f, ensure_ascii=False, indent=2)
+                    f.flush()
+                    os.fsync(f.fileno())
+                os.replace(temp_path, stats_path)
+        except IOError:
+            if temp_path.exists():
+                temp_path.unlink()
+            raise
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "total_queries": self._total_queries,
+            "cache_hits": self._cache_hits,
+            "cache_misses": self._cache_misses,
+            "hit_rate": (self._cache_hits / self._total_queries) if self._total_queries > 0 else 0.0,
+            "total_api_calls_saved": self._total_api_calls_saved,
+            "first_cache_date": self._first_cache_date,
+            "last_cache_date": self._last_cache_date
+        }

common/cache/cache_storage.py

@@ -0,0 +1,79 @@
+import json
+import os
+import time
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict
+
+from filelock import FileLock
+
+
+def get_cache_filename() -> str:
+    # 缓存的长久保留与过期剔除，交由底部的 cleanup_expired_entries 通过 TTL 控制
+    return "ai_decisions_v2.json"
+
+
+def _get_lock_path(cache_path: Path) -> str:
+    return f"{cache_path}.lock"
+
+
+def load_cache(cache_dir: str) -> Dict[str, Any]:
+    cache_path = Path(cache_dir) / get_cache_filename()
+    if not cache_path.exists():
+        return {"version": "1.1", "entries": {}}
+
+    lock = FileLock(_get_lock_path(cache_path))
+    try:
+        with lock:
+            with open(cache_path, "r", encoding="utf-8") as f:
+                data = json.load(f)
+        return data if "entries" in data else {"version": "1.1", "entries": {}}
+    except (json.JSONDecodeError, IOError):
+        return {"version": "1.1", "entries": {}}
+
+
+def save_cache(cache_dir: str, data: Dict[str, Any]) -> None:
+    cache_path = Path(cache_dir) / get_cache_filename()
+    temp_path = cache_path.with_suffix(".tmp")
+    os.makedirs(cache_dir, exist_ok=True)
+
+    lock = FileLock(_get_lock_path(cache_path))
+    try:
+        with lock:
+            with open(temp_path, "w", encoding="utf-8") as f:
+                json.dump(data, f, ensure_ascii=False, indent=2)
+                f.flush()
+                os.fsync(f.fileno())
+            os.replace(temp_path, cache_path)
+    except IOError:
+        if temp_path.exists():
+            temp_path.unlink()
+        raise
+
+
+def cleanup_expired_entries(
+    data: Dict[str, Any], default_ttl_seconds: float
+) -> Dict[str, Any]:
+    if "entries" not in data:
+        return data
+
+    now = time.time()
+    cleaned_entries = {}
+
+    for key, entry in data["entries"].items():
+        metadata = entry.get("metadata", {})
+        created_at = metadata.get("created_at")
+        if not created_at:
+            continue
+
+        try:
+            # 标准化 UTC 时间解析
+            created_time = datetime.fromisoformat(created_at.replace("Z", "+00:00"))
+            entry_ttl = metadata.get("ttl_seconds", default_ttl_seconds)
+
+            if now - created_time.timestamp() <= entry_ttl:
+                cleaned_entries[key] = entry
+        except ValueError:
+            continue
+
+    return {"version": data.get("version", "1.1"), "entries": cleaned_entries}

common/cache/embedding_loader.py

@@ -0,0 +1,150 @@
+from pathlib import Path
+from typing import Any, Optional
+
+from common.logs import log
+
+# NOTE: `sentence_transformers` (and its torch/transformers stack, ~2GB) is an
+# OPTIONAL dependency — installed via `pip install screenforge[ml]`, not the core
+# requirements. It is imported lazily inside load(), NOT at module scope, so that
+# importing common.cache / common.ai on a clean (core-only) install does not crash
+# with ModuleNotFoundError. The semantic (vector) cache degrades gracefully when
+# the package is absent; the exact-key (hash) cache keeps working.
+
+
+class EmbeddingModelLoader:
+    """负责句子向量模型的加载和缓存管理"""
+
+    def __init__(
+        self,
+        model_name: str = "paraphrase-multilingual-MiniLM-L12-v2",
+        hf_cache_dir: Optional[Path] = None,
+        disable_ssl_verify: bool = True,
+    ):
+        self.model_name = model_name
+        self.hf_cache_dir = hf_cache_dir or self._default_cache_dir(model_name)
+        self.disable_ssl_verify = disable_ssl_verify
+        self._model = None
+        self._original_requests_init = None
+        self._original_httpx_init = None
+
+    @staticmethod
+    def _default_cache_dir(model_name: str) -> Path:
+        """计算 HuggingFace 模型的默认缓存目录"""
+        return (
+            Path.home()
+            / ".cache"
+            / "huggingface"
+            / "hub"
+            / f"models--sentence-transformers--{model_name}"
+        )
+
+    def _configure_network(self):
+        """配置网络请求库（仅在模型加载期间生效，强制跳过 SSL）"""
+        if not self.disable_ssl_verify:
+            return
+
+        import requests
+        import urllib3
+
+        urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
+
+        # 保存对原函数的引用
+        self._original_requests_init = requests.Session.__init__
+        original_req_init = self._original_requests_init  # 通过局部变量闭包捕获
+
+        def safe_session_init(sess_self, *args, **kwargs):
+            # sess_self 是 requests.Session 实例
+            original_req_init(sess_self, *args, **kwargs)
+            sess_self.verify = False
+
+        requests.Session.__init__ = safe_session_init
+
+        try:
+            import httpx
+
+            # 保存对原函数的引用
+            self._original_httpx_init = httpx.Client.__init__
+            original_httpx_init = self._original_httpx_init  # 通过局部变量闭包捕获
+
+            def safe_httpx_init(client_self, *args, **kwargs):
+                # client_self 是 httpx.Client 实例
+                kwargs["verify"] = False
+                original_httpx_init(client_self, *args, **kwargs)
+
+            httpx.Client.__init__ = safe_httpx_init
+        except ImportError:
+            self._original_httpx_init = None
+
+    def _restore_network(self):
+        """恢复网络请求库的原始配置，不污染全局环境"""
+        if not self.disable_ssl_verify:
+            return
+
+        import requests
+
+        if self._original_requests_init:
+            requests.Session.__init__ = self._original_requests_init
+
+        if self._original_httpx_init is not None:
+            import httpx
+
+            httpx.Client.__init__ = self._original_httpx_init
+
+    def _cleanup_corrupted_cache(self) -> bool:
+        """清理损坏的模型缓存"""
+        if not self.hf_cache_dir.exists():
+            return False
+
+        import shutil
+
+        log.warning("[System] Corrupted model cache detected, cleaning up...")
+        shutil.rmtree(self.hf_cache_dir)
+        log.info("[System] Corrupted cache cleaned")
+        return True
+
+    def _should_cleanup_cache(self, error_msg: str) -> bool:
+        """判断是否需要清理缓存"""
+        error_indicators = ["Can't load the model", "pytorch_model.bin", "safetensors"]
+        return any(indicator in error_msg for indicator in error_indicators)
+
+    def load(self) -> Optional[Any]:
+        """加载模型（带缓存、代理兼容和错误处理机制）。
+
+        ML 依赖缺失时返回 None（优雅降级，不抛异常），调用方据此跳过向量检索。
+        """
+        if self._model is not None:
+            return self._model
+
+        try:
+            from sentence_transformers import SentenceTransformer
+        except ImportError:
+            log.warning(
+                "[System] Semantic cache disabled — 'sentence_transformers' not "
+                "installed. Install with: pip install screenforge[ml] (exact-key "
+                "cache still works without it)."
+            )
+            return None
+
+        log.info("[System] Initializing local semantic cache engine...")
+
+        if not self.hf_cache_dir.exists():
+            log.warning("[System] First run — downloading embedding model (~100MB)...")
+        else:
+            log.info("[System] Loading cached embedding model...")
+
+        self._configure_network()
+
+        try:
+            try:
+                self._model = SentenceTransformer(self.model_name)
+            except Exception as e:
+                if self._should_cleanup_cache(str(e)):
+                    self._cleanup_corrupted_cache()
+                    self._model = SentenceTransformer(self.model_name)
+                else:
+                    raise e
+
+            log.info("[System] Semantic cache model loaded and ready")
+            return self._model
+        finally:
+            self._restore_network()