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

glaip_sdk/agents/base.py

@@ -54,10 +54,13 @@ from glaip_sdk.utils.resource_refs import is_uuid
 
 if TYPE_CHECKING:
     from glaip_sdk.client.schedules import AgentScheduleManager
+    from glaip_sdk.models import AgentResponse, Model
     from glaip_sdk.guardrails import GuardrailManager
-    from glaip_sdk.models import AgentResponse
     from glaip_sdk.registry import AgentRegistry, MCPRegistry, ToolRegistry
 
+# Import model validation utility
+from glaip_sdk.models._validation import _validate_model
+
 logger = logging.getLogger(__name__)
 
 _AGENT_NOT_DEPLOYED_MSG = "Agent must be deployed before running. Call deploy() first."
@@ -99,11 +102,11 @@ class Agent:
         - instruction: Agent instruction text (required)
         - description: Agent description (default: "")
         - tools: List of tools (default: [])
+        - model: Optional model override (default: None)
         - agents: List of sub-agents (default: [])
         - mcps: List of MCPs (default: [])
         - timeout: Timeout in seconds (default: 300)
         - metadata: Optional metadata dict (default: None)
-        - model: Optional model override (default: None)
         - framework: Agent framework (default: "langchain")
         - version: Agent version (default: "1.0.0")
         - agent_type: Agent type (default: "config")
@@ -130,7 +133,7 @@ class Agent:
         tools: list | None = None,
         agents: list | None = None,
         mcps: list | None = None,
-        model: str | None = _UNSET,  # type: ignore[assignment]
+        model: str | Model | None = _UNSET,  # type: ignore[assignment]
         guardrail: GuardrailManager | None = None,
         _client: Any = None,
         **kwargs: Any,
@@ -148,7 +151,7 @@ class Agent:
             tools: List of tools (Tool classes, SDK Tool objects, or strings).
             agents: List of sub-agents (Agent classes, instances, or strings).
             mcps: List of MCPs.
-            model: Model identifier.
+            model: Model identifier or Model configuration object.
             guardrail: The guardrail manager for content safety.
             _client: Internal client reference (set automatically).
 
@@ -176,7 +179,7 @@ class Agent:
         self._tools = tools
         self._agents = agents
         self._mcps = mcps
-        self._model = model
+        self._model = self._validate_and_set_model(model)
         self._guardrail = guardrail
         self._language_model_id: str | None = None
         # Extract parameters from kwargs with _UNSET defaults
@@ -210,6 +213,30 @@ class Agent:
                 stacklevel=2,
             )
 
+    def _validate_and_set_model(self, model: str | Any) -> str | Any:
+        """Validate and normalize model parameter.
+
+        Supports both string model identifiers and Model objects:
+        - String: Simple model identifier (e.g., "openai/gpt-4o" or OpenAI.GPT_4O)
+        - Model: Model object with credentials/hyperparameters for local execution
+
+        Args:
+            model: Model identifier (string) or Model object.
+
+        Returns:
+            Validated model (string or Model object).
+        """
+        if model is None or model is Agent._UNSET:
+            return model
+
+        from glaip_sdk.models import Model  # noqa: PLC0415
+
+        if isinstance(model, str):
+            return _validate_model(model)
+        elif isinstance(model, Model):
+            return model
+        return model
+
     # ─────────────────────────────────────────────────────────────────
     # Properties (override in subclasses OR pass to __init__)
     # ─────────────────────────────────────────────────────────────────
@@ -354,11 +381,11 @@ class Agent:
         return None
 
     @property
-    def model(self) -> str | None:
+    def model(self) -> str | Model | None:
         """Optional model override.
 
         Returns:
-            Model identifier string or None to use default.
+            Model identifier string, Model object, or None to use default.
         """
         if self._model is not self._UNSET:
             return self._model
@@ -561,9 +588,14 @@ class Agent:
             "framework": self.framework,
             "version": self.version,
             "agent_type": self.agent_type,
-            "model": self.model,
         }
 
+        if self.model:
+            if isinstance(self.model, str):
+                config["model"] = self.model
+            else:
+                config["model"] = self.model.id
+
         # Handle metadata (default to empty dict if None)
         config["metadata"] = self.metadata or {}
 

