forgeoptimizer 1.0.0__py3-none-any.whl

forgecli/providers/router.py

@@ -0,0 +1,345 @@
+"""Model routing and selection.
+
+A :class:`ModelRouter` resolves a high-level request (provider name,
+model alias, or ``"auto"``) into a concrete :class:`Provider` and
+``model`` string. The router owns:
+
+* the **registry** of installed providers (OpenAI, Anthropic, Google, mock, …);
+* a static **cost model** keyed by ``(provider, model)``;
+* a **selector** that, given a request's required capabilities, picks
+  the cheapest compatible option.
+
+The router is decoupled from concrete providers; new providers can be
+registered without touching the router itself.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from enum import Enum
+
+from forgecli.providers.base import ProviderRegistry, default_registry
+
+# A small, well-known per-1k-token price table (USD, in/out).
+# Values are static defaults; users may override per-deployment. Source:
+# public pricing pages as of 2024-2025. These are advisory — the router
+# uses them only to break ties between equally-capable models.
+DEFAULT_PRICING: dict[tuple[str, str], tuple[float, float]] = {
+    # OpenAI
+    ("openai", "gpt-5.5"): (0.02, 0.10),
+    ("openai", "gpt-5"): (0.015, 0.075),
+    ("openai", "gpt-5-mini"): (0.00015, 0.0006),
+    ("openai", "gpt-4.1"): (0.005, 0.015),
+    ("openai", "gpt-4.1-mini"): (0.00015, 0.0006),
+    ("openai", "gpt-4o"): (0.005, 0.015),
+    ("openai", "gpt-4o-mini"): (0.00015, 0.0006),
+    ("openai", "gpt-4-turbo"): (0.01, 0.03),
+    ("openai", "o1"): (0.015, 0.06),
+    ("openai", "o1-preview"): (0.015, 0.06),
+    ("openai", "o1-mini"): (0.003, 0.012),
+    # Anthropic
+    ("anthropic", "claude-opus-4.8"): (0.015, 0.075),
+    ("anthropic", "claude-opus-4.6"): (0.015, 0.075),
+    ("anthropic", "claude-sonnet-4.6"): (0.003, 0.015),
+    ("anthropic", "claude-sonnet-4.5"): (0.003, 0.015),
+    ("anthropic", "claude-haiku-4.5"): (0.0008, 0.004),
+    ("anthropic", "claude-3-5-sonnet-latest"): (0.003, 0.015),
+    ("anthropic", "claude-3-5-haiku-latest"): (0.0008, 0.004),
+    ("anthropic", "claude-3-opus-latest"): (0.015, 0.075),
+    # Google
+    ("google", "gemini-2.5-pro"): (0.00125, 0.005),
+    ("google", "gemini-2.5-flash"): (0.000075, 0.0003),
+    ("google", "gemini-2.5-flash-lite"): (0.00003, 0.0001),
+    ("google", "gemini-2.0-flash"): (0.000075, 0.0003),
+    ("google", "gemini-1.5-pro"): (0.00125, 0.005),
+    ("google", "gemini-1.5-flash"): (0.000075, 0.0003),
+    ("google", "gemini-2.0-flash-exp"): (0.0, 0.0),
+    # Mock
+    ("mock", "mock-model"): (0.0, 0.0),
+}
+
+
+class SelectionMode(str, Enum):
+    """How the router picks a model."""
+
+    EXPLICIT = "explicit"   # caller named provider + model
+    ALIAS = "alias"         # caller named a provider alias
+    CHEAPEST = "cheapest"   # "auto" — pick the cheapest compatible model
+    FALLBACK = "fallback"   # an explicit selection failed; another matched
+
+
+@dataclass(frozen=True)
+class ModelCapabilities:
+    """The capability hints a request expresses."""
+
+    max_tokens: int | None = None
+    needs_tools: bool = False
+    needs_vision: bool = False
+
+
+@dataclass(frozen=True)
+class RouteDecision:
+    """The router's resolution of a request."""
+
+    provider_name: str
+    model: str
+    mode: SelectionMode
+    cost_in: float = 0.0
+    cost_out: float = 0.0
+    candidates: tuple[tuple[str, str], ...] = ()
+
+
+@dataclass
+class ModelRouter:
+    """Resolve high-level routing requests to provider + model."""
+
+    registry: ProviderRegistry = field(default_factory=lambda: default_registry)
+    pricing: dict[tuple[str, str], tuple[float, float]] = field(
+        default_factory=lambda: dict(DEFAULT_PRICING)
+    )
+    default_models: dict[str, str] = field(
+        default_factory=lambda: {
+            "openai": "gpt-5",
+            "anthropic": "claude-sonnet-4.6",
+            "google": "gemini-2.5-flash",
+            "openrouter": "glm-5.2",
+            "groq": "llama-4-scout",
+            "mistral": "mistral-large",
+            "ollama": "llama3",
+            "lmstudio": "local-model",
+            "vllm": "local-model",
+            "mock": "mock-model",
+        }
+    )
+    aliases: dict[str, str] = field(
+        default_factory=lambda: {
+            "claude": "anthropic",
+            "openai": "openai",
+            "gpt": "openai",
+            "gemini": "google",
+            "google": "google",
+        }
+    )
+
+    # ------------------------------------------------------------------
+    # Discovery
+    # ------------------------------------------------------------------
+
+    def available_providers(self) -> list[str]:
+        return self.registry.names()
+
+    def has_provider(self, name: str) -> bool:
+        return self.registry.has(name)
+
+    def resolve_alias(self, name: str) -> str:
+        return self.aliases.get(name.lower(), name.lower())
+
+    def default_model_for(self, provider_name: str) -> str:
+        return self.default_models.get(
+            provider_name.lower(),
+            _DEFAULT_MODEL_BY_PROVIDER.get(provider_name.lower(), "auto"),
+        )
+
+    # ------------------------------------------------------------------
+    # Selection
+    # ------------------------------------------------------------------
+
+    def select(
+        self,
+        choice: str | None,
+        *,
+        capabilities: ModelCapabilities | None = None,
+    ) -> RouteDecision:
+        """Resolve a CLI choice (claude / openai / gemini / auto / …)."""
+        choice = (choice or "auto").strip()
+        caps = capabilities or ModelCapabilities()
+
+        if choice.lower() == "auto":
+            return self._select_cheapest(caps)
+        return self._select_explicit(choice, caps)
+
+    def cheapest(
+        self,
+        capabilities: ModelCapabilities | None = None,
+        *,
+        provider: str | None = None,
+    ) -> RouteDecision:
+        """Pick the cheapest compatible (provider, model) pair.
+
+        When ``provider`` is set, the algorithm restricts the search to
+        that single provider. If that provider has no credentials, the
+        router falls back to the mock with :data:`SelectionMode.FALLBACK`
+        so the CLI never hard-errors.
+        """
+        if provider is not None:
+            return self._select_cheapest(
+                capabilities or ModelCapabilities(), provider=provider
+            )
+        return self._select_cheapest(capabilities or ModelCapabilities())
+
+    # ------------------------------------------------------------------
+    # Internal selectors
+    # ------------------------------------------------------------------
+
+    def _select_explicit(
+        self, choice: str, caps: ModelCapabilities
+    ) -> RouteDecision:
+        provider_name = self.resolve_alias(choice)
+        if not self.registry.has(provider_name):
+            return RouteDecision(
+                provider_name=provider_name,
+                model=self.default_model_for(provider_name),
+                mode=SelectionMode.ALIAS,
+            )
+        model = self.default_model_for(provider_name)
+        cost_in, cost_out = self.pricing.get(
+            (provider_name, model), (0.0, 0.0)
+        )
+        return RouteDecision(
+            provider_name=provider_name,
+            model=model,
+            mode=SelectionMode.ALIAS,
+            cost_in=cost_in,
+            cost_out=cost_out,
+        )
+
+    def _select_cheapest(
+        self,
+        caps: ModelCapabilities,
+        *,
+        provider: str | None = None,
+    ) -> RouteDecision:
+        candidates = self._list_real_candidates(caps, provider=provider)
+        if candidates:
+            # Sort by (in_price, out_price, provider_name) for determinism.
+            candidates.sort(
+                key=lambda c: (
+                    self.pricing.get(c, (0.0, 0.0))[0],
+                    self.pricing.get(c, (0.0, 0.0))[1],
+                    c[0],
+                )
+            )
+            chosen = candidates[0]
+            cost_in, cost_out = self.pricing.get(chosen, (0.0, 0.0))
+            return RouteDecision(
+                provider_name=chosen[0],
+                model=chosen[1],
+                mode=SelectionMode.CHEAPEST,
+                cost_in=cost_in,
+                cost_out=cost_out,
+                candidates=tuple(candidates),
+            )
+
+        # No real provider had credentials; fall back to the mock.
+        return RouteDecision(
+            provider_name="mock",
+            model=self.default_model_for("mock"),
+            mode=SelectionMode.FALLBACK,
+        )
+
+    def _list_real_candidates(
+        self,
+        caps: ModelCapabilities,
+        *,
+        provider: str | None = None,
+    ) -> list[tuple[str, str]]:
+        """Return the (provider, model) pairs that satisfy ``caps`` AND
+        have credentials available. Excludes the ``mock`` provider,
+        which is reserved as a fallback.
+        """
+        out: list[tuple[str, str]] = []
+        for name in self.registry.names():
+            if name == "mock":
+                continue
+            if provider is not None and name != provider:
+                continue
+            if not _provider_has_credentials(name):
+                continue
+            model = self.default_model_for(name)
+            out.append((name, model))
+        return out
+
+    def _list_candidates(
+        self,
+        caps: ModelCapabilities,
+        *,
+        provider: str | None = None,
+    ) -> list[tuple[str, str]]:
+        """Public list of real candidates; for tests and CLI display."""
+        return self._list_real_candidates(caps, provider=provider)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+_DEFAULT_MODEL_BY_PROVIDER: dict[str, str] = {
+    "openai": "gpt-5",
+    "anthropic": "claude-sonnet-4.6",
+    "google": "gemini-2.5-flash",
+    "openrouter": "glm-5.2",
+    "groq": "llama-4-scout",
+    "mistral": "mistral-large",
+    "minimax": "abab6.5g-chat",
+    "xai": "grok-2",
+    "together": "llama-3.1-70b",
+    "fireworks": "llama-3.1-70b",
+    "cohere": "command-r-plus",
+    "nvidia": "llama-3.1-70b",
+    "ollama": "llama3",
+    "lmstudio": "local-model",
+    "vllm": "local-model",
+    "mock": "mock-model",
+}
+
+
+_PROVIDER_ENV_VARS: dict[str, tuple[str, ...]] = {
+    "openai": ("OPENAI_API_KEY",),
+    "anthropic": ("ANTHROPIC_API_KEY",),
+    "google": ("GOOGLE_API_KEY", "GEMINI_API_KEY"),
+    "azure": ("AZURE_OPENAI_API_KEY",),
+    "mistral": ("MISTRAL_API_KEY",),
+    "groq": ("GROQ_API_KEY",),
+    "openrouter": ("OPENROUTER_API_KEY",),
+    "minimax": ("MINIMAX_API_KEY",),
+    "xai": ("XAI_API_KEY",),
+    "together": ("TOGETHER_API_KEY",),
+    "fireworks": ("FIREWORKS_API_KEY",),
+    "cohere": ("COHERE_API_KEY",),
+    "nvidia": ("NVIDIA_API_KEY",),
+    "ollama": ("OLLAMA_API_KEY",),
+    "lmstudio": ("LMSTUDIO_API_KEY",),
+    "vllm": ("VLLM_API_KEY",),
+}
+
+
+def _provider_has_credentials(name: str) -> bool:
+    """Return True if any known env var or secure storage key for ``name`` is non-empty."""
+    if name == "mock":
+        return True
+    if any(os.environ.get(env_var) for env_var in _PROVIDER_ENV_VARS.get(name, ())):
+        return True
+    from forgecli.core.credentials import get_api_key
+    return bool(get_api_key(name))
+
+
+def estimate_cost(
+    decision: RouteDecision,
+    *,
+    prompt_tokens: int,
+    completion_tokens: int,
+) -> float:
+    """Estimate USD cost for a finished call."""
+    return (decision.cost_in * prompt_tokens + decision.cost_out * completion_tokens) / 1000.0
+
+
+__all__ = [
+    "DEFAULT_PRICING",
+    "ModelCapabilities",
+    "ModelRouter",
+    "RouteDecision",
+    "SelectionMode",
+    "estimate_cost",
+]

