forgeoptimizer 0.1.0__py3-none-any.whl

forgecli/plugins/__init__.py

@@ -0,0 +1,249 @@
+"""Plugin extension points for ForgeCLI.
+
+A plugin is a Python package that exposes one or more of:
+
+* :class:`Workflow` — a named, executable unit that orchestrates
+  the standard pipeline stages (retrieval, optimization, LLM call,
+  apply, test, summary) in a custom way. The top-level ``forge``
+  command dispatches to a Workflow based on the user's prompt and
+  the current :class:`Intent`.
+* :class:`Provider` — an AI provider. The router picks from registered
+  providers based on the user's model choice.
+* :class:`PromptOptimizer` — a prompt-rewriting strategy. Selected by
+  the configured intensity.
+* :class:`Analyzer` — a code-review analyzer. The review command
+  runs every registered analyzer.
+* :class:`IntentClassifier` — a plugin that returns a high-level
+  :class:`Intent` for a given prompt (e.g. "build", "ask", "plan").
+  Used by the top-level ``forge`` command.
+
+Plugins are discovered via the ``forgecli.plugins`` entry-point
+group; see :func:`discover_plugins`. A plugin's ``configure``
+hook is invoked once at startup with the active
+:class:`~forgecli.core.context.AppContext` so it can register
+its own commands, providers, or analyzers.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import TYPE_CHECKING, Any
+
+from forgecli.core.context import AppContext
+from forgecli.providers.base import Provider
+from forgecli.review.analyzer import Analyzer
+
+if TYPE_CHECKING:
+    from forgecli.engine.execution import Stage, StageRegistry
+
+
+class Intent(str, Enum):
+    """A high-level description of what the user wants to do."""
+
+    BUILD = "build"  # generate / modify code
+    ASK = "ask"  # answer a question about the project
+    PLAN = "plan"  # produce a plan without writing code
+    DOCS = "docs"  # produce documentation
+    REVIEW = "review"  # run the code review pipeline
+    EXPLAIN = "explain"  # explain a single node / file
+    UNKNOWN = "unknown"
+
+
+@dataclass
+class IntentPrediction:
+    """The router's guess at what the user wants."""
+
+    intent: Intent
+    confidence: float
+    rationale: tuple[str, ...] = ()
+
+
+@dataclass
+class PluginContext:
+    """The shared state passed to a :class:`Workflow`."""
+
+    app_context: AppContext
+    prompt: str
+    intent: Intent
+    extras: dict[str, Any] = field(default_factory=dict)
+
+
+# ---------------------------------------------------------------------------
+# Base classes
+# ---------------------------------------------------------------------------
+
+
+class Workflow(ABC):
+    """A named, executable workflow.
+
+    The top-level ``forge`` command dispatches to the first registered
+    Workflow whose :meth:`can_handle` returns True for the active
+    :class:`Intent` and prompt.
+    """
+
+    name: str = "abstract"
+    intents: tuple[Intent, ...] = ()
+
+    @abstractmethod
+    async def run(self, context: PluginContext) -> dict[str, Any]:
+        """Execute the workflow; return a result payload for the CLI."""
+
+    @classmethod
+    def can_handle(cls, intent: Intent, prompt: str) -> bool:
+        """Return True if this workflow should run for ``intent``.
+
+        Implemented as a classmethod so the registry can iterate
+        over the workflow *classes* (not instances) and call
+        ``can_handle`` directly.
+        """
+        return intent in cls.intents
+
+
+class IntentClassifier(ABC):
+    """A pluggable intent classifier."""
+
+    name: str = "abstract"
+
+    @abstractmethod
+    def classify(self, prompt: str, *, history: tuple[str, ...] = ()) -> IntentPrediction:
+        """Return the most likely :class:`Intent` for ``prompt``."""
+
+
+# ---------------------------------------------------------------------------
+# Registry
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class PluginRegistry:
+    """In-memory registry of all loaded plugins.
+
+    When *engine_registry* is provided, every call to
+    :meth:`register_stage` or :meth:`replace_stage` is mirrored to
+    the engine's :class:`~forgecli.engine.execution.StageRegistry`.
+    """
+
+    providers: dict[str, type[Provider]] = field(default_factory=dict)
+    optimizers: dict[str, type] = field(default_factory=dict)
+    analyzers: list[type[Analyzer]] = field(default_factory=list)
+    classifiers: list[IntentClassifier] = field(default_factory=list)
+    workflows: list[Workflow] = field(default_factory=list)
+    stages: dict[str, Any] = field(default_factory=dict)
+    configure_hooks: list[Callable[[AppContext], None]] = field(default_factory=list)
+    engine_registry: StageRegistry | None = None  # StageRegistry, kept loose to avoid import cycles
+
+    def register_provider(self, name: str, provider_cls: type[Provider]) -> None:
+        self.providers[name] = provider_cls
+
+    def register_optimizer(self, name: str, optimizer_cls: type) -> None:
+        self.optimizers[name] = optimizer_cls
+
+    def register_analyzer(self, analyzer_cls: type[Analyzer]) -> None:
+        self.analyzers.append(analyzer_cls)
+
+    def register_classifier(self, classifier: IntentClassifier) -> None:
+        self.classifiers.append(classifier)
+
+    def register_workflow(self, workflow: Workflow) -> None:
+        self.workflows.append(workflow)
+
+    def register_stage(self, stage: Stage) -> None:
+        """Register a :class:`Stage` so the engine can pick it up by name."""
+        if not getattr(stage, "name", None):
+            raise ValueError("Stage.name must be non-empty")
+        if stage.name in self.stages:
+            raise ValueError(f"Stage {stage.name!r} already registered")
+        self.stages[stage.name] = stage
+        self._sync_to_engine_registry(stage)
+
+    def replace_stage(self, stage: Stage) -> None:
+        """Replace a registered :class:`Stage` (last-writer-wins)."""
+        if not getattr(stage, "name", None):
+            raise ValueError("Stage.name must be non-empty")
+        self.stages[stage.name] = stage
+        self._sync_to_engine_registry(stage, replace=True)
+
+    def _sync_to_engine_registry(self, stage: Stage, *, replace: bool = False) -> None:
+        engine_reg = self.engine_registry
+        if engine_reg is None:
+            return
+        try:
+            if replace:
+                engine_reg.replace(stage)
+            else:
+                engine_reg.register(stage)
+        except (ValueError, KeyError):
+            pass
+
+    def register_configure_hook(self, hook: Callable[[AppContext], None]) -> None:
+        self.configure_hooks.append(hook)
+
+    def link_engine_registry(self, engine_registry: StageRegistry) -> None:
+        """Link this plugin registry to an engine :class:`StageRegistry`.
+
+        All existing plugin stages are bulk-registered into the
+        engine registry; future calls to :meth:`register_stage`
+        and :meth:`replace_stage` are mirrored automatically.
+        """
+        self.engine_registry = engine_registry
+        for _, stage in list(self.stages.items()):
+            try:
+                engine_registry.register(stage)
+            except (ValueError, KeyError):
+                engine_registry.replace(stage)
+
+    def classifiers_sorted(self) -> list[IntentClassifier]:
+        return sorted(self.classifiers, key=lambda c: getattr(c, "priority", 100))
+
+
+# ---------------------------------------------------------------------------
+# Discovery
+# ---------------------------------------------------------------------------
+
+
+def discover_plugins(
+    registry: PluginRegistry,
+    group: str = "forgecli.plugins",
+) -> list[str]:
+    """Discover and load installed plugins via entry points.
+
+    Each entry point must resolve to a callable that takes a
+    :class:`PluginRegistry` (and optionally a
+    :class:`~forgecli.core.context.AppContext`) and returns nothing.
+    """
+    import importlib.metadata as importlib_metadata
+
+    loaded: list[str] = []
+    try:
+        entries = importlib_metadata.entry_points(group=group)
+    except Exception:
+        return loaded
+    for ep in entries:
+        try:
+            plugin_factory = ep.load()
+        except Exception:
+            continue
+        try:
+            plugin_factory(registry)
+            loaded.append(ep.name)
+        except Exception:
+            continue
+    return loaded
+
+
+__all__ = [
+    "Intent",
+    "IntentClassifier",
+    "IntentPrediction",
+    "PluginContext",
+    "PluginRegistry",
+    "Workflow",
+    "discover_plugins",
+]
+
+
+# Silence unused-import warnings for symbols only used in some branches.
+_ = Awaitable

