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

algo_cli/intelligence/backpressure.py

@@ -0,0 +1,99 @@
+"""B86. Backpressure Signals for Token-Aware Agents.
+
+PRESSURE=LOW/MED/HIGH tells agent when to expand or contract output.
+BUDGET directives.  Source: Keel pattern.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum, auto
+
+
+class PressureLevel(Enum):
+    LOW = auto()      # plenty of budget — be thorough
+    MEDIUM = auto()   # budget tightening — be concise
+    HIGH = auto()     # budget critical — minimal output only
+    CRITICAL = auto() # budget exhausted — stop
+
+
+@dataclass
+class BackpressureSignal:
+    level: PressureLevel
+    remaining_tokens: int = 0
+    total_budget: int = 0
+    used_pct: float = 0.0
+    directive: str = ""
+    recommended_max_output: int = 0
+
+
+class BackpressureMonitor:
+    """Monitor token budget and emit pressure signals."""
+
+    THRESHOLDS: dict[PressureLevel, float] = {
+        PressureLevel.LOW: 0.5,       # >50% remaining
+        PressureLevel.MEDIUM: 0.25,   # >25% remaining
+        PressureLevel.HIGH: 0.10,     # >10% remaining
+        PressureLevel.CRITICAL: 0.0,  # exhausted
+    }
+
+    DIRECTIVES: dict[PressureLevel, str] = {
+        PressureLevel.LOW: "BUDGET:EXPAND — be thorough, include examples and context",
+        PressureLevel.MEDIUM: "BUDGET:NORMAL — be concise but complete",
+        PressureLevel.HIGH: "BUDGET:CONTRACT — minimal output, skip explanations",
+        PressureLevel.CRITICAL: "BUDGET:STOP — output budget exhausted, stop immediately",
+    }
+
+    MAX_OUTPUT: dict[PressureLevel, int] = {
+        PressureLevel.LOW: 4000,
+        PressureLevel.MEDIUM: 2000,
+        PressureLevel.HIGH: 500,
+        PressureLevel.CRITICAL: 0,
+    }
+
+    def __init__(self, total_budget: int = 8000) -> None:
+        self._total = total_budget
+        self._used = 0
+
+    def consume(self, tokens: int) -> BackpressureSignal:
+        """Consume tokens and return current pressure signal."""
+        self._used += tokens
+        return self.signal()
+
+    def signal(self) -> BackpressureSignal:
+        """Get current backpressure signal without consuming."""
+        remaining = max(0, self._total - self._used)
+        used_pct = self._used / self._total if self._total > 0 else 1.0
+        remaining_pct = 1.0 - used_pct
+
+        # Determine level
+        level = PressureLevel.CRITICAL
+        for lvl, threshold in self.THRESHOLDS.items():
+            if remaining_pct >= threshold:
+                level = lvl
+                break
+
+        return BackpressureSignal(
+            level=level,
+            remaining_tokens=remaining,
+            total_budget=self._total,
+            used_pct=used_pct,
+            directive=self.DIRECTIVES[level],
+            recommended_max_output=self.MAX_OUTPUT[level],
+        )
+
+    def reset(self) -> None:
+        self._used = 0
+
+    @property
+    def used(self) -> int:
+        return self._used
+
+    @property
+    def remaining(self) -> int:
+        return max(0, self._total - self._used)
+
+    def should_stop(self) -> bool:
+        return self.signal().level == PressureLevel.CRITICAL
+
+    def should_contract(self) -> bool:
+        return self.signal().level in (PressureLevel.HIGH, PressureLevel.CRITICAL)

algo_cli/intelligence/bloom_filter.py

@@ -0,0 +1,186 @@
+"""Bloom Filter — probabilistic set membership with false positives.
+
+A Bloom filter answers "is this item in the set?" in O(k) time using
+k hash functions and a bit array.  False positives are possible but
+false negatives are impossible.  Memory is ~10x smaller than a hash set.
+
+Harness use: dedup for embedding pipeline — "has this file already been
+embedded?" without storing every path.  Also useful for URL dedup
+("have we already fetched this URL?") and content dedup.
+
+Operations:
+  - add(item):     O(k) — set k bits
+  - contains(item): O(k) — check k bits
+  - false_positive_rate(): current estimated FPR
+  - merge(other):  union two filters (same size/hashes)
+
+Properties:
+  - No false negatives (if contains() returns False, item was never added)
+  - False positive rate tunable via bit_array_size and num_hashes
+  - Cannot remove items (use CountingBloomFilter for that)
+"""
+from __future__ import annotations
+
+import hashlib
+import math
+from typing import Any
+
+
+class BloomFilter:
+    """Standard Bloom filter with double-hashing (Kirsch-Mitzenmacher).
+
+    Uses two base hashes h1=MD5, h2=SHA1 and derives k hashes via
+    h_i(x) = h1(x) + i * h2(x), avoiding k separate hash computations.
+    """
+
+    def __init__(
+        self,
+        capacity: int = 10_000,
+        false_positive_rate: float = 0.01,
+    ) -> None:
+        """Create a Bloom filter sized for *capacity* items at target FPR.
+
+        Args:
+            capacity: Expected number of items to add.
+            false_positive_rate: Target false positive rate (e.g. 0.01 = 1%).
+        """
+        self.capacity = capacity
+        self.target_fpr = false_positive_rate
+        self.bit_array_size = self._optimal_m(capacity, false_positive_rate)
+        self.num_hashes = self._optimal_k(self.bit_array_size, capacity)
+        self._bits = bytearray((self.bit_array_size + 7) // 8)
+        self.count = 0
+
+    @staticmethod
+    def _optimal_m(n: int, p: float) -> int:
+        """Optimal bit array size: m = -n*ln(p) / (ln(2)^2)."""
+        return max(1, int(-n * math.log(p) / (math.log(2) ** 2)))
+
+    @staticmethod
+    def _optimal_k(m: int, n: int) -> int:
+        """Optimal number of hash functions: k = (m/n) * ln(2)."""
+        return max(1, int((m / max(1, n)) * math.log(2)))
+
+    def _hashes(self, item: Any) -> list[int]:
+        """Generate k hash positions using double-hashing."""
+        data = str(item).encode("utf-8")
+        h1 = int.from_bytes(hashlib.md5(data).digest()[:8], "little")
+        h2 = int.from_bytes(hashlib.sha1(data).digest()[:8], "little")
+        m = self.bit_array_size
+        return [(h1 + i * h2) % m for i in range(self.num_hashes)]
+
+    def _set_bit(self, pos: int) -> None:
+        self._bits[pos >> 3] |= (1 << (pos & 7))
+
+    def _get_bit(self, pos: int) -> bool:
+        return bool(self._bits[pos >> 3] & (1 << (pos & 7)))
+
+    def add(self, item: Any) -> None:
+        """Add an item to the filter."""
+        for pos in self._hashes(item):
+            self._set_bit(pos)
+        self.count += 1
+
+    def add_many(self, items: list[Any]) -> None:
+        """Add multiple items."""
+        for item in items:
+            self.add(item)
+
+    def contains(self, item: Any) -> bool:
+        """Check if item might be in the set.
+
+        Returns True if the item is possibly in the set (may be false positive).
+        Returns False if the item is definitely not in the set.
+        """
+        return all(self._get_bit(pos) for pos in self._hashes(item))
+
+    def __contains__(self, item: Any) -> bool:
+        return self.contains(item)
+
+    def false_positive_rate(self) -> float:
+        """Current estimated false positive rate based on items added."""
+        if self.count == 0:
+            return 0.0
+        k = self.num_hashes
+        m = self.bit_array_size
+        n = self.count
+        return (1 - math.exp(-k * n / m)) ** k
+
+    def merge(self, other: BloomFilter) -> None:
+        """Merge another filter into this one (in-place union).
+
+        Both filters must have the same bit_array_size and num_hashes.
+        """
+        if self.bit_array_size != other.bit_array_size:
+            raise ValueError("Cannot merge filters with different sizes")
+        if self.num_hashes != other.num_hashes:
+            raise ValueError("Cannot merge filters with different hash counts")
+        for i in range(len(self._bits)):
+            self._bits[i] |= other._bits[i]
+        self.count += other.count
+
+    def bit_density(self) -> float:
+        """Fraction of bits set — useful for monitoring saturation."""
+        set_bits = sum(bin(b).count("1") for b in self._bits)
+        return set_bits / self.bit_array_size
+
+    def stats(self) -> dict[str, Any]:
+        return {
+            "capacity": self.capacity,
+            "bit_array_size": self.bit_array_size,
+            "num_hashes": self.num_hashes,
+            "items_added": self.count,
+            "false_positive_rate": round(self.false_positive_rate(), 6),
+            "bit_density": round(self.bit_density(), 4),
+            "memory_bytes": len(self._bits),
+        }
+
+
+class CountingBloomFilter:
+    """Counting Bloom filter — supports removal via counter per slot.
+
+    Uses 4-bit counters (max count 15) instead of single bits.
+    Slightly more memory than standard BloomFilter but supports delete().
+    """
+
+    def __init__(
+        self,
+        capacity: int = 10_000,
+        false_positive_rate: float = 0.01,
+    ) -> None:
+        self.capacity = capacity
+        m = BloomFilter._optimal_m(capacity, false_positive_rate)
+        self.bit_array_size = m
+        self.num_hashes = BloomFilter._optimal_k(m, capacity)
+        self._counters = bytearray(m)  # each counter 0-255 (we cap at 255)
+        self.count = 0
+
+    def _hashes(self, item: Any) -> list[int]:
+        data = str(item).encode("utf-8")
+        h1 = int.from_bytes(hashlib.md5(data).digest()[:8], "little")
+        h2 = int.from_bytes(hashlib.sha1(data).digest()[:8], "little")
+        m = self.bit_array_size
+        return [(h1 + i * h2) % m for i in range(self.num_hashes)]
+
+    def add(self, item: Any) -> None:
+        for pos in self._hashes(item):
+            if self._counters[pos] < 255:
+                self._counters[pos] += 1
+        self.count += 1
+
+    def remove(self, item: Any) -> None:
+        """Remove an item. Only call if you know the item was previously added."""
+        for pos in self._hashes(item):
+            if self._counters[pos] > 0:
+                self._counters[pos] -= 1
+        self.count = max(0, self.count - 1)
+
+    def contains(self, item: Any) -> bool:
+        return all(self._counters[pos] > 0 for pos in self._hashes(item))
+
+    def __contains__(self, item: Any) -> bool:
+        return self.contains(item)
+
+    def estimate_count(self, item: Any) -> int:
+        """Estimate the number of times item was added (min of counters)."""
+        return min(self._counters[pos] for pos in self._hashes(item))

algo_cli/intelligence/bonferroni.py

@@ -0,0 +1,66 @@
+"""H24 — Bonferroni Correction for Multiple Comparisons.
+
+Prevents false discoveries when running many tests by adjusting the
+significance threshold: divide alpha by the number of comparisons.
+
+Source: GLOSSOPETRAE ``e3s_multiconstruction_stego.mjs``.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class BonferroniResult:
+    """Result of a Bonferroni correction check."""
+
+    p_value: float
+    adjusted_alpha: float
+    is_significant: bool
+    n_tests: int
+
+
+class BonferroniGuard:
+    """Bonferroni correction guard for multiple comparisons."""
+
+    @staticmethod
+    def correct(alpha: float, n_tests: int) -> float:
+        """Return the Bonferroni-adjusted alpha threshold.
+
+        Args:
+            alpha: Original significance level (e.g. 0.05).
+            n_tests: Number of comparisons performed.
+
+        Returns:
+            Adjusted alpha = alpha / n_tests.
+        """
+        if n_tests < 1:
+            raise ValueError(f"n_tests must be >= 1, got {n_tests}")
+        return alpha / n_tests
+
+    @staticmethod
+    def is_significant(p_value: float, alpha: float, n_tests: int) -> bool:
+        """Check if a p-value is significant after Bonferroni correction."""
+        adjusted = BonferroniGuard.correct(alpha, n_tests)
+        return p_value < adjusted
+
+    @staticmethod
+    def evaluate(p_value: float, alpha: float, n_tests: int) -> BonferroniResult:
+        """Full evaluation with details."""
+        adjusted = BonferroniGuard.correct(alpha, n_tests)
+        return BonferroniResult(
+            p_value=p_value,
+            adjusted_alpha=adjusted,
+            is_significant=p_value < adjusted,
+            n_tests=n_tests,
+        )
+
+    @staticmethod
+    def evaluate_many(
+        p_values: list[float], alpha: float
+    ) -> list[BonferroniResult]:
+        """Evaluate multiple p-values with Bonferroni correction."""
+        n = len(p_values)
+        return [
+            BonferroniGuard.evaluate(p, alpha, n) for p in p_values
+        ]

