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

algo_cli/intelligence/multi_tier_grade.py

@@ -0,0 +1,211 @@
+"""H26 — Multi-Tier Grading.
+
+Strict / lenient / structured grading tiers for solution evaluation.
+Mined from GLOSSOPETRAE experiments/lib/grade_rigor.mjs.
+
+- gradeStrict: unforgiving — any error fails
+- gradeLenient: attempts surface recovery before grading
+- gradeStructured: requires control flow presence, rejects degenerate precompute
+"""
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass, field
+
+
+@dataclass
+class GradeResult:
+    """Result of grading a solution."""
+
+    tier: str  # "strict", "lenient", "structured"
+    passed: bool
+    score: float  # 0.0 - 1.0
+    correct_output: bool = False
+    has_required_constructs: bool = False
+    is_degenerate: bool = False
+    recovered: bool = False
+    notes: list[str] = field(default_factory=list)
+
+
+def _check_output_correctness(actual: str, expected: str) -> bool:
+    """Check if actual output matches expected."""
+    return actual.strip() == expected.strip()
+
+
+def _has_required_constructs(code: str) -> bool:
+    """Check if code has loops, functions, or conditionals."""
+    try:
+        tree = ast.parse(code)
+    except SyntaxError:
+        return False
+
+    has_loop = False
+    has_func = False
+    has_conditional = False
+
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.For, ast.While)):
+            has_loop = True
+        elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda)):
+            has_func = True
+        elif isinstance(node, (ast.If, ast.IfExp)):
+            has_conditional = True
+
+    return has_loop or has_func or has_conditional
+
+
+def _is_degenerate_precompute(code: str) -> bool:
+    """Check if code precomputes the answer without required constructs."""
+    try:
+        tree = ast.parse(code)
+    except SyntaxError:
+        return False
+
+    has_loop = any(isinstance(n, (ast.For, ast.While)) for n in ast.walk(tree))
+    has_func_def = any(
+        isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef))
+        for n in ast.walk(tree)
+    )
+    has_conditional = any(isinstance(n, (ast.If, ast.IfExp)) for n in ast.walk(tree))
+    has_call = any(isinstance(n, ast.Call) for n in ast.walk(tree))
+
+    # Degenerate: has no loops, no function defs, no conditionals, and no function calls
+    return not (has_loop or has_func_def or has_conditional or has_call)
+
+
+def grade_strict(
+    code: str,
+    actual_output: str,
+    expected_output: str,
+) -> GradeResult:
+    """Grade strictly — any error fails."""
+    correct = _check_output_correctness(actual_output, expected_output)
+    return GradeResult(
+        tier="strict",
+        passed=correct,
+        score=1.0 if correct else 0.0,
+        correct_output=correct,
+        notes=["Strict: output must match exactly"],
+    )
+
+
+def grade_lenient(
+    code: str,
+    actual_output: str,
+    expected_output: str,
+) -> GradeResult:
+    """Grade leniently — attempt surface recovery before grading."""
+    # Try exact match first (no normalization)
+    if actual_output == expected_output:
+        return GradeResult(
+            tier="lenient",
+            passed=True,
+            score=1.0,
+            correct_output=True,
+            recovered=False,
+            notes=["Lenient: exact match"],
+        )
+
+    # Try surface recovery: normalize whitespace
+    recovered_output = actual_output.strip()
+    recovered_expected = expected_output.strip()
+
+    # Try exact match after strip
+    correct = recovered_output == recovered_expected
+    if correct:
+        return GradeResult(
+            tier="lenient",
+            passed=True,
+            score=1.0,
+            correct_output=True,
+            recovered=True,
+            notes=["Lenient: whitespace stripped"],
+        )
+
+    # Try case-insensitive match (recovery)
+    correct = recovered_output.lower() == recovered_expected.lower()
+
+    # Try removing extra whitespace
+    if not correct:
+        import re
+        norm_actual = re.sub(r"\s+", " ", recovered_output).strip()
+        norm_expected = re.sub(r"\s+", " ", recovered_expected).strip()
+        correct = norm_actual == norm_expected
+        recovered = correct
+    else:
+        recovered = True
+
+    return GradeResult(
+        tier="lenient",
+        passed=correct,
+        score=1.0 if correct else 0.0,
+        correct_output=correct,
+        recovered=recovered,
+        notes=["Lenient: whitespace and case normalized"] if recovered else ["Lenient: output does not match"],
+    )
+
+
+def grade_structured(
+    code: str,
+    actual_output: str,
+    expected_output: str,
+) -> GradeResult:
+    """Grade with structure requirements — must have control flow, no degenerate precompute."""
+    correct = _check_output_correctness(actual_output, expected_output)
+    has_constructs = _has_required_constructs(code)
+    degenerate = _is_degenerate_precompute(code)
+
+    notes: list[str] = []
+    if degenerate:
+        notes.append("Degenerate precompute: no loops, functions, or conditionals found")
+    if not has_constructs:
+        notes.append("Missing required constructs (loops, functions, or conditionals)")
+
+    # Structured: must be correct AND have constructs AND not be degenerate
+    passed = correct and has_constructs and not degenerate
+
+    if passed:
+        score = 1.0
+    elif correct and not degenerate:
+        score = 0.7  # Correct but missing some constructs
+    elif correct:
+        score = 0.3  # Correct but degenerate
+    else:
+        score = 0.0
+
+    return GradeResult(
+        tier="structured",
+        passed=passed,
+        score=score,
+        correct_output=correct,
+        has_required_constructs=has_constructs,
+        is_degenerate=degenerate,
+        notes=notes,
+    )
+
+
+def grade(
+    code: str,
+    actual_output: str,
+    expected_output: str,
+    tier: str = "strict",
+) -> GradeResult:
+    """Grade a solution at the specified tier.
+
+    Args:
+        code: The solution code.
+        actual_output: What the code produced.
+        expected_output: What was expected.
+        tier: "strict", "lenient", or "structured".
+
+    Returns:
+        GradeResult with detailed grading information.
+    """
+    if tier == "strict":
+        return grade_strict(code, actual_output, expected_output)
+    elif tier == "lenient":
+        return grade_lenient(code, actual_output, expected_output)
+    elif tier == "structured":
+        return grade_structured(code, actual_output, expected_output)
+    else:
+        raise ValueError(f"Unknown grading tier: {tier}")

