forgeoptimizer 1.0.0__py3-none-any.whl

forgecli/engine/runner.py

@@ -0,0 +1,155 @@
+"""High-level runner that wraps the ExecutionEngine for CLI use.
+
+Provides :func:`run_engine` which accepts the same high-level
+parameters as the CLI (prompt, provider, optimizer, graph, etc.)
+and returns an :class:`EngineResult` ready for rendering.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from forgecli.engine.context import EngineContext
+from forgecli.engine.defaults import default_registry
+from forgecli.engine.execution import EngineResult, ExecutionEngine
+
+
+def run_engine(
+    prompt: str,
+    root: Path,
+    *,
+    provider: Any = None,
+    optimizer: Any = None,
+    caveman_optimizer: Any = None,
+    graph: Any = None,
+    classifier: Any = None,
+    router: Any = None,
+    test_command: str | None = None,
+    test_timeout: float = 120.0,
+    retries: int = 0,
+    skip_tests: bool = False,
+    skip_graph: bool = False,
+    skip_ponytail: bool = False,
+    skip_caveman: bool = False,
+    pipeline_names: tuple[str, ...] | None = None,
+    extras: dict[str, Any] | None = None,
+) -> EngineResult:
+    """Build an :class:`ExecutionEngine`, run the pipeline, and return the result.
+
+    Parameters mirror the CLI flags; keyword arguments not consumed by
+    this function are forwarded to :func:`default_registry`.
+
+    Returns an :class:`EngineResult` that callers can render as text
+    or JSON.
+    """
+    import asyncio
+
+    engine_ctx = EngineContext(
+        prompt=prompt,
+        cwd=root,
+    )
+    if extras:
+        engine_ctx.extras.update(extras)
+
+    if not skip_caveman and caveman_optimizer is not None:
+        engine_ctx.extras["caveman_optimizer"] = caveman_optimizer
+    if not skip_graph and graph is not None:
+        engine_ctx.extras["graph"] = graph
+    if not skip_ponytail and optimizer is not None:
+        engine_ctx.extras["optimizer"] = optimizer
+    if provider is not None:
+        engine_ctx.extras["provider"] = provider
+    if retries:
+        engine_ctx.extras["retries"] = retries
+    if test_command is not None and not skip_tests:
+        engine_ctx.extras["test_command"] = test_command
+    engine_ctx.extras["test_timeout"] = test_timeout
+
+    registry = default_registry(
+        provider=provider,
+        optimizer=optimizer if not skip_ponytail else None,
+        caveman_optimizer=caveman_optimizer if not skip_caveman else None,
+        graph=graph if not skip_graph else None,
+        classifier=classifier,
+        router=router,
+        test_command=None if skip_tests else test_command,
+    )
+
+    names = pipeline_names or ExecutionEngine.DEFAULT_PIPELINE
+    engine = ExecutionEngine.from_registry(registry, names=names)
+
+    return asyncio.run(engine.run(engine_ctx))
+
+
+def engine_result_to_dict(result: EngineResult) -> dict[str, object]:
+    """Return a JSON-serializable view of an :class:`EngineResult`."""
+    ctx = result.context
+    return {
+        "success": result.success,
+        "cancelled": result.cancelled,
+        "failed_stage": result.failed_stage,
+        "error": result.error,
+        "prompt": ctx.prompt,
+        "run_id": ctx.run_id,
+        "intent": ctx.intent_analysis.intent.value if ctx.intent_analysis else None,
+        "intent_confidence": ctx.intent_analysis.confidence if ctx.intent_analysis else 0.0,
+        "retrieval_match_count": len(ctx.retrieval.matched_nodes) if ctx.retrieval else 0,
+        "model": ctx.model_selection.model if ctx.model_selection else None,
+        "provider": ctx.model_selection.provider if ctx.model_selection else None,
+        "diff_length": len(ctx.diff_text),
+        "applied_files": [str(p) for p in ctx.applied_files],
+        "test_returncode": ctx.test_returncode,
+        "fix_attempts": ctx.fix_attempts,
+        "stages": [
+            {
+                "name": log.stage,
+                "status": log.status,
+                "duration_seconds": log.duration_seconds,
+                "error": log.error,
+            }
+            for log in ctx.log
+        ],
+    }
+
+
+def render_engine_result(result: EngineResult) -> str:
+    """Return a human-readable summary of the engine run.
+
+    Format is similar to the build pipeline's ``build_summary`` but
+    reads from :class:`EngineContext` instead of :class:`BuildContext`.
+    """
+    ctx = result.context
+    lines: list[str] = []
+    lines.append(f"Goal: {ctx.prompt}")
+    if ctx.model_selection is not None:
+        ms = ctx.model_selection
+        lines.append(
+            f"Route: {ms.provider}/{ms.model} (mode={ms.mode}, "
+            f"in=${ms.cost_in:.5f}/1k, out=${ms.cost_out:.5f}/1k)"
+        )
+    if ctx.applied_files:
+        rel = [str(p.relative_to(ctx.cwd) if p.is_relative_to(ctx.cwd) else p) for p in ctx.applied_files]
+        lines.append(f"Files touched ({len(rel)}):")
+        for path in rel:
+            lines.append(f"  - {path}")
+    else:
+        lines.append("Files touched: (none)")
+    if ctx.test_returncode is None:
+        lines.append("Tests: skipped")
+    elif ctx.test_returncode == 0:
+        lines.append("Tests: passed")
+    else:
+        lines.append(f"Tests: FAILED (exit {ctx.test_returncode})")
+    total = sum(log.duration_seconds for log in ctx.log)
+    lines.append(f"Total time: {total:.2f}s across {len(ctx.log)} stages")
+    if result.error:
+        lines.append(f"Error: {result.error}")
+    return "\n".join(lines)
+
+
+__all__ = [
+    "engine_result_to_dict",
+    "render_engine_result",
+    "run_engine",
+]

forgecli/engine/stages/__init__.py

@@ -0,0 +1,33 @@
+"""Concrete Stage implementations for the Execution Engine.
+
+Each module in this package implements one or more :class:`Stage`
+protocol objects that wire into the engine's
+:attr:`~forgecli.engine.execution.ExecutionEngine.DEFAULT_PIPELINE`.
+
+Stages are thin adapters over the existing build pipeline functions
+in :mod:`forgecli.build` — they map between :class:`EngineContext`
+and :class:`BuildContext`, then delegate to the well-tested build
+functions.
+"""
+
+from forgecli.engine.stages.caveman_optimizer import CavemanOptimizerStage
+from forgecli.engine.stages.context_optimizer import ContextOptimizerStage
+from forgecli.engine.stages.execution_engine_stage import ExecutionEngineStage
+from forgecli.engine.stages.git_engine import GitEngineStage
+from forgecli.engine.stages.intent_analyzer import IntentAnalyzerStage
+from forgecli.engine.stages.model_router import ModelRouterStage
+from forgecli.engine.stages.planning_engine import PlanningEngineStage
+from forgecli.engine.stages.repository_analyzer import RepositoryAnalyzerStage
+from forgecli.engine.stages.validation_engine import ValidationEngineStage
+
+__all__ = [
+    "CavemanOptimizerStage",
+    "ContextOptimizerStage",
+    "ExecutionEngineStage",
+    "GitEngineStage",
+    "IntentAnalyzerStage",
+    "ModelRouterStage",
+    "PlanningEngineStage",
+    "RepositoryAnalyzerStage",
+    "ValidationEngineStage",
+]

forgecli/engine/stages/caveman_optimizer.py

@@ -0,0 +1,47 @@
+"""Stage 3 — Caveman Optimizer.
+
+Applies the Caveman ruleset to the user prompt to reduce token usage
+in LLM responses. Wraps :func:`forgecli.build.caveman_optimize.caveman_optimization`.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from forgecli.build import BuildContext
+from forgecli.build.caveman_optimize import caveman_optimization as _build_caveman_optimize
+from forgecli.engine.execution import StageContext, StageResult, StageStatus
+from forgecli.optimizer.caveman import CavemanPromptOptimizer
+
+
+class CavemanOptimizerStage:
+    """Optimize the prompt using Caveman rules."""
+
+    name = "caveman-optimizer"
+
+    def __init__(self, optimizer: CavemanPromptOptimizer | None = None) -> None:
+        self._optimizer = optimizer
+
+    async def __call__(self, context: StageContext) -> StageResult:
+        optimizer = self._optimizer or context.engine.extras.get("caveman_optimizer")
+        build_ctx = BuildContext(
+            prompt=context.engine.prompt,
+            root=Path(context.engine.cwd),
+        )
+        build_ctx.extras["caveman_optimizer"] = optimizer
+
+        build_ctx = await _build_caveman_optimize(build_ctx)
+
+        context.engine.caveman_optimized_request = build_ctx.caveman_optimized_request
+        context.engine.caveman_optimized_notes = build_ctx.caveman_optimized_notes
+
+        return StageResult(
+            status=StageStatus.SUCCEEDED,
+            data={
+                "notes": list(build_ctx.caveman_optimized_notes),
+            },
+            notes=build_ctx.caveman_optimized_notes or ("no caveman optimization applied",),
+        )
+
+
+__all__ = ["CavemanOptimizerStage"]

