glaip-sdk 0.6.15b2__py3-none-any.whl → 0.6.16__py3-none-any.whl

glaip_sdk/models/__init__.py

@@ -0,0 +1,90 @@
+"""Models package for AIP SDK.
+
+This package provides Pydantic models for API responses.
+
+For the public runtime API with methods like run(), deploy(), update(), delete():
+- glaip_sdk.agents.Agent
+- glaip_sdk.tools.Tool
+- glaip_sdk.mcps.MCP
+
+The Agent, Tool, and MCP exports from this module are DEPRECATED.
+They redirect to glaip_sdk.agents.Agent, glaip_sdk.tools.Tool, glaip_sdk.mcps.MCP
+respectively with deprecation warnings.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+import warnings
+
+# Pure Pydantic models for API responses (no runtime methods)
+from glaip_sdk.models.agent import AgentResponse
+from glaip_sdk.models.agent_runs import (
+    RunOutputChunk,
+    RunsPage,
+    RunSummary,
+    RunWithOutput,
+)
+from glaip_sdk.models.common import LanguageModelResponse, TTYRenderer
+from glaip_sdk.models.mcp import MCPResponse
+from glaip_sdk.models.tool import ToolResponse
+
+
+def __getattr__(name: str) -> type:
+    """Deprecation warnings for backward compatibility."""
+    if name == "Agent":
+        warnings.warn(
+            "Importing Agent from glaip_sdk.models is deprecated. "
+            "Use 'from glaip_sdk.agents import Agent' instead. "
+            "This will be removed in v1.0.0",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        from glaip_sdk.agents import Agent  # noqa: PLC0415
+
+        return Agent
+
+    if name == "Tool":
+        warnings.warn(
+            "Importing Tool from glaip_sdk.models is deprecated. "
+            "Use 'from glaip_sdk.tools import Tool' instead. "
+            "This will be removed in v1.0.0",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        from glaip_sdk.tools import Tool  # noqa: PLC0415
+
+        return Tool
+
+    if name == "MCP":
+        warnings.warn(
+            "Importing MCP from glaip_sdk.models is deprecated. "
+            "Use 'from glaip_sdk.mcps import MCP' instead. "
+            "This will be removed in v1.0.0",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        from glaip_sdk.mcps import MCP  # noqa: PLC0415
+
+        return MCP
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    # Pure Pydantic response models (recommended for type hints)
+    "AgentResponse",
+    "ToolResponse",
+    "MCPResponse",
+    # Deprecated aliases (redirect to runtime classes with warning)
+    "Agent",
+    "Tool",
+    "MCP",
+    # Other models
+    "LanguageModelResponse",
+    "TTYRenderer",
+    "RunSummary",
+    "RunsPage",
+    "RunWithOutput",
+    "RunOutputChunk",
+]

glaip_sdk/models/agent.py

@@ -0,0 +1,47 @@
+"""Agent response model for AIP SDK.
+
+This module contains the Pydantic model for Agent API responses.
+This is a pure data model with no runtime behavior.
+
+For the runtime Agent class with deploy/run methods, use glaip_sdk.agents.Agent.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from datetime import datetime
+from typing import Any
+
+from glaip_sdk.config.constants import DEFAULT_AGENT_RUN_TIMEOUT
+from pydantic import BaseModel
+
+
+class AgentResponse(BaseModel):
+    """Pydantic model for Agent API responses.
+
+    This is a pure data model for deserializing API responses.
+    It does NOT have runtime methods (run, update, delete).
+
+    For the runtime Agent class, use glaip_sdk.agents.Agent.
+    """
+
+    id: str
+    name: str
+    instruction: str | None = None
+    description: str | None = None
+    type: str | None = None
+    framework: str | None = None
+    version: str | None = None
+    tools: list[dict[str, Any]] | None = None
+    agents: list[dict[str, Any]] | None = None
+    mcps: list[dict[str, Any]] | None = None
+    tool_configs: dict[str, Any] | None = None
+    mcp_configs: dict[str, Any] | None = None
+    agent_config: dict[str, Any] | None = None
+    timeout: int = DEFAULT_AGENT_RUN_TIMEOUT
+    metadata: dict[str, Any] | None = None
+    language_model_id: str | None = None
+    a2a_profile: dict[str, Any] | None = None
+    created_at: datetime | None = None
+    updated_at: datetime | None = None

