glaip-sdk 0.1.2__py3-none-any.whl → 0.7.17__py3-none-any.whl

glaip_sdk/mcps/base.py

@@ -0,0 +1,345 @@
+"""MCP (Model Context Protocol) helper for glaip_sdk.
+
+Provides a simple, migration-ready way to declare and resolve MCPs with
+in-memory caching and create-on-missing functionality.
+
+The MCP class also supports runtime operations (update, delete, get_tools)
+when retrieved from the API via client.mcps.get().
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+
+Example - Lazy Reference:
+    >>> from glaip_sdk.mcps import MCP
+    >>>
+    >>> # Create from known ID
+    >>> mcp = MCP.from_id("mcp_abc123")
+    >>>
+    >>> # Create lookup-only by name (error if not found)
+    >>> mcp = MCP.from_native("arxiv-search")
+    >>>
+    >>> # Create for lookup/creation by name (create if missing)
+    >>> mcp = MCP(name="my-filesystem-mcp", transport="sse", config={"url": "..."})
+
+Example - Runtime Operations:
+    >>> from glaip_sdk import Glaip
+    >>>
+    >>> client = Glaip()
+    >>> mcp = client.mcps.get("mcp-123")
+    >>> tools = mcp.get_tools()  # Get tools from MCP
+    >>> mcp.update(description="Updated description")
+    >>> mcp.delete()
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from glaip_sdk.models import MCPResponse
+
+# Type alias for MCP configuration values
+MCPConfigValue = str | int | bool | list[str] | dict[str, str]
+
+_MCP_NOT_DEPLOYED_MSG = "MCP not available on platform. No ID set."
+_CLIENT_NOT_AVAILABLE_MSG = "Client not available. Use client.mcps.get() to get a client-connected MCP."
+
+
+class MCP:
+    """MCP reference helper for declaring MCPs in Agent definitions.
+
+    Supports both lazy references and runtime operations:
+    - Lazy reference: Created via from_native() or from_id()
+    - Runtime: Created via from_response() or client.mcps.get()
+
+    Attributes:
+        name: Human-readable MCP name (used for lookup/creation).
+        id: Backend MCP ID (used for direct fetch if known).
+        transport: Transport type (e.g., "sse", "stdio", "websocket").
+        config: Transport configuration dict (URLs, args, env vars).
+        description: Optional description for the MCP.
+        metadata: Optional additional metadata dict.
+        authentication: Authentication configuration.
+
+    Example - Lazy Reference:
+        >>> # Create from known ID
+        >>> mcp = MCP.from_id("mcp_abc123")
+        >>>
+        >>> # Create lookup-only by name (error if not found)
+        >>> mcp = MCP.from_native("arxiv-search")
+        >>>
+        >>> # Create for lookup/creation by name (create if missing)
+        >>> mcp = MCP(name="my-filesystem-mcp", transport="sse", config={"url": "..."})
+
+    Example - Runtime Operations:
+        >>> mcp = client.mcps.get("mcp-123")
+        >>> mcp.update(description="New description")
+        >>> mcp.delete()
+    """
+
+    def __init__(
+        self,
+        name: str | None = None,
+        *,
+        id: str | None = None,  # noqa: A002 - Allow shadowing builtin for API compat
+        transport: str | None = None,
+        config: dict[str, MCPConfigValue] | None = None,
+        description: str | None = None,
+        metadata: dict[str, Any] | None = None,
+        authentication: dict[str, Any] | None = None,
+        _lookup_only: bool = False,
+        _client: Any = None,
+    ) -> None:
+        """Initialize an MCP.
+
+        Args:
+            name: Human-readable MCP name.
+            id: Backend MCP ID.
+            transport: Transport type (e.g., "sse", "stdio").
+            config: Transport configuration dict.
+            description: Optional description.
+            metadata: Optional metadata dict.
+            authentication: Authentication configuration.
+            _lookup_only: If True, don't create if not found.
+            _client: Internal client reference.
+
+        Raises:
+            ValueError: If neither name nor id is provided.
+        """
+        if not name and not id:
+            raise ValueError("At least one of 'name' or 'id' must be provided")
+
+        self.name = name
+        self._id = id
+        self.transport = transport
+        self.config = config
+        self.description = description
+        self.metadata = metadata
+        self.authentication = authentication
+        self._lookup_only = _lookup_only
+        self._client = _client
+
+    @property
+    def id(self) -> str | None:  # noqa: A003 - Allow shadowing builtin for API compat
+        """MCP ID on the platform."""
+        return self._id
+
+    @id.setter
+    def id(self, value: str | None) -> None:  # noqa: A003
+        """Set the MCP ID."""
+        self._id = value
+
+    def __repr__(self) -> str:
+        """Return string representation."""
+        if self._id:
+            return f"MCP(id={self._id!r}, name={self.name!r})"
+        if self._lookup_only:
+            return f"MCP.from_native({self.name!r})"
+        return f"MCP(name={self.name!r})"
+
+    def __eq__(self, other: object) -> bool:
+        """Check equality based on id if available, else name."""
+        if not isinstance(other, MCP):
+            return NotImplemented
+        if self._id and other._id:
+            return self._id == other._id
+        return self.name == other.name
+
+    def __hash__(self) -> int:
+        """Hash based on id if available, else name."""
+        if self._id:
+            return hash(self._id)
+        return hash(self.name)
+
+    def model_dump(self, *, exclude_none: bool = False) -> dict[str, Any]:
+        """Return a dict representation of the MCP.
+
+        Provides Pydantic-style serialization for backward compatibility.
+
+        Args:
+            exclude_none: If True, exclude None values from the output.
+
+        Returns:
+            Dictionary containing MCP attributes.
+        """
+        data = {
+            "id": self._id,
+            "name": self.name,
+            "transport": self.transport,
+            "config": self.config,
+            "description": self.description,
+            "metadata": self.metadata,
+            "authentication": self.authentication,
+        }
+        if exclude_none:
+            return {k: v for k, v in data.items() if v is not None}
+        return data
+
+    @classmethod
+    def from_native(cls, name: str) -> MCP:
+        """Create a lookup-only MCP reference by name.
+
+        Use this when referencing an MCP that already exists on the platform.
+        Resolution will NOT create the MCP if not found - it will raise an error.
+
+        Args:
+            name: The name of the existing MCP.
+
+        Returns:
+            MCP instance configured for lookup-only resolution.
+
+        Raises:
+            ValueError: If name is empty.
+
+        Example:
+            >>> mcp = MCP.from_native("arxiv-search")
+            >>> # Registry will find by name, error if not found or ambiguous
+        """
+        if not name:
+            raise ValueError("Name cannot be empty")
+        return cls(name=name, _lookup_only=True)
+
+    @classmethod
+    def from_id(cls, mcp_id: str) -> MCP:
+        """Create an MCP helper for lookup-only by ID.
+
+        This creates a minimal MCP reference that will be resolved
+        from the backend using the ID. Use this when you know the
+        backend MCP ID but don't have the full configuration.
+
+        Args:
+            mcp_id: The backend MCP ID.
+
+        Returns:
+            An MCP instance with only the ID set, marked for lookup-only.
+
+        Raises:
+            ValueError: If mcp_id is empty.
+
+        Example:
+            >>> mcp = MCP.from_id("550e8400-e29b-41d4-a716-446655440000")
+            >>> # Registry will fetch directly by ID
+        """
+        if not mcp_id:
+            raise ValueError("ID cannot be empty")
+        return cls(id=mcp_id, _lookup_only=True)
+
+    # ─────────────────────────────────────────────────────────────────
+    # Runtime Methods (require client connection)
+    # ─────────────────────────────────────────────────────────────────
+
+    def _set_client(self, client: Any) -> MCP:
+        """Set the client reference for this MCP.
+
+        Args:
+            client: The Glaip client instance.
+
+        Returns:
+            Self for method chaining.
+        """
+        self._client = client
+        return self
+
+    def get_tools(self) -> list[dict[str, Any]]:
+        """Get tools available from this MCP.
+
+        Returns:
+            List of tool definitions from the MCP.
+
+        Raises:
+            ValueError: If the MCP has no ID.
+            RuntimeError: If client is not available.
+        """
+        if not self._id:
+            raise ValueError(_MCP_NOT_DEPLOYED_MSG)
+        if not self._client:
+            raise RuntimeError(_CLIENT_NOT_AVAILABLE_MSG)
+
+        # Delegate to the client's MCP tools endpoint
+        return self._client.mcps.get_tools(mcp_id=self._id)
+
+    def update(self, **kwargs: Any) -> MCP:
+        """Update the MCP with new configuration.
+
+        Args:
+            **kwargs: MCP properties to update (name, description, config, etc.).
+
+        Returns:
+            Self with updated properties.
+
+        Raises:
+            ValueError: If the MCP has no ID.
+            RuntimeError: If client is not available.
+        """
+        if not self._id:
+            raise ValueError(_MCP_NOT_DEPLOYED_MSG)
+        if not self._client:
+            raise RuntimeError(_CLIENT_NOT_AVAILABLE_MSG)
+
+        response = self._client.mcps.update(mcp_id=self._id, **kwargs)
+
+        # Update local properties from response
+        if hasattr(response, "name") and response.name:
+            self.name = response.name
+        if hasattr(response, "description"):
+            self.description = response.description
+        if hasattr(response, "config"):
+            self.config = response.config
+        if hasattr(response, "transport"):
+            self.transport = response.transport
+
+        return self
+
+    def delete(self) -> None:
+        """Delete the MCP from the platform.
+
+        Raises:
+            ValueError: If the MCP has no ID.
+            RuntimeError: If client is not available.
+        """
+        if not self._id:
+            raise ValueError(_MCP_NOT_DEPLOYED_MSG)
+        if not self._client:
+            raise RuntimeError(_CLIENT_NOT_AVAILABLE_MSG)
+
+        self._client.mcps.delete(mcp_id=self._id)
+        self._id = None
+        self._client = None
+
+    @classmethod
+    def from_response(
+        cls,
+        response: MCPResponse,
+        client: Any = None,
+    ) -> MCP:
+        """Create an MCP instance from an API response.
+
+        This allows you to work with MCPs retrieved from the API
+        as full MCP instances with all methods available.
+
+        Args:
+            response: The MCPResponse from an API call.
+            client: The Glaip client instance for API operations.
+
+        Returns:
+            An MCP instance initialized from the response.
+
+        Example:
+            >>> response = client.mcps.get("mcp-123")
+            >>> mcp = MCP.from_response(response, client)
+            >>> tools = mcp.get_tools()
+        """
+        mcp = cls(
+            name=response.name,
+            id=response.id,
+            description=getattr(response, "description", None),
+            transport=getattr(response, "transport", None),
+            config=getattr(response, "config", None),
+            metadata=getattr(response, "metadata", None),
+            authentication=getattr(response, "authentication", None),
+        )
+
+        if client:
+            mcp._set_client(client)
+
+        return mcp

glaip_sdk/models/__init__.py

@@ -0,0 +1,136 @@
+# pylint: disable=duplicate-code
+"""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
+
+from glaip_sdk.models._validation import _validate_model, convert_model_for_local_execution
+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
+
+# Pure Pydantic models for API responses (no runtime methods)
+# Import model constants and validation (absolute imports)
+from glaip_sdk.models.constants import (
+    DEFAULT_MODEL,
+    Anthropic,
+    AzureOpenAI,
+    Bedrock,
+    DeepInfra,
+    DeepSeek,
+    Google,
+    ModelProvider,
+    OpenAI,
+)
+from glaip_sdk.models.mcp import MCPResponse
+from glaip_sdk.models.model import Model
+
+# Export schedule models
+from glaip_sdk.models.schedule import (  # noqa: F401
+    ScheduleConfig,
+    ScheduleMetadata,
+    ScheduleResponse,
+    ScheduleRunOutputChunk,
+    ScheduleRunResponse,
+    ScheduleRunResult,
+)
+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__ = [
+    # Model constants and validation
+    "OpenAI",
+    "Anthropic",
+    "Google",
+    "AzureOpenAI",
+    "DeepInfra",
+    "DeepSeek",
+    "Bedrock",
+    "Model",
+    "ModelProvider",
+    "DEFAULT_MODEL",
+    "_validate_model",
+    "convert_model_for_local_execution",
+    # 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",
+    # Schedule models
+    "ScheduleConfig",
+    "ScheduleMetadata",
+    "ScheduleResponse",
+    "ScheduleRunResponse",
+    "ScheduleRunOutputChunk",
+    "ScheduleRunResult",
+]

