glaip-sdk 0.0.7__py3-none-any.whl → 0.6.5b6__py3-none-any.whl

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,11 +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/"
@@ -58,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)
@@ -96,9 +100,7 @@ class ToolClient(BaseClient):
         """
         return os.path.splitext(os.path.basename(file_path))[0]
 
-    def _prepare_upload_data(
-        self, name: str, framework: str, description: str | None = None, **kwargs
-    ) -> dict:
+    def _prepare_upload_data(self, name: str, framework: str, description: str | None = None, **kwargs) -> dict:
         """Prepare upload data dictionary.
 
         Args:
@@ -113,6 +115,7 @@ class ToolClient(BaseClient):
         data = {
             "name": name,
             "framework": framework,
+            "type": kwargs.pop("tool_type", DEFAULT_TOOL_TYPE),  # Default to custom
         }
 
         if description:
@@ -154,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,
@@ -202,9 +206,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
 
@@ -217,31 +219,31 @@ class ToolClient(BaseClient):
         elif hasattr(current_tool, "description") and current_tool.description:
             update_data["description"] = current_tool.description
 
-    def _handle_tags_update(
-        self, update_data: dict[str, Any], kwargs: dict[str, Any], current_tool: Tool
-    ) -> None:
+    def _handle_tags_update(self, update_data: dict[str, Any], kwargs: dict[str, Any], current_tool: Tool) -> None:
         """Handle tags field in update payload."""
         if kwargs.get("tags"):
             if isinstance(kwargs["tags"], list):
-                update_data["tags"] = ",".join(
-                    str(tag).strip() for tag in kwargs["tags"]
-                )
+                update_data["tags"] = ",".join(str(tag).strip() for tag in kwargs["tags"])
             else:
                 update_data["tags"] = str(kwargs["tags"])
         elif hasattr(current_tool, "tags") and current_tool.tags:
             # Preserve existing tags if present
             if isinstance(current_tool.tags, list):
-                update_data["tags"] = ",".join(
-                    str(tag).strip() for tag in current_tool.tags
-                )
+                update_data["tags"] = ",".join(str(tag).strip() for tag in current_tool.tags)
             else:
                 update_data["tags"] = str(current_tool.tags)
 
-    def _handle_additional_kwargs(
-        self, update_data: dict[str, Any], kwargs: dict[str, Any]
-    ) -> None:
+    def _handle_additional_kwargs(self, update_data: dict[str, Any], kwargs: dict[str, Any]) -> None:
         """Handle additional kwargs in update payload."""
-        excluded_keys = {"tags", "framework", "version"}
+        excluded_keys = {
+            "tags",
+            "framework",
+            "version",
+            "type",
+            "tool_type",
+            "name",
+            "description",
+        }
         for key, value in kwargs.items():
             if key not in excluded_keys:
                 update_data[key] = value
