forgeoptimizer 0.1.0__py3-none-any.whl

forgecli/core/models.py

@@ -0,0 +1,214 @@
+"""Modular registry for all supported AI models in ForgeCLI."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+ModelTier = Literal["latest", "recommended", "normal", "legacy", "deprecated"]
+
+
+@dataclass(frozen=True)
+class ModelDef:
+    id: str
+    display_name: str
+    tier: ModelTier
+    provider: str  # Lowercase provider name, e.g., 'openai', 'groq'
+
+
+# Single source of truth for the model catalog
+MODEL_CATALOG: list[ModelDef] = [
+    # ---------------------------------------------------------------------------
+    # OpenAI
+    # ---------------------------------------------------------------------------
+    ModelDef(id="gpt-5.5", display_name="GPT-5.5", tier="latest", provider="openai"),
+    ModelDef(id="gpt-5", display_name="GPT-5", tier="recommended", provider="openai"),
+    ModelDef(id="gpt-5-mini", display_name="GPT-5 Mini", tier="normal", provider="openai"),
+    ModelDef(id="gpt-4.1", display_name="GPT-4.1", tier="legacy", provider="openai"),
+    ModelDef(id="gpt-4.1-mini", display_name="GPT-4.1 Mini", tier="legacy", provider="openai"),
+    ModelDef(id="gpt-4o", display_name="GPT-4o", tier="legacy", provider="openai"),
+    ModelDef(id="gpt-4o-mini", display_name="GPT-4o Mini", tier="legacy", provider="openai"),
+    ModelDef(id="gpt-4-turbo", display_name="GPT-4 Turbo", tier="legacy", provider="openai"),
+    ModelDef(id="o1", display_name="o1", tier="legacy", provider="openai"),
+    ModelDef(id="o1-preview", display_name="o1 Preview", tier="legacy", provider="openai"),
+    ModelDef(id="o1-mini", display_name="o1 Mini", tier="legacy", provider="openai"),
+    # ---------------------------------------------------------------------------
+    # Anthropic
+    # ---------------------------------------------------------------------------
+    ModelDef(
+        id="claude-opus-4.8", display_name="Claude Opus 4.8", tier="latest", provider="anthropic"
+    ),
+    ModelDef(
+        id="claude-opus-4.6", display_name="Claude Opus 4.6", tier="latest", provider="anthropic"
+    ),
+    ModelDef(
+        id="claude-sonnet-4.6",
+        display_name="Claude Sonnet 4.6",
+        tier="recommended",
+        provider="anthropic",
+    ),
+    ModelDef(
+        id="claude-sonnet-4.5",
+        display_name="Claude Sonnet 4.5",
+        tier="legacy",
+        provider="anthropic",
+    ),
+    ModelDef(
+        id="claude-haiku-4.5", display_name="Claude Haiku 4.5", tier="legacy", provider="anthropic"
+    ),
+    ModelDef(
+        id="claude-3-5-sonnet-latest",
+        display_name="Claude 3.5 Sonnet",
+        tier="legacy",
+        provider="anthropic",
+    ),
+    ModelDef(
+        id="claude-3-5-haiku-latest",
+        display_name="Claude 3.5 Haiku",
+        tier="legacy",
+        provider="anthropic",
+    ),
+    ModelDef(
+        id="claude-3-opus-latest", display_name="Claude 3 Opus", tier="legacy", provider="anthropic"
+    ),
+    # ---------------------------------------------------------------------------
+    # Google Gemini
+    # ---------------------------------------------------------------------------
+    ModelDef(
+        id="gemini-2.5-pro", display_name="Gemini 2.5 Pro", tier="recommended", provider="google"
+    ),
+    ModelDef(
+        id="gemini-2.5-flash",
+        display_name="Gemini 2.5 Flash",
+        tier="recommended",
+        provider="google",
+    ),
+    ModelDef(
+        id="gemini-2.5-flash-lite",
+        display_name="Gemini 2.5 Flash Lite",
+        tier="normal",
+        provider="google",
+    ),
+    ModelDef(
+        id="gemini-2.0-flash", display_name="Gemini 2.0 Flash", tier="legacy", provider="google"
+    ),
+    ModelDef(id="gemini-1.5-pro", display_name="Gemini 1.5 Pro", tier="legacy", provider="google"),
+    ModelDef(
+        id="gemini-1.5-flash", display_name="Gemini 1.5 Flash", tier="legacy", provider="google"
+    ),
+    ModelDef(
+        id="gemini-2.0-flash-exp",
+        display_name="Gemini 2.0 Flash Exp",
+        tier="legacy",
+        provider="google",
+    ),
+    # ---------------------------------------------------------------------------
+    # OpenRouter
+    # ---------------------------------------------------------------------------
+    ModelDef(id="glm-5.2", display_name="GLM 5.2", tier="normal", provider="openrouter"),
+    ModelDef(id="deepseek-v3", display_name="DeepSeek V3", tier="normal", provider="openrouter"),
+    ModelDef(id="deepseek-r1", display_name="DeepSeek R1", tier="normal", provider="openrouter"),
+    ModelDef(id="qwen3-coder", display_name="Qwen3 Coder", tier="normal", provider="openrouter"),
+    ModelDef(id="qwen3-32b", display_name="Qwen3 32B", tier="normal", provider="openrouter"),
+    ModelDef(id="kimi-k2", display_name="Kimi K2", tier="normal", provider="openrouter"),
+    ModelDef(
+        id="llama-4-maverick", display_name="Llama 4 Maverick", tier="normal", provider="openrouter"
+    ),
+    ModelDef(
+        id="llama-4-scout", display_name="Llama 4 Scout", tier="normal", provider="openrouter"
+    ),
+    ModelDef(
+        id="llama-3.3-70b", display_name="Llama 3.3 70B", tier="normal", provider="openrouter"
+    ),
+    ModelDef(id="gemma-3", display_name="Gemma 3", tier="normal", provider="openrouter"),
+    ModelDef(id="devstral", display_name="Devstral", tier="normal", provider="openrouter"),
+    ModelDef(id="codestral", display_name="Codestral", tier="normal", provider="openrouter"),
+    ModelDef(id="phi-4", display_name="Phi-4", tier="normal", provider="openrouter"),
+    ModelDef(
+        id="mistral-large", display_name="Mistral Large", tier="normal", provider="openrouter"
+    ),
+    # ---------------------------------------------------------------------------
+    # Groq
+    # ---------------------------------------------------------------------------
+    ModelDef(id="llama-4-scout", display_name="Llama 4 Scout", tier="normal", provider="groq"),
+    ModelDef(id="deepseek-r1", display_name="DeepSeek R1", tier="normal", provider="groq"),
+    ModelDef(id="qwen3-32b", display_name="Qwen3 32B", tier="normal", provider="groq"),
+    ModelDef(id="gemma-3", display_name="Gemma 3", tier="normal", provider="groq"),
+    # ---------------------------------------------------------------------------
+    # Mistral
+    # ---------------------------------------------------------------------------
+    ModelDef(id="mistral-large", display_name="Mistral Large", tier="normal", provider="mistral"),
+    ModelDef(id="magistral", display_name="Magistral", tier="normal", provider="mistral"),
+    ModelDef(id="mistral-small", display_name="Mistral Small", tier="normal", provider="mistral"),
+    ModelDef(id="codestral", display_name="Codestral", tier="normal", provider="mistral"),
+    # ---------------------------------------------------------------------------
+    # MiniMax
+    # ---------------------------------------------------------------------------
+    ModelDef(
+        id="abab6.5g-chat", display_name="Abab 6.5G Chat", tier="recommended", provider="minimax"
+    ),
+    ModelDef(id="abab6.5-chat", display_name="Abab 6.5 Chat", tier="legacy", provider="minimax"),
+    # ---------------------------------------------------------------------------
+    # xAI (Grok)
+    # ---------------------------------------------------------------------------
+    ModelDef(id="grok-2", display_name="Grok 2", tier="recommended", provider="xai"),
+    ModelDef(id="grok-beta", display_name="Grok Beta", tier="latest", provider="xai"),
+    # ---------------------------------------------------------------------------
+    # Together AI
+    # ---------------------------------------------------------------------------
+    ModelDef(
+        id="llama-3.1-70b", display_name="Llama 3.1 70B", tier="recommended", provider="together"
+    ),
+    ModelDef(
+        id="llama-3.1-405b", display_name="Llama 3.1 405B", tier="latest", provider="together"
+    ),
+    # ---------------------------------------------------------------------------
+    # Fireworks AI
+    # ---------------------------------------------------------------------------
+    ModelDef(
+        id="llama-3.1-70b", display_name="Llama 3.1 70B", tier="recommended", provider="fireworks"
+    ),
+    ModelDef(
+        id="llama-3.1-405b", display_name="Llama 3.1 405B", tier="latest", provider="fireworks"
+    ),
+    # ---------------------------------------------------------------------------
+    # Cohere
+    # ---------------------------------------------------------------------------
+    ModelDef(id="command-r-plus", display_name="Command R+", tier="recommended", provider="cohere"),
+    ModelDef(id="command-r", display_name="Command R", tier="normal", provider="cohere"),
+    # ---------------------------------------------------------------------------
+    # NVIDIA NIM
+    # ---------------------------------------------------------------------------
+    ModelDef(
+        id="llama-3.1-70b", display_name="Llama 3.1 70B", tier="recommended", provider="nvidia"
+    ),
+    ModelDef(id="llama-3.1-405b", display_name="Llama 3.1 405B", tier="latest", provider="nvidia"),
+    # ---------------------------------------------------------------------------
+    # Ollama
+    # ---------------------------------------------------------------------------
+    ModelDef(id="llama3", display_name="Llama 3", tier="normal", provider="ollama"),
+    # ---------------------------------------------------------------------------
+    # LM Studio
+    # ---------------------------------------------------------------------------
+    ModelDef(id="local-model", display_name="Local Model", tier="normal", provider="lmstudio"),
+    # ---------------------------------------------------------------------------
+    # vLLM
+    # ---------------------------------------------------------------------------
+    ModelDef(id="local-model", display_name="Local Model", tier="normal", provider="vllm"),
+]
+
+
+def get_model_def(model_id: str, provider: str | None = None) -> ModelDef | None:
+    """Retrieve the model definition by model ID, optionally filtering by provider."""
+    model_id_lower = model_id.lower().strip()
+    provider_lower = provider.lower().strip() if provider else None
+    for m in MODEL_CATALOG:
+        if m.id == model_id_lower and (provider_lower is None or m.provider == provider_lower):
+            return m
+    return None
+
+
+def get_display_name(model_id: str, provider: str | None = None) -> str:
+    """Get the friendly display name for a model, defaulting to the ID itself."""
+    m = get_model_def(model_id, provider)
+    return m.display_name if m else model_id

forgecli/core/plugins.py

@@ -0,0 +1,54 @@
+"""Plugin discovery and lifecycle.
+
+The plugin system is intentionally tiny for the scaffold: plugins are
+loaded by entry point group (``forgecli.plugins``) and must implement
+:class:`Plugin`. A real implementation may also support directory
+plugins (``plugins_dir``) but the interface is the same.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from importlib import metadata
+from typing import Any
+
+from forgecli.core.context import AppContext
+from forgecli.core.errors import PluginError
+
+
+class Plugin(ABC):
+    """Base class for ForgeCLI plugins."""
+
+    name: str = "plugin"
+
+    @abstractmethod
+    def configure(self, context: AppContext) -> None:
+        """Register services, commands, providers, etc. on ``context``."""
+
+
+def discover_plugins(group: str = "forgecli.plugins") -> list[Plugin]:
+    """Discover installed plugins via the ``group`` entry point."""
+    plugins: list[Plugin] = []
+    try:
+        entries = metadata.entry_points(group=group)
+    except Exception as exc:
+        raise PluginError(f"Plugin discovery failed: {exc}") from exc
+    for ep in entries:
+        try:
+            plugin_cls = ep.load()
+            plugin = plugin_cls()  # type: ignore[call-arg]
+        except Exception as exc:
+            raise PluginError(f"Failed to load plugin {ep.name!r}: {exc}") from exc
+        if not isinstance(plugin, Plugin):
+            raise PluginError(f"Plugin {ep.name!r} must subclass forgecli.plugins.Plugin")
+        plugins.append(plugin)
+    return plugins
+
+
+def install_plugins(context: AppContext, plugins: list[Plugin]) -> None:
+    """Configure each plugin against ``context``."""
+    for plugin in plugins:
+        plugin.configure(context)
+
+
+__all__ = ["Any", "Plugin", "discover_plugins", "install_plugins"]

