cct-cli 0.7.9.0__py3-none-any.whl

calc_terminal/vision/priority.py

@@ -0,0 +1,218 @@
+"""
+CAT v0.8.a — Frame Priority Engine (spec 9).
+
+Scores frames/events for AI analysis priority:
+
+  score = visual_change + interaction_event + annotation_event
+        + user_request + error_signal + AI_requested_frame
+
+Only high-value frames are sent to expensive multimodal reasoning.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+
+class PriorityLevel(str, Enum):
+    SKIP = "skip"
+    LOW = "low"
+    NORMAL = "normal"
+    HIGH = "high"
+    CRITICAL = "critical"
+
+
+@dataclass
+class PriorityScore:
+    total: float
+    level: PriorityLevel
+    breakdown: Dict[str, float]
+    should_send: bool
+    reasons: List[str]
+
+
+class FramePriorityEngine:
+    """
+    Event-driven priority scoring. Call score_event() for each signal;
+    call score_frame() to combine into a final decision for a candidate frame.
+    """
+
+    # Weights — tuned so obvious signals dominate redundant frame dribbles
+    WEIGHTS = {
+        "visual_change_none": 0,
+        "visual_change_minor": 5,
+        "visual_change_moderate": 15,
+        "visual_change_major": 30,
+        "visual_change_critical": 50,
+        "cursor_move": 2,
+        "cursor_dwell": 12,
+        "click": 18,
+        "annotation": 25,
+        "scroll": 4,
+        "user_chat": 35,
+        "user_analyze_request": 40,
+        "ai_requested_frame": 45,
+        "error_signal": 40,
+        "preview_change": 20,
+        "ui_state_change": 10,
+    }
+
+    # Thresholds for final level
+    THRESHOLDS = {
+        PriorityLevel.SKIP: 0,
+        PriorityLevel.LOW: 5,
+        PriorityLevel.NORMAL: 15,
+        PriorityLevel.HIGH: 30,
+        PriorityLevel.CRITICAL: 45,
+    }
+
+    def __init__(self, high_threshold: float = 30.0):
+        self.high_threshold = high_threshold
+        self._pending_signals: List[Dict[str, Any]] = []
+        self._last_send_time: float = 0.0
+        self._min_send_interval: float = 1.0  # seconds, adaptive
+        self._consecutive_skips: int = 0
+
+    def add_signal(self, kind: str, value: float = 1.0, detail: str = ""):
+        """Queue a signal; it will be consumed on next score_frame()."""
+        self._pending_signals.append({
+            "kind": kind,
+            "value": value,
+            "detail": detail,
+            "ts": time.time(),
+        })
+        # keep bounded
+        if len(self._pending_signals) > 100:
+            self._pending_signals = self._pending_signals[-50:]
+
+    # Convenience helpers
+    def signal_visual_change(self, level: str):
+        key = f"visual_change_{level}"
+        self.add_signal(key, detail=level)
+
+    def signal_cursor_move(self): self.add_signal("cursor_move")
+    def signal_cursor_dwell(self): self.add_signal("cursor_dwell")
+    def signal_click(self): self.add_signal("click")
+    def signal_annotation(self, tool: str = ""): self.add_signal("annotation", detail=tool)
+    def signal_scroll(self): self.add_signal("scroll")
+    def signal_user_chat(self): self.add_signal("user_chat")
+    def signal_user_analyze(self): self.add_signal("user_analyze_request")
+    def signal_ai_request(self): self.add_signal("ai_requested_frame")
+    def signal_error(self, msg: str = ""): self.add_signal("error_signal", detail=msg)
+    def signal_preview_change(self): self.add_signal("preview_change")
+    def signal_ui_state_change(self): self.add_signal("ui_state_change")
+
+    def score_frame(self,
+                    visual_change: str = "none",
+                    has_annotation: bool = False,
+                    has_cursor_event: bool = False,
+                    has_user_request: bool = False,
+                    has_error: bool = False,
+                    ai_requested: bool = False,
+                    force: bool = False) -> PriorityScore:
+        """
+        Score a candidate frame. Also drains pending signals.
+        Set force=True for explicit user Analyze actions (always send).
+        """
+        breakdown: Dict[str, float] = {}
+        reasons: List[str] = []
+        total = 0.0
+
+        # visual change component
+        vc_key = f"visual_change_{visual_change}"
+        vc_score = self.WEIGHTS.get(vc_key, 0)
+        if vc_score:
+            breakdown["visual_change"] = vc_score
+            reasons.append(f"visual:{visual_change} +{vc_score}")
+            total += vc_score
+
+        # pending signals
+        for sig in self._pending_signals:
+            w = self.WEIGHTS.get(sig["kind"], 0)
+            if w:
+                breakdown[sig["kind"]] = breakdown.get(sig["kind"], 0) + w
+                reasons.append(f"{sig['kind']} +{w}")
+                total += w
+        self._pending_signals.clear()
+
+        # explicit flags (additive if not already counted via signals)
+        if has_annotation and "annotation" not in breakdown:
+            w = self.WEIGHTS["annotation"]
+            breakdown["annotation"] = w
+            reasons.append(f"annotation +{w}")
+            total += w
+        if has_cursor_event and "cursor_move" not in breakdown and "cursor_dwell" not in breakdown:
+            w = self.WEIGHTS["cursor_move"]
+            breakdown["cursor_event"] = w
+            total += w
+        if has_user_request and "user_chat" not in breakdown:
+            w = self.WEIGHTS["user_chat"]
+            breakdown["user_request"] = w
+            reasons.append(f"user_request +{w}")
+            total += w
+        if has_error:
+            w = self.WEIGHTS["error_signal"]
+            breakdown["error_signal"] = breakdown.get("error_signal", 0) + w
+            reasons.append(f"error +{w}")
+            total += w
+        if ai_requested:
+            w = self.WEIGHTS["ai_requested_frame"]
+            breakdown["ai_requested"] = w
+            reasons.append(f"ai_requested +{w}")
+            total += w
+
+        # level
+        if force:
+            level = PriorityLevel.CRITICAL
+            should_send = True
+        elif total >= self.THRESHOLDS[PriorityLevel.CRITICAL]:
+            level = PriorityLevel.CRITICAL
+            should_send = True
+        elif total >= self.THRESHOLDS[PriorityLevel.HIGH]:
+            level = PriorityLevel.HIGH
+            should_send = True
+        elif total >= self.THRESHOLDS[PriorityLevel.NORMAL]:
+            level = PriorityLevel.NORMAL
+            # throttle normal frames
+            should_send = (time.time() - self._last_send_time) >= self._min_send_interval
+            if not should_send:
+                reasons.append("throttled (normal priority, interval)")
+        elif total >= self.THRESHOLDS[PriorityLevel.LOW]:
+            level = PriorityLevel.LOW
+            should_send = False
+            reasons.append("low priority — skipped")
+        else:
+            level = PriorityLevel.SKIP
+            should_send = False
+
+        if should_send:
+            self._last_send_time = time.time()
+            self._consecutive_skips = 0
+        else:
+            self._consecutive_skips += 1
+            # anti-starvation: force send after many skips if we have moderate visual change
+            if self._consecutive_skips >= 10 and visual_change in ("moderate", "major", "critical"):
+                should_send = True
+                level = PriorityLevel.NORMAL
+                reasons.append("anti-starvation override")
+                self._consecutive_skips = 0
+                self._last_send_time = time.time()
+
+        return PriorityScore(
+            total=round(total, 1),
+            level=level,
+            breakdown=breakdown,
+            should_send=should_send,
+            reasons=reasons,
+        )
+
+    def set_min_interval(self, seconds: float):
+        self._min_send_interval = max(0.2, seconds)
+
+    def reset(self):
+        self._pending_signals.clear()
+        self._last_send_time = 0.0
+        self._consecutive_skips = 0

calc_terminal/vision/provider.py

@@ -0,0 +1,180 @@
+"""
+CAT v0.8.a — Vision Provider Router.
+
+Capability-aware routing for vision requests.  Routes vision analysis
+to the best available provider based on capabilities, cost, and quality.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Tuple
+
+
+@dataclass
+class VisionCapability:
+    vision: bool = False
+    max_image_tokens: int = 0
+    supported_formats: tuple = ("png", "jpeg", "gif", "webp")
+    supports_video: bool = False
+    supports_audio: bool = False
+    supports_streaming: bool = False
+    cost_per_image_token: float = 0.0
+    quality_score: float = 0.0
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "vision": self.vision,
+            "max_image_tokens": self.max_image_tokens,
+            "supported_formats": list(self.supported_formats),
+            "supports_video": self.supports_video,
+            "supports_audio": self.supports_audio,
+            "supports_streaming": self.supports_streaming,
+            "cost_per_image_token": self.cost_per_image_token,
+            "quality_score": self.quality_score,
+        }
+
+
+PROVIDER_VISION_CAPS: Dict[str, VisionCapability] = {
+    "openai": VisionCapability(
+        vision=True, max_image_tokens=8192,
+        supported_formats=("png", "jpeg", "gif", "webp"),
+        cost_per_image_token=0.01, quality_score=0.95,
+    ),
+    "anthropic": VisionCapability(
+        vision=True, max_image_tokens=8192,
+        supported_formats=("png", "jpeg", "gif", "webp"),
+        cost_per_image_token=0.015, quality_score=0.93,
+    ),
+    "google": VisionCapability(
+        vision=True, max_image_tokens=16384,
+        supported_formats=("png", "jpeg", "gif", "webp"),
+        cost_per_image_token=0.008, quality_score=0.90,
+    ),
+    "ollama": VisionCapability(
+        vision=True, max_image_tokens=4096,
+        supported_formats=("png", "jpeg"),
+        cost_per_image_token=0.0, quality_score=0.70,
+    ),
+    "groq": VisionCapability(
+        vision=True, max_image_tokens=4096,
+        supported_formats=("png", "jpeg", "webp"),
+        cost_per_image_token=0.003, quality_score=0.80,
+    ),
+    "mistral": VisionCapability(
+        vision=True, max_image_tokens=8192,
+        supported_formats=("png", "jpeg", "gif", "webp"),
+        cost_per_image_token=0.01, quality_score=0.85,
+    ),
+    "deepseek": VisionCapability(
+        vision=True, max_image_tokens=8192,
+        supported_formats=("png", "jpeg", "gif", "webp"),
+        cost_per_image_token=0.005, quality_score=0.82,
+    ),
+    "together": VisionCapability(
+        vision=True, max_image_tokens=8192,
+        supported_formats=("png", "jpeg", "gif", "webp"),
+        cost_per_image_token=0.008, quality_score=0.85,
+    ),
+    "openrouter": VisionCapability(
+        vision=True, max_image_tokens=16384,
+        supported_formats=("png", "jpeg", "gif", "webp"),
+        cost_per_image_token=0.01, quality_score=0.88,
+    ),
+}
+
+
+class VisionProviderRouter:
+    """Routes vision requests to the best available provider."""
+
+    def __init__(self, config: Optional[Dict] = None):
+        self._config = config or {}
+        self._fallback_order = [
+            "openai", "anthropic", "google", "deepseek",
+            "groq", "mistral", "together", "openrouter", "ollama",
+        ]
+
+    def get_capabilities(self, provider: str) -> VisionCapability:
+        return PROVIDER_VISION_CAPS.get(provider, VisionCapability())
+
+    def find_vision_capable(self, config: Optional[Dict] = None) -> Optional[Tuple[Dict, VisionCapability]]:
+        cfg = config or self._config
+        provider = cfg.get("provider", "")
+        model = cfg.get("model", "")
+
+        caps = self.get_capabilities(provider)
+        if caps.vision:
+            return cfg, caps
+
+        for fallback_provider in self._fallback_order:
+            if fallback_provider == provider:
+                continue
+            fallback_caps = self.get_capabilities(fallback_provider)
+            if fallback_caps.vision:
+                fallback_config = dict(cfg)
+                fallback_config["provider"] = fallback_provider
+                return fallback_config, fallback_caps
+
+        return None
+
+    def select_best_provider(self, image_size: int = 0,
+                             need_video: bool = False,
+                             prefer_free: bool = False) -> Optional[Tuple[str, VisionCapability]]:
+        candidates = []
+        for provider, caps in PROVIDER_VISION_CAPS.items():
+            if not caps.vision:
+                continue
+            if need_video and not caps.supports_video:
+                continue
+            if prefer_free and caps.cost_per_image_token > 0:
+                continue
+            if image_size > 0 and image_size > caps.max_image_tokens * 100:
+                continue
+            candidates.append((provider, caps))
+
+        if prefer_free:
+            candidates = [(p, c) for p, c in candidates if c.cost_per_image_token == 0]
+
+        if not candidates:
+            return None
+
+        candidates.sort(key=lambda x: (
+            -x[1].quality_score,
+            x[1].cost_per_image_token,
+        ))
+        return candidates[0]
+
+    def route_vision_request(self, frame_b64: str,
+                             frame_size_bytes: int = 0,
+                             config: Optional[Dict] = None) -> Dict[str, Any]:
+        cfg = config or self._config
+        provider = cfg.get("provider", "")
+        caps = self.get_capabilities(provider)
+
+        result = {
+            "provider": provider,
+            "capabilities": caps.to_dict(),
+            "routed": caps.vision,
+            "fallback_used": False,
+        }
+
+        if not caps.vision:
+            route = self.find_vision_capable(cfg)
+            if route:
+                fallback_cfg, fallback_caps = route
+                result["provider"] = fallback_cfg.get("provider", "")
+                result["capabilities"] = fallback_caps.to_dict()
+                result["routed"] = True
+                result["fallback_used"] = True
+                result["original_provider"] = provider
+            else:
+                result["error"] = "No vision-capable provider available"
+
+        return result
+
+    def get_all_capabilities(self) -> Dict[str, Dict]:
+        return {
+            provider: caps.to_dict()
+            for provider, caps in PROVIDER_VISION_CAPS.items()
+        }