@@ -269,15 +271,24 @@ class ToolClient(BaseClient):
             - Handles metadata updates properly
         """
         # Prepare the update payload with current values as defaults
+        type_override = kwargs.pop("type", None)
+        if type_override is None:
+            type_override = kwargs.pop("tool_type", None)
+        current_type = (
+            type_override
+            or getattr(current_tool, "tool_type", None)
+            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,
-            "type": DEFAULT_TOOL_TYPE,  # Required by backend
-            "framework": kwargs.get(
-                "framework", getattr(current_tool, "framework", DEFAULT_TOOL_FRAMEWORK)
-            ),
-            "version": kwargs.get(
-                "version", getattr(current_tool, "version", DEFAULT_TOOL_VERSION)
-            ),
+            "type": current_type,
+            "framework": kwargs.get("framework", getattr(current_tool, "framework", DEFAULT_TOOL_FRAMEWORK)),
+            "version": kwargs.get("version", getattr(current_tool, "version", DEFAULT_TOOL_VERSION)),
         }
 
         # Handle description update
@@ -337,9 +348,7 @@ class ToolClient(BaseClient):
 
         try:
             # Prepare upload data
-            upload_data = self._prepare_upload_data(
-                name=name, framework=framework, description=description, **kwargs
-            )
+            upload_data = self._prepare_upload_data(name=name, framework=framework, description=description, **kwargs)
 
             # Upload file
             return self._upload_tool_file(temp_file_path, upload_data)
@@ -433,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.
 
@@ -476,6 +620,19 @@ class ToolClient(BaseClient):
         # Validate file exists
         self._validate_and_read_file(file_path)
 
+        # Fetch current metadata to ensure required fields are preserved
+        current_tool = self.get_tool_by_id(tool_id)
+
+        payload_kwargs = kwargs.copy()
+        name = payload_kwargs.pop("name", None)
+        description = payload_kwargs.pop("description", None)
+        update_payload = self._build_update_payload(
+            current_tool=current_tool,
+            name=name,
+            description=description,
+            **payload_kwargs,
+        )
+
         try:
             # Prepare multipart upload
             with open(file_path, "rb") as fb:
@@ -491,11 +648,12 @@ class ToolClient(BaseClient):
                     "PUT",
                     TOOLS_UPLOAD_BY_ID_ENDPOINT_FMT.format(tool_id=tool_id),
                     files=files,
-                    data=kwargs,  # Pass kwargs directly as data
+                    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/client/validators.py

@@ -39,9 +39,7 @@ class ResourceValidator:
         if len(found_tools) == 1:
             return str(found_tools[0].id)
         elif len(found_tools) > 1:
-            raise AmbiguousResourceError(
-                f"Multiple tools found with name '{tool_name}': {[t.id for t in found_tools]}"
-            )
+            raise AmbiguousResourceError(f"Multiple tools found with name '{tool_name}': {[t.id for t in found_tools]}")
         else:
             raise NotFoundError(f"Tool not found: {tool_name}")
 
@@ -51,9 +49,7 @@ class ResourceValidator:
         if len(found_tools) == 1:
             return str(found_tools[0].id)
         elif len(found_tools) > 1:
-            raise AmbiguousResourceError(
-                f"Multiple tools found with name '{tool.name}': {[t.id for t in found_tools]}"
-            )
+            raise AmbiguousResourceError(f"Multiple tools found with name '{tool.name}': {[t.id for t in found_tools]}")
         else:
             raise NotFoundError(f"Tool not found: {tool.name}")
 
@@ -73,9 +69,7 @@ class ResourceValidator:
         elif hasattr(tool, "name") and tool.name is not None:
             return self._resolve_tool_by_name_attribute(tool, client)
         else:
-            raise ValidationError(
-                f"Invalid tool reference: {tool} - must have 'id' or 'name' attribute"
-            )
+            raise ValidationError(f"Invalid tool reference: {tool} - must have 'id' or 'name' attribute")
 
     def _process_single_tool(self, tool: str | Tool, client: Any) -> str:
         """Process a single tool reference and return its ID."""
@@ -99,22 +93,14 @@ class ResourceValidator:
             try:
                 tool_id = cls()._process_single_tool(tool, client)
                 tool_ids.append(tool_id)
-            except (AmbiguousResourceError, NotFoundError) as e:
+            except (AmbiguousResourceError, NotFoundError) as err:
                 # Determine the tool name for the error message
-                tool_name = (
-                    tool if isinstance(tool, str) else getattr(tool, "name", str(tool))
-                )
-                raise ValidationError(
-                    f"Failed to resolve tool name '{tool_name}' to ID: {e}"
-                )
-            except Exception as e:
+                tool_name = tool if isinstance(tool, str) else getattr(tool, "name", str(tool))
+                raise ValidationError(f"Failed to resolve tool name '{tool_name}' to ID: {err}") from err
+            except Exception as err:
                 # For other exceptions, wrap them appropriately
-                tool_name = (
-                    tool if isinstance(tool, str) else getattr(tool, "name", str(tool))
-                )
-                raise ValidationError(
-                    f"Failed to resolve tool name '{tool_name}' to ID: {e}"
-                )
+                tool_name = tool if isinstance(tool, str) else getattr(tool, "name", str(tool))
+                raise ValidationError(f"Failed to resolve tool name '{tool_name}' to ID: {err}") from err
 
         return tool_ids
 
@@ -158,9 +144,7 @@ class ResourceValidator:
         elif hasattr(agent, "name") and agent.name is not None:
             return self._resolve_agent_by_name_attribute(agent, client)
         else:
-            raise ValidationError(
-                f"Invalid agent reference: {agent} - must have 'id' or 'name' attribute"
-            )
+            raise ValidationError(f"Invalid agent reference: {agent} - must have 'id' or 'name' attribute")
 
     def _process_single_agent(self, agent: str | Any, client: Any) -> str:
         """Process a single agent reference and return its ID."""
@@ -184,26 +168,14 @@ class ResourceValidator:
             try:
                 agent_id = cls()._process_single_agent(agent, client)
                 agent_ids.append(agent_id)
-            except (AmbiguousResourceError, NotFoundError) as e:
+            except (AmbiguousResourceError, NotFoundError) as err:
                 # Determine the agent name for the error message
-                agent_name = (
-                    agent
-                    if isinstance(agent, str)
-                    else getattr(agent, "name", str(agent))
-                )
-                raise ValidationError(
-                    f"Failed to resolve agent name '{agent_name}' to ID: {e}"
-                )
-            except Exception as e:
+                agent_name = agent if isinstance(agent, str) else getattr(agent, "name", str(agent))
+                raise ValidationError(f"Failed to resolve agent name '{agent_name}' to ID: {err}") from err
+            except Exception as err:
                 # For other exceptions, wrap them appropriately
-                agent_name = (
-                    agent
-                    if isinstance(agent, str)
-                    else getattr(agent, "name", str(agent))
-                )
-                raise ValidationError(
-                    f"Failed to resolve agent name '{agent_name}' to ID: {e}"
-                )
+                agent_name = agent if isinstance(agent, str) else getattr(agent, "name", str(agent))
+                raise ValidationError(f"Failed to resolve agent name '{agent_name}' to ID: {err}") from err
 
         return agent_ids
 
@@ -213,8 +185,8 @@ class ResourceValidator:
         for tool_id in tool_ids:
             try:
                 client.get_tool_by_id(tool_id)
-            except NotFoundError:
-                raise ValidationError(f"Tool not found: {tool_id}")
+            except NotFoundError as err:
+                raise ValidationError(f"Tool not found: {tool_id}") from err
 
     @classmethod
     def validate_agents_exist(cls, agent_ids: list[str], client: Any) -> None:
@@ -222,5 +194,5 @@ class ResourceValidator:
         for agent_id in agent_ids:
             try:
                 client.get_agent_by_id(agent_id)
-            except NotFoundError:
-                raise ValidationError(f"Agent not found: {agent_id}")
+            except NotFoundError as err:
+                raise ValidationError(f"Agent not found: {agent_id}") from err

glaip_sdk/config/constants.py

@@ -5,11 +5,7 @@ Authors:
 """
 
 # Default language model configuration
