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

algo_cli/intelligence/cavecrew.py

@@ -0,0 +1,118 @@
+"""B75. Cavecrew: Model Specialization per Role.
+
+Match model cost to task complexity.
+Investigator (cheap) → Builder (standard) → Reviewer (cheap) → Orchestrator (expensive).
+Saves ~60% tokens.  Source: Claudient pattern.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum, auto
+from typing import Callable
+
+
+class CrewRole(Enum):
+    INVESTIGATOR = auto()   # cheap model — search, read, gather
+    BUILDER = auto()        # standard model — write, edit, implement
+    REVIEWER = auto()       # cheap model — check, verify, audit
+    ORCHESTRATOR = auto()   # expensive model — plan, decide, coordinate
+
+
+@dataclass
+class CrewMember:
+    role: CrewRole
+    model: str
+    system_prompt: str = ""
+    max_iterations: int = 5
+
+
+@dataclass
+class CrewTask:
+    description: str
+    assigned_role: CrewRole
+    dependencies: list[str] = field(default_factory=list)
+    result: str = ""
+
+
+DEFAULT_CREW: dict[CrewRole, CrewMember] = {
+    CrewRole.INVESTIGATOR: CrewMember(
+        role=CrewRole.INVESTIGATOR,
+        model="qwen3:4b",
+        system_prompt="You are an investigator. Search, read, and gather information. Be concise.",
+        max_iterations=3,
+    ),
+    CrewRole.BUILDER: CrewMember(
+        role=CrewRole.BUILDER,
+        model="glm-5.2",
+        system_prompt="You are a builder. Write and edit code. Follow existing patterns.",
+        max_iterations=5,
+    ),
+    CrewRole.REVIEWER: CrewMember(
+        role=CrewRole.REVIEWER,
+        model="qwen3:4b",
+        system_prompt="You are a reviewer. Check for errors, missing tests, and improvements.",
+        max_iterations=3,
+    ),
+    CrewRole.ORCHESTRATOR: CrewMember(
+        role=CrewRole.ORCHESTRATOR,
+        model="gpt-5.5",
+        system_prompt="You are the orchestrator. Plan, decide, and coordinate. Be strategic.",
+        max_iterations=5,
+    ),
+}
+
+
+class Cavecrew:
+    """Model-specialized crew for cost-efficient multi-agent work."""
+
+    def __init__(self, crew: dict[CrewRole, CrewMember] | None = None) -> None:
+        self._crew = crew or dict(DEFAULT_CREW)
+        self._tasks: list[CrewTask] = []
+        self._results: dict[str, str] = {}
+
+    def assign(self, task: CrewTask) -> None:
+        self._tasks.append(task)
+
+    def run(self, run_fn: Callable[[CrewMember, str, str], str]) -> dict[str, str]:
+        """Execute tasks in dependency order, routing to appropriate models."""
+        completed: set[str] = set()
+
+        for _ in range(len(self._tasks) * 2):  # safety limit
+            ready = [
+                t for t in self._tasks
+                if t.description not in completed
+                and all(d in completed for d in t.dependencies)
+            ]
+            if not ready:
+                break
+
+            for task in ready:
+                member = self._crew.get(task.assigned_role)
+                if not member:
+                    continue
+                try:
+                    result = run_fn(member, member.system_prompt, task.description)
+                    task.result = result
+                    self._results[task.description] = result
+                    completed.add(task.description)
+                except Exception as e:
+                    task.result = f"ERROR: {e}"
+                    self._results[task.description] = task.result
+                    completed.add(task.description)
+
+        return dict(self._results)
+
+    def estimate_cost(self) -> dict[CrewRole, int]:
+        """Estimate relative token cost per role."""
+        costs = {
+            CrewRole.INVESTIGATOR: 1,   # cheap
+            CrewRole.BUILDER: 3,         # standard
+            CrewRole.REVIEWER: 1,        # cheap
+            CrewRole.ORCHESTRATOR: 5,    # expensive
+        }
+        return {role: costs.get(role, 1) * sum(1 for t in self._tasks if t.assigned_role == role)
+                for role in CrewRole}
+
+    @property
+    def crew(self) -> dict[CrewRole, CrewMember]:
+        return dict(self._crew)

algo_cli/intelligence/changelog.py

@@ -0,0 +1,176 @@
+"""B44. Changefile-Driven Release Notes (Microsoft Beachball Pattern).
+
+Requires a changefile for every user-visible code change.  Generates
+release notes grouped by kind (feature, fix, maintenance, safety, docs,
+breaking).  Validates that no release is missing changefiles.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+
+class ChangeKind:
+    FEATURE = "feature"
+    FIX = "fix"
+    MAINTENANCE = "maintenance"
+    SAFETY = "safety"
+    DOCS = "docs"
+    BREAKING = "breaking"
+
+
+@dataclass
+class ChangeFile:
+    """A single change file (changes/*.json)."""
+    filename: str
+    kind: str
+    description: str
+    component: str = ""
+    author: str = ""
+    created_at: str = field(default_factory=lambda: datetime.now().isoformat())
+    version_bump: str = "patch"  # "patch", "minor", "major"
+
+
+@dataclass
+class ReleaseNotes:
+    version: str
+    date: str
+    sections: dict[str, list[str]] = field(default_factory=dict)
+    breaking_changes: list[str] = field(default_factory=list)
+    total_changes: int = 0
+
+    def to_markdown(self) -> str:
+        lines = [f"# Release {self.version}", f"Date: {self.date}", ""]
+        if self.breaking_changes:
+            lines.append("## ⚠️ Breaking Changes")
+            for bc in self.breaking_changes:
+                lines.append(f"- {bc}")
+            lines.append("")
+        kind_order = [ChangeKind.FEATURE, ChangeKind.FIX, ChangeKind.SAFETY, ChangeKind.MAINTENANCE, ChangeKind.DOCS]
+        kind_labels = {
+            ChangeKind.FEATURE: "✨ Features",
+            ChangeKind.FIX: "🐛 Fixes",
+            ChangeKind.SAFETY: "🛡️ Safety",
+            ChangeKind.MAINTENANCE: "🔧 Maintenance",
+            ChangeKind.DOCS: "📚 Documentation",
+        }
+        for kind in kind_order:
+            entries = self.sections.get(kind, [])
+            if entries:
+                lines.append(f"## {kind_labels.get(kind, kind)}")
+                for entry in entries:
+                    lines.append(f"- {entry}")
+                lines.append("")
+        return "\n".join(lines)
+
+
+class ChangelogManager:
+    """Manages change files and release note generation."""
+
+    def __init__(self, changes_dir: str = "changes"):
+        self.changes_dir = Path(changes_dir)
+        self._changes: list[ChangeFile] = []
+
+    def add_change(self, change: ChangeFile) -> None:
+        self._changes.append(change)
+
+    def load_from_dir(self, directory: Path | None = None) -> list[ChangeFile]:
+        """Load change files from a directory."""
+        d = directory or self.changes_dir
+        if not d.exists():
+            return []
+        loaded: list[ChangeFile] = []
+        for f in sorted(d.glob("*.json")):
+            try:
+                data = json.loads(f.read_text(encoding="utf-8"))
+                loaded.append(ChangeFile(
+                    filename=f.name,
+                    kind=data.get("kind", ChangeKind.MAINTENANCE),
+                    description=data.get("description", ""),
+                    component=data.get("component", ""),
+                    author=data.get("author", ""),
+                    created_at=data.get("created_at", datetime.now().isoformat()),
+                    version_bump=data.get("version_bump", "patch"),
+                ))
+            except (json.JSONDecodeError, KeyError):
+                continue
+        self._changes.extend(loaded)
+        return loaded
+
+    def pending_changes(self) -> list[ChangeFile]:
+        """Return all loaded changes (not yet released)."""
+        return list(self._changes)
+
+    def has_changes(self) -> bool:
+        return len(self._changes) > 0
+
+    def required_version_bump(self) -> str:
+        """Determine the minimum version bump from pending changes."""
+        if any(c.version_bump == "major" or c.kind == ChangeKind.BREAKING for c in self._changes):
+            return "major"
+        if any(c.version_bump == "minor" or c.kind == ChangeKind.FEATURE for c in self._changes):
+            return "minor"
+        return "patch"
+
+    def generate_release_notes(self, version: str, date: str | None = None) -> ReleaseNotes:
+        """Generate release notes from pending changes."""
+        date = date or datetime.now().strftime("%Y-%m-%d")
+        sections: dict[str, list[str]] = {}
+        breaking: list[str] = []
+        for change in self._changes:
+            kind = change.kind
+            if kind == ChangeKind.BREAKING:
+                breaking.append(change.description)
+                kind = ChangeKind.FIX  # also list under fixes
+            sections.setdefault(kind, []).append(
+                f"{change.description}" + (f" ({change.component})" if change.component else "")
+            )
+        notes = ReleaseNotes(
+            version=version,
+            date=date,
+            sections=sections,
+            breaking_changes=breaking,
+            total_changes=len(self._changes),
+        )
+        return notes
+
+    def release_check(self) -> dict[str, Any]:
+        """Validate release readiness."""
+        issues: list[str] = []
+        if not self._changes:
+            issues.append("no changefiles found — user-visible changes require a changefile")
+        for c in self._changes:
+            if not c.description:
+                issues.append(f"changefile {c.filename} has empty description")
+            if c.kind not in [ChangeKind.FEATURE, ChangeKind.FIX, ChangeKind.MAINTENANCE, ChangeKind.SAFETY, ChangeKind.DOCS, ChangeKind.BREAKING]:
+                issues.append(f"changefile {c.filename} has unknown kind: {c.kind}")
+        return {
+            "ready": len(issues) == 0,
+            "issues": issues,
+            "change_count": len(self._changes),
+            "required_bump": self.required_version_bump(),
+        }
+
+    def clear_released(self) -> None:
+        """Clear changes after generating release notes."""
+        self._changes.clear()
+
+
+def write_change_file(directory: Path, name: str, kind: str, description: str, component: str = "", author: str = "") -> Path:
+    """Write a change file to disk."""
+    directory.mkdir(parents=True, exist_ok=True)
+    data = {
+        "kind": kind,
+        "description": description,
+        "component": component,
+        "author": author,
+        "created_at": datetime.now().isoformat(),
+        "version_bump": "major" if kind == ChangeKind.BREAKING else "minor" if kind == ChangeKind.FEATURE else "patch",
+    }
+    path = directory / f"{name}.json"
+    path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+    return path