forgecli/prompts/__init__.py

@@ -0,0 +1,11 @@
+"""Prompt templates and rendering."""
+
+from forgecli.prompts.loader import PromptLoader
+from forgecli.prompts.registry import PromptRegistry
+from forgecli.prompts.renderer import PromptRenderer
+
+__all__ = [
+    "PromptLoader",
+    "PromptRegistry",
+    "PromptRenderer",
+]

forgecli/prompts/loader.py

@@ -0,0 +1,28 @@
+"""Discover prompt templates on disk."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from forgecli.core.service import Service
+
+
+class PromptLoader(Service):
+    """Load prompt templates by name from a base directory."""
+
+    name = "prompts.loader"
+
+    def __init__(self, base_dir: Path) -> None:
+        super().__init__()
+        self._base_dir = Path(base_dir)
+
+    @property
+    def base_dir(self) -> Path:
+        return self._base_dir
+
+    def load(self, name: str) -> str:
+        """Return the contents of the prompt file identified by ``name``."""
+        path = self._base_dir / name
+        if not path.exists():
+            raise FileNotFoundError(f"Prompt not found: {path}")
+        return path.read_text(encoding="utf-8")

forgecli/prompts/registry.py

@@ -0,0 +1,32 @@
+"""In-memory registry of named prompts."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from forgecli.core.service import Service
+
+
+class PromptRegistry(Service):
+    """Stores prompts by name without touching the filesystem."""
+
+    name = "prompts.registry"
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._prompts: dict[str, str] = {}
+
+    def register(self, name: str, template: str) -> None:
+        self._prompts[name] = template
+
+    def get(self, name: str) -> str:
+        try:
+            return self._prompts[name]
+        except KeyError as exc:
+            raise KeyError(f"Prompt not registered: {name!r}") from exc
+
+    def names(self) -> list[str]:
+        return sorted(self._prompts)
+
+    def items(self) -> Iterable[tuple[str, str]]:
+        return self._prompts.items()

