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

algo_cli/intelligence/parallel_fanout.py

@@ -0,0 +1,104 @@
+"""B65. Multi-Source Parallel Fan-Out.
+
+N questions × M sources = NM parallel tasks.
+Source: deep-research-agent pattern.
+"""
+from __future__ import annotations
+
+import time
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from dataclasses import dataclass, field
+from typing import Callable
+
+
+@dataclass
+class FanOutTask:
+    question: str
+    source: str  # "web", "github", "arxiv", "local"
+    query: str
+    priority: int = 5
+
+
+@dataclass
+class FanOutResult:
+    question: str
+    source: str
+    query: str
+    results: list[tuple[str, str]] = field(default_factory=list)  # (title, content)
+    duration_s: float = 0.0
+    error: str | None = None
+    success: bool = True
+
+
+class ParallelFanOut:
+    """Execute N questions × M sources in parallel."""
+
+    def __init__(self, max_workers: int = 4, timeout: float = 30.0) -> None:
+        self._max_workers = max_workers
+        self._timeout = timeout
+        self._source_handlers: dict[str, Callable[[str], list[tuple[str, str]]]] = {}
+
+    def register_source(self, name: str,
+                        handler: Callable[[str], list[tuple[str, str]]]) -> None:
+        self._source_handlers[name] = handler
+
+    def fan_out(self, questions: list[str], sources: list[str]) -> list[FanOutResult]:
+        """Run all question×source combinations in parallel."""
+        tasks: list[FanOutTask] = []
+        for q in questions:
+            for src in sources:
+                tasks.append(FanOutTask(question=q, source=src, query=q))
+
+        return self._execute(tasks)
+
+    def _execute(self, tasks: list[FanOutTask]) -> list[FanOutResult]:
+        results: list[FanOutResult] = []
+
+        with ThreadPoolExecutor(max_workers=self._max_workers) as pool:
+            future_to_task = {
+                pool.submit(self._run_task, task): task for task in tasks
+            }
+            for future in as_completed(future_to_task, timeout=self._timeout):
+                task = future_to_task[future]
+                try:
+                    results.append(future.result())
+                except Exception as e:
+                    results.append(FanOutResult(
+                        question=task.question, source=task.source,
+                        query=task.query, error=str(e), success=False,
+                    ))
+
+        return results
+
+    def _run_task(self, task: FanOutTask) -> FanOutResult:
+        handler = self._source_handlers.get(task.source)
+        if not handler:
+            return FanOutResult(
+                question=task.question, source=task.source,
+                query=task.query, error=f"No handler for source '{task.source}'",
+                success=False,
+            )
+        start = time.time()
+        try:
+            results = handler(task.query)
+            return FanOutResult(
+                question=task.question, source=task.source,
+                query=task.query, results=results,
+                duration_s=time.time() - start,
+            )
+        except Exception as e:
+            return FanOutResult(
+                question=task.question, source=task.source,
+                query=task.query, error=str(e), success=False,
+                duration_s=time.time() - start,
+            )
+
+    def merge_results(self, results: list[FanOutResult]) -> dict[str, list[tuple[str, str, str]]]:
+        """Merge results by question: {question: [(source, title, content), ...]}"""
+        merged: dict[str, list[tuple[str, str, str]]] = {}
+        for r in results:
+            if not r.success:
+                continue
+            for title, content in r.results:
+                merged.setdefault(r.question, []).append((r.source, title, content))
+        return merged

algo_cli/intelligence/permission_modes.py