algo_cli/intelligence/checkpoint_resume.py

@@ -0,0 +1,92 @@
+"""H11 — Checkpoint/Resume.
+
+Resumable long catalog operations via state serialization.
+Mined from GLOSSOPETRAE experiment harnesses.
+"""
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class Checkpoint:
+    """A single checkpoint capturing operation state."""
+
+    operation_id: str
+    step: int
+    total_steps: int
+    state: dict[str, Any] = field(default_factory=dict)
+    created_at: float = field(default_factory=time.time)
+    completed: bool = False
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "operation_id": self.operation_id,
+            "step": self.step,
+            "total_steps": self.total_steps,
+            "state": dict(self.state),
+            "created_at": self.created_at,
+            "completed": self.completed,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Checkpoint:
+        return cls(
+            operation_id=data["operation_id"],
+            step=data["step"],
+            total_steps=data["total_steps"],
+            state=dict(data.get("state", {})),
+            created_at=data.get("created_at", time.time()),
+            completed=data.get("completed", False),
+        )
+
+
+class CheckpointManager:
+    """Save and load checkpoints for resumable operations."""
+
+    def __init__(self) -> None:
+        self._checkpoints: dict[str, Checkpoint] = {}
+
+    def save(self, checkpoint: Checkpoint) -> None:
+        self._checkpoints[checkpoint.operation_id] = checkpoint
+
+    def load(self, operation_id: str) -> Checkpoint | None:
+        return self._checkpoints.get(operation_id)
+
+    def complete(self, operation_id: str) -> Checkpoint | None:
+        cp = self._checkpoints.get(operation_id)
+        if cp is not None:
+            cp.completed = True
+        return cp
+
+    def is_complete(self, operation_id: str) -> bool:
+        cp = self._checkpoints.get(operation_id)
+        return cp is not None and cp.completed
+
+    def resume_step(self, operation_id: str) -> int:
+        """Return the step to resume from (0 if no checkpoint)."""
+        cp = self._checkpoints.get(operation_id)
+        if cp is None or cp.completed:
+            return 0
+        return cp.step
+
+    def serialize(self, operation_id: str) -> str:
+        cp = self._checkpoints.get(operation_id)
+        if cp is None:
+            raise KeyError(f"No checkpoint for {operation_id!r}")
+        return json.dumps(cp.to_dict())
+
+    def deserialize(self, data: str) -> Checkpoint:
+        return Checkpoint.from_dict(json.loads(data))
+
+    def all(self) -> list[Checkpoint]:
+        return list(self._checkpoints.values())
+
+    def count(self) -> int:
+        return len(self._checkpoints)
+
+    def clear(self) -> None:
+        self._checkpoints.clear()