algo_cli/intelligence/negative_controls.py

@@ -0,0 +1,113 @@
+"""H17 — Negative Control Samples.
+
+Known-clean samples to measure false positive rate.
+Mined from T3MP3ST bench/cve-hunt/ DECOY samples.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ControlSample:
+    """A single negative control sample."""
+
+    id: str
+    content: str
+    label: str = "clean"
+    expected_finding: bool = False
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ConfusionMatrix:
+    """Confusion matrix from running a detector against control samples."""
+
+    true_positives: int = 0
+    false_positives: int = 0
+    true_negatives: int = 0
+    false_negatives: int = 0
+
+    @property
+    def total(self) -> int:
+        return self.true_positives + self.false_positives + self.true_negatives + self.false_negatives
+
+    @property
+    def false_positive_rate(self) -> float:
+        tn_fp = self.true_negatives + self.false_positives
+        return self.false_positives / tn_fp if tn_fp > 0 else 0.0
+
+    @property
+    def false_negative_rate(self) -> float:
+        tp_fn = self.true_positives + self.false_negatives
+        return self.false_negatives / tp_fn if tp_fn > 0 else 0.0
+
+    @property
+    def accuracy(self) -> float:
+        if self.total == 0:
+            return 0.0
+        return (self.true_positives + self.true_negatives) / self.total
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "true_positives": self.true_positives,
+            "false_positives": self.false_positives,
+            "true_negatives": self.true_negatives,
+            "false_negatives": self.false_negatives,
+            "false_positive_rate": self.false_positive_rate,
+            "false_negative_rate": self.false_negative_rate,
+            "accuracy": self.accuracy,
+        }
+
+
+class NegativeControlSuite:
+    """Manage negative control samples and compute confusion matrices."""
+
+    def __init__(self) -> None:
+        self._samples: list[ControlSample] = []
+
+    def add_sample(
+        self,
+        id: str,
+        content: str,
+        expected_finding: bool = False,
+        label: str = "clean",
+        metadata: dict[str, Any] | None = None,
+    ) -> ControlSample:
+        sample = ControlSample(
+            id=id,
+            content=content,
+            label=label,
+            expected_finding=expected_finding,
+            metadata=metadata or {},
+        )
+        self._samples.append(sample)
+        return sample
+
+    def evaluate(self, detector_results: dict[str, bool]) -> ConfusionMatrix:
+        """Evaluate detector results against expected findings."""
+        cm = ConfusionMatrix()
+        for sample in self._samples:
+            detected = detector_results.get(sample.id, False)
+            if sample.expected_finding and detected:
+                cm.true_positives += 1
+            elif sample.expected_finding and not detected:
+                cm.false_negatives += 1
+            elif not sample.expected_finding and detected:
+                cm.false_positives += 1
+            else:
+                cm.true_negatives += 1
+        return cm
+
+    def get_sample(self, sample_id: str) -> ControlSample | None:
+        for s in self._samples:
+            if s.id == sample_id:
+                return s
+        return None
+
+    def all_samples(self) -> list[ControlSample]:
+        return list(self._samples)
+
+    def count(self) -> int:
+        return len(self._samples)

algo_cli/intelligence/numeric_clamp.py

@@ -0,0 +1,63 @@
+"""H10 — Numeric Clamp Guard.
+
+Prevents impossible telemetry values by clamping to a valid range and
+recording warnings when out-of-range values are encountered.
+
+Source: GLOSSOPETRAE ``clampCheck()``.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class ClampWarning:
+    """Recorded when a value is clamped."""
+
+    original: float
+    clamped: float
+    lo: float
+    hi: float
+
+
+class NumericClampGuard:
+    """Clamp numeric values to [lo, hi] and record out-of-range events."""
+
+    def __init__(self, lo: float = 0.0, hi: float = 1.0) -> None:
+        if lo > hi:
+            raise ValueError(f"lo ({lo}) must be <= hi ({hi})")
+        self.lo = lo
+        self.hi = hi
+        self.warnings: list[ClampWarning] = []
+
+    def clamp(self, value: float) -> float:
+        """Clamp *value* to [lo, hi].  Records a warning if clamping occurred."""
+        if value < self.lo:
+            self.warnings.append(
+                ClampWarning(original=value, clamped=self.lo, lo=self.lo, hi=self.hi)
+            )
+            return self.lo
+        if value > self.hi:
+            self.warnings.append(
+                ClampWarning(original=value, clamped=self.hi, lo=self.lo, hi=self.hi)
+            )
+            return self.hi
+        return value
+
+    def clamp_many(self, values: list[float]) -> list[float]:
+        """Clamp a batch of values."""
+        return [self.clamp(v) for v in values]
+
+    def has_warnings(self) -> bool:
+        return len(self.warnings) > 0
+
+    def clear_warnings(self) -> None:
+        self.warnings.clear()
+
+    def stats(self) -> dict:
+        return {
+            "lo": self.lo,
+            "hi": self.hi,
+            "warnings": len(self.warnings),
+            "clamped_count": len(self.warnings),
+        }