forgecli/prompts/renderer.py

@@ -0,0 +1,23 @@
+"""Render prompt templates into strings."""
+
+from __future__ import annotations
+
+from forgecli.core.service import Service
+
+
+class PromptRenderer(Service):
+    """Render prompt templates with a small variable substitution.
+
+    A real implementation will use Jinja2; for now we support a tiny
+    ``{var}`` syntax so the rest of the system can be exercised without
+    the dependency being required.
+    """
+
+    name = "prompts.renderer"
+
+    def render(self, template: str, **variables: object) -> str:
+        """Substitute ``{name}`` occurrences in ``template``."""
+        result = template
+        for key, value in variables.items():
+            result = result.replace("{" + key + "}", str(value))
+        return result

forgecli/providers/__init__.py

@@ -0,0 +1,39 @@
+"""AI provider abstraction layer."""
+
+from forgecli.providers.base import (
+    ChatMessage,
+    ChatRequest,
+    ChatResponse,
+    EmbeddingRequest,
+    EmbeddingResponse,
+    ModelInfo,
+    Provider,
+    ProviderRegistry,
+    StreamChunk,
+)
+from forgecli.providers.router import (
+    DEFAULT_PRICING,
+    ModelCapabilities,
+    ModelRouter,
+    RouteDecision,
+    SelectionMode,
+    estimate_cost,
+)
+
+__all__ = [
+    "DEFAULT_PRICING",
+    "ChatMessage",
+    "ChatRequest",
+    "ChatResponse",
+    "EmbeddingRequest",
+    "EmbeddingResponse",
+    "ModelCapabilities",
+    "ModelInfo",
+    "ModelRouter",
+    "Provider",
+    "ProviderRegistry",
+    "RouteDecision",
+    "SelectionMode",
+    "StreamChunk",
+    "estimate_cost",
+]

forgecli/providers/anthropic.py

