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

algo_cli/intelligence/ema_tuning.py

@@ -0,0 +1,104 @@
+"""H13 — Feedback-Driven Parameter Tuning (EMA).
+
+Exponential moving average tuning: user feedback (binary ratings) updates
+an EMA that adjusts harness parameters over time.  Includes sample-count
+gating (no adjustments until minimum samples collected) and bounded history.
+
+Source: G0DM0D3 AutoTune.
+"""
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass
+from typing import Any
+
+
+MAX_HISTORY = 500
+MIN_SAMPLES_TO_APPLY = 3
+
+
+@dataclass
+class TuningState:
+    """Snapshot of the EMA tuner state."""
+
+    ema: float
+    samples: int
+    applied: bool
+    history_size: int
+
+
+class EMATuner:
+    """EMA-based parameter tuner with sample-count gating."""
+
+    def __init__(
+        self,
+        param_name: str,
+        initial_value: float = 0.5,
+        alpha: float = 0.3,
+        min_samples: int = MIN_SAMPLES_TO_APPLY,
+        max_history: int = MAX_HISTORY,
+    ) -> None:
+        if not 0.0 < alpha <= 1.0:
+            raise ValueError(f"alpha must be in (0, 1], got {alpha}")
+        self.param_name = param_name
+        self.alpha = alpha
+        self.min_samples = min_samples
+        self.max_history = max_history
+        self._ema = initial_value
+        self._samples = 0
+        self._history: deque[float] = deque(maxlen=max_history)
+
+    def update(self, rating: float) -> float:
+        """Update EMA with a new rating (0.0 to 1.0).
+
+        Returns the updated EMA value.
+        """
+        if not 0.0 <= rating <= 1.0:
+            raise ValueError(f"rating must be in [0, 1], got {rating}")
+        self._samples += 1
+        self._history.append(rating)
+        self._ema = self.alpha * rating + (1 - self.alpha) * self._ema
+        return self._ema
+
+    def update_binary(self, positive: bool) -> float:
+        """Update with a binary rating (True=1.0, False=0.0)."""
+        return self.update(1.0 if positive else 0.0)
+
+    @property
+    def ema(self) -> float:
+        return self._ema
+
+    @property
+    def samples(self) -> int:
+        return self._samples
+
+    @property
+    def can_apply(self) -> bool:
+        """True when enough samples have been collected to apply tuning."""
+        return self._samples >= self.min_samples
+
+    def apply(self, params: dict[str, Any]) -> dict[str, Any]:
+        """Apply the tuned value to a params dict if enough samples exist.
+
+        Returns a new dict with the parameter updated.
+        """
+        if not self.can_apply:
+            return params
+        result = dict(params)
+        result[self.param_name] = self._ema
+        return result
+
+    def state(self) -> TuningState:
+        """Return a snapshot of the current state."""
+        return TuningState(
+            ema=round(self._ema, 6),
+            samples=self._samples,
+            applied=self.can_apply,
+            history_size=len(self._history),
+        )
+
+    def reset(self) -> None:
+        """Reset to initial state."""
+        self._ema = 0.5
+        self._samples = 0
+        self._history.clear()

algo_cli/intelligence/event_log.py

@@ -0,0 +1,92 @@
+"""H4 — Harness Discovery Event Log.
+
+Structured events for the full discovery lifecycle.
+Mined from T3MP3ST EventEmitter (finding:discovered, finding:retracted, etc.).
+"""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Callable
+
+
+class EventType(str, Enum):
+    DISCOVERED = "discovered"
+    PROPOSED = "proposed"
+    VERIFIED = "verified"
+    RETRACTED = "retracted"
+    DEPRECATED = "deprecated"
+    PROMOTED = "promoted"
+
+
+@dataclass
+class Event:
+    """A single discovery event."""
+
+    event_type: EventType
+    target_id: str
+    timestamp: float = field(default_factory=time.time)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "event_type": self.event_type.value,
+            "target_id": self.target_id,
+            "timestamp": self.timestamp,
+            "metadata": dict(self.metadata),
+        }
+
+
+class EventLogger:
+    """Append-only event log with subscription support."""
+
+    def __init__(self) -> None:
+        self._events: list[Event] = []
+        self._subscribers: list[tuple[Callable[[Event], None], EventType | None]] = []
+
+    def emit(
+        self,
+        event_type: EventType,
+        target_id: str,
+        metadata: dict[str, Any] | None = None,
+    ) -> Event:
+        """Emit an event and notify subscribers."""
+        event = Event(
+            event_type=event_type,
+            target_id=target_id,
+            metadata=metadata or {},
+        )
+        self._events.append(event)
+        for callback, filter_type in self._subscribers:
+            if filter_type is None or filter_type == event_type:
+                callback(event)
+        return event
+
+    def subscribe(
+        self,
+        callback: Callable[[Event], None],
+        event_type: EventType | None = None,
+    ) -> None:
+        """Subscribe to events. Optionally filter by event type."""
+        self._subscribers.append((callback, event_type))
+
+    def query(
+        self,
+        event_type: EventType | None = None,
+        target_id: str | None = None,
+    ) -> list[Event]:
+        """Query events by type and/or target."""
+        results = self._events
+        if event_type is not None:
+            results = [e for e in results if e.event_type == event_type]
+        if target_id is not None:
+            results = [e for e in results if e.target_id == target_id]
+        return list(results)
+
+    def count(self) -> int:
+        return len(self._events)
+
+    def clear(self) -> None:
+        self._events.clear()
+        self._subscribers.clear()

