multi-forge 0.2.0__py3-none-any.whl

forge/core/llm/types.py

@@ -0,0 +1,176 @@
+"""Canonical types for LLM client abstraction.
+
+These types provide a provider-agnostic interface for LLM interactions.
+All client implementations convert to/from these canonical types.
+"""
+
+from typing import Any, Literal, Self
+
+from pydantic import BaseModel, Field, model_validator
+
+ReasoningEffort = Literal["none", "low", "medium", "high", "xhigh"]
+Verbosity = Literal["low", "medium", "high", "xhigh", "max"]
+MessageRole = Literal["system", "user", "assistant", "tool"]
+StreamEventType = Literal["text_delta", "tool_call_delta", "response_end", "usage", "error"]
+# Client-side prompt caching policy (NOT provider mechanism)
+# Provider mechanisms (auto, explicit, context_cache_api) are in model_catalog.yaml
+PromptCachingPolicy = Literal["passthrough", "auto_inject"]
+
+
+class ThinkingConfig(BaseModel):
+    """Direct thinking mode control (Gemini/Claude extended thinking)."""
+
+    type: Literal["enabled", "disabled", "adaptive"] = "enabled"
+    budget_tokens: int = 8192
+
+    @model_validator(mode="after")
+    def validate_budget_tokens(self) -> Self:
+        """Validate budget_tokens is positive when thinking is enabled/adaptive."""
+        if self.type in ("enabled", "adaptive") and self.budget_tokens <= 0:
+            raise ValueError("budget_tokens must be positive when thinking is enabled")
+        return self
+
+
+class InjectionPoint(BaseModel):
+    """Typed injection point for auto_inject cache control.
+
+    Specifies where to add cache_control directives in messages.
+    """
+
+    location: Literal["message"] = "message"
+    role: Literal["system", "user", "assistant"] | None = None
+    index: int | None = None  # Target by index (-1 = last message)
+
+
+class PromptCachingConfig(BaseModel):
+    """Client-side prompt caching configuration for LLM calls.
+
+    Policies (client behavior):
+    - passthrough: Honor caller's cache_control if provided (default)
+    - auto_inject: Force cache_control injection even if caller didn't specify
+                   (uses LiteLLM's cache_control_injection_points)
+
+    Note: Provider mechanisms (auto, explicit, context_cache_api) are defined
+    in model_catalog.yaml under prompt_caching.mechanism, not here.
+    """
+
+    policy: PromptCachingPolicy = "passthrough"
+    # For auto_inject policy: where to inject cache_control
+    injection_points: list[InjectionPoint] | None = None
+
+    @model_validator(mode="after")
+    def validate_injection_points(self) -> Self:
+        """Validate injection_points is provided when policy is auto_inject."""
+        if self.policy == "auto_inject" and not self.injection_points:
+            # Default: cache system messages
+            self.injection_points = [InjectionPoint(location="message", role="system")]
+        return self
+
+
+class ModelHyperparameters(BaseModel):
+    """Provider-agnostic parameters for LLM calls.
+
+    Timeout and prompt caching are operational parameters that vary by model:
+    - Reasoning models (GPT-5, o3) need longer timeouts (180-300s)
+    - Fast models (GPT-4o-mini, Haiku) can use shorter timeouts (30-60s)
+    - Prompt caching mode controls whether cache_control is passed through or auto-injected
+    """
+
+    max_tokens: int = 4096
+    temperature: float | None = None
+    top_p: float | None = None
+    reasoning_effort: ReasoningEffort | None = None
+    thinking: ThinkingConfig | None = None
+    verbosity: Verbosity | None = None
+    timeout: int | None = None  # Request timeout in seconds (None = use model default)
+    prompt_caching: PromptCachingConfig | None = None
+    strict: bool = False  # Raise UnsupportedParamError instead of warn+ignore
+    # Provider-specific extras, namespaced: {"openai": {...}, "anthropic": {...}}
+    extra: dict[str, dict[str, Any]] = Field(default_factory=dict)
+
+    @model_validator(mode="after")
+    def validate_hyperparameters(self) -> Self:
+        """Validate numeric hyperparameters are within valid ranges.
+
+        Catches invalid values early rather than failing at the LLM provider.
+        """
+        if self.max_tokens <= 0:
+            raise ValueError(f"max_tokens must be positive, got {self.max_tokens}")
+        if self.max_tokens > 1_000_000:
+            raise ValueError(f"max_tokens exceeds maximum (1M), got {self.max_tokens}")
+
+        if self.temperature is not None:
+            if not 0.0 <= self.temperature <= 2.0:
+                raise ValueError(f"temperature must be between 0.0 and 2.0, got {self.temperature}")
+
+        if self.top_p is not None:
+            if not 0.0 <= self.top_p <= 1.0:
+                raise ValueError(f"top_p must be between 0.0 and 1.0, got {self.top_p}")
+
+        if self.timeout is not None:
+            if self.timeout <= 0:
+                raise ValueError(f"timeout must be positive, got {self.timeout}")
+            if self.timeout > 600:
+                raise ValueError(f"timeout exceeds maximum (600s), got {self.timeout}")
+
+        return self
+
+
+class ToolCall(BaseModel):
+    """Canonical tool call representation (stable across providers).
+
+    Represents a complete, parsed tool call ready for execution.
+    """
+
+    id: str
+    name: str
+    arguments: dict[str, Any]  # Parsed arguments (not raw JSON string)
+
+
+class ToolCallDelta(BaseModel):
+    """Partial tool call for streaming (accumulate until complete).
+
+    During streaming, tool calls arrive in fragments. Accumulate these
+    deltas until the stream completes, then parse into ToolCall.
+
+    OpenAI streaming sends `id` only on the first chunk for each tool call.
+    Subsequent argument chunks use `index` (integer) to correlate.
+    """
+
+    index: int | None = None  # OpenAI tool call index (stable across chunks)
+    id: str | None = None
+    name: str | None = None
+    arguments_json: str = ""  # Raw JSON fragment, parse when complete
+
+
+class Message(BaseModel):
+    """Canonical message format."""
+
+    role: MessageRole
+    content: str | list[dict[str, Any]]  # text or content blocks
+    tool_call_id: str | None = None  # For role="tool" responses
+    tool_calls: list[ToolCall] | None = None  # For role="assistant" with tool use
+
+
+class CompletionResponse(BaseModel):
+    """Canonical completion response."""
+
+    text: str
+    tool_calls: list[ToolCall] | None = None
+    usage: dict[str, int] | None = None  # {prompt_tokens, completion_tokens, total_tokens}
+    raw: dict[str, Any] | None = None  # Original provider response (debugging only)
+
+
+class StreamEvent(BaseModel):
+    """Canonical streaming event.
+
+    For type="response_end", tool_calls contains the finalized list of
+    complete ToolCall objects accumulated from tool_call_delta events.
+    """
+
+    type: StreamEventType
+    text: str | None = None
+    tool_call_delta: ToolCallDelta | None = None
+    tool_calls: list[ToolCall] | None = None  # Finalized tool calls at response_end
+    usage: dict[str, int] | None = None
+    error: str | None = None

