glaip-sdk 0.1.2__py3-none-any.whl → 0.7.17__py3-none-any.whl

glaip_sdk/client/base.py

@@ -3,10 +3,12 @@
 
 Authors:
     Raymond Christopher (raymond.christopher@gdplabs.id)
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
 """
 
 import logging
 import os
+import time
 from collections.abc import Iterable, Mapping
 from typing import Any, NoReturn, Union
 
@@ -88,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
@@ -480,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/hitl.py

@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+"""HITL REST client for manual approval operations.
+
+Authors:
+    GLAIP SDK Team
+"""
+
+from typing import Any
+
+from glaip_sdk.client.base import BaseClient
+from glaip_sdk.hitl.base import HITLDecision
+
+
+class HITLClient(BaseClient):
+    """Client for HITL REST endpoints.
+
+    Use for manual approval workflows separate from agent runs.
+
+    Example:
+        >>> # List pending approvals
+        >>> pending = client.hitl.list_pending()
+        >>>
+        >>> # Approve a request
+        >>> client.hitl.approve(
+        ...     request_id="bc4d0a77-7800-470e-a91c-7fd663a66b4d",
+        ...     operator_input="Verified and approved",
+        ... )
+    """
+
+    def approve(
+        self,
+        request_id: str,
+        operator_input: str | None = None,
+        run_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Approve a HITL request.
+
+        Args:
+            request_id: HITL request ID from SSE stream
+            operator_input: Optional notes/reason for approval
+            run_id: Optional client-side run correlation ID
+
+        Returns:
+            Response dict: {"status": "ok", "message": "..."}
+        """
+        return self._post_decision(
+            request_id,
+            HITLDecision.APPROVED,
+            operator_input,
+            run_id,
+        )
+
+    def reject(
+        self,
+        request_id: str,
+        operator_input: str | None = None,
+        run_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Reject a HITL request.
+
+        Args:
+            request_id: HITL request ID
+            operator_input: Optional reason for rejection
+            run_id: Optional run correlation ID
+
+        Returns:
+            Response dict
+        """
+        return self._post_decision(
+            request_id,
+            HITLDecision.REJECTED,
+            operator_input,
+            run_id,
+        )
+
+    def skip(
+        self,
+        request_id: str,
+        operator_input: str | None = None,
+        run_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Skip a HITL request.
+
+        Args:
+            request_id: HITL request ID
+            operator_input: Optional notes
+            run_id: Optional run correlation ID
+
+        Returns:
+            Response dict
+        """
+        return self._post_decision(
+            request_id,
+            HITLDecision.SKIPPED,
+            operator_input,
+            run_id,
+        )
+
+    def _post_decision(
+        self,
+        request_id: str,
+        decision: HITLDecision,
+        operator_input: str | None,
+        run_id: str | None,
+    ) -> dict[str, Any]:
+        """Post HITL decision to backend."""
+        payload = {
+            "request_id": request_id,
+            "decision": decision.value,
+        }
+
+        if operator_input:
+            payload["operator_input"] = operator_input
+        if run_id:
+            payload["run_id"] = run_id
+
+        return self._request("POST", "/agents/hitl/decision", json=payload)
+
+    def list_pending(self) -> list[dict[str, Any]]:
+        """List all pending HITL requests.
+
+        Returns:
+            List of pending request dicts with metadata:
+            [
+                {
+                    "request_id": "...",
+                    "tool": "...",
+                    "arguments": {...},
+                    "created_at": "...",
+                    "agent_id": "...",
+                    "hitl_metadata": {...},
+                },
+                ...
+            ]
+        """
+        return self._request("GET", "/agents/hitl/pending")

glaip_sdk/client/main.py

@@ -3,15 +3,26 @@
 
 Authors:
     Raymond Christopher (raymond.christopher@gdplabs.id)
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
 """
 
-from typing import Any
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
 
 from glaip_sdk.client.agents import AgentClient
 from glaip_sdk.client.base import BaseClient
+from glaip_sdk.client.hitl import HITLClient
 from glaip_sdk.client.mcps import MCPClient
+from glaip_sdk.client.schedules import ScheduleClient
+from glaip_sdk.client.shared import build_shared_config
 from glaip_sdk.client.tools import ToolClient
-from glaip_sdk.models import MCP, Agent, Tool
+
+if TYPE_CHECKING:  # pragma: no cover
+    from glaip_sdk.agents import Agent
+    from glaip_sdk.client.payloads.agent import AgentListResult
+    from glaip_sdk.mcps import MCP
+    from glaip_sdk.tools import Tool
 
 
 class Client(BaseClient):
@@ -25,15 +36,12 @@ 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)
+        self.schedules = ScheduleClient(**shared_config)
+        self.hitl = HITLClient(**shared_config)
 
     # ---- Core API Methods (Public Interface) ----
 
@@ -53,7 +61,7 @@ class Client(BaseClient):
         name: str | None = None,
         version: str | None = None,
         sync_langflow_agents: bool = False,
-    ) -> list[Agent]:
+    ) -> AgentListResult:
         """List agents with optional filtering.
 
         Args:
@@ -64,7 +72,7 @@ class Client(BaseClient):
             sync_langflow_agents: Sync with LangFlow server before listing (only applies when agent_type=langflow)
 
         Returns:
-            List of agents matching the filters
+            AgentListResult with agents and pagination metadata. Supports iteration and indexing.
         """
         return self.agents.list_agents(
             agent_type=agent_type,
@@ -204,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
@@ -217,6 +221,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
@@ -227,6 +236,8 @@ class Client(BaseClient):
                 self.tools.http_client = self.http_client
             if hasattr(self, "mcps"):
                 self.mcps.http_client = self.http_client
+            if hasattr(self, "schedules"):
+                self.schedules.http_client = self.http_client
         except Exception:
             pass
 

glaip_sdk/client/mcps.py

@@ -3,18 +3,22 @@
 
 Authors:
     Raymond Christopher (raymond.christopher@gdplabs.id)
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
 """
 
 import logging
 from typing import Any
 
 from glaip_sdk.client.base import BaseClient
-from glaip_sdk.config.constants import (
-    DEFAULT_MCP_TRANSPORT,
-    DEFAULT_MCP_TYPE,
+from glaip_sdk.config.constants import DEFAULT_MCP_TRANSPORT, DEFAULT_MCP_TYPE
+from glaip_sdk.mcps import MCP
+from glaip_sdk.models import MCPResponse
+from glaip_sdk.utils.client_utils import (
+    add_kwargs_to_payload,
+    create_model_instances,
+    find_by_name,
 )
-from glaip_sdk.models import MCP
-from glaip_sdk.utils.client_utils import create_model_instances, find_by_name
+from glaip_sdk.utils.resource_refs import is_uuid
 
 # API endpoints
 MCPS_ENDPOINT = "/mcps/"
@@ -45,7 +49,8 @@ class MCPClient(BaseClient):
     def get_mcp_by_id(self, mcp_id: str) -> MCP:
         """Get MCP by ID."""
         data = self._request("GET", f"{MCPS_ENDPOINT}{mcp_id}")
-        return MCP(**data)._set_client(self)
+        response = MCPResponse(**data)
+        return MCP.from_response(response, client=self)
 
     def find_mcps(self, name: str | None = None) -> list[MCP]:
         """Find MCPs by name."""
@@ -77,34 +82,156 @@ class MCPClient(BaseClient):
             get_endpoint_fmt=f"{MCPS_ENDPOINT}{{id}}",
             json=payload,
         )
-        return MCP(**full_mcp_data)._set_client(self)
+        response = MCPResponse(**full_mcp_data)
+        return MCP.from_response(response, client=self)
 
-    def update_mcp(self, mcp_id: str, **kwargs) -> MCP:
+    def update_mcp(self, mcp_id: str | MCP, **kwargs) -> MCP:
         """Update an existing MCP.
 
-        Automatically chooses between PUT (full update) and PATCH (partial update)
-        based on the provided fields:
-        - Uses PUT if name, config, and transport are all provided (full update)
-        - Uses PATCH otherwise (partial update)
+        Notes:
+            - Payload construction is centralized via ``_build_update_payload`` so required
+              defaults (e.g., ``type``) and value normalization stay consistent across SDK and CLI.
+            - For backward compatibility, still chooses PATCH vs PUT based on which fields the
+              caller provided, but uses the SDK payload builder for the final payload.
         """
-        # Check if all required fields for full update are provided
+        # Backward-compatible: allow passing an MCP instance to avoid an extra fetch.
+        if isinstance(mcp_id, MCP):
+            current_mcp = mcp_id
+            if not current_mcp.id:
+                raise ValueError("MCP instance has no id; cannot update.")
+            mcp_id_value = str(current_mcp.id)
+        else:
+            current_mcp = None
+            mcp_id_value = mcp_id
+
         required_fields = {"name", "config", "transport"}
         provided_fields = set(kwargs.keys())
+        method = "PUT" if required_fields.issubset(provided_fields) else "PATCH"
+
+        if not kwargs:
+            data = self._request(method, f"{MCPS_ENDPOINT}{mcp_id_value}", json={})
+            response = MCPResponse(**data)
+            return MCP.from_response(response, client=self)
+
+        if current_mcp is None:
+            current_mcp = self.get_mcp_by_id(mcp_id_value)
+
+        payload_kwargs = kwargs.copy()
+        name = payload_kwargs.pop("name", None)
+        description = payload_kwargs.pop("description", None)
+        full_payload = self._build_update_payload(
+            current_mcp=current_mcp,
+            name=name,
+            description=description,
+            **payload_kwargs,
+        )
 
-        if required_fields.issubset(provided_fields):
-            # All required fields provided - use full update (PUT)
-            method = "PUT"
+        if method == "PUT":
+            json_payload = full_payload
         else:
-            # Partial update - use PATCH
-            method = "PATCH"
+            json_payload = {key: full_payload[key] for key in provided_fields if key in full_payload}
+            json_payload["type"] = full_payload["type"]
+            if "config" in provided_fields and "transport" not in provided_fields and "transport" in full_payload:
+                json_payload["transport"] = full_payload["transport"]
 
-        data = self._request(method, f"{MCPS_ENDPOINT}{mcp_id}", json=kwargs)
-        return MCP(**data)._set_client(self)
+        data = self._request(method, f"{MCPS_ENDPOINT}{mcp_id_value}", json=json_payload)
+        response = MCPResponse(**data)
+        return MCP.from_response(response, client=self)
 
     def delete_mcp(self, mcp_id: str) -> None:
         """Delete an MCP."""
         self._request("DELETE", f"{MCPS_ENDPOINT}{mcp_id}")
 
+    def upsert_mcp(
+        self,
+        identifier: str | MCP,
+        description: str | None = None,
+        config: dict[str, Any] | None = None,
+        **kwargs,
+    ) -> MCP:
+        """Create or update an MCP by instance, ID, or name.
+
+        Args:
+            identifier: MCP instance, ID (UUID string), or name
+            description: MCP description
+            config: MCP configuration dictionary
+            **kwargs: Additional parameters (transport, metadata, etc.)
+
+        Returns:
+            The created or updated MCP.
+
+        Example:
+            >>> # By name (creates if not exists)
+            >>> mcp = client.mcps.upsert_mcp(
+            ...     "deepwiki",
+            ...     transport="sse",
+            ...     config={"url": "https://mcp.deepwiki.com/sse"},
+            ... )
+            >>> # By instance
+            >>> mcp = client.mcps.upsert_mcp(existing_mcp, description="Updated")
+            >>> # By ID
+            >>> mcp = client.mcps.upsert_mcp("uuid-here", description="Updated")
+        """
+        # Handle MCP instance
+        if isinstance(identifier, MCP):
+            if identifier.id:
+                logger.info("Updating MCP by instance: %s", identifier.name)
+                return self._do_upsert_update(identifier.id, identifier.name, description, config, **kwargs)
+            # MCP without ID - treat name as identifier
+            identifier = identifier.name
+
+        # Handle string (ID or name)
+        if isinstance(identifier, str):
+            if is_uuid(identifier):
+                logger.info("Updating MCP by ID: %s", identifier)
+                existing = self.get_mcp_by_id(identifier)
+                return self._do_upsert_update(identifier, existing.name, description, config, **kwargs)
+
+            # It's a name - find or create
+            return self._upsert_by_name(identifier, description, config, **kwargs)
+
+        raise ValueError(f"Invalid identifier type: {type(identifier)}")
+
+    def _do_upsert_update(
+        self,
+        mcp_id: str,
+        name: str | None,
+        description: str | None,
+        config: dict[str, Any] | None,
+        **kwargs,
+    ) -> MCP:
+        """Perform the update part of upsert."""
+        update_kwargs = {**kwargs}
+        if name is not None:
+            update_kwargs["name"] = name
+        if description is not None:
+            update_kwargs["description"] = description
+        if config is not None:
+            update_kwargs["config"] = config
+        return self.update_mcp(mcp_id, **update_kwargs)
+
+    def _upsert_by_name(
+        self,
+        name: str,
+        description: str | None,
+        config: dict[str, Any] | None,
+        **kwargs,
+    ) -> MCP:
+        """Find by name and update, or create if not found."""
+        all_mcps = self.list_mcps()
+        existing = [mcp for mcp in all_mcps if mcp.name.lower() == name.lower()]
+
+        if len(existing) == 1:
+            logger.info("Updating existing MCP: %s", name)
+            return self._do_upsert_update(existing[0].id, name, description, config, **kwargs)
+
+        if len(existing) > 1:
+            raise ValueError(f"Multiple MCPs found with name '{name}'")
+
+        # Create new MCP
+        logger.info("Creating new MCP: %s", name)
+        return self.create_mcp(name=name, description=description, config=config, **kwargs)
+
     def _build_create_payload(
         self,
         name: str,
@@ -147,9 +274,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
 
@@ -206,7 +331,23 @@ class MCPClient(BaseClient):
     def get_mcp_tools(self, mcp_id: str) -> list[dict[str, Any]]:
         """Get tools available from an MCP."""
         data = self._request("GET", f"{MCPS_ENDPOINT}{mcp_id}/tools")
-        return data or []
+        if data is None:
+            return []
+        if isinstance(data, list):
+            return data
+        if isinstance(data, dict):
+            if "tools" in data:
+                return data.get("tools", []) or []
+            logger.warning(
+                "Unexpected MCP tools response keys %s; returning empty list",
+                list(data.keys()),
+            )
+            return []
+        logger.warning(
+            "Unexpected MCP tools response type %s; returning empty list",
+            type(data).__name__,
+        )
+        return []
 
     def test_mcp_connection(self, config: dict[str, Any]) -> dict[str, Any]:
         """Test MCP connection using configuration.

glaip_sdk/client/payloads/agent/__init__.py

@@ -0,0 +1,23 @@
+"""Agent payload types for requests and responses.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from glaip_sdk.client.payloads.agent.requests import (
+    AgentCreateRequest,
+    AgentListParams,
+    AgentUpdateRequest,
+    merge_payload_fields,
+    resolve_language_model_fields,
+)
+from glaip_sdk.client.payloads.agent.responses import AgentListResult
+
+__all__ = [
+    "AgentCreateRequest",
+    "AgentListParams",
+    "AgentListResult",
+    "AgentUpdateRequest",
+    "merge_payload_fields",
+    "resolve_language_model_fields",
+]