forgecli/providers/router_state.py

@@ -0,0 +1,89 @@
+"""Live runtime state for the model router.
+
+The active provider selection (claude / openai / gemini / auto) is
+persisted to ``data_dir/router.json`` and surfaced on every
+:class:`AppContext` via ``extras``. A selection of ``"auto"`` triggers
+the cheapest-compatible algorithm on every chat call.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+from forgecli.providers.router import ModelCapabilities, RouteDecision, SelectionMode
+
+
+@dataclass
+class RouterState:
+    """The user-chosen provider/model selection."""
+
+    choice: str | None = None
+    model: str | None = None
+    provider: str | None = None
+
+    @classmethod
+    def from_extras(cls, extras: dict[str, object]) -> RouterState:
+        state = cls()
+        choice = extras.get("router.choice") or extras.get("router_choice")
+        if isinstance(choice, str):
+            state.choice = choice
+        model = extras.get("router.model") or extras.get("router_model")
+        if isinstance(model, str):
+            state.model = model
+        provider = extras.get("router.provider") or extras.get("router_provider")
+        if isinstance(provider, str):
+            state.provider = provider
+        return state
+
+    def to_extras(self) -> dict[str, str]:
+        out: dict[str, str] = {}
+        if self.choice:
+            out["router.choice"] = self.choice
+        if self.model:
+            out["router.model"] = self.model
+        if self.provider:
+            out["router.provider"] = self.provider
+        return out
+
+
+def load_state(path: Path) -> RouterState:
+    if not path.exists():
+        return RouterState()
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return RouterState()
+    state = RouterState()
+    choice = payload.get("choice")
+    if isinstance(choice, str):
+        state.choice = choice
+    model = payload.get("model")
+    if isinstance(model, str):
+        state.model = model
+    provider = payload.get("provider")
+    if isinstance(provider, str):
+        state.provider = provider
+    return state
+
+
+def save_state(path: Path, state: RouterState) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        json.dumps(
+            {"choice": state.choice, "model": state.model, "provider": state.provider},
+            indent=2,
+        ),
+        encoding="utf-8",
+    )
+
+
+__all__ = [
+    "ModelCapabilities",
+    "RouteDecision",
+    "RouterState",
+    "SelectionMode",
+    "load_state",
+    "save_state",
+]

forgecli/review/__init__.py

@@ -0,0 +1,45 @@
+"""Code review and quality analysis."""
+
+from forgecli.review.analyzer import AnalysisContext, Analyzer, SourceFile
+from forgecli.review.analyzers.architecture import ArchitectureAnalyzer
+from forgecli.review.analyzers.complexity import ComplexityAnalyzer
+from forgecli.review.analyzers.dead_code import DeadCodeAnalyzer
+from forgecli.review.analyzers.duplicates import DuplicatesAnalyzer
+from forgecli.review.analyzers.performance import PerformanceAnalyzer
+from forgecli.review.analyzers.security import SecurityAnalyzer
+from forgecli.review.finding import Finding, Severity
+from forgecli.review.report import (
+    print_review,
+    render_review,
+    review_to_json,
+    review_to_markdown,
+)
+from forgecli.review.repository import (
+    RepositoryReview,
+    default_analyzers,
+    review_repository,
+)
+from forgecli.review.suggestions import Suggestion, build_suggestions
+
+__all__ = [
+    "AnalysisContext",
+    "Analyzer",
+    "ArchitectureAnalyzer",
+    "ComplexityAnalyzer",
+    "DeadCodeAnalyzer",
+    "DuplicatesAnalyzer",
+    "Finding",
+    "PerformanceAnalyzer",
+    "RepositoryReview",
+    "SecurityAnalyzer",
+    "Severity",
+    "SourceFile",
+    "Suggestion",
+    "build_suggestions",
+    "default_analyzers",
+    "print_review",
+    "render_review",
+    "review_repository",
+    "review_to_json",
+    "review_to_markdown",
+]

forgecli/review/analyzer.py

@@ -0,0 +1,124 @@
+"""Common types for the review analyzer layer.
+
+Every concrete analyzer subclasses :class:`Analyzer` and implements
+:meth:`run`. The framework hands each analyzer a shared
+:class:`AnalysisContext` (a pre-loaded view of the project) and the
+analyzer returns a list of :class:`Finding` objects.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import ClassVar
+
+from forgecli.review.finding import Finding
+
+# Directories we never want to recurse into.
+_DEFAULT_IGNORES: tuple[str, ...] = (
+    ".git",
+    ".venv",
+    "venv",
+    "env",
+    "__pycache__",
+    ".pytest_cache",
+    ".mypy_cache",
+    ".ruff_cache",
+    "build",
+    "dist",
+    ".eggs",
+    "node_modules",
+    "target",
+    ".idea",
+    ".vscode",
+    "tests",
+)
+
+
+# File extensions we analyze.
+_DEFAULT_EXTENSIONS: tuple[str, ...] = (
+    ".py",
+    ".pyi",
+)
+
+
+@dataclass
+class SourceFile:
+    """One source file under review."""
+
+    path: Path
+    text: str
+    lines: tuple[str, ...]
+
+    @classmethod
+    def load(cls, path: Path) -> SourceFile:
+        try:
+            text = path.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            text = ""
+        return cls(path=path, text=text, lines=tuple(text.splitlines()))
+
+    def line_at(self, line_number: int) -> str:
+        if 1 <= line_number <= len(self.lines):
+            return self.lines[line_number - 1]
+        return ""
+
+
+@dataclass
+class AnalysisContext:
+    """The shared state passed to every analyzer."""
+
+    root: Path
+    files: list[SourceFile] = field(default_factory=list)
+    extras: dict[str, object] = field(default_factory=dict)
+
+    @classmethod
+    def load(
+        cls,
+        root: Path,
+        *,
+        extensions: Iterable[str] = _DEFAULT_EXTENSIONS,
+        ignore: Iterable[str] = _DEFAULT_IGNORES,
+    ) -> AnalysisContext:
+        """Walk ``root`` and load every matching file."""
+        root = Path(root).resolve()
+        ignore_set = set(ignore)
+        files: list[SourceFile] = []
+        if root.is_file():
+            files.append(SourceFile.load(root))
+            return cls(root=root, files=files)
+        for path in sorted(root.rglob("*")):
+            if not path.is_file():
+                continue
+            if path.suffix.lower() not in extensions:
+                continue
+            if any(part in ignore_set for part in path.parts):
+                continue
+            files.append(SourceFile.load(path))
+        return cls(root=root, files=files)
+
+    def get(self, path: Path) -> SourceFile | None:
+        for file in self.files:
+            if file.path == path:
+                return file
+        return None
+
+
+class Analyzer(ABC):
+    """Base class for review analyzers."""
+
+    name: ClassVar[str] = "abstract"
+    category: ClassVar[str] = "abstract"
+
+    @abstractmethod
+    def run(self, context: AnalysisContext) -> list[Finding]:
+        """Return the findings produced by this analyzer."""
+
+
+__all__ = [
+    "AnalysisContext",
+    "Analyzer",
+    "SourceFile",
+]

forgecli/review/analyzers/__init__.py

@@ -0,0 +1 @@
+"""Concrete analyzers shipped with ForgeCLI."""