algo_cli/intelligence/circuit_breaker.py

@@ -0,0 +1,88 @@
+"""H16 — Detection Risk Circuit Breaker.
+
+Accumulate risk per failure, auto-disable at threshold.
+Mined from T3MP3ST WHITEPAPER §3.5.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable
+
+
+@dataclass
+class CircuitState:
+    """State for a single circuit."""
+
+    name: str
+    risk: float = 0.0
+    threshold: float = 1.0
+    increment: float = 0.1
+    tripped: bool = False
+    trip_count: int = 0
+    last_failure: str = ""
+    metadata: dict[str, object] = field(default_factory=dict)
+
+
+class CircuitBreaker:
+    """Manage multiple named circuit breakers."""
+
+    def __init__(self) -> None:
+        self._circuits: dict[str, CircuitState] = {}
+        self._on_trip: list[Callable[[str, CircuitState], None]] = []
+
+    def register(
+        self,
+        name: str,
+        threshold: float = 1.0,
+        increment: float = 0.1,
+    ) -> CircuitState:
+        circuit = CircuitState(name=name, threshold=threshold, increment=increment)
+        self._circuits[name] = circuit
+        return circuit
+
+    def record_failure(self, name: str, reason: str = "") -> CircuitState:
+        circuit = self._circuits.get(name)
+        if circuit is None:
+            raise KeyError(f"Circuit {name!r} not registered")
+        if circuit.tripped:
+            return circuit
+        circuit.risk += circuit.increment
+        circuit.last_failure = reason
+        if circuit.risk >= circuit.threshold:
+            circuit.tripped = True
+            circuit.trip_count += 1
+            for cb in self._on_trip:
+                cb(name, circuit)
+        return circuit
+
+    def record_success(self, name: str) -> CircuitState:
+        circuit = self._circuits.get(name)
+        if circuit is None:
+            raise KeyError(f"Circuit {name!r} not registered")
+        circuit.risk = max(0.0, circuit.risk - circuit.increment)
+        return circuit
+
+    def is_tripped(self, name: str) -> bool:
+        circuit = self._circuits.get(name)
+        return circuit is not None and circuit.tripped
+
+    def reset(self, name: str) -> CircuitState:
+        circuit = self._circuits.get(name)
+        if circuit is None:
+            raise KeyError(f"Circuit {name!r} not registered")
+        circuit.risk = 0.0
+        circuit.tripped = False
+        circuit.last_failure = ""
+        return circuit
+
+    def on_trip(self, callback: Callable[[str, CircuitState], None]) -> None:
+        self._on_trip.append(callback)
+
+    def get(self, name: str) -> CircuitState | None:
+        return self._circuits.get(name)
+
+    def all(self) -> list[CircuitState]:
+        return list(self._circuits.values())
+
+    def count(self) -> int:
+        return len(self._circuits)

algo_cli/intelligence/clarification_gate.py

@@ -0,0 +1,101 @@
+"""B67. Human-in-the-Loop Clarification.
+
+Ask clarifying questions before expensive research.
+Source: DeepResearch-Agent pattern.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum, auto
+
+
+class ClarificationType(Enum):
+    SCOPE = auto()        # "Do you mean X or Y?"
+    DEPTH = auto()        # "Brief overview or deep dive?"
+    AUDIENCE = auto()     # "For beginners or experts?"
+    FORMAT = auto()       # "Report, bullet points, or code?"
+    TIMEFRAME = auto()   # "Recent only or historical?"
+
+
+@dataclass
+class Clarification:
+    id: str
+    type: ClarificationType
+    question: str
+    options: list[str] = field(default_factory=list)
+    default: str = ""
+    answer: str = ""
+
+
+@dataclass
+class ClarificationResult:
+    clarifications: list[Clarification] = field(default_factory=list)
+    refined_query: str = ""
+    skipped: bool = False
+
+
+class ClarificationGate:
+    """Generate and collect clarifying questions before research."""
+
+    AMBIGUOUS_WORDS = {"best", "good", "fast", "simple", "advanced", "modern", "latest"}
+
+    def generate(self, query: str) -> list[Clarification]:
+        """Generate clarifying questions based on query analysis."""
+        clarifications: list[Clarification] = []
+        words = set(query.lower().split())
+
+        # Check for ambiguous terms
+        ambiguous = words & self.AMBIGUOUS_WORDS
+        if ambiguous:
+            clarifications.append(Clarification(
+                id="clar_1",
+                type=ClarificationType.SCOPE,
+                question=f"You mentioned '{', '.join(ambiguous)}'. Can you be more specific?",
+                default="general overview",
+            ))
+
+        # Check for depth signals
+        if not any(w in query.lower() for w in ["deep", "detailed", "overview", "brief", "summary"]):
+            clarifications.append(Clarification(
+                id="clar_2",
+                type=ClarificationType.DEPTH,
+                question="How deep should the research go?",
+                options=["Brief overview", "Standard depth", "Deep dive"],
+                default="Standard depth",
+            ))
+
+        # Check for format
+        if not any(w in query.lower() for w in ["report", "bullet", "code", "table", "list"]):
+            clarifications.append(Clarification(
+                id="clar_3",
+                type=ClarificationType.FORMAT,
+                question="What format would you prefer?",
+                options=["Markdown report", "Bullet points", "Code examples"],
+                default="Markdown report",
+            ))
+
+        # Check for timeframe
+        if not any(w in query.lower() for w in ["2024", "2025", "2026", "recent", "latest", "historical"]):
+            clarifications.append(Clarification(
+                id="clar_4",
+                type=ClarificationType.TIMEFRAME,
+                question="What timeframe should I focus on?",
+                options=["Recent (2025-2026)", "Last 3 years", "Historical"],
+                default="Recent (2025-2026)",
+            ))
+
+        return clarifications
+
+    def refine_query(self, query: str, answers: dict[str, str]) -> str:
+        """Refine the original query based on clarification answers."""
+        refined = query
+        for clar_id, answer in answers.items():
+            if answer and answer != "general overview":
+                refined += f" ({answer})"
+        return refined
+
+    def should_ask(self, query: str, auto_skip: bool = False) -> bool:
+        """Determine if clarification is needed."""
+        if auto_skip:
+            return False
+        return len(self.generate(query)) > 0