multi-forge 0.2.0__py3-none-any.whl

forge/core/models/types.py

@@ -0,0 +1,167 @@
+"""Type definitions for the model catalog.
+
+This module defines the dataclasses that represent model specifications
+and the catalog structure. All types are immutable (frozen) to ensure
+the catalog remains a stable reference.
+"""
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+
+@dataclass(frozen=True)
+class TemperatureSpec:
+    """Temperature constraints for a model."""
+
+    min: float
+    default: float
+    max: float
+
+    def __post_init__(self) -> None:
+        if not (self.min <= self.default <= self.max):
+            raise ValueError(
+                f"Temperature invariant violated: min ({self.min}) <= default ({self.default}) <= max ({self.max})"
+            )
+        if self.min < 0:
+            raise ValueError(f"Temperature min must be >= 0, got {self.min}")
+
+
+@dataclass(frozen=True)
+class ModelSpec:
+    """Intrinsic properties of a model.
+
+    These are facts about what the model CAN do, not operational config.
+    Operational config (tier mappings, routing, defaults) belongs in template YAMLs.
+    """
+
+    # Basic identity
+    friendly_name: str
+    intelligence_score: int
+
+    # Token limits
+    context_window_tokens: int
+    max_output_tokens: int
+    max_thinking_tokens: int | None = None
+
+    # Display
+    short_name: str | None = None  # Compact display name (e.g., "gemini-flash"); None = derive algorithmically
+
+    # Capability flags
+    supports_thinking: bool = False
+    supports_images: bool = False
+    supports_verbosity: bool = False
+    supports_top_p: bool = True
+    supports_sampling_overrides: bool = True
+    supports_1m_context: bool = False
+
+    # Temperature configuration
+    temperature_constraint: Literal["fixed", "range"] = "range"
+    temperature: TemperatureSpec = field(default_factory=lambda: TemperatureSpec(0.0, 1.0, 2.0))
+
+    # Verbosity configuration (GPT-5 non-Codex models via Responses API)
+    verbosity_levels: tuple[str, ...] | None = None
+
+    # API configuration
+    use_responses_api: bool = False
+
+    # Reasoning/thinking configuration
+    # Native parameter name varies by provider:
+    # - OpenAI: "reasoning_effort"
+    # - Anthropic: "output_config.effort"
+    # - Gemini 2.5: "thinking_budget"
+    # - Gemini 3: "thinking_level"
+    native_thinking_param: str | None = None
+
+    # LiteLLM abstraction - supported reasoning_effort values
+    # These are the values LiteLLM accepts and maps to native params
+    litellm_reasoning_efforts: tuple[str, ...] | None = None
+    default_reasoning_effort: str | None = None
+    thinking_modes: tuple[str, ...] | None = None
+
+    # Gemini 3 specific - thinking levels (different from reasoning_effort)
+    thinking_levels: tuple[str, ...] | None = None
+    default_thinking_level: str | None = None
+
+    # Metadata
+    token_estimate_multiplier: float = 1.0
+    system_prompt_addendum: str | None = None
+    tags: tuple[str, ...] = field(default_factory=tuple)
+
+    def __post_init__(self) -> None:
+        if self.context_window_tokens <= 0:
+            raise ValueError(f"context_window_tokens must be > 0, got {self.context_window_tokens}")
+        if self.max_output_tokens <= 0:
+            raise ValueError(f"max_output_tokens must be > 0, got {self.max_output_tokens}")
+        if self.max_thinking_tokens is not None and self.max_thinking_tokens <= 0:
+            raise ValueError(f"max_thinking_tokens must be > 0 or null, got {self.max_thinking_tokens}")
+        if not (0 <= self.intelligence_score <= 100):
+            raise ValueError(f"intelligence_score must be 0-100, got {self.intelligence_score}")
+        if self.token_estimate_multiplier <= 0:
+            raise ValueError(f"token_estimate_multiplier must be > 0, got {self.token_estimate_multiplier}")
+        if self.temperature_constraint == "fixed":
+            if self.temperature.min != self.temperature.max:
+                raise ValueError(
+                    f"Fixed temperature constraint requires min == max, "
+                    f"got min={self.temperature.min}, max={self.temperature.max}"
+                )
+
+
+REQUIRED_TIERS = frozenset({"haiku", "sonnet", "opus"})
+
+
+@dataclass(frozen=True)
+class ModelCatalog:
+    """The complete model catalog.
+
+    Immutable container for all models and their aliases.
+    Use the module-level functions to query the catalog.
+    """
+
+    schema_version: int
+    models: dict[str, ModelSpec]
+    aliases: dict[str, str]
+    defaults: dict[str, dict[str, str]] = field(default_factory=dict)  # provider -> tier -> canonical model ID
+
+    def resolve(self, model_or_alias: str) -> str:
+        """Resolve a model ID or alias to its canonical ID.
+
+        Args:
+            model_or_alias: A canonical model ID or an alias.
+
+        Returns:
+            The canonical model ID.
+
+        Raises:
+            KeyError: If the model/alias is not found in the catalog.
+        """
+        if model_or_alias in self.models:
+            return model_or_alias
+        if model_or_alias in self.aliases:
+            return self.aliases[model_or_alias]
+        raise KeyError(f"Unknown model or alias: {model_or_alias!r}")
+
+    def get(self, model_or_alias: str) -> ModelSpec:
+        """Get the model spec for a model ID or alias.
+
+        Args:
+            model_or_alias: A canonical model ID or an alias.
+
+        Returns:
+            The ModelSpec for the resolved model.
+
+        Raises:
+            KeyError: If the model/alias is not found in the catalog.
+        """
+        canonical_id = self.resolve(model_or_alias)
+        return self.models[canonical_id]
+
+    def get_default(self, provider: str, tier: str) -> str:
+        """Return the canonical model ID for a provider+tier default.
+
+        Raises KeyError if provider or tier is not in defaults.
+        """
+        return self.defaults[provider][tier]
+
+    def __contains__(self, model_or_alias: str) -> bool:
+        """Check if a model or alias exists in the catalog."""
+        return model_or_alias in self.models or model_or_alias in self.aliases

