glaip-sdk 0.0.0b99__py3-none-any.whl

glaip_sdk/client/validators.py

@@ -0,0 +1,198 @@
+"""Validation utilities for AIP SDK.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from typing import Any
+from uuid import UUID
+
+from glaip_sdk.exceptions import AmbiguousResourceError, NotFoundError, ValidationError
+from glaip_sdk.models import Tool
+
+
+class ResourceValidator:
+    """Validates and resolves resource references."""
+
+    RESERVED_NAMES = {
+        "research-agent",
+        "github-agent",
+        "aws-pricing-filter-generator-agent",
+    }
+
+    @classmethod
+    def is_reserved_name(cls, name: str) -> bool:
+        """Check if a name is reserved."""
+        return name in cls.RESERVED_NAMES
+
+    def _is_uuid_string(self, value: str) -> bool:
+        """Check if a string is a valid UUID."""
+        try:
+            UUID(value)
+            return True
+        except ValueError:
+            return False
+
+    def _resolve_tool_by_name(self, tool_name: str, client: Any) -> str:
+        """Resolve tool name to ID."""
+        found_tools = client.find_tools(name=tool_name)
+        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]}")
+        else:
+            raise NotFoundError(f"Tool not found: {tool_name}")
+
+    def _resolve_tool_by_name_attribute(self, tool: Tool, client: Any) -> str:
+        """Resolve tool by name attribute."""
+        found_tools = client.find_tools(name=tool.name)
+        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]}")
+        else:
+            raise NotFoundError(f"Tool not found: {tool.name}")
+
+    def _process_tool_string(self, tool: str, client: Any) -> str:
+        """Process a string tool reference."""
+        if self._is_uuid_string(tool):
+            return tool  # Already a UUID string
+        else:
+            return self._resolve_tool_by_name(tool, client)
+
+    def _process_tool_object(self, tool: Tool, client: Any) -> str:
+        """Process a Tool object reference."""
+        if hasattr(tool, "id") and tool.id is not None:
+            return str(tool.id)
+        elif isinstance(tool, UUID):
+            return str(tool)
+        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")
+
+    def _process_single_tool(self, tool: str | Tool, client: Any) -> str:
+        """Process a single tool reference and return its ID."""
+        if isinstance(tool, str):
+            return self._process_tool_string(tool, client)
+        else:
+            return self._process_tool_object(tool, client)
+
+    @classmethod
+    def extract_tool_ids(cls, tools: list[str | Tool], client: Any) -> list[str]:
+        """Extract tool IDs from a list of tool names, IDs, or Tool objects.
+
+        For agent creation, the backend expects tool IDs (UUIDs).
+        This method handles:
+        - Tool objects (extracts their ID)
+        - UUID strings (passes through)
+        - Tool names (finds tool and extracts ID)
+        """
+        tool_ids = []
+        for tool in tools:
+            try:
+                tool_id = cls()._process_single_tool(tool, client)
+                tool_ids.append(tool_id)
+            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: {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: {err}") from err
+
+        return tool_ids
+
+    def _resolve_agent_by_name(self, agent_name: str, client: Any) -> str:
+        """Resolve agent name to ID."""
+        found_agents = client.find_agents(name=agent_name)
+        if len(found_agents) == 1:
+            return str(found_agents[0].id)
+        elif len(found_agents) > 1:
+            raise AmbiguousResourceError(
+                f"Multiple agents found with name '{agent_name}': {[a.id for a in found_agents]}"
+            )
+        else:
+            raise NotFoundError(f"Agent not found: {agent_name}")
+
+    def _resolve_agent_by_name_attribute(self, agent: Any, client: Any) -> str:
+        """Resolve agent by name attribute."""
+        found_agents = client.find_agents(name=agent.name)
+        if len(found_agents) == 1:
+            return str(found_agents[0].id)
+        elif len(found_agents) > 1:
+            raise AmbiguousResourceError(
+                f"Multiple agents found with name '{agent.name}': {[a.id for a in found_agents]}"
+            )
+        else:
+            raise NotFoundError(f"Agent not found: {agent.name}")
+
+    def _process_agent_string(self, agent: str, client: Any) -> str:
+        """Process a string agent reference."""
+        if self._is_uuid_string(agent):
+            return agent  # Already a UUID string
+        else:
+            return self._resolve_agent_by_name(agent, client)
+
+    def _process_agent_object(self, agent: Any, client: Any) -> str:
+        """Process an Agent object reference."""
+        if hasattr(agent, "id") and agent.id is not None:
+            return str(agent.id)
+        elif isinstance(agent, UUID):
+            return str(agent)
+        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")
+
+    def _process_single_agent(self, agent: str | Any, client: Any) -> str:
+        """Process a single agent reference and return its ID."""
+        if isinstance(agent, str):
+            return self._process_agent_string(agent, client)
+        else:
+            return self._process_agent_object(agent, client)
+
+    @classmethod
+    def extract_agent_ids(cls, agents: list[str | Any], client: Any) -> list[str]:
+        """Extract agent IDs from a list of agent names, IDs, or agent objects.
+
+        For agent creation, the backend expects agent IDs (UUIDs).
+        This method handles:
+        - Agent objects (extracts their ID)
+        - UUID strings (passes through)
+        - Agent names (finds agent and extracts ID)
+        """
+        agent_ids = []
+        for agent in agents:
+            try:
+                agent_id = cls()._process_single_agent(agent, client)
+                agent_ids.append(agent_id)
+            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: {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: {err}") from err
+
+        return agent_ids
+
+    @classmethod
+    def validate_tools_exist(cls, tool_ids: list[str], client: Any) -> None:
+        """Validate that all tool IDs exist."""
+        for tool_id in tool_ids:
+            try:
+                client.get_tool_by_id(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:
+        """Validate that all agent IDs exist."""
+        for agent_id in agent_ids:
+            try:
+                client.get_agent_by_id(agent_id)
+            except NotFoundError as err:
+                raise ValidationError(f"Agent not found: {agent_id}") from err

glaip_sdk/config/constants.py

@@ -0,0 +1,52 @@
+"""Configuration constants for the AIP SDK.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+# Default language model configuration
+DEFAULT_MODEL = "gpt-5-nano"
+DEFAULT_AGENT_RUN_TIMEOUT = 300
+
+# User agent and version
+SDK_NAME = "glaip-sdk"
+
+# Reserved names that cannot be used for agents/tools
+RESERVED_NAMES = {
+    "system",
+    "admin",
+    "root",
+    "test",
+    "example",
+    "demo",
+    "sample",
+}
+
+# Agent creation/update constants
+DEFAULT_AGENT_TYPE = "config"
+DEFAULT_AGENT_FRAMEWORK = "langchain"
+DEFAULT_AGENT_VERSION = "1.0"
+DEFAULT_AGENT_PROVIDER = "openai"
+
+# Tool creation/update constants
+DEFAULT_TOOL_TYPE = "custom"
+DEFAULT_TOOL_FRAMEWORK = "langchain"
+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

