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

glaip_sdk/client/agents.py

@@ -3,6 +3,7 @@
 
 Authors:
     Raymond Christopher (raymond.christopher@gdplabs.id)
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
 """
 
 import asyncio
@@ -15,7 +16,7 @@ from pathlib import Path
 from typing import Any, BinaryIO
 
 import httpx
-
+from glaip_sdk.agents import Agent
 from glaip_sdk.client._agent_payloads import (
     AgentCreateRequest,
     AgentListParams,
@@ -40,7 +41,7 @@ from glaip_sdk.config.constants import (
     DEFAULT_MODEL,
 )
 from glaip_sdk.exceptions import NotFoundError, ValidationError
-from glaip_sdk.models import Agent
+from glaip_sdk.models import AgentResponse
 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 (
@@ -73,7 +74,9 @@ _DEFAULT_METADATA_TYPE = "custom"
 
 
 @asynccontextmanager
-async def _async_timeout_guard(timeout_seconds: float | None) -> AsyncGenerator[None, None]:
+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
@@ -260,7 +263,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
+        self._runs_client: AgentRunsClient | None = None
 
     def list_agents(
         self,
@@ -359,7 +362,8 @@ class AgentClient(BaseClient):
                 status_code=404,
             )
 
-        return Agent(**data)._set_client(self)
+        response = AgentResponse(**data)
+        return Agent.from_response(response, client=self)
 
     def find_agents(self, name: str | None = None) -> list[Agent]:
         """Find agents by name."""
@@ -826,7 +830,8 @@ class AgentClient(BaseClient):
             get_endpoint_fmt=f"{AGENTS_ENDPOINT}{{id}}",
             json=payload_dict,
         )
-        return Agent(**full_agent_data)._set_client(self)
+        response = AgentResponse(**full_agent_data)
+        return Agent.from_response(response, client=self)
 
     def create_agent(
         self,
@@ -921,8 +926,9 @@ class AgentClient(BaseClient):
 
         payload_dict = request.to_payload(current_agent)
 
-        response = self._request("PUT", f"/agents/{agent_id}", json=payload_dict)
-        return Agent(**response)._set_client(self)
+        api_response = self._request("PUT", f"/agents/{agent_id}", json=payload_dict)
+        response = AgentResponse(**api_response)
+        return Agent.from_response(response, client=self)
 
     def update_agent(
         self,
@@ -969,6 +975,62 @@ class AgentClient(BaseClient):
         """Delete an agent."""
         self._request("DELETE", f"/agents/{agent_id}")
 
+    def upsert_agent(self, identifier: str | Agent, **kwargs) -> Agent:
+        """Create or update an agent by instance, ID, or name.
+
+        Args:
+            identifier: Agent instance, ID (UUID string), or name
+            **kwargs: Agent configuration (instruction, description, tools, etc.)
+
+        Returns:
+            The created or updated agent.
+
+        Example:
+            >>> # By name (creates if not exists)
+            >>> agent = client.agents.upsert_agent(
+            ...     "hello_agent",
+            ...     instruction="You are a helpful assistant.",
+            ...     description="A friendly agent",
+            ... )
+            >>> # By instance
+            >>> agent = client.agents.upsert_agent(existing_agent, description="Updated")
+            >>> # By ID
+            >>> agent = client.agents.upsert_agent("uuid-here", description="Updated")
+        """
+        # Handle Agent instance
+        if isinstance(identifier, Agent):
+            if identifier.id:
+                logger.info("Updating agent by instance: %s", identifier.name)
+                return self.update_agent(identifier.id, name=identifier.name, **kwargs)
+            identifier = identifier.name
+
+        # Handle string (ID or name)
+        if isinstance(identifier, str):
+            # Check if it's a UUID
+            if is_uuid(identifier):
+                logger.info("Updating agent by ID: %s", identifier)
+                return self.update_agent(identifier, **kwargs)
+
+            # It's a name - find or create
+            return self._upsert_agent_by_name(identifier, **kwargs)
+
+        raise ValueError(f"Invalid identifier type: {type(identifier)}")
+
+    def _upsert_agent_by_name(self, name: str, **kwargs) -> Agent:
+        """Find agent by name and update, or create if not found."""
+        existing = self.find_agents(name)
+
+        if len(existing) == 1:
+            logger.info("Updating existing agent: %s", name)
+            return self.update_agent(existing[0].id, name=name, **kwargs)
+
+        if len(existing) > 1:
+            raise ValueError(f"Multiple agents found with name '{name}'")
+
+        # Create new agent
+        logger.info("Creating new agent: %s", name)
+        return self.create_agent(name=name, **kwargs)
+
     def _prepare_sync_request_data(
         self,
         message: str,

glaip_sdk/client/base.py

@@ -3,6 +3,7 @@
 
 Authors:
     Raymond Christopher (raymond.christopher@gdplabs.id)
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
 """
 
 import logging