forge/core/logging.py

@@ -0,0 +1,146 @@
+"""File logging for Forge.
+
+Activated by ``log_level`` config setting or ``FORGE_DEBUG=1`` env var.
+Attaches a RotatingFileHandler to the ``forge`` logger namespace so all child
+loggers (forge.cli.*, forge.session.*, forge.core.*, etc.) emit to disk.
+
+No file I/O occurs when the effective log_level is "off".
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from logging.handlers import RotatingFileHandler
+from pathlib import Path
+
+_LEVEL_MAP = {
+    "debug": logging.DEBUG,
+    "info": logging.INFO,
+    "warning": logging.WARNING,
+}
+
+
+def get_effective_log_level() -> str:
+    """Resolve effective log level (env var overrides are applied in RuntimeConfig).
+
+    Returns:
+        "off", "debug", "info", or "warning".
+    """
+    try:
+        from forge.runtime_config import get_runtime_config
+
+        return get_runtime_config().log_level
+    except Exception:
+        return "off"
+
+
+def configure_debug_logging(component: str, subdirectory: str) -> None:
+    """Attach a RotatingFileHandler to the 'forge' namespace.
+
+    Activates when log_level config is not "off" or FORGE_DEBUG=1.
+    Per-PID log files avoid multi-process rotation conflicts.
+
+    Fail-open: permission errors or missing dirs don't crash the command.
+
+    Args:
+        component: Log filename stem (e.g., "session-start", "session").
+        subdirectory: Directory under $FORGE_HOME/logs/ (e.g., "hooks", "cli").
+    """
+    level = get_effective_log_level()
+    if level == "off":
+        return
+
+    forge_logger = logging.getLogger("forge")
+
+    try:
+        from forge.core.paths import get_forge_home
+
+        logs_dir = get_forge_home() / "logs" / subdirectory
+        logs_dir.mkdir(exist_ok=True, parents=True)
+
+        pid = os.getpid()
+        log_file = logs_dir / f"{component}.{pid}.log"
+
+        # Idempotency: skip if THIS exact file handler is already attached.
+        for h in forge_logger.handlers:
+            if isinstance(h, RotatingFileHandler) and getattr(h, "baseFilename", None) == str(log_file):
+                return
+
+        py_level = _LEVEL_MAP.get(level, logging.DEBUG)
+        forge_logger.setLevel(py_level)
+        forge_logger.propagate = False
+
+        fmt = logging.Formatter(
+            "%(asctime)s.%(msecs)03d | %(levelname)-8s | %(process)d | "
+            "%(name)s:%(funcName)s:%(lineno)d - %(message)s",
+            datefmt="%Y-%m-%d %H:%M:%S",
+        )
+        handler = RotatingFileHandler(str(log_file), maxBytes=10 * 1024 * 1024, backupCount=5)
+        handler.setLevel(py_level)
+        handler.setFormatter(fmt)
+        forge_logger.addHandler(handler)
+
+        # Set 0600 perms — log files may contain payload fragments / hostnames.
+        try:
+            os.chmod(str(log_file), 0o600)
+        except OSError:
+            pass
+    except Exception:
+        pass  # Fail-open: don't crash the command because logging couldn't start
+
+
+def configure_console_logging() -> None:
+    """Attach a stderr StreamHandler to the 'forge' namespace.
+
+    For long-running processes (proxy server) that need visible console output
+    in addition to file logging. Idempotent: skips if a stderr handler exists.
+
+    No-op when log_level is "off".
+    """
+    level = get_effective_log_level()
+    if level == "off":
+        return
+
+    py_level = _LEVEL_MAP.get(level, logging.DEBUG)
+    forge_logger = logging.getLogger("forge")
+
+    import sys
+
+    has_stderr = any(
+        isinstance(h, logging.StreamHandler)
+        and not isinstance(h, logging.FileHandler)
+        and getattr(h, "stream", None) is sys.stderr
+        for h in forge_logger.handlers
+    )
+    if has_stderr:
+        return
+
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setLevel(py_level)
+    handler.setFormatter(
+        logging.Formatter(
+            "%(asctime)s | %(levelname)-8s | %(process)d | %(name)s:%(funcName)s:%(lineno)d - %(message)s",
+            datefmt="%Y-%m-%d %H:%M:%S",
+        )
+    )
+    forge_logger.addHandler(handler)
+
+
+def find_latest_log(subdirectory: str, glob_pattern: str) -> Path | None:
+    """Find the most recently modified log file in a subdirectory.
+
+    Args:
+        subdirectory: Directory under $FORGE_HOME/logs/ (e.g., "proxy").
+        glob_pattern: Glob pattern to match (e.g., "proxy.*.log").
+    """
+    try:
+        from forge.core.paths import get_forge_home
+
+        logs_dir = get_forge_home() / "logs" / subdirectory
+        if not logs_dir.exists():
+            return None
+        log_files = sorted(logs_dir.glob(glob_pattern), key=lambda p: p.stat().st_mtime, reverse=True)
+        return log_files[0] if log_files else None
+    except Exception:
+        return None

forge/core/models/__init__.py

@@ -0,0 +1,91 @@
+"""Central model catalog for intrinsic model properties.
+
+This module is the single source of truth for model capabilities:
+- Context window sizes
+- Maximum output tokens
+- Thinking/reasoning support and configuration
+- Temperature constraints
+- Verbosity support
+- API requirements (responses API, etc.)
+
+Usage:
+    from forge.core.models import (
+        get_model_spec,
+        get_context_window_tokens,
+        get_max_output_tokens,
+        resolve_model_id,
+        model_exists,
+    )
+
+    # Get full spec for a model
+    spec = get_model_spec("gpt-5.5")
+    print(spec.context_window_tokens)  # 400000
+    print(spec.litellm_reasoning_efforts)  # ('none', 'low', 'medium', 'high', 'xhigh')
+    print(spec.supports_verbosity)  # True
+
+    # Aliases work transparently
+    spec = get_model_spec("openai/gpt-5.5")  # Same result
+
+    # Convenience functions
+    ctx = get_context_window_tokens("gemini-3.1-pro-preview")  # 1048576
+    max_out = get_max_output_tokens("gpt-5.5")  # 128000
+
+    # Check existence without raising
+    if model_exists("unknown-model"):
+        ...
+"""
+
+from forge.core.models.catalog import (
+    ModelCatalogError,
+    get_compact_name,
+    get_context_window_tokens,
+    get_default_model,
+    get_max_output_tokens,
+    get_model_spec,
+    get_provider_defaults,
+    get_system_prompt_addendum,
+    load_model_catalog,
+    model_exists,
+    resolve_model_id,
+)
+from forge.core.models.pricing import (
+    ModelPricing,
+    calculate_cost,
+    get_pricing,
+    micros_to_usd,
+)
+from forge.core.models.types import (
+    ModelCatalog,
+    ModelSpec,
+    TemperatureSpec,
+)
+
+__all__ = [
+    # Catalog loader
+    "load_model_catalog",
+    # Lookup functions (strict)
+    "resolve_model_id",
+    "get_model_spec",
+    "get_context_window_tokens",
+    "get_max_output_tokens",
+    # Non-strict check
+    "model_exists",
+    # Defaults
+    "get_default_model",
+    "get_provider_defaults",
+    # Display
+    "get_compact_name",
+    # System prompt addendum
+    "get_system_prompt_addendum",
+    # Error type
+    "ModelCatalogError",
+    # Pricing
+    "ModelPricing",
+    "get_pricing",
+    "calculate_cost",
+    "micros_to_usd",
+    # Types
+    "ModelCatalog",
+    "ModelSpec",
+    "TemperatureSpec",
+]