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

algo_cli/intelligence/flow_dag.py

@@ -0,0 +1,267 @@
+"""B35. Declarative LLM Flow DAG + Evaluation Harness (PromptFlow Pattern).
+
+Parses YAML-like flow definitions into a DAG of nodes, executes them in
+topological order, and runs evaluation checks against the outputs.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable
+from collections import defaultdict
+
+
+class FlowError(Exception):
+    pass
+
+
+@dataclass
+class FlowNode:
+    id: str
+    kind: str  # "tool", "llm", "python"
+    tool: str | None = None
+    llm: str | None = None
+    prompt: str | None = None
+    inputs: dict[str, Any] = field(default_factory=dict)
+    source_code: str | None = None
+
+
+@dataclass
+class FlowEval:
+    name: str
+    kind: str  # "assert_contains", "assert_not_empty", "custom"
+    expected: Any = None
+    check_fn: Callable[[str], bool] | None = None
+
+
+@dataclass
+class FlowDefinition:
+    name: str
+    inputs: dict[str, Any] = field(default_factory=dict)
+    nodes: list[FlowNode] = field(default_factory=list)
+    outputs: dict[str, str] = field(default_factory=dict)
+    evals: list[FlowEval] = field(default_factory=list)
+
+
+@dataclass
+class FlowTrace:
+    node_id: str
+    inputs: dict[str, Any]
+    output: str
+    duration_ms: float = 0.0
+    error: str | None = None
+
+
+@dataclass
+class FlowResult:
+    outputs: dict[str, Any]
+    traces: list[FlowTrace] = field(default_factory=list)
+    eval_results: dict[str, bool] = field(default_factory=dict)
+    success: bool = True
+
+
+# ── parser ────────────────────────────────────────────────────────────
+
+
+def parse_flow(data: dict) -> FlowDefinition:
+    """Parse a dict (from YAML/JSON) into a FlowDefinition."""
+    name = data.get("name", "unnamed")
+    inputs = data.get("inputs", {})
+    nodes = []
+    for nd in data.get("nodes", []):
+        nodes.append(FlowNode(
+            id=nd["id"],
+            kind=nd.get("kind", "tool"),
+            tool=nd.get("tool"),
+            llm=nd.get("llm"),
+            prompt=nd.get("prompt"),
+            inputs=nd.get("inputs", {}),
+            source_code=nd.get("source"),
+        ))
+    outputs = data.get("outputs", {})
+    evals = []
+    for ev in data.get("evals", []):
+        evals.append(FlowEval(
+            name=ev["name"],
+            kind=ev.get("kind", "assert_contains"),
+            expected=ev.get("expected"),
+            check_fn=ev.get("check_fn"),
+        ))
+    return FlowDefinition(name=name, inputs=inputs, nodes=nodes, outputs=outputs, evals=evals)
+
+
+# ── DAG validation ────────────────────────────────────────────────────
+
+
+def _build_adjacency(flow: FlowDefinition) -> tuple[dict[str, list[str]], dict[str, int]]:
+    """Build adjacency list and in-degree map from ${node.output} references."""
+    adj: dict[str, list[str]] = defaultdict(list)
+    in_deg: dict[str, int] = defaultdict(int)
+    node_ids = {n.id for n in flow.nodes}
+    for n in flow.nodes:
+        in_deg.setdefault(n.id, 0)
+        for val in n.inputs.values():
+            if isinstance(val, str) and "${" in val:
+                ref = _extract_ref(val)
+                if ref and ref in node_ids:
+                    adj[ref].append(n.id)
+                    in_deg[n.id] += 1
+    return adj, in_deg
+
+
+def _extract_ref(expr: str) -> str | None:
+    """Extract node id from ${node_id.field} or ${node_id}."""
+    if "${" not in expr:
+        return None
+    start = expr.index("${") + 2
+    end = expr.index("}", start)
+    ref = expr[start:end]
+    # strip field accessor
+    return ref.split(".")[0]
+
+
+def detect_cycles(flow: FlowDefinition) -> list[str] | None:
+    """Return cycle path if found, else None."""
+    adj, in_deg = _build_adjacency(flow)
+    # Kahn's algorithm
+    queue = [nid for nid, d in in_deg.items() if d == 0]
+    visited = 0
+    while queue:
+        nid = queue.pop(0)
+        visited += 1
+        for nxt in adj[nid]:
+            in_deg[nxt] -= 1
+            if in_deg[nxt] == 0:
+                queue.append(nxt)
+    if visited != len(in_deg):
+        # find a cycle path via DFS
+        return _find_cycle_dfs(adj, set(in_deg.keys()))
+    return None
+
+
+def _find_cycle_dfs(adj: dict[str, list[str]], nodes: set[str]) -> list[str]:
+    visited: set[str] = set()
+    stack: list[str] = []
+    on_stack: set[str] = set()
+
+    def dfs(u: str) -> list[str] | None:
+        visited.add(u)
+        stack.append(u)
+        on_stack.add(u)
+        for v in adj.get(u, []):
+            if v not in visited:
+                result = dfs(v)
+                if result:
+                    return result
+            elif v in on_stack:
+                idx = stack.index(v)
+                return stack[idx:] + [v]
+        stack.pop()
+        on_stack.discard(u)
+        return None
+
+    for n in nodes:
+        if n not in visited:
+            result = dfs(n)
+            if result:
+                return result
+    return []
+
+
+def topological_sort(flow: FlowDefinition) -> list[str]:
+    """Return node ids in execution order."""
+    cycle = detect_cycles(flow)
+    if cycle:
+        raise FlowError(f"Cycle detected: {' -> '.join(cycle)}")
+    adj, in_deg = _build_adjacency(flow)
+    queue = sorted([nid for nid, d in in_deg.items() if d == 0])
+    order: list[str] = []
+    while queue:
+        nid = queue.pop(0)
+        order.append(nid)
+        nexts = sorted(adj[nid])
+        for nxt in nexts:
+            in_deg[nxt] -= 1
+            if in_deg[nxt] == 0:
+                queue.append(nxt)
+    return order
+
+
+# ── executor ──────────────────────────────────────────────────────────
+
+
+def _resolve_value(expr: Any, context: dict[str, Any]) -> Any:
+    """Resolve ${node.field} references from context."""
+    if not isinstance(expr, str) or "${" not in expr:
+        return expr
+    start = expr.index("${") + 2
+    end = expr.index("}", start)
+    ref = expr[start:end]
+    parts = ref.split(".")
+    val = context
+    for p in parts:
+        if isinstance(val, dict):
+            val = val.get(p)
+        else:
+            val = getattr(val, p, None)
+    # replace in string
+    return expr.replace(f"${{{ref}}}", str(val)) if isinstance(val, (str, int, float)) else val
+
+
+class FlowExecutor:
+    """Executes a FlowDefinition with pluggable tool/llm handlers."""
+
+    def __init__(
+        self,
+        tool_handler: Callable[[str, dict], str] | None = None,
+        llm_handler: Callable[[str, str, dict], str] | None = None,
+    ):
+        self.tool_handler = tool_handler or (lambda tool, inputs: f"[tool:{tool}]")
+        self.llm_handler = llm_handler or (lambda model, prompt, inputs: f"[llm:{model}]")
+
+    def run(self, flow: FlowDefinition, inputs: dict[str, Any] | None = None) -> FlowResult:
+        context: dict[str, Any] = dict(flow.inputs)
+        if inputs:
+            context.update(inputs)
+        traces: list[FlowTrace] = []
+        order = topological_sort(flow)
+        node_map = {n.id: n for n in flow.nodes}
+        for nid in order:
+            node = node_map[nid]
+            resolved = {k: _resolve_value(v, context) for k, v in node.inputs.items()}
+            try:
+                if node.kind == "tool":
+                    output = self.tool_handler(node.tool or "", resolved)
+                elif node.kind == "llm":
+                    output = self.llm_handler(node.llm or "", node.prompt or "", resolved)
+                elif node.kind == "python":
+                    output = self._run_python(node.source_code or "", resolved)
+                else:
+                    output = ""
+                context[nid] = {**resolved, "text": output}
+                traces.append(FlowTrace(node_id=nid, inputs=resolved, output=output))
+            except Exception as e:
+                context[nid] = {"text": "", "error": str(e)}
+                traces.append(FlowTrace(node_id=nid, inputs=resolved, output="", error=str(e)))
+        # resolve outputs
+        outputs = {k: _resolve_value(v, context) for k, v in flow.outputs.items()}
+        # run evals
+        eval_results: dict[str, bool] = {}
+        for ev in flow.evals:
+            text = str(outputs.get(ev.name, ""))
+            if ev.kind == "assert_contains":
+                eval_results[ev.name] = str(ev.expected) in text
+            elif ev.kind == "assert_not_empty":
+                eval_results[ev.name] = bool(text.strip())
+            elif ev.kind == "custom" and ev.check_fn:
+                eval_results[ev.name] = ev.check_fn(text)
+            else:
+                eval_results[ev.name] = False
+        success = all(eval_results.values()) if eval_results else True
+        return FlowResult(outputs=outputs, traces=traces, eval_results=eval_results, success=success)
+
+    @staticmethod
+    def _run_python(source: str, inputs: dict) -> str:
+        local_ns = dict(inputs)
+        exec(source, {}, local_ns)
+        return str(local_ns.get("result", ""))

algo_cli/intelligence/gatherer.py

@@ -0,0 +1,223 @@
+"""Gatherer State Machine — priority queue with retry and transactional state.
+
+Borrowed from Windows Search gatherer
+(C:\\ProgramData\\Microsoft\\Search\\Data\\Applications\\Windows\\Windows-gather.db,
+SystemIndex_Gthr table):
+The Windows Search gatherer tracks per-document crawl state including:
+  - Priority (0-255, UNSIGNEDBYTE)
+  - FailureUpdateAttempts (retry count with exponential backoff)
+  - CrawlNumberCrawled (version counter)
+  - TransactionFlags (in-progress, committed, rolled-back, retry-pending)
+  - LastRequestedRunTime (prevents re-scheduling)
+
+This module implements the same pattern for the harness embedding/indexing
+pipeline: files are enqueued with priority, processed in batches, retried on
+failure with exponential backoff, and tracked with transactional state.
+
+Pattern: B31 in ALGO.md.
+"""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from enum import IntFlag
+from typing import Any, Callable
+
+
+class TransactionFlags(IntFlag):
+    NONE = 0
+    IN_PROGRESS = 1
+    COMMITTED = 2
+    ROLLED_BACK = 4
+    RETRY_PENDING = 8
+
+
+@dataclass
+class GathererEntry:
+    """A single item in the gatherer queue."""
+    path: str
+    priority: int = 5  # 0=highest, 255=lowest
+    failure_attempts: int = 0
+    crawl_number: int = 0
+    last_requested_run: float = 0.0
+    last_modified: float = 0.0
+    transaction_flags: TransactionFlags = TransactionFlags.NONE
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    MAX_ATTEMPTS: int = 3
+
+    def should_retry(self) -> bool:
+        return self.failure_attempts < self.MAX_ATTEMPTS
+
+    def next_retry_delay(self) -> float:
+        """Exponential backoff: 1s, 2s, 4s, 8s... capped at 300s."""
+        return min(2 ** self.failure_attempts, 300)
+
+    def priority_score(self) -> float:
+        """Higher = more urgent. Combines static priority + staleness."""
+        staleness = time.time() - self.last_modified if self.last_modified else 0
+        return (255 - self.priority) * 100 + min(staleness / 3600, 100)
+
+    def is_in_progress(self) -> bool:
+        return bool(self.transaction_flags & TransactionFlags.IN_PROGRESS)
+
+    def is_committed(self) -> bool:
+        return bool(self.transaction_flags & TransactionFlags.COMMITTED)
+
+    def is_rolled_back(self) -> bool:
+        return bool(self.transaction_flags & TransactionFlags.ROLLED_BACK)
+
+
+class GathererQueue:
+    """Priority queue with retry, backoff, and transactional state.
+
+    Usage:
+        queue = GathererQueue()
+        queue.enqueue(GathererEntry(path="foo.py", priority=3))
+        batch = queue.next_batch(batch_size=50)
+        for entry in batch:
+            queue.mark_in_progress(entry)
+            try:
+                embed_file(entry.path)
+                queue.mark_success(entry)
+            except Exception:
+                queue.mark_failure(entry)
+    """
+
+    def __init__(self) -> None:
+        self.entries: dict[str, GathererEntry] = {}
+
+    # --- enqueue / dequeue ------------------------------------------------
+
+    def enqueue(self, entry: GathererEntry) -> None:
+        """Add or update an entry in the queue."""
+        existing = self.entries.get(entry.path)
+        if existing:
+            # Preserve retry count and crawl number on re-enqueue
+            entry.failure_attempts = existing.failure_attempts
+            entry.crawl_number = existing.crawl_number
+        self.entries[entry.path] = entry
+
+    def enqueue_many(self, paths: list[str], priority: int = 5) -> None:
+        """Bulk enqueue with uniform priority."""
+        for path in paths:
+            self.enqueue(GathererEntry(path=path, priority=priority))
+
+    # --- batch selection --------------------------------------------------
+
+    def next_batch(
+        self, batch_size: int = 50, *, respect_backoff: bool = True,
+    ) -> list[GathererEntry]:
+        """Get next batch sorted by priority score (descending).
+
+        Filters out:
+        - In-progress entries (already being processed)
+        - Entries that exceeded max retry attempts (rolled back)
+        - Entries whose retry delay hasn't elapsed (unless respect_backoff=False)
+        """
+        now = time.time()
+        eligible: list[GathererEntry] = []
+        for entry in self.entries.values():
+            if entry.is_in_progress():
+                continue
+            if entry.is_rolled_back():
+                continue
+            if not entry.should_retry():
+                continue
+            # Check retry backoff delay
+            if respect_backoff and (entry.transaction_flags & TransactionFlags.RETRY_PENDING):
+                if now - entry.last_requested_run < entry.next_retry_delay():
+                    continue
+            eligible.append(entry)
+
+        eligible.sort(key=lambda e: e.priority_score(), reverse=True)
+        return eligible[:batch_size]
+
+    # --- state transitions ------------------------------------------------
+
+    def mark_in_progress(self, entry: GathererEntry) -> None:
+        entry.transaction_flags = TransactionFlags.IN_PROGRESS
+        entry.last_requested_run = time.time()
+
+    def mark_success(self, entry: GathererEntry) -> None:
+        entry.transaction_flags = TransactionFlags.COMMITTED
+        entry.failure_attempts = 0
+        entry.crawl_number += 1
+
+    def mark_failure(self, entry: GathererEntry) -> None:
+        entry.failure_attempts += 1
+        if entry.should_retry():
+            entry.transaction_flags = TransactionFlags.RETRY_PENDING
+        else:
+            entry.transaction_flags = TransactionFlags.ROLLED_BACK
+
+    def remove(self, path: str) -> None:
+        """Remove a completed entry from the queue."""
+        self.entries.pop(path, None)
+
+    # --- queries ----------------------------------------------------------
+
+    def pending_count(self) -> int:
+        """Number of entries not yet committed or rolled back."""
+        return sum(
+            1 for e in self.entries.values()
+            if not e.is_committed() and not e.is_rolled_back()
+        )
+
+    def committed_count(self) -> int:
+        return sum(1 for e in self.entries.values() if e.is_committed())
+
+    def failed_count(self) -> int:
+        return sum(1 for e in self.entries.values() if e.is_rolled_back())
+
+    def retry_count(self) -> int:
+        return sum(
+            1 for e in self.entries.values()
+            if e.transaction_flags & TransactionFlags.RETRY_PENDING
+        )
+
+    def stats(self) -> dict[str, int]:
+        return {
+            "total": len(self.entries),
+            "pending": self.pending_count(),
+            "committed": self.committed_count(),
+            "failed": self.failed_count(),
+            "retry": self.retry_count(),
+        }
+
+    # --- processing loop --------------------------------------------------
+
+    def process(
+        self,
+        processor: Callable[[GathererEntry], Any],
+        *,
+        batch_size: int = 50,
+        max_rounds: int = 100,
+        respect_backoff: bool = True,
+    ) -> dict[str, int]:
+        """Process the queue until empty or max_rounds reached.
+
+        Args:
+            processor: Function that takes a GathererEntry and processes it.
+                       Raises on failure.
+            batch_size: Max entries per batch.
+            max_rounds: Safety limit to prevent infinite loops.
+            respect_backoff: If False, skip retry backoff delay (for sync loops).
+
+        Returns:
+            Stats dict with committed/failed/retry counts.
+        """
+        rounds = 0
+        while rounds < max_rounds:
+            batch = self.next_batch(batch_size, respect_backoff=respect_backoff)
+            if not batch:
+                break
+            for entry in batch:
+                self.mark_in_progress(entry)
+                try:
+                    processor(entry)
+                    self.mark_success(entry)
+                except Exception:
+                    self.mark_failure(entry)
+            rounds += 1
+        return self.stats()

algo_cli/intelligence/golden_master.py

@@ -0,0 +1,98 @@
+"""B82. Golden Master: Characterization Tests.
+
+Capture current behavior before refactoring.  Verify no regressions after.
+Source: CCASP pattern.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable
+
+
+@dataclass
+class GoldenMaster:
+    name: str
+    inputs: list[Any] = field(default_factory=list)
+    expected_outputs: list[Any] = field(default_factory=list)
+    snapshots: dict[str, str] = field(default_factory=dict)  # input_hash → output_hash
+
+    def capture(self, input_data: Any, output: Any) -> None:
+        """Capture a golden master snapshot."""
+        input_hash = self._hash(input_data)
+        output_hash = self._hash(output)
+        self.inputs.append(input_data)
+        self.expected_outputs.append(output)
+        self.snapshots[input_hash] = output_hash
+
+    def verify(self, input_data: Any, output: Any) -> bool:
+        """Verify output matches golden master."""
+        input_hash = self._hash(input_data)
+        output_hash = self._hash(output)
+        return self.snapshots.get(input_hash) == output_hash
+
+    def verify_all(self, run_fn: Callable[[Any], Any]) -> list[bool]:
+        """Verify all captured inputs against current behavior."""
+        results: list[bool] = []
+        for input_data, expected in zip(self.inputs, self.expected_outputs):
+            actual = run_fn(input_data)
+            results.append(self.verify(input_data, actual))
+        return results
+
+    @staticmethod
+    def _hash(data: Any) -> str:
+        if isinstance(data, str):
+            return hashlib.sha256(data.encode()).hexdigest()[:16]
+        return hashlib.sha256(json.dumps(data, default=str, sort_keys=True).encode()).hexdigest()[:16]
+
+    def save(self, path: Path) -> None:
+        """Save golden master to file."""
+        path.write_text(json.dumps({
+            "name": self.name,
+            "snapshots": self.snapshots,
+        }, indent=2), encoding="utf-8")
+
+    @classmethod
+    def load(cls, path: Path) -> "GoldenMaster":
+        """Load golden master from file."""
+        data = json.loads(path.read_text(encoding="utf-8"))
+        gm = cls(name=data["name"])
+        gm.snapshots = data.get("snapshots", {})
+        return gm
+
+
+class GoldenMasterRunner:
+    """Run golden master characterization tests."""
+
+    def __init__(self) -> None:
+        self._masters: dict[str, GoldenMaster] = {}
+
+    def create(self, name: str) -> GoldenMaster:
+        gm = GoldenMaster(name=name)
+        self._masters[name] = gm
+        return gm
+
+    def get(self, name: str) -> GoldenMaster | None:
+        return self._masters.get(name)
+
+    def run_all(self, run_fn: Callable[[Any], Any]) -> dict[str, list[bool]]:
+        """Run all golden masters against current behavior."""
+        return {name: gm.verify_all(run_fn) for name, gm in self._masters.items()}
+
+    def regression_report(self, run_fn: Callable[[Any], Any]) -> str:
+        """Generate a report of any regressions."""
+        lines: list[str] = ["Golden Master Regression Report", ""]
+        all_pass = True
+        for name, gm in self._masters.items():
+            results = gm.verify_all(run_fn)
+            passed = sum(results)
+            total = len(results)
+            status = "PASS" if passed == total else "FAIL"
+            if passed != total:
+                all_pass = False
+            lines.append(f"  {name}: {passed}/{total} — {status}")
+        lines.append("")
+        lines.append("ALL PASS" if all_pass else "REGRESSIONS DETECTED")
+        return "\n".join(lines)