glaip-sdk 0.2.1__py3-none-any.whl → 0.3.0__py3-none-any.whl

glaip_sdk/client/agents.py

@@ -5,9 +5,11 @@ Authors:
     Raymond Christopher (raymond.christopher@gdplabs.id)
 """
 
+import asyncio
 import json
 import logging
 from collections.abc import AsyncGenerator, Callable, Iterator, Mapping
+from contextlib import asynccontextmanager
 from os import PathLike
 from pathlib import Path
 from typing import Any, BinaryIO
@@ -20,6 +22,7 @@ from glaip_sdk.client._agent_payloads import (
     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 (
@@ -28,6 +31,7 @@ from glaip_sdk.client.run_rendering import (
 )
 from glaip_sdk.client.tools import ToolClient
 from glaip_sdk.config.constants import (
+    AGENT_CONFIG_FIELDS,
     DEFAULT_AGENT_FRAMEWORK,
     DEFAULT_AGENT_RUN_TIMEOUT,
     DEFAULT_AGENT_TYPE,
@@ -67,6 +71,19 @@ _MERGED_SEQUENCE_FIELDS = ("tools", "agents", "mcps")
 _DEFAULT_METADATA_TYPE = "custom"
 
 
+@asynccontextmanager
+async def _async_timeout_guard(timeout_seconds: float | None) -> AsyncGenerator[None, None]:
+    """Apply an asyncio timeout when a custom timeout is provided."""
+    if timeout_seconds is None:
+        yield
+        return
+    try:
+        async with asyncio.timeout(timeout_seconds):
+            yield
+    except asyncio.TimeoutError as exc:
+        raise httpx.TimeoutException(f"Request timed out after {timeout_seconds}s") from exc
+
+
 def _normalise_sequence(value: Any) -> list[Any] | None:
     """Normalise optional sequence inputs to plain lists."""
     if value is None:
@@ -193,19 +210,7 @@ def _extract_original_refs(raw_definition: dict) -> dict[str, list]:
 
 def _build_cli_args(overrides_dict: dict) -> dict[str, Any]:
     """Build CLI args from overrides, filtering out None values."""
-    cli_args = {
-        key: overrides_dict.get(key)
-        for key in (
-            "name",
-            "instruction",
-            "model",
-            "tools",
-            "agents",
-            "mcps",
-            "timeout",
-        )
-        if overrides_dict.get(key) is not None
-    }
+    cli_args = {key: overrides_dict.get(key) for key in AGENT_CONFIG_FIELDS if overrides_dict.get(key) is not None}
 
     # Normalize sequence fields
     for field in _MERGED_SEQUENCE_FIELDS:
@@ -254,6 +259,7 @@ class AgentClient(BaseClient):
         self._renderer_manager = AgentRunRenderingManager(logger)
         self._tool_client: ToolClient | None = None
         self._mcp_client: MCPClient | None = None
+        self._runs_client: "AgentRunsClient | None" = None
 
     def list_agents(
         self,
@@ -366,6 +372,11 @@ class AgentClient(BaseClient):
     # Renderer delegation helpers
     # ------------------------------------------------------------------ #
     def _get_renderer_manager(self) -> AgentRunRenderingManager:
+        """Get or create the renderer manager instance.
+
+        Returns:
+            AgentRunRenderingManager instance.
+        """
         manager = getattr(self, "_renderer_manager", None)
         if manager is None:
             manager = AgentRunRenderingManager(logger)
@@ -373,6 +384,15 @@ class AgentClient(BaseClient):
         return manager
 
     def _create_renderer(self, renderer: RichStreamRenderer | str | None, **kwargs: Any) -> RichStreamRenderer:
+        """Create or return a renderer instance.
+
+        Args:
+            renderer: Renderer instance, string identifier, or None.
+            **kwargs: Additional keyword arguments (e.g., verbose).
+
+        Returns:
+            RichStreamRenderer instance.
+        """
         manager = self._get_renderer_manager()
         verbose = kwargs.get("verbose", False)
         if isinstance(renderer, RichStreamRenderer) or hasattr(renderer, "on_start"):
@@ -387,6 +407,18 @@ class AgentClient(BaseClient):
         agent_name: str | None,
         meta: dict[str, Any],
     ) -> tuple[str, dict[str, Any], float | None, float | None]:
+        """Process stream events from an HTTP response.
+
+        Args:
+            stream_response: HTTP response stream.
+            renderer: Renderer to use for displaying events.
+            timeout_seconds: Timeout in seconds.
+            agent_name: Optional agent name.
+            meta: Metadata dictionary.
+
+        Returns:
+            Tuple of (final_text, stats_usage, started_monotonic, finished_monotonic).
+        """
         manager = self._get_renderer_manager()
         return manager.process_stream_events(
             stream_response,
@@ -404,6 +436,18 @@ class AgentClient(BaseClient):
         started_monotonic: float | None,
         finished_monotonic: float | None,
     ) -> str:
+        """Finalize the renderer and return the final text.
+
+        Args:
+            renderer: Renderer to finalize.
+            final_text: Final text content.
+            stats_usage: Usage statistics dictionary.
+            started_monotonic: Start time (monotonic).
+            finished_monotonic: Finish time (monotonic).
+
+        Returns:
+            Final text string.
+        """
         manager = self._get_renderer_manager()
         return manager.finalize_renderer(
             renderer,
@@ -414,11 +458,21 @@ class AgentClient(BaseClient):
         )
 
     def _get_tool_client(self) -> ToolClient:
+        """Get or create the tool client instance.
+
+        Returns:
+            ToolClient instance.
+        """
         if self._tool_client is None:
             self._tool_client = ToolClient(parent_client=self)
         return self._tool_client
 
     def _get_mcp_client(self) -> MCPClient:
+        """Get or create the MCP client instance.
+
+        Returns:
+            MCPClient instance.
+        """
         if self._mcp_client is None:
             self._mcp_client = MCPClient(parent_client=self)
         return self._mcp_client
@@ -428,6 +482,15 @@ class AgentClient(BaseClient):
         entry: Any,
         fallback_iter: Iterator[Any] | None,
     ) -> tuple[str | None, str | None]:
+        """Normalize a reference entry to extract ID and name.
+
+        Args:
+            entry: Reference entry (string, dict, or other).
+            fallback_iter: Optional iterator for fallback values.
+
+        Returns:
+            Tuple of (entry_id, entry_name).
+        """
         entry_id: str | None = None
         entry_name: str | None = None
 
@@ -464,6 +527,19 @@ class AgentClient(BaseClient):
         label: str,
         plural_label: str | None = None,
     ) -> list[str] | None:
+        """Resolve a list of resource references to IDs.
+
+        Args:
+            items: List of resource references to resolve.
+            references: Optional list of reference objects for fallback.
+            fetch_by_id: Function to fetch resource by ID.
+            find_by_name: Function to find resources by name.
+            label: Singular label for error messages.
+            plural_label: Plural label for error messages.
+
+        Returns:
+            List of resolved resource IDs, or None if items is empty.
+        """
         if not items:
             return None
 
@@ -495,6 +571,22 @@ class AgentClient(BaseClient):
         singular: str,
         plural: str,
     ) -> str:
+        """Resolve a single resource reference to an ID.
+
+        Args:
+            entry: Resource reference to resolve.
+            fallback_iter: Optional iterator for fallback values.
+            fetch_by_id: Function to fetch resource by ID.
+            find_by_name: Function to find resources by name.
+            singular: Singular label for error messages.
+            plural: Plural label for error messages.
+
+        Returns:
+            Resolved resource ID string.
+
+        Raises:
+            ValueError: If the resource cannot be resolved.
+        """
         entry_id, entry_name = self._normalise_reference_entry(entry, fallback_iter)
 
         validated_id = self._validate_resource_id(fetch_by_id, entry_id)
@@ -511,6 +603,14 @@ class AgentClient(BaseClient):
 
     @staticmethod
     def _coerce_reference_value(entry: Any) -> str:
+        """Coerce a reference entry to a string value.
+
+        Args:
+            entry: Reference entry (dict, string, or other).
+
+        Returns:
+            String representation of the reference.
+        """
         if isinstance(entry, dict):
             if entry.get("id"):
                 return str(entry["id"])
@@ -520,6 +620,15 @@ class AgentClient(BaseClient):
 
     @staticmethod
     def _validate_resource_id(fetch_by_id: Callable[[str], Any], candidate_id: str | None) -> str | None:
+        """Validate a resource ID by attempting to fetch it.
+
+        Args:
+            fetch_by_id: Function to fetch resource by ID.
+            candidate_id: Candidate ID to validate.
+
+        Returns:
+            Validated ID if found, None otherwise.
+        """
         if not candidate_id:
             return None
         try:
@@ -535,6 +644,20 @@ class AgentClient(BaseClient):
         singular: str,
         plural: str,
     ) -> tuple[str, bool]:
+        """Resolve a resource by name to an ID.
+
+        Args:
+            find_by_name: Function to find resources by name.
+            entry_name: Name of the resource to find.
+            singular: Singular label for error messages.
+            plural: Plural label for error messages.
+
+        Returns:
+            Tuple of (resolved_id, success).
+
+        Raises:
+            ValueError: If resource not found or multiple matches exist.
+        """
         try:
             matches = find_by_name(entry_name)
         except Exception:
@@ -555,6 +678,15 @@ class AgentClient(BaseClient):
         tools: list[Any] | None,
         references: list[Any] | None = None,
     ) -> list[str] | None:
+        """Resolve tool references to IDs.
+
+        Args:
+            tools: List of tool references to resolve.
+            references: Optional list of reference objects for fallback.
+
+        Returns:
+            List of resolved tool IDs, or None if tools is empty.
+        """
         tool_client = self._get_tool_client()
         return self._resolve_resource_ids(
             tools,
@@ -570,6 +702,15 @@ class AgentClient(BaseClient):
         agents: list[Any] | None,
         references: list[Any] | None = None,
     ) -> list[str] | None:
+        """Resolve agent references to IDs.
+
+        Args:
+            agents: List of agent references to resolve.
+            references: Optional list of reference objects for fallback.
+
+        Returns:
+            List of resolved agent IDs, or None if agents is empty.
+        """
         return self._resolve_resource_ids(
             agents,
             references,
@@ -584,6 +725,15 @@ class AgentClient(BaseClient):
         mcps: list[Any] | None,
         references: list[Any] | None = None,
     ) -> list[str] | None:
+        """Resolve MCP references to IDs.
+
+        Args:
+            mcps: List of MCP references to resolve.
+            references: Optional list of reference objects for fallback.
+
+        Returns:
+            List of resolved MCP IDs, or None if mcps is empty.
+        """
         mcp_client = self._get_mcp_client()
         return self._resolve_resource_ids(
             mcps,
@@ -1028,7 +1178,7 @@ class AgentClient(BaseClient):
         message: str,
         files: list[str | BinaryIO] | None = None,
         *,
-        timeout: float | None = None,
+        request_timeout: float | None = None,
         **kwargs,
     ) -> AsyncGenerator[dict, None]:
         """Async run an agent with a message, yielding streaming JSON chunks.