calc_terminal/vision/safety.py

@@ -0,0 +1,149 @@
+"""
+CAT v0.8.a — Privacy & Safety Controls.
+
+Configurable privacy filtering, blocked region detection,
+data retention limits, and safety safeguards.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Tuple
+
+
+@dataclass
+class SafetyConfig:
+    max_session_minutes: int = 60
+    max_frames_per_session: int = 500
+    max_total_frames_per_day: int = 5000
+    block_password_fields: bool = True
+    block_financial_data: bool = False
+    block_pii_detection: bool = True
+    blur_sensitive_regions: bool = True
+    auto_stop_on_error: bool = True
+    require_confirmation_for_persist: bool = True
+    log_all_access: bool = True
+    max_context_history: int = 20
+    data_retention_hours: int = 24
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "max_session_minutes": self.max_session_minutes,
+            "max_frames_per_session": self.max_frames_per_session,
+            "max_total_frames_per_day": self.max_total_frames_per_day,
+            "block_password_fields": self.block_password_fields,
+            "block_financial_data": self.block_financial_data,
+            "block_pii_detection": self.block_pii_detection,
+            "blur_sensitive_regions": self.blur_sensitive_regions,
+            "auto_stop_on_error": self.auto_stop_on_error,
+            "require_confirmation_for_persist": self.require_confirmation_for_persist,
+            "log_all_access": self.log_all_access,
+            "max_context_history": self.max_context_history,
+            "data_retention_hours": self.data_retention_hours,
+        }
+
+
+class PrivacyController:
+    """Enforces privacy rules on captured frames and context."""
+
+    SENSITIVE_KEYWORDS = [
+        "password", "passwd", "secret", "token", "api_key", "apikey",
+        "authorization", "credit_card", "ssn", "social_security",
+        "bank_account", "routing_number", "pin_code",
+    ]
+
+    def __init__(self, config: Optional[SafetyConfig] = None):
+        self.config = config or SafetyConfig()
+        self._access_log: List[Dict] = []
+        self._daily_frame_count = 0
+        self._day_start = self._today()
+
+    def _today(self) -> str:
+        return time.strftime("%Y-%m-%d")
+
+    def _reset_daily_if_needed(self):
+        today = self._today()
+        if today != self._day_start:
+            self._daily_frame_count = 0
+            self._day_start = today
+
+    def validate_config(self, config: Any) -> None:
+        if hasattr(config, "fps") and config.fps > 10:
+            raise ValueError("Frame rate exceeds safety limit (10 fps max)")
+        if hasattr(config, "max_frames") and config.max_frames > self.config.max_frames_per_session:
+            raise ValueError(
+                f"Max frames exceeds safety limit "
+                f"({self.config.max_frames_per_session})"
+            )
+
+    def is_blocked_region(self, frame_b64: str) -> bool:
+        if not self.config.block_pii_detection:
+            return False
+        if len(frame_b64) < 100:
+            return False
+        return False
+
+    def check_text_sensitivity(self, text: str) -> Dict[str, Any]:
+        text_lower = text.lower()
+        blocked = [
+            kw for kw in self.SENSITIVE_KEYWORDS
+            if kw in text_lower
+        ]
+        return {
+            "sensitive": bool(blocked),
+            "keywords_found": blocked,
+            "recommendation": "block" if blocked else "allow",
+        }
+
+    def filter_frame_metadata(self, meta: Dict[str, Any]) -> Dict[str, Any]:
+        filtered = dict(meta)
+        if self.config.block_password_fields:
+            if "active_element" in filtered:
+                el = filtered["active_element"].lower()
+                if any(kw in el for kw in ("password", "secret", "pin")):
+                    filtered["active_element"] = "[REDACTED]"
+        return filtered
+
+    def log_access(self, action: str, resource: str, details: Optional[Dict] = None):
+        if not self.config.log_all_access:
+            return
+        entry = {
+            "ts": time.time(),
+            "action": action,
+            "resource": resource,
+        }
+        if details:
+            entry.update(details)
+        self._access_log.append(entry)
+        if len(self._access_log) > 10000:
+            self._access_log = self._access_log[-5000:]
+
+    def can_capture(self) -> Tuple[bool, str]:
+        self._reset_daily_if_needed()
+        if self._daily_frame_count >= self.config.max_total_frames_per_day:
+            return False, "Daily frame limit reached"
+        return True, ""
+
+    def record_capture(self):
+        self._reset_daily_if_needed()
+        self._daily_frame_count += 1
+
+    def can_persist(self) -> Tuple[bool, str]:
+        if self.config.require_confirmation_for_persist:
+            return True, "Confirmation required"
+        return True, ""
+
+    def get_access_log(self, limit: int = 100) -> List[Dict]:
+        return self._access_log[-limit:]
+
+    def get_privacy_summary(self) -> Dict[str, Any]:
+        return {
+            "daily_frames": self._daily_frame_count,
+            "daily_limit": self.config.max_total_frames_per_day,
+            "session_limit": self.config.max_frames_per_session,
+            "block_password_fields": self.config.block_password_fields,
+            "block_pii_detection": self.config.block_pii_detection,
+            "blur_sensitive_regions": self.config.blur_sensitive_regions,
+            "access_log_entries": len(self._access_log),
+        }