glaip-sdk 0.0.7__py3-none-any.whl → 0.6.5b6__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
+from collections.abc import Iterable, Mapping
 from typing import Any, NoReturn, Union
 
 import httpx
@@ -14,7 +16,7 @@ from dotenv import load_dotenv
 
 import glaip_sdk
 from glaip_sdk._version import __version__ as SDK_VERSION
-from glaip_sdk.config.constants import SDK_NAME
+from glaip_sdk.config.constants import DEFAULT_ERROR_MESSAGE, SDK_NAME
 from glaip_sdk.exceptions import (
     AuthenticationError,
     ConflictError,
@@ -151,12 +153,7 @@ class BaseClient:
     def timeout(self, value: float) -> None:
         """Set timeout and rebuild client."""
         self._timeout = value
-        if (
-            hasattr(self, "http_client")
-            and self.http_client
-            and not self._session_scoped
-            and not self._parent_client
-        ):
+        if hasattr(self, "http_client") and self.http_client and not self._session_scoped and not self._parent_client:
             self.http_client.close()
             self.http_client = self._build_client(value)
 
@@ -230,8 +227,13 @@ class BaseClient:
             else:
                 raise
 
-    def _request(self, method: str, endpoint: str, **kwargs) -> Any:
-        """Make HTTP request with error handling."""
+    def _perform_request(
+        self,
+        method: str,
+        endpoint: str,
+        **kwargs: Any,
+    ) -> httpx.Response:
+        """Execute a raw HTTP request with retry handling."""
         # Ensure client is alive before making request
         self._ensure_client_alive()
 
@@ -239,20 +241,31 @@ class BaseClient:
         try:
             response = self.http_client.request(method, endpoint, **kwargs)
             client_log.debug(f"Response status: {response.status_code}")
-            return self._handle_response(response)
+            return response
         except httpx.ConnectError as e:
-            client_log.warning(
-                f"Connection error on {method} {endpoint}, retrying once: {e}"
-            )
+            client_log.warning(f"Connection error on {method} {endpoint}, retrying once: {e}")
             try:
                 response = self.http_client.request(method, endpoint, **kwargs)
-                client_log.debug(
-                    f"Retry successful, response status: {response.status_code}"
-                )
-                return self._handle_response(response)
+                client_log.debug(f"Retry successful, response status: {response.status_code}")
+                return response
             except httpx.ConnectError:
                 client_log.error(f"Retry failed for {method} {endpoint}: {e}")
-                raise e
+                raise
+
+    def _request(self, method: str, endpoint: str, **kwargs) -> Any:
+        """Make HTTP request with error handling and unwrap success envelopes."""
+        response = self._perform_request(method, endpoint, **kwargs)
+        return self._handle_response(response, unwrap=True)
+
+    def _request_with_envelope(
+        self,
+        method: str,
+        endpoint: str,
+        **kwargs: Any,
+    ) -> Any:
+        """Make HTTP request but return the full success envelope."""
+        response = self._perform_request(method, endpoint, **kwargs)
+        return self._handle_response(response, unwrap=False)
 
     def _parse_response_content(self, response: httpx.Response) -> Any | None:
         """Parse response content based on content type."""
@@ -271,14 +284,14 @@ class BaseClient:
         else:
             return None  # Let _handle_response deal with error status codes
 
-    def _handle_success_response(self, parsed: Any) -> Any:
+    def _handle_success_response(self, parsed: Any, *, unwrap: bool) -> Any:
         """Handle successful response with success flag."""
         if isinstance(parsed, dict) and "success" in parsed:
             if parsed.get("success"):
-                return parsed.get("data", parsed)
+                return parsed.get("data", parsed) if unwrap else parsed
             else:
                 error_type = parsed.get("error", "UnknownError")
-                message = parsed.get("message", "Unknown error")
+                message = self._format_error_dict({key: value for key, value in parsed.items() if key != "success"})
                 self._raise_api_error(
                     400,
                     message,
@@ -290,35 +303,142 @@ class BaseClient:
 
     def _get_error_message(self, response: httpx.Response) -> str:
         """Extract error message from response, preferring parsed content."""
-        # Try to get error message from parsed content if available
-        error_message = response.text
+        parsed = self._parse_error_json(response)
+        if parsed is None:
+            return response.text
+
+        formatted = self._format_parsed_error(parsed)
+        return formatted if formatted is not None else response.text
+
+    def _parse_error_json(self, response: httpx.Response) -> Any | None:
+        """Safely parse JSON from an error response."""
         try:
-            parsed = response.json()
-            if isinstance(parsed, dict) and "message" in parsed:
-                error_message = parsed["message"]
-            elif isinstance(parsed, str):
-                error_message = parsed
+            return response.json()
         except (ValueError, TypeError):
-            pass  # Use response.text as fallback
-        return error_message
+            return None
 
-    def _handle_response(self, response: httpx.Response) -> Any:
-        """Handle HTTP response with proper error handling."""
-        # Handle no-content success before general error handling
-        if response.status_code == 204:
+    def _format_parsed_error(self, parsed: Any) -> str | None:
+        """Build a readable error message from parsed JSON payloads."""
+        if isinstance(parsed, dict):
+            return self._format_error_dict(parsed)
+        if isinstance(parsed, str):
+            return parsed
+        return str(parsed) if parsed else None
+
+    def _format_error_dict(self, parsed: dict[str, Any]) -> str:
+        """Format structured API error payloads."""
+        detail = parsed.get("detail")
+        if isinstance(detail, list):
+            validation_message = self._format_validation_errors(detail)
+            if validation_message:
+                return validation_message
+            return f"Validation error: {parsed}"
+
+        formatted_details = None
+        if "details" in parsed:
+            formatted_details = self._format_error_details(parsed["details"])
+
+        message = parsed.get("message")
+        if message:
+            if formatted_details:
+                return f"{message}\n{formatted_details}"
+            return message
+
+        if formatted_details:
+            return formatted_details
+
+        return str(parsed) if parsed else DEFAULT_ERROR_MESSAGE
+
+    def _format_error_details(self, details: Any) -> str | None:
+        """Render generic error details into a human-readable string."""
+        if details is None:
             return None
 
-        # Handle error status codes
-        if not (200 <= response.status_code < 300):
-            error_message = self._get_error_message(response)
-            self._raise_api_error(response.status_code, error_message)
-            return None  # Won't be reached but helps with type checking
+        if isinstance(details, dict):
+            return self._format_detail_mapping(details)
 
-        parsed = self._parse_response_content(response)
-        if parsed is None:
+        if isinstance(details, (list, tuple, set)):
+            return self._format_detail_iterable(details)
+
+        return f"Details: {details}"
+
+    @staticmethod
+    def _format_detail_mapping(details: Mapping[str, Any]) -> str | None:
+        """Format details provided as a mapping."""
+        entries = [f"  {key}: {value}" for key, value in details.items()]
+        if not entries:
+            return None
+        return "Details:\n" + "\n".join(entries)
+
+    @staticmethod
+    def _format_detail_iterable(details: Iterable[Any]) -> str | None:
+        """Format details provided as an iterable collection."""
+        entries: list[str] = []
+        for item in details:
+            if isinstance(item, Mapping):
+                inner = ", ".join(f"{k}={v}" for k, v in item.items())
+                entries.append(f"  - {inner if inner else '{}'}")
+            else:
+                entries.append(f"  - {item}")
+
+        if not entries:
+            return None
+
+        return "Details:\n" + "\n".join(entries)
+
+    def _format_validation_errors(self, errors: list[Any]) -> str | None:
+        """Render validation errors into a human-readable string."""
+        entries: list[str] = []
+        for error in errors:
+            if isinstance(error, dict):
+                loc = " -> ".join(str(x) for x in error.get("loc", []))
+                msg = error.get("msg", DEFAULT_ERROR_MESSAGE)
+                error_type = error.get("type", "unknown")
+                prefix = loc if loc else "Field"
+                entries.append(f"  {prefix}: {msg} ({error_type})")
+            else:
+                entries.append(f"  {error}")
+
+        if not entries:
+            return None
+
+        return "Validation errors:\n" + "\n".join(entries)
+
+    @staticmethod
+    def _is_no_content_response(response: httpx.Response) -> bool:
+        """Return True when the response contains no content."""
+        return response.status_code == 204
+
+    @staticmethod
+    def _is_success_status(response: httpx.Response) -> bool:
+        """Return True for successful HTTP status codes."""
+        return 200 <= response.status_code < 300
+
+    def _handle_error_response(self, response: httpx.Response) -> None:
+        """Raise an API error for non-success responses."""
+        error_message = self._get_error_message(response)
+        parsed_content = self._parse_response_content(response)
+        self._raise_api_error(response.status_code, error_message, payload=parsed_content)
+
+    def _handle_response(
+        self,
+        response: httpx.Response,
+        *,
+        unwrap: bool = True,
+    ) -> Any:
+        """Handle HTTP response with proper error handling."""
+        # Handle no-content success before general error handling
+        if self._is_no_content_response(response):
             return None
 
-        return self._handle_success_response(parsed)
+        if self._is_success_status(response):
+            parsed = self._parse_response_content(response)
+            if parsed is None:
+                return None
+            return self._handle_success_response(parsed, unwrap=unwrap)
+
+        self._handle_error_response(response)
+        return None
 
     def _raise_api_error(
         self,
@@ -363,12 +483,7 @@ class BaseClient:
 
     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
-        ):
+        if hasattr(self, "http_client") and self.http_client and not self._session_scoped and not self._parent_client:
             self.http_client.close()
 
     def __enter__(self) -> "BaseClient":

glaip_sdk/client/main.py

@@ -3,29 +3,38 @@
 
 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.mcps import MCPClient
+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._agent_payloads import AgentListResult
+    from glaip_sdk.mcps import MCP
+    from glaip_sdk.tools import Tool
 
 
 class Client(BaseClient):
     """Main client that composes all specialized clients and shares one HTTP session."""
 
     def __init__(self, **kwargs):
+        """Initialize the main client.
+
+        Args:
+            **kwargs: Client configuration arguments (api_url, api_key, timeout, etc.)
+        """
         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)
@@ -37,6 +46,10 @@ class Client(BaseClient):
         """Create a new agent."""
         return self.agents.create_agent(**kwargs)
 
+    def create_agent_from_file(self, *args, **kwargs) -> Agent:
+        """Create a new agent from a JSON or YAML configuration file."""
+        return self.agents.create_agent_from_file(*args, **kwargs)
+
     def list_agents(
         self,
         agent_type: str | None = None,
@@ -44,7 +57,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:
@@ -55,7 +68,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,
@@ -81,6 +94,10 @@ class Client(BaseClient):
         """Update an existing agent."""
         return self.agents.update_agent(agent_id, **kwargs)
 
+    def update_agent_from_file(self, agent_id: str, *args, **kwargs) -> Agent:
+        """Update an existing agent using a JSON or YAML configuration file."""
+        return self.agents.update_agent_from_file(agent_id, *args, **kwargs)
+
     def delete_agent(self, agent_id: str) -> bool:
         """Delete an agent."""
         return self.agents.delete_agent(agent_id)
@@ -145,9 +162,9 @@ class Client(BaseClient):
         """Get tool script content."""
         return self.tools.get_tool_script(tool_id)
 
-    def update_tool_via_file(self, tool_id: str, file_path: str) -> Tool:
+    def update_tool_via_file(self, tool_id: str, file_path: str, **kwargs) -> Tool:
         """Update tool via file."""
-        return self.tools.update_tool_via_file(tool_id, file_path)
+        return self.tools.update_tool_via_file(tool_id, file_path, **kwargs)
 
     # MCPs
     def create_mcp(self, **kwargs) -> MCP:
@@ -199,10 +216,16 @@ class Client(BaseClient):
     # ---- Timeout propagation ----
     @property
     def timeout(self) -> float:  # type: ignore[override]
+        """Get the client timeout value."""
         return super().timeout
 
     @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

@@ -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."""
@@ -57,7 +62,7 @@ class MCPClient(BaseClient):
     def create_mcp(
         self,
         name: str,
-        description: str,
+        description: str | None = None,
         config: dict[str, Any] | None = None,
         **kwargs,
     ) -> MCP:
@@ -77,7 +82,8 @@ 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:
         """Update an existing MCP.
@@ -99,16 +105,106 @@ class MCPClient(BaseClient):
             method = "PATCH"
 
         data = self._request(method, f"{MCPS_ENDPOINT}{mcp_id}", json=kwargs)
-        return MCP(**data)._set_client(self)
+        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."""
+        existing = self.find_mcps(name)
+
+        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,
-        description: str,
+        description: str | None = None,
         transport: str = DEFAULT_MCP_TRANSPORT,
         config: dict[str, Any] | None = None,
         **kwargs,
@@ -122,7 +218,7 @@ class MCPClient(BaseClient):
 
         Args:
             name: MCP name
-            description: MCP description
+            description: MCP description (optional)
             transport: MCP transport protocol (defaults to stdio)
             config: MCP configuration dictionary
             **kwargs: Additional parameters
@@ -147,9 +243,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
 
@@ -179,9 +273,7 @@ class MCPClient(BaseClient):
         update_data = {
             "name": name if name is not None else current_mcp.name,
             "type": DEFAULT_MCP_TYPE,  # Required by backend, MCPs are always server type
-            "transport": kwargs.get(
-                "transport", getattr(current_mcp, "transport", DEFAULT_MCP_TRANSPORT)
-            ),
+            "transport": kwargs.get("transport", getattr(current_mcp, "transport", DEFAULT_MCP_TRANSPORT)),
         }
 
         # Handle description with proper None handling
@@ -208,7 +300,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.