synapse-cli-agent 0.1.13__py3-none-any.whl

synapse/models/__init__.py

@@ -0,0 +1,5 @@
+"""Model profile registry and provider assembly."""
+
+from synapse.models.registry import ModelProfile, ModelRegistry, build_model_from_settings
+
+__all__ = ["ModelProfile", "ModelRegistry", "build_model_from_settings"]

synapse/models/config.py

@@ -0,0 +1,240 @@
+"""Model configuration parsing and normalization helpers."""
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+_ENV_PATTERN = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)")
+
+DEFAULT_MODELS_CONFIG_REL = Path(".coding-agent") / "models.json"
+
+THINKING_LEVELS = ("minimal", "low", "medium", "high", "max")
+DEFAULT_THINKING_LEVELS: tuple[str, ...] = ("off", *THINKING_LEVELS)
+
+_PROFILE_META_KEYS = {
+    "model", "api_key", "api_key_env", "base_url", "websocket",
+    "context_window", "contextwindow", "max_input_tokens", "enable_thinking",
+    "thinking", "thinking_level", "reasoning_effort", "thinking_levels",
+    "parallel_tool_calls", "image_input", "capabilities", "extra",
+    "model_kwargs", "extra_body", "params",
+}
+
+def expand_env_string(value: Any) -> Any:
+    """Expand ${VAR} / $VAR in string config values."""
+    if not isinstance(value, str):
+        return value
+
+    def repl(match: re.Match[str]) -> str:
+        key = match.group(1) or match.group(2)
+        return os.environ.get(key, "")
+
+    return _ENV_PATTERN.sub(repl, value)
+
+
+def parse_context_window(cfg: dict[str, Any] | None) -> int | None:
+    """Read context window (tokens) from a models.json profile object.
+
+    Accepts ``context_window``, ``contextwindow``, or ``max_input_tokens``.
+    Returns a positive int, or None when unset/invalid.
+    """
+    if not isinstance(cfg, dict):
+        return None
+    raw = cfg.get("context_window")
+    if raw is None:
+        raw = cfg.get("contextwindow")
+    if raw is None:
+        raw = cfg.get("max_input_tokens")
+    if raw is None or raw is False:
+        return None
+    try:
+        value = int(raw)
+    except (TypeError, ValueError):
+        return None
+    if value <= 0:
+        return None
+    return value
+
+
+def apply_context_window_to_model(model: Any, context_window: int | None) -> Any:
+    """Stamp ``max_input_tokens`` onto a chat model profile for summarization."""
+    if model is None or context_window is None:
+        return model
+    try:
+        size = int(context_window)
+    except (TypeError, ValueError):
+        return model
+    if size <= 0:
+        return model
+    existing = getattr(model, "profile", None)
+    profile: dict[str, Any]
+    if isinstance(existing, dict):
+        profile = dict(existing)
+    else:
+        profile = {}
+    profile["max_input_tokens"] = size
+    try:
+        model.profile = profile
+    except Exception:  # noqa: BLE001
+        # Some wrappers expose read-only profile; best-effort only.
+        try:
+            object.__setattr__(model, "profile", profile)
+        except Exception:  # noqa: BLE001
+            pass
+    return model
+
+
+def parse_optional_bool(value: Any, *, field_name: str = "image_input") -> bool | None:
+    """Parse JSON and common string boolean values without truthiness surprises."""
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        normalized = value.strip().casefold()
+        if normalized in {"true", "1", "yes", "on", "enabled"}:
+            return True
+        if normalized in {"false", "0", "no", "off", "disabled"}:
+            return False
+    raise ValueError(f"{field_name} must be a boolean")
+
+
+def normalize_thinking_level(value: Any) -> str | None:
+    """Normalize thinking level / reasoning_effort to a canonical string.
+
+    Accepts: off|minimal|low|medium|high|max, plus common aliases
+    (min, med, xhigh, ultra).
+    """
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        return "high" if value else "off"
+    text = str(value).strip().casefold()
+    if not text:
+        return None
+    if text in {"off", "false", "0", "disabled", "none", "no"}:
+        return "off"
+    aliases = {
+        "min": "minimal",
+        "minimal": "minimal",
+        "low": "low",
+        "medium": "medium",
+        "med": "medium",
+        "mid": "medium",
+        "high": "high",
+        "max": "max",
+        "maximum": "max",
+        "xhigh": "max",
+        "ultra": "max",
+        "highest": "max",
+    }
+    if text in aliases:
+        return aliases[text]
+    # pass through unknown provider-specific values (e.g. "xhigh" already mapped)
+    return str(value).strip()
+
+
+def parse_thinking_levels(raw: Any) -> list[str] | None:
+    """Parse a thinking_levels array into canonical labels.
+
+    Returns None when unset. Accepts strings like off|low|medium|high|max.
+    """
+    if raw is None:
+        return None
+    if not isinstance(raw, list):
+        raise ValueError("thinking_levels must be an array of strings")
+    out: list[str] = []
+    seen: set[str] = set()
+    for item in raw:
+        level = normalize_thinking_level(item)
+        if not level:
+            raise ValueError(f"invalid thinking level in thinking_levels: {item!r}")
+        if level in seen:
+            continue
+        seen.add(level)
+        out.append(level)
+    if not out:
+        raise ValueError("thinking_levels must not be empty")
+    return out
+
+
+def default_thinking_levels() -> list[str]:
+    """Built-in allowed thinking levels."""
+    return list(DEFAULT_THINKING_LEVELS)
+
+
+def parse_thinking_config(cfg: dict[str, Any]) -> tuple[bool | None, str | None]:
+    """Return (enable_thinking, reasoning_effort) from profile JSON.
+
+    Priority:
+      1) thinking: false | \"off\" | \"disabled\" => disabled
+      2) thinking / thinking_level / reasoning_effort string => level
+      3) enable_thinking bool
+    """
+    enable: bool | None = None
+    level: str | None = None
+
+    raw_thinking = cfg.get("thinking", None)
+    if raw_thinking is not None:
+        if isinstance(raw_thinking, bool):
+            enable = raw_thinking
+            if raw_thinking:
+                level = normalize_thinking_level(
+                    cfg.get("thinking_level")
+                    or cfg.get("reasoning_effort")
+                    or "high"
+                )
+            else:
+                level = None
+        else:
+            text = str(raw_thinking).strip().casefold()
+            if text in {"off", "false", "0", "disabled", "none", "no"}:
+                enable = False
+                level = None
+            elif text in {"on", "true", "1", "enabled", "yes"}:
+                enable = True
+                level = normalize_thinking_level(
+                    cfg.get("thinking_level") or cfg.get("reasoning_effort") or "high"
+                )
+            else:
+                enable = True
+                level = normalize_thinking_level(raw_thinking)
+
+    if "thinking_level" in cfg and cfg.get("thinking_level") is not None:
+        enable = True if enable is None else enable
+        if enable is not False:
+            level = normalize_thinking_level(cfg.get("thinking_level")) or level
+
+    if "reasoning_effort" in cfg and cfg.get("reasoning_effort") is not None:
+        enable = True if enable is None else enable
+        if enable is not False:
+            level = normalize_thinking_level(cfg.get("reasoning_effort")) or level
+
+    if "enable_thinking" in cfg and cfg.get("enable_thinking") is not None:
+        enable = bool(cfg.get("enable_thinking"))
+        if enable and level is None:
+            level = normalize_thinking_level(
+                cfg.get("thinking_level")
+                or cfg.get("reasoning_effort")
+                or "high"
+            )
+        if not enable:
+            level = None
+
+    return enable, level
+
+
+def _coerce_params(cfg: dict[str, Any]) -> dict[str, Any]:
+    """Collect custom ChatModel / request parameters from profile config."""
+    params: dict[str, Any] = {}
+    for key in ("params", "extra"):
+        raw = cfg.get(key)
+        if isinstance(raw, dict):
+            params.update(raw)
+    # Common top-level ChatModel kwargs
+    for key, value in cfg.items():
+        if key in _PROFILE_META_KEYS:
+            continue
+        params[key] = value
+    return params