@@ -1037,7 +1187,7 @@ class AgentClient(BaseClient):
             agent_id: ID of the agent to run
             message: Message to send to the agent
             files: Optional list of files to include
-            timeout: Request timeout in seconds
+            request_timeout: Optional request timeout in seconds (defaults to client timeout)
             **kwargs: Additional arguments (chat_history, pii_mapping, etc.)
 
         Yields:
@@ -1048,18 +1198,22 @@ class AgentClient(BaseClient):
             httpx.TimeoutException: When general timeout occurs
             Exception: For other unexpected errors
         """
+        # 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
+        http_timeout = http_timeout_override or self.timeout
+
         # Prepare request data
         payload, data_payload, files_payload, headers = self._prepare_request_data(message, files, **kwargs)
 
         # Create async client configuration
-        async_client_config = self._create_async_client_config(timeout, headers)
+        async_client_config = self._create_async_client_config(http_timeout_override, headers)
 
         # Get execution timeout for streaming control
         timeout_seconds = kwargs.get("timeout", DEFAULT_AGENT_RUN_TIMEOUT)
         agent_name = kwargs.get("agent_name")
 
-        try:
-            # Create async client and stream response
+        async def _chunk_stream() -> AsyncGenerator[dict, None]:
             async with httpx.AsyncClient(**async_client_config) as async_client:
                 async for chunk in self._stream_agent_response(
                     async_client,
@@ -1073,7 +1227,17 @@ class AgentClient(BaseClient):
                 ):
                     yield chunk
 
-        finally:
-            # Ensure cleanup - this is handled by the calling context
-            # but we keep this for safety in case of future changes
-            pass
+        async with _async_timeout_guard(http_timeout):
+            async for chunk in _chunk_stream():
+                yield chunk
+
+    @property
+    def runs(self) -> "AgentRunsClient":
+        """Get the agent runs client."""
+        if self._runs_client is None:
+            # Import here to avoid circular dependency with client.main
+            from glaip_sdk.client.main import _build_shared_config
+
+            shared_config = _build_shared_config(self)
+            self._runs_client = AgentRunsClient(**shared_config)
+        return self._runs_client

glaip_sdk/client/main.py

@@ -14,6 +14,23 @@ from glaip_sdk.client.tools import ToolClient
 from glaip_sdk.models import MCP, Agent, Tool
 
 
+def _build_shared_config(client: BaseClient) -> dict[str, Any]:
+    """Build shared configuration dictionary for sub-clients.
+
+    Args:
+        client: Base client instance.
+
+    Returns:
+        Dictionary with shared configuration.
+    """
+    return {
+        "parent_client": client,
+        "api_url": client.api_url,
+        "api_key": client.api_key,
+        "timeout": client._timeout,
+    }
+
+
 class Client(BaseClient):
     """Main client that composes all specialized clients and shares one HTTP session."""
 
@@ -25,12 +42,7 @@ class Client(BaseClient):
         """
         super().__init__(**kwargs)
         # Share the single httpx.Client + config with sub-clients
