multi-forge 0.2.0__py3-none-any.whl

forge/backend/__init__.py

@@ -0,0 +1,174 @@
+"""Backend management for Forge.
+
+Backends are underlying services that proxies depend on (e.g., LiteLLM).
+They have their own lifecycle, registry, and CLI commands.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from forge.backend.registry import (
+    BackendInstance,
+    BackendRegistry,
+    BackendRegistryStore,
+)
+
+
+@dataclass(frozen=True)
+class BackendEnsureResult:
+    """Result of ensure_backend() operation."""
+
+    instance: BackendInstance
+    source: Literal["reuse", "start"]
+
+
+class BackendAdapter(ABC):
+    """Abstract base class for backend lifecycle management."""
+
+    @abstractmethod
+    def start(self, backend_id: str, config_path: Path, port: int) -> BackendInstance:
+        """Start backend, return instance details.
+
+        Args:
+            backend_id: Unique instance ID (e.g., "litellm-4000")
+            config_path: Path to backend config file
+            port: Port number to bind
+
+        Returns:
+            BackendInstance with PID and status
+
+        Raises:
+            BackendStartError: If backend fails to start
+        """
+
+    @abstractmethod
+    def stop(self, instance: BackendInstance) -> None:
+        """Stop backend (best effort).
+
+        Args:
+            instance: Backend instance to stop
+        """
+
+    @abstractmethod
+    def health_check(self, instance: BackendInstance) -> bool:
+        """Check if backend is healthy.
+
+        Args:
+            instance: Backend instance to check
+
+        Returns:
+            True if healthy, False otherwise
+        """
+
+
+class BackendStartError(Exception):
+    """Raised when backend fails to start."""
+
+
+class BackendManager:
+    """Orchestrates backends via adapters."""
+
+    def __init__(self, registry_store: BackendRegistryStore) -> None:
+        """Initialize backend manager.
+
+        Args:
+            registry_store: Backend registry store
+        """
+        self.registry_store = registry_store
+        self.adapters: dict[str, BackendAdapter] = {}
+
+    def register_adapter(self, adapter_type: str, adapter: BackendAdapter) -> None:
+        """Register a backend adapter.
+
+        Args:
+            adapter_type: Adapter type (e.g., "litellm")
+            adapter: Adapter instance
+        """
+        self.adapters[adapter_type] = adapter
+
+    def ensure_backend(self, backend_id: str, adapter_type: str, port: int) -> BackendEnsureResult:
+        """Ensure backend is running (reuse -> start pattern).
+
+        Args:
+            backend_id: Backend instance ID (e.g., "litellm-4000")
+            adapter_type: Adapter type (e.g., "litellm")
+            port: Port number
+
+        Returns:
+            BackendEnsureResult with instance and source ("reuse" or "start")
+
+        Raises:
+            BackendStartError: If backend fails to start
+        """
+        from forge.backend.creation import get_backend_config_path
+
+        adapter = self.adapters.get(adapter_type)
+        if not adapter:
+            raise ValueError(f"No adapter registered for type: {adapter_type}")
+
+        registry = self.registry_store.read()
+        existing = registry.backends.get(backend_id)
+
+        if existing:
+            # health_check works with or without PID (port probe fallback)
+            if adapter.health_check(existing):
+                return BackendEnsureResult(instance=existing, source="reuse")
+
+            def remove_dead(reg: BackendRegistry) -> None:
+                reg.backends.pop(backend_id, None)
+
+            self.registry_store.update(timeout_s=10.0, mutate=remove_dead)
+
+        config_path = get_backend_config_path(adapter_type)
+        if not config_path.exists():
+            raise BackendStartError(
+                f"Backend config not found: {config_path}\n" f"Create it with: forge backend create {adapter_type}"
+            )
+
+        instance = adapter.start(backend_id, config_path, port)
+
+        def add_instance(reg: BackendRegistry) -> None:
+            reg.backends[backend_id] = instance
+
+        self.registry_store.update(timeout_s=10.0, mutate=add_instance)
+
+        return BackendEnsureResult(instance=instance, source="start")
+
+    def stop_backend(self, backend_id: str) -> None:
+        """Stop backend and remove from registry.
+
+        Args:
+            backend_id: Backend instance ID
+
+        Raises:
+            ValueError: If backend not found
+        """
+        registry = self.registry_store.read()
+        instance = registry.backends.get(backend_id)
+
+        if not instance:
+            raise ValueError(f"Backend not found: {backend_id}")
+
+        adapter = self.adapters.get(instance.adapter_type)
+        if adapter:
+            adapter.stop(instance)
+
+        def remove_instance(reg: BackendRegistry) -> None:
+            reg.backends.pop(backend_id, None)
+
+        self.registry_store.update(timeout_s=10.0, mutate=remove_instance)
+
+
+__all__ = [
+    "BackendAdapter",
+    "BackendEnsureResult",
+    "BackendInstance",
+    "BackendManager",
+    "BackendRegistry",
+    "BackendRegistryStore",
+    "BackendStartError",
+]

forge/backend/adapters/__init__.py

@@ -0,0 +1,38 @@
+"""Backend adapters for different backend types."""
+
+from __future__ import annotations
+
+from forge.backend import BackendAdapter
+from forge.backend.adapters.litellm import LiteLLMAdapter
+
+# Registry of known adapter types
+_ADAPTER_REGISTRY: dict[str, type["BackendAdapter"]] = {
+    "litellm": LiteLLMAdapter,
+}
+
+
+def get_adapter(adapter_type: str) -> "BackendAdapter":
+    """Get an adapter instance by type.
+
+    Args:
+        adapter_type: Adapter type (e.g., "litellm")
+
+    Returns:
+        New adapter instance
+
+    Raises:
+        ValueError: If adapter type is unknown
+    """
+    adapter_class = _ADAPTER_REGISTRY.get(adapter_type)
+    if adapter_class is None:
+        available = ", ".join(sorted(_ADAPTER_REGISTRY.keys()))
+        raise ValueError(f"Unknown adapter type: '{adapter_type}'. Available: {available}")
+    return adapter_class()
+
+
+def get_supported_adapters() -> list[str]:
+    """Get list of supported adapter types."""
+    return sorted(_ADAPTER_REGISTRY.keys())
+
+
+__all__ = ["LiteLLMAdapter", "get_adapter", "get_supported_adapters"]

forge/backend/adapters/litellm.py

@@ -0,0 +1,158 @@
+"""LiteLLM backend adapter.
+
+Manages LiteLLM proxy processes for multi-provider model access.
+LiteLLM supports many providers (Gemini, OpenAI, Anthropic, etc.) -
+the specific provider is determined by the config file and env vars.
+
+Env var validation happens BEFORE this adapter is called (in _ensure_dependency_backend),
+so this adapter just passes through whatever is in os.environ.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+import httpx
+
+from forge.backend import BackendAdapter, BackendStartError
+from forge.backend.registry import BackendInstance
+from forge.core.paths import get_forge_home
+from forge.core.state import now_iso
+
+
+class LiteLLMAdapter(BackendAdapter):
+    """Adapter for managing LiteLLM backend processes.
+
+    This adapter is provider-agnostic - it starts LiteLLM with whatever
+    config and environment variables are provided. The specific provider
+    (Gemini, OpenAI, etc.) is determined by:
+    1. The LiteLLM config file (model_list with provider prefixes)
+    2. Environment variables (GEMINI_API_KEY, OPENAI_API_KEY, etc.)
+
+    Env var validation is handled by the caller (_ensure_dependency_backend)
+    which checks BackendDependency.required_env_vars before starting.
+    """
+
+    def _wait_for_health(self, port: int, timeout: float = 15.0) -> bool:
+        """Wait for backend to become healthy.
+
+        Uses /health/liveliness (not /health) because the full health endpoint
+        runs model-level checks against remote providers, which can take 5-10s.
+        The liveliness endpoint just verifies the server process is accepting
+        requests (~5ms).
+
+        Args:
+            port: Port to check
+            timeout: Timeout in seconds
+
+        Returns:
+            True if healthy within timeout, False otherwise
+        """
+        start_time = time.time()
+        url = f"http://localhost:{port}/health/liveliness"
+
+        while time.time() - start_time < timeout:
+            try:
+                with httpx.Client(timeout=httpx.Timeout(2.0)) as client:
+                    response = client.get(url)
+                    if response.status_code == 200:
+                        return True
+            except (httpx.RequestError, httpx.TimeoutException):
+                pass
+            time.sleep(0.5)
+
+        return False
+
+    def start(self, backend_id: str, config_path: Path, port: int) -> BackendInstance:
+        """Start LiteLLM backend.
+
+        Args:
+            backend_id: Backend instance ID (e.g., "litellm-4000")
+            config_path: Path to LiteLLM config file
+            port: Port number to bind
+
+        Returns:
+            BackendInstance with PID and status
+
+        Raises:
+            BackendStartError: If backend fails to start
+
+        Note:
+            Required env vars (GEMINI_API_KEY, OPENAI_API_KEY, etc.) should
+            already be in os.environ - validation happens before this method
+            is called. We pass through the full environment to the subprocess.
+        """
+        # Build command — resolve the litellm binary from the same venv as
+        # sys.executable, rather than relying on a bare 'litellm' on PATH.
+        # Console scripts (pip, litellm, etc.) are always siblings of python
+        # in the venv's bin/ directory.
+        litellm_bin = str(Path(sys.executable).parent / "litellm")
+        cmd = [litellm_bin, "--config", str(config_path), "--port", str(port)]
+
+        # Pass through current environment (includes API keys loaded by load_config)
+        log_file = get_forge_home() / "logs" / "backend" / f"litellm-{port}.log"
+        log_file.parent.mkdir(parents=True, exist_ok=True)
+
+        with log_file.open("a") as log:
+            proc = subprocess.Popen(
+                cmd,
+                env=os.environ.copy(),
+                stdout=log,
+                stderr=subprocess.STDOUT,
+                start_new_session=True,  # Detach from parent
+            )
+
+        # Wait for health (timeout 10s)
+        if not self._wait_for_health(port, timeout=10):
+            try:
+                proc.kill()
+            except OSError:
+                pass  # Process already exited
+            raise BackendStartError(f"LiteLLM failed to start on port {port}\nCheck logs: {log_file}")
+
+        return BackendInstance(
+            backend_id=backend_id,
+            adapter_type="litellm",
+            port=port,
+            pid=proc.pid,
+            status="healthy",
+            created_at=now_iso(),
+        )
+
+    def stop(self, instance: BackendInstance) -> None:
+        """Stop LiteLLM backend (best effort).
+
+        Args:
+            instance: Backend instance to stop
+        """
+        if instance.pid is None:
+            return
+
+        try:
+            os.kill(instance.pid, 15)  # SIGTERM
+        except (ProcessLookupError, PermissionError):
+            pass
+
+    def health_check(self, instance: BackendInstance) -> bool:
+        """Check if LiteLLM backend is healthy.
+
+        Uses /health/liveliness for fast checks (~5ms) rather than the full
+        /health endpoint which contacts all model providers (~5-10s).
+
+        Args:
+            instance: Backend instance to check
+
+        Returns:
+            True if healthy, False otherwise
+        """
+        try:
+            url = f"http://localhost:{instance.port}/health/liveliness"
+            with httpx.Client(timeout=httpx.Timeout(2.0)) as client:
+                response = client.get(url)
+                return response.status_code == 200
+        except (httpx.RequestError, httpx.TimeoutException):
+            return False