glaip_sdk/models/_provider_mappings.py

@@ -0,0 +1,101 @@
+"""Provider configuration for model name standardization.
+
+This module centralizes provider configurations, including how provider names
+map to server implementations and their base URLs for local execution.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+__all__ = ["PROVIDERS", "ProviderConfig", "get_driver", "get_base_url"]
+
+
+class ProviderConfig:
+    """Configuration for a model provider.
+
+    Defines how a provider is referenced in SDK constants and how it maps to
+    the underlying driver implementation and API endpoints.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        driver: str,
+        base_url: str | None = None,
+    ):
+        """Initialize provider configuration.
+
+        Args:
+            name: User-facing provider name used in SDK constants (e.g., "deepinfra").
+            driver: Driver implementation name in language_models.yaml (e.g., "openai-compatible").
+            base_url: Base URL for the provider's API (required for local execution).
+        """
+        self.name = name
+        self.driver = driver
+        self.base_url = base_url
+
+
+# Centralized provider configurations
+# Key: provider name (used in SDK constants)
+# Value: ProviderConfig with driver mapping and base URL
+PROVIDERS: dict[str, ProviderConfig] = {
+    "deepinfra": ProviderConfig(
+        name="deepinfra",
+        driver="openai-compatible",
+        base_url="https://api.deepinfra.com/v1/openai",
+    ),
+    "deepseek": ProviderConfig(
+        name="deepseek",
+        driver="openai-compatible",
+        base_url="https://api.deepseek.com",
+    ),
+    "custom": ProviderConfig(
+        name="custom",
+        driver="openai-compatible",
+        base_url=None,  # User-provided via Model.base_url
+    ),
+}
+
+
+def get_driver(provider: str) -> str:
+    """Get driver name for a given provider.
+
+    Maps SDK provider names to their underlying driver implementations.
+    For providers not in the config, returns the provider name unchanged
+    (assumes provider name matches driver name).
+
+    Args:
+        provider: Provider name from SDK constants (e.g., "deepinfra", "openai").
+
+    Returns:
+        Driver name (e.g., "openai-compatible" for deepinfra, "openai" for openai).
+
+    Examples:
+        >>> get_driver("deepinfra")
+        "openai-compatible"
+        >>> get_driver("openai")
+        "openai"
+    """
+    config = PROVIDERS.get(provider)
+    return config.driver if config else provider
+
+
+def get_base_url(provider: str) -> str | None:
+    """Get default base URL for a provider.
+
+    Returns the configured base URL for local execution, if available.
+
+    Args:
+        provider: Provider name from SDK constants (e.g., "deepinfra").
+
+    Returns:
+        Base URL string, or None if no config exists or no base_url configured.
+
+    Examples:
+        >>> get_base_url("deepinfra")
+        "https://api.deepinfra.com/v1/openai"
+        >>> get_base_url("openai")
+        None
+    """
+    config = PROVIDERS.get(provider)
+    return config.base_url if config else None