algo_cli/intelligence/evidence_graph.py

@@ -0,0 +1,114 @@
+"""B63. Evidence Graph for Provenance.
+
+Link every claim to source text snippets with traceable citations.
+Source: Deep-Research-Agent pattern.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Source:
+    id: str
+    title: str
+    url: str = ""
+    content: str = ""
+    retrieved_at: str = ""
+    trust_score: float = 0.5
+
+
+@dataclass
+class Claim:
+    id: str
+    text: str
+    source_ids: list[str] = field(default_factory=list)
+    evidence_spans: list[dict] = field(default_factory=list)
+    confidence: float = 0.0
+    contradictions: list[str] = field(default_factory=list)
+
+
+@dataclass
+class EvidenceEdge:
+    claim_id: str
+    source_id: str
+    span_start: int = 0
+    span_end: int = 0
+    relevance: float = 0.0
+
+
+class EvidenceGraph:
+    """Graph linking claims to source evidence for provenance."""
+
+    def __init__(self) -> None:
+        self._sources: dict[str, Source] = {}
+        self._claims: dict[str, Claim] = {}
+        self._edges: list[EvidenceEdge] = []
+
+    def add_source(self, source: Source) -> None:
+        self._sources[source.id] = source
+
+    def add_claim(self, claim: Claim) -> None:
+        self._claims[claim.id] = claim
+        for sid in claim.source_ids:
+            if sid in self._sources:
+                self._edges.append(EvidenceEdge(claim_id=claim.id, source_id=sid))
+
+    def link_evidence(self, claim_id: str, source_id: str,
+                      span_start: int = 0, span_end: int = 0,
+                      relevance: float = 1.0) -> None:
+        self._edges.append(EvidenceEdge(
+            claim_id=claim_id, source_id=source_id,
+            span_start=span_start, span_end=span_end, relevance=relevance,
+        ))
+        claim = self._claims.get(claim_id)
+        if claim and source_id not in claim.source_ids:
+            claim.source_ids.append(source_id)
+
+    def get_evidence(self, claim_id: str) -> list[tuple[Source, EvidenceEdge]]:
+        """Get all source evidence for a claim."""
+        result: list[tuple[Source, EvidenceEdge]] = []
+        for edge in self._edges:
+            if edge.claim_id == claim_id:
+                source = self._sources.get(edge.source_id)
+                if source:
+                    result.append((source, edge))
+        return sorted(result, key=lambda x: x[1].relevance, reverse=True)
+
+    def find_contradictions(self) -> list[tuple[str, str, str]]:
+        """Find claims that contradict each other."""
+        contradictions: list[tuple[str, str, str]] = []
+        claim_list = list(self._claims.values())
+        for i, a in enumerate(claim_list):
+            for b in claim_list[i + 1:]:
+                if a.source_ids and b.source_ids:
+                    shared = set(a.source_ids) & set(b.source_ids)
+                    if shared and a.text != b.text:
+                        # Simple heuristic: if same source but different claims
+                        contradictions.append((a.id, b.id, "same source, different claims"))
+        return contradictions
+
+    def render_citations(self, claim_id: str) -> str:
+        """Render citations for a claim in [1], [2] format."""
+        evidence = self.get_evidence(claim_id)
+        if not evidence:
+            return ""
+        citations: list[str] = []
+        for i, (source, edge) in enumerate(evidence, 1):
+            span_text = ""
+            if edge.span_end > edge.span_start:
+                span_text = source.content[edge.span_start:edge.span_end]
+            citations.append(f"[{i}] {source.title} — {span_text[:100]}")
+        return "\n".join(citations)
+
+    @property
+    def source_count(self) -> int:
+        return len(self._sources)
+
+    @property
+    def claim_count(self) -> int:
+        return len(self._claims)
+
+    @property
+    def edge_count(self) -> int:
+        return len(self._edges)

algo_cli/intelligence/extension_host.py

@@ -0,0 +1,162 @@
+"""B38. Extension Host Isolation + Declarative Contribution Points (VS Code Pattern).
+
+Extensions declare what they contribute (commands, tools, converters,
+maintenance checks) via a manifest.  Activation events control when an
+extension's code is loaded.  Extensions run behind a boundary and cannot
+directly mutate files or send externally.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+
+# ── contribution schema ───────────────────────────────────────────────
+
+
+@dataclass
+class CommandContribution:
+    id: str
+    title: str
+    handler: Callable[[], str] | None = None
+
+
+@dataclass
+class ToolContribution:
+    id: str
+    description: str
+    handler: Callable[[dict], str] | None = None
+
+
+@dataclass
+class ConverterContribution:
+    id: str
+    suffixes: list[str]
+    handler: Callable[[str], str] | None = None
+
+
+@dataclass
+class MaintenanceCheckContribution:
+    id: str
+    name: str
+    handler: Callable[[], dict] | None = None
+
+
+@dataclass
+class ExtensionManifest:
+    """Declarative manifest for an Algo CLI extension."""
+    id: str
+    name: str
+    version: str = "0.1.0"
+    enabled: bool = True
+    activation_events: list[str] = field(default_factory=list)
+    contributes_commands: list[CommandContribution] = field(default_factory=list)
+    contributes_tools: list[ToolContribution] = field(default_factory=list)
+    contributes_converters: list[ConverterContribution] = field(default_factory=list)
+    contributes_maintenance_checks: list[MaintenanceCheckContribution] = field(default_factory=list)
+
+
+# ── activation events ─────────────────────────────────────────────────
+
+
+def matches_activation(event: str, context: dict[str, Any]) -> bool:
+    """Check if an activation event matches the current context."""
+    if event == "*":
+        return True
+    if event.startswith("onCommand:"):
+        return context.get("command") == event.split(":", 1)[1]
+    if event.startswith("onFileType:"):
+        return context.get("file_suffix") == event.split(":", 1)[1]
+    if event.startswith("onProject:"):
+        return context.get("project") == event.split(":", 1)[1]
+    if event.startswith("onSchedule:"):
+        return context.get("schedule") == event.split(":", 1)[1]
+    return False
+
+
+# ── extension host ────────────────────────────────────────────────────
+
+
+class ExtensionHost:
+    """Manages extensions with activation and contribution resolution."""
+
+    def __init__(self) -> None:
+        self._manifests: dict[str, ExtensionManifest] = {}
+        self._activated: set[str] = set()
+
+    def register(self, manifest: ExtensionManifest) -> None:
+        self._manifests[manifest.id] = manifest
+
+    def activate(self, ext_id: str, context: dict[str, Any] | None = None) -> bool:
+        """Activate an extension if its activation events match."""
+        manifest = self._manifests.get(ext_id)
+        if not manifest or not manifest.enabled:
+            return False
+        ctx = context or {}
+        if any(matches_activation(ev, ctx) for ev in manifest.activation_events):
+            self._activated.add(ext_id)
+            return True
+        return False
+
+    def is_activated(self, ext_id: str) -> bool:
+        return ext_id in self._activated
+
+    def disable(self, ext_id: str) -> None:
+        manifest = self._manifests.get(ext_id)
+        if manifest:
+            manifest.enabled = False
+            self._activated.discard(ext_id)
+
+    def all_commands(self) -> list[CommandContribution]:
+        """Get commands from all activated extensions."""
+        commands: list[CommandContribution] = []
+        for ext_id in self._activated:
+            manifest = self._manifests[ext_id]
+            commands.extend(manifest.contributes_commands)
+        return commands
+
+    def all_tools(self) -> list[ToolContribution]:
+        tools: list[ToolContribution] = []
+        for ext_id in self._activated:
+            manifest = self._manifests[ext_id]
+            tools.extend(manifest.contributes_tools)
+        return tools
+
+    def all_converters(self) -> list[ConverterContribution]:
+        converters: list[ConverterContribution] = []
+        for ext_id in self._activated:
+            manifest = self._manifests[ext_id]
+            converters.extend(manifest.contributes_converters)
+        return converters
+
+    def all_maintenance_checks(self) -> list[MaintenanceCheckContribution]:
+        checks: list[MaintenanceCheckContribution] = []
+        for ext_id in self._activated:
+            manifest = self._manifests[ext_id]
+            checks.extend(manifest.contributes_maintenance_checks)
+        return checks
+
+    def execute_command(self, command_id: str) -> str:
+        """Execute a contributed command (gated by activation)."""
+        for ext_id in self._activated:
+            manifest = self._manifests[ext_id]
+            for cmd in manifest.contributes_commands:
+                if cmd.id == command_id and cmd.handler:
+                    return cmd.handler()
+        return f"Command {command_id} not found or not activated"
+
+    def validate_manifest(self, ext_id: str) -> list[str]:
+        """Validate a manifest and return list of issues."""
+        manifest = self._manifests.get(ext_id)
+        if not manifest:
+            return ["manifest not found"]
+        issues: list[str] = []
+        if not manifest.id:
+            issues.append("missing id")
+        if not manifest.name:
+            issues.append("missing name")
+        for cmd in manifest.contributes_commands:
+            if not cmd.id:
+                issues.append("command missing id")
+        return issues