glaip_sdk/cli/commands/agents/__init__.py

@@ -11,37 +11,30 @@ Authors:
 # Import from submodules
 from glaip_sdk.cli.commands.agents._common import (  # noqa: E402
     AGENT_NOT_FOUND_ERROR,
-    _get_agent_for_update,
-    _resolve_agent,
-    agents_group,
     _coerce_mapping_candidate,
     _display_agent_details,
     _emit_verbose_guidance,
     _fetch_full_agent_details,
+    _get_agent_for_update,
     _get_agent_model_name,
     _get_language_model_display_name,
     _model_from_config,
     _prepare_agent_output,
+    _resolve_agent,
     _resolve_resources_by_name,
+    agents_group,
     console,
 )
 from glaip_sdk.cli.commands.agents.create import create  # noqa: E402
 from glaip_sdk.cli.commands.agents.delete import delete  # noqa: E402
 from glaip_sdk.cli.commands.agents.get import get  # noqa: E402
 from glaip_sdk.cli.commands.agents.list import list_agents  # noqa: E402
-from glaip_sdk.cli.commands.agents.run import run, _maybe_attach_transcript_toggle  # noqa: E402
+from glaip_sdk.cli.commands.agents.run import _maybe_attach_transcript_toggle, run  # noqa: E402
 from glaip_sdk.cli.commands.agents.sync_langflow import sync_langflow  # noqa: E402
 from glaip_sdk.cli.commands.agents.update import update  # noqa: E402
 
 # Import core functions for test compatibility
 from glaip_sdk.cli.core.context import get_client  # noqa: E402