-        shared_config = {
-            "parent_client": self,
-            "api_url": self.api_url,
-            "api_key": self.api_key,
-            "timeout": self._timeout,
-        }
+        shared_config = _build_shared_config(self)
         self.agents = AgentClient(**shared_config)
         self.tools = ToolClient(**shared_config)
         self.mcps = MCPClient(**shared_config)
@@ -217,6 +229,11 @@ class Client(BaseClient):
 
     @timeout.setter
     def timeout(self, value: float) -> None:  # type: ignore[override]
+        """Set the client timeout and propagate to sub-clients.
+
+        Args:
+            value: Timeout value in seconds.
+        """
         # Rebuild the root http client
         BaseClient.timeout.fset(self, value)  # call parent setter
         # Propagate the new session to sub-clients so they don't hold a closed client

glaip_sdk/client/mcps.py

@@ -14,7 +14,7 @@ from glaip_sdk.config.constants import (
     DEFAULT_MCP_TYPE,
 )
 from glaip_sdk.models import MCP
-from glaip_sdk.utils.client_utils import create_model_instances, find_by_name
+from glaip_sdk.utils.client_utils import add_kwargs_to_payload, create_model_instances, find_by_name
 
 # API endpoints
 MCPS_ENDPOINT = "/mcps/"
@@ -147,9 +147,7 @@ class MCPClient(BaseClient):
 
         # Add any other kwargs (excluding already handled ones)
         excluded_keys = {"type"}  # type is handled above