forge/core/naming.py

@@ -0,0 +1,212 @@
+"""Random name generation for human-friendly identifiers.
+
+Provides consistent naming across Forge components using the coolname library.
+
+Session names use default coolname (adjective-animal): 'spirited-coati'.
+Proxy names use a custom color-fruit generator: 'teal-lemon'.
+
+Usage:
+    from forge.core.naming import generate_name, generate_unique_name
+    from forge.core.naming import generate_proxy_name, generate_unique_proxy_name
+
+    name = generate_name()                           # 'mottled-crab'
+    unique = generate_unique_name(existing)           # Avoids collisions
+    proxy = generate_proxy_name()                     # 'teal-lemon'
+    unique_proxy = generate_unique_proxy_name(existing)
+"""
+
+from __future__ import annotations
+
+import random
+from typing import Literal
+
+import coolname
+from coolname import RandomGenerator
+
+# Type alias for supported word counts
+WordCount = Literal[2, 3, 4]
+
+# Default word count for generated names
+DEFAULT_WORDS: WordCount = 2
+
+
+def generate_name(words: WordCount = DEFAULT_WORDS) -> str:
+    """Generate a random human-friendly name.
+
+    Args:
+        words: Number of words in the name (2, 3, or 4).
+            - 2: 'adjective-noun' (e.g., 'happy-fox') - ~10^5 combinations
+            - 3: 'adjective-adjective-noun' (e.g., 'big-maize-lori') - ~10^8 combinations
+            - 4: 'adjective-adjective-noun-of-noun' (e.g., 'military-diamond-tuatara-of-endeavor') - ~10^10 combinations
+
+    Returns:
+        A hyphenated lowercase name.
+
+    Example:
+        >>> name = generate_name()
+        >>> '-' in name
+        True
+    """
+    return coolname.generate_slug(words)
+
+
+def generate_unique_name(
+    existing_names: set[str],
+    words: WordCount = DEFAULT_WORDS,
+    max_attempts: int = 100,
+) -> str:
+    """Generate a random name that doesn't conflict with existing names.
+
+    Args:
+        existing_names: Set of names that already exist.
+        words: Number of words in the name (2, 3, or 4).
+        max_attempts: Maximum attempts before falling back to suffix strategy.
+
+    Returns:
+        A unique random name not in existing_names.
+
+    Note:
+        If max_attempts is exceeded, falls back to appending random suffixes
+        until a unique name is found. With ~10^5 combinations for 2-word names,
+        collisions are rare unless existing_names is very large.
+
+    Example:
+        >>> existing = {"happy-fox", "brave-wolf"}
+        >>> name = generate_unique_name(existing)
+        >>> name not in existing
+        True
+    """
+    # Try generating names without suffix
+    for _ in range(max_attempts):
+        name = generate_name(words)
+        if name not in existing_names:
+            return name
+
+    # Fallback: append random suffix, loop until unique
+    while True:
+        base = generate_name(words)
+        suffix = random.randint(100, 9999)  # 4 digits for more entropy
+        name = f"{base}-{suffix}"
+        if name not in existing_names:
+            return name
+
+
+def generate_parts(words: WordCount = DEFAULT_WORDS) -> list[str]:
+    """Generate name parts as a list (for custom formatting).
+
+    Args:
+        words: Number of words to generate (2, 3, or 4).
+
+    Returns:
+        List of name parts (e.g., ['happy', 'fox']).
+
+    Example:
+        >>> parts = generate_parts()
+        >>> len(parts) == 2
+        True
+    """
+    return coolname.generate(words)
+
+
+# --- Proxy names: color-fruit pattern (visually distinct from session names) ---
+
+_PROXY_COLORS = [
+    "amber",
+    "azure",
+    "bronze",
+    "cobalt",
+    "copper",
+    "coral",
+    "crimson",
+    "cyan",
+    "ebony",
+    "emerald",
+    "garnet",
+    "golden",
+    "indigo",
+    "ivory",
+    "jade",
+    "lavender",
+    "magenta",
+    "maroon",
+    "navy",
+    "ochre",
+    "onyx",
+    "ruby",
+    "sage",
+    "scarlet",
+    "silver",
+    "slate",
+    "teal",
+    "topaz",
+    "turquoise",
+    "violet",
+]
+
+_PROXY_FRUITS = [
+    "apple",
+    "apricot",
+    "banana",
+    "cherry",
+    "citron",
+    "coconut",
+    "date",
+    "fig",
+    "grape",
+    "guava",
+    "kiwi",
+    "lemon",
+    "lime",
+    "lychee",
+    "mango",
+    "melon",
+    "olive",
+    "orange",
+    "papaya",
+    "peach",
+    "pear",
+    "plum",
+    "pomelo",
+    "quince",
+    "raisin",
+    "sorbet",
+    "tangerine",
+    "walnut",
+    "yuzu",
+    "zest",
+]
+
+_proxy_generator = RandomGenerator(
+    {
+        "all": {"type": "cartesian", "lists": ["color", "fruit"]},
+        "color": {"type": "words", "words": _PROXY_COLORS},
+        "fruit": {"type": "words", "words": _PROXY_FRUITS},
+    }
+)
+
+
+def generate_proxy_name() -> str:
+    """Generate a color-fruit proxy name (e.g., 'teal-lemon')."""
+    return _proxy_generator.generate_slug()
+
+
+def generate_unique_proxy_name(
+    existing_names: set[str],
+    max_attempts: int = 100,
+) -> str:
+    """Generate a unique color-fruit proxy name.
+
+    30 colors x 30 fruits = 900 combinations.
+    Falls back to numeric suffix if exhausted.
+    """
+    for _ in range(max_attempts):
+        name = generate_proxy_name()
+        if name not in existing_names:
+            return name
+
+    while True:
+        base = generate_proxy_name()
+        suffix = random.randint(100, 9999)
+        name = f"{base}-{suffix}"
+        if name not in existing_names:
+            return name