glaip_sdk/client/main.py

@@ -3,16 +3,24 @@
 
 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):
@@ -49,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:
@@ -60,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,

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 add_kwargs_to_payload, 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,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,12 +105,102 @@ 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,
@@ -211,9 +307,15 @@ class MCPClient(BaseClient):
         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()))
+            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__)
+        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]:

glaip_sdk/client/tools.py

@@ -3,6 +3,7 @@
 
 Authors:
     Raymond Christopher (raymond.christopher@gdplabs.id)
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
 """
 
 import logging
@@ -16,12 +17,14 @@ from glaip_sdk.config.constants import (
     DEFAULT_TOOL_TYPE,
     DEFAULT_TOOL_VERSION,
 )
-from glaip_sdk.models import Tool
+from glaip_sdk.models import ToolResponse
+from glaip_sdk.tools import Tool
 from glaip_sdk.utils.client_utils import (
     add_kwargs_to_payload,
     create_model_instances,
     find_by_name,
 )
+from glaip_sdk.utils.resource_refs import is_uuid
 
 # API endpoints
 TOOLS_ENDPOINT = "/tools/"
@@ -59,11 +62,11 @@ class ToolClient(BaseClient):
     def get_tool_by_id(self, tool_id: str) -> Tool:
         """Get tool by ID."""
         data = self._request("GET", f"{TOOLS_ENDPOINT}{tool_id}")
-        return Tool(**data)._set_client(self)
+        response = ToolResponse(**data)
+        return Tool.from_response(response, client=self)
 
     def find_tools(self, name: str | None = None) -> list[Tool]:
         """Find tools by name."""
-        # Backend doesn't support name query parameter, so we fetch all and filter client-side
         data = self._request("GET", TOOLS_ENDPOINT)
         tools = create_model_instances(data, Tool, self)
         return find_by_name(tools, name, case_sensitive=False)
@@ -112,6 +115,7 @@ class ToolClient(BaseClient):
         data = {
             "name": name,
             "framework": framework,
+            "type": kwargs.pop("tool_type", DEFAULT_TOOL_TYPE),  # Default to custom
         }
 
         if description:
@@ -153,7 +157,8 @@ class ToolClient(BaseClient):
                 data=upload_data,
             )
 
-        return Tool(**response)._set_client(self)
+        tool_response = ToolResponse(**response)
+        return Tool.from_response(tool_response, client=self)
 
     def _build_create_payload(
         self,
@@ -275,6 +280,9 @@ class ToolClient(BaseClient):
             or getattr(current_tool, "type", None)
             or DEFAULT_TOOL_TYPE
         )
+        # Convert enum to string value for API payload
+        if hasattr(current_type, "value"):
+            current_type = current_type.value
 
         update_data = {
             "name": name if name is not None else current_tool.name,
@@ -434,12 +442,147 @@ class ToolClient(BaseClient):
     def update_tool(self, tool_id: str, **kwargs) -> Tool:
         """Update an existing tool."""
         data = self._request("PUT", f"{TOOLS_ENDPOINT}{tool_id}", json=kwargs)
-        return Tool(**data)._set_client(self)
+        response = ToolResponse(**data)
+        return Tool.from_response(response, client=self)
 
     def delete_tool(self, tool_id: str) -> None:
         """Delete a tool."""
         self._request("DELETE", f"{TOOLS_ENDPOINT}{tool_id}")
 
+    def upsert_tool(
+        self,
+        identifier: str | Tool,
+        code: str | None = None,
+        description: str | None = None,
+        framework: str = "langchain",
+        **kwargs,
+    ) -> Tool:
+        """Create or update a tool by instance, ID, or name.
+
+        Args:
+            identifier: Tool instance, ID (UUID string), or name
+            code: Python code containing the tool plugin (required for create)
+            description: Tool description
+            framework: Tool framework (defaults to "langchain")
+            **kwargs: Additional parameters (tags, version, etc.)
+
+        Returns:
+            The created or updated tool.
+
+        Example:
+            >>> # By name with code (creates if not exists)
+            >>> tool = client.tools.upsert_tool(
+            ...     "greeting",
+            ...     code=bundled_source,
+            ...     description="A greeting tool",
+            ... )
+            >>> # By instance
+            >>> tool = client.tools.upsert_tool(existing_tool, code=new_code)
+            >>> # By ID
+            >>> tool = client.tools.upsert_tool("uuid-here", code=new_code)
+        """
+        # Handle Tool instance
+        if isinstance(identifier, Tool):
+            if identifier.id:
+                logger.info("Updating tool by instance: %s", identifier.name)
+                return self._do_tool_upsert_update(
+                    identifier.id,
+                    identifier.name,
+                    code,
+                    description,
+                    framework,
+                    **kwargs,
+                )
+            identifier = identifier.name
+
+        # Handle string (ID or name)
+        if isinstance(identifier, str):
+            if is_uuid(identifier):
+                logger.info("Updating tool by ID: %s", identifier)
+                existing = self.get_tool_by_id(identifier)
+                return self._do_tool_upsert_update(identifier, existing.name, code, description, framework, **kwargs)
+
+            # It's a name - find or create
+            return self._upsert_tool_by_name(identifier, code, description, framework, **kwargs)
+
+        raise ValueError(f"Invalid identifier type: {type(identifier)}")
+
+    def _do_tool_upsert_update(
+        self,
+        tool_id: str,
+        name: str | None,
+        code: str | None,
+        description: str | None,
+        framework: str,
+        **kwargs,
+    ) -> Tool:
+        """Perform the update part of tool upsert."""
+        if code:
+            # Update via file upload
+            with tempfile.NamedTemporaryFile(
+                mode="w",
+                suffix=".py",
+                prefix=f"{name or 'tool'}_",
+                delete=False,
+                encoding="utf-8",
+            ) as temp_file:
+                temp_file.write(code)
+                temp_file_path = temp_file.name
+
+            try:
+                return self.update_tool_via_file(
+                    tool_id,
+                    temp_file_path,
+                    name=name,
+                    description=description,
+                    framework=framework,
+                    **kwargs,
+                )
+            finally:
+                try:
+                    os.unlink(temp_file_path)
+                except OSError:
+                    pass
+        else:
+            # Metadata-only update
+            update_kwargs = {"framework": framework, **kwargs}
+            if name:
+                update_kwargs["name"] = name
+            if description:
+                update_kwargs["description"] = description
+            return self.update_tool(tool_id, **update_kwargs)
+
+    def _upsert_tool_by_name(
+        self,
+        name: str,
+        code: str | None,
+        description: str | None,
+        framework: str,
+        **kwargs,
+    ) -> Tool:
+        """Find tool by name and update, or create if not found."""
+        existing = self.find_tools(name)
+
+        if len(existing) == 1:
+            logger.info("Updating existing tool: %s", name)
+            return self._do_tool_upsert_update(existing[0].id, name, code, description, framework, **kwargs)
+
+        if len(existing) > 1:
+            raise ValueError(f"Multiple tools found with name '{name}'")
+
+        # Create new tool - code is required
+        if not code:
+            raise ValueError(f"Tool '{name}' not found and no code provided for creation")
+
+        logger.info("Creating new tool: %s", name)
+        return self.create_tool_from_code(
+            name=name,
+            code=code,
+            framework=framework,
+            description=description,
+            **kwargs,
+        )
+
     def get_tool_script(self, tool_id: str) -> str:
         """Get the tool script content.
 
@@ -508,8 +651,9 @@ class ToolClient(BaseClient):
                     data=update_payload,
                 )
 
-            return Tool(**response)._set_client(self)
+            tool_response = ToolResponse(**response)
+            return Tool.from_response(tool_response, client=self)
 
         except Exception as e:
-            logger.error(f"Failed to update tool {tool_id} via file: {e}")
+            logger.error("Failed to update tool %s via file: %s", tool_id, e)
             raise

glaip_sdk/mcps/__init__.py

@@ -0,0 +1,21 @@
+"""MCP (Model Context Protocol) package for GL AIP platform.
+
+This package provides the MCP class and MCPRegistry for managing
+Model Context Protocol configurations on the GL AIP platform.
+
+Example:
+    >>> from glaip_sdk.mcps import MCP, get_mcp_registry
+    >>> mcp = MCP.from_native("arxiv-search")
+"""
+
+from __future__ import annotations
+
+from glaip_sdk.mcps.base import MCP, MCPConfigValue
+from glaip_sdk.registry.mcp import MCPRegistry, get_mcp_registry
+
+__all__ = [
+    "MCP",
+    "MCPConfigValue",
+    "MCPRegistry",
+    "get_mcp_registry",
+]