algo_cli/intelligence/boundary_compaction.py

@@ -0,0 +1,98 @@
+"""B54. Boundary-Aware Context Compaction.
+
+Preserve function-call pairs atomically during compaction.
+Source: openai-agents-context-compaction pattern.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class Message:
+    role: str
+    content: str
+    tool_call_id: str | None = None
+    tool_calls: list[dict] | None = None
+    token_estimate: int = 0
+
+
+@dataclass
+class CompactionResult:
+    messages: list[Message]
+    removed_count: int
+    preserved_pairs: int
+    summary: str = ""
+
+
+class BoundaryAwareCompactor:
+    """Compact context while preserving function-call pairs atomically."""
+
+    def __init__(self, target_tokens: int = 8000, min_keep: int = 4):
+        self.target_tokens = target_tokens
+        self.min_keep = min_keep
+
+    def _estimate_tokens(self, msg: Message) -> int:
+        if msg.token_estimate:
+            return msg.token_estimate
+        return max(1, len(msg.content) // 4)
+
+    def _total_tokens(self, messages: list[Message]) -> int:
+        return sum(self._estimate_tokens(m) for m in messages)
+
+    def _find_call_pairs(self, messages: list[Message]) -> list[tuple[int, int]]:
+        """Find (assistant_with_tool_call, tool_response) index pairs."""
+        pairs: list[tuple[int, int]] = []
+        for i, msg in enumerate(messages):
+            if msg.role == "assistant" and msg.tool_calls:
+                for call in msg.tool_calls:
+                    call_id = call.get("id")
+                    for j in range(i + 1, len(messages)):
+                        if messages[j].tool_call_id == call_id:
+                            pairs.append((i, j))
+                            break
+        return pairs
+
+    def compact(self, messages: list[Message]) -> CompactionResult:
+        """Compact messages to fit within target_tokens."""
+        total = self._total_tokens(messages)
+        if total <= self.target_tokens:
+            return CompactionResult(messages=messages, removed_count=0, preserved_pairs=0)
+
+        pairs = self._find_call_pairs(messages)
+        pair_indices: set[int] = set()
+        for a, b in pairs:
+            pair_indices.add(a)
+            pair_indices.add(b)
+
+        # Always keep the last min_keep messages
+        protected = set(range(max(0, len(messages) - self.min_keep), len(messages)))
+        protected |= pair_indices
+
+        # Remove oldest non-protected messages until under target
+        removed = 0
+        result = list(messages)
+        i = 0
+        while self._total_tokens(result) > self.target_tokens and i < len(result):
+            if i in protected:
+                i += 1
+                continue
+            result.pop(i)
+            removed += 1
+            # Rebuild protected set indices after removal
+            protected = set(range(max(0, len(result) - self.min_keep), len(result)))
+            # Rebuild pair indices
+            pair_indices.clear()
+            new_pairs = self._find_call_pairs(result)
+            for a, b in new_pairs:
+                pair_indices.add(a)
+                pair_indices.add(b)
+            protected |= pair_indices
+        else:
+            i += 1
+
+        return CompactionResult(
+            messages=result,
+            removed_count=removed,
+            preserved_pairs=len(pairs),
+        )

algo_cli/intelligence/catalog_verifier.py

@@ -0,0 +1,172 @@
+"""H2 — Algorithm Catalog Verifier.
+
+Re-derive every `implemented` status from live tests.
+Mined from T3MP3ST verify-claims.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class CatalogEntry:
+    """A single catalog entry parsed from ALGO.md."""
+
+    id: str
+    title: str
+    status: str = "unknown"  # "implemented", "proposed", "partial", "retired"
+    section: str = ""
+    line_number: int = 0
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "title": self.title,
+            "status": self.status,
+            "section": self.section,
+            "line_number": self.line_number,
+            "metadata": dict(self.metadata),
+        }
+
+
+@dataclass
+class VerificationResult:
+    """Result of verifying a single catalog entry."""
+
+    entry_id: str
+    claimed_status: str
+    verified: bool
+    reason: str = ""
+    test_names: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "entry_id": self.entry_id,
+            "claimed_status": self.claimed_status,
+            "verified": self.verified,
+            "reason": self.reason,
+            "test_names": list(self.test_names),
+        }
+
+
+@dataclass
+class VerificationReport:
+    """Full report of catalog verification."""
+
+    results: list[VerificationResult] = field(default_factory=list)
+    total_entries: int = 0
+    verified_count: int = 0
+    failed_count: int = 0
+
+    @property
+    def all_verified(self) -> bool:
+        return self.failed_count == 0
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "results": [r.to_dict() for r in self.results],
+            "total_entries": self.total_entries,
+            "verified_count": self.verified_count,
+            "failed_count": self.failed_count,
+            "all_verified": self.all_verified,
+        }
+
+
+class CatalogVerifier:
+    """Parse ALGO.md and verify claimed statuses against live tests."""
+
+    # Match entries like "### H1. Title", "### H1 — Title", or "### H1 Title"
+    _ENTRY_RE = re.compile(r"^###\s+([A-Z]\d+)\.?\s*[—–\-\s]\s*(.+)$", re.MULTILINE)
+    # Match status markers
+    _STATUS_RE = re.compile(r"\b(implemented|proposed|partial|retired)\b", re.IGNORECASE)
+
+    def parse_catalog(self, markdown_text: str) -> list[CatalogEntry]:
+        """Parse ALGO.md markdown and return catalog entries."""
+        entries: list[CatalogEntry] = []
+        for match in self._ENTRY_RE.finditer(markdown_text):
+            entry_id = match.group(1)
+            title = match.group(2).strip()
+            line_num = markdown_text[: match.start()].count("\n") + 1
+            # Look for status in the next ~500 chars
+            after_text = markdown_text[match.end() : match.end() + 500]
+            status_match = self._STATUS_RE.search(after_text)
+            status = status_match.group(1).lower() if status_match else "unknown"
+            entries.append(
+                CatalogEntry(
+                    id=entry_id,
+                    title=title,
+                    status=status,
+                    line_number=line_num,
+                )
+            )
+        return entries
+
+    def verify(
+        self,
+        entries: list[CatalogEntry],
+        test_results: dict[str, bool] | None = None,
+    ) -> VerificationReport:
+        """Verify entries against test results.
+
+        Args:
+            entries: Parsed catalog entries.
+            test_results: Map of entry_id → test_passed. If None, all claimed
+                          "implemented" entries without tests are flagged.
+        """
+        test_results = test_results or {}
+        results: list[VerificationResult] = []
+        verified = 0
+        failed = 0
+        for entry in entries:
+            if entry.status != "implemented":
+                results.append(
+                    VerificationResult(
+                        entry_id=entry.id,
+                        claimed_status=entry.status,
+                        verified=True,
+                        reason=f"Status is '{entry.status}' — no verification needed",
+                    )
+                )
+                verified += 1
+                continue
+            # Check if we have test results
+            test_passed = test_results.get(entry.id)
+            if test_passed is None:
+                results.append(
+                    VerificationResult(
+                        entry_id=entry.id,
+                        claimed_status=entry.status,
+                        verified=False,
+                        reason="Claimed 'implemented' but no test result provided",
+                    )
+                )
+                failed += 1
+            elif test_passed:
+                results.append(
+                    VerificationResult(
+                        entry_id=entry.id,
+                        claimed_status=entry.status,
+                        verified=True,
+                        reason="Test passed",
+                    )
+                )
+                verified += 1
+            else:
+                results.append(
+                    VerificationResult(
+                        entry_id=entry.id,
+                        claimed_status=entry.status,
+                        verified=False,
+                        reason="Test failed",
+                    )
+                )
+                failed += 1
+        return VerificationReport(
+            results=results,
+            total_entries=len(entries),
+            verified_count=verified,
+            failed_count=failed,
+        )