forge/backend/creation.py

@@ -0,0 +1,89 @@
+"""Backend config creation (copy templates to installed location)."""
+
+from __future__ import annotations
+
+import hashlib
+import shutil
+from pathlib import Path
+
+from forge.config.loader import get_defaults_dir
+from forge.core.paths import get_forge_home
+
+
+def create_backend_config(
+    adapter_type: str,
+    source_config: Path | None = None,
+) -> Path:
+    """Create backend config by copying to installed location.
+
+    Config is shared by all instances of the same adapter type.
+
+    Args:
+        adapter_type: Adapter type (e.g., "litellm")
+        source_config: Source config file (defaults to defaults/backends/{adapter}.yaml)
+
+    Returns:
+        Path to created config file
+
+    Raises:
+        ValueError: If adapter type is unknown or source config not found
+    """
+    backend_dir = get_forge_home() / "backends" / adapter_type
+    backend_dir.mkdir(parents=True, exist_ok=True)
+
+    # Determine source config
+    if source_config is None:
+        # Use convention-based path: defaults/backends/{adapter}.yaml
+        defaults_dir = get_defaults_dir()  # src/forge/config/defaults/
+        source_config = defaults_dir / "backends" / f"{adapter_type}.yaml"
+
+    if not source_config.exists():
+        raise ValueError(
+            f"No default config for adapter '{adapter_type}': {source_config}\n"
+            f"Either provide --config or create {source_config}"
+        )
+
+    # Copy config (idempotent - overwrites if exists)
+    dest_config = backend_dir / "config.yaml"
+    shutil.copy(source_config, dest_config)
+    dest_config.chmod(0o600)
+
+    return dest_config
+
+
+def get_backend_config_path(adapter_type: str) -> Path:
+    """Get path to backend config file.
+
+    Args:
+        adapter_type: Adapter type (e.g., "litellm")
+
+    Returns:
+        Path to config file (may not exist yet)
+    """
+    return get_forge_home() / "backends" / adapter_type / "config.yaml"
+
+
+def is_backend_config_outdated(adapter_type: str) -> bool:
+    """Check if installed backend config differs from the default.
+
+    Compares SHA256 digests of the installed config and the default template.
+    Returns True if the installed config exists but differs from the default
+    (meaning new models or settings may be available).
+
+    Args:
+        adapter_type: Adapter type (e.g., "litellm")
+
+    Returns:
+        True if installed config is outdated, False otherwise.
+    """
+    installed = get_backend_config_path(adapter_type)
+    if not installed.exists():
+        return False  # No config yet — will be created on first use
+
+    default = get_defaults_dir() / "backends" / f"{adapter_type}.yaml"
+    if not default.exists():
+        return False  # No default to compare against
+
+    installed_digest = hashlib.sha256(installed.read_bytes()).hexdigest()
+    default_digest = hashlib.sha256(default.read_bytes()).hexdigest()
+    return installed_digest != default_digest

