glaip-sdk 0.1.2__py3-none-any.whl → 0.7.17__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)
@@ -99,6 +103,9 @@ class ToolClient(BaseClient):
     def _prepare_upload_data(self, name: str, framework: str, description: str | None = None, **kwargs) -> dict:
         """Prepare upload data dictionary.
 
+        Uses the same payload building logic as _build_create_payload to ensure
+        consistency between upload and metadata-only tool creation.
+
         Args:
             name: Tool name
             framework: Tool framework
@@ -108,27 +115,19 @@ class ToolClient(BaseClient):
         Returns:
             dict: Upload data dictionary
         """
-        data = {
-            "name": name,
-            "framework": framework,
-        }
-
-        if description:
-            data["description"] = description
-
-        # Handle tags if provided in kwargs
-        if kwargs.get("tags"):
-            if isinstance(kwargs["tags"], list):
-                data["tags"] = ",".join(kwargs["tags"])
-            else:
-                data["tags"] = kwargs["tags"]
+        # Extract tool_type from kwargs if present, defaulting to DEFAULT_TOOL_TYPE
+        tool_type = kwargs.pop("tool_type", DEFAULT_TOOL_TYPE)
 
-        # Include any other kwargs in the upload data
-        for key, value in kwargs.items():
-            if key not in ["tags"]:  # tags already handled above
-                data[key] = value
+        # Use _build_create_payload to build the payload consistently
+        payload = self._build_create_payload(
+            name=name,
+            description=description,
+            framework=framework,
+            tool_type=tool_type,
+            **kwargs,
+        )
 
-        return data
+        return payload
 
     def _upload_tool_file(self, file_path: str, upload_data: dict) -> Tool:
         """Upload tool file to server.
@@ -152,7 +151,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,
@@ -200,9 +200,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
 
@@ -276,6 +274,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,
@@ -432,15 +433,187 @@ class ToolClient(BaseClient):
             except OSError:
                 pass  # Ignore cleanup errors
 
-    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)
+    def update_tool(self, tool_id: str | Tool, **kwargs) -> Tool:
+        """Update an existing tool.
+
+        Notes:
+            - Payload construction is centralized via ``_build_update_payload`` to keep metadata
+              update and upload update flows consistent.
+            - Accepts either a tool ID or a ``Tool`` instance (avoids an extra fetch when callers
+              already have the current tool).
+        """
+        # Backward-compatible: allow passing a Tool instance to avoid an extra fetch.
+        if isinstance(tool_id, Tool):
+            current_tool = tool_id
+            if not current_tool.id:
+                raise ValueError("Tool instance has no id; cannot update.")
+            tool_id_value = str(current_tool.id)
+        else:
+            current_tool = None
+            tool_id_value = tool_id
+
+        if not kwargs:
+            data = self._request("PUT", f"{TOOLS_ENDPOINT}{tool_id_value}", json={})
+            response = ToolResponse(**data)
+            return Tool.from_response(response, client=self)
+
+        if current_tool is None:
+            current_tool = self.get_tool_by_id(tool_id_value)
+
+        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,
+        )
+
+        data = self._request("PUT", f"{TOOLS_ENDPOINT}{tool_id_value}", json=update_payload)
+        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)
+        name_lower = name.lower()
+        exact_matches = [tool for tool in existing if tool.name and tool.name.lower() == name_lower]
+
+        if len(exact_matches) == 1:
+            logger.info("Updating existing tool: %s", name)
+            return self._do_tool_upsert_update(exact_matches[0].id, name, code, description, framework, **kwargs)
+
+        if len(exact_matches) > 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.
 
@@ -509,8 +682,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/config/constants.py

@@ -4,8 +4,28 @@ Authors:
     Raymond Christopher (raymond.christopher@gdplabs.id)
 """
 
-# Default language model configuration
-DEFAULT_MODEL = "gpt-5-nano"
+# Lazy import cache for DEFAULT_MODEL to avoid circular dependency
+_DEFAULT_MODEL: str | None = None
+
+
+def __getattr__(name: str) -> str:
+    """Lazy import DEFAULT_MODEL from models.constants to avoid circular dependency.
+
+    Note: Prefer importing DEFAULT_MODEL directly from glaip_sdk.models.constants
+    as it is the canonical source. This re-export exists for backward compatibility.
+    """
+    if name in ("DEFAULT_MODEL", "SDK_DEFAULT_MODEL"):
+        global _DEFAULT_MODEL
+        if _DEFAULT_MODEL is None:
+            from glaip_sdk.models.constants import (  # noqa: PLC0415
+                DEFAULT_MODEL as _MODEL,
+            )
+
+            _DEFAULT_MODEL = _MODEL
+        return _DEFAULT_MODEL
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
 DEFAULT_AGENT_RUN_TIMEOUT = 300
 
 # User agent and version
@@ -39,3 +59,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/guardrails/__init__.py