-        for key, value in kwargs.items():
-            if key not in excluded_keys:
-                payload[key] = value
+        add_kwargs_to_payload(payload, kwargs, excluded_keys)
 
         return payload
 

glaip_sdk/client/run_rendering.py

@@ -124,6 +124,11 @@ class AgentRunRenderingManager:
         renderer.on_start(meta)
 
     def _create_silent_renderer(self) -> RichStreamRenderer:
+        """Create a silent renderer that outputs to a string buffer.
+
+        Returns:
+            RichStreamRenderer configured for silent output.
+        """
         silent_config = RendererConfig(
             live=False,
             persist_live=False,
@@ -136,6 +141,11 @@ class AgentRunRenderingManager:
         )
 
     def _create_minimal_renderer(self) -> RichStreamRenderer:
+        """Create a minimal renderer with reduced output.
+
+        Returns:
+            RichStreamRenderer configured for minimal output.
+        """
         minimal_config = RendererConfig(
             live=False,
             persist_live=False,
@@ -148,6 +158,11 @@ class AgentRunRenderingManager:
         )
 
     def _create_verbose_renderer(self) -> RichStreamRenderer:
+        """Create a verbose renderer with detailed output.
+
+        Returns:
+            RichStreamRenderer configured for verbose output.
+        """
         verbose_config = RendererConfig(
             live=False,
             append_finished_snapshots=False,
@@ -159,6 +174,14 @@ class AgentRunRenderingManager:
         )
 
     def _create_default_renderer(self, verbose: bool) -> RichStreamRenderer:
