multi-forge 0.2.0__py3-none-any.whl

forge/config/__init__.py

@@ -0,0 +1,110 @@
+"""Unified configuration system for Multi-Forge.
+
+This module provides a type-safe configuration system with three sources:
+
+    1. Proxy file: ~/.forge/proxies/{id}/proxy.yaml (user owns full config)
+    2. Template: defaults/templates/{t}.yaml (for proxy creation only)
+    3. Secrets: .env + env vars (*_API_KEY, *_AUTH_URL, FORGE_HOME)
+
+Schema defaults in dataclasses handle missing fields.
+
+Usage:
+    from forge.config import config
+
+    # Access configuration
+    model = config.proxy.litellm.tiers.opus
+    overrides = config.proxy.litellm.tier_overrides.get("opus")
+
+    # Load with specific proxy
+    from forge.config import load_config
+    config = load_config(proxy_id="my-proxy")
+
+    # Load template (for proxy creation)
+    config = load_config(template="litellm-gemini")
+
+    # Reload configuration
+    from forge.config import reload
+    reload(proxy_id="my-proxy")
+"""
+
+from forge.config.loader import load_config, reload_config
+from forge.config.schema import (
+    OPENAI_MODELS,
+    ForgeConfig,
+    ProviderConfig,
+    ProxyConfig,
+    SessionConfig,
+    TierModels,
+    TierOverride,
+    TierOverrides,
+    is_openai_model,
+)
+
+__all__ = [
+    # Main config instance
+    "config",
+    # Functions
+    "load_config",
+    "reload",
+    "get_config",
+    "init_config",
+    # Helper functions
+    "is_openai_model",
+    # Constants
+    "OPENAI_MODELS",
+    # Schema classes (for type hints)
+    "ForgeConfig",
+    "ProxyConfig",
+    "SessionConfig",
+    "ProviderConfig",
+    "TierModels",
+    "TierOverride",
+    "TierOverrides",
+]
+
+# Global config instance (singleton)
+_config: ForgeConfig | None = None
+
+
+def get_config() -> ForgeConfig:
+    """Get the global config instance, loading if necessary."""
+    global _config
+    if _config is None:
+        _config = load_config()
+    return _config
+
+
+def reload(*, template: str | None = None, proxy_id: str | None = None) -> ForgeConfig:
+    """Reload configuration from all sources."""
+    global _config
+    if _config is not None:
+        _config = reload_config(_config, template=template, proxy_id=proxy_id)
+    else:
+        _config = load_config(template=template, proxy_id=proxy_id)
+    return _config
+
+
+def init_config(*, template: str | None = None, proxy_id: str | None = None) -> ForgeConfig:
+    """Initialize configuration with optional template/proxy.
+
+    Call this at application startup to load config with a specific template.
+    Subsequent calls to get_config() will return this instance.
+    """
+    global _config
+    _config = load_config(template=template, proxy_id=proxy_id)
+    return _config
+
+
+# Lazy-loaded config property
+class _ConfigProxy:
+    """Proxy that lazily loads config on first access."""
+
+    def __getattr__(self, name: str):
+        return getattr(get_config(), name)
+
+    def __repr__(self) -> str:
+        return repr(get_config())
+
+
+# Export lazy config proxy as 'config'
+config: ForgeConfig = _ConfigProxy()  # type: ignore[assignment]  # _ConfigProxy delegates to ForgeConfig at runtime

forge/config/dataclass_utils.py