forge/backend/registry.py

@@ -0,0 +1,178 @@
+"""Backend registry for Forge backend services.
+
+A backend is a service that proxies depend on (e.g., LiteLLM on port 4000).
+The backend registry is stored at:
+
+- ~/.forge/backends/index.json
+
+This module implements a small, versioned JSON store with atomic writes.
+
+Ownership: Forge Backend Manager (`forge backend` CLI).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Callable, Literal
+
+import dacite
+
+from forge.core.paths import get_forge_home
+from forge.core.state import (
+    StateCorruptedError,
+    atomic_write_json,
+    file_lock_for_target,
+)
+
+logger = logging.getLogger(__name__)
+
+BACKEND_REGISTRY_VERSION = 1
+BACKENDS_DIR = "backends"
+BACKEND_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
+
+
+class BackendRegistryCorruptedError(StateCorruptedError):
+    """Raised when the backend registry cannot be parsed."""
+
+    pass
+
+
+@dataclass
+class BackendInstance:
+    """A backend instance (used both in registry and at runtime).
+
+    Timestamps are stored as ISO8601 strings.
+    """
+
+    backend_id: str  # e.g., "litellm-4000"
+    adapter_type: str  # e.g., "litellm"
+    port: int
+    pid: int | None = None
+    status: Literal["healthy", "unhealthy", "stopped", "unknown"] = "unknown"
+    created_at: str | None = None
+
+
+@dataclass
+class BackendRegistry:
+    """Backend registry file format."""
+
+    version: int = BACKEND_REGISTRY_VERSION
+    backends: dict[str, BackendInstance] = field(default_factory=dict)
+
+
+def get_backend_registry_path() -> Path:
+    """Return the full path to the backend registry file."""
+
+    return get_forge_home() / BACKENDS_DIR / BACKEND_INDEX_FILENAME
+
+
+class BackendRegistryStore:
+    """Manage the backend registry at ~/.forge/backends/index.json.
+
+    Error handling:
+    - Missing file: returns empty registry (self-healing)
+    - Corrupted file: raises BackendRegistryCorruptedError
+    """
+
+    def __init__(self, registry_path: Path | None = None) -> None:
+        self._registry_path = registry_path or get_backend_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) -> BackendRegistry:
+        if not self.exists():
+            return BackendRegistry()
+
+        try:
+            with open(self._registry_path, encoding="utf-8") as f:
+                data = json.load(f)
+        except json.JSONDecodeError as e:
+            raise BackendRegistryCorruptedError(str(self._registry_path), f"invalid JSON: {e}")
+        except OSError as e:
+            raise BackendRegistryCorruptedError(str(self._registry_path), f"read error: {e}")
+
+        version = data.get("version")
+        if version is None:
+            raise BackendRegistryCorruptedError(str(self._registry_path), "missing version field")
+        if version != BACKEND_REGISTRY_VERSION:
+            raise BackendRegistryCorruptedError(
+                str(self._registry_path),
+                f"incompatible version {version} (this Forge expects {BACKEND_REGISTRY_VERSION}). "
+                f"Delete this file and retry.",
+            )
+
+        try:
+            return dacite.from_dict(
+                data_class=BackendRegistry,
+                data=data,
+                config=dacite.Config(strict=True),
+            )
+        except (dacite.DaciteError, TypeError, KeyError) as e:
+            raise BackendRegistryCorruptedError(str(self._registry_path), f"deserialization error: {e}")
+
+    def write(self, registry: BackendRegistry) -> None:
+        data = asdict(registry)
+        atomic_write_json(self._registry_path, data)
+
+    def update(self, *, timeout_s: float, mutate: Callable[[BackendRegistry], None]) -> BackendRegistry:
+        """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 registry entries whose Forge-spawned pid is no longer running.
+
+        Definition of stale (normative):
+        - Only entries with pid != None are considered (Forge-spawned backends).
+        - Entries with pid == None are never auto-pruned.
+
+        Returns:
+            List of backend 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 backend_id, entry in list(registry.backends.items()):
+                if entry.pid is None:
+                    continue
+                if not is_pid_alive(entry.pid):
+                    del registry.backends[backend_id]
+                    stale_ids.append(backend_id)
+
+            if stale_ids:
+                self.write(registry)
+
+            return stale_ids
+
+    def list_backends(self) -> list[BackendInstance]:
+        """List all backends (prunes dead PIDs first).
+
+        Returns:
+            List of backend instances, ordered by creation time (oldest first).
+        """
+
+        self.prune_dead_pids()
+        registry = self.read()
+
+        backends = list(registry.backends.values())
+        backends.sort(key=lambda x: x.created_at or "")
+        return backends

forge/cli/__init__.py

@@ -0,0 +1,16 @@
+"""Forge CLI - Command line interface for Multi-Forge.
+
+Entry point: `forge` command (installed via pyproject.toml scripts).
+
+Usage:
+    forge session start [name]    # Create and start a new session
+    forge session resume <name>   # Resume an existing session (reattach or --fresh for context assembly)
+    forge session list            # List all sessions
+    forge session delete <name>   # Delete a session
+"""
+
+from __future__ import annotations
+
+from .main import main
+
+__all__ = ["main"]