glaip-sdk 0.7.13__py3-none-any.whl → 0.7.15__py3-none-any.whl

glaip_sdk/client/base.py

@@ -8,6 +8,7 @@ Authors:
 
 import logging
 import os
+import time
 from collections.abc import Iterable, Mapping
 from typing import Any, NoReturn, Union
 
@@ -89,6 +90,11 @@ class BaseClient:
             client_log.info(f"Initializing client with API URL: {self.api_url}")
             self.http_client = self._build_client(timeout)
 
+        # Language model cache (shared by all clients)
+        self._lm_cache: list[dict[str, Any]] | None = None
+        self._lm_cache_time: float = 0.0
+        self._lm_cache_ttl: float = 300.0  # 5 minutes TTL
+
     def _build_client(self, timeout: float) -> httpx.Client:
         """Build HTTP client with configuration."""
         # For streaming operations, we need more generous read timeouts
@@ -481,6 +487,25 @@ class BaseClient:
             request_id=request_id,
         )
 
+    def list_language_models(self, force_refresh: bool = False) -> list[dict[str, Any]]:
+        """List available language models with TTL caching.
+
+        Args:
+            force_refresh: Whether to ignore cache and fetch fresh list.
+
+        Returns:
+            List of available language models.
+        """
+        now = time.monotonic()
+        if not force_refresh and self._lm_cache is not None:
+            if now - self._lm_cache_time < self._lm_cache_ttl:
+                return self._lm_cache
+
+        models = self._request("GET", "/language-models") or []
+        self._lm_cache = models
+        self._lm_cache_time = now
+        return models
+
     def close(self) -> None:
         """Close the HTTP client."""
         if hasattr(self, "http_client") and self.http_client and not self._session_scoped and not self._parent_client:

glaip_sdk/client/main.py

@@ -212,10 +212,6 @@ class Client(BaseClient):
         return self.mcps.get_mcp_tools_from_config(config)
 
     # Language Models
-    def list_language_models(self) -> list[dict]:
-        """List available language models."""
-        data = self._request("GET", "/language-models")
-        return data or []
 
     # ---- Timeout propagation ----
     @property

glaip_sdk/client/payloads/agent/requests.py

@@ -17,8 +17,8 @@ from glaip_sdk.config.constants import (
     DEFAULT_AGENT_PROVIDER,
     DEFAULT_AGENT_TYPE,
     DEFAULT_AGENT_VERSION,
-    DEFAULT_MODEL,
 )
+from glaip_sdk.models.constants import DEFAULT_MODEL
 from glaip_sdk.payload_schemas.agent import AgentImportOperation, get_import_field_plan
 from glaip_sdk.utils.client_utils import extract_ids
 