synapse/models/helpers.py

@@ -0,0 +1,206 @@
+"""Settings, capability, and presentation helpers for model profiles."""
+from __future__ import annotations
+
+from typing import Any
+
+from synapse.models.config import (
+    THINKING_LEVELS,
+    default_thinking_levels,
+    normalize_thinking_level,
+)
+from synapse.models.profile import ModelProfile
+
+
+def model_provider(model: str | None) -> str:
+    """Return provider prefix (openai/anthropic/...) or empty string."""
+    text = (model or "").strip()
+    if ":" not in text:
+        return ""
+    return text.split(":", 1)[0].strip().casefold()
+
+
+def model_supports_image_input(
+    model: str | None,
+    explicit: bool | None = None,
+    base_url: str | None = None,
+) -> bool:
+    """Resolve native image support with explicit and endpoint-aware defaults.
+
+    Official model names are not enough to prove that a custom OpenAI-compatible
+    gateway accepts image blocks. Non-official OpenAI endpoints therefore default
+    to text-only; set ``image_input: true`` to opt in explicitly.
+    """
+    if explicit is not None:
+        return bool(explicit)
+    raw = (model or "").strip().casefold()
+    provider, _, model_id = raw.partition(":")
+    name = model_id or raw
+    if provider in {"anthropic", "claude"}:
+        return "claude-3" in name or "claude-4" in name or "sonnet-4" in name or "opus-4" in name
+    if provider in {"google", "google_genai", "google_vertexai", "gemini", "vertexai"}:
+        return "gemini" in name
+    if provider in {"openai", "azure_openai", "azure"} or not provider:
+        if base_url and not _is_official_openai_endpoint(base_url):
+            return False
+        return any(
+            marker in name
+            for marker in (
+                "gpt-4o",
+                "gpt-4.1",
+                "gpt-4-turbo",
+                "gpt-5",
+                "gpt5",
+                "o3",
+                "o4",
+            )
+        )
+    return False
+
+
+def _is_official_openai_endpoint(base_url: str) -> bool:
+    normalized = base_url.strip().casefold().rstrip("/")
+    return normalized in {
+        "https://api.openai.com",
+        "https://api.openai.com/v1",
+        "https://chatgpt.com/backend-api/codex",
+    }
+
+
+def settings_fallback_api_key(settings: Any, model: str | None = None) -> str | None:
+    """Pick settings-level API key for a model provider.
+
+    Profile plaintext / api_key_env always wins earlier via resolved_api_key().
+    This only supplies the fallback when the profile has no key.
+    """
+    provider = model_provider(model or getattr(settings, "model", None))
+    openai_key = getattr(settings, "openai_api_key", None)
+    anthropic_key = getattr(settings, "anthropic_api_key", None)
+    if provider == "anthropic":
+        return anthropic_key
+    if provider == "openai":
+        return openai_key
+    return openai_key or anthropic_key
+
+
+def apply_profile_to_settings(
+    settings: Any,
+    profile: ModelProfile,
+    *,
+    seed_thinking: bool = True,
+) -> Any:
+    """Apply a model profile's identity + credentials onto Settings.
+
+    Thinking defaults are seeded only when ``seed_thinking`` is True (model switch).
+    Credentials always follow the selected profile so switching models cannot keep
+    the previous provider's key as the active credential source.
+    """
+    settings.active_model = profile.name
+    settings.model = profile.model
+    if profile.base_url:
+        # Shared transport field used as OpenAI-compatible / Anthropic base_url source.
+        settings.openai_base_url = profile.base_url
+
+    key = profile.resolved_api_key()
+    provider = model_provider(profile.model)
+    if key:
+        if provider == "anthropic":
+            settings.anthropic_api_key = key
+            settings.openai_api_key = None
+        else:
+            # openai + generic OpenAI-compatible providers
+            settings.openai_api_key = key
+            settings.anthropic_api_key = None
+    else:
+        # Clear both so stale keys from a previous profile cannot leak.
+        settings.openai_api_key = None
+        settings.anthropic_api_key = None
+
+    if seed_thinking:
+        if profile.enable_thinking is not None:
+            settings.enable_thinking = bool(profile.enable_thinking)
+        if profile.reasoning_effort:
+            settings.reasoning_effort = profile.reasoning_effort
+        if profile.parallel_tool_calls is not None:
+            settings.parallel_tool_calls = bool(profile.parallel_tool_calls)
+    return settings
+
+def short_model_id(model: str | None) -> str:
+    """Strip provider prefix: ``openai:deepseek-v4-pro`` -> ``deepseek-v4-pro``."""
+    text = (model or "").strip()
+    if ":" in text:
+        text = text.split(":", 1)[1]
+    return text or "model"
+
+
+def settings_thinking_label(settings: Any) -> str:
+    """Current effective thinking label from Settings (runtime override aware)."""
+    if getattr(settings, "enable_thinking", True) is False:
+        return "off"
+    effort = getattr(settings, "reasoning_effort", None)
+    if effort:
+        return str(effort)
+    return "on"
+
+
+def format_model_status(settings: Any) -> str:
+    """Status-bar label: ``deepseek-v4-pro · high``."""
+    model = short_model_id(str(getattr(settings, "model", "") or ""))
+    return f"{model} · {settings_thinking_label(settings)}"
+
+
+def apply_thinking_to_settings(
+    settings: Any,
+    raw: str,
+    *,
+    allowed: list[str] | None = None,
+) -> str:
+    """Apply a thinking level token onto settings. Returns canonical label.
+
+    Accepts off|minimal|low|medium|high|max (and aliases).
+    When ``allowed`` is provided, the level must be in that catalog.
+    """
+    text = (raw or "").strip()
+    if not text:
+        raise ValueError("empty thinking level")
+    level = normalize_thinking_level(text)
+    if not level:
+        raise ValueError(f"unknown thinking level: {raw}")
+    catalog = list(allowed) if allowed is not None else default_thinking_levels()
+    if level not in catalog:
+        raise ValueError(
+            f"thinking level {level!r} not allowed; choose one of: {', '.join(catalog)}"
+        )
+    if level == "off":
+        settings.enable_thinking = False
+        return "off"
+    settings.enable_thinking = True
+    settings.reasoning_effort = level
+    return level
+
+
+def is_thinking_token(raw: str) -> bool:
+    """True if token looks like a thinking level (for /model parsing)."""
+    text = (raw or "").strip().casefold()
+    if text in {
+        "off",
+        "false",
+        "0",
+        "disabled",
+        "none",
+        "no",
+        "on",
+        "true",
+        "1",
+        "enabled",
+        "yes",
+        *THINKING_LEVELS,
+        "min",
+        "med",
+        "mid",
+        "maximum",
+        "xhigh",
+        "ultra",
+        "highest",
+    }:
+        return True
+    return normalize_thinking_level(text) in THINKING_LEVELS