glaip_sdk/models/agent_runs.py

@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+"""Agent run models for AIP SDK.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from datetime import datetime, timedelta
+from typing import Any, Literal
+from uuid import UUID
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+# Type alias for SSE event dictionaries
+RunOutputChunk = dict[str, Any]
+
+
+class RunSummary(BaseModel):
+    """Represents a single agent run in list/table views with metadata only."""
+
+    id: UUID
+    agent_id: UUID
+    run_type: Literal["manual", "schedule"]
+    schedule_id: UUID | None = None
+    status: Literal["started", "success", "failed", "cancelled", "aborted", "unavailable"]
+    started_at: datetime
+    completed_at: datetime | None = None
+    input: str | None = None
+    config: dict[str, Any] | None = None
+    created_at: datetime
+    updated_at: datetime
+
+    @field_validator("completed_at")
+    @classmethod
+    def validate_completed_after_started(cls, v: datetime | None, info) -> datetime | None:
+        """Validate that completed_at is after started_at if present."""
+        if v is not None and "started_at" in info.data:
+            started_at = info.data["started_at"]
+            if v < started_at:
+                raise ValueError("completed_at must be after started_at")
+        return v
+
+    def duration(self) -> timedelta | None:
+        """Calculate duration from started_at to completed_at.
+
+        Returns:
+            Duration as timedelta if completed_at exists, None otherwise
+        """
+        if self.completed_at is not None:
+            return self.completed_at - self.started_at
+        return None
+
+    def duration_formatted(self) -> str:
+        """Format duration as HH:MM:SS string.
+
+        Returns:
+            Formatted duration string or "—" if not completed
+        """
+        duration = self.duration()
+        if duration is None:
+            return "—"
+        total_seconds = int(duration.total_seconds())
+        hours = total_seconds // 3600
+        minutes = (total_seconds % 3600) // 60
+        seconds = total_seconds % 60
+        return f"{hours:02d}:{minutes:02d}:{seconds:02d}"
+
+    def input_preview(self, max_length: int = 120) -> str:
+        """Generate truncated input preview for table display.
+
+        Args:
+            max_length: Maximum length of preview string
+
+        Returns:
+            Truncated input string or "—" if input is None or empty
+        """
+        if not self.input:
+            return "—"
+        # Strip newlines and collapse whitespace
+        preview = " ".join(self.input.split())
+        if len(preview) > max_length:
+            return preview[:max_length] + "…"
+        return preview
+
+
+class RunsPage(BaseModel):
+    """Represents a paginated collection of run summaries from the list endpoint."""
+
+    data: list[RunSummary]
+    total: int = Field(ge=0)
+    page: int = Field(ge=1)
+    limit: int = Field(ge=1, le=100)
+    has_next: bool
+    has_prev: bool
+
+    @model_validator(mode="after")
+    def validate_pagination_consistency(self) -> "RunsPage":
+        """Validate pagination consistency."""
+        # If has_next is True, then page * limit < total
+        if self.has_next and self.page * self.limit >= self.total:
+            raise ValueError("has_next inconsistency: page * limit must be < total when has_next is True")
+        return self
+
+
+class RunWithOutput(RunSummary):
+    """Extends RunSummary with the complete SSE event stream for detailed viewing."""
+
+    output: list[RunOutputChunk] = Field(default_factory=list)
+
+    @field_validator("output", mode="before")
+    @classmethod
+    def normalize_output(cls, v: Any) -> list[RunOutputChunk]:
+        """Normalize output field to empty list when null."""
+        if v is None:
+            return []
+        return v

glaip_sdk/models/common.py

@@ -0,0 +1,42 @@
+"""Common models for AIP SDK.
+
+This module contains common models that don't fit into specific categories.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from pydantic import BaseModel
+
+
+class LanguageModelResponse(BaseModel):
+    """Language model response model."""
+
+    name: str
+    provider: str
+    description: str | None = None
+    capabilities: list[str] | None = None
+    max_tokens: int | None = None
+    supports_streaming: bool = False
+
+
+class TTYRenderer:
+    """Simple TTY renderer for non-Rich environments."""
+
+    def __init__(self, use_color: bool = True):
+        """Initialize the TTY renderer.
+
+        Args:
+            use_color: Whether to use color output
+        """
+        self.use_color = use_color
+
+    def render_message(self, message: str, event_type: str = "message") -> None:
+        """Render a message with optional color."""
+        if event_type == "error":
+            print(f"ERROR: {message}", flush=True)
+        elif event_type == "done":
+            print(f"\n✅ {message}", flush=True)
+        else:
+            print(message, flush=True)