-from glaip_sdk.cli.core.rendering import with_client_and_spinner  # noqa: E402
-
-# Import display functions for test compatibility
-from glaip_sdk.cli.display import (  # noqa: E402
-    handle_json_output,
-    handle_rich_output,
-)
 
 # Import core output functions for test compatibility
 from glaip_sdk.cli.core.output import (  # noqa: E402
@@ -52,11 +45,20 @@ from glaip_sdk.cli.core.output import (  # noqa: E402
 # Import rendering functions for test compatibility
 from glaip_sdk.cli.core.rendering import (  # noqa: E402
     build_renderer,
+    with_client_and_spinner,  # noqa: E402
 )
 
 # Import display functions for test compatibility
-from glaip_sdk.cli.display import (  # noqa: E402
+# Import display functions for test compatibility
+from glaip_sdk.cli.display import (  # noqa: E402  # noqa: E402
     display_agent_run_suggestions,
+    handle_json_output,
+    handle_rich_output,
+)
+
+# Import IO functions for test compatibility
+from glaip_sdk.cli.io import (  # noqa: E402
+    fetch_raw_resource_details,
 )
 
 # Import rich helpers for test compatibility
@@ -70,11 +72,6 @@ from glaip_sdk.cli.transcript import (  # noqa: E402
     store_transcript_for_session,
 )
 
-# Import IO functions for test compatibility
-from glaip_sdk.cli.io import (  # noqa: E402
-    fetch_raw_resource_details,
-)
-
 # Import utils for test compatibility
 from glaip_sdk.utils import (  # noqa: E402
     is_uuid,

glaip_sdk/cli/commands/agents/_common.py

@@ -19,8 +19,11 @@ from glaip_sdk.branding import (
     WARNING_STYLE,
 )
 from glaip_sdk.cli.constants import DEFAULT_AGENT_INSTRUCTION_PREVIEW_LIMIT
-from glaip_sdk.config.constants import AGENT_CONFIG_FIELDS, DEFAULT_MODEL
 from glaip_sdk.cli.context import get_ctx_value
+from glaip_sdk.cli.core.output import (
+    output_result,
+)
+from glaip_sdk.cli.core.rendering import spinner_context
 from glaip_sdk.cli.display import (
     build_resource_result_data,
     handle_json_output,
@@ -31,10 +34,8 @@ from glaip_sdk.cli.hints import in_slash_mode
 from glaip_sdk.cli.io import fetch_raw_resource_details
 from glaip_sdk.cli.resolution import resolve_resource_reference
 from glaip_sdk.cli.rich_helpers import markup_text
-from glaip_sdk.cli.core.output import (
-    output_result,
-)
-from glaip_sdk.cli.core.rendering import spinner_context
+from glaip_sdk.config.constants import AGENT_CONFIG_FIELDS
+from glaip_sdk.models.constants import DEFAULT_MODEL
 from glaip_sdk.icons import ICON_AGENT
 from glaip_sdk.utils import format_datetime, is_uuid
 

glaip_sdk/cli/commands/agents/create.py

@@ -11,19 +11,19 @@ from typing import Any
 import click
 
 from glaip_sdk.cli.context import output_flags
+from glaip_sdk.cli.core.context import get_client
 from glaip_sdk.cli.display import (
     display_agent_run_suggestions,
     display_creation_success,
     handle_json_output,
     handle_rich_output,
 )
-from glaip_sdk.cli.core.context import get_client
-from glaip_sdk.config.constants import DEFAULT_AGENT_RUN_TIMEOUT, DEFAULT_MODEL
 from glaip_sdk.cli.validators import (
     validate_agent_instruction_cli as validate_agent_instruction,
-    validate_agent_name_cli as validate_agent_name,
-    validate_timeout_cli as validate_timeout,
 )
+from glaip_sdk.cli.validators import validate_agent_name_cli as validate_agent_name
+from glaip_sdk.cli.validators import validate_timeout_cli as validate_timeout
+from glaip_sdk.config.constants import DEFAULT_AGENT_RUN_TIMEOUT
 from glaip_sdk.utils.validation import coerce_timeout
 
 from ._common import (
@@ -67,7 +67,11 @@ def _handle_creation_exception(ctx: Any, e: Exception) -> None:
 @click.option("--instruction", help="Agent instruction (prompt)")
 @click.option(
     "--model",
-    help=f"Language model to use (e.g., {DEFAULT_MODEL}, default: {DEFAULT_MODEL})",
+    help=(
+        "Language model in 'provider/model' format "
+        "(e.g., openai/gpt-4o-mini, bedrock/us.anthropic.claude-sonnet-4-20250514-v1:0). "
+        "Use 'aip models list' to see available models."
+    ),
 )
 @click.option("--tools", multiple=True, help="Tool names or IDs to attach")
 @click.option("--agents", multiple=True, help="Sub-agent names or IDs to attach")

glaip_sdk/client/agents.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python3
+# pylint: disable=duplicate-code
 """Agent client for AIP SDK.
 
 Authors:
@@ -9,6 +9,7 @@ Authors:
 import asyncio
 import json
 import logging
+import warnings
 from collections.abc import AsyncGenerator, Callable, Iterator, Mapping
 from contextlib import asynccontextmanager
 from os import PathLike
@@ -21,15 +22,15 @@ if TYPE_CHECKING:
 
 import httpx
 from glaip_sdk.agents import Agent
+from glaip_sdk.client.agent_runs import AgentRunsClient
+from glaip_sdk.client.base import BaseClient
+from glaip_sdk.client.mcps import MCPClient
 from glaip_sdk.client.payloads.agent import (
     AgentCreateRequest,
     AgentListParams,
     AgentListResult,
     AgentUpdateRequest,
 )
-from glaip_sdk.client.agent_runs import AgentRunsClient
-from glaip_sdk.client.base import BaseClient
-from glaip_sdk.client.mcps import MCPClient
 from glaip_sdk.client.run_rendering import (
     AgentRunRenderingManager,
     compute_timeout_seconds,
@@ -42,10 +43,10 @@ from glaip_sdk.config.constants import (
     DEFAULT_AGENT_RUN_TIMEOUT,
     DEFAULT_AGENT_TYPE,
     DEFAULT_AGENT_VERSION,
-    DEFAULT_MODEL,
 )
 from glaip_sdk.exceptions import NotFoundError, ValidationError
 from glaip_sdk.models import AgentResponse
+from glaip_sdk.models.constants import DEFAULT_MODEL
 from glaip_sdk.payload_schemas.agent import list_server_only_fields
 from glaip_sdk.utils.agent_config import normalize_agent_config_for_import
 from glaip_sdk.utils.client_utils import (
@@ -255,13 +256,16 @@ class AgentClient(BaseClient):
         self,
         *,
         parent_client: BaseClient | None = None,
+        lm_cache_ttl: float = 3600.0,
         **kwargs: Any,
     ) -> None:
         """Initialize the agent client.
 
         Args:
-            parent_client: Parent client to adopt session/config from
-            **kwargs: Additional arguments for standalone initialization
+            parent_client: Parent client to adopt session/config from.
+            lm_cache_ttl: TTL for the language model list cache in seconds.
+                Defaults to 3600 (1 hour).
+            **kwargs: Additional arguments for standalone initialization.
         """
         super().__init__(parent_client=parent_client, **kwargs)
         self._renderer_manager = AgentRunRenderingManager(logger)
@@ -270,6 +274,117 @@ class AgentClient(BaseClient):
         self._runs_client: AgentRunsClient | None = None
         self._schedule_client: ScheduleClient | None = None
 
+        self._lm_cache: list[dict[str, Any]] | None = None
+        self._lm_cache_time: float = 0.0
+        self._lm_cache_ttl: float = lm_cache_ttl
+
+    def clear_language_model_cache(self) -> None:
+        """Invalidate the language model list cache.
+
+        Forces the next call to list_language_models() to fetch a fresh list
+        from the server.
+        """
+        self._lm_cache = None
+        self._lm_cache_time = 0.0
+        logger.debug("Language model cache invalidated.")
+
+    def _resolve_language_model_id(self, model_str: str | None) -> str | None:
+        """Resolve a friendly model name to a server language model ID.
+
+        Handles provider name mapping (e.g., 'deepinfra/model' → 'openai-compatible/model')
+        by checking both the original provider name and its driver equivalent.
+
+        Args:
+            model_str: The model string to resolve (e.g., 'openai/gpt-4o', 'deepinfra/Qwen3-30B').
+
+        Returns:
+            The resolved server model ID (UUID), or None if not found.
+
+        Examples:
+            >>> _resolve_language_model_id("openai/gpt-4o")
+            "uuid-1234-..."
+            >>> _resolve_language_model_id("deepinfra/Qwen3-30B")  # Maps to openai-compatible
+            "uuid-5678-..."
+        """
+        if not model_str:
+            return None
+
+        # If resolution is explicitly disabled (e.g. in unit tests to avoid extra API calls), skip it
+        if getattr(self, "_skip_model_resolution", False):
+            return None
+
+        try:
+            models = self.list_language_models()
+
+            # Try exact match first
+            model_id = self._find_exact_model_match(model_str, models)
+            if model_id:
+                return model_id
+
+            # Try with provider-to-driver mapping
+            return self._try_resolve_with_driver_mapping(model_str, models)
+        except Exception:
+            pass
+
+        return None
+
+    def _find_exact_model_match(self, model_str: str, models: list[dict[str, Any]]) -> str | None:
+        """Find exact model match in models list.
+
+        Args:
+            model_str: Model string to match.
+            models: List of language model dictionaries from server.
+
+        Returns:
+            Model ID (UUID) if found, None otherwise.
+        """
+        for model_info in models:
+            provider = model_info.get("provider")
+            name = model_info.get("name")
+            if provider and name:
+                full_name = f"{provider}/{name}"
+                if full_name == model_str:
+                    return model_info.get("id")
+            if name == model_str:
+                return model_info.get("id")
+        return None
+
+    def _try_resolve_with_driver_mapping(self, model_str: str, models: list[dict[str, Any]]) -> str | None:
+        """Try to resolve model using provider-to-driver mapping.
+
+        Maps provider names to their driver implementations (e.g., deepinfra → openai-compatible)
+        and searches the models list with the driver name.
+
+        Args:
+            model_str: Model string in provider/model format (e.g., "deepinfra/Qwen3-30B").
+            models: List of language model dictionaries from server.
+
+        Returns:
+            Model ID (UUID) if found, None otherwise.
+        """
+        if "/" not in model_str:
+            return None
+
+        from glaip_sdk.models._provider_mappings import get_driver  # noqa: PLC0415
+
+        provider, model_name = model_str.split("/", 1)
+        driver = get_driver(provider)
+
+        # Only try with driver if it's different from provider
+        if driver == provider:
+            return None
+
+        driver_model_str = f"{driver}/{model_name}"
+        for model_info in models:
+            provider_field = model_info.get("provider")
+            name_field = model_info.get("name")
+            if provider_field and name_field:
+                full_name = f"{provider_field}/{name_field}"
+                if full_name == driver_model_str:
+                    return model_info.get("id")
+
+        return None
+
     def list_agents(
         self,
         query: AgentListParams | None = None,
@@ -461,11 +576,18 @@ class AgentClient(BaseClient):
         Returns:
             Final text string.
         """
-        from glaip_sdk.client.run_rendering import finalize_render_manager  # noqa: PLC0415
+        from glaip_sdk.client.run_rendering import (  # noqa: PLC0415
+            finalize_render_manager,
+        )
 
         manager = self._get_renderer_manager()
         return finalize_render_manager(
-            manager, renderer, final_text, stats_usage, started_monotonic, finished_monotonic
+            manager,
+            renderer,
+            final_text,
+            stats_usage,
+            started_monotonic,
+            finished_monotonic,
         )
 
     def _get_tool_client(self) -> ToolClient:
@@ -769,10 +891,18 @@ class AgentClient(BaseClient):
             plural_label="MCPs",
         )
 
-    def _create_agent_from_payload(self, payload: Mapping[str, Any]) -> "Agent":
-        """Create an agent using a fully prepared payload mapping."""
-        known, extras = _split_known_and_extra(payload, AgentCreateRequest.__dataclass_fields__)
+    def _validate_agent_basics(self, known: dict[str, Any]) -> tuple[str, str]:
+        """Validate and extract basic agent fields.
+
+        Args:
+            known: Known fields dictionary.
+
+        Returns:
+            Tuple of (name, validated_instruction).
 
+        Raises:
+            ValueError: If name or instruction is empty/whitespace.
+        """
         name = known.pop("name", None)
         instruction = known.pop("instruction", None)
         if not name or not str(name).strip():
@@ -781,9 +911,20 @@ class AgentClient(BaseClient):
             raise ValueError("Agent instruction cannot be empty or whitespace")
 
         validated_instruction = validate_agent_instruction(str(instruction))
-        _normalise_sequence_fields(known)
+        return str(name).strip(), validated_instruction
 
-        resolved_model = known.pop("model", None) or DEFAULT_MODEL
+    def _resolve_all_resources(
+        self, known: dict[str, Any], extras: dict[str, Any]
+    ) -> tuple[list[str] | None, list[str] | None, list[str] | None]:
+        """Resolve all resource IDs (tools, agents, mcps).
+
+        Args:
+            known: Known fields dictionary.
+            extras: Extra fields dictionary.
+
+        Returns:
+            Tuple of (resolved_tools, resolved_agents, resolved_mcps).
+        """
         tool_refs = extras.pop("_tool_refs", None)
         agent_refs = extras.pop("_agent_refs", None)
         mcp_refs = extras.pop("_mcp_refs", None)
@@ -796,10 +937,56 @@ class AgentClient(BaseClient):
         resolved_agents = self._resolve_agent_ids(agents_raw, agent_refs)
         resolved_mcps = self._resolve_mcp_ids(mcps_raw, mcp_refs)
 
+        return resolved_tools, resolved_agents, resolved_mcps
+
+    def _process_model_fields(
+        self, resolved_model: Any, known: dict[str, Any]
+    ) -> tuple[str, str | None, str | None, str | None]:
+        """Process model fields and extract language model ID.
+
+        Args:
+            resolved_model: Resolved model (string or Model object).
+            known: Known fields dictionary.
+
+        Returns:
+            Tuple of (resolved_model_str, language_model_id, provider, model_name).
+        """
+        from glaip_sdk.models import Model  # noqa: PLC0415
+
+        if isinstance(resolved_model, Model):
+            if resolved_model.credentials or resolved_model.hyperparameters or resolved_model.base_url:
+                warnings.warn(
+                    "Model object contains local configuration (credentials, hyperparameters, or base_url) "
+                    "which is ignored for remote deployment. These fields are only used for local execution.",
+                    UserWarning,
+                    stacklevel=2,
+                )
+            resolved_model = resolved_model.id
+
+        # Validate and normalize string models (handles bare name deprecation)
+        if isinstance(resolved_model, str):
+            from glaip_sdk.models._validation import _validate_model  # noqa: PLC0415
+
+            resolved_model = _validate_model(resolved_model)
+
         language_model_id = known.pop("language_model_id", None)
+        if not language_model_id and isinstance(resolved_model, str):
+            language_model_id = self._resolve_language_model_id(resolved_model)
+
         provider = known.pop("provider", None)
         model_name = known.pop("model_name", None)
 
+        return resolved_model, language_model_id, provider, model_name
+
+    def _extract_agent_metadata(self, known: dict[str, Any]) -> tuple[str, str, str]:
+        """Extract agent type, framework, and version.
+
+        Args:
+            known: Known fields dictionary.
+
+        Returns:
+            Tuple of (agent_type, framework, version).
+        """
         agent_type_value = known.pop("agent_type", None)
         fallback_type_value = known.pop("type", None)
         if agent_type_value is None:
@@ -807,6 +994,26 @@ class AgentClient(BaseClient):
 
         framework_value = known.pop("framework", None) or DEFAULT_AGENT_FRAMEWORK
         version_value = known.pop("version", None) or DEFAULT_AGENT_VERSION
+
+        return agent_type_value, framework_value, version_value
+
+    def _create_agent_from_payload(self, payload: Mapping[str, Any]) -> "Agent":
+        """Create an agent using a fully prepared payload mapping."""
+        known, extras = _split_known_and_extra(payload, AgentCreateRequest.__dataclass_fields__)
+
+        # Validate and extract basic fields
+        name, validated_instruction = self._validate_agent_basics(known)
+        _normalise_sequence_fields(known)
+
+        # Resolve model and resources
+        resolved_model = known.pop("model", None) or DEFAULT_MODEL
+        resolved_tools, resolved_agents, resolved_mcps = self._resolve_all_resources(known, extras)
+
+        # Process model and language model ID
+        resolved_model, language_model_id, provider, model_name = self._process_model_fields(resolved_model, known)
+
+        # Extract agent type, framework, version
+        agent_type_value, framework_value, version_value = self._extract_agent_metadata(known)
         account_id = known.pop("account_id", None)
         description = known.pop("description", None)
         metadata = _prepare_agent_metadata(known.pop("metadata", None))
@@ -819,7 +1026,7 @@ class AgentClient(BaseClient):
         final_extras.setdefault("model", resolved_model)
 
         request = AgentCreateRequest(
-            name=str(name).strip(),
+            name=name,
             instruction=validated_instruction,
             model=resolved_model,
             language_model_id=language_model_id,
@@ -897,6 +1104,29 @@ class AgentClient(BaseClient):
         """Backward-compatible helper to create an agent from a configuration file."""
         return self.create_agent(file=file_path, **overrides)
 
+    def _resolve_update_model_fields(self, known: dict[str, Any]) -> None:
+        """Resolve model fields in-place for update payload if present.
+
+        If 'model' or 'language_model_id' keys exist in the known fields dict,
+        this method resolves them into 'language_model_id', 'provider', and 'model_name'
+        using the standard resolution logic, ensuring consistency with create_agent.
+
+        Args:
+            known: The dictionary of known fields to check and update in-place.
+        """
+        if "model" in known or "language_model_id" in known:
+            model_val = known.pop("model", None)
+            r_model, r_id, r_prov, r_name = self._process_model_fields(model_val, known)
+
+            if r_model is not None:
+                known["model"] = r_model
+            if r_id is not None:
+                known["language_model_id"] = r_id
+            if r_prov is not None:
+                known["provider"] = r_prov
+            if r_name is not None:
+                known["model_name"] = r_name
+
     def _update_agent_from_payload(
         self,
         agent_id: str,
@@ -922,6 +1152,8 @@ class AgentClient(BaseClient):
         if mcps_value is not None:
             mcps_value = self._resolve_mcp_ids(mcps_value, mcp_refs)  # pragma: no cover
 
+        self._resolve_update_model_fields(known)
+
         request = AgentUpdateRequest(
             name=known.pop("name", None),
             instruction=known.pop("instruction", None),

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