@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+"""Custom exceptions for AIP SDK.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from typing import Any
+
+
+class AIPError(Exception):
+    """Base exception for AIP SDK."""
+
+    pass
+
+
+class APIError(AIPError):
+    """Base API exception with rich context."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        error_type: str | None = None,
+        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
+        self.payload = payload
+        self.request_id = request_id
+
+
+class AuthenticationError(APIError):
+    """Authentication failed."""
+
+    pass
+
+
+class ValidationError(APIError):
+    """Validation failed."""
+
+    pass
+
+
+class ForbiddenError(APIError):
+    """Access forbidden."""
+
+    pass
+
+
+class NotFoundError(APIError):
+    """Resource not found."""
+
+    pass
+
+
+class ConflictError(APIError):
+    """Resource conflict."""
+
+    pass
+
+
+class AmbiguousResourceError(APIError):
+    """Multiple resources match the query."""
+
+    pass
+
+
+class ServerError(APIError):
+    """Server error."""
+
+    pass
+
+
+class RateLimitError(APIError):
+    """Rate limit exceeded."""
+
+    pass
+
+
+class TimeoutError(APIError):
+    """Request timeout."""
+
+    pass
+
+
+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}"
+        super().__init__(message)
+        self.timeout_seconds = timeout_seconds
+        self.agent_name = agent_name

glaip_sdk/hitl/__init__.py