glaip_sdk/models/mcp.py

@@ -0,0 +1,33 @@
+"""MCP response model for AIP SDK.
+
+This module contains the Pydantic model for MCP API responses.
+This is a pure data model with no runtime behavior.
+
+For the runtime MCP class with update/delete methods, use glaip_sdk.mcps.MCP.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class MCPResponse(BaseModel):
+    """Pydantic model for MCP API responses.
+
+    This is a pure data model for deserializing API responses.
+    It does NOT have runtime methods (update, delete, get_tools).
+
+    For the runtime MCP class, use glaip_sdk.mcps.MCP.
+    """
+
+    id: str
+    name: str
+    description: str | None = None
+    config: dict[str, Any] | None = None
+    transport: str | None = None  # "sse" or "http"
+    authentication: dict[str, Any] | None = None
+    metadata: dict[str, Any] | None = None

glaip_sdk/models/tool.py

@@ -0,0 +1,33 @@
+"""Tool response model for AIP SDK.
+
+This module contains the Pydantic model for Tool API responses.
+This is a pure data model with no runtime behavior.
+
+For the runtime Tool class with update/delete methods, use glaip_sdk.tools.Tool.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from pydantic import BaseModel
+
+
+class ToolResponse(BaseModel):
+    """Pydantic model for Tool API responses.
+
+    This is a pure data model for deserializing API responses.
+    It does NOT have runtime methods (update, delete, get_script).
+
+    For the runtime Tool class, use glaip_sdk.tools.Tool.
+    """
+
+    id: str
+    name: str
+    tool_type: str | None = None
+    description: str | None = None
+    framework: str | None = None
+    version: str | None = None
+    tool_script: str | None = None
+    tool_file: str | None = None
+    tags: str | list[str] | None = None

glaip_sdk/payload_schemas/__init__.py