+        """Create the default renderer based on verbosity.
+
+        Args:
+            verbose: Whether to create a verbose renderer.
+
+        Returns:
+            RichStreamRenderer instance.
+        """
         if verbose:
             return self._create_verbose_renderer()
         default_config = RendererConfig()
@@ -214,12 +237,27 @@ class AgentRunRenderingManager:
         meta: dict[str, Any],
         renderer: RichStreamRenderer,
     ) -> None:
+        """Capture request ID from response headers and update metadata.
+
+        Args:
+            stream_response: HTTP response stream.
+            meta: Metadata dictionary to update.
+            renderer: Renderer instance.
+        """
         req_id = stream_response.headers.get("x-request-id") or stream_response.headers.get("x-run-id")
         if req_id:
             meta["run_id"] = req_id
             renderer.on_start(meta)
 
     def _maybe_start_timer(self, event: dict[str, Any]) -> float | None:
+        """Start timing if this is a content-bearing event.
+
+        Args:
+            event: Event dictionary.
+
+        Returns:
+            Monotonic time if timer should start, None otherwise.
+        """
         try:
             ev = json.loads(event["data"])
         except json.JSONDecodeError:
@@ -237,6 +275,18 @@ class AgentRunRenderingManager:
         stats_usage: dict[str, Any],
         meta: dict[str, Any],
     ) -> tuple[str, dict[str, Any]]:
+        """Process a single streaming event.
+
+        Args:
+            event: Event dictionary.
+            renderer: Renderer instance.
+            final_text: Accumulated text so far.
+            stats_usage: Usage statistics dictionary.
+            meta: Metadata dictionary.
+
+        Returns:
+            Tuple of (updated_final_text, updated_stats_usage).
+        """
         try:
             ev = json.loads(event["data"])
         except json.JSONDecodeError:
@@ -292,6 +342,15 @@ class AgentRunRenderingManager:
         return None
 
     def _handle_content_event(self, ev: dict[str, Any], final_text: str) -> str:
