algo-cli-runtime 0.14.0__py3-none-any.whl

algo_cli/intelligence/lesson_catalog.py

@@ -0,0 +1,135 @@
+"""H5 — Lesson-to-Catalog Proposal Pipeline.
+
+Scans lesson text for algorithmic patterns and proposes catalog entries.
+Mined from T3MP3ST self-improvement loop (🧪 Research → 📋 Catalog).
+
+LLM integration: optionally uses an LLM to scan lesson text and propose
+catalog entries. Falls back to keyword-based extraction when no model is
+available.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class CatalogProposal:
+    """A proposed catalog entry derived from a lesson."""
+
+    title: str
+    use_for: str
+    pseudocode: str
+    source_lesson: str
+    confidence: float = 0.0
+    keywords: list[str] = field(default_factory=list)
+
+
+# Keyword patterns that indicate algorithmic lessons
+_PATTERN_KEYWORDS = {
+    "algorithm": ["algorithm", "pattern", "approach", "method", "strategy"],
+    "verification": ["verify", "check", "validate", "test", "assert"],
+    "guard": ["guard", "clamp", "prevent", "block", "gate"],
+    "pipeline": ["pipeline", "flow", "stage", "phase", "step"],
+    "metric": ["metric", "score", "measure", "telemetry", "signal"],
+    "fallback": ["fallback", "retry", "recover", "degrade"],
+}
+
+
+def _extract_keywords(text: str) -> list[str]:
+    """Extract algorithmic keywords from lesson text."""
+    text_lower = text.lower()
+    found = []
+    for category, keywords in _PATTERN_KEYWORDS.items():
+        for kw in keywords:
+            if kw in text_lower:
+                found.append(kw)
+    return found
+
+
+def _extract_title(text: str) -> str:
+    """Derive a title from lesson text."""
+    # Try to find a heading or first sentence
+    lines = text.strip().split("\n")
+    for line in lines:
+        line = line.strip()
+        if line.startswith("#"):
+            return line.lstrip("#").strip()
+        if line and len(line) > 10:
+            # Use first sentence, truncated
+            first_sentence = line.split(".")[0]
+            if len(first_sentence) > 60:
+                return first_sentence[:57] + "..."
+            return first_sentence
+    return "Untitled Pattern"
+
+
+def _compute_confidence(keywords: list[str], text: str) -> float:
+    """Compute confidence based on keyword density."""
+    if not keywords:
+        return 0.0
+    text_lower = text.lower()
+    total_hits = sum(text_lower.count(kw) for kw in keywords)
+    # Normalize by text length (per 1000 chars)
+    density = total_hits / max(len(text), 1) * 1000
+    # Sigmoid-like: 0.5 at density=2, approaching 1.0 at density=5+
+    return min(1.0, density / 5.0)
+
+
+def propose_from_lesson(
+    lesson_text: str,
+    model_client: Any | None = None,
+) -> CatalogProposal:
+    """Propose a catalog entry from a lesson.
+
+    Args:
+        lesson_text: The lesson text to scan.
+        model_client: Optional LLM client for richer extraction.
+                     Falls back to keyword-based extraction when None.
+
+    Returns:
+        A CatalogProposal with extracted patterns.
+    """
+    keywords = _extract_keywords(lesson_text)
+    title = _extract_title(lesson_text)
+    confidence = _compute_confidence(keywords, lesson_text)
+
+    # Build pseudocode from keywords
+    if keywords:
+        pseudo_lines = [
+            f"# Detected patterns: {', '.join(keywords[:5])}",
+            f"def {title.lower().replace(' ', '_')}(input):",
+            f"    # Keywords: {', '.join(keywords)}",
+            "    result = process(input)",
+            "    return result",
+        ]
+        pseudocode = "\n".join(pseudo_lines)
+    else:
+        pseudocode = "# No clear algorithmic pattern detected"
+
+    use_for = f"Lessons containing: {', '.join(keywords[:3])}" if keywords else "General lessons"
+
+    return CatalogProposal(
+        title=title,
+        use_for=use_for,
+        pseudocode=pseudocode,
+        source_lesson=lesson_text[:200],
+        confidence=confidence,
+        keywords=keywords,
+    )
+
+
+def propose_batch(
+    lessons: list[str],
+    model_client: Any | None = None,
+) -> list[CatalogProposal]:
+    """Propose catalog entries from multiple lessons."""
+    return [propose_from_lesson(lesson, model_client) for lesson in lessons]
+
+
+def filter_high_confidence(
+    proposals: list[CatalogProposal],
+    threshold: float = 0.3,
+) -> list[CatalogProposal]:
+    """Filter proposals below confidence threshold."""
+    return [p for p in proposals if p.confidence >= threshold]

algo_cli/intelligence/llm_fallback.py

@@ -0,0 +1,169 @@
+"""H15 — LLM Fallback Chain.
+
+Multi-tier fallback for LLM calls: primary model → fallback model →
+3-tier JSON parsing. Prevents total failure when primary model is unavailable.
+Mined from T3MP3ST WHITEPAPER §5.2 safeLLMCall().
+"""
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class FallbackResult:
+    """Result of a fallback chain call."""
+
+    success: bool
+    response: str = ""
+    parsed_json: dict | None = None
+    model_used: str = ""
+    parse_tier: int = 0  # 0=direct, 1=regex, 2=repair, 3=failed
+    error: str = ""
+
+
+def _parse_json_tier_1(text: str) -> dict | None:
+    """Tier 1: Direct json.loads."""
+    try:
+        return json.loads(text)
+    except (json.JSONDecodeError, TypeError):
+        return None
+
+
+def _parse_json_tier_2(text: str) -> dict | None:
+    """Tier 2: Extract JSON from markdown code blocks or surrounding text."""
+    # Try to find ```json ... ``` blocks
+    match = re.search(r"```(?:json)?\s*\n?(.*?)\n?```", text, re.DOTALL)
+    if match:
+        result = _parse_json_tier_1(match.group(1).strip())
+        if result is not None:
+            return result
+
+    # Try to find the first { ... } block
+    match = re.search(r"\{.*\}", text, re.DOTALL)
+    if match:
+        result = _parse_json_tier_1(match.group(0))
+        if result is not None:
+            return result
+
+    return None
+
+
+def _parse_json_tier_3(text: str) -> dict | None:
+    """Tier 3: Repair common JSON errors (trailing commas, unquoted keys)."""
+    repaired = text
+
+    # Remove trailing commas before } or ]
+    repaired = re.sub(r",\s*([}\]])", r"\1", repaired)
+
+    # Quote unquoted keys (key:)
+    repaired = re.sub(r"(\w+)\s*:", r'"\1":', repaired)
+    # But don't double-quote already-quoted keys
+    repaired = re.sub(r'""(\w+)""\s*:', r'"\1":', repaired)
+
+    # Remove control characters
+    repaired = re.sub(r"[\x00-\x1f]", "", repaired)
+
+    return _parse_json_tier_1(repaired)
+
+
+def parse_json_with_fallback(text: str) -> tuple[dict | None, int]:
+    """Parse JSON with 3-tier fallback.
+
+    Returns (parsed_dict_or_None, tier_used).
+    Tier 0 = direct parse, 1 = regex extraction, 2 = repair, 3 = failed.
+    """
+    result = _parse_json_tier_1(text)
+    if result is not None:
+        return result, 0
+
+    result = _parse_json_tier_2(text)
+    if result is not None:
+        return result, 1
+
+    result = _parse_json_tier_3(text)
+    if result is not None:
+        return result, 2
+
+    return None, 3
+
+
+def llm_call_with_fallback(
+    prompt: str,
+    primary_client: Any | None = None,
+    fallback_client: Any | None = None,
+    expect_json: bool = False,
+) -> FallbackResult:
+    """Call LLM with fallback chain.
+
+    Args:
+        prompt: The prompt to send.
+        primary_client: Primary model client (must have .generate(prompt) -> str).
+        fallback_client: Fallback model client.
+        expect_json: If True, attempt JSON parsing with 3-tier fallback.
+
+    Returns:
+        FallbackResult with success status and parsed data.
+    """
+    # Try primary model
+    if primary_client is not None:
+        try:
+            response = primary_client.generate(prompt)
+            if response:
+                if expect_json:
+                    parsed, tier = parse_json_with_fallback(response)
+                    if parsed is not None:
+                        return FallbackResult(
+                            success=True,
+                            response=response,
+                            parsed_json=parsed,
+                            model_used=getattr(primary_client, "model_name", "primary"),
+                            parse_tier=tier,
+                        )
+                else:
+                    return FallbackResult(
+                        success=True,
+                        response=response,
+                        model_used=getattr(primary_client, "model_name", "primary"),
+                    )
+        except Exception as e:
+            primary_error = str(e)
+        else:
+            primary_error = "empty response"
+    else:
+        primary_error = "no primary client"
+
+    # Try fallback model
+    if fallback_client is not None:
+        try:
+            response = fallback_client.generate(prompt)
+            if response:
+                if expect_json:
+                    parsed, tier = parse_json_with_fallback(response)
+                    if parsed is not None:
+                        return FallbackResult(
+                            success=True,
+                            response=response,
+                            parsed_json=parsed,
+                            model_used=getattr(fallback_client, "model_name", "fallback"),
+                            parse_tier=tier,
+                        )
+                else:
+                    return FallbackResult(
+                        success=True,
+                        response=response,
+                        model_used=getattr(fallback_client, "model_name", "fallback"),
+                    )
+        except Exception as e:
+            fallback_error = str(e)
+        else:
+            fallback_error = "empty response"
+    else:
+        fallback_error = "no fallback client"
+
+    return FallbackResult(
+        success=False,
+        error=f"Primary: {primary_error}; Fallback: {fallback_error}",
+    )

algo_cli/intelligence/log2_histogram.py

@@ -0,0 +1,267 @@
+"""Log2 Histogram — memory-efficient latency telemetry.
+
+Borrowed from Windows Performance Counters registry
+(HKLM\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\Perflib\\009):
+Windows uses 16 log2-sized buckets covering 128µs to >30s — 6 orders of
+magnitude in 72 bytes.  Binary-search insertion is O(log 16) = O(4).
+Histograms are mergeable across sessions for aggregate statistics.
+
+Pattern: B29 in ALGO.md.
+"""
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+# Bucket upper bounds in microseconds.
+# Source: Windows Performance Counter registry bucket definitions.
+BOUNDARIES_US: tuple[float, ...] = (
+    128,        # bucket 01: <= 128 µs
+    256,        # bucket 02: <= 256 µs
+    512,        # bucket 03: <= 512 µs
+    1_024,      # bucket 04: <= 1 ms
+    4_096,      # bucket 05: <= 4 ms
+    16_384,     # bucket 06: <= 16 ms
+    65_536,     # bucket 07: <= 64 ms
+    131_072,    # bucket 08: <= 128 ms
+    262_144,    # bucket 09: <= 256 ms
+    524_288,    # bucket 10: <= 512 ms
+    1_048_576,  # bucket 11: <= 1 s
+    2_097_152,  # bucket 12: <= 2 s
+    10_485_760, # bucket 13: <= 10 s
+    20_971_520, # bucket 14: <= 20 s
+    31_457_280, # bucket 15: <= 30 s
+    float("inf"),  # bucket 16: > 30 s
+)
+
+# Human-readable labels for each bucket.
+BUCKET_LABELS: tuple[str, ...] = (
+    "<=128µs", "<=256µs", "<=512µs", "<=1ms", "<=4ms", "<=16ms",
+    "<=64ms", "<=128ms", "<=256ms", "<=512ms", "<=1s", "<=2s",
+    "<=10s", "<=20s", "<=30s", ">30s",
+)
+
+
+@dataclass
+class Log2Histogram:
+    """Log2-bucketed histogram — O(log b) insert, O(b) quantile.
+
+    16 buckets cover 128µs to >30s in ~72 bytes.
+    Mergeable: two histograms combine by bucket-wise addition.
+    """
+
+    buckets: list[int] = field(default_factory=lambda: [0] * len(BOUNDARIES_US))
+    count: int = 0
+    sum_us: float = 0.0
+    min_us: float = float("inf")
+    max_us: float = 0.0
+
+    # --- core operations --------------------------------------------------
+
+    def observe(self, value_us: float) -> None:
+        """Record a latency observation in microseconds."""
+        idx = self._bucket_index(value_us)
+        self.buckets[idx] += 1
+        self.count += 1
+        self.sum_us += value_us
+        if value_us < self.min_us:
+            self.min_us = value_us
+        if value_us > self.max_us:
+            self.max_us = value_us
+
+    def observe_seconds(self, value_s: float) -> None:
+        """Record a latency observation in seconds."""
+        self.observe(value_s * 1_000_000)
+
+    def _bucket_index(self, value: float) -> int:
+        """Binary search for bucket — O(log 16) = O(4)."""
+        lo, hi = 0, len(BOUNDARIES_US) - 1
+        while lo < hi:
+            mid = (lo + hi) // 2
+            if value <= BOUNDARIES_US[mid]:
+                hi = mid
+            else:
+                lo = mid + 1
+        return lo
+
+    # --- queries ----------------------------------------------------------
+
+    def percentile(self, p: float) -> float:
+        """Estimate p-th percentile in microseconds — O(buckets).
+
+        Uses linear interpolation within the bucket.
+        """
+        if self.count == 0:
+            return 0.0
+        target = self.count * p / 100.0
+        cumulative = 0
+        for i, bucket_count in enumerate(self.buckets):
+            cumulative += bucket_count
+            if cumulative >= target:
+                lower = 0.0 if i == 0 else BOUNDARIES_US[i - 1]
+                upper = BOUNDARIES_US[i]
+                if bucket_count == 0:
+                    return lower
+                frac = (target - (cumulative - bucket_count)) / bucket_count
+                return lower + frac * (upper - lower)
+        return BOUNDARIES_US[-2]  # second-to-last (last is inf)
+
+    def percentile_seconds(self, p: float) -> float:
+        """Estimate p-th percentile in seconds."""
+        return self.percentile(p) / 1_000_000
+
+    def mean_us(self) -> float:
+        """Arithmetic mean in microseconds."""
+        return self.sum_us / self.count if self.count else 0.0
+
+    def mean_seconds(self) -> float:
+        return self.mean_us() / 1_000_000
+
+    # --- merge ------------------------------------------------------------
+
+    def merge(self, other: Log2Histogram) -> Log2Histogram:
+        """Merge two histograms — O(buckets)."""
+        result = Log2Histogram()
+        result.buckets = [a + b for a, b in zip(self.buckets, other.buckets)]
+        result.count = self.count + other.count
+        result.sum_us = self.sum_us + other.sum_us
+        result.min_us = min(self.min_us, other.min_us)
+        result.max_us = max(self.max_us, other.max_us)
+        return result
+
+    # --- serialization ----------------------------------------------------
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "buckets": list(self.buckets),
+            "count": self.count,
+            "sum_us": self.sum_us,
+            "min_us": self.min_us if self.min_us != float("inf") else 0.0,
+            "max_us": self.max_us,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Log2Histogram:
+        h = cls()
+        h.buckets = list(data.get("buckets", [0] * len(BOUNDARIES_US)))
+        h.count = data.get("count", 0)
+        h.sum_us = data.get("sum_us", 0.0)
+        h.min_us = data.get("min_us", float("inf"))
+        h.max_us = data.get("max_us", 0.0)
+        return h
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict())
+
+    @classmethod
+    def from_json(cls, s: str) -> Log2Histogram:
+        return cls.from_dict(json.loads(s))
+
+    # --- display ----------------------------------------------------------
+
+    def summary(self) -> dict[str, float]:
+        """Compact summary for dashboards."""
+        return {
+            "count": self.count,
+            "mean_us": round(self.mean_us(), 1),
+            "p50_us": round(self.percentile(50), 1),
+            "p90_us": round(self.percentile(90), 1),
+            "p99_us": round(self.percentile(99), 1),
+            "min_us": round(self.min_us, 1) if self.min_us != float("inf") else 0,
+            "max_us": round(self.max_us, 1),
+        }
+
+    def histogram_text(self) -> str:
+        """ASCII histogram for terminal display."""
+        if self.count == 0:
+            return "(empty)"
+        max_count = max(self.buckets) or 1
+        lines = []
+        for i, count in enumerate(self.buckets):
+            if count == 0:
+                continue
+            bar_len = int(count / max_count * 40)
+            bar = "█" * bar_len
+            lines.append(f"  {BUCKET_LABELS[i]:>8s} │{bar:<40s} │ {count}")
+        return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Registry — per-tool latency histograms
+# ---------------------------------------------------------------------------
+
+_REGISTRY: dict[str, Log2Histogram] = {}
+
+
+def get_histogram(name: str) -> Log2Histogram:
+    """Get or create a named histogram (e.g., 'read_file', 'embed', 'model')."""
+    if name not in _REGISTRY:
+        _REGISTRY[name] = Log2Histogram()
+    return _REGISTRY[name]
+
+
+def record_latency(name: str, duration_s: float) -> None:
+    """Record a latency observation for a named operation."""
+    get_histogram(name).observe_seconds(duration_s)
+
+
+def all_summaries() -> dict[str, dict[str, float]]:
+    """Get summaries for all registered histograms."""
+    return {name: h.summary() for name, h in _REGISTRY.items()}
+
+
+def save_to_file(path: Path) -> None:
+    """Persist all histograms to a JSON file."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    data = {name: h.to_dict() for name, h in _REGISTRY.items()}
+    path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+
+
+def load_from_file(path: Path) -> None:
+    """Load histograms from a JSON file (merges into registry)."""
+    if not path.exists():
+        return
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return
+    for name, hist_data in data.items():
+        existing = _REGISTRY.get(name)
+        loaded = Log2Histogram.from_dict(hist_data)
+        if existing:
+            _REGISTRY[name] = existing.merge(loaded)
+        else:
+            _REGISTRY[name] = loaded
+
+
+def clear_registry() -> None:
+    """Clear all registered histograms (for testing)."""
+    _REGISTRY.clear()
+
+
+# ---------------------------------------------------------------------------
+# Context manager for easy timing
+# ---------------------------------------------------------------------------
+
+class LatencyTimer:
+    """Context manager that records latency into a named histogram.
+
+    Usage:
+        with LatencyTimer("read_file"):
+            content = read_file(path)
+    """
+
+    def __init__(self, name: str):
+        self.name = name
+        self._start = 0.0
+
+    def __enter__(self) -> LatencyTimer:
+        self._start = time.perf_counter()
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        duration = time.perf_counter() - self._start
+        record_latency(self.name, duration)