forgecli/engine/stages/context_optimizer.py

@@ -0,0 +1,44 @@
+"""Stage 3 — Context Optimizer.
+
+Applies the Ponytail ruleset to the user prompt. Wraps
+:func:`forgecli.build.optimize.ponytail_optimization`.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from forgecli.build import BuildContext
+from forgecli.build.optimize import ponytail_optimization as _build_optimize
+from forgecli.engine.execution import StageContext, StageResult, StageStatus
+from forgecli.optimizer.ponytail import PromptOptimizer
+
+
+class ContextOptimizerStage:
+    """Optimize the prompt using Ponytail rules."""
+
+    name = "context-optimizer"
+
+    def __init__(self, optimizer: PromptOptimizer | None = None) -> None:
+        self._optimizer = optimizer
+
+    async def __call__(self, context: StageContext) -> StageResult:
+        optimizer = self._optimizer or context.engine.extras.get("optimizer")
+        build_ctx = BuildContext(
+            prompt=context.engine.prompt,
+            root=Path(context.engine.cwd),
+        )
+        build_ctx.extras["optimizer"] = optimizer
+
+        build_ctx = await _build_optimize(build_ctx)
+
+        context.engine.optimized_request = build_ctx.optimized_request
+        context.engine.optimized_notes = build_ctx.optimized_notes
+
+        return StageResult(
+            status=StageStatus.SUCCEEDED,
+            data={
+                "notes": list(build_ctx.optimized_notes),
+            },
+            notes=build_ctx.optimized_notes or ("no optimization applied",),
+        )

forgecli/engine/stages/execution_engine_stage.py

@@ -0,0 +1,108 @@
+"""Stage 6 - Execution Engine.
+
+Invokes the LLM with the assembled prompt and extracts a unified diff
+from the response. Combines :func:`forgecli.build.llm.llm_call` and
+:func:`forgecli.build.diff_extract.diff_extraction` into a single stage.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from forgecli.build import BuildContext
+from forgecli.build.diff_extract import diff_extraction
+from forgecli.build.llm import llm_call
+from forgecli.engine.execution import StageContext, StageResult, StageStatus
+from forgecli.providers.base import ChatMessage, ChatRequest, Provider, Role
+from forgecli.providers.router import RouteDecision
+
+
+class ExecutionEngineStage:
+    """Send the prompt to the LLM and extract a diff."""
+
+    name = "execution-engine"
+
+    def __init__(self, provider: Provider | None = None) -> None:
+        self._provider = provider
+
+    async def __call__(self, context: StageContext) -> StageResult:
+        provider = self._provider or context.engine.extras.get("provider")
+        if provider is None:
+            return StageResult(
+                status=StageStatus.FAILED,
+                error="no provider available for LLM call",
+                notes=("no provider in extras or constructor",),
+            )
+
+        decision: RouteDecision | None = context.engine.extras.get("decision")
+        build_ctx = BuildContext(
+            prompt=context.engine.prompt,
+            root=Path(context.engine.cwd),
+            decision=decision,
+        )
+        if context.engine.retrieval is not None:
+            build_ctx.retrieval = context.engine.retrieval.context_text
+        if context.engine.optimized_request is not None:
+            build_ctx.optimized_request = context.engine.optimized_request
+            build_ctx.optimized_notes = context.engine.optimized_notes
+        # Merge caveman-optimized system prompt into the final request.
+        if (
+            context.engine.caveman_optimized_request is not None
+            and context.engine.optimized_request is not None
+        ):
+            build_ctx.optimized_request = _merge_caveman_request(
+                context.engine.caveman_optimized_request,
+                context.engine.optimized_request,
+            )
+        elif context.engine.caveman_optimized_request is not None:
+            build_ctx.optimized_request = context.engine.caveman_optimized_request
+        retries = int(context.engine.extras.get("retries", 0))
+        build_ctx.extras["provider"] = provider
+        build_ctx.extras["retries"] = retries
+
+        build_ctx = await llm_call(build_ctx)
+        build_ctx = await diff_extraction(build_ctx)
+
+        context.engine.response = build_ctx.response
+        context.engine.diff_text = build_ctx.diff_text
+
+        diff_len = len(build_ctx.diff_text)
+        notes: tuple[str, ...] = ()
+        if diff_len > 0:
+            notes = (f"extracted {diff_len}-char diff",)
+        else:
+            notes = ("no diff found in LLM response",)
+
+        return StageResult(
+            status=StageStatus.SUCCEEDED,
+            data={
+                "diff_length": diff_len,
+                "has_response": build_ctx.response is not None,
+            },
+            notes=notes,
+        )
+
+
+def _merge_caveman_request(
+    caveman_req: ChatRequest,
+    ponytail_req: ChatRequest,
+) -> ChatRequest:
+    """Merge caveman and ponytail system prompts into one request."""
+    caveman_sys = [
+        m for m in caveman_req.messages if m.role is Role.SYSTEM
+    ]
+    ponytail_sys = [
+        m for m in ponytail_req.messages if m.role is Role.SYSTEM
+    ]
+    other_messages = [
+        m for m in ponytail_req.messages if m.role is not Role.SYSTEM
+    ]
+
+    merged_sys_content = "\n\n".join(
+        m.content for m in [*caveman_sys, *ponytail_sys] if m.content.strip()
+    )
+    merged_messages: list[ChatMessage] = [
+        ChatMessage(role=Role.SYSTEM, content=merged_sys_content),
+        *other_messages,
+    ]
+    return ponytail_req.model_copy(update={"messages": merged_messages})