@@ -0,0 +1,207 @@
+"""Anthropic Messages API provider.
+
+Targets the public ``https://api.anthropic.com/v1`` endpoint. The
+provider uses ``x-api-key`` + ``anthropic-version`` headers per the
+official API, and translates ChatRequest/Response into the Anthropic
+``messages`` schema (system extracted from the message list).
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from forgecli.providers.base import (
+    ChatMessage,
+    ChatRequest,
+    ChatResponse,
+    EmbeddingRequest,
+    EmbeddingResponse,
+    ModelInfo,
+    Role,
+    StreamChunk,
+)
+from forgecli.providers.http_base import HTTPChatProvider
+
+
+@dataclass
+class AnthropicConfig:
+    """Configuration for the Anthropic provider."""
+
+    api_key_env: str = "ANTHROPIC_API_KEY"
+    base_url: str = "https://api.anthropic.com"
+    default_model: str = "claude-3-5-haiku-latest"
+    max_tokens: int = 4096
+    temperature: float = 0.2
+    api_version: str = "2023-06-01"
+
+
+class AnthropicProvider(HTTPChatProvider):
+    """Anthropic Messages API."""
+
+    name = "anthropic"
+
+    def __init__(
+        self,
+        config: AnthropicConfig | None = None,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        super().__init__(
+            config or AnthropicConfig(),
+            api_key=api_key,
+            base_url=base_url,
+            client=client,
+        )
+
+    def _default_base_url(self) -> str:
+        return "https://api.anthropic.com"
+
+    def _chat_url(self) -> str:
+        return f"{self._base_url}/v1/messages"
+
+    def _auth_headers(self) -> dict[str, str]:
+        if not self._api_key:
+            return {}
+        return {
+            "x-api-key": self._api_key,
+            "anthropic-version": self.config.api_version,
+        }
+
+    def _format_request(self, request: ChatRequest) -> dict[str, Any]:
+        system_parts: list[str] = []
+        messages: list[dict[str, Any]] = []
+        for message in request.messages:
+            if message.role is Role.SYSTEM:
+                if message.content:
+                    system_parts.append(message.content)
+                continue
+            messages.append(
+                {
+                    "role": message.role.value,
+                    "content": message.content,
+                }
+            )
+        body: dict[str, Any] = {
+            "model": request.model or self.config.default_model,
+            "messages": messages,
+            "max_tokens": request.max_tokens or self.config.max_tokens,
+        }
+        if system_parts:
+            body["system"] = "\n\n".join(system_parts)
+        body["temperature"] = (
+            request.temperature if request.temperature is not None else self.config.temperature
+        )
+        if request.top_p is not None:
+            body["top_p"] = request.top_p
+        if request.stop:
+            body["stop_sequences"] = list(request.stop)
+        return body
+
+    def _parse_response(self, payload: dict[str, Any]) -> ChatResponse:
+        content_blocks = payload.get("content") or []
+        text_parts: list[str] = []
+        for block in content_blocks:
+            if isinstance(block, dict) and block.get("type") == "text":
+                text_parts.append(str(block.get("text", "")))
+        text = "".join(text_parts)
+        usage = payload.get("usage") or {}
+        return ChatResponse(
+            model=str(payload.get("model", self.config.default_model)),
+            message=ChatMessage(role=Role.ASSISTANT, content=text),
+            finish_reason=payload.get("stop_reason"),
+            prompt_tokens=int(usage.get("input_tokens", 0) or 0),
+            completion_tokens=int(usage.get("output_tokens", 0) or 0),
+            total_tokens=int(
+                (usage.get("input_tokens", 0) or 0) + (usage.get("output_tokens", 0) or 0)
+            ),
+            raw=payload,
+        )
+
+    async def stream(self, request: ChatRequest) -> AsyncIterator[StreamChunk]:
+        from forgecli.core.errors import ProviderError
+
+        if not self._api_key:
+            self.validate()
+        body = self._format_request(request)
+        body["stream"] = True
+
+        req = self._client.build_request(
+            "POST", self._chat_url(), json=body, headers=self._auth_headers()
+        )
+        response = await self._client.send(req, stream=True)
+        if response.status_code >= 400:
+            await response.aread()
+            raise ProviderError(
+                f"{self.name} stream failed ({response.status_code}): {response.text[:500]}"
+            )
+
+        import json
+
+        try:
+            event_name = None
+            async for line in response.aiter_lines():
+                line = line.strip()
+                if not line:
+                    continue
+                if line.startswith("event: "):
+                    event_name = line[7:]
+                elif line.startswith("data: "):
+                    data_str = line[6:]
+                    try:
+                        payload = json.loads(data_str)
+                        if event_name == "content_block_delta":
+                            delta = payload.get("delta", {})
+                            if delta.get("type") == "text_delta":
+                                text = delta.get("text", "")
+                                yield StreamChunk(delta=text, raw=payload)
+                        elif event_name == "message_delta":
+                            delta = payload.get("delta", {})
+                            finish_reason = delta.get("stop_reason")
+                            if finish_reason:
+                                yield StreamChunk(
+                                    delta="", finish_reason=finish_reason, raw=payload
+                                )
+                    except Exception:
+                        pass
+        finally:
+            await response.aclose()
+
+    # Anthropic does not expose a public embeddings endpoint; we
+    # surface a clear error rather than a confusing 404.
+    async def embed(self, request: EmbeddingRequest) -> EmbeddingResponse:  # type: ignore[override]
+        from forgecli.core.errors import ProviderError
+
+        raise ProviderError(f"{self.name} does not provide embeddings in this build")
+
+    def _format_embeddings(self, request: EmbeddingRequest) -> dict[str, Any]:  # pragma: no cover
+        raise NotImplementedError
+
+    def _parse_embeddings(self, payload: dict[str, Any]) -> EmbeddingResponse:  # pragma: no cover
+        raise NotImplementedError
+
+    def _default_embedding_model(self) -> str:  # pragma: no cover
+        return ""
+
+    def _known_models(self) -> list[ModelInfo]:
+        from forgecli.core.models import MODEL_CATALOG
+
+        return [
+            ModelInfo(
+                id=m.id,
+                name=m.display_name,
+                context_window=200_000,
+                supports_tools=True,
+                supports_vision="haiku" not in m.id,
+            )
+            for m in MODEL_CATALOG
+            if m.provider == "anthropic"
+        ]
+
+
+__all__ = ["AnthropicConfig", "AnthropicProvider"]