forge/core/ops/__init__.py

@@ -0,0 +1,73 @@
+"""Command-core operations.
+
+This package contains reusable operations that can be invoked from:
+
+- the Forge CLI (`forge ...`), and
+- in-chat direct commands (via `%...` routed through `forge hook user-prompt-submit`).
+
+Ops must be UI-agnostic: no Click usage, no printing, and no hook JSON.
+"""
+
+from .context import ExecutionContext
+from .gc import (
+    CleanError,
+    CleanReport,
+    CleanResult,
+    OrphanCategory,
+    collect_clean_report,
+    run_clean,
+)
+from .proxy import (
+    ListProxiesItem,
+    ListProxiesResult,
+    ShowProxyResult,
+    list_proxies,
+    show_proxy,
+)
+from .resolution import (
+    ResolvedSession,
+    resolve_session_repo_wide,
+)
+from .session import (
+    ForgeOpError,
+    ListSessionsItem,
+    ListSessionsResult,
+    ResetOverridesResult,
+    ResolveSessionResult,
+    SetOverrideResult,
+    list_sessions,
+    reset_session_overrides,
+    resolve_session,
+    set_session_override,
+)
+
+__all__ = [
+    "ExecutionContext",
+    "ForgeOpError",
+    # GC ops
+    "CleanError",
+    "CleanReport",
+    "CleanResult",
+    "OrphanCategory",
+    "collect_clean_report",
+    "run_clean",
+    # Resolution ops
+    "ResolvedSession",
+    "resolve_session_repo_wide",
+    # Session ops
+    "ListSessionsItem",
+    "ListSessionsResult",
+    "list_sessions",
+    "ResolveSessionResult",
+    "resolve_session",
+    "SetOverrideResult",
+    "set_session_override",
+    "ResetOverridesResult",
+    "reset_session_overrides",
+    # Proxy ops
+    "ListProxiesItem",
+    "ListProxiesResult",
+    "ShowProxyResult",
+    "list_proxies",
+    "show_proxy",
+]