forgecli/core/service.py

@@ -0,0 +1,22 @@
+"""Composable service lifecycle base class."""
+
+from __future__ import annotations
+
+from forgecli.core.logging import get_logger
+
+
+class Service:
+    """Base class for application services with structured logging."""
+
+    name: str = "service"
+
+    def __init__(self) -> None:
+        self.log = get_logger(f"forgecli.{self.name}")
+
+    async def start(self) -> None:  # pragma: no cover - placeholder
+        """Bring the service online. Override in subclasses."""
+        self.log.debug("start() called (no-op)")
+
+    async def stop(self) -> None:  # pragma: no cover - placeholder
+        """Tear the service down. Override in subclasses."""
+        self.log.debug("stop() called (no-op)")

forgecli/docs/__init__.py

@@ -0,0 +1,5 @@
+"""Auto-generated project documentation."""
+
+from forgecli.docs.generator import generate_docs
+
+__all__ = ["generate_docs"]

forgecli/docs/generator.py

@@ -0,0 +1,115 @@
+"""Auto-generate project documentation from the Graphify knowledge graph.
+
+The generator walks the project, asks Graphify for a snapshot, and
+emits a Markdown report at ``docs/OVERVIEW.md`` with:
+
+* a module-by-module summary derived from the graph nodes;
+* the file tree of the project;
+* a flat list of every symbol with its location.
+
+The output is intentionally simple: the goal is to give an LLM
+(or a human) a starting point for richer docs.
+"""
+
+from __future__ import annotations
+
+from datetime import date
+from pathlib import Path
+
+from forgecli.core.context import AppContext
+from forgecli.graph.backend_graphify import GraphifyRepositoryGraph
+from forgecli.utils.fs import ensure_dir
+
+_INTRO_TEMPLATE = """\
+# {project} — Auto-generated overview
+
+_Generated on {today} by `forge docs`._
+
+This document is a starting point: it summarises the module layout
+and lists every symbol the Graphify knowledge graph knows about.
+For deeper documentation, run `forge plan`, `forge build`, or
+`forge explain` on individual modules.
+
+"""
+
+
+def generate_docs(context: AppContext, *, output: Path | None = None) -> Path:
+    """Generate the overview file and return its path."""
+    root = context.cwd
+    target = output or (root / "docs" / "OVERVIEW.md")
+    ensure_dir(target.parent)
+
+    graph = GraphifyRepositoryGraph(root=root)
+    snapshot = graph._cached  # may be None; load() if needed.
+
+    # Build a tiny ad-hoc snapshot by re-walking the project.
+    nodes = _walk_nodes(root)
+    communities = _community_buckets(nodes)
+
+    lines: list[str] = [
+        _INTRO_TEMPLATE.format(project=root.name, today=date.today().isoformat()),
+    ]
+    lines.append("## Modules\n")
+    for community, members in sorted(communities.items()):
+        lines.append(f"### {community}\n")
+        for node in sorted(members, key=lambda n: str(n["path"])):
+            location = f"`{node['path']}:{node['line']}`" if node["line"] else f"`{node['path']}`"
+            lines.append(f"- {node['label']} — {location}")
+        lines.append("")
+    if not nodes:
+        lines.append("_No indexed symbols found._\n")
+    target.write_text("\n".join(lines).rstrip() + "\n", encoding="utf-8")
+    _ = snapshot  # silence unused
+    return target
+
+
+def _walk_nodes(root: Path) -> list[dict[str, object]]:
+    """Build a small node list from the project tree.
+
+    This is a *fallback* when Graphify hasn't been run. The docs
+    generator is meant to be cheap and offline; it doesn't shell out
+    to the Graphify CLI.
+    """
+    nodes: list[dict[str, object]] = []
+    for path in sorted(root.rglob("*.py")):
+        if any(part.startswith(".") for part in path.parts):
+            continue
+        if any(part in {"__pycache__", "node_modules", ".venv", "venv"} for part in path.parts):
+            continue
+        rel = path.relative_to(root)
+        try:
+            text = path.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        nodes.append({"path": str(rel), "label": path.name, "line": 1})
+        for index, line in enumerate(text.splitlines(), start=1):
+            stripped = line.lstrip()
+            if stripped.startswith(("def ", "class ", "async def ")):
+                name = _extract_symbol_name(stripped)
+                if name:
+                    nodes.append({"path": str(rel), "label": name, "line": index})
+    return nodes
+
+
+def _extract_symbol_name(line: str) -> str | None:
+    """Return the symbol name from a ``def foo(...)`` / ``class Foo:`` line."""
+    line = line.strip()
+    for prefix in ("async def ", "def ", "class "):
+        if line.startswith(prefix):
+            rest = line[len(prefix) :]
+            return rest.split("(", 1)[0].split(":", 1)[0].strip() or None
+    return None
+
+
+def _community_buckets(nodes: list[dict[str, object]]) -> dict[str, list[dict[str, object]]]:
+    """Group nodes by their top-level directory (the "module")."""
+    buckets: dict[str, list[dict[str, object]]] = {}
+    for node in nodes:
+        path = str(node["path"])
+        parts = path.split("/")
+        module = parts[0] if len(parts) > 1 else path
+        buckets.setdefault(module, []).append(node)
+    return buckets
+
+
+__all__ = ["generate_docs"]