-DEFAULT_MODEL = "gpt-4.1"
-DEFAULT_MODEL_PROVIDER = "openai"
-
-# Default timeout values
-DEFAULT_TIMEOUT = 30.0
+DEFAULT_MODEL = "gpt-5-nano"
 DEFAULT_AGENT_RUN_TIMEOUT = 300
 
 # User agent and version
@@ -40,3 +36,17 @@ DEFAULT_TOOL_VERSION = "1.0"
 # MCP creation/update constants
 DEFAULT_MCP_TYPE = "server"
 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/exceptions.py

@@ -26,6 +26,15 @@ class APIError(AIPError):
         payload: Any = None,
         request_id: str | None = None,
     ):
+        """Initialize the API error.
+
+        Args:
+            message: The error message
+            status_code: HTTP status code
+            error_type: Type of error
+            payload: Additional error payload
+            request_id: Request identifier
+        """
         super().__init__(message)
         self.status_code = status_code
         self.error_type = error_type
@@ -91,16 +100,14 @@ class AgentTimeoutError(TimeoutError):
     """Agent execution timeout with specific duration information."""
 
     def __init__(self, timeout_seconds: float, agent_name: str = None):
+        """Initialize the agent timeout error.
+
+        Args:
+            timeout_seconds: The timeout duration in seconds
+            agent_name: Optional name of the agent that timed out
+        """
         agent_info = f" for agent '{agent_name}'" if agent_name else ""
-        message = (
-            f"Agent execution timed out after {timeout_seconds} seconds{agent_info}"
-        )
+        message = f"Agent execution timed out after {timeout_seconds} seconds{agent_info}"
         super().__init__(message)
         self.timeout_seconds = timeout_seconds
         self.agent_name = agent_name
-
-
-class ClientError(APIError):
-    """Client-side error (e.g., invalid request format, missing parameters)."""
-
-    pass

glaip_sdk/icons.py

@@ -0,0 +1,25 @@
+"""Lightweight icon definitions used across the CLI.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+ICON_AGENT = "🤖"
+ICON_AGENT_STEP = "🤖"
+ICON_TOOL = "🔧"
+ICON_TOOL_STEP = "🔧"
+ICON_DELEGATE = ICON_AGENT_STEP
+ICON_STATUS_SUCCESS = "✓"
+ICON_STATUS_FAILED = "✗"
+ICON_STATUS_WARNING = "⚠"
+
+__all__ = [
+    "ICON_AGENT",
+    "ICON_AGENT_STEP",
+    "ICON_TOOL",
+    "ICON_TOOL_STEP",
+    "ICON_DELEGATE",
+    "ICON_STATUS_SUCCESS",
+    "ICON_STATUS_FAILED",
+    "ICON_STATUS_WARNING",
+]

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",
+]