@@ -100,6 +100,11 @@ def resolve_language_model_fields(
     resolved_model = model_name or model or default_model
     resolved_provider = provider if provider is not None else default_provider
 
+    if resolved_model and isinstance(resolved_model, str) and "/" in resolved_model:
+        parts = resolved_model.split("/", 1)
+        resolved_provider = parts[0]
+        resolved_model = parts[1]
+
     result: dict[str, Any] = {}
     if resolved_model is not None:
         result["model_name"] = resolved_model

glaip_sdk/config/constants.py

@@ -4,8 +4,28 @@ Authors:
     Raymond Christopher (raymond.christopher@gdplabs.id)
 """
 
-# Default language model configuration
-DEFAULT_MODEL = "gpt-5-nano"
+# Lazy import cache for DEFAULT_MODEL to avoid circular dependency
+_DEFAULT_MODEL: str | None = None
+
+
+def __getattr__(name: str) -> str:
+    """Lazy import DEFAULT_MODEL from models.constants to avoid circular dependency.
+
+    Note: Prefer importing DEFAULT_MODEL directly from glaip_sdk.models.constants
+    as it is the canonical source. This re-export exists for backward compatibility.
+    """
+    if name in ("DEFAULT_MODEL", "SDK_DEFAULT_MODEL"):
+        global _DEFAULT_MODEL
+        if _DEFAULT_MODEL is None:
+            from glaip_sdk.models.constants import (  # noqa: PLC0415
+                DEFAULT_MODEL as _MODEL,
+            )
+
+            _DEFAULT_MODEL = _MODEL
+        return _DEFAULT_MODEL
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
 DEFAULT_AGENT_RUN_TIMEOUT = 300
 
 # User agent and version

glaip_sdk/models/__init__.py

@@ -1,3 +1,4 @@
+# pylint: disable=duplicate-code
 """Models package for AIP SDK.
 
 This package provides Pydantic models for API responses.
@@ -17,7 +18,7 @@ Authors:
 
 import warnings
 
-# Pure Pydantic models for API responses (no runtime methods)
+from glaip_sdk.models._validation import _validate_model, convert_model_for_local_execution
 from glaip_sdk.models.agent import AgentResponse
 from glaip_sdk.models.agent_runs import (
     RunOutputChunk,
@@ -26,7 +27,22 @@ from glaip_sdk.models.agent_runs import (
     RunWithOutput,
 )
 from glaip_sdk.models.common import LanguageModelResponse, TTYRenderer
+
+# Pure Pydantic models for API responses (no runtime methods)
+# Import model constants and validation (absolute imports)
+from glaip_sdk.models.constants import (
+    DEFAULT_MODEL,
+    Anthropic,
+    AzureOpenAI,
+    Bedrock,
+    DeepInfra,
+    DeepSeek,
+    Google,
+    ModelProvider,
+    OpenAI,
+)
 from glaip_sdk.models.mcp import MCPResponse
+from glaip_sdk.models.model import Model
 
 # Export schedule models
 from glaip_sdk.models.schedule import (  # noqa: F401
@@ -82,6 +98,19 @@ def __getattr__(name: str) -> type:
 
 
 __all__ = [
+    # Model constants and validation
+    "OpenAI",
+    "Anthropic",
+    "Google",
+    "AzureOpenAI",
+    "DeepInfra",
+    "DeepSeek",
+    "Bedrock",
+    "Model",
+    "ModelProvider",
+    "DEFAULT_MODEL",
+    "_validate_model",
+    "convert_model_for_local_execution",
     # Pure Pydantic response models (recommended for type hints)
     "AgentResponse",
     "ToolResponse",

glaip_sdk/models/_provider_mappings.py

@@ -0,0 +1,101 @@
+"""Provider configuration for model name standardization.
+
+This module centralizes provider configurations, including how provider names
+map to server implementations and their base URLs for local execution.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+__all__ = ["PROVIDERS", "ProviderConfig", "get_driver", "get_base_url"]
+
+
+class ProviderConfig:
+    """Configuration for a model provider.
+
+    Defines how a provider is referenced in SDK constants and how it maps to
+    the underlying driver implementation and API endpoints.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        driver: str,
+        base_url: str | None = None,
+    ):
+        """Initialize provider configuration.
+
+        Args:
+            name: User-facing provider name used in SDK constants (e.g., "deepinfra").
+            driver: Driver implementation name in language_models.yaml (e.g., "openai-compatible").
+            base_url: Base URL for the provider's API (required for local execution).
+        """
+        self.name = name
+        self.driver = driver
+        self.base_url = base_url
+
+
+# Centralized provider configurations
+# Key: provider name (used in SDK constants)
+# Value: ProviderConfig with driver mapping and base URL
+PROVIDERS: dict[str, ProviderConfig] = {
+    "deepinfra": ProviderConfig(
+        name="deepinfra",
+        driver="openai-compatible",
+        base_url="https://api.deepinfra.com/v1/openai",
+    ),
+    "deepseek": ProviderConfig(
+        name="deepseek",
+        driver="openai-compatible",
+        base_url="https://api.deepseek.com",
+    ),
+    "custom": ProviderConfig(
+        name="custom",
+        driver="openai-compatible",
+        base_url=None,  # User-provided via Model.base_url
+    ),
+}
+
+
+def get_driver(provider: str) -> str:
+    """Get driver name for a given provider.
+
+    Maps SDK provider names to their underlying driver implementations.
+    For providers not in the config, returns the provider name unchanged
+    (assumes provider name matches driver name).
+
+    Args:
+        provider: Provider name from SDK constants (e.g., "deepinfra", "openai").
+
+    Returns:
+        Driver name (e.g., "openai-compatible" for deepinfra, "openai" for openai).
+
+    Examples:
+        >>> get_driver("deepinfra")
+        "openai-compatible"
+        >>> get_driver("openai")
+        "openai"
+    """
+    config = PROVIDERS.get(provider)
+    return config.driver if config else provider
+
+
+def get_base_url(provider: str) -> str | None:
+    """Get default base URL for a provider.
+
+    Returns the configured base URL for local execution, if available.
+
+    Args:
+        provider: Provider name from SDK constants (e.g., "deepinfra").
+
+    Returns:
+        Base URL string, or None if no config exists or no base_url configured.
+
+    Examples:
+        >>> get_base_url("deepinfra")
+        "https://api.deepinfra.com/v1/openai"
+        >>> get_base_url("openai")
+        None
+    """
+    config = PROVIDERS.get(provider)
+    return config.base_url if config else None

glaip_sdk/models/_validation.py

@@ -0,0 +1,97 @@
+"""Model validation utility for GL AIP SDK.
+
+Validates model names in 'provider/model' format and provides
+helpful error messages for invalid formats.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import warnings
+from typing import Any
+
+
+def _validate_model(model: str) -> str:
+    """Validate model format and deprecate bare names.
+
+    Args:
+        model: Model string to validate
+
+    Returns:
+        Normalized model string in provider/model format
+
+    Raises:
+        ValueError: If model format is invalid
+    """
+    if "/" not in model:
+        warnings.warn(
+            f"Bare model name '{model}' is deprecated. "
+            f"Use 'provider/model' format (e.g., 'openai/{model}'). "
+            f"This will be an error in v2.0. Use constants: from glaip_sdk.models import OpenAI",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return f"openai/{model}"
+
+    provider, model_name = model.split("/", 1)
+    if not provider or not model_name:
+        raise ValueError(
+            f"Invalid model format: '{model}'. "
+            f"Expected 'provider/model' format (e.g., 'openai/gpt-4o-mini'). "
+            f"Use constants: from glaip_sdk.models import OpenAI; Agent(model=OpenAI.GPT_4O_MINI)."
+        )
+    return model
+
+
+def convert_model_for_local_execution(model: str | Any) -> tuple[str, dict[str, Any]]:
+    """Convert model to aip_agents format for local execution.
+
+    Converts provider/model format appropriately for aip_agents.
+    Handles both Model objects and string models.
+
+    Args:
+        model: Model object or string identifier.
+
+    Returns:
+        Tuple of (model_string, config_dict) where:
+        - model_string: Model in format expected by aip_agents (provider/model)
+        - config_dict: Configuration dict with credentials, hyperparameters, etc.
+    """
+    from glaip_sdk.models import Model  # noqa: PLC0415
+
+    # Handle Model objects
+    if isinstance(model, Model):
+        return model.to_aip_agents_format()
+
+    # Handle string models
+    if isinstance(model, str):
+        if "/" not in model:
+            return model, {}
+
+        parts = model.split("/", 1)
+        provider = parts[0]
+        model_name = parts[1]
+
+        # Map provider to driver and get base_url from config
+        from glaip_sdk.models._provider_mappings import (  # noqa: PLC0415
+            get_base_url,
+            get_driver,
+        )
+
+        driver = get_driver(provider)
+        base_url = get_base_url(provider)
+
+        config: dict[str, Any] = {}
+        if base_url:
+            config["lm_base_url"] = base_url
+
+        # Return with driver name
+        return f"{driver}/{model_name}", config
+
+    # For other types (None, etc.), return as-is
+    return model, {}
+
+
+__all__ = ["_validate_model", "convert_model_for_local_execution"]

glaip_sdk/models/agent.py

@@ -13,9 +13,10 @@ Authors:
 from datetime import datetime
 from typing import Any
 
-from glaip_sdk.config.constants import DEFAULT_AGENT_RUN_TIMEOUT
 from pydantic import BaseModel
 
+from glaip_sdk.config.constants import DEFAULT_AGENT_RUN_TIMEOUT
+
 
 class AgentResponse(BaseModel):
     """Pydantic model for Agent API responses.

glaip_sdk/models/constants.py

@@ -0,0 +1,141 @@
+# pylint: disable=duplicate-code
+"""Model constants for GL AIP SDK.
+
+Typed constants for popular AI models matching AIP Server's language_models.yaml keys.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "ModelProvider",
+    "OpenAI",
+    "Anthropic",
+    "Google",
+    "AzureOpenAI",
+    "DeepInfra",
+    "DeepSeek",
+    "Bedrock",
+    "DEFAULT_MODEL",
+]
+
+# Note: DeepInfra provider changed to 'openai-compatible' for aip_agents compatibility
+
+
+class ModelProvider:
+    """Supported model providers."""
+
+    OPENAI = "openai"
+    ANTHROPIC = "anthropic"
+    AZURE_OPENAI = "azure-openai"
+    GOOGLE = "google"
+    DEEPINFRA = "deepinfra"
+    DEEPSEEK = "deepseek"
+    OPENAI_COMPATIBLE = "openai-compatible"
+    BEDROCK = "bedrock"
+
+
+class OpenAI:
+    """OpenAI model constants."""
+
+    GPT_4O_MINI = "openai/gpt-4o-mini"
+    GPT_4O = "openai/gpt-4o"
+    GPT_4_1 = "openai/gpt-4.1"
+    GPT_4_1_NANO = "openai/gpt-4.1-nano"
+    GPT_4_1_MINI = "openai/gpt-4.1-mini"
+    GPT_5 = "openai/gpt-5"
+    GPT_5_MINI = "openai/gpt-5-mini"
+    GPT_5_NANO = "openai/gpt-5-nano"
+    GPT_5_LOW = "openai/gpt-5-low"
+    GPT_5_MINIMAL = "openai/gpt-5-minimal"
+    GPT_5_MEDIUM = "openai/gpt-5-medium"
+    GPT_5_HIGH = "openai/gpt-5-high"
+    GPT_5_1 = "openai/gpt-5.1"
+    GPT_5_1_LOW = "openai/gpt-5.1-low"
+    GPT_5_1_MEDIUM = "openai/gpt-5.1-medium"
+    GPT_5_1_HIGH = "openai/gpt-5.1-high"
+    GPT_5_2 = "openai/gpt-5.2"
+    GPT_5_2_LOW = "openai/gpt-5.2-low"
+    GPT_5_2_MEDIUM = "openai/gpt-5.2-medium"
+    GPT_5_2_HIGH = "openai/gpt-5.2-high"
+    GPT_5_2_XHIGH = "openai/gpt-5.2-xhigh"
+    GPT_4O_2024_11_20 = "openai/gpt-4o-2024-11-20"
+    O4_MINI = "openai/o4-mini"
+
+
+class Anthropic:
+    """Anthropic model constants."""
+
+    CLAUDE_3_5_SONNET_LATEST = "anthropic/claude-3-5-sonnet-latest"
+    CLAUDE_3_7_SONNET_LATEST = "anthropic/claude-3-7-sonnet-latest"
+    CLAUDE_SONNET_4_0 = "anthropic/claude-sonnet-4-0"
+    CLAUDE_OPUS_4_0 = "anthropic/claude-opus-4-0"
+    CLAUDE_OPUS_4_1 = "anthropic/claude-opus-4-1"
+    CLAUDE_SONNET_4_5 = "anthropic/claude-sonnet-4-5"
+    # DX Alias
+    CLAUDE_3_5_SONNET = CLAUDE_3_5_SONNET_LATEST
+
+
+class Google:
+    """Google model constants."""
+
+    GEMINI_2_5_FLASH = "google/gemini-2.5-flash"
+    GEMINI_3_FLASH_PREVIEW = "google/gemini-3-flash-preview"
+    GEMINI_3_PRO_PREVIEW = "google/gemini-3-pro-preview"
+    GEMINI_2_5_PRO = "google/gemini-2.5-pro"
+
+
+class AzureOpenAI:
+    """Azure OpenAI model constants."""
+
+    GPT_4O = "azure-openai/gpt-4o"
+    GPT_4O_MINI = "azure-openai/gpt-4o-mini"
+    GPT_4_1 = "azure-openai/gpt-4.1"
+
+
+class DeepInfra:
+    """DeepInfra model constants.
+
+    Note: DeepInfra models use the openai-compatible driver internally,
+    but we expose them with the 'deepinfra/' prefix for better DX.
+    The SDK handles the mapping to 'openai-compatible/' automatically.
+    """
+
+    QWEN3_235B_A22B_INSTRUCT_2507 = "deepinfra/Qwen/Qwen3-235B-A22B-Instruct-2507"
+    KIMI_K2_INSTRUCT = "deepinfra/moonshotai/Kimi-K2-Instruct"
+    QWEN3_30B_A3B = "deepinfra/Qwen/Qwen3-30B-A3B"
+    GLM_4_5_AIR = "deepinfra/zai-org/GLM-4.5-Air"
+    QWEN3_32B = "deepinfra/Qwen/Qwen3-32B"
+    QWEN3_NEXT_80B_A3B_THINKING = "deepinfra/Qwen/Qwen3-Next-80B-A3B-Thinking"
+    QWEN3_NEXT_80B_A3B_INSTRUCT = "deepinfra/Qwen/Qwen3-Next-80B-A3B-Instruct"
+    QWEN3_14B = "deepinfra/Qwen/Qwen3-14B"
+    GLM_4_5 = "deepinfra/zai-org/GLM-4.5"
+
+
+class DeepSeek:
+    """DeepSeek model constants.
+
+    Note: DeepSeek models use the openai-compatible driver internally,
+    but we expose them with the 'deepseek/' prefix for better DX.
+    The SDK handles the mapping to 'openai-compatible/' automatically.
+    """
+
+    DEEPSEEK_CHAT = "deepseek/deepseek-chat"
+    DEEPSEEK_V3_1 = "deepseek/deepseek-ai/DeepSeek-V3.1"
+    DEEPSEEK_V3_1_TERMINUS = "deepseek/deepseek-ai/DeepSeek-V3.1-Terminus"
+
+
+class Bedrock:
+    """AWS Bedrock model constants."""
+
+    CLAUDE_SONNET_4_20250514_V1_0 = "bedrock/us.anthropic.claude-sonnet-4-20250514-v1:0"
+    CLAUDE_3_5_HAIKU_20241022_V1_0 = "bedrock/us.anthropic.claude-3-5-haiku-20241022-v1:0"
+    CLAUDE_SONNET_4_5_20250929_V1_0 = "bedrock/us.anthropic.claude-sonnet-4-5-20250929-v1:0"
+
+    # DX Aliases
+    ANTHROPIC_CLAUDE_SONNET_4 = CLAUDE_SONNET_4_20250514_V1_0
+    ANTHROPIC_CLAUDE_3_5_HAIKU = CLAUDE_3_5_HAIKU_20241022_V1_0
+    ANTHROPIC_CLAUDE_SONNET_4_5 = CLAUDE_SONNET_4_5_20250929_V1_0
+
+
+# Default model selection
+DEFAULT_MODEL = OpenAI.GPT_5_NANO

glaip_sdk/models/model.py

@@ -0,0 +1,170 @@
+"""Model configuration class for GL AIP SDK.
+
+Provides a structured way to specify models, credentials, and hyperparameters
+for local execution.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, field_validator
+
+
+class Model(BaseModel):
+    """Model configuration class for local execution.
+
+    Bundles model identity with credentials and hyperparameters.
+    """
+
+    id: str
+    credentials: dict[str, Any] | str | None = None
+    hyperparameters: dict[str, Any] | None = None
+    base_url: str | None = None
+
+    @field_validator("id")
+    @classmethod
+    def validate_id(cls, v: str) -> str:
+        """Validate model ID format.
+
+        Args:
+            v: Model identifier string.
+
+        Returns:
+            Validated model identifier in 'provider/model' format.
+
+        Raises:
+            ValueError: If model format is invalid.
+        """
+        from glaip_sdk.models._validation import _validate_model  # noqa: PLC0415
+
+        return _validate_model(v)
+
+    def to_aip_agents_format(self) -> tuple[str, dict[str, Any]]:
+        """Convert Model to aip_agents format.
+
+        Converts provider/model format to driver/model format for aip_agents.
+        For custom models with base_url, uses format: openai-compatible/base_url:model_name
+
+        Returns:
+            Tuple of (model_string, agent_config_dict).
+        """
+        if "/" not in self.id:
+            return self.id, {}
+
+        parts = self.id.split("/", 1)
+        provider = parts[0]
+        model_name = parts[1]
+
+        config = self._build_agent_config(provider)
+        model_string = self._build_model_string(provider, model_name, config)
+
+        return model_string, config
+
+    def _build_agent_config(self, provider: str) -> dict[str, Any]:
+        """Build agent config dict from Model attributes.
+
+        Args:
+            provider: Provider name extracted from model id.
+
+        Returns:
+            Configuration dict with credentials, hyperparameters, and base_url.
+        """
+        config: dict[str, Any] = {}
+
+        if self.credentials:
+            if isinstance(self.credentials, str):
+                config["lm_api_key"] = self.credentials
+            elif isinstance(self.credentials, dict):
+                config["lm_credentials"] = self.credentials
+
+        if self.hyperparameters:
+            config["lm_hyperparameters"] = self.hyperparameters
+
+        base_url = self._resolve_base_url(provider)
+        if base_url:
+            config["lm_base_url"] = base_url
+
+        return config
+
+    def _resolve_base_url(self, provider: str) -> str | None:
+        """Resolve base URL for the provider.
+
+        Uses centralized provider configurations to determine base_url.
+        Users can override by explicitly setting base_url attribute.
+
+        Args:
+            provider: Provider name from model ID (e.g., "deepinfra").
+
+        Returns:
+            Base URL string or None.
+
+        Examples:
+            >>> model = Model(id="deepinfra/Qwen/Qwen3-30B")
+            >>> model._resolve_base_url("deepinfra")
+            "https://api.deepinfra.com/v1/openai"
+        """
+        if self.base_url:
+            return self.base_url
+
+        # Get base_url from provider config
+        from glaip_sdk.models._provider_mappings import get_base_url  # noqa: PLC0415
+
+        base_url = get_base_url(provider)
+        if base_url:
+            return base_url
+
+        return None
+
+    def _build_model_string(self, provider: str, model_name: str, config: dict[str, Any]) -> str:
+        """Build normalized model string for aip_agents.
+
+        Converts provider names to their driver implementations for local execution.
+
+        Conversion strategy:
+        1. Custom models with base_url: Use colon format (openai-compatible/{base_url}:{model_name})
+           This allows aip_agents to parse base_url and model_name separately.
+        2. Standard providers: Map to driver and use slash format (driver/{model_name})
+           aip_agents will handle provider/model format internally.
+
+        Args:
+            provider: Provider name from model ID (e.g., "deepinfra", "openai").
+            model_name: Model name after provider prefix.
+            config: Agent config dict (may contain base_url).
+
+        Returns:
+            Normalized model string in provider/model format with driver name.
+
+        Examples:
+            >>> _build_model_string("deepinfra", "Qwen/Qwen3-30B", {})
+            "openai-compatible/Qwen/Qwen3-30B"
+            >>> _build_model_string("openai", "gpt-4o", {})
+            "openai/gpt-4o"
+        """
+        from glaip_sdk.models._provider_mappings import get_driver  # noqa: PLC0415
+
+        # Map provider to driver (e.g., deepinfra → openai-compatible)
+        driver = get_driver(provider)
+
+        if provider == "custom":
+            base_url = config.get("lm_base_url")
+            if base_url:
+                return f"{driver}/{base_url}:{model_name}"
+
+        # Standard case: driver with slash format
+        # aip_agents will handle provider/model format internally
+        return f"{driver}/{model_name}"
+
+    def __repr__(self) -> str:
+        """Return string representation of Model.
+
+        Note: Credentials are masked to avoid leaking secrets in logs.
+        Hyperparameters and base_url are shown if present.
+        """
+        creds_repr = "***" if self.credentials else "None"
+        return (
+            f"Model(id={self.id!r}, "
+            f"credentials={creds_repr}, "
+            f"hyperparameters={self.hyperparameters!r}, "
+            f"base_url={self.base_url!r})"
+        )