glaip-sdk 0.5.3__py3-none-any.whl → 0.6.0__py3-none-any.whl

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[MyType]):
+        ...     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.
+        """

glaip_sdk/registry/mcp.py

@@ -0,0 +1,251 @@
+"""MCP registry for glaip_sdk.
+
+This module provides the MCPRegistry that caches MCPs (Model Context Protocols)
+to avoid redundant API calls when deploying agents with MCPs.
+
+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
+from glaip_sdk.utils.resource_refs import is_uuid
+
+if TYPE_CHECKING:
+    from glaip_sdk.mcps import MCP
+
+logger = logging.getLogger(__name__)
+
+
+class MCPRegistry(BaseRegistry["MCP"]):
+    """Registry for MCPs (Model Context Protocols).
+
+    Resolves MCP references to glaip_sdk.models.MCP objects.
+    Caches results to avoid redundant API calls.
+
+    Handles:
+        - glaip_sdk.models.MCP → return as-is (uses mcp.id)
+        - String names/IDs → lookup on platform, cache, return MCP
+
+    Attributes:
+        _cache: Internal cache mapping names to MCP objects.
+
+    Example:
+        >>> registry = get_mcp_registry()
+        >>> mcp = registry.resolve("arxiv-mcp")
+        >>> print(mcp.id)
+    """
+
+    def _extract_name(self, ref: Any) -> str:
+        """Extract MCP name from a reference.
+
+        Args:
+            ref: An MCP object, dict, or string name.
+
+        Returns:
+            The extracted MCP name.
+
+        Raises:
+            ValueError: If name cannot be extracted from the reference.
+        """
+        # String name
+        if isinstance(ref, str):
+            return ref
+
+        # Dict from API response - extract name or id
+        if isinstance(ref, dict):
+            return ref.get("name") or ref.get("id") or ""
+
+        # Already resolved MCP (glaip_sdk.models.MCP)
+        if hasattr(ref, "id") and hasattr(ref, "name") and not isinstance(ref, type):
+            return ref.name or ref.id
+
+        raise ValueError(f"Cannot extract name from: {ref}")
+
+    def _resolve_and_cache(self, ref: Any, name: str) -> MCP:
+        """Resolve MCP reference - find by name/ID or create if needed.
+
+        Args:
+            ref: The MCP reference to resolve.
+            name: The extracted MCP name.
+
+        Returns:
+            The resolved glaip_sdk.models.MCP object.
+
+        Raises:
+            ValueError: If the MCP cannot be resolved.
+        """
+        # MCP object (check if already has ID)
+        if hasattr(ref, "id") and hasattr(ref, "name") and not isinstance(ref, type):
+            if ref.id is not None:
+                # Already resolved MCP with ID - just cache and return
+                logger.debug("Caching already resolved MCP: %s", name)
+                self._cache[name] = ref
+                return ref
+
+            # MCP without ID - need to look up or create
+            return self._lookup_or_create_mcp(ref, name)
+
+        # Dict from API response - use ID directly if available
+        if isinstance(ref, dict):
+            mcp_id = ref.get("id")
+            if mcp_id:
+                from glaip_sdk.mcps.base import MCP  # noqa: PLC0415
+
+                mcp = MCP(id=mcp_id, name=ref.get("name", ""))
+                self._cache[name] = mcp
+                return mcp
+            raise ValueError(f"MCP dict missing 'id': {ref}")
+
+        # String name - look up on platform
+        if isinstance(ref, str):
+            return self._lookup_mcp_by_name(name)
+
+        raise ValueError(f"Could not resolve MCP reference: {ref}")
+
+    def _lookup_or_create_mcp(self, ref: Any, name: str) -> MCP:
+        """Look up or create an MCP from a reference.
+
+        Args:
+            ref: The MCP reference with config details.
+            name: The extracted MCP name.
+
+        Returns:
+            The resolved or created glaip_sdk.models.MCP object.
+        """
+        # Check if this MCP is lookup-only (e.g., from MCP.from_native)
+        if getattr(ref, "_lookup_only", False):
+            return self._lookup_native_mcp(name)
+
+        return self._upsert_mcp_from_ref(ref, name)
+
+    def _lookup_native_mcp(self, name: str) -> MCP:
+        """Look up a native MCP that must exist on the platform.
+
+        Used for MCP.from_native() references that should not be created.
+
+        Args:
+            name: The MCP name to look up.
+
+        Returns:
+            The found MCP.
+
+        Raises:
+            ValueError: If MCP not found or multiple found.
+        """
+        from glaip_sdk.utils.client import get_client  # noqa: PLC0415
+
+        client = get_client()
+        logger.info("Looking up native MCP: %s", name)
+
+        results = client.find_mcps(name)
+        if len(results) == 1:
+            mcp = results[0]
+            self._cache[name] = mcp
+            return mcp
+        if len(results) > 1:
+            raise ValueError(f"Multiple MCPs found with name '{name}'")
+        raise ValueError(f"MCP not found on platform: {name}")
+
+    def _upsert_mcp_from_ref(self, ref: Any, name: str) -> MCP:
+        """Create or update an MCP from a reference with config.
+
+        Args:
+            ref: The MCP reference with config details.
+            name: The extracted MCP name.
+
+        Returns:
+            The created or updated MCP.
+        """
+        from glaip_sdk.utils.client import get_client  # noqa: PLC0415
+
+        client = get_client()
+        logger.info("Upserting MCP: %s", name)
+
+        mcp = client.mcps.upsert_mcp(
+            name,
+            description=getattr(ref, "description", None),
+            config=getattr(ref, "config", None),
+            transport=getattr(ref, "transport", None),
+            metadata=getattr(ref, "metadata", None),
+            authentication=getattr(ref, "authentication", None),
+        )
+        self._cache[name] = mcp
+        return mcp
+
+    def _lookup_mcp_by_name(self, name: str) -> MCP:
+        """Look up MCP by name or ID on the platform.
+
+        Args:
+            name: The MCP name or ID to look up.
+
+        Returns:
+            The resolved glaip_sdk.models.MCP object.
+
+        Raises:
+            ValueError: If the MCP cannot be found.
+        """
+        # Lazy imports to avoid circular dependency
+        from glaip_sdk.utils.client import get_client  # noqa: PLC0415
+
+        client = get_client()
+        logger.info("Looking up MCP by name: %s", name)
+
+        # Check if it's a valid UUID
+        if is_uuid(name):
+            mcp = client.get_mcp_by_id(name)
+            if mcp:
+                self._cache[name] = mcp
+                return mcp
+        else:
+            results = client.find_mcps(name)
+            if len(results) == 1:
+                mcp = results[0]
+                self._cache[name] = mcp
+                return mcp
+            if len(results) > 1:
+                raise ValueError(f"Multiple MCPs found with name '{name}'")
+
+        raise ValueError(f"MCP not found on platform: {name}")
+
+
+class _MCPRegistrySingleton:
+    """Singleton holder for MCPRegistry to avoid global statement."""
+
+    _instance: MCPRegistry | None = None
+
+    @classmethod
+    def get_instance(cls) -> MCPRegistry:
+        """Get or create the singleton instance.
+
+        Returns:
+            The global MCPRegistry instance.
+        """
+        if cls._instance is None:
+            cls._instance = MCPRegistry()
+        return cls._instance
+
+    @classmethod
+    def reset(cls) -> None:
+        """Reset the singleton instance (for testing)."""
+        cls._instance = None
+
+
+def get_mcp_registry() -> MCPRegistry:
+    """Get the singleton MCPRegistry instance.
+
+    Returns a global MCPRegistry that caches MCPs across the session.
+
+    Returns:
+        The global MCPRegistry instance.
+
+    Example:
+        >>> from glaip_sdk.registry import get_mcp_registry
+        >>> registry = get_mcp_registry()
+        >>> mcp = registry.resolve("arxiv-mcp")
+    """
+    return _MCPRegistrySingleton.get_instance()