forge/core/ops/context.py

@@ -0,0 +1,141 @@
+"""Command-core execution context.
+
+This context is intentionally lightweight: it carries paths only.
+Stores (SessionStore/IndexStore/etc.) are cheap file wrappers and should be
+constructed inside ops as needed.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class ExecutionContext:
+    """Execution context for command-core ops.
+
+    Attributes:
+        cwd: Current working directory.
+        worktree_root: Git checkout root (= checkout_root in the identity model).
+        project_root: Git repository root (= logical repo, main checkout).
+        forge_root: Forge project root (directory containing .forge/), or None
+            if not inside a Forge project.
+    """
+
+    cwd: Path
+    worktree_root: Path
+    project_root: Path
+    forge_root: Path | None = None
+
+    @classmethod
+    def from_cwd(cls, cwd: Path | None = None) -> "ExecutionContext":
+        """Create context by deriving paths from the current working directory.
+
+        Uses git to find the worktree/project root. Falls back to cwd if not
+        in a git repository.
+
+        Args:
+            cwd: Working directory. Defaults to Path.cwd().
+
+        Returns:
+            ExecutionContext with derived paths.
+        """
+        if cwd is None:
+            cwd = Path.cwd().resolve()
+        else:
+            cwd = cwd.resolve()
+
+        # Try to find git root (works for both regular repos and worktrees)
+        worktree_root = _find_git_root(cwd)
+        if worktree_root is None:
+            # Not in a git repo: use cwd for all paths
+            forge_root = find_forge_root(cwd)
+            return cls(cwd=cwd, worktree_root=cwd, project_root=cwd, forge_root=forge_root)
+
+        # For worktrees, find the main repository root
+        project_root = _find_main_repo_root(worktree_root)
+
+        # Find Forge project root (.forge/ directory)
+        forge_root = find_forge_root(cwd)
+
+        return cls(cwd=cwd, worktree_root=worktree_root, project_root=project_root, forge_root=forge_root)
+
+
+def _find_git_root(start: Path) -> Path | None:
+    """Find git root by walking up from start.
+
+    Returns None if not in a git repository.
+    """
+    current = start
+    while current != current.parent:
+        if (current / ".git").exists():
+            return current
+        current = current.parent
+
+    # Check root
+    if (current / ".git").exists():
+        return current
+
+    return None
+
+
+def _find_main_repo_root(worktree_root: Path) -> Path:
+    """Find the main repository root from a worktree.
+
+    In a regular repo, .git is a directory and we return worktree_root.
+    In a worktree, .git is a file containing 'gitdir: <path>' pointing to
+    the worktree's git dir inside the main repo's .git/worktrees/.
+    """
+    git_path = worktree_root / ".git"
+
+    if git_path.is_dir():
+        # Regular repo, not a worktree
+        return worktree_root
+
+    if git_path.is_file():
+        # Worktree: .git file contains 'gitdir: <path>'
+        try:
+            content = git_path.read_text().strip()
+            if content.startswith("gitdir:"):
+                gitdir = content[7:].strip()
+                # gitdir is typically: /path/to/main/.git/worktrees/<name>
+                # We want: /path/to/main
+                gitdir_path = Path(gitdir)
+                if not gitdir_path.is_absolute():
+                    gitdir_path = (worktree_root / gitdir_path).resolve()
+
+                # Navigate up from .git/worktrees/<name> to find main repo
+                if "worktrees" in gitdir_path.parts:
+                    # Find .git directory (parent of worktrees)
+                    idx = gitdir_path.parts.index("worktrees")
+                    git_dir = Path(*gitdir_path.parts[:idx])
+                    if git_dir.name == ".git":
+                        return git_dir.parent
+        except (OSError, ValueError):
+            pass
+
+    # Fallback: return worktree_root
+    return worktree_root
+
+
+def find_forge_root(start: Path) -> Path | None:
+    """Find the Forge project root by walking up from start.
+
+    A Forge project root is a directory containing a ``.forge/`` subdirectory,
+    established by ``forge extension enable``.
+
+    Stops at git repository boundaries (``.git`` directory or file) to avoid
+    escaping into a parent repository's ``.forge/``.
+
+    Returns None if not inside a Forge project.
+    """
+    current = start
+    while current != current.parent:
+        if (current / ".forge").is_dir():
+            return current
+        if (current / ".git").exists():
+            return None  # Hit git boundary without finding .forge/
+        current = current.parent
+
+    return None