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

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

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.
+        """