forgeoptimizer 1.0.0__py3-none-any.whl

forgecli/core/errors.py

@@ -0,0 +1,27 @@
+"""Typed exception hierarchy for ForgeCLI."""
+
+from __future__ import annotations
+
+
+class ForgeCLIError(Exception):
+    """Base class for all ForgeCLI-specific errors."""
+
+
+class ConfigError(ForgeCLIError):
+    """Raised when configuration cannot be loaded or validated."""
+
+
+class ProviderError(ForgeCLIError):
+    """Raised on AI provider failures (network, auth, schema)."""
+
+
+class GitError(ForgeCLIError):
+    """Raised on Git-related failures (missing repo, bad ref, etc)."""
+
+
+class PluginError(ForgeCLIError):
+    """Raised on plugin discovery or lifecycle failures."""
+
+
+class PipelineError(ForgeCLIError):
+    """Raised when a builder/review/planner pipeline cannot complete."""

forgecli/core/events.py

@@ -0,0 +1,67 @@
+"""A tiny pub/sub event bus used for decoupled logging and lifecycle hooks."""
+
+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 typing import Any
+
+Subscriber = Callable[["Event"], "None | Awaitable[None]"]
+
+
+@dataclass(frozen=True)
+class Event:
+    """An immutable event payload."""
+
+    name: str
+    payload: dict[str, Any] = field(default_factory=dict)
+    timestamp: datetime = field(default_factory=lambda: datetime.now(UTC))
+
+
+class EventBus:
+    """Asynchronous-first pub/sub bus.
+
+    Synchronous subscribers are invoked inline; async subscribers are
+    scheduled via :func:`asyncio.create_task`. The bus is intentionally
+    simple: subscribers cannot block the publisher and ordering is
+    best-effort.
+    """
+
+    def __init__(self) -> None:
+        self._subscribers: dict[str, list[Subscriber]] = {}
+        self._pending_tasks: set[asyncio.Task[Any]] = set()
+
+    def subscribe(self, name: str, callback: Subscriber) -> None:
+        """Register ``callback`` for events named ``name``."""
+        self._subscribers.setdefault(name, []).append(callback)
+
+    def unsubscribe(self, name: str, callback: Subscriber) -> None:
+        bucket = self._subscribers.get(name)
+        if not bucket:
+            return
+        with contextlib.suppress(ValueError):
+            bucket.remove(callback)
+
+    async def publish(self, name: str, **payload: Any) -> None:
+        """Publish an event, dispatching to all registered subscribers."""
+        event = Event(name=name, payload=dict(payload))
+        for callback in list(self._subscribers.get(name, ())):
+            result = callback(event)
+            if asyncio.iscoroutine(result):
+                await result
+
+    def emit(self, name: str, **payload: Any) -> None:
+        """Synchronous variant of :meth:`publish`; async subs are not awaited."""
+        event = Event(name=name, payload=dict(payload))
+        for callback in list(self._subscribers.get(name, ())):
+            result = callback(event)
+            if asyncio.iscoroutine(result):
+                # Fire-and-forget; require an event loop to be running.
+                with contextlib.suppress(RuntimeError):
+                    loop = asyncio.get_running_loop()
+                    task = loop.create_task(result)
+                    self._pending_tasks.add(task)
+                    task.add_done_callback(self._pending_tasks.discard)

forgecli/core/logging.py

@@ -0,0 +1,47 @@
+"""Logging configuration built on the standard library ``logging`` package."""
+
+from __future__ import annotations
+
+import logging
+import sys
+from typing import Final
+
+_LOG_FORMAT: Final[str] = "%(asctime)s [%(levelname)s] %(name)s: %(message)s"
+_configured = False
+
+
+def configure_logging(level: str = "INFO") -> None:
+    """Configure root logging once for the lifetime of the process."""
+    global _configured
+    if _configured:
+        new_level = _coerce_level(level)
+        if logging.getLogger().level != logging.DEBUG or new_level == logging.DEBUG:
+            logging.getLogger().setLevel(new_level)
+        return
+
+    handler = logging.StreamHandler(stream=sys.stderr)
+    handler.setFormatter(logging.Formatter(_LOG_FORMAT))
+
+    root = logging.getLogger()
+    root.handlers.clear()
+    root.addHandler(handler)
+    root.setLevel(_coerce_level(level))
+
+    # Quiet noisy third-party loggers.
+    for noisy in ("httpx", "httpcore", "git", "urllib3"):
+        logging.getLogger(noisy).setLevel(logging.WARNING)
+
+    _configured = True
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Return a configured logger, configuring root logging lazily."""
+    if not _configured:
+        configure_logging()
+    return logging.getLogger(name)
+
+
+def _coerce_level(level: str) -> int:
+    if level.isdigit():
+        return int(level)
+    return logging.getLevelName(level.upper())

forgecli/core/models.py

@@ -0,0 +1,159 @@
+"""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,56 @@
+"""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,119 @@
+"""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",
+]