algo_cli/intelligence/occ_editor.py

@@ -0,0 +1,66 @@
+"""B80. Optimistic Concurrency Control for Edits.
+
+SHA-256 version hashes prevent conflicting writes and stale-data overwrites.
+Source: Pathfinder pattern.
+"""
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass
+class WriteResult:
+    success: bool
+    version: str = ""
+    error: str = ""
+    current_version: str = ""
+    message: str = ""
+
+
+class OCCEditor:
+    """Optimistic concurrency control for file edits."""
+
+    def __init__(self) -> None:
+        self._versions: dict[str, str] = {}
+
+    def read(self, path: str) -> tuple[str, str]:
+        """Read file and return (content, version_hash)."""
+        content = Path(path).read_text(encoding="utf-8")
+        version = self._hash(content)
+        self._versions[path] = version
+        return content, version
+
+    def write(self, path: str, content: str, expected_version: str) -> WriteResult:
+        """Write with OCC — fails if file changed since read."""
+        try:
+            current = Path(path).read_text(encoding="utf-8")
+        except FileNotFoundError:
+            current = ""
+        current_version = self._hash(current)
+
+        if current_version != expected_version:
+            return WriteResult(
+                success=False,
+                error="VERSION_MISMATCH",
+                current_version=current_version,
+                message=f"File changed since you read it. Expected {expected_version[:8]}, got {current_version[:8]}.",
+            )
+
+        Path(path).write_text(content, encoding="utf-8")
+        new_version = self._hash(content)
+        self._versions[path] = new_version
+        return WriteResult(success=True, version=new_version)
+
+    def check_version(self, path: str, expected_version: str) -> bool:
+        """Check if file still matches expected version."""
+        try:
+            content = Path(path).read_text(encoding="utf-8")
+        except FileNotFoundError:
+            return False
+        return self._hash(content) == expected_version
+
+    @staticmethod
+    def _hash(content: str) -> str:
+        return hashlib.sha256(content.encode("utf-8")).hexdigest()

