glaip-sdk 0.1.0__py3-none-any.whl → 0.6.10__py3-none-any.whl

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

@@ -4,16 +4,4 @@ Authors:
     Raymond Christopher (raymond.christopher@gdplabs.id)
 """
 
-from glaip_sdk.payload_schemas.agent import (
-    AgentImportOperation,
-    ImportFieldPlan,
-    get_import_field_plan,
-    list_server_only_fields,
-)
-
-__all__ = [
-    "AgentImportOperation",
-    "ImportFieldPlan",
-    "get_import_field_plan",
-    "list_server_only_fields",
-]
+__all__: list[str] = []

glaip_sdk/payload_schemas/agent.py

@@ -60,9 +60,7 @@ AGENT_FIELD_RULES: Mapping[str, FieldRule] = {
 }
 
 
-def get_import_field_plan(
-    field_name: str, operation: AgentImportOperation
-) -> ImportFieldPlan:
+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

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()

glaip_sdk/registry/base.py

@@ -0,0 +1,139 @@
+"""Abstract base registry for caching platform objects.
+
+This module provides the BaseRegistry abstract class that serves as the
+foundation for type-specific registries (AgentRegistry, ToolRegistry, MCPRegistry).
+
+The registry pattern provides:
+    - In-memory caching to avoid redundant API calls
+    - Transparent resolution of various reference types
+    - Simple invalidation and cache management
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import logging
+from abc import ABC, abstractmethod
+from typing import Any, Generic, TypeVar
+
+logger = logging.getLogger(__name__)
+
+
+T = TypeVar("T")
+
+
+class BaseRegistry(ABC, Generic[T]):
+    """Abstract base registry for caching platform objects.
+
+    Provides a caching layer between local code and the AIP platform.
+    Subclasses implement type-specific resolution logic.
+
+    The registry follows a simple flow:
+        1. Check if reference is already a platform object → return as-is
+        2. Extract name from reference
+        3. Check cache → return if found
+        4. Resolve via subclass logic → cache and return
+
+    Attributes:
+        _cache: Internal cache mapping names to objects.
+
+    Example:
+        >>> class MyRegistry(BaseRegistry):
+        ...     def _extract_name(self, ref: Any) -> str:
+        ...         return ref.name if hasattr(ref, 'name') else str(ref)
+        ...
+        ...     def _resolve_and_cache(self, ref: Any, name: str) -> MyType:
+        ...         obj = fetch_from_platform(name)
+        ...         self._cache[name] = obj
+        ...         return obj
+    """
+
+    def __init__(self) -> None:
+        """Initialize the registry with an empty cache."""
+        self._cache: dict[str, T] = {}
+
+    def resolve(self, ref: Any) -> T:
+        """Resolve a reference to a platform object.
+
+        This is the main entry point for the registry. It handles:
+            - Cached references (returned from cache)
+            - New references (resolved via subclass, then cached)
+
+        Args:
+            ref: A reference to resolve. Can be a class, string name,
+                or platform object depending on the registry type.
+
+        Returns:
+            The resolved platform object.
+
+        Raises:
+            ValueError: If the reference cannot be resolved.
+        """
+        name = self._extract_name(ref)
+
+        if name in self._cache:
+            logger.debug("Cache hit: %s", name)
+            return self._cache[name]
+
+        return self._resolve_and_cache(ref, name)
+
+    def get(self, name: str) -> T | None:
+        """Get a cached object by name.
+
+        Args:
+            name: The name of the object to retrieve.
+
+        Returns:
+            The cached object, or None if not found.
+        """
+        return self._cache.get(name)
+
+    def invalidate(self, name: str) -> None:
+        """Remove an object from the cache.
+
+        Use this to force a re-fetch on the next resolve call.
+
+        Args:
+            name: The name of the object to invalidate.
+        """
+        self._cache.pop(name, None)
+        logger.debug("Invalidated cache entry: %s", name)
+
+    def clear(self) -> None:
+        """Clear all cached entries."""
+        self._cache.clear()
+        logger.debug("Cleared registry cache")
+
+    @abstractmethod
+    def _extract_name(self, ref: Any) -> str:
+        """Extract the name from a reference.
+
+        Args:
+            ref: The reference to extract a name from.
+
+        Returns:
+            The extracted name string.
+
+        Raises:
+            ValueError: If name cannot be extracted.
+        """
+
+    @abstractmethod
+    def _resolve_and_cache(self, ref: Any, name: str) -> T:
+        """Resolve the reference and cache the result.
+
+        Subclasses implement type-specific resolution logic here.
+        This method MUST cache the result in self._cache[name].
+
+        Args:
+            ref: The reference to resolve.
+            name: The extracted name for caching.
+
+        Returns:
+            The resolved platform object.
+
+        Raises:
+            ValueError: If resolution fails.
+        """