forgecli/engine/__init__.py

@@ -0,0 +1,105 @@
+"""The ForgeCLI Execution Engine.
+
+This package defines the *contract* for every orchestration stage
+in ForgeCLI. The pipeline is a fixed sequence of eight stages:
+
+    1. Intent Analyzer        — turn the prompt into an Intent
+    2. Repository Analyzer   — query Graphify for relevant context
+    3. Context Optimizer     — apply Ponytail to the prompt + context
+    4. Planning Engine       — produce a SoftwarePlan
+    5. Model Router          — pick (provider, model) for the call
+    6. Execution Engine      — invoke the LLM, extract a diff
+    7. Validation Engine     — apply the diff + run tests + auto-fix
+    8. Git Engine            — stage / push the changes
+
+Every stage is an independent object behind the :class:`Stage`
+Protocol. The :class:`ExecutionEngine` runs them in order, emits
+structured events, supports retries, cancellation, and plugin
+hooks. No business logic lives in this package — the actual
+implementations live in :mod:`forgecli.engine.stages` and may be
+replaced by plugins.
+"""
+
+from forgecli.engine.context import (
+    EngineContext,
+    IntentAnalysis,
+    ModelSelection,
+    RetrievalResult,
+    StageLog,
+)
+from forgecli.engine.defaults import (
+    default_registry,
+)
+from forgecli.engine.events import (
+    EngineCancelledError,
+    EngineEvent,
+    EventBus,
+    LogLevel,
+    ProgressEvent,
+    StageEvent,
+    TextLogEvent,
+)
+from forgecli.engine.execution import (
+    EngineResult,
+    ExecutionEngine,
+    PipelineBuilder,
+    Stage,
+    StageContext,
+    StageRegistry,
+    StageResult,
+    StageStatus,
+)
+from forgecli.engine.plugins import (
+    EnginePluginFactory,
+    HookManager,
+    PluginHook,
+    register_plugin,
+    stage_as_plugin,
+)
+from forgecli.engine.stages import (
+    ContextOptimizerStage,
+    ExecutionEngineStage,
+    GitEngineStage,
+    IntentAnalyzerStage,
+    ModelRouterStage,
+    PlanningEngineStage,
+    RepositoryAnalyzerStage,
+    ValidationEngineStage,
+)
+
+__all__ = [
+    "ContextOptimizerStage",
+    "EngineCancelledError",
+    "EngineContext",
+    "EngineEvent",
+    "EnginePluginFactory",
+    "EngineResult",
+    "EventBus",
+    "ExecutionEngine",
+    "ExecutionEngineStage",
+    "GitEngineStage",
+    "HookManager",
+    "IntentAnalysis",
+    "IntentAnalyzerStage",
+    "LogLevel",
+    "ModelRouterStage",
+    "ModelSelection",
+    "PipelineBuilder",
+    "PlanningEngineStage",
+    "PluginHook",
+    "ProgressEvent",
+    "RepositoryAnalyzerStage",
+    "RetrievalResult",
+    "Stage",
+    "StageContext",
+    "StageEvent",
+    "StageLog",
+    "StageRegistry",
+    "StageResult",
+    "StageStatus",
+    "TextLogEvent",
+    "ValidationEngineStage",
+    "default_registry",
+    "register_plugin",
+    "stage_as_plugin",
+]

forgecli/engine/context.py

@@ -0,0 +1,163 @@
+"""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",
+]