aip-agents-binary 0.0.0__py3-none-any.whl

aip_agents/integration/ptc.py

@@ -0,0 +1,95 @@
+"""Public PTC contracts for cross-package integrations.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING, Any, Protocol
+
+if TYPE_CHECKING:
+    from aip_agents.ptc import PromptConfig, PTCCustomToolConfig, PTCSandboxConfig
+    from aip_agents.ptc.custom_tools import (
+        PTCCustomToolValidationError,
+        PTCFileToolDef,
+        PTCPackageToolDef,
+        PTCToolDef,
+        check_name_collisions,
+        enrich_tool_def_with_metadata,
+        extract_tool_metadata,
+        validate_custom_tool_config,
+    )
+    from aip_agents.ptc.naming import sanitize_function_name
+    from aip_agents.ptc.tool_def_helpers import file_tool, package_tool
+
+
+class PromptBuilderProtocol(Protocol):
+    """Callable contract for building PTC usage guidance."""
+
+    def __call__(
+        self,
+        mcp_client: Any | None = None,
+        config: PromptConfig | None = None,
+        custom_tools_config: PTCCustomToolConfig | None = None,
+    ) -> str:
+        """Build a prompt describing the available PTC tool surface."""
+        ...
+
+
+_PTC_MODULE = "aip_agents.ptc"
+_PTC_CUSTOM_TOOLS_MODULE = "aip_agents.ptc.custom_tools"
+_PTC_NAMING_MODULE = "aip_agents.ptc.naming"
+
+_IMPORT_MAP = {
+    "PTCFileToolDef": _PTC_CUSTOM_TOOLS_MODULE,
+    "PTCPackageToolDef": _PTC_CUSTOM_TOOLS_MODULE,
+    "PTCSandboxConfig": _PTC_MODULE,
+    "PTCToolDef": _PTC_CUSTOM_TOOLS_MODULE,
+    "PTCCustomToolConfig": _PTC_MODULE,
+    "PTCCustomToolValidationError": _PTC_MODULE,
+    "PromptConfig": _PTC_MODULE,
+    "check_name_collisions": _PTC_CUSTOM_TOOLS_MODULE,
+    "enrich_tool_def_with_metadata": _PTC_MODULE,
+    "extract_tool_metadata": _PTC_MODULE,
+    "file_tool": _PTC_MODULE,
+    "package_tool": _PTC_MODULE,
+    "sanitize_function_name": _PTC_NAMING_MODULE,
+    "validate_custom_tool_config": _PTC_MODULE,
+}
+
+__all__ = [
+    "PTCFileToolDef",
+    "PTCPackageToolDef",
+    "PTCSandboxConfig",
+    "PTCToolDef",
+    "PTCCustomToolConfig",
+    "PTCCustomToolValidationError",
+    "PromptBuilderProtocol",
+    "PromptConfig",
+    "check_name_collisions",
+    "enrich_tool_def_with_metadata",
+    "extract_tool_metadata",
+    "file_tool",
+    "package_tool",
+    "sanitize_function_name",
+    "validate_custom_tool_config",
+]
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy-load public PTC contracts."""
+    module_name = _IMPORT_MAP.get(name)
+    if module_name is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    module = importlib.import_module(module_name)
+    value = getattr(module, name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    """Return module attributes for dir()."""
+    return sorted(__all__)

aip_agents/integration/skills.py

@@ -0,0 +1,37 @@
+"""Public skills contracts for cross-package integrations.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from aip_agents.skills import Skill
+
+
+_IMPORT_MAP = {
+    "Skill": "aip_agents.skills",
+}
+
+__all__ = ["Skill"]
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy-load public skills contracts."""
+    module_name = _IMPORT_MAP.get(name)
+    if module_name is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    module = importlib.import_module(module_name)
+    value = getattr(module, name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    """Return module attributes for dir()."""
+    return sorted(__all__)

aip_agents/integration/storage.py

@@ -0,0 +1,81 @@
+"""Public tool-output storage contracts for cross-package integrations.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING, Any, Protocol
+
+if TYPE_CHECKING:
+    from aip_agents.storage import (
+        InMemoryStorageProvider,
+        MinioConfig,
+        MinioObjectStorage,
+        ObjectStorageProvider,
+    )
+    from aip_agents.utils.langgraph.tool_output_management import (
+        StoreOutputParams,
+        ToolOutputConfig,
+        ToolOutputManager,
+    )
+
+
+class ToolOutputManagerProtocol(Protocol):
+    """Minimal tool-output manager contract used by local-mode integrations."""
+
+    def store_output(self, params: StoreOutputParams) -> None:
+        """Persist a tool output entry."""
+        ...
+
+    def has_outputs(self, thread_id: str | None = None) -> bool:
+        """Return whether any outputs are available."""
+        ...
+
+    def get_latest_reference(self, thread_id: str) -> str | None:
+        """Return the latest reference token for a thread."""
+        ...
+
+
+_STORAGE_MODULE = "aip_agents.storage"
+_TOOL_OUTPUT_MODULE = "aip_agents.utils.langgraph.tool_output_management"
+
+_IMPORT_MAP = {
+    "InMemoryStorageProvider": _STORAGE_MODULE,
+    "MinioConfig": _STORAGE_MODULE,
+    "MinioObjectStorage": _STORAGE_MODULE,
+    "ObjectStorageProvider": _STORAGE_MODULE,
+    "StoreOutputParams": _TOOL_OUTPUT_MODULE,
+    "ToolOutputConfig": _TOOL_OUTPUT_MODULE,
+    "ToolOutputManager": _TOOL_OUTPUT_MODULE,
+}
+
+__all__ = [
+    "InMemoryStorageProvider",
+    "MinioConfig",
+    "MinioObjectStorage",
+    "ObjectStorageProvider",
+    "StoreOutputParams",
+    "ToolOutputConfig",
+    "ToolOutputManager",
+    "ToolOutputManagerProtocol",
+]
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy-load public storage contracts."""
+    module_name = _IMPORT_MAP.get(name)
+    if module_name is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    module = importlib.import_module(module_name)
+    value = getattr(module, name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    """Return module attributes for dir()."""
+    return sorted(__all__)

aip_agents/integration/version.py

@@ -0,0 +1,103 @@
+"""Versioned metadata for the public integration facade.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+CONTRACT_NAMESPACE = "aip_agents.integration"
+
+INTEGRATION_FACADE_MODULES = (
+    "agent",
+    "guardrails",
+    "hitl",
+    "ptc",
+    "skills",
+    "storage",
+)
+
+integration_contract_version = "v1"
+
+CONTRACT_MODULES = tuple(f"{CONTRACT_NAMESPACE}.{module_name}" for module_name in INTEGRATION_FACADE_MODULES)
+
+CONTRACT_EXPORTS = {
+    "agent": (
+        "AgentInterface",
+        "AgentRunProtocol",
+        "LangGraphReactAgent",
+    ),
+    "guardrails": (
+        "GuardrailManager",
+        "GuardrailMode",
+        "NemoGuardrailEngine",
+        "PhraseMatcherEngine",
+    ),
+    "hitl": (
+        "ApprovalDecision",
+        "ApprovalDecisionType",
+        "ApprovalManager",
+        "ApprovalRequest",
+        "BasePromptHandler",
+        "PromptHandlerProtocol",
+    ),
+    "ptc": (
+        "PTCFileToolDef",
+        "PTCPackageToolDef",
+        "PTCSandboxConfig",
+        "PTCToolDef",
+        "PTCCustomToolConfig",
+        "PTCCustomToolValidationError",
+        "PromptBuilderProtocol",
+        "PromptConfig",
+        "check_name_collisions",
+        "enrich_tool_def_with_metadata",
+        "extract_tool_metadata",
+        "file_tool",
+        "package_tool",
+        "sanitize_function_name",
+        "validate_custom_tool_config",
+    ),
+    "skills": ("Skill",),
+    "storage": (
+        "InMemoryStorageProvider",
+        "MinioConfig",
+        "MinioObjectStorage",
+        "ObjectStorageProvider",
+        "StoreOutputParams",
+        "ToolOutputConfig",
+        "ToolOutputManager",
+        "ToolOutputManagerProtocol",
+    ),
+}
+
+NON_CONTRACT_SURFACE_PATTERNS = (
+    "aip_agents.agent.hitl.*",
+    "aip_agents.guardrails.engines.*",
+    "aip_agents.guardrails.manager",
+    "aip_agents.guardrails.schemas",
+    "aip_agents.ptc.custom_tools",
+    "aip_agents.ptc.naming",
+    "aip_agents.ptc.tool_def_helpers",
+    "aip_agents.storage.clients.*",
+    "aip_agents.storage.providers.*",
+    "aip_agents.utils.langgraph.tool_output_management",
+)
+
+IMPORT_MODE_ENV_VAR = "GLAIP_SDK_AIP_IMPORT_MODE"
+
+AUTO_MODE_FALLBACK_ENABLED = True
+
+INTEGRATION_MODE_STRICT = True
+
+__all__ = [
+    "AUTO_MODE_FALLBACK_ENABLED",
+    "CONTRACT_EXPORTS",
+    "CONTRACT_MODULES",
+    "CONTRACT_NAMESPACE",
+    "INTEGRATION_FACADE_MODULES",
+    "INTEGRATION_MODE_STRICT",
+    "IMPORT_MODE_ENV_VAR",
+    "NON_CONTRACT_SURFACE_PATTERNS",
+    "integration_contract_version",
+]

aip_agents/mcp/__init__.py

@@ -0,0 +1 @@
+"""Model Context Protocol related classes and functions."""

aip_agents/mcp/client/__init__.py

@@ -0,0 +1,60 @@
+"""MCP Client.
+
+This module provides a adapter client for interacting with MCP servers.
+
+Authors:
+    Fachriza Dian Adhiatma (fachriza.d.adhiatma@gdplabs.id)
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from typing import TYPE_CHECKING, Any
+
+from aip_agents.agent.google_adk_constants import GOOGLE_ADK_IMPORT_ERROR_MESSAGE
+from aip_agents.mcp.client.base_mcp_client import BaseMCPClient
+
+if TYPE_CHECKING:
+    from aip_agents.mcp.client.google_adk.client import GoogleADKMCPClient
+    from aip_agents.mcp.client.langchain.client import LangchainMCPClient
+
+__all__ = ["LangchainMCPClient", "BaseMCPClient"]
+
+if importlib.util.find_spec("google.adk") is not None:
+    __all__.append("GoogleADKMCPClient")
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy import of MCP client implementations.
+
+    This avoids importing heavy dependencies (Google ADK, Vertex AI, etc.)
+    when they are not needed.
+
+    Args:
+        name: Attribute name to import.
+
+    Returns:
+        The requested class.
+
+    Raises:
+        AttributeError: If attribute is not found.
+    """
+    if name == "GoogleADKMCPClient":
+        try:
+            from aip_agents.mcp.client.google_adk.client import (
+                GoogleADKMCPClient as _GoogleADKMCPClient,
+            )
+        except ModuleNotFoundError as e:
+            if e.name and e.name.startswith("google"):
+                raise ImportError(GOOGLE_ADK_IMPORT_ERROR_MESSAGE) from e
+            raise
+
+        return _GoogleADKMCPClient
+    elif name == "LangchainMCPClient":
+        from aip_agents.mcp.client.langchain.client import (
+            LangchainMCPClient as _LangchainMCPClient,
+        )
+
+        return _LangchainMCPClient
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")