multi-forge 0.2.0__py3-none-any.whl

forge/proxy/model_spec.py

@@ -0,0 +1,158 @@
+"""Model ID normalization for proxy requests.
+
+This module handles the flexible model ID scheme:
+- provider/vendor/model → explicit provider
+- vendor/model → default_provider
+- model → default_provider + inferred vendor
+
+The proxy owns this normalization logic as orchestration concern.
+core.llm stays strict and requires explicit (provider, model_id) tuples.
+"""
+
+from typing import cast
+
+from forge.core.llm.detection import ProviderType
+
+# Known providers - these can appear as first segment
+KNOWN_PROVIDERS = frozenset({"litellm_remote", "litellm_local"})
+
+# Known vendors - these appear as vendor/ prefix before model name
+KNOWN_VENDORS = frozenset(
+    {
+        "openai",
+        "anthropic",
+        "vertex_ai",
+        "gemini",
+        "bedrock",
+        "replicate",
+        "together_ai",
+    }
+)
+
+
+def _infer_vendor(model_name: str) -> str:
+    """Infer vendor from model name patterns.
+
+    Args:
+        model_name: Model name without any vendor prefix (e.g., "gpt-5.5")
+
+    Returns:
+        Inferred vendor prefix.
+
+    Raises:
+        ValueError: If vendor cannot be inferred from model name.
+
+    Examples:
+        >>> _infer_vendor("gpt-5.5")
+        'openai'
+        >>> _infer_vendor("claude-sonnet-4.6")
+        'anthropic'
+        >>> _infer_vendor("gemini-3.1-pro")
+        'vertex_ai'
+    """
+    name = model_name.lower()
+
+    # OpenAI models: gpt-*, o1*, o3*, o4*
+    if name.startswith("gpt-") or name.startswith(("o1", "o3", "o4")):
+        return "openai"
+
+    # Anthropic models: claude-*
+    if name.startswith("claude-"):
+        return "anthropic"
+
+    # Google models: gemini-* → vertex_ai for remote routing
+    if name.startswith("gemini-"):
+        return "vertex_ai"
+
+    raise ValueError(
+        f"Cannot infer vendor for model '{model_name}'. "
+        f"Use explicit vendor prefix like 'openai/{model_name}' or 'anthropic/{model_name}'."
+    )
+
+
+def normalize_model_spec(
+    input_spec: str,
+    default_provider: ProviderType = "litellm_remote",
+) -> tuple[ProviderType, str]:
+    """Parse model spec and return (provider, vendor/model).
+
+    Supports progressive fallback:
+      - provider/vendor/model → explicit provider (e.g., "litellm_local/gemini/gemini-3.1")
+      - vendor/model → default_provider (e.g., "openai/gpt-5.5")
+      - model → default_provider + inferred vendor (e.g., "gpt-5.5" → "openai/gpt-5.5")
+
+    Args:
+        input_spec: Model specification in any supported format.
+        default_provider: Provider to use when not explicitly specified.
+
+    Returns:
+        Tuple of (provider, model_id) where model_id is vendor/model format.
+
+    Raises:
+        ValueError: If the spec is malformed or cannot be parsed.
+
+    Examples:
+        >>> normalize_model_spec("litellm_remote/openai/gpt-5.5")
+        ('litellm_remote', 'openai/gpt-5.5')
+        >>> normalize_model_spec("openai/gpt-5.5")
+        ('litellm_remote', 'openai/gpt-5.5')
+        >>> normalize_model_spec("gpt-5.5")
+        ('litellm_remote', 'openai/gpt-5.5')
+        >>> normalize_model_spec("litellm_remote/openai/gpt-5.5")
+        ('litellm_remote', 'openai/gpt-5.5')
+    """
+    if not input_spec or not input_spec.strip():
+        raise ValueError("Model spec cannot be empty")
+
+    parts = input_spec.strip().split("/")
+
+    if len(parts) == 1:
+        # Single segment: model only → infer vendor, use default provider
+        model_name = parts[0]
+        vendor = _infer_vendor(model_name)
+        return (default_provider, f"{vendor}/{model_name}")
+
+    if len(parts) == 2:
+        first, second = parts
+
+        # Check if first segment is a known provider (ambiguous case)
+        if first in KNOWN_PROVIDERS:
+            # This looks like provider/something, but we need vendor/model
+            raise ValueError(
+                f"Ambiguous model spec '{input_spec}': '{first}' looks like a provider "
+                f"but missing vendor segment. Use '{first}/openai/{second}' format."
+            )
+
+        # Standard vendor/model format
+        if first not in KNOWN_VENDORS:
+            raise ValueError(
+                f"Unknown vendor '{first}' in model spec '{input_spec}'. "
+                f"Known vendors: {', '.join(sorted(KNOWN_VENDORS))}"
+            )
+
+        return (default_provider, input_spec)
+
+    if len(parts) == 3:
+        provider, vendor, model = parts
+
+        # Validate provider
+        if provider not in KNOWN_PROVIDERS:
+            raise ValueError(
+                f"Unknown provider '{provider}' in model spec '{input_spec}'. "
+                f"Known providers: {', '.join(sorted(KNOWN_PROVIDERS))}"
+            )
+
+        # Validate vendor
+        if vendor not in KNOWN_VENDORS:
+            raise ValueError(
+                f"Unknown vendor '{vendor}' in model spec '{input_spec}'. "
+                f"Known vendors: {', '.join(sorted(KNOWN_VENDORS))}"
+            )
+
+        return (cast(ProviderType, provider), f"{vendor}/{model}")
+
+    # 4+ segments: invalid
+    raise ValueError(
+        f"Invalid model spec '{input_spec}': too many segments. "
+        f"Use 'provider/vendor/model', 'vendor/model', or 'model' format."
+    )