forgecli/engine/stages/git_engine.py

@@ -0,0 +1,30 @@
+"""Stage 8 — Git Engine (placeholder).
+
+Stages and optionally pushes the applied changes. Currently
+a pass-through that records intent; actual git integration will follow.
+"""
+
+from __future__ import annotations
+
+from forgecli.engine.execution import StageContext, StageResult, StageStatus
+
+
+class GitEngineStage:
+    """Stage and push applied changes."""
+
+    name = "git-engine"
+
+    async def __call__(self, context: StageContext) -> StageResult:
+        if not context.engine.applied_files:
+            return StageResult(
+                status=StageStatus.SKIPPED,
+                notes=("no files to stage",),
+                data={"staged": False},
+            )
+
+        context.engine.staged = True
+        return StageResult(
+            status=StageStatus.SUCCEEDED,
+            notes=("files staged (placeholder)",),
+            data={"staged": True},
+        )

forgecli/engine/stages/intent_analyzer.py

@@ -0,0 +1,38 @@
+"""Stage 1 — Intent Analyzer.
+
+Classifies the user's prompt into an :class:`Intent` using the
+:class:`HeuristicIntentClassifier`. The result is stored in
+``context.engine.intent_analysis``.
+"""
+
+from __future__ import annotations
+
+from forgecli.engine.context import IntentAnalysis
+from forgecli.engine.execution import StageContext, StageResult, StageStatus
+from forgecli.orchestrator import HeuristicIntentClassifier
+from forgecli.plugins import IntentClassifier
+
+
+class IntentAnalyzerStage:
+    """Classify the user prompt into an :class:`Intent`."""
+
+    name = "intent-analyzer"
+
+    def __init__(self, classifier: IntentClassifier | None = None) -> None:
+        self._classifier = classifier or HeuristicIntentClassifier()
+
+    async def __call__(self, context: StageContext) -> StageResult:
+        prediction = self._classifier.classify(context.engine.prompt)
+        context.engine.intent_analysis = IntentAnalysis(
+            intent=prediction.intent,
+            confidence=prediction.confidence,
+            rationale=prediction.rationale,
+        )
+        return StageResult(
+            status=StageStatus.SUCCEEDED,
+            data={
+                "intent": prediction.intent.value,
+                "confidence": prediction.confidence,
+            },
+            notes=prediction.rationale,
+        )