+        """Handle a content event and update final text.
+
+        Args:
+            ev: Event dictionary.
+            final_text: Current accumulated text.
+
+        Returns:
+            Updated final text.
+        """
         content = ev.get("content", "")
         if not content.startswith("Artifact received:"):
             return content
@@ -303,6 +362,13 @@ class AgentRunRenderingManager:
         meta: dict[str, Any],
         renderer: RichStreamRenderer,
     ) -> None:
+        """Handle a run_info event and update metadata.
+
+        Args:
+            ev: Event dictionary.
+            meta: Metadata dictionary to update.
+            renderer: Renderer instance.
+        """
         if ev.get("model"):
             meta["model"] = ev["model"]
             renderer.on_start(meta)

glaip_sdk/client/tools.py

@@ -18,6 +18,7 @@ from glaip_sdk.config.constants import (
 )
 from glaip_sdk.models import Tool
 from glaip_sdk.utils.client_utils import (
+    add_kwargs_to_payload,
     create_model_instances,
     find_by_name,
 )
@@ -200,9 +201,7 @@ class ToolClient(BaseClient):
 
         # Add any other kwargs (excluding already handled ones)
         excluded_keys = {"tags", "version"}
-        for key, value in kwargs.items():
-            if key not in excluded_keys:
-                payload[key] = value
+        add_kwargs_to_payload(payload, kwargs, excluded_keys)
 
         return payload
 

glaip_sdk/config/constants.py

@@ -39,3 +39,14 @@ DEFAULT_MCP_TRANSPORT = "stdio"
 
 # Default error messages
 DEFAULT_ERROR_MESSAGE = "Unknown error"
+
+# Agent configuration fields used for CLI args and payload building
+AGENT_CONFIG_FIELDS = (
+    "name",
+    "instruction",
+    "model",
+    "tools",
+    "agents",
+    "mcps",
+    "timeout",
+)

glaip_sdk/models/__init__.py

@@ -0,0 +1,56 @@
+"""Models package for AIP SDK.
+
+This package re-exports models from the legacy models.py file for backward compatibility.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+import importlib.util
+import sys
+from pathlib import Path
+
+# Export new agent runs models first (no dependencies on legacy models)
+from glaip_sdk.models.agent_runs import (  # noqa: F401
+    RunOutputChunk,
+    RunSummary,
+    RunsPage,
+    RunWithOutput,
+)
+
+# Import from the parent models.py file
+_parent_file = Path(__file__).parent.parent / "models.py"
+if _parent_file.exists():
+    spec = importlib.util.spec_from_file_location("glaip_sdk.models_legacy", _parent_file)
+    models_legacy = importlib.util.module_from_spec(spec)
+    sys.modules["glaip_sdk.models_legacy"] = models_legacy
+    spec.loader.exec_module(models_legacy)
+
+    # Re-export all models
+    Agent = models_legacy.Agent
+    Tool = models_legacy.Tool
+    MCP = models_legacy.MCP
+    LanguageModelResponse = models_legacy.LanguageModelResponse
+    TTYRenderer = models_legacy.TTYRenderer
+else:
+    # Fallback: try direct import (won't work if models/ exists)
+    # pragma: no cover - defensive fallback path, unlikely to execute
+    from glaip_sdk import models as models_legacy  # type: ignore  # pragma: no cover
+
+    Agent = models_legacy.Agent  # pragma: no cover
+    Tool = models_legacy.Tool  # pragma: no cover
+    MCP = models_legacy.MCP  # pragma: no cover
+    LanguageModelResponse = models_legacy.LanguageModelResponse  # pragma: no cover
+    TTYRenderer = models_legacy.TTYRenderer  # pragma: no cover
+
+__all__ = [
+    "Agent",
+    "Tool",
+    "MCP",
+    "LanguageModelResponse",
+    "TTYRenderer",
+    "RunSummary",
+    "RunsPage",
+    "RunWithOutput",
+    "RunOutputChunk",
+]