forge/proxy/proxies.py

@@ -0,0 +1,333 @@
+"""Proxy registry for Forge proxy endpoints.
+
+A proxy is a first-class identity for a running proxy endpoint (base_url/port) bound to a template.
+The proxy registry is stored at:
+
+- ~/.forge/proxies/index.json
+
+This module implements a small, versioned JSON store with atomic writes.
+
+Ownership: Forge Proxy Orchestrator (`forge proxy` CLI).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Callable
+
+import dacite
+
+from forge.core.paths import get_forge_home
+from forge.core.state import (
+    StateCorruptedError,
+    atomic_write_json,
+    file_lock_for_target,
+)
+
+_log = logging.getLogger(__name__)
+
+# A "starting" entry with no PID older than this is considered orphaned.
+STARTING_STALENESS_THRESHOLD_S = 60
+
+PROXY_REGISTRY_VERSION = 1
+PROXIES_DIR = "proxies"
+PROXY_INDEX_FILENAME = "index.json"
+
+CLI_LOCK_TIMEOUT_S = 5.0
+
+
+from forge.core.process import is_pid_alive as is_pid_alive  # noqa: E402, F401  # re-export
+
+
+def _is_orphaned_starting(entry: ProxyEntry) -> bool:
+    """Return True if a 'starting' entry with no PID is stale.
+
+    A proxy in "starting" state should transition to "healthy" within seconds.
+    If it's been in "starting" for longer than STARTING_STALENESS_THRESHOLD_S,
+    it was orphaned by an interrupted start_proxy() call (e.g., Ctrl+C).
+    """
+    if entry.created_at is None:
+        # No timestamp — can't determine age, treat as stale (defensive).
+        return True
+    try:
+        created = datetime.fromisoformat(entry.created_at)
+        # Ensure timezone-aware comparison
+        now = datetime.now(timezone.utc)
+        if created.tzinfo is None:
+            created = created.replace(tzinfo=timezone.utc)
+        age_s = (now - created).total_seconds()
+        return age_s > STARTING_STALENESS_THRESHOLD_S
+    except (ValueError, TypeError):
+        # Unparseable timestamp — treat as stale.
+        return True
+
+
+class ProxyRegistryCorruptedError(StateCorruptedError):
+    """Raised when the proxy registry cannot be parsed."""
+
+    pass
+
+
+@dataclass
+class ProxyEntry:
+    """A single proxy entry.
+
+    Timestamps are stored as ISO8601 strings.
+    """
+
+    proxy_id: str
+    template: str
+    base_url: str
+    port: int
+    pid: int | None = None
+    created_at: str | None = None
+    last_seen_at: str | None = None
+    status: str | None = None
+
+
+@dataclass
+class ProxyRegistry:
+    """Proxy registry file format."""
+
+    version: int = PROXY_REGISTRY_VERSION
+    proxies: dict[str, ProxyEntry] = field(default_factory=dict)
+
+
+def get_proxy_registry_path() -> Path:
+    """Return the full path to the proxy registry file."""
+
+    return get_forge_home() / PROXIES_DIR / PROXY_INDEX_FILENAME
+
+
+def lookup_proxy_by_base_url(registry: ProxyRegistry, base_url: str) -> ProxyEntry | None:
+    """Reverse lookup: find proxy entry by base_url.
+
+    Args:
+        registry: The proxy registry to search.
+        base_url: The URL to match (e.g., "http://localhost:8084").
+
+    Returns:
+        The matching ProxyEntry, or None if no proxy owns that base_url.
+    """
+    for entry in registry.proxies.values():
+        if entry.base_url == base_url:
+            return entry
+    return None
+
+
+# Proxy statuses that represent a routable (active) proxy.
+ROUTABLE_STATUSES = frozenset({"healthy", "starting"})
+
+
+class ProxyResolutionError(Exception):
+    """Base for proxy resolution failures."""
+
+
+class ProxyNotFoundError(ProxyResolutionError):
+    """No proxy matches the given name (neither proxy_id nor template)."""
+
+    def __init__(self, name: str, *, inactive_ids: list[str] | None = None) -> None:
+        self.name = name
+        self.inactive_ids = inactive_ids or []
+        if self.inactive_ids:
+            ids = ", ".join(self.inactive_ids)
+            super().__init__(
+                f"found {len(self.inactive_ids)} proxy(s) with template '{name}' " f"but none are active: {ids}"
+            )
+        else:
+            super().__init__(f"no proxy found matching '{name}' (checked proxy_id and template)")
+
+
+class AmbiguousProxyError(ProxyResolutionError):
+    """Multiple active proxies match the given template name."""
+
+    def __init__(self, name: str, proxy_ids: list[str]) -> None:
+        self.name = name
+        self.proxy_ids = proxy_ids
+        ids = ", ".join(proxy_ids)
+        super().__init__(
+            f"ambiguous: template '{name}' matches {len(proxy_ids)} active proxies: {ids}. "
+            f"Use a specific proxy_id instead"
+        )
+
+
+def resolve_proxy(registry: ProxyRegistry, name: str) -> ProxyEntry:
+    """Resolve a proxy by ID or template name.
+
+    Resolution order:
+    1. Exact proxy_id match (any status -- user asked for it by name).
+    2. Template fallback among active (routable) entries only.
+       Succeeds if exactly one active proxy uses that template.
+
+    Raises:
+        ProxyNotFoundError: No match found.
+        AmbiguousProxyError: Multiple active proxies share the template.
+    """
+    # 1. Exact proxy_id match
+    if name in registry.proxies:
+        return registry.proxies[name]
+
+    # 2. Template fallback (active entries only)
+    all_matches = [e for e in registry.proxies.values() if e.template == name]
+    active = [e for e in all_matches if e.status in ROUTABLE_STATUSES]
+
+    if len(active) == 1:
+        return active[0]
+    if len(active) > 1:
+        raise AmbiguousProxyError(name, [e.proxy_id for e in active])
+    if all_matches:
+        raise ProxyNotFoundError(name, inactive_ids=[e.proxy_id for e in all_matches])
+    raise ProxyNotFoundError(name)
+
+
+def resolve_proxy_optional(registry: ProxyRegistry, name: str) -> ProxyEntry | None:
+    """Fail-open variant of resolve_proxy.
+
+    Returns None on not-found. Logs a warning on ambiguous match
+    (silent fallback to direct could bypass enterprise proxy policies).
+    Intended for headless consumers (supervisor, handoff, workflows)
+    where a missing proxy should degrade gracefully.
+    """
+    try:
+        return resolve_proxy(registry, name)
+    except AmbiguousProxyError as e:
+        _log.warning("Proxy resolution ambiguous, falling back to direct: %s", e)
+        return None
+    except ProxyResolutionError:
+        return None
+
+
+class ProxyRegistryStore:
+    """Manage the proxy registry at ~/.forge/proxies/index.json.
+
+    Error handling:
+    - Missing file: returns empty registry (self-healing)
+    - Corrupted file: raises ProxyRegistryCorruptedError
+    """
+
+    def __init__(self, registry_path: Path | None = None) -> None:
+        self._registry_path = registry_path or get_proxy_registry_path()
+
+    @property
+    def registry_path(self) -> Path:
+        return self._registry_path
+
+    def exists(self) -> bool:
+        return self._registry_path.is_file()
+
+    def read(self) -> ProxyRegistry:
+        if not self.exists():
+            return ProxyRegistry()
+
+        try:
+            with open(self._registry_path, encoding="utf-8") as f:
+                data = json.load(f)
+        except json.JSONDecodeError as e:
+            raise ProxyRegistryCorruptedError(str(self._registry_path), f"invalid JSON: {e}")
+        except OSError as e:
+            raise ProxyRegistryCorruptedError(str(self._registry_path), f"read error: {e}")
+
+        version = data.get("version")
+        if version is None:
+            raise ProxyRegistryCorruptedError(str(self._registry_path), "missing version field")
+        if version != PROXY_REGISTRY_VERSION:
+            raise ProxyRegistryCorruptedError(
+                str(self._registry_path),
+                f"incompatible version {version} (this Forge expects {PROXY_REGISTRY_VERSION}). "
+                f"Delete this file and retry.",
+            )
+
+        try:
+            return dacite.from_dict(
+                data_class=ProxyRegistry,
+                data=data,
+                config=dacite.Config(strict=True),
+            )
+        except (dacite.DaciteError, TypeError, KeyError) as e:
+            raise ProxyRegistryCorruptedError(str(self._registry_path), f"deserialization error: {e}")
+
+    def write(self, registry: ProxyRegistry) -> None:
+        data = asdict(registry)
+        atomic_write_json(self._registry_path, data)
+
+    def update(self, *, timeout_s: float, mutate: Callable[[ProxyRegistry], None]) -> ProxyRegistry:
+        """Update registry via a locked read-modify-write cycle."""
+
+        with file_lock_for_target(target_path=self._registry_path, timeout_s=timeout_s):
+            registry = self.read()
+            mutate(registry)
+            self.write(registry)
+            return registry
+
+    def prune_dead_pids(self, *, timeout_s: float = CLI_LOCK_TIMEOUT_S) -> list[str]:
+        """Remove stale proxy entries from the registry.
+
+        Definition of stale (normative):
+        - Entries with a pid that is no longer running (dead process).
+        - Entries with status "starting", pid == None, and created_at older than
+          STARTING_STALENESS_THRESHOLD_S (orphaned from interrupted start_proxy).
+
+        Entries with pid == None and status other than "starting" (e.g.,
+        "configured", "stopped") are intentional user states and never pruned.
+
+        Returns:
+            List of proxy IDs removed from the registry.
+        """
+
+        with file_lock_for_target(target_path=self._registry_path, timeout_s=timeout_s):
+            registry = self.read()
+
+            stale_ids: list[str] = []
+            for proxy_id, entry in list(registry.proxies.items()):
+                if entry.pid is not None:
+                    if not is_pid_alive(entry.pid):
+                        del registry.proxies[proxy_id]
+                        stale_ids.append(proxy_id)
+                elif entry.status == "starting" and _is_orphaned_starting(entry):
+                    del registry.proxies[proxy_id]
+                    stale_ids.append(proxy_id)
+
+            if stale_ids:
+                self.write(registry)
+
+            return stale_ids
+
+    def list_proxies(self) -> list[ProxyEntry]:
+        """List proxy entries in deterministic order.
+
+        Entries with last_seen_at sort before entries without, then by proxy_id ASC
+        within each group. Does not sort by timestamp value (format-agnostic).
+        """
+
+        registry = self.read()
+        proxies = list(registry.proxies.values())
+
+        def _sort_key(entry: ProxyEntry) -> tuple[int, str]:
+            # Prefer entries with last_seen_at; sort them newest-first.
+            if entry.last_seen_at is None:
+                return (0, entry.proxy_id)
+            return (1, entry.proxy_id)
+
+        # We can't parse timestamps here without committing to a format; keep stable ordering.
+        # The CLI will display timestamps; orchestration later can implement richer sorting.
+        proxies.sort(key=_sort_key, reverse=True)
+        return proxies
+
+    def find_by_base_url(self, base_url: str) -> ProxyEntry | None:
+        """Find a proxy entry by its base_url.
+
+        This is a convenience method that combines read() + lookup_proxy_by_base_url().
+        Useful for status line and other consumers that need reverse lookup from URL.
+
+        Args:
+            base_url: The URL to match (e.g., "http://localhost:8084").
+
+        Returns:
+            The matching ProxyEntry, or None if no proxy owns that base_url.
+        """
+        registry = self.read()
+        return lookup_proxy_by_base_url(registry, base_url)

forge/proxy/proxy_identity.py

@@ -0,0 +1,134 @@
+"""Proxy identity discovery for runtime truth.
+
+This module provides a lightweight, testable way to discover the proxy's
+identity for the GET / runtime truth endpoint.
+
+The discovery uses a 2-tier approach:
+1. Registry lookup by (template, port) (primary)
+2. Derived from request/env (fallback - for unregistered proxies)
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Literal
+
+from forge.proxy.proxies import ProxyRegistryCorruptedError, ProxyRegistryStore
+
+logger = logging.getLogger(__name__)
+
+# Default port when neither request nor env port is available.
+# This is intentionally a simple constant (not derived from config) to keep
+# this module lightweight and avoid circular imports. The value matches
+# the base.yaml default, but if they drift, the impact is only on the
+# "derived" fallback path (manual/unregistered proxies).
+DEFAULT_PROXY_PORT = 8082
+
+# Type aliases for clarity and correctness
+ProxySource = Literal["registry", "derived"]
+ProxyStatus = Literal["registered", "unregistered"]
+
+
+@dataclass(frozen=True)
+class ProxyIdentity:
+    """Proxy identity for runtime truth.
+
+    Immutable (frozen) to prevent accidental mutation.
+    All fields are always populated - no None values except proxy_id
+    when the proxy is unregistered.
+    """
+
+    proxy_id: str | None
+    template: str
+    port: int
+    base_url: str
+    source: ProxySource
+    status: ProxyStatus
+
+
+def get_proxy_identity(
+    *,
+    active_template: str,
+    request_host: str | None = None,
+    request_port: int | None = None,
+    env_port: int | None = None,
+    process_proxy_id: str | None = None,
+) -> ProxyIdentity:
+    """Discover proxy identity using 2-tier approach.
+
+    Priority for port determination:
+        request_port > env_port > DEFAULT_PROXY_PORT
+
+    Priority for proxy identity:
+        1. Process proxy id + registry lookup by (template, port) (source="registry")
+        2. Registry lookup by (template, port) (source="registry")
+        3. Derived values (source="derived", status="unregistered")
+
+    The base_url is always derived from the effective host/port, not from
+    the registry, to ensure accuracy with the actual request endpoint.
+
+    Args:
+        active_template: The proxy template name (e.g., "litellm-openai")
+        request_host: Host from the incoming request (preferred)
+        request_port: Port from the incoming request (preferred)
+        env_port: Port from ACTIVE_PORT env var (fallback)
+        process_proxy_id: Proxy id this process was started with (FORGE_PROXY_ID).
+
+    Returns:
+        ProxyIdentity with all fields populated. proxy_id may be None
+        when the proxy is unregistered.
+    """
+    effective_port = request_port or env_port or DEFAULT_PROXY_PORT
+    effective_host = request_host or "localhost"
+    base_url = f"http://{effective_host}:{effective_port}"
+
+    try:
+        store = ProxyRegistryStore()
+        registry = store.read()
+
+        # Multiple matches shouldn't happen, but corruption could cause it;
+        # sort by proxy_id for deterministic selection.
+        matches = [
+            entry
+            for entry in registry.proxies.values()
+            if entry.template == active_template and entry.port == effective_port
+        ]
+        if process_proxy_id:
+            for entry in matches:
+                if entry.proxy_id == process_proxy_id:
+                    return ProxyIdentity(
+                        proxy_id=entry.proxy_id,
+                        template=active_template,
+                        port=effective_port,
+                        base_url=base_url,
+                        source="registry",
+                        status="registered",
+                    )
+
+        if matches:
+            best_match = sorted(matches, key=lambda e: e.proxy_id)[0]
+            return ProxyIdentity(
+                proxy_id=best_match.proxy_id,
+                template=active_template,
+                port=effective_port,
+                base_url=base_url,  # Use derived base_url, not registry
+                source="registry",
+                status="registered",
+            )
+    except ProxyRegistryCorruptedError as e:
+        logger.warning(f"Proxy registry corrupted during identity lookup: {e}")
+    except Exception as e:
+        # Don't fail if registry is unavailable (e.g., missing file is handled
+        # by ProxyRegistryStore.read() returning empty registry, but other
+        # unexpected errors should be logged)
+        logger.debug(f"Proxy registry lookup failed: {e}")
+
+    return ProxyIdentity(
+        proxy_id=process_proxy_id,
+        template=active_template,
+        port=effective_port,
+        base_url=base_url,
+        source="derived",
+        status="unregistered",
+    )