@@ -0,0 +1,80 @@
+"""Guardrails package for content filtering and safety checks.
+
+This package provides modular guardrail engines and managers for filtering
+harmful content in AI agent interactions. All components support lazy loading
+from aip-agents to maintain Principle VII compliance.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from enum import StrEnum
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from aip_agents.guardrails.engines.nemo import NemoGuardrailEngine
+    from aip_agents.guardrails.engines.phrase_matcher import PhraseMatcherEngine
+    from aip_agents.guardrails.manager import GuardrailManager
+    from aip_agents.guardrails.schemas import GuardrailMode
+
+
+class ImportableName(StrEnum):
+    """Names of the importable attributes."""
+
+    GUARDRAIL_MANAGER = "GuardrailManager"
+    PHRASE_MATCHER_ENGINE = "PhraseMatcherEngine"
+    NEMO_GUARDRAIL_ENGINE = "NemoGuardrailEngine"
+    GUARDRAIL_MODE = "GuardrailMode"
+
+
+# Lazy loading support - components are only imported when actually used
+_LAZY_IMPORTS = {}
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy import to avoid eager loading of optional aip-agents dependency.
+
+    This function is called by Python when an attribute is not found in the module.
+    It performs the import from aip_agents.guardrails at runtime.
+
+    Args:
+        name: The name of the attribute to get.
+
+    Returns:
+        The attribute value from aip_agents.
+
+    Raises:
+        AttributeError: If the attribute doesn't exist.
+        ImportError: If aip-agents is not installed but a component is accessed.
+    """
+    if name in _LAZY_IMPORTS:
+        return _LAZY_IMPORTS[name]
+
+    if name == ImportableName.GUARDRAIL_MANAGER:
+        from aip_agents.guardrails.manager import GuardrailManager  # noqa: PLC0415
+
+        _LAZY_IMPORTS[name] = GuardrailManager
+        return GuardrailManager
+
+    if name == ImportableName.PHRASE_MATCHER_ENGINE:
+        from aip_agents.guardrails.engines.phrase_matcher import (  # noqa: PLC0415
+            PhraseMatcherEngine,
+        )
+
+        _LAZY_IMPORTS[name] = PhraseMatcherEngine
+        return PhraseMatcherEngine
+
+    if name == ImportableName.NEMO_GUARDRAIL_ENGINE:
+        from aip_agents.guardrails.engines.nemo import NemoGuardrailEngine  # noqa: PLC0415
+
+        _LAZY_IMPORTS[name] = NemoGuardrailEngine
+        return NemoGuardrailEngine
+
+    if name == ImportableName.GUARDRAIL_MODE:
+        from aip_agents.guardrails.schemas import GuardrailMode  # noqa: PLC0415
+
+        _LAZY_IMPORTS[name] = GuardrailMode
+        return GuardrailMode
+
+    msg = f"module {__name__!r} has no attribute {name!r}"
+    raise AttributeError(msg)

glaip_sdk/guardrails/serializer.py