@@ -0,0 +1,88 @@
+"""Dict-to-dataclass conversion utilities.
+
+Extracted from loader.py to break the loader ↔ schema import cycle (CR-007).
+"""
+
+from __future__ import annotations
+
+import types
+from dataclasses import fields, is_dataclass
+from typing import Any, Union, get_args, get_origin
+
+
+def _is_union_type(origin: Any) -> bool:
+    """Check if origin indicates a Union type (typing.Union or types.UnionType)."""
+    if origin is Union:
+        return True
+    # PEP604 union (e.g., int | str, X | None) — Python 3.10+
+    if origin is types.UnionType:
+        return True
+    return False
+
+
+def _unwrap_optional(field_type: Any) -> tuple[Any, bool]:
+    """Unwrap Optional[X] or X | None to X.
+
+    Returns:
+        (unwrapped_type, is_optional): The unwrapped type and whether it was Optional.
+    """
+    origin = get_origin(field_type)
+    if not _is_union_type(origin):
+        return field_type, False
+
+    args = get_args(field_type)
+    non_none_args = [a for a in args if a is not type(None)]
+
+    if type(None) in args and len(non_none_args) == 1:
+        return non_none_args[0], True
+
+    return field_type, False
+
+
+def dict_to_dataclass(cls: type[Any], data: dict, *, strict: bool = False) -> Any:
+    """Convert nested dict to dataclass instance.
+
+    Recursively converts nested dicts to their corresponding dataclass types.
+    Handles Optional types, lists, and primitive types.
+
+    Args:
+        strict: If True, raise ValueError on unknown keys not present in the dataclass.
+    """
+    if not is_dataclass(cls):
+        return data  # type: ignore[return-value]  # returns raw dict when cls is not a dataclass
+
+    if strict:
+        known = {f.name for f in fields(cls)}
+        unknown = set(data.keys()) - known
+        if unknown:
+            raise ValueError(f"{cls.__name__} has unknown fields: {', '.join(sorted(unknown))}")
+
+    kwargs: dict[str, Any] = {}
+    for f in fields(cls):
+        if f.name not in data:
+            continue
+
+        value = data[f.name]
+        field_type = f.type
+
+        unwrapped_type, is_optional = _unwrap_optional(field_type)
+
+        if value is None and is_optional:
+            kwargs[f.name] = value
+            continue
+
+        origin = get_origin(unwrapped_type)
+
+        if origin is list and isinstance(value, list):
+            kwargs[f.name] = value
+        elif is_dataclass(unwrapped_type) and isinstance(value, dict):
+            if isinstance(unwrapped_type, type):
+                kwargs[f.name] = dict_to_dataclass(unwrapped_type, value, strict=strict)
+            else:
+                kwargs[f.name] = value
+        elif _is_union_type(origin):
+            kwargs[f.name] = value
+        else:
+            kwargs[f.name] = value
+
+    return cls(**kwargs)

forge/config/defaults/backends/litellm.yaml