algo_cli/intelligence/output_normalize.py

@@ -0,0 +1,112 @@
+"""H22 — Sequential Output Normalization Pipeline.
+
+Toggleable pipeline stages for output normalization.
+Mined from G0DM0D3 PAPER.md §3.5 STM.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Callable
+
+
+@dataclass
+class PipelineStage:
+    """A single normalization stage."""
+
+    name: str
+    enabled: bool = True
+    transform: Callable[[str], str] = lambda x: x
+    description: str = ""
+
+
+class OutputNormalizationPipeline:
+    """Sequential pipeline of toggleable normalization stages."""
+
+    def __init__(self) -> None:
+        self._stages: list[PipelineStage] = []
+
+    def add_stage(
+        self,
+        name: str,
+        transform: Callable[[str], str],
+        enabled: bool = True,
+        description: str = "",
+    ) -> PipelineStage:
+        stage = PipelineStage(
+            name=name, enabled=enabled, transform=transform, description=description
+        )
+        self._stages.append(stage)
+        return stage
+
+    def enable(self, name: str) -> bool:
+        stage = self._find(name)
+        if stage is None:
+            return False
+        stage.enabled = True
+        return True
+
+    def disable(self, name: str) -> bool:
+        stage = self._find(name)
+        if stage is None:
+            return False
+        stage.enabled = False
+        return True
+
+    def _find(self, name: str) -> PipelineStage | None:
+        for s in self._stages:
+            if s.name == name:
+                return s
+        return None
+
+    def run(self, text: str) -> str:
+        """Run all enabled stages in sequence."""
+        result = text
+        for stage in self._stages:
+            if stage.enabled:
+                result = stage.transform(result)
+        return result
+
+    def get_stage_names(self) -> list[str]:
+        return [s.name for s in self._stages]
+
+    def get_enabled_stages(self) -> list[str]:
+        return [s.name for s in self._stages if s.enabled]
+
+    def count(self) -> int:
+        return len(self._stages)
+
+    def remove_stage(self, name: str) -> bool:
+        stage = self._find(name)
+        if stage is None:
+            return False
+        self._stages.remove(stage)
+        return True
+
+
+# Built-in transforms
+def hedge_reducer(text: str) -> str:
+    """Reduce hedging language."""
+    text = re.sub(r"\bI think\b", "", text, flags=re.IGNORECASE)
+    text = re.sub(r"\bmaybe\b", "", text, flags=re.IGNORECASE)
+    text = re.sub(r"\bperhaps\b", "", text, flags=re.IGNORECASE)
+    text = re.sub(r"\bpossibly\b", "", text, flags=re.IGNORECASE)
+    text = re.sub(r"\s+", " ", text)
+    return text.strip()
+
+
+def direct_mode(text: str) -> str:
+    """Convert indirect requests to direct."""
+    text = re.sub(r"\bCould you\b", "", text, flags=re.IGNORECASE)
+    text = re.sub(r"\bWould you\b", "", text, flags=re.IGNORECASE)
+    text = re.sub(r"\bCan you\b", "", text, flags=re.IGNORECASE)
+    text = re.sub(r"\s+", " ", text)
+    return text.strip()
+
+
+def casual_mode(text: str) -> str:
+    """Make output more casual."""
+    text = re.sub(r"\bTherefore\b", "So", text, flags=re.IGNORECASE)
+    text = re.sub(r"\bHowever\b", "But", text, flags=re.IGNORECASE)
+    text = re.sub(r"\s+", " ", text)
+    return text.strip()

algo_cli/intelligence/parallel_delegation.py

@@ -0,0 +1,98 @@
+"""B70. Parallel Delegation + Subject Hygiene.
+
+Launch 2-4 subagents simultaneously, each with a clear traceable subject.
+Source: awesome-agentic-patterns.
+"""
+from __future__ import annotations
+
+import time
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from dataclasses import dataclass
+from typing import Callable
+
+
+@dataclass
+class DelegatedTask:
+    subject: str  # clear, traceable identifier
+    description: str
+    agent_id: str = ""
+    priority: int = 5
+
+
+@dataclass
+class DelegationResult:
+    subject: str
+    output: str = ""
+    success: bool = True
+    error: str | None = None
+    duration_s: float = 0.0
+
+
+class ParallelDelegator:
+    """Delegate tasks to multiple agents in parallel with subject hygiene."""
+
+    def __init__(self, max_workers: int = 4) -> None:
+        self._max_workers = max_workers
+
+    def delegate_all(
+        self,
+        tasks: list[DelegatedTask],
+        run_fn: Callable[[DelegatedTask], str],
+    ) -> list[DelegationResult]:
+        """Run all tasks in parallel, wait for all to complete."""
+        results: list[DelegationResult] = []
+
+        with ThreadPoolExecutor(max_workers=self._max_workers) as pool:
+            future_to_task = {pool.submit(self._run, task, run_fn): task for task in tasks}
+            for future in as_completed(future_to_task):
+                results.append(future.result())
+
+        # Sort by original task order
+        subject_order = {t.subject: i for i, t in enumerate(tasks)}
+        results.sort(key=lambda r: subject_order.get(r.subject, 999))
+        return results
+
+    def delegate_race(
+        self,
+        tasks: list[DelegatedTask],
+        run_fn: Callable[[DelegatedTask], str],
+    ) -> DelegationResult | None:
+        """Run tasks in parallel, return first successful result."""
+        with ThreadPoolExecutor(max_workers=self._max_workers) as pool:
+            futures = {pool.submit(self._run, task, run_fn): task for task in tasks}
+            for future in as_completed(futures):
+                result = future.result()
+                if result.success:
+                    # Cancel remaining
+                    for f in futures:
+                        f.cancel()
+                    return result
+        return None
+
+    def _run(self, task: DelegatedTask, run_fn: Callable[[DelegatedTask], str]) -> DelegationResult:
+        start = time.time()
+        try:
+            output = run_fn(task)
+            return DelegationResult(
+                subject=task.subject, output=output,
+                duration_s=time.time() - start,
+            )
+        except Exception as e:
+            return DelegationResult(
+                subject=task.subject, success=False, error=str(e),
+                duration_s=time.time() - start,
+            )
+
+    @staticmethod
+    def validate_subjects(tasks: list[DelegatedTask]) -> list[str]:
+        """Ensure subjects are unique and descriptive. Return issues."""
+        issues: list[str] = []
+        subjects = [t.subject for t in tasks]
+        if len(set(subjects)) != len(subjects):
+            issues.append("Duplicate subjects found")
+        for t in tasks:
+            if len(t.subject) < 3:
+                issues.append(f"Subject too short: '{t.subject}'")
+            if len(t.description) < 10:
+                issues.append(f"Description too short for '{t.subject}'")
+        return issues