synapse/models/profile.py

@@ -0,0 +1,59 @@
+"""Model endpoint profile domain object."""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Any
+
+from synapse.models.config import expand_env_string
+
+
+@dataclass(frozen=True)
+class ModelProfile:
+    """One named model endpoint.
+
+    Thinking fields here are **defaults only**. Session thinking lives on Settings
+    and is applied at build time via explicit enable_thinking/reasoning_effort.
+    """
+
+    name: str
+    model: str
+    api_key: str | None = None
+    api_key_env: str | None = None
+    base_url: str | None = None
+    # Model input context size (tokens). Used by compact/summarization thresholds.
+    context_window: int | None = None
+    enable_thinking: bool | None = None
+    reasoning_effort: str | None = None
+    # Optional allowed levels for this model (subset of registry.thinking_levels)
+    thinking_levels: tuple[str, ...] | None = None
+    parallel_tool_calls: bool | None = None
+    # Use the ordinary Responses API WebSocket instead of HTTP/SSE.
+    websocket: bool | None = None
+    # Free-form kwargs for init_chat_model (temperature, max_tokens, timeout, ...)
+    extra: dict[str, Any] = field(default_factory=dict)
+    # Request body kwargs merged into model_kwargs
+    model_kwargs: dict[str, Any] = field(default_factory=dict)
+    # Provider-specific body (merged into extra_body)
+    extra_body: dict[str, Any] = field(default_factory=dict)
+    # Whether the selected primary model accepts native image content.
+    # None means infer from provider/model name.
+    image_input: bool | None = None
+
+    def resolved_api_key(self) -> str | None:
+        if self.api_key:
+            return expand_env_string(self.api_key) or None
+        if self.api_key_env:
+            env_name = str(expand_env_string(self.api_key_env) or "")
+            return os.environ.get(env_name) or None
+        return None
+
+    def thinking_label(self) -> str:
+        if self.enable_thinking is False:
+            return "off"
+        if self.reasoning_effort:
+            return str(self.reasoning_effort)
+        if self.enable_thinking is True:
+            return "on"
+        return "default"
+