@@ -0,0 +1,89 @@
+"""Guardrail serialization logic.
+
+This module provides functionality to serialize GuardrailManager and its engines
+into the JSON format expected by the GL AIP backend. This keeps the serialization
+logic within the SDK rather than polluting the core aip-agents logic.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from glaip_sdk.guardrails import (
+        GuardrailManager,
+        NemoGuardrailEngine,
+        PhraseMatcherEngine,
+    )
+
+
+def _serialize_phrase_matcher(engine: PhraseMatcherEngine) -> dict[str, Any]:
+    """Serialize a PhraseMatcherEngine configuration."""
+    config: dict[str, Any] = {}
+
+    # Extract config from BaseGuardrailEngineConfig
+    if hasattr(engine, "config") and engine.config:
+        config.update(engine.config.model_dump())
+
+    # Extract specific fields
+    if hasattr(engine, "banned_phrases"):
+        config["banned_phrases"] = engine.banned_phrases
+
+    return config
+
+
+def _serialize_nemo(engine: NemoGuardrailEngine) -> dict[str, Any]:
+    """Serialize a NemoGuardrailEngine configuration."""
+    config: dict[str, Any] = {}
+
+    # Extract config from BaseGuardrailEngineConfig
+    if hasattr(engine, "config") and engine.config:
+        config.update(engine.config.model_dump())
+
+    # Extract specific fields
+    nemo_fields = [
+        "topic_safety_mode",
+        "allowed_topics",
+        "denied_topics",
+        "include_core_restrictions",
+        "core_restriction_categories",
+        "config_dict",
+        "denial_phrases",
+    ]
+    for field in nemo_fields:
+        if hasattr(engine, field):
+            val = getattr(engine, field)
+            if val is not None:
+                config[field] = val
+
+    return config
+
+
+def serialize_guardrail_manager(manager: GuardrailManager) -> dict[str, Any]:
+    """Serialize a GuardrailManager into the backend JSON format.
+
+    Args:
+        manager: The GuardrailManager instance to serialize.
+
+    Returns:
+        A dictionary matching the agent_config.guardrails schema.
+    """
+    from glaip_sdk.guardrails import NemoGuardrailEngine, PhraseMatcherEngine  # noqa: PLC0415
+
+    engines_config = []
+
+    if hasattr(manager, "engines"):
+        for engine in manager.engines:
+            if isinstance(engine, PhraseMatcherEngine):
+                engines_config.append({"type": "phrase_matcher", "config": _serialize_phrase_matcher(engine)})
+            elif isinstance(engine, NemoGuardrailEngine):
+                engines_config.append({"type": "nemo", "config": _serialize_nemo(engine)})
+            else:
+                # Fallback for unknown engines
+                continue
+
+    enabled = getattr(manager, "enabled", True)
+    return {"enabled": enabled, "engines": engines_config}

glaip_sdk/hitl/__init__.py

@@ -0,0 +1,48 @@
+"""Human-in-the-Loop (HITL) utilities for glaip-sdk.
+
+This package provides utilities for HITL approval workflows in both local
+and remote agent execution modes.
+
+For local development, LocalPromptHandler is automatically injected when
+agent_config.hitl_enabled is True. No manual setup required.
+
+For remote execution, use RemoteHITLHandler to handle HITL events programmatically.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+    GLAIP SDK Team
+"""
+
+from typing import TYPE_CHECKING, Any
+
+# These don't require aip_agents, so import them directly
+from glaip_sdk.hitl.base import HITLCallback, HITLDecision, HITLRequest, HITLResponse
+from glaip_sdk.hitl.callback import PauseResumeCallback
+from glaip_sdk.hitl.remote import RemoteHITLHandler
+
+if TYPE_CHECKING:
+    from glaip_sdk.hitl.local import LocalPromptHandler
+
+__all__ = [
+    "LocalPromptHandler",
+    "PauseResumeCallback",
+    "HITLCallback",
+    "HITLDecision",
+    "HITLRequest",
+    "HITLResponse",
+    "RemoteHITLHandler",
+]
+
+
+def __getattr__(name: str) -> Any:  # noqa: ANN401
+    """Lazy import for LocalPromptHandler.
+
+    This defers the import of aip_agents until LocalPromptHandler is actually accessed,
+    preventing ImportError when aip-agents is not installed but HITL is not being used.
+    """
+    if name == "LocalPromptHandler":
+        from glaip_sdk.hitl.local import LocalPromptHandler  # noqa: PLC0415
+
+        globals()["LocalPromptHandler"] = LocalPromptHandler
+        return LocalPromptHandler
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

glaip_sdk/hitl/base.py

@@ -0,0 +1,64 @@
+#!/usr/bin/env python3
+"""Base types for HITL approval handling.
+
+Authors:
+    GLAIP SDK Team
+"""
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Protocol, runtime_checkable
+
+
+class HITLDecision(str, Enum):
+    """HITL decision types."""
+
+    APPROVED = "approved"
+    REJECTED = "rejected"
+    SKIPPED = "skipped"
+
+
+@dataclass
+class HITLRequest:
+    """HITL approval request from SSE stream."""
+
+    request_id: str
+    tool_name: str
+    tool_args: dict[str, Any]
+    timeout_at: str  # ISO 8601, authoritative deadline
+    timeout_seconds: int  # Informational, fallback only
+
+    # Raw metadata for advanced use cases
+    hitl_metadata: dict[str, Any]
+    tool_metadata: dict[str, Any]
+
+
+@dataclass
+class HITLResponse:
+    """HITL decision response."""
+
+    decision: HITLDecision
+    operator_input: str | None = None
+
+
+@runtime_checkable
+class HITLCallback(Protocol):
+    """Protocol for HITL approval callbacks.
+
+    Callbacks should complete within the computed callback timeout.
+    Callbacks should handle exceptions internally or let them propagate.
+    """
+
+    def __call__(self, request: HITLRequest) -> HITLResponse:
+        """Handle HITL approval request.
+
+        Args:
+            request: HITL request with tool info and metadata
+
+        Returns:
+            HITLResponse with decision and optional operator input
+
+        Raises:
+            Any exception will be caught, logged, and treated as REJECTED.
+        """
+        ...

glaip_sdk/hitl/callback.py

@@ -0,0 +1,43 @@
+"""Pause/resume callback for HITL renderer control.
+
+This module provides PauseResumeCallback which allows HITL prompt handlers
+to control the live renderer without directly coupling to the renderer implementation.
+
+Author:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from typing import Any
+
+
+class PauseResumeCallback:
+    """Simple callback object for pausing/resuming the live renderer.
+
+    This allows the LocalPromptHandler to control the renderer without
+    directly coupling to the renderer implementation.
+    """
+
+    def __init__(self) -> None:
+        """Initialize the callback."""
+        self._renderer: Any | None = None
+
+    def set_renderer(self, renderer: Any) -> None:
+        """Set the renderer instance.
+
+        Args:
+            renderer: RichStreamRenderer instance with pause_live() and resume_live() methods.
+        """
+        self._renderer = renderer
+
+    def pause(self) -> None:
+        """Pause the live renderer before prompting."""
+        if self._renderer and hasattr(self._renderer, "_shutdown_live"):
+            self._renderer._shutdown_live()
+
+    def resume(self) -> None:
+        """Resume the live renderer after prompting."""
+        if self._renderer and hasattr(self._renderer, "_ensure_live"):
+            self._renderer._ensure_live()
+
+
+__all__ = ["PauseResumeCallback"]