algo_cli/intelligence/extension_manifest.py

@@ -0,0 +1,115 @@
+"""B57. Extension Manifest Schema + Catalog.
+
+YAML manifest with commands/config/hooks.  Extension registry with
+multi-source catalog and priority.  Source: spec-kit pattern.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum, auto
+from typing import Any
+
+
+class ExtensionStatus(Enum):
+    DISCOVERED = auto()
+    INSTALLED = auto()
+    ENABLED = auto()
+    DISABLED = auto()
+    ERROR = auto()
+
+
+@dataclass
+class ExtensionContribution:
+    type: str  # "command", "tool", "hook", "contextProvider", "fileConverter"
+    id: str
+    handler: str = ""  # module:function or path
+    config: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ExtensionManifest:
+    id: str
+    name: str
+    version: str
+    description: str = ""
+    author: str = ""
+    priority: int = 100  # lower = higher priority
+    activation_events: list[str] = field(default_factory=list)
+    contributes: list[ExtensionContribution] = field(default_factory=list)
+    config_schema: dict[str, Any] = field(default_factory=dict)
+    status: ExtensionStatus = ExtensionStatus.DISCOVERED
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "name": self.name,
+            "version": self.version,
+            "description": self.description,
+            "author": self.author,
+            "priority": self.priority,
+            "activation_events": self.activation_events,
+            "contributes": [
+                {"type": c.type, "id": c.id, "handler": c.handler, "config": c.config}
+                for c in self.contributes
+            ],
+        }
+
+
+@dataclass
+class CatalogSource:
+    name: str
+    url: str = ""
+    trust_level: str = "local"  # local, trusted, community
+    priority: int = 100
+    enabled: bool = True
+
+
+class ExtensionCatalog:
+    """Multi-source extension catalog with priority-based resolution."""
+
+    def __init__(self) -> None:
+        self._sources: dict[str, CatalogSource] = {}
+        self._extensions: dict[str, ExtensionManifest] = {}
+
+    def add_source(self, source: CatalogSource) -> None:
+        self._sources[source.name] = source
+
+    def register(self, manifest: ExtensionManifest, source_name: str = "local") -> None:
+        self._extensions[manifest.id] = manifest
+
+    def get(self, ext_id: str) -> ExtensionManifest | None:
+        return self._extensions.get(ext_id)
+
+    def list_extensions(self, status: ExtensionStatus | None = None) -> list[ExtensionManifest]:
+        exts = list(self._extensions.values())
+        if status:
+            exts = [e for e in exts if e.status == status]
+        return sorted(exts, key=lambda e: e.priority)
+
+    def find_contribution(self, contrib_type: str, contrib_id: str) -> ExtensionManifest | None:
+        for ext in self._extensions.values():
+            for c in ext.contributes:
+                if c.type == contrib_type and c.id == contrib_id:
+                    return ext
+        return None
+
+    def enable(self, ext_id: str) -> bool:
+        ext = self._extensions.get(ext_id)
+        if ext:
+            ext.status = ExtensionStatus.ENABLED
+            return True
+        return False
+
+    def disable(self, ext_id: str) -> bool:
+        ext = self._extensions.get(ext_id)
+        if ext:
+            ext.status = ExtensionStatus.DISABLED
+            return True
+        return False
+
+    def match_activation(self, event: str) -> list[ExtensionManifest]:
+        """Find extensions whose activation events match."""
+        return [
+            e for e in self._extensions.values()
+            if e.status == ExtensionStatus.ENABLED and event in e.activation_events
+        ]