@@ -0,0 +1,105 @@
+"""B51. Declarative Permission Modes + Structural Spawn Safety.
+
+Config-level tool sets and path restrictions.  Prevent permission
+escalation structurally.  Source: aloop pattern.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum, auto
+
+
+class PermissionLevel(Enum):
+    READ_ONLY = auto()
+    STANDARD = auto()
+    ELEVATED = auto()
+    UNRESTRICTED = auto()
+
+
+# Tool sets per permission level
+DEFAULT_TOOL_SETS: dict[PermissionLevel, set[str]] = {
+    PermissionLevel.READ_ONLY: {
+        "read_file", "search_files", "list_directory", "harness_search",
+        "harness_read", "web_search", "web_fetch", "read_pdf",
+    },
+    PermissionLevel.STANDARD: {
+        "read_file", "search_files", "list_directory", "write_file",
+        "edit_file", "run_shell", "harness_search", "harness_read",
+        "web_search", "web_fetch", "read_pdf", "embed_text",
+    },
+    PermissionLevel.ELEVATED: {
+        "read_file", "search_files", "list_directory", "write_file",
+        "edit_file", "run_shell", "harness_search", "harness_read",
+        "web_search", "web_fetch", "read_pdf", "embed_text",
+        "model_create", "model_delete", "git_status", "git_diff",
+    },
+    PermissionLevel.UNRESTRICTED: {"*"},
+}
+
+# Which levels can spawn which levels (prevent escalation)
+SPAWN_MATRIX: dict[PermissionLevel, set[PermissionLevel]] = {
+    PermissionLevel.READ_ONLY: set(),
+    PermissionLevel.STANDARD: {PermissionLevel.READ_ONLY},
+    PermissionLevel.ELEVATED: {PermissionLevel.READ_ONLY, PermissionLevel.STANDARD},
+    PermissionLevel.UNRESTRICTED: {
+        PermissionLevel.READ_ONLY, PermissionLevel.STANDARD,
+        PermissionLevel.ELEVATED, PermissionLevel.UNRESTRICTED,
+    },
+}
+
+
+@dataclass
+class PermissionMode:
+    level: PermissionLevel
+    allowed_tools: set[str] = field(default_factory=set)
+    allowed_paths: list[str] = field(default_factory=list)  # glob patterns
+    denied_paths: list[str] = field(default_factory=list)
+    spawnable_modes: set[PermissionLevel] = field(default_factory=set)
+
+    def __post_init__(self) -> None:
+        if not self.allowed_tools:
+            self.allowed_tools = DEFAULT_TOOL_SETS.get(self.level, set()).copy()
+        if not self.spawnable_modes:
+            self.spawnable_modes = SPAWN_MATRIX.get(self.level, set()).copy()
+
+    def can_use_tool(self, tool_name: str) -> bool:
+        return "*" in self.allowed_tools or tool_name in self.allowed_tools
+
+    def can_access_path(self, path: str) -> bool:
+        import fnmatch
+        for denied in self.denied_paths:
+            if fnmatch.fnmatch(path, denied):
+                return False
+        if not self.allowed_paths:
+            return True
+        return any(fnmatch.fnmatch(path, p) for p in self.allowed_paths)
+
+    def can_spawn(self, target_level: PermissionLevel) -> bool:
+        return target_level in self.spawnable_modes
+
+
+class PermissionManager:
+    """Manage permission modes and enforce structural spawn safety."""
+
+    def __init__(self, default_level: PermissionLevel = PermissionLevel.STANDARD) -> None:
+        self._modes: dict[str, PermissionMode] = {}
+        self._default = PermissionMode(level=default_level)
+
+    def register(self, name: str, mode: PermissionMode) -> None:
+        self._modes[name] = mode
+
+    def get(self, name: str | None) -> PermissionMode:
+        if name and name in self._modes:
+            return self._modes[name]
+        return self._default
+
+    def validate_spawn(
+        self,
+        parent_name: str | None,
+        child_level: PermissionLevel,
+    ) -> bool:
+        parent = self.get(parent_name)
+        return parent.can_spawn(child_level)
+
+    def list_modes(self) -> dict[str, PermissionMode]:
+        return dict(self._modes)

algo_cli/intelligence/pre_push_gate.py

@@ -0,0 +1,68 @@
+"""H32 — Pre-Push Scrubbing Gate.
+
+Hard-blocks raw pushes of private working tree; requires explicit env var
+override.  Mirrors T3MP3ST ``.githooks/pre-push`` pattern.
+
+Source: T3MP3ST ``.githooks/pre-push``.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Optional
+
+
+@dataclass(frozen=True)
+class GateResult:
+    """Result of a pre-push gate check."""
+
+    allowed: bool
+    reason: str
+    override_used: bool
+
+
+class PrePushGate:
+    """Gate that blocks pushes unless an override env var is set."""
+
+    def __init__(self, override_env_var: str = "ALGO_ALLOW_RAW_PUSH") -> None:
+        self.override_env_var = override_env_var
+
+    def check(
+        self,
+        env_getter: Callable[[str], Optional[str]] = lambda _k: None,
+        allow_override: bool = False,
+    ) -> GateResult:
+        """Check whether a push should be allowed.
+
+        Args:
+            env_getter: Function that returns env var values (defaults to None).
+            allow_override: If True, skip the env var check entirely.
+
+        Returns:
+            GateResult with allowed=True if push should proceed.
+        """
+        if allow_override:
+            return GateResult(
+                allowed=True,
+                reason="Override explicitly granted by caller.",
+                override_used=True,
+            )
+        env_value = env_getter(self.override_env_var)
+        if env_value and env_value.lower() in ("1", "true", "yes"):
+            return GateResult(
+                allowed=True,
+                reason=f"Override env var {self.override_env_var} is set.",
+                override_used=True,
+            )
+        return GateResult(
+            allowed=False,
+            reason=(
+                f"Raw push blocked. Set {self.override_env_var}=1 to override, "
+                "or use a scrubbed export path."
+            ),
+            override_used=False,
+        )
+
+    def require_override(self, env_getter: Callable[[str], Optional[str]] = lambda _k: None) -> bool:
+        """Return True if an override is required to push."""
+        result = self.check(env_getter=env_getter)
+        return not result.allowed