@@ -0,0 +1,196 @@
+# LiteLLM Local Proxy Configuration
+# For use with personal API keys (Gemini and/or OpenAI)
+#
+# Supported models:
+#   Gemini (requires GEMINI_API_KEY):
+#     - gemini/gemini-3.1-pro-preview (Gemini 3.1 Pro - latest with thinking)
+#     - gemini/gemini-3.1-pro-preview-customtools (optimized for custom tools + bash)
+#     - gemini/gemini-3-flash-preview (Gemini 3 Flash - fast, cheap)
+#     - gemini/gemini-2.5-flash (fast, cheap)
+#     - gemini/gemini-2.5-pro (powerful)
+#
+#   OpenAI (requires OPENAI_API_KEY):
+#     - openai/gpt-5, gpt-5-codex, gpt-5-mini, gpt-5-nano, gpt-5-pro
+#     - openai/gpt-5.1, gpt-5.1-codex, gpt-5.1-codex-max, gpt-5.1-codex-mini
+#     - openai/gpt-5.2, gpt-5.2-codex, gpt-5.2-pro
+#     - openai/gpt-5.3-codex
+#     - openai/gpt-5.4, gpt-5.4-pro
+#     - openai/gpt-5.5
+#
+# Start with: forge backend start litellm --port 4000
+
+model_list:
+  # Gemini 3.1 Pro Preview - latest model with thinking support
+  - model_name: gemini/gemini-3.1-pro-preview
+    litellm_params:
+      model: gemini/gemini-3.1-pro-preview
+      api_key: os.environ/GEMINI_API_KEY
+
+  # Gemini 3.1 Pro Preview (Custom Tools) - optimized for agentic workflows with custom tools + bash
+  - model_name: gemini/gemini-3.1-pro-preview-customtools
+    litellm_params:
+      model: gemini/gemini-3.1-pro-preview-customtools
+      api_key: os.environ/GEMINI_API_KEY
+
+  # Gemini 3 Flash Preview - fast and cheap
+  - model_name: gemini/gemini-3-flash-preview
+    litellm_params:
+      model: gemini/gemini-3-flash-preview
+      api_key: os.environ/GEMINI_API_KEY
+
+  # Gemini 2.5 Flash - fast and cheap
+  - model_name: gemini/gemini-2.5-flash
+    litellm_params:
+      model: gemini/gemini-2.5-flash
+      api_key: os.environ/GEMINI_API_KEY
+
+  # Gemini 2.5 Pro - powerful
+  - model_name: gemini/gemini-2.5-pro
+    litellm_params:
+      model: gemini/gemini-2.5-pro
+      api_key: os.environ/GEMINI_API_KEY
+
+  # Aliases for convenience (match config.yaml model names)
+  - model_name: gemini-3.1-pro-preview
+    litellm_params:
+      model: gemini/gemini-3.1-pro-preview
+      api_key: os.environ/GEMINI_API_KEY
+
+  - model_name: gemini-3.1-pro-preview-customtools
+    litellm_params:
+      model: gemini/gemini-3.1-pro-preview-customtools
+      api_key: os.environ/GEMINI_API_KEY
+
+  - model_name: gemini-3-flash-preview
+    litellm_params:
+      model: gemini/gemini-3-flash-preview
+      api_key: os.environ/GEMINI_API_KEY
+
+  - model_name: gemini-2.5-flash
+    litellm_params:
+      model: gemini/gemini-2.5-flash
+      api_key: os.environ/GEMINI_API_KEY
+
+  - model_name: gemini-2.5-pro
+    litellm_params:
+      model: gemini/gemini-2.5-pro
+      api_key: os.environ/GEMINI_API_KEY
+
+  # =========================================================================
+  # OpenAI Models (requires OPENAI_API_KEY)
+  # =========================================================================
+
+  # --- GPT-5 family ---
+  - model_name: openai/gpt-5
+    litellm_params:
+      model: openai/gpt-5
+      api_key: os.environ/OPENAI_API_KEY
+
+  - model_name: openai/gpt-5-codex
+    litellm_params:
+      model: openai/gpt-5-codex
+      api_key: os.environ/OPENAI_API_KEY
+
+  - model_name: openai/gpt-5-mini
+    litellm_params:
+      model: openai/gpt-5-mini
+      api_key: os.environ/OPENAI_API_KEY
+
+  - model_name: openai/gpt-5-nano
+    litellm_params:
+      model: openai/gpt-5-nano
+      api_key: os.environ/OPENAI_API_KEY
+
+  - model_name: openai/gpt-5-pro
+    litellm_params:
+      model: openai/gpt-5-pro
+      api_key: os.environ/OPENAI_API_KEY
+
+  # --- GPT-5.1 family ---
+  - model_name: openai/gpt-5.1
+    litellm_params:
+      model: openai/gpt-5.1
+      api_key: os.environ/OPENAI_API_KEY
+
+  - model_name: openai/gpt-5.1-codex
+    litellm_params:
+      model: openai/gpt-5.1-codex
+      api_key: os.environ/OPENAI_API_KEY
+
+  - model_name: openai/gpt-5.1-codex-max
+    litellm_params:
+      model: openai/gpt-5.1-codex-max
+      api_key: os.environ/OPENAI_API_KEY
+
+  - model_name: openai/gpt-5.1-codex-mini
+    litellm_params:
+      model: openai/gpt-5.1-codex-mini
+      api_key: os.environ/OPENAI_API_KEY
+
+  # --- GPT-5.2 family ---
+  - model_name: openai/gpt-5.2
+    litellm_params:
+      model: openai/gpt-5.2
+      api_key: os.environ/OPENAI_API_KEY
+
+  - model_name: openai/gpt-5.2-codex
+    litellm_params:
+      model: openai/gpt-5.2-codex
+      api_key: os.environ/OPENAI_API_KEY
+
+  - model_name: openai/gpt-5.2-pro
+    litellm_params:
+      model: openai/gpt-5.2-pro
+      api_key: os.environ/OPENAI_API_KEY
+
+  # --- GPT-5.3 family ---
+  - model_name: openai/gpt-5.3-codex
+    litellm_params:
+      model: openai/gpt-5.3-codex
+      api_key: os.environ/OPENAI_API_KEY
+
+  # --- GPT-5.4 family ---
+  - model_name: openai/gpt-5.4
+    litellm_params:
+      model: openai/gpt-5.4
+      api_key: os.environ/OPENAI_API_KEY
+
+  - model_name: openai/gpt-5.4-pro
+    litellm_params:
+      model: openai/gpt-5.4-pro
+      api_key: os.environ/OPENAI_API_KEY
+
+  - model_name: openai/gpt-5.4-mini
+    litellm_params:
+      model: openai/gpt-5.4-mini
+      api_key: os.environ/OPENAI_API_KEY
+
+  - model_name: openai/gpt-5.4-nano
+    litellm_params:
+      model: openai/gpt-5.4-nano
+      api_key: os.environ/OPENAI_API_KEY
+
+  # --- GPT-5.5 ---
+  - model_name: openai/gpt-5.5
+    litellm_params:
+      model: openai/gpt-5.5
+      api_key: os.environ/OPENAI_API_KEY
+
+litellm_settings:
+  # Drop unmapped params instead of erroring
+  drop_params: true
+
+  # Enable detailed logging for debugging
+  set_verbose: false
+
+  # Request timeout
+  request_timeout: 600
+
+# General settings (optional)
+# general_settings:
+#   # Master key for API authentication (optional)
+#   # Set via: export LITELLM_MASTER_KEY="sk-your-key"
+#   master_key: os.environ/LITELLM_MASTER_KEY
+#
+#   # Database for tracking (optional)
+#   # database_url: "postgresql://..."

