glaip-sdk 0.6.1__py3-none-any.whl → 0.6.2__py3-none-any.whl

glaip_sdk/agents/base.py

@@ -51,6 +51,7 @@ from typing import TYPE_CHECKING, Any
 
 from glaip_sdk.registry import get_agent_registry, get_mcp_registry, get_tool_registry
 from glaip_sdk.utils.discovery import find_agent
+from glaip_sdk.utils.runtime_config import normalize_runtime_config_keys
 
 if TYPE_CHECKING:
     from glaip_sdk.models import AgentResponse
@@ -795,21 +796,23 @@ class Agent:
         self._client = client
         return self
 
-    def run(
+    def _prepare_run_kwargs(
         self,
         message: str,
-        verbose: bool = False,
+        verbose: bool,
+        runtime_config: dict[str, Any] | None,
         **kwargs: Any,
-    ) -> str:
-        """Run the agent synchronously with a message.
+    ) -> tuple[Any, dict[str, Any]]:
+        """Prepare common arguments for run/arun methods.
 
         Args:
             message: The message to send to the agent.
             verbose: If True, print streaming output to console.
+            runtime_config: Optional runtime configuration.
             **kwargs: Additional arguments to pass to the run API.
 
         Returns:
-            The agent's response as a string.
+            Tuple of (agent_client, call_kwargs).
 
         Raises:
             ValueError: If the agent hasn't been deployed yet.
@@ -820,24 +823,77 @@ class Agent:
         if not self._client:
             raise RuntimeError(_CLIENT_NOT_AVAILABLE_MSG)
 
-        # _client can be either main Client or AgentClient
         agent_client = getattr(self._client, "agents", self._client)
-        return agent_client.run_agent(
-            agent_id=self.id,
-            message=message,
-            verbose=verbose,
-            **kwargs,
+
+        call_kwargs: dict[str, Any] = {
+            "agent_id": self.id,
+            "message": message,
+            "verbose": verbose,
+        }
+
+        if runtime_config is not None:
+            call_kwargs["runtime_config"] = normalize_runtime_config_keys(
+                runtime_config,
+                tool_registry=get_tool_registry(),
+                mcp_registry=get_mcp_registry(),
+                agent_registry=get_agent_registry(),
+            )
+
+        call_kwargs.update(kwargs)
+        return agent_client, call_kwargs
+
+    def run(
+        self,
+        message: str,
+        verbose: bool = False,
+        runtime_config: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> str:
+        """Run the agent synchronously with a message.
+
+        Args:
+            message: The message to send to the agent.
+            verbose: If True, print streaming output to console.
+            runtime_config: Optional runtime configuration for tools, MCPs, and agents.
+                Keys can be SDK objects, UUIDs, or names. Example:
+                {
+                    "tool_configs": {"tool-id": {"param": "value"}},
+                    "mcp_configs": {"mcp-id": {"setting": "on"}},
+                    "agent_config": {"planning": True},
+                }
+            **kwargs: Additional arguments to pass to the run API.
+
+        Returns:
+            The agent's response as a string.
+
+        Raises:
+            ValueError: If the agent hasn't been deployed yet.
+            RuntimeError: If client is not available.
+        """
+        agent_client, call_kwargs = self._prepare_run_kwargs(
+            message, verbose, runtime_config or kwargs.get("runtime_config"), **kwargs
         )
+        return agent_client.run_agent(**call_kwargs)
 
     async def arun(
         self,
         message: str,
+        verbose: bool = False,
+        runtime_config: dict[str, Any] | None = None,
         **kwargs: Any,
     ) -> AsyncGenerator[dict, None]:
         """Run the agent asynchronously with streaming output.
 
         Args:
             message: The message to send to the agent.
+            verbose: If True, print streaming output to console.
+            runtime_config: Optional runtime configuration for tools, MCPs, and agents.
+                Keys can be SDK objects, UUIDs, or names. Example:
+                {
+                    "tool_configs": {"tool-id": {"param": "value"}},
+                    "mcp_configs": {"mcp-id": {"setting": "on"}},
+                    "agent_config": {"planning": True},
+                }
             **kwargs: Additional arguments to pass to the run API.
 
         Yields:
@@ -847,18 +903,10 @@ class Agent:
             ValueError: If the agent hasn't been deployed yet.
             RuntimeError: If client is not available.
         """
-        if not self.id:
-            raise ValueError(_AGENT_NOT_DEPLOYED_MSG)
-        if not self._client:
-            raise RuntimeError(_CLIENT_NOT_AVAILABLE_MSG)
-
-        # _client can be either main Client or AgentClient
-        agent_client = getattr(self._client, "agents", self._client)
-        async for chunk in agent_client.arun_agent(
-            agent_id=self.id,
-            message=message,
-            **kwargs,
-        ):
+        agent_client, call_kwargs = self._prepare_run_kwargs(
+            message, verbose, runtime_config or kwargs.get("runtime_config"), **kwargs
+        )
+        async for chunk in agent_client.arun_agent(**call_kwargs):
             yield chunk
 
     def update(self, **kwargs: Any) -> Agent:

glaip_sdk/client/agents.py

@@ -441,7 +441,7 @@ class AgentClient(BaseClient):
         started_monotonic: float | None,
         finished_monotonic: float | None,
     ) -> str:
-        """Finalize the renderer and return the final text.
+        """Finalize the renderer and return the final response text.
 
         Args:
             renderer: Renderer to finalize.
@@ -1095,9 +1095,32 @@ class AgentClient(BaseClient):
         tty: bool = False,
         *,
         renderer: RichStreamRenderer | str | None = "auto",
+        runtime_config: dict[str, Any] | None = None,
         **kwargs,
     ) -> str:
-        """Run an agent with a message, streaming via a renderer."""
+        """Run an agent with a message, streaming via a renderer.
+
+        Args:
+            agent_id: The ID of the agent to run.
+            message: The message to send to the agent.
+            files: Optional list of files to include with the request.
+            tty: Whether to enable TTY mode.
+            renderer: Renderer for streaming output.
+            runtime_config: Optional runtime configuration for tools, MCPs, and agents.
+                Keys should be platform IDs. Example:
+                {
+                    "tool_configs": {"tool-id": {"param": "value"}},
+                    "mcp_configs": {"mcp-id": {"setting": "on"}},
+                    "agent_config": {"planning": True},
+                }
+            **kwargs: Additional arguments to pass to the run API.
+
+        Returns:
+            The agent's response as a string.
+        """
+        # Include runtime_config in kwargs only when caller hasn't already provided it
+        if runtime_config is not None and "runtime_config" not in kwargs:
+            kwargs["runtime_config"] = runtime_config
         (
             payload,
             data_payload,
@@ -1242,6 +1265,7 @@ class AgentClient(BaseClient):
         files: list[str | BinaryIO] | None = None,
         *,
         request_timeout: float | None = None,
+        runtime_config: dict[str, Any] | None = None,
         **kwargs,
     ) -> AsyncGenerator[dict, None]:
         """Async run an agent with a message, yielding streaming JSON chunks.
@@ -1251,6 +1275,13 @@ class AgentClient(BaseClient):
             message: Message to send to the agent
             files: Optional list of files to include
             request_timeout: Optional request timeout in seconds (defaults to client timeout)
+            runtime_config: Optional runtime configuration for tools, MCPs, and agents.
+                Keys should be platform IDs. Example:
+                {
+                    "tool_configs": {"tool-id": {"param": "value"}},
+                    "mcp_configs": {"mcp-id": {"setting": "on"}},
+                    "agent_config": {"planning": True},
+                }
             **kwargs: Additional arguments (chat_history, pii_mapping, etc.)
 
         Yields:
@@ -1261,6 +1292,9 @@ class AgentClient(BaseClient):
             httpx.TimeoutException: When general timeout occurs
             Exception: For other unexpected errors
         """
+        # Include runtime_config in kwargs only when caller hasn't already provided it
+        if runtime_config is not None and "runtime_config" not in kwargs:
+            kwargs["runtime_config"] = runtime_config
         # Derive timeout values for request/control flow
         legacy_timeout = kwargs.get("timeout")
         http_timeout_override = request_timeout if request_timeout is not None else legacy_timeout

glaip_sdk/utils/runtime_config.py

@@ -0,0 +1,306 @@
+"""Runtime configuration helpers for agent execution.
+
+Provides utilities for normalizing runtime_config keys from various input types
+(SDK objects, UUIDs, names) to stable platform IDs.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from glaip_sdk.utils.resource_refs import is_uuid
+from gllm_core.utils import LoggerManager
+
+if TYPE_CHECKING:
+    from glaip_sdk.agents import Agent
+    from glaip_sdk.mcps import MCP
+    from glaip_sdk.registry import AgentRegistry, MCPRegistry, ToolRegistry
+    from glaip_sdk.tools import Tool
+
+    # Type alias for config key inputs (only used in type hints)
+    ConfigKeyInput = str | Agent | Tool | MCP | type[Agent] | type[Tool] | type[MCP]
+
+    # Type alias for registry types
+    Registry = ToolRegistry | MCPRegistry | AgentRegistry
+
+    # Type alias for runtime config dict shape after normalization
+    # Top-level keys include:
+    # - "tool_configs", "mcp_configs", "agent_config"
+    # - Agent IDs for agent-specific overrides
+    # Values are nested dictionaries whose contents depend on the section.
+    RuntimeConfigDict = dict[str, dict[str, object]]
+
+logger = LoggerManager().get_logger(__name__)
+
+# Config fields that need key normalization (maps field name to registry type)
+_NORMALIZABLE_FIELDS = {
+    "tool_configs": "tool",
+    "mcp_configs": "mcp",
+}
+
+# Config fields that are preserved as-is (no normalization needed)
+_PASSTHROUGH_FIELDS = {"agent_config"}
+
+
+def _extract_id_from_key(key: ConfigKeyInput) -> str | None:
+    """Extract ID directly from key if available.
+
+    Args:
+        key: The config key to extract ID from.
+
+    Returns:
+        The ID string if available, None otherwise.
+    """
+    if isinstance(key, str) and is_uuid(key):
+        return key
+    if hasattr(key, "id") and key.id is not None:
+        return key.id
+    return None
+
+
+def _resolve_via_registry(key: ConfigKeyInput, registry: Registry | None) -> str | None:
+    """Attempt to resolve key via registry.
+
+    Args:
+        key: The config key to resolve.
+        registry: Registry to use for resolution.
+
+    Returns:
+        The resolved ID string if successful, None otherwise.
+    """
+    if registry is None:
+        return None
+
+    try:
+        return registry.resolve(key).id
+    except (KeyError, ValueError, AttributeError) as exc:
+        logger.debug("Failed to resolve key via registry: %r", key, exc_info=exc)
+        return None
+    except Exception as exc:  # pragma: no cover - unexpected failures
+        logger.warning(
+            "Unexpected error resolving key via registry for %r: %s",
+            key,
+            exc,
+            exc_info=True,
+        )
+        return None
+
+
+def _resolve_config_key(
+    key: ConfigKeyInput,
+    registry: Registry | None,
+    *,
+    missing_registry_message: str,
+    unresolved_message: str,
+) -> str:
+    """Resolve a config key using a registry when needed.
+
+    For non-ID keys this always requires a registry; callers customize the
+    error messages for missing registries vs unresolved keys.
+    """
+    # Allow direct UUID / object.id without needing a registry
+    if (extracted_id := _extract_id_from_key(key)) is not None:
+        return extracted_id
+
+    # For non-ID keys we always require a registry
+    if registry is None:
+        raise ValueError(missing_registry_message.format(key=key))
+
+    if (resolved_id := _resolve_via_registry(key, registry)) is not None:
+        return resolved_id
+
+    raise ValueError(unresolved_message.format(key=key))
+
+
+def _normalize_section_keys(
+    config_section: dict[ConfigKeyInput, dict[str, object]],
+    registry: Registry | None,
+) -> dict[str, dict[str, object]]:
+    """Normalize keys in a single config section (e.g. tool_configs).
+
+    Converts ConfigKeyInput keys (SDK objects, names, classes) to stable IDs
+    using the provided registry.
+
+    Example:
+        Input:  {ToolClass: {"param": "value"}, "tool-name": {"x": 1}}
+        Output: {"uuid-1": {"param": "value"}, "uuid-2": {"x": 1}}
+
+    Args:
+        config_section: The config section dict to normalize.
+        registry: Registry to use for resolving keys.
+
+    Returns:
+        Normalized config section with all keys converted to IDs.
+    """
+    normalized: dict[str, dict[str, object]] = {}
+    for key, value in config_section.items():
+        resolved_id = _resolve_config_key(
+            key,
+            registry,
+            missing_registry_message="Unable to resolve runtime_config key via registry: {key!r}",
+            unresolved_message="Unable to resolve runtime_config key via registry: {key!r}",
+        )
+        normalized[resolved_id] = value
+    return normalized
+
+
+def _is_agent_specific_key(key: object) -> bool:
+    """Check if a key represents an agent-specific override.
+
+    Agent-specific keys are:
+    - Agent instances (from glaip_sdk.agents.Agent)
+    - UUID strings (agent IDs)
+    - Non-reserved string names (resolved via agent_registry)
+
+    NOT agent-specific:
+    - Known config field names (tool_configs, mcp_configs, agent_config)
+    - Tool or MCP objects (these are only valid inside *_configs sections)
+
+    Args:
+        key: The key to check.
+
+    Returns:
+        True if the key could be an agent-specific override.
+    """
+    from glaip_sdk.agents import Agent  # noqa: PLC0415
+
+    # Agent instance
+    if isinstance(key, Agent):
+        return True
+
+    # Non-string keys that are not Agent instances are not agent-specific
+    if not isinstance(key, str):
+        return False
+
+    # Known config field names are not agent-specific
+    if key in _NORMALIZABLE_FIELDS or key in _PASSTHROUGH_FIELDS:
+        return False
+
+    # Any other string key is treated as an agent reference (ID or name)
+    return True
+
+
+def _normalize_standard_config(
+    config: dict[str, object],
+    tool_registry: ToolRegistry | None,
+    mcp_registry: MCPRegistry | None,
+    context: str = "",
+) -> dict[str, object]:
+    """Normalize a standard config dict with tool_configs, mcp_configs, agent_config sections.
+
+    Used for both global runtime_config and agent-specific nested configs.
+    Delegates key normalization to _normalize_section_keys for each section.
+
+    Example:
+        Input:  {"tool_configs": {ToolClass: {...}}, "agent_config": {...}}
+        Output: {"tool_configs": {"tool-uuid": {...}}, "agent_config": {...}}
+
+    Args:
+        config: The config dict to normalize.
+        tool_registry: Registry for resolving tool keys.
+        mcp_registry: Registry for resolving MCP keys.
+        context: Context string for warning messages.
+
+    Returns:
+        Normalized config dict.
+    """
+    registries: dict[str, Registry | None] = {
+        "tool": tool_registry,
+        "mcp": mcp_registry,
+    }
+
+    result: dict[str, object] = {}
+
+    for field, value in config.items():
+        if field in _NORMALIZABLE_FIELDS and isinstance(value, dict):
+            registry_type = _NORMALIZABLE_FIELDS[field]
+            result[field] = _normalize_section_keys(value, registries.get(registry_type))
+        elif field in _PASSTHROUGH_FIELDS:
+            result[field] = value
+        else:
+            logger.warning("Unknown field '%s' in %s, ignoring", field, context or "config")
+
+    return result
+
+
+def normalize_runtime_config_keys(
+    runtime_config: RuntimeConfigDict | None,
+    tool_registry: ToolRegistry | None,
+    mcp_registry: MCPRegistry | None,
+    agent_registry: AgentRegistry | None,
+) -> RuntimeConfigDict | None:
+    """Normalize runtime_config keys from various input types to stable IDs.
+
+    Handles both global configs and agent-specific overrides:
+    - Global: tool_configs, mcp_configs, agent_config
+    - Agent-specific: keyed by Agent object, agent UUID, or agent name string
+
+    Example:
+        Input:
+        {
+            "tool_configs": {ToolClass: {"param": "val"}},
+            "agent_config": {"planning": True},
+            AgentClass: {"mcp_configs": {MCPClass: {...}}}
+        }
+        Output:
+        {
+            "tool_configs": {"tool-uuid": {"param": "val"}},
+            "agent_config": {"planning": True},
+            "agent-uuid": {"mcp_configs": {"mcp-uuid": {...}}}
+        }
+
+    Converts keys from:
+    - SDK objects → their .id attribute
+    - UUID strings → passed through
+    - Names → resolved via appropriate registry
+
+    Args:
+        runtime_config: The runtime configuration dict to normalize.
+        tool_registry: Registry for resolving tool keys.
+        mcp_registry: Registry for resolving MCP keys.
+        agent_registry: Registry for resolving agent keys.
+
+    Returns:
+        Normalized runtime_config with all keys converted to IDs, or None if input is None.
+    """
+    if runtime_config is None:
+        return None
+
+    if not runtime_config:
+        return {}
+
+    registries: dict[str, Registry | None] = {
+        "tool": tool_registry,
+        "mcp": mcp_registry,
+    }
+
+    result: dict[str, object] = {}
+
+    for field, value in runtime_config.items():
+        if field in _NORMALIZABLE_FIELDS and isinstance(value, dict):
+            registry_type = _NORMALIZABLE_FIELDS[field]
+            result[field] = _normalize_section_keys(value, registries.get(registry_type))
+        elif field in _PASSTHROUGH_FIELDS:
+            result[field] = value
+        elif _is_agent_specific_key(field) and isinstance(value, dict):
+            agent_id = _resolve_config_key(
+                field,
+                agent_registry,
+                missing_registry_message=(
+                    "Agent-specific runtime_config provided but no agent_registry is available to resolve key: {key!r}"
+                ),
+                unresolved_message="Unable to resolve agent-specific runtime_config key: {key!r}",
+            )
+            result[agent_id] = _normalize_standard_config(
+                value,
+                tool_registry,
+                mcp_registry,
+                context=f"agent '{agent_id}'",
+            )
+        else:
+            logger.warning("Unknown field '%s' in runtime_config, ignoring", field)
+
+    return result

{glaip_sdk-0.6.1.dist-info → glaip_sdk-0.6.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: glaip-sdk
-Version: 0.6.1
+Version: 0.6.2
 Summary: Python SDK for GL AIP (GDP Labs AI Agent Package) - Simplified CLI Design
 License: MIT
 Author: Raymond Christopher

{glaip_sdk-0.6.1.dist-info → glaip_sdk-0.6.2.dist-info}/RECORD

@@ -1,7 +1,7 @@
 glaip_sdk/__init__.py,sha256=0PAFfodqAEdggIiV1Es_JryDokZrhYLFFIXosqdguJU,420
 glaip_sdk/_version.py,sha256=5CHGCxx_36fgmMWuEx6jJ2CzzM-i9eBFyQWFwBi23XE,2259
 glaip_sdk/agents/__init__.py,sha256=VfYov56edbWuySXFEbWJ_jLXgwnFzPk1KB-9-mfsUCc,776
-glaip_sdk/agents/base.py,sha256=mEUHw5bv5eIwcrU9CEVYBfSdmDh9qjeAzGoecsgSS2w,33968
+glaip_sdk/agents/base.py,sha256=asXkYyOiaeqqzsOk_FoFXbECBozyy7rfxgr9h0iliKc,36060
 glaip_sdk/branding.py,sha256=tLqYCIHMkUf8p2smpuAGNptwaKUN38G4mlh0A0DOl_w,7823
 glaip_sdk/cli/__init__.py,sha256=xCCfuF1Yc7mpCDcfhHZTX0vizvtrDSLeT8MJ3V7m5A0,156
 glaip_sdk/cli/account_store.py,sha256=NXuAVPaJS_32Aw1VTaZCNwIID-gADw4F_UMieoWmg3g,17336
@@ -57,7 +57,7 @@ glaip_sdk/cli/validators.py,sha256=d-kq4y7HWMo6Gc7wLXWUsCt8JwFvJX_roZqRm1Nko1I,5
 glaip_sdk/client/__init__.py,sha256=F-eE_dRSzA0cc1it06oi0tZetZBHmSUjWSHGhJMLCls,263
 glaip_sdk/client/_agent_payloads.py,sha256=cH7CvNRn0JvudwKLr072E7W2QGWO9r-4xDxWMvXoPKE,17865
 glaip_sdk/client/agent_runs.py,sha256=tZSFEZZ3Yx0uYRgnwkLe-X0TlmgKJQ-ivzb6SrVnxY8,4862
-glaip_sdk/client/agents.py,sha256=QSeXH93ysyNae67FCStIpDfDr33t4_d2gXpJD07GV54,45866
+glaip_sdk/client/agents.py,sha256=33Wr5BYLN6uSN_Vwdine-9KKT030nDnsEArytN9g0lc,47580
 glaip_sdk/client/base.py,sha256=BhNaC2TJJ2jVWRTYmfxD3WjYgAyIuWNz9YURdNXXjJo,18245
 glaip_sdk/client/main.py,sha256=RTREAOgGouYm4lFKkpNBQ9dmxalnBsIpSSaQLWVFSmU,9054
 glaip_sdk/client/mcps.py,sha256=gFRuLOGeh6ieIhR4PeD6yNVT6NhvUMTqPq9iuu1vkAY,13019
@@ -130,10 +130,11 @@ glaip_sdk/utils/rendering/viewer/__init__.py,sha256=XrxmE2cMAozqrzo1jtDFm8HqNtvD
 glaip_sdk/utils/rendering/viewer/presenter.py,sha256=mlLMTjnyeyPVtsyrAbz1BJu9lFGQSlS-voZ-_Cuugv0,5725
 glaip_sdk/utils/resource_refs.py,sha256=vF34kyAtFBLnaKnQVrsr2st1JiSxVbIZ4yq0DelJvCI,5966
 glaip_sdk/utils/run_renderer.py,sha256=d_VMI6LbvHPUUeRmGqh5wK_lHqDEIAcym2iqpbtDad0,1365
+glaip_sdk/utils/runtime_config.py,sha256=Y6frWR_PjD3CV2Jl3AqKxhhsJCkrxSuX27jw0-2aX2M,10124
 glaip_sdk/utils/serialization.py,sha256=z-qpvWLSBrGK3wbUclcA1UIKLXJedTnMSwPdq-FF4lo,13308
 glaip_sdk/utils/sync.py,sha256=3VKqs1UfNGWSobgRXohBKP7mMMzdUW3SU0bJQ1uxOgw,4872
 glaip_sdk/utils/validation.py,sha256=Vt8oSnn7OM6ns5vjOl5FwGIMWBPb0yI6RD5XL_L5_4M,6826
-glaip_sdk-0.6.1.dist-info/METADATA,sha256=VwJmx6U73oXAx60NouUdkhGK_TV0Yx-n1QN9R__sC-w,7128
-glaip_sdk-0.6.1.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
-glaip_sdk-0.6.1.dist-info/entry_points.txt,sha256=EGs8NO8J1fdFMWA3CsF7sKBEvtHb_fujdCoNPhfMouE,47
-glaip_sdk-0.6.1.dist-info/RECORD,,
+glaip_sdk-0.6.2.dist-info/METADATA,sha256=i9j_B_1f1ONjg6yRh_pcA8ZRqkhl9ZJ-V1JecnRTUOw,7128
+glaip_sdk-0.6.2.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+glaip_sdk-0.6.2.dist-info/entry_points.txt,sha256=EGs8NO8J1fdFMWA3CsF7sKBEvtHb_fujdCoNPhfMouE,47
+glaip_sdk-0.6.2.dist-info/RECORD,,