@@ -0,0 +1,15 @@
+"""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.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from glaip_sdk.hitl.local import LocalPromptHandler, PauseResumeCallback
+
+__all__ = ["LocalPromptHandler", "PauseResumeCallback"]

glaip_sdk/hitl/local.py

@@ -0,0 +1,151 @@
+"""Local HITL prompt handler with interactive console support.
+
+Author:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+import os
+from typing import Any
+
+try:
+    from aip_agents.agent.hitl.prompt.base import BasePromptHandler
+    from aip_agents.schema.hitl import ApprovalDecision, ApprovalDecisionType, ApprovalRequest
+except ImportError as e:
+    raise ImportError("aip_agents is required for local HITL. Install with: pip install 'glaip-sdk[local]'") from e
+
+from rich.console import Console
+from rich.prompt import Prompt
+
+
+class LocalPromptHandler(BasePromptHandler):
+    """Local HITL prompt handler with interactive console prompts.
+
+    Experimental local HITL implementation with known limitations:
+    - Timeouts are not enforced (interactive prompts wait indefinitely)
+    - Relies on private renderer methods for pause/resume
+    - Only supports interactive terminal environments
+
+    The key insight from Rich documentation is that Live must be stopped before
+    using Prompt/input(), otherwise the input won't render properly.
+
+    Environment variables:
+        GLAIP_HITL_AUTO_APPROVE: Set to "true" (case-insensitive) to auto-approve
+            all requests without user interaction. Useful for integration tests and CI.
+    """
+
+    def __init__(self, *, pause_resume_callback: Any | None = None) -> None:
+        """Initialize the prompt handler.
+
+        Args:
+            pause_resume_callback: Optional callable with pause() and resume() methods
+                to control the live renderer during prompts. This is needed because
+                Rich Live interferes with Prompt/input().
+        """
+        super().__init__()
+        self._pause_resume = pause_resume_callback
+        self._console = Console()
+
+    async def prompt_for_decision(
+        self,
+        request: ApprovalRequest,
+        timeout_seconds: int,
+        context_keys: list[str] | None = None,
+    ) -> ApprovalDecision:
+        """Prompt for approval decision with live renderer pause/resume.
+
+        Supports auto-approval via GLAIP_HITL_AUTO_APPROVE environment variable
+        for integration testing and CI environments. Set to "true" (case-insensitive) to enable.
+        """
+        _ = (timeout_seconds, context_keys)  # Suppress unused parameter warnings.
+
+        # Check for auto-approve mode (for integration tests/CI)
+        auto_approve = os.getenv("GLAIP_HITL_AUTO_APPROVE", "").lower() == "true"
+
+        if auto_approve:
+            # Auto-approve without user interaction
+            return ApprovalDecision(
+                request_id=request.request_id,
+                decision=ApprovalDecisionType.APPROVED,
+                operator_input="auto-approved",
+            )
+
+        # Pause the live renderer if callback is available
+        if self._pause_resume:
+            self._pause_resume.pause()
+
+        try:
+            # POC/MVP: Show what we're approving (still auto-approve for now)
+            self._print_request_info(request)
+
+            # POC/MVP: For testing, we can do actual input here
+            # Uncomment to enable real prompting:
+            response = Prompt.ask(
+                "\n[yellow]Approve this tool call?[/yellow] [dim](y/n/s)[/dim]",
+                console=self._console,
+                default="y",
+            )
+            response = response.lower().strip()
+
+            if response in ("y", "yes"):
+                decision = ApprovalDecisionType.APPROVED
+            elif response in ("n", "no"):
+                decision = ApprovalDecisionType.REJECTED
+            else:
+                decision = ApprovalDecisionType.SKIPPED
+
+            return ApprovalDecision(
+                request_id=request.request_id,
+                decision=decision,
+                operator_input=response if decision != ApprovalDecisionType.SKIPPED else None,
+            )
+        finally:
+            # Always resume the live renderer
+            if self._pause_resume:
+                self._pause_resume.resume()
+
+    def _print_request_info(self, request: ApprovalRequest) -> None:
+        """Print the approval request information."""
+        self._console.print()
+        self._console.rule("[yellow]HITL Approval Request[/yellow]", style="yellow")
+
+        tool_name = request.tool_name or "unknown"
+        self._console.print(f"[cyan]Tool:[/cyan] {tool_name}")
+
+        if hasattr(request, "arguments_preview") and request.arguments_preview:
+            self._console.print(f"[cyan]Arguments:[/cyan] {request.arguments_preview}")
+
+        if request.context:
+            self._console.print(f"[dim]Context: {request.context}[/dim]")
+
+
+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__ = ["LocalPromptHandler", "PauseResumeCallback"]

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