forge/config/defaults/templates/litellm-anthropic-local.yaml

@@ -0,0 +1,33 @@
+# Template: litellm-anthropic-local
+# Anthropic Claude via local LiteLLM with personal API key (DEVELOPMENT)
+#
+# Requires:
+#   - ANTHROPIC_API_KEY in .env
+#
+# Backend (LiteLLM on port 4000) starts automatically.
+#
+# Note: If you added ANTHROPIC_API_KEY after the backend started,
+# restart with: forge backend stop litellm-4000
+
+proxy:
+  family: anthropic
+  preferred_provider: litellm
+  default_port: 8091
+
+  # Backend dependency (auto-started when proxy starts)
+  backend_dependency:
+    adapter: litellm
+    port: 4000
+    required_env_vars:
+      - ANTHROPIC_API_KEY
+
+  litellm:
+    tiers:
+      haiku: anthropic/claude-haiku-4-5
+      sonnet: anthropic/claude-sonnet-4-6
+      opus: anthropic/claude-opus-4-6
+    model_alternatives:
+      opus:
+        claude-opus-4-7: anthropic/claude-opus-4-7
+    prompt_caching: passthrough
+    error_hints: true

forge/config/defaults/templates/litellm-anthropic.yaml

@@ -0,0 +1,24 @@
+# Template: litellm-anthropic
+# Anthropic Claude via remote/shared LiteLLM
+#
+# Access to Claude Opus 4.6/4.7, Sonnet 4.6, and Haiku 4.5.
+# Requires LITELLM_API_KEY and LITELLM_BASE_URL in .env (or environment).
+#
+# Use --model claude-opus-4-7 to select Opus 4.7 instead of the 4.6 default.
+# prompt_caching: passthrough respects Anthropic's 4-breakpoint cache_control limit.
+
+proxy:
+  family: anthropic
+  preferred_provider: litellm
+  default_port: 8092
+
+  litellm:
+    tiers:
+      haiku: anthropic/claude-haiku-4-5
+      sonnet: anthropic/claude-sonnet-4-6
+      opus: anthropic/claude-opus-4-6
+    model_alternatives:
+      opus:
+        claude-opus-4-7: anthropic/claude-opus-4-7
+    prompt_caching: passthrough
+    error_hints: true