forgecli/engine/stages/model_router.py

@@ -0,0 +1,66 @@
+"""Stage 5 — Model Router.
+
+Resolves the user's model choice (or "auto") into a concrete
+(provider, model) pair using :class:`ModelRouter`. The result
+is stored in ``context.engine.model_selection``.
+"""
+
+from __future__ import annotations
+
+from forgecli.engine.context import ModelSelection
+from forgecli.engine.execution import StageContext, StageResult, StageStatus
+from forgecli.providers.router import ModelCapabilities, ModelRouter
+from forgecli.providers.router_state import RouterState, load_state
+
+
+class ModelRouterStage:
+    """Resolve the model choice and store the selection."""
+
+    name = "model-router"
+
+    def __init__(
+        self,
+        router: ModelRouter | None = None,
+        state: RouterState | None = None,
+    ) -> None:
+        self._router = router or ModelRouter()
+        self._state = state
+
+    async def __call__(self, context: StageContext) -> StageResult:
+        state = self._state or _resolve_state(context)
+        choice = state.choice
+        capabilities: ModelCapabilities = context.engine.extras.get(
+            "model_capabilities", ModelCapabilities()
+        )
+        decision = self._router.select(choice, capabilities=capabilities)
+
+        context.engine.model_selection = ModelSelection(
+            provider=decision.provider_name,
+            model=decision.model,
+            mode=decision.mode.value,
+            cost_in=decision.cost_in,
+            cost_out=decision.cost_out,
+        )
+        context.engine.extras["decision"] = decision
+
+        return StageResult(
+            status=StageStatus.SUCCEEDED,
+            data={
+                "provider": decision.provider_name,
+                "model": decision.model,
+                "mode": decision.mode.value,
+                "cost_in": decision.cost_in,
+                "cost_out": decision.cost_out,
+            },
+            notes=(
+                f"route: {decision.provider_name}/{decision.model} "
+                f"(mode={decision.mode.value})",
+            ),
+        )
+
+
+def _resolve_state(context: StageContext) -> RouterState:
+    paths = context.engine.extras.get("paths")
+    if paths is not None:
+        return load_state(paths.data_dir / "router.json")
+    return RouterState()

