forgeoptimizer 1.0.0__py3-none-any.whl

forgecli/engine/context.py

@@ -0,0 +1,171 @@
+"""Typed context that flows through the engine's eight stages.
+
+Each stage reads from the context, mutates one or two fields, and
+returns a :class:`~forgecli.engine.execution.StageResult`. The
+context is the *only* mechanism stages use to share data — there
+are no hidden globals.
+"""
+
+from __future__ import annotations
+
+import time
+import uuid
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from forgecli.plugins import Intent
+
+# ---------------------------------------------------------------------------
+# Per-stage payloads
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class IntentAnalysis:
+    """The output of the Intent Analyzer stage."""
+
+    intent: Intent
+    confidence: float
+    rationale: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class RetrievalResult:
+    """The output of the Repository Analyzer stage."""
+
+    query: str
+    matched_nodes: tuple[Mapping[str, Any], ...] = ()
+    context_text: str = ""
+    artifacts: dict[str, Path] = field(default_factory=dict)
+    notes: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class ModelSelection:
+    """The output of the Model Router stage."""
+
+    provider: str
+    model: str
+    mode: str = "explicit"  # "explicit" | "cheapest" | "fallback"
+    cost_in: float = 0.0
+    cost_out: float = 0.0
+
+
+@dataclass(frozen=True)
+class StageLog:
+    """A single record of how a stage performed.
+
+    The engine accumulates these on :class:`EngineContext` so
+    callers can render a final report.
+    """
+
+    stage: str
+    status: str
+    started_at: float
+    finished_at: float | None = None
+    notes: tuple[str, ...] = ()
+    error: str | None = None
+
+    @property
+    def duration_seconds(self) -> float:
+        if self.finished_at is None:
+            return 0.0
+        return max(0.0, self.finished_at - self.started_at)
+
+
+# ---------------------------------------------------------------------------
+# Engine context
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class EngineContext:
+    """Mutable state shared by every stage of the engine.
+
+    The context is constructed by :class:`EngineBuilder` and
+    passed to each :class:`Stage`. Stages may set the
+    ``intent_analysis`` / ``retrieval`` / ``model_selection`` /
+    ``plan`` / ``response`` / ``diff_text`` / ``applied_files`` /
+    ``test_*`` fields; downstream stages read them.
+    """
+
+    prompt: str
+    cwd: Path
+    run_id: str = field(default_factory=lambda: uuid.uuid4().hex[:12])
+    started_at: float = field(default_factory=time.time)
+
+    # Stage 1: Intent
+    intent_analysis: IntentAnalysis | None = None
+    # Stage 2: Retrieval
+    retrieval: RetrievalResult | None = None
+    # Stage 3: Caveman optimization (runs before context optimization)
+    caveman_optimized_request: Any = None
+    caveman_optimized_notes: tuple[str, ...] = ()
+    # Stage 4: Context optimization
+    optimized_request: Any = None
+    optimized_notes: tuple[str, ...] = ()
+    # Stage 5: Plan
+    plan: Any = None  # SoftwarePlan; kept loose to avoid an import cycle
+    # Stage 5: Model
+    model_selection: ModelSelection | None = None
+    # Stage 6: Execution
+    response: Any = None
+    # Stage 7: Validation
+    diff_text: str = ""
+    applied_files: list[Path] = field(default_factory=list)
+    test_stdout: str = ""
+    test_stderr: str = ""
+    test_returncode: int | None = None
+    fix_attempts: int = 0
+    # Stage 8: Git
+    staged: bool = False
+    pushed: bool = False
+
+    # Free-form extras for plugins / advanced stages.
+    extras: dict[str, Any] = field(default_factory=dict)
+
+    # Per-stage log (append-only).
+    log: list[StageLog] = field(default_factory=list)
+
+    def to_log_dict(self) -> dict[str, Any]:
+        """Return a JSON-serializable snapshot of the context (no Paths)."""
+        return {
+            "run_id": self.run_id,
+            "started_at": self.started_at,
+            "intent": self.intent_analysis.intent.value
+            if self.intent_analysis
+            else None,
+            "intent_confidence": self.intent_analysis.confidence
+            if self.intent_analysis
+            else 0.0,
+            "retrieval_query": self.retrieval.query if self.retrieval else None,
+            "retrieval_match_count": len(self.retrieval.matched_nodes)
+            if self.retrieval
+            else 0,
+            "caveman_optimized_notes": list(self.caveman_optimized_notes),
+            "optimized_notes": list(self.optimized_notes),
+            "has_plan": self.plan is not None,
+            "model": self.model_selection.model if self.model_selection else None,
+            "provider": self.model_selection.provider
+            if self.model_selection
+            else None,
+            "response_present": self.response is not None,
+            "diff_length": len(self.diff_text),
+            "applied_files": [str(p) for p in self.applied_files],
+            "test_returncode": self.test_returncode,
+            "fix_attempts": self.fix_attempts,
+            "staged": self.staged,
+            "pushed": self.pushed,
+            "stage_count": len(self.log),
+        }
+
+
+__all__ = [
+    "EngineContext",
+    "IntentAnalysis",
+    "ModelSelection",
+    "RetrievalResult",
+    "StageLog",
+]