forge/config/defaults/templates/litellm-gemini-flash-local.yaml

@@ -0,0 +1,37 @@
+# Template: litellm-gemini-flash-local
+# Gemini 3 Flash via local LiteLLM (beats Pro on SWE benchmarks!)
+#
+# Requires:
+#   - GEMINI_API_KEY in .env
+#
+# Backend (LiteLLM on port 4000) starts automatically.
+# All tiers use Flash, differentiated by reasoning_effort.
+#
+# Note: If you added GEMINI_API_KEY after the backend started,
+# restart with: forge backend stop litellm-4000
+
+proxy:
+  family: gemini
+  preferred_provider: litellm
+  default_port: 8088
+
+  # Backend dependency (auto-started when proxy starts)
+  backend_dependency:
+    adapter: litellm
+    port: 4000
+    required_env_vars:
+      - GEMINI_API_KEY
+
+  litellm:
+    tiers:
+      haiku: gemini/gemini-3-flash-preview
+      sonnet: gemini/gemini-3-flash-preview
+      opus: gemini/gemini-3-flash-preview
+    # Per-tier overrides: all tiers use same model, differentiate by reasoning
+    tier_overrides:
+      haiku:
+        reasoning_effort: low
+      sonnet:
+        reasoning_effort: medium
+      opus:
+        reasoning_effort: high

forge/config/defaults/templates/litellm-gemini-local.yaml

@@ -0,0 +1,32 @@
+# Template: litellm-gemini-local
+# Gemini models via local LiteLLM proxy with personal API key (DEVELOPMENT)
+#
+# Requires:
+#   - GEMINI_API_KEY in .env
+#
+# Backend (LiteLLM on port 4000) starts automatically.
+# For tests: Use litellm-gemini-test template (port 4001)
+
+proxy:
+  family: gemini
+  preferred_provider: litellm
+  default_port: 8086
+
+  # Backend dependency (auto-started when proxy starts)
+  backend_dependency:
+    adapter: litellm
+    port: 4000
+    required_env_vars:
+      - GEMINI_API_KEY
+
+  litellm:
+    tiers:
+      haiku: gemini/gemini-3-flash-preview
+      sonnet: gemini/gemini-3.1-pro-preview
+      opus: gemini/gemini-3.1-pro-preview
+    # Per-tier overrides to differentiate sonnet/opus (both use same model)
+    tier_overrides:
+      sonnet:
+        reasoning_effort: medium
+      opus:
+        reasoning_effort: high

forge/config/defaults/templates/litellm-gemini-test.yaml

@@ -0,0 +1,34 @@
+# Template: litellm-gemini-test
+# Gemini models via local LiteLLM proxy on TEST port (4001)
+#
+# Requires:
+#   - GEMINI_API_KEY in .env
+#
+# Backend (LiteLLM on port 4001) starts automatically for test isolation.
+# Dev port is 4000, test port is 4001 (isolation).
+
+internal: true  # Hidden from user-facing template listings
+
+proxy:
+  family: gemini
+  preferred_provider: litellm
+  default_port: 8087
+
+  # Backend dependency (auto-started when proxy starts, test port for isolation)
+  backend_dependency:
+    adapter: litellm
+    port: 4001
+    required_env_vars:
+      - GEMINI_API_KEY
+
+  litellm:
+    tiers:
+      haiku: gemini/gemini-3-flash-preview
+      sonnet: gemini/gemini-3.1-pro-preview
+      opus: gemini/gemini-3.1-pro-preview
+    # Per-tier overrides to differentiate sonnet/opus (both use same model)
+    tier_overrides:
+      sonnet:
+        reasoning_effort: medium
+      opus:
+        reasoning_effort: high

forge/config/defaults/templates/litellm-gemini.yaml