@@ -0,0 +1,7 @@
+"""Payload schema metadata for AIP resources.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+__all__: list[str] = []

glaip_sdk/payload_schemas/agent.py

@@ -0,0 +1,85 @@
+"""Agent payload schema metadata derived from agent_payloads.md.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+
+This module encodes which agent fields are mutable, server-managed, or require
+additional sanitisation so that CLI and SDK flows can share the same rules.
+"""
+
+from collections.abc import Collection, Mapping
+from dataclasses import dataclass
+from typing import Literal
+
+AgentImportOperation = Literal["create", "update"]
+
+
+@dataclass(frozen=True)
+class FieldRule:
+    """Schema rule defining how a field should be treated."""
+
+    server_only: bool = False
+    cli_managed_create: bool = False
+    cli_managed_update: bool = False
+    requires_sanitization: bool = False
+
+
+@dataclass(frozen=True)
+class ImportFieldPlan:
+    """Plan for how an import pipeline should treat a specific field."""
+
+    copy: bool
+    sanitize: bool = False
+
+
+_DEFAULT_RULE = FieldRule()
+
+
+AGENT_FIELD_RULES: Mapping[str, FieldRule] = {
+    # Server-provided metadata (never send back)
+    "id": FieldRule(server_only=True),
+    "created_at": FieldRule(server_only=True),
+    "updated_at": FieldRule(server_only=True),
+    "deleted_at": FieldRule(server_only=True),
+    "success": FieldRule(server_only=True),
+    "message": FieldRule(server_only=True),
+    # Fields handled explicitly by CLI/SDK helpers for language model selection
+    "language_model_id": FieldRule(cli_managed_create=True, cli_managed_update=True),
+    "provider": FieldRule(cli_managed_create=True, cli_managed_update=True),
+    "model_name": FieldRule(cli_managed_create=True, cli_managed_update=True),
+    "model": FieldRule(cli_managed_create=True, cli_managed_update=True),
+    # Fields collected via CLI flags / explicit logic
+    "name": FieldRule(cli_managed_create=True, cli_managed_update=True),
+    "instruction": FieldRule(cli_managed_create=True, cli_managed_update=True),
+    "tools": FieldRule(cli_managed_create=True, cli_managed_update=True),
+    "agents": FieldRule(cli_managed_create=True, cli_managed_update=True),
+    "mcps": FieldRule(cli_managed_create=True, cli_managed_update=True),
+    "timeout": FieldRule(cli_managed_create=True, cli_managed_update=True),
+    # Fields requiring sanitisation before sending to the API
+    "agent_config": FieldRule(requires_sanitization=True),
+}
+
+
+def get_import_field_plan(field_name: str, operation: AgentImportOperation) -> ImportFieldPlan:
+    """Return the import handling plan for ``field_name`` under ``operation``.
+
+    Unknown fields default to being copied as-is so new API fields propagate
+    without additional code changes.
+    """
+    rule = AGENT_FIELD_RULES.get(field_name, _DEFAULT_RULE)
+
+    if rule.server_only:
+        return ImportFieldPlan(copy=False)
+
+    if operation == "create" and rule.cli_managed_create:
+        return ImportFieldPlan(copy=False)
+
+    if operation == "update" and rule.cli_managed_update:
+        return ImportFieldPlan(copy=False)
+
+    return ImportFieldPlan(copy=True, sanitize=rule.requires_sanitization)
+
+
+def list_server_only_fields() -> Collection[str]:
+    """Expose the set of server-only fields for other tooling."""
+    return {name for name, rule in AGENT_FIELD_RULES.items() if rule.server_only}

glaip_sdk/registry/__init__.py

@@ -0,0 +1,55 @@
+"""Registry package for GL AIP platform.
+
+This package provides registries that cache platform objects to avoid
+redundant API calls when deploying multi-agent systems.
+
+Example:
+    >>> from glaip_sdk.registry import get_agent_registry, get_tool_registry
+    >>> agent_registry = get_agent_registry()
+    >>> tool_registry = get_tool_registry()
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING
+
+from glaip_sdk.registry.base import BaseRegistry
+
+# Lazy imports to avoid circular dependencies
+if TYPE_CHECKING:  # pragma: no cover
+    from glaip_sdk.registry.agent import AgentRegistry, get_agent_registry
+    from glaip_sdk.registry.mcp import MCPRegistry, get_mcp_registry
+    from glaip_sdk.registry.tool import ToolRegistry, get_tool_registry
+
+__all__ = [
+    "BaseRegistry",
+    "AgentRegistry",
+    "get_agent_registry",
+    "ToolRegistry",
+    "get_tool_registry",
+    "MCPRegistry",
+    "get_mcp_registry",
+]
+
+
+def __getattr__(name: str) -> type:
+    """Lazy import to avoid circular dependencies."""
+    _agent_module = "glaip_sdk.registry.agent"
+    _tool_module = "glaip_sdk.registry.tool"
+    _mcp_module = "glaip_sdk.registry.mcp"
+
+    lazy_imports = {
+        "AgentRegistry": _agent_module,
+        "get_agent_registry": _agent_module,
+        "ToolRegistry": _tool_module,
+        "get_tool_registry": _tool_module,
+        "MCPRegistry": _mcp_module,
+        "get_mcp_registry": _mcp_module,
+    }
+
+    if name in lazy_imports:
+        module = importlib.import_module(lazy_imports[name])
+        return getattr(module, name)
+
+    raise AttributeError(f"module 'glaip_sdk.registry' has no attribute '{name}'")

glaip_sdk/registry/agent.py