forgecli/engine/stages/planning_engine.py

@@ -0,0 +1,45 @@
+"""Stage 4 — Planning Engine (placeholder).
+
+Generates a software plan using :func:`forgecli.planner.software.build_software_plan`.
+Stores the plan in ``context.engine.plan``.
+"""
+
+from __future__ import annotations
+
+from forgecli.engine.execution import StageContext, StageResult, StageStatus
+from forgecli.planner.software import PlannerOptions, build_software_plan
+
+
+class PlanningEngineStage:
+    """Generate a deterministic software plan from the prompt."""
+
+    name = "planning-engine"
+
+    def __init__(self, enabled: bool = True) -> None:
+        self._enabled = enabled
+
+    async def __call__(self, context: StageContext) -> StageResult:
+        if not self._enabled:
+            return StageResult(
+                status=StageStatus.SKIPPED,
+                notes=("planning disabled",),
+                data={"skipped": True},
+            )
+
+        prompt = context.engine.prompt
+        options = context.engine.extras.get("planner_options", PlannerOptions())
+        plan = build_software_plan(prompt, options)
+        context.engine.plan = plan
+
+        return StageResult(
+            status=StageStatus.SUCCEEDED,
+            data={
+                "summary": plan.summary,
+                "milestones": len(plan.milestones),
+                "tasks": len(plan.tasks) if hasattr(plan, "tasks") else 0,
+            },
+            notes=(
+                f"plan: {plan.summary}",
+                f"{len(plan.milestones)} milestones",
+            ),
+        )

forgecli/engine/stages/repository_analyzer.py

@@ -0,0 +1,54 @@
+"""Stage 2 — Repository Analyzer.
+
+Queries the configured :class:`RepositoryGraph` for nodes relevant to
+the user prompt. Wraps :func:`forgecli.build.retrieval.graphify_retrieval`.
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+from forgecli.build import BuildContext
+from forgecli.build.retrieval import graphify_retrieval as _build_retrieval
+from forgecli.engine.context import RetrievalResult
+from forgecli.engine.execution import StageContext, StageResult, StageStatus
+from forgecli.graph.repository import RepositoryGraph
+
+
+class RepositoryAnalyzerStage:
+    """Query the repository graph for context relevant to the prompt."""
+
+    name = "repository-analyzer"
+
+    def __init__(self, graph: RepositoryGraph | None = None) -> None:
+        self._graph = graph
+
+    async def __call__(self, context: StageContext) -> StageResult:
+        graph = self._graph or context.engine.extras.get("graph")
+        build_ctx = BuildContext(
+            prompt=context.engine.prompt,
+            root=Path(context.engine.cwd),
+        )
+        build_ctx.extras["graph"] = graph
+
+        started = time.perf_counter()
+        build_ctx = await _build_retrieval(build_ctx)
+        elapsed = time.perf_counter() - started
+
+        context.engine.retrieval = RetrievalResult(
+            query=context.engine.prompt,
+            context_text=build_ctx.retrieval,
+            notes=(
+                f"retrieved in {elapsed:.3f}s",
+                f"{len(build_ctx.retrieval)} chars",
+            ),
+        )
+        return StageResult(
+            status=StageStatus.SUCCEEDED,
+            data={
+                "retrieval_length": len(build_ctx.retrieval),
+                "elapsed_seconds": round(elapsed, 3),
+            },
+            notes=(f"retrieved {len(build_ctx.retrieval)} chars of context",),
+        )