@@ -0,0 +1,21 @@
+# Template: litellm-gemini
+# Gemini models via remote/shared LiteLLM
+#
+# Default template for Gemini access through a shared LiteLLM gateway.
+# Requires LITELLM_API_KEY and LITELLM_BASE_URL in .env (or environment).
+
+proxy:
+  family: gemini
+  preferred_provider: litellm
+  default_port: 8084
+
+  litellm:
+    tiers:
+      haiku: vertex_ai/gemini-2.5-flash
+      sonnet: vertex_ai/gemini-3.1-pro-preview
+      opus: vertex_ai/gemini-3.1-pro-preview
+    tier_overrides:
+      sonnet:
+        reasoning_effort: medium
+      opus:
+        reasoning_effort: high

forge/config/defaults/templates/litellm-openai-codex-local.yaml

@@ -0,0 +1,36 @@
+# Template: litellm-openai-codex-local
+# OpenAI Codex models via local LiteLLM with personal API key (DEVELOPMENT)
+#
+# Requires:
+#   - OPENAI_API_KEY in .env
+#
+# Backend (LiteLLM on port 4000) starts automatically.
+#
+# Note: If you added OPENAI_API_KEY after the backend started,
+# restart with: forge backend stop litellm-4000
+
+proxy:
+  family: openai
+  preferred_provider: litellm
+  default_port: 8090
+
+  # Backend dependency (auto-started when proxy starts)
+  backend_dependency:
+    adapter: litellm
+    port: 4000
+    required_env_vars:
+      - OPENAI_API_KEY
+
+  litellm:
+    tiers:
+      haiku: openai/gpt-5.1-codex-mini
+      sonnet: openai/gpt-5.3-codex
+      opus: openai/gpt-5.5
+    tier_overrides:
+      sonnet:
+        reasoning_effort: medium
+      opus:
+        reasoning_effort: high
+        verbosity: high
+    openai_api_mode: auto
+    error_hints: true

forge/config/defaults/templates/litellm-openai-local.yaml

@@ -0,0 +1,38 @@
+# Template: litellm-openai-local
+# OpenAI models via local LiteLLM with personal API key (DEVELOPMENT)
+#
+# Requires:
+#   - OPENAI_API_KEY in .env
+#
+# Backend (LiteLLM on port 4000) starts automatically.
+#
+# Note: If you added OPENAI_API_KEY after the backend started,
+# restart with: forge backend stop litellm-4000
+
+proxy:
+  family: openai
+  preferred_provider: litellm
+  default_port: 8089
+
+  # Backend dependency (auto-started when proxy starts)
+  backend_dependency:
+    adapter: litellm
+    port: 4000
+    required_env_vars:
+      - OPENAI_API_KEY
+
+  litellm:
+    tiers:
+      haiku: openai/gpt-5.4-mini
+      sonnet: openai/gpt-5.5
+      opus: openai/gpt-5.5
+    # Per-tier overrides to differentiate sonnet/opus (both use same model)
+    tier_overrides:
+      sonnet:
+        reasoning_effort: medium
+        verbosity: high
+      opus:
+        reasoning_effort: high
+        verbosity: high
+    openai_api_mode: auto
+    error_hints: true

forge/config/defaults/templates/litellm-openai.yaml

@@ -0,0 +1,28 @@
+# Template: litellm-openai
+# OpenAI models via remote/shared LiteLLM
+#
+# Access to GPT-4o, GPT-5, and O-series models.
+# Requires LITELLM_API_KEY and LITELLM_BASE_URL in .env (or environment).
+#
+# Haiku uses gpt-5.4-mini; sonnet and opus both use gpt-5.5,
+# differentiated by tier_overrides (reasoning_effort and verbosity).
+
+proxy:
+  family: openai
+  preferred_provider: litellm
+  default_port: 8085
+
+  litellm:
+    tiers:
+      haiku: openai/gpt-5.4-mini
+      sonnet: openai/gpt-5.5
+      opus: openai/gpt-5.5
+    tier_overrides:
+      sonnet:
+        reasoning_effort: medium
+        verbosity: high
+      opus:
+        reasoning_effort: high
+        verbosity: high
+    openai_api_mode: auto
+    error_hints: true