forgecli/engine/defaults.py

@@ -0,0 +1,89 @@
+"""Default stage wiring for the Execution Engine.
+
+Provides :func:`default_registry` which populates a
+:class:`~forgecli.engine.execution.StageRegistry` with all eight
+DEFAULT_PIPELINE stages. Callers can then build an engine with::
+
+    registry = default_registry()
+    engine = ExecutionEngine.from_registry(registry)
+    result = await engine.run(context)
+
+Individual stages can be overridden via
+:meth:`StageRegistry.replace` before building the engine.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from forgecli.engine.execution import Stage, StageRegistry
+from forgecli.engine.stages import (
+    CavemanOptimizerStage,
+    ContextOptimizerStage,
+    ExecutionEngineStage,
+    GitEngineStage,
+    IntentAnalyzerStage,
+    ModelRouterStage,
+    PlanningEngineStage,
+    RepositoryAnalyzerStage,
+    ValidationEngineStage,
+)
+
+
+def default_registry(
+    *,
+    provider: Any = None,
+    optimizer: Any = None,
+    caveman_optimizer: Any = None,
+    graph: Any = None,
+    classifier: Any = None,
+    router: Any = None,
+    test_command: str | None = None,
+    plugin_registry: Any = None,
+    **stage_kwargs: Any,
+) -> StageRegistry:
+    """Create a :class:`StageRegistry` with all nine default pipeline stages.
+
+    Keyword arguments are forwarded to stage constructors:
+
+    * ``provider`` → :class:`ExecutionEngineStage`
+    * ``optimizer`` → :class:`ContextOptimizerStage`
+    * ``caveman_optimizer`` → :class:`CavemanOptimizerStage`
+    * ``graph`` → :class:`RepositoryAnalyzerStage`
+    * ``classifier`` → :class:`IntentAnalyzerStage`
+    * ``router`` → :class:`ModelRouterStage`
+    * ``test_command`` → :class:`ValidationEngineStage`
+    * ``plugin_registry`` → a :class:`~forgecli.plugins.PluginRegistry` whose
+      stages are bulk-loaded into the registry after default stages.
+      The plugin registry is also linked so future
+      :meth:`~forgecli.plugins.PluginRegistry.register_stage` /
+      :meth:`~forgecli.plugins.PluginRegistry.replace_stage` calls
+      are mirrored into this registry.
+
+    Remaining kwargs are passed to stages that accept them by name
+    (e.g. ``auto_commit`` for :class:`GitEngineStage`).
+    """
+    registry = StageRegistry()
+
+    stages: list[Stage] = [
+        IntentAnalyzerStage(classifier=classifier),
+        RepositoryAnalyzerStage(graph=graph),
+        CavemanOptimizerStage(optimizer=caveman_optimizer),
+        ContextOptimizerStage(optimizer=optimizer),
+        PlanningEngineStage(**{k: v for k, v in stage_kwargs.items() if k in ("enabled",)}),
+        ModelRouterStage(router=router),
+        ExecutionEngineStage(provider=provider),
+        ValidationEngineStage(test_command=test_command),
+        GitEngineStage(),
+    ]
+
+    for stage in stages:
+        registry.register(stage)
+
+    if plugin_registry is not None:
+        plugin_registry.link_engine_registry(registry)
+
+    return registry
+
+
+__all__ = ["default_registry"]

forgecli/engine/events.py

@@ -0,0 +1,185 @@
+"""Structured event bus for the Execution Engine.
+
+The :class:`EventBus` is a tiny pub/sub dispatcher for the four
+event kinds the engine emits:
+
+* :class:`StageEvent` — a stage transitioned to a new state.
+* :class:`ProgressEvent` — fractional progress within a stage.
+* :class:`TextLogEvent` — a free-form log line (the engine's
+  "streaming log" surface).
+* :class:`EngineEvent` — the abstract base; every concrete event
+  inherits from it.
+
+Subscribers can be sync or async; the engine handles fan-out
+sequentially. A single :class:`asyncio.Event` (the cancellation
+token) is checked between stages and during long operations so a
+caller can abort cleanly.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from enum import Enum
+
+
+class LogLevel(str, Enum):
+    """Severity for :class:`TextLogEvent`."""
+
+    DEBUG = "debug"
+    INFO = "info"
+    WARN = "warn"
+    ERROR = "error"
+
+
+@dataclass(frozen=True)
+class EngineEvent:
+    """Abstract base of every event the engine emits."""
+
+    timestamp: datetime = field(default_factory=lambda: datetime.now(UTC))
+    run_id: str = ""
+
+
+@dataclass(frozen=True)
+class StageEvent(EngineEvent):
+    """A stage transitioned to a new state."""
+
+    stage: str = ""
+    status: str = "running"  # "running" | "succeeded" | "failed" | "skipped" | "retrying"
+    attempt: int = 1
+    note: str | None = None
+
+
+@dataclass(frozen=True)
+class ProgressEvent(EngineEvent):
+    """Fractional progress within a stage (0.0 - 1.0)."""
+
+    stage: str = ""
+    progress: float = 0.0
+    message: str | None = None
+
+
+@dataclass(frozen=True)
+class TextLogEvent(EngineEvent):
+    """A free-form log line emitted by a stage."""
+
+    level: LogLevel = LogLevel.INFO
+    source: str = ""
+    message: str = ""
+
+
+EventHandler = Callable[[EngineEvent], "None | Awaitable[None]"]
+
+
+class EventBus:
+    """In-process pub/sub bus for engine events.
+
+    Subscribers are registered per event class. Handlers may be sync
+    or async; the engine awaits any coroutines it gets back. A single
+    :class:`asyncio.Event` (the cancellation token) is checked between
+    stages so the caller can abort cleanly.
+    """
+
+    def __init__(self) -> None:
+        self._subscribers: dict[type, list[EventHandler]] = {}
+        self.cancellation = asyncio.Event()
+        self.history: list[EngineEvent] = []
+
+    # ------------------------------------------------------------------
+    # Subscription
+    # ------------------------------------------------------------------
+
+    def subscribe(self, event_cls: type[EngineEvent], handler: EventHandler) -> None:
+        self._subscribers.setdefault(event_cls, []).append(handler)
+
+    def unsubscribe(self, event_cls: type[EngineEvent], handler: EventHandler) -> None:
+        bucket = self._subscribers.get(event_cls)
+        if not bucket:
+            return
+        with contextlib.suppress(ValueError):
+            bucket.remove(handler)
+
+    # ------------------------------------------------------------------
+    # Cancellation
+    # ------------------------------------------------------------------
+
+    def cancel(self) -> None:
+        """Request cancellation. The engine checks ``cancellation`` between stages."""
+        self.cancellation.set()
+
+    def reset_cancellation(self) -> None:
+        self.cancellation.clear()
+
+    def is_cancelled(self) -> bool:
+        return self.cancellation.is_set()
+
+    # ------------------------------------------------------------------
+    # Publishing
+    # ------------------------------------------------------------------
+
+    def publish(self, event: EngineEvent) -> None:
+        """Publish synchronously; async handlers are scheduled."""
+        self.history.append(event)
+        for handler in list(self._subscribers.get(type(event), ())):
+            try:
+                result = handler(event)
+            except Exception:
+                continue
+            if asyncio.iscoroutine(result):
+                # Best-effort: schedule on the running loop if any.
+                try:
+                    loop = asyncio.get_running_loop()
+                    task = loop.create_task(result)
+                    task.add_done_callback(self._discard_task)
+                except RuntimeError:
+                    pass
+
+    @staticmethod
+    def _discard_task(task: asyncio.Task) -> None:
+        # Placeholder to keep a strong reference to the task until it
+        # completes. Without this, asyncio may garbage-collect the
+        # task mid-flight and emit "Task was destroyed but it is
+        # pending" warnings.
+        return None
+
+    async def publish_and_drain(self, event: EngineEvent) -> None:
+        """Publish and await any async handler results."""
+        self.history.append(event)
+        for handler in list(self._subscribers.get(type(event), ())):
+            try:
+                result = handler(event)
+            except Exception:
+                continue
+            if asyncio.iscoroutine(result):
+                await result
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    def drain(self) -> list[EngineEvent]:
+        return list(self.history)
+
+
+# ---------------------------------------------------------------------------
+# Cancellation sentinel exception
+# ---------------------------------------------------------------------------
+
+
+class EngineCancelledError(Exception):
+    """Raised by the engine when the cancellation token is set."""
+
+
+__all__ = [
+    "EngineCancelledError",
+    "EngineEvent",
+    "EventBus",
+    "EventHandler",
+    "LogLevel",
+    "ProgressEvent",
+    "StageEvent",
+    "TextLogEvent",
+]