@@ -0,0 +1,164 @@
+"""Agent registry for glaip_sdk.
+
+This module provides the AgentRegistry that caches deployed agents
+to avoid redundant API calls when deploying multi-agent systems.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+from glaip_sdk.registry.base import BaseRegistry
+
+if TYPE_CHECKING:
+    from glaip_sdk.agents import Agent
+
+logger = logging.getLogger(__name__)
+
+
+class AgentRegistry(BaseRegistry["Agent"]):
+    """Registry for agents.
+
+    Resolves agent references to glaip_sdk.models.Agent objects.
+    Caches results to avoid redundant API calls and duplicate deployments.
+
+    Handles:
+        - glaip_sdk.agents.Agent classes → deploy, cache, return Agent
+        - glaip_sdk.agents.Agent instances → deploy, cache, return Agent
+        - glaip_sdk.models.Agent → return as-is (uses agent.id)
+        - String names → lookup on platform, cache, return Agent
+
+    Attributes:
+        _cache: Internal cache mapping names to Agent objects.
+
+    Example:
+        >>> registry = get_agent_registry()
+        >>> agent = registry.resolve(GreeterAgent)  # Returns deployed Agent
+        >>> print(agent.id)   # "uuid-123"
+        >>> print(agent.name) # "greeter_agent"
+    """
+
+    def _extract_name(self, ref: Any) -> str:
+        """Extract agent name from a reference.
+
+        Args:
+            ref: An agent class, instance, or string name.
+
+        Returns:
+            The extracted agent name.
+
+        Raises:
+            ValueError: If name cannot be extracted from the reference.
+        """
+        # Lazy import to avoid circular dependency
+        from glaip_sdk.agents.base import Agent  # noqa: PLC0415
+
+        # Agent class
+        if isinstance(ref, type) and issubclass(ref, Agent):
+            return ref().name
+
+        # Agent instance
+        if isinstance(ref, Agent):
+            return ref.name
+
+        # Already deployed agent (glaip_sdk.models.Agent)
+        if hasattr(ref, "id") and hasattr(ref, "name") and not isinstance(ref, type):
+            return ref.name
+
+        # String name
+        if isinstance(ref, str):
+            return ref
+
+        raise ValueError(f"Cannot extract name from: {ref}")
+
+    def _resolve_and_cache(self, ref: Any, name: str) -> Agent:
+        """Resolve agent reference - deploy if class/instance, find if string.
+
+        Args:
+            ref: The agent reference to resolve.
+            name: The extracted agent name.
+
+        Returns:
+            The resolved glaip_sdk.models.Agent object.
+
+        Raises:
+            ValueError: If the agent cannot be resolved.
+        """
+        # Lazy imports to avoid circular dependency
+        from glaip_sdk.agents.base import Agent  # noqa: PLC0415
+        from glaip_sdk.utils.discovery import find_agent  # noqa: PLC0415
+
+        # Agent class
+        if isinstance(ref, type) and issubclass(ref, Agent):
+            logger.info("Deploying Agent class: %s", name)
+            deployed = ref().deploy()
+            self._cache[name] = deployed
+            return deployed
+
+        # Agent instance
+        if isinstance(ref, Agent):
+            logger.info("Deploying Agent instance: %s", name)
+            deployed = ref.deploy()
+            self._cache[name] = deployed
+            return deployed
+
+        # Already deployed agent (glaip_sdk.models.Agent) - just cache and return
+        if hasattr(ref, "id") and hasattr(ref, "name") and not isinstance(ref, type):
+            logger.debug("Caching already deployed agent: %s", name)
+            self._cache[name] = ref
+            return ref
+
+        # String name - look up on platform
+        if isinstance(ref, str):
+            logger.info("Looking up agent by name: %s", name)
+            agent = find_agent(name)
+            if agent:
+                self._cache[name] = agent
+                return agent
+            raise ValueError(f"Agent not found on platform: {name}")
+
+        raise ValueError(f"Could not resolve agent reference: {ref}")
+
+
+class _AgentRegistrySingleton:
+    """Singleton holder for AgentRegistry to avoid global statement."""
+
+    _instance: AgentRegistry | None = None
+
+    @classmethod
+    def get_instance(cls) -> AgentRegistry:
+        """Get or create the singleton instance.
+
+        Returns:
+            The global AgentRegistry instance.
+        """
+        if cls._instance is None:
+            cls._instance = AgentRegistry()
+        return cls._instance
+
+    @classmethod
+    def reset(cls) -> None:
+        """Reset the singleton instance (for testing)."""
+        cls._instance = None
+
+
+def get_agent_registry() -> AgentRegistry:
+    """Get the singleton AgentRegistry instance.
+
+    Returns a global AgentRegistry that caches agents across the session.
+    Use this function to get the registry instead of creating instances directly.
+
+    Returns:
+        The global AgentRegistry instance.
+
+    Example:
+        >>> from glaip_sdk.registry import get_agent_registry
+        >>> registry = get_agent_registry()
+        >>> agent = registry.resolve("weather_agent")
+        >>> print(agent.name)
+    """
+    return _AgentRegistrySingleton.get_instance()