algo_cli/intelligence/prefetch.py

@@ -0,0 +1,171 @@
+"""Content Prefetch — predictive cache warming via transition matrix.
+
+Borrowed from Windows.Networking.BackgroundTransfer.ContentPrefetchTask.dll:
+Windows allows apps to register prefetch tasks that run before the user opens
+the app — warming the cache with content the user is likely to request.
+
+This module learns access patterns ("after reading X, user usually reads Y")
+and pre-loads predicted files into an LRU cache before they're requested.
+
+Pattern: B33 in ALGO.md.
+"""
+from __future__ import annotations
+
+import time
+from collections import Counter, OrderedDict
+from dataclasses import dataclass
+from typing import Any, Callable
+
+
+@dataclass
+class AccessRecord:
+    """A single file access record."""
+    path: str
+    timestamp: float
+    action: str = "read"
+
+
+class PredictivePrefetch:
+    """Predict next likely accesses based on temporal transition patterns.
+
+    Usage:
+        cache = PredictivePrefetch(max_cache=32)
+        content = cache.get("foo.py", loader=read_file)
+        # cache learns: after foo.py, user often reads test_foo.py
+        # next time foo.py is read, test_foo.py is pre-warmed
+    """
+
+    def __init__(self, max_cache: int = 32, max_history: int = 1000):
+        self.max_cache = max_cache
+        self.max_history = max_history
+        self.access_history: list[AccessRecord] = []
+        self.prefetch_cache: OrderedDict[str, Any] = OrderedDict()
+        self.transition_counts: Counter = Counter()
+        # Per-path access frequency (for cold-start predictions)
+        self.access_frequency: Counter = Counter()
+
+    # --- learning ---------------------------------------------------------
+
+    def record_access(self, path: str, action: str = "read") -> None:
+        """Record a file access for pattern learning."""
+        now = time.time()
+        # Learn transition: previous access → this access
+        if self.access_history:
+            prev = self.access_history[-1]
+            key = f"{prev.path}|{prev.action}->{path}|{action}"
+            self.transition_counts[key] += 1
+        self.access_history.append(AccessRecord(path, now, action))
+        self.access_frequency[path] += 1
+        # Bound history
+        if len(self.access_history) > self.max_history:
+            self.access_history = self.access_history[-self.max_history // 2 :]
+
+    # --- prediction -------------------------------------------------------
+
+    def predict_next(self, current_path: str, action: str = "read") -> list[str]:
+        """Predict likely next accesses given current access.
+
+        Returns paths sorted by transition probability (descending).
+        """
+        candidates: Counter = Counter()
+        prefix = f"{current_path}|{action}->"
+        for key, count in self.transition_counts.items():
+            if key.startswith(prefix):
+                suffix = key[len(prefix):]
+                next_path = suffix.split("|")[0]
+                candidates[next_path] = count
+
+        # If no transitions learned, fall back to most-accessed paths
+        if not candidates:
+            for path, freq in self.access_frequency.most_common(self.max_cache):
+                if path != current_path:
+                    candidates[path] = freq
+
+        return [p for p, _ in candidates.most_common(self.max_cache)]
+
+    # --- cache management -------------------------------------------------
+
+    def warm_cache(self, paths: list[str], loader: Callable[[str], Any]) -> int:
+        """Pre-load predicted paths into cache. Returns number warmed."""
+        warmed = 0
+        for path in paths:
+            if path not in self.prefetch_cache:
+                try:
+                    self.prefetch_cache[path] = loader(path)
+                    warmed += 1
+                except Exception:
+                    pass  # prefetch failures are silent (best-effort)
+        self._evict()
+        return warmed
+
+    def prefetch_for(self, current_path: str, loader: Callable[[str], Any]) -> int:
+        """Predict and warm cache for likely-next accesses."""
+        predicted = self.predict_next(current_path)
+        return self.warm_cache(predicted, loader)
+
+    def get(self, path: str, loader: Callable[[str], Any]) -> Any:
+        """Get from cache or load on miss. Records access for learning."""
+        if path in self.prefetch_cache:
+            self.prefetch_cache.move_to_end(path)
+            self.record_access(path, "read")
+            return self.prefetch_cache[path]
+        result = loader(path)
+        self.prefetch_cache[path] = result
+        self.record_access(path, "read")
+        self._evict()
+        # After loading, prefetch likely-next files in background
+        # (caller can call prefetch_for explicitly for async warming)
+        return result
+
+    def _evict(self) -> None:
+        """Evict oldest entries if over capacity (LRU)."""
+        while len(self.prefetch_cache) > self.max_cache:
+            self.prefetch_cache.popitem(last=False)
+
+    # --- queries ----------------------------------------------------------
+
+    def cache_size(self) -> int:
+        return len(self.prefetch_cache)
+
+    def cache_hit_rate(self) -> float:
+        """Calculate cache hit rate from access history."""
+        if not self.access_history:
+            return 0.0
+        hits = sum(
+            1 for rec in self.access_history
+            if rec.path in self.prefetch_cache
+        )
+        return hits / len(self.access_history)
+
+    def cached_paths(self) -> list[str]:
+        return list(self.prefetch_cache.keys())
+
+    def stats(self) -> dict[str, Any]:
+        return {
+            "cache_size": self.cache_size(),
+            "cache_capacity": self.max_cache,
+            "history_size": len(self.access_history),
+            "transitions_learned": len(self.transition_counts),
+            "unique_paths_accessed": len(self.access_frequency),
+            "cache_hit_rate": round(self.cache_hit_rate(), 3),
+        }
+
+    # --- persistence ------------------------------------------------------
+
+    def export_transitions(self) -> dict[str, int]:
+        """Export transition counts for persistence/analysis."""
+        return dict(self.transition_counts)
+
+    def import_transitions(self, data: dict[str, int]) -> None:
+        """Import previously learned transition counts."""
+        for key, count in data.items():
+            self.transition_counts[key] += count
+
+    def export_frequency(self) -> dict[str, int]:
+        """Export access frequency for persistence."""
+        return dict(self.access_frequency)
+
+    def import_frequency(self, data: dict[str, int]) -> None:
+        """Import previously learned access frequency."""
+        for path, count in data.items():
+            self.access_frequency[path] += count

algo_cli/intelligence/process_framework.py

@@ -0,0 +1,217 @@
+"""B46. Process Framework for Business Workflows (Semantic Kernel Pattern).
+
+Models real-world business processes (bid → permit → install → invoice)
+as state machines with typed steps, conditional transitions, retries,
+and failure fallbacks.  Processes are serializable for pause/resume.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Callable
+
+
+class ProcessState(Enum):
+    PENDING = "pending"
+    RUNNING = "running"
+    WAITING = "waiting"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    SKIPPED = "skipped"
+
+
+@dataclass
+class ProcessStep:
+    name: str
+    action: Callable[[dict], Any]
+    inputs: dict[str, Any] = field(default_factory=dict)
+    outputs: dict[str, Any] = field(default_factory=dict)
+    state: ProcessState = ProcessState.PENDING
+    condition: Callable[[dict], bool] | None = None
+    on_success: str | None = None
+    on_failure: str | None = None
+    retries: int = 0
+    max_retries: int = 3
+
+    def to_dict(self) -> dict:
+        return {
+            "name": self.name,
+            "state": self.state.value,
+            "retries": self.retries,
+            "outputs": self.outputs,
+        }
+
+
+class Process:
+    """State-machine workflow with conditional transitions."""
+
+    def __init__(self, name: str):
+        self.name = name
+        self.steps: dict[str, ProcessStep] = {}
+        self.start_step: str | None = None
+        self.context: dict[str, Any] = {}
+        self.completed: bool = False
+
+    def add_step(self, step: ProcessStep, is_start: bool = False) -> None:
+        self.steps[step.name] = step
+        if is_start:
+            self.start_step = step.name
+
+    def run(self, context: dict[str, Any] | None = None) -> dict[str, Any]:
+        """Execute the process from start to end (or failure)."""
+        if context:
+            self.context.update(context)
+        current = self.start_step
+        while current:
+            step = self.steps.get(current)
+            if not step:
+                break
+            # Condition gate
+            if step.condition and not step.condition(self.context):
+                step.state = ProcessState.SKIPPED
+                current = step.on_success
+                continue
+            step.state = ProcessState.RUNNING
+            try:
+                result = step.action(self.context)
+                step.outputs = result if isinstance(result, dict) else {"result": result}
+                self.context.update(step.outputs)
+                step.state = ProcessState.COMPLETED
+                current = step.on_success
+            except Exception as e:
+                step.retries += 1
+                if step.retries < step.max_retries:
+                    step.state = ProcessState.WAITING
+                    continue  # retry same step
+                step.state = ProcessState.FAILED
+                self.context[f"{step.name}_error"] = str(e)
+                current = step.on_failure
+        self.completed = True
+        return self.context
+
+    def status(self) -> dict[str, Any]:
+        """Return current process status."""
+        return {
+            "name": self.name,
+            "completed": self.completed,
+            "steps": {name: step.to_dict() for name, step in self.steps.items()},
+            "context_keys": list(self.context.keys()),
+        }
+
+    def serialize(self) -> str:
+        """Serialize process state for persistence."""
+        return json.dumps({
+            "name": self.name,
+            "start_step": self.start_step,
+            "completed": self.completed,
+            "context": {k: v for k, v in self.context.items() if isinstance(v, (str, int, float, bool, list, dict))},
+            "steps": {name: step.to_dict() for name, step in self.steps.items()},
+        }, indent=2)
+
+    def resume_from(self, step_name: str) -> dict[str, Any]:
+        """Resume execution from a specific step."""
+        current = step_name
+        while current:
+            step = self.steps.get(current)
+            if not step:
+                break
+            if step.state == ProcessState.COMPLETED:
+                current = step.on_success
+                continue
+            if step.condition and not step.condition(self.context):
+                step.state = ProcessState.SKIPPED
+                current = step.on_success
+                continue
+            step.state = ProcessState.RUNNING
+            try:
+                result = step.action(self.context)
+                step.outputs = result if isinstance(result, dict) else {"result": result}
+                self.context.update(step.outputs)
+                step.state = ProcessState.COMPLETED
+                current = step.on_success
+            except Exception as e:
+                step.retries += 1
+                if step.retries < step.max_retries:
+                    step.state = ProcessState.WAITING
+                    continue
+                step.state = ProcessState.FAILED
+                self.context[f"{step.name}_error"] = str(e)
+                current = step.on_failure
+        self.completed = True
+        return self.context
+
+
+# ── factories for reusable business workflows ────────────────────────
+
+
+def make_bid_process() -> Process:
+    """Create a standard bid workflow."""
+    p = Process("bid_process")
+
+    def site_visit(ctx: dict) -> dict:
+        return {"site_visited": True, "notes": ctx.get("notes", "")}
+
+    def estimate(ctx: dict) -> dict:
+        return {"estimate_total": ctx.get("estimate_total", 0)}
+
+    def send_bid(ctx: dict) -> dict:
+        return {"bid_sent": True, "bid_amount": ctx.get("estimate_total", 0)}
+
+    def follow_up(ctx: dict) -> dict:
+        return {"follow_up_sent": True}
+
+    def won(ctx: dict) -> dict:
+        return {"status": "won"}
+
+    def lost(ctx: dict) -> dict:
+        return {"status": "lost"}
+
+    p.add_step(ProcessStep(name="site_visit", action=site_visit, on_success="estimate"), is_start=True)
+    p.add_step(ProcessStep(name="estimate", action=estimate, on_success="send_bid"))
+    p.add_step(ProcessStep(name="send_bid", action=send_bid, on_success="follow_up"))
+    p.add_step(ProcessStep(name="follow_up", action=follow_up, on_success="check_result"))
+    p.add_step(ProcessStep(
+        name="check_result",
+        action=lambda ctx: {"won": ctx.get("won", False)},
+        condition=lambda ctx: ctx.get("won", False),
+        on_success="won",
+        on_failure="lost",
+    ))
+    p.add_step(ProcessStep(name="won", action=won))
+    p.add_step(ProcessStep(name="lost", action=lost))
+    return p
+
+
+def make_permit_process() -> Process:
+    """Create a standard permit workflow."""
+    p = Process("permit_process")
+
+    def apply(ctx: dict) -> dict:
+        return {"permit_submitted": True}
+
+    def review(ctx: dict) -> dict:
+        return {"reviewed": True, "approved": ctx.get("approved", False)}
+
+    def corrections(ctx: dict) -> dict:
+        return {"corrections_made": True}
+
+    def approval(ctx: dict) -> dict:
+        return {"permit_approved": True}
+
+    def schedule_inspection(ctx: dict) -> dict:
+        return {"inspection_scheduled": True}
+
+    p.add_step(ProcessStep(name="apply", action=apply, on_success="review"), is_start=True)
+    p.add_step(ProcessStep(
+        name="review",
+        action=review,
+        condition=lambda ctx: ctx.get("approved", False),
+        on_success="approval",
+        on_failure="corrections",
+    ))
+    p.add_step(ProcessStep(name="corrections", action=corrections, on_success="review"))
+    p.add_step(ProcessStep(name="approval", action=approval, on_success="schedule_inspection"))
+    p.add_step(ProcessStep(name="schedule_inspection", action=schedule_inspection))
+    return p