glaip_sdk/models/_validation.py

@@ -0,0 +1,97 @@
+"""Model validation utility for GL AIP SDK.
+
+Validates model names in 'provider/model' format and provides
+helpful error messages for invalid formats.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import warnings
+from typing import Any
+
+
+def _validate_model(model: str) -> str:
+    """Validate model format and deprecate bare names.
+
+    Args:
+        model: Model string to validate
+
+    Returns:
+        Normalized model string in provider/model format
+
+    Raises:
+        ValueError: If model format is invalid
+    """
+    if "/" not in model:
+        warnings.warn(
+            f"Bare model name '{model}' is deprecated. "
+            f"Use 'provider/model' format (e.g., 'openai/{model}'). "
+            f"This will be an error in v2.0. Use constants: from glaip_sdk.models import OpenAI",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return f"openai/{model}"
+
+    provider, model_name = model.split("/", 1)
+    if not provider or not model_name:
+        raise ValueError(
+            f"Invalid model format: '{model}'. "
+            f"Expected 'provider/model' format (e.g., 'openai/gpt-4o-mini'). "
+            f"Use constants: from glaip_sdk.models import OpenAI; Agent(model=OpenAI.GPT_4O_MINI)."
+        )
+    return model
+
+
+def convert_model_for_local_execution(model: str | Any) -> tuple[str, dict[str, Any]]:
+    """Convert model to aip_agents format for local execution.
+
+    Converts provider/model format appropriately for aip_agents.
+    Handles both Model objects and string models.
+
+    Args:
+        model: Model object or string identifier.
+
+    Returns:
+        Tuple of (model_string, config_dict) where:
+        - model_string: Model in format expected by aip_agents (provider/model)
+        - config_dict: Configuration dict with credentials, hyperparameters, etc.
+    """
+    from glaip_sdk.models import Model  # noqa: PLC0415
+
+    # Handle Model objects
+    if isinstance(model, Model):
+        return model.to_aip_agents_format()
+
+    # Handle string models
+    if isinstance(model, str):
+        if "/" not in model:
+            return model, {}
+
+        parts = model.split("/", 1)
+        provider = parts[0]
+        model_name = parts[1]
+
+        # Map provider to driver and get base_url from config
+        from glaip_sdk.models._provider_mappings import (  # noqa: PLC0415
+            get_base_url,
+            get_driver,
+        )
+
+        driver = get_driver(provider)
+        base_url = get_base_url(provider)
+
+        config: dict[str, Any] = {}
+        if base_url:
+            config["lm_base_url"] = base_url
+
+        # Return with driver name
+        return f"{driver}/{model_name}", config
+
+    # For other types (None, etc.), return as-is
+    return model, {}
+
+
+__all__ = ["_validate_model", "convert_model_for_local_execution"]