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

aip_agents/sandbox/template_builder.py

@@ -0,0 +1,131 @@
+"""Template builder for PTC sandbox templates.
+
+This module provides utilities for creating and managing E2B sandbox templates
+for programmatic tool calling (PTC) environments.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from e2b import Template, default_build_logger
+
+from aip_agents.sandbox.validation import validate_package_names
+from aip_agents.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+def create_ptc_template(base_template: str, ptc_packages: list[str] | None) -> Template:
+    """Create a PTC template definition based on a base template.
+
+    Args:
+        base_template: Base template alias to build from (e.g., "code-interpreter-v1").
+        ptc_packages: List of packages to install in the template.
+            If None or empty, skips pip install step.
+
+    Returns:
+        Template: A configured template ready to be built.
+    """
+    logger.info(f"Creating template from base: {base_template}")
+    template = Template().from_template(base_template)
+
+    if ptc_packages:
+        # Validate all packages before constructing command
+        validate_package_names(ptc_packages)
+
+        # Note: packages_str is safe because ptc_packages is a controlled list from
+        # configuration, not user input. Template.run_cmd() only accepts str.
+        packages_str = " ".join(ptc_packages)
+        logger.info(f"Installing packages: {packages_str}")
+        template.run_cmd(f"pip install -q {packages_str}")
+
+    return template
+
+
+def _template_exists(template_id: str) -> bool:
+    """Check if a template alias exists.
+
+    Args:
+        template_id: The template alias to check.
+
+    Returns:
+        bool: True if alias exists, False otherwise.
+    """
+    try:
+        return Template.alias_exists(template_id)
+    except Exception:
+        logger.warning(f"Template alias check failed for: {template_id}")
+        return False
+
+
+def _build_template(template: Template, template_id: str) -> bool:
+    """Build a template with the given alias.
+
+    Args:
+        template: The template to build.
+        template_id: The alias to assign to the built template.
+
+    Returns:
+        bool: True if build succeeded, False otherwise.
+    """
+    try:
+        logger.info(f"Building template: {template_id}")
+        Template.build(
+            template,
+            alias=template_id,
+            on_build_logs=default_build_logger(),
+        )
+        logger.info(f"Template built successfully: {template_id}")
+        return True
+    except Exception as e:
+        logger.warning(f"Template build failed for {template_id}: {e}")
+        return False
+
+
+def ensure_ptc_template(
+    template_id: str,
+    base_template: str,
+    ptc_packages: list[str] | None,
+    force_rebuild: bool = False,
+) -> str | None:
+    """Ensure a PTC sandbox template exists, creating it if necessary.
+
+    This is an explicit helper that apps can call at startup to ensure the
+    template exists. It is never run implicitly by the SDK.
+
+    Args:
+        template_id: Unique alias for the template (e.g., "aip-agents-ptc-v1").
+        base_template: Base template alias to build from
+            (e.g., "code-interpreter-v1").
+        ptc_packages: List of packages to install in the template.
+            If None or empty, skips pip install step.
+        force_rebuild: If True, rebuild even if alias exists.
+
+    Returns:
+        The template_id on success, None if creation failed.
+        Never raises exceptions.
+    """
+    # Fast path: template already exists and we're not forcing rebuild
+    if not force_rebuild and _template_exists(template_id):
+        logger.info(f"Template already exists: {template_id}")
+        return template_id
+
+    # Create and build the template
+    try:
+        template = create_ptc_template(base_template, ptc_packages)
+    except Exception as e:
+        logger.warning(f"Template creation failed for {template_id}: {e}")
+        return None
+
+    # Build the template
+    is_success = _build_template(template, template_id)
+    if is_success:
+        return template_id
+
+    # Build failed. Check if template exists anyway (race condition: another
+    # process may have built it while we were trying)
+    if _template_exists(template_id):
+        logger.info(f"Template already exists after failed build: {template_id}")
+        return template_id
+
+    return None

aip_agents/sandbox/template_builder.pyi

@@ -0,0 +1,36 @@
+from _typeshed import Incomplete
+from aip_agents.sandbox.validation import validate_package_names as validate_package_names
+from aip_agents.utils.logger import get_logger as get_logger
+from e2b import Template
+
+logger: Incomplete
+
+def create_ptc_template(base_template: str, ptc_packages: list[str] | None) -> Template:
+    '''Create a PTC template definition based on a base template.
+
+    Args:
+        base_template: Base template alias to build from (e.g., "code-interpreter-v1").
+        ptc_packages: List of packages to install in the template.
+            If None or empty, skips pip install step.
+
+    Returns:
+        Template: A configured template ready to be built.
+    '''
+def ensure_ptc_template(template_id: str, base_template: str, ptc_packages: list[str] | None, force_rebuild: bool = False) -> str | None:
+    '''Ensure a PTC sandbox template exists, creating it if necessary.
+
+    This is an explicit helper that apps can call at startup to ensure the
+    template exists. It is never run implicitly by the SDK.
+
+    Args:
+        template_id: Unique alias for the template (e.g., "aip-agents-ptc-v1").
+        base_template: Base template alias to build from
+            (e.g., "code-interpreter-v1").
+        ptc_packages: List of packages to install in the template.
+            If None or empty, skips pip install step.
+        force_rebuild: If True, rebuild even if alias exists.
+
+    Returns:
+        The template_id on success, None if creation failed.
+        Never raises exceptions.
+    '''

aip_agents/sandbox/types.py

@@ -0,0 +1,24 @@
+"""Sandbox execution result types.
+
+This module defines types for sandbox execution results.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class SandboxExecutionResult:
+    """Result of a sandbox code execution.
+
+    Attributes:
+        stdout: Standard output from the execution.
+        stderr: Standard error from the execution.
+        exit_code: Exit code (0 for success, non-zero for failure).
+    """
+
+    stdout: str
+    stderr: str
+    exit_code: int

aip_agents/sandbox/types.pyi

@@ -0,0 +1,14 @@
+from dataclasses import dataclass
+
+@dataclass
+class SandboxExecutionResult:
+    """Result of a sandbox code execution.
+
+    Attributes:
+        stdout: Standard output from the execution.
+        stderr: Standard error from the execution.
+        exit_code: Exit code (0 for success, non-zero for failure).
+    """
+    stdout: str
+    stderr: str
+    exit_code: int

aip_agents/sandbox/validation.py

@@ -0,0 +1,50 @@
+"""Validation utilities for sandbox operations.
+
+This module provides validation functions for sandbox-related operations
+such as package name validation.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+import re
+
+_PACKAGE_SPEC_PATTERN = re.compile(
+    r"^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?"
+    r"(?:\[[A-Za-z0-9._-]+(?:,[A-Za-z0-9._-]+)*\])?"
+    r"(?:"
+    r"(?:==|!=|<=|>=|~=|<|>)[0-9][A-Za-z0-9.*+!_-]*"
+    r"(?:,(?:==|!=|<=|>=|~=|<|>)[0-9][A-Za-z0-9.*+!_-]*)*"
+    r")?$"
+)
+
+
+def validate_package_name(package: str) -> bool:
+    """Validate package name/specifier format for pip install.
+
+    Allows standard pip formats: package, package==version, package[extra].
+
+    Args:
+        package: Package name or specifier to validate.
+
+    Returns:
+        True if package name is valid, False otherwise.
+    """
+    if not package:
+        return False
+
+    return bool(_PACKAGE_SPEC_PATTERN.fullmatch(package))
+
+
+def validate_package_names(packages: list[str]) -> None:
+    """Validate all package names in a list.
+
+    Args:
+        packages: List of package names or specifiers to validate.
+
+    Raises:
+        ValueError: If any package name is invalid.
+    """
+    for pkg in packages:
+        if not validate_package_name(pkg):
+            raise ValueError(f"Invalid package name format: {pkg}")

aip_agents/sandbox/validation.pyi

@@ -0,0 +1,20 @@
+def validate_package_name(package: str) -> bool:
+    """Validate package name/specifier format for pip install.
+
+    Allows standard pip formats: package, package==version, package[extra].
+
+    Args:
+        package: Package name or specifier to validate.
+
+    Returns:
+        True if package name is valid, False otherwise.
+    """
+def validate_package_names(packages: list[str]) -> None:
+    """Validate all package names in a list.
+
+    Args:
+        packages: List of package names or specifiers to validate.
+
+    Raises:
+        ValueError: If any package name is invalid.
+    """

aip_agents/schema/__init__.py

@@ -0,0 +1,69 @@
+"""Central schema package for aip_agents data models."""
+
+from aip_agents.schema.a2a import A2AEvent, A2AStreamEventType, ToolCallInfo, ToolResultInfo
+from aip_agents.schema.agent import (
+    A2AClientConfig,
+    AgentConfig,
+    BaseAgentConfig,
+    CredentialType,
+    HttpxClientOptions,
+    LangflowAgentConfig,
+    StreamMode,
+)
+from aip_agents.schema.hitl import (
+    ApprovalDecision,
+    ApprovalDecisionType,
+    ApprovalLogEntry,
+    ApprovalRequest,
+    HitlMetadata,
+)
+from aip_agents.schema.langgraph import ToolCallResult, ToolStorageParams
+from aip_agents.schema.model_id import ModelId, ModelProvider
+from aip_agents.schema.step_limit import (
+    MaxDelegationDepthExceededError,
+    MaxStepsExceededError,
+    StepLimitConfig,
+    StepLimitError,
+    StepLimitErrorResponse,
+    StepLimitErrorType,
+)
+from aip_agents.schema.storage import OBJECT_STORAGE_PREFIX, StorageConfig, StorageType
+
+__all__ = [
+    # A2A
+    "A2AEvent",
+    "A2AStreamEventType",
+    "ToolCallInfo",
+    "ToolResultInfo",
+    # Agent
+    "A2AClientConfig",
+    "AgentConfig",
+    "BaseAgentConfig",
+    "CredentialType",
+    "HttpxClientOptions",
+    "LangflowAgentConfig",
+    "StreamMode",
+    # HITL
+    "ApprovalDecision",
+    "ApprovalDecisionType",
+    "ApprovalLogEntry",
+    "ApprovalRequest",
+    "HitlMetadata",
+    # LangGraph
+    "ToolCallResult",
+    "ToolStorageParams",
+    # Model
+    "ModelId",
+    "ModelProvider",
+    # Storage
+    "OBJECT_STORAGE_PREFIX",
+    "StorageConfig",
+    "StorageType",
+    # Step Limit
+    "MaxDelegationDepthExceededError",
+    "MaxStepsExceededError",
+    "StepLimitConfig",
+    "StepLimitError",
+    "StepLimitErrorResponse",
+    "StepLimitErrorType",
+]

aip_agents/schema/__init__.pyi

@@ -0,0 +1,9 @@
+from aip_agents.schema.a2a import A2AEvent as A2AEvent, A2AStreamEventType as A2AStreamEventType, ToolCallInfo as ToolCallInfo, ToolResultInfo as ToolResultInfo
+from aip_agents.schema.agent import A2AClientConfig as A2AClientConfig, AgentConfig as AgentConfig, BaseAgentConfig as BaseAgentConfig, CredentialType as CredentialType, HttpxClientOptions as HttpxClientOptions, LangflowAgentConfig as LangflowAgentConfig, StreamMode as StreamMode
+from aip_agents.schema.hitl import ApprovalDecision as ApprovalDecision, ApprovalDecisionType as ApprovalDecisionType, ApprovalLogEntry as ApprovalLogEntry, ApprovalRequest as ApprovalRequest, HitlMetadata as HitlMetadata
+from aip_agents.schema.langgraph import ToolCallResult as ToolCallResult, ToolStorageParams as ToolStorageParams
+from aip_agents.schema.model_id import ModelId as ModelId, ModelProvider as ModelProvider
+from aip_agents.schema.step_limit import MaxDelegationDepthExceededError as MaxDelegationDepthExceededError, MaxStepsExceededError as MaxStepsExceededError, StepLimitConfig as StepLimitConfig, StepLimitError as StepLimitError, StepLimitErrorResponse as StepLimitErrorResponse, StepLimitErrorType as StepLimitErrorType
+from aip_agents.schema.storage import OBJECT_STORAGE_PREFIX as OBJECT_STORAGE_PREFIX, StorageConfig as StorageConfig, StorageType as StorageType
+
+__all__ = ['A2AEvent', 'A2AStreamEventType', 'ToolCallInfo', 'ToolResultInfo', 'A2AClientConfig', 'AgentConfig', 'BaseAgentConfig', 'CredentialType', 'HttpxClientOptions', 'LangflowAgentConfig', 'StreamMode', 'ApprovalDecision', 'ApprovalDecisionType', 'ApprovalLogEntry', 'ApprovalRequest', 'HitlMetadata', 'ToolCallResult', 'ToolStorageParams', 'ModelId', 'ModelProvider', 'OBJECT_STORAGE_PREFIX', 'StorageConfig', 'StorageType', 'MaxDelegationDepthExceededError', 'MaxStepsExceededError', 'StepLimitConfig', 'StepLimitError', 'StepLimitErrorResponse', 'StepLimitErrorType']

aip_agents/schema/a2a.py

@@ -0,0 +1,56 @@
+"""A2A event schema definitions used for agent-executor communication."""
+
+from enum import Enum
+from typing import Any
+
+from typing_extensions import TypedDict
+
+__all__ = [
+    "A2AStreamEventType",
+    "A2AEvent",
+    "ToolCallInfo",
+    "ToolResultInfo",
+]
+
+
+class A2AStreamEventType(Enum):
+    """Semantic event types for A2A agent-executor communication."""
+
+    STATUS_UPDATE = "status_update"
+    CONTENT_CHUNK = "content_chunk"
+    FINAL_RESPONSE = "final_response"
+    TOOL_CALL = "tool_call"
+    TOOL_RESULT = "tool_result"
+    ERROR = "error"
+    STEP_LIMIT_EXCEEDED = "step_limit_exceeded"
+
+
+class A2AEvent(TypedDict):
+    """Structured event data used by the A2A connector."""
+
+    event_type: A2AStreamEventType
+    content: str
+    metadata: dict[str, Any]
+    tool_info: dict[str, Any] | None
+    is_final: bool
+    artifacts: list[dict[str, Any]] | None
+    references: list[Any] | None
+    step_usage: dict[str, Any] | None
+    total_usage: dict[str, Any] | None
+    thinking_and_activity_info: dict[str, Any] | None
+
+
+class ToolCallInfo(TypedDict):
+    """Structured information for tool invocation events."""
+
+    tool_calls: list[dict[str, Any]]
+    status: str
+
+
+class ToolResultInfo(TypedDict):
+    """Structured information for tool completion events."""
+
+    name: str
+    args: dict[str, Any]
+    output: str
+    execution_time: float | None

aip_agents/schema/a2a.pyi

@@ -0,0 +1,40 @@
+from enum import Enum
+from typing import Any
+from typing_extensions import TypedDict
+
+__all__ = ['A2AStreamEventType', 'A2AEvent', 'ToolCallInfo', 'ToolResultInfo']
+
+class A2AStreamEventType(Enum):
+    """Semantic event types for A2A agent-executor communication."""
+    STATUS_UPDATE: str
+    CONTENT_CHUNK: str
+    FINAL_RESPONSE: str
+    TOOL_CALL: str
+    TOOL_RESULT: str
+    ERROR: str
+    STEP_LIMIT_EXCEEDED: str
+
+class A2AEvent(TypedDict):
+    """Structured event data used by the A2A connector."""
+    event_type: A2AStreamEventType
+    content: str
+    metadata: dict[str, Any]
+    tool_info: dict[str, Any] | None
+    is_final: bool
+    artifacts: list[dict[str, Any]] | None
+    references: list[Any] | None
+    step_usage: dict[str, Any] | None
+    total_usage: dict[str, Any] | None
+    thinking_and_activity_info: dict[str, Any] | None
+
+class ToolCallInfo(TypedDict):
+    """Structured information for tool invocation events."""
+    tool_calls: list[dict[str, Any]]
+    status: str
+
+class ToolResultInfo(TypedDict):
+    """Structured information for tool completion events."""
+    name: str
+    args: dict[str, Any]
+    output: str
+    execution_time: float | None

aip_agents/schema/agent.py

@@ -0,0 +1,111 @@
+"""Schema definitions for agent configuration types."""
+
+from enum import StrEnum
+from typing import Any
+
+from a2a.types import AgentCard
+from gllm_core.utils.retry import RetryConfig
+from pydantic import BaseModel, Field
+
+try:
+    # Pydantic v2 preferred config
+    from pydantic import ConfigDict  # type: ignore
+except Exception:  # pragma: no cover
+    ConfigDict = None  # type: ignore
+
+__all__ = [
+    "CredentialType",
+    "StreamMode",
+    "HttpxClientOptions",
+    "A2AClientConfig",
+    "BaseAgentConfig",
+    "AgentConfig",
+    "LangflowAgentConfig",
+]
+
+
+class CredentialType(StrEnum):
+    """Credential type enumeration for type safety and better developer experience."""
+
+    API_KEY = "api_key"
+    FILE = "file"
+    DICT = "dict"
+
+
+class StreamMode(StrEnum):
+    """LangGraph stream modes for astream operations."""
+
+    VALUES = "values"
+    CUSTOM = "custom"
+    MESSAGES = "messages"
+
+
+class HttpxClientOptions(BaseModel):
+    """Options for the HTTP client."""
+
+    timeout: float = 360.0
+    trust_env: bool = False
+    follow_redirects: bool = True
+
+    if ConfigDict is not None:
+        # Pydantic v2 style config
+        model_config = ConfigDict(extra="allow")  # type: ignore[assignment]
+    else:  # pragma: no cover
+
+        class Config:  # type: ignore[no-redef]
+            """Pydantic v1 fallback config for HttpxClientOptions."""
+
+            extra = "allow"
+
+
+class A2AClientConfig(BaseModel):
+    """Configuration for A2A client."""
+
+    discovery_urls: list[str] | None = None
+    known_agents: dict[str, AgentCard] = Field(default_factory=dict)
+    httpx_client_options: HttpxClientOptions | None = HttpxClientOptions()
+
+
+class BaseAgentConfig(BaseModel):
+    """Base configuration for agent implementations."""
+
+    tools: list[Any] | None = None
+    default_hyperparameters: dict[str, Any] | None = None
+
+    if ConfigDict is not None:
+        model_config = ConfigDict(extra="allow")  # type: ignore[assignment]
+    else:  # pragma: no cover
+
+        class Config:  # type: ignore[no-redef]
+            """Pydantic v1 fallback config for BaseAgentConfig."""
+
+            extra = "allow"
+
+
+class AgentConfig(BaseAgentConfig):
+    """Configuration for agent implementations with language model settings."""
+
+    lm_name: str | None = None
+    lm_hyperparameters: dict[str, Any] | None = None
+    lm_provider: str | None = None
+    lm_base_url: str | None = None
+    lm_api_key: str | None = None
+    lm_credentials: str | dict[str, Any] | None = None
+    lm_retry_config: RetryConfig | None = None
+
+
+class LangflowAgentConfig(BaseAgentConfig):
+    """Configuration for Langflow agent implementations."""
+
+    flow_id: str
+    base_url: str | None = None
+    api_key: str | None = None
+
+    if ConfigDict is not None:
+        model_config = ConfigDict(extra="allow")  # type: ignore[assignment]
+    else:  # pragma: no cover
+
+        class Config:  # type: ignore[no-redef]
+            """Pydantic v1 fallback config for LangflowAgentConfig."""
+
+            extra = "allow"

aip_agents/schema/agent.pyi

@@ -0,0 +1,65 @@
+from _typeshed import Incomplete
+from a2a.types import AgentCard
+from enum import StrEnum
+from gllm_core.utils.retry import RetryConfig
+from pydantic import BaseModel
+from typing import Any
+
+__all__ = ['CredentialType', 'StreamMode', 'HttpxClientOptions', 'A2AClientConfig', 'BaseAgentConfig', 'AgentConfig', 'LangflowAgentConfig']
+
+class CredentialType(StrEnum):
+    """Credential type enumeration for type safety and better developer experience."""
+    API_KEY: str
+    FILE: str
+    DICT: str
+
+class StreamMode(StrEnum):
+    """LangGraph stream modes for astream operations."""
+    VALUES: str
+    CUSTOM: str
+    MESSAGES: str
+
+class HttpxClientOptions(BaseModel):
+    """Options for the HTTP client."""
+    timeout: float
+    trust_env: bool
+    follow_redirects: bool
+    model_config: Incomplete
+    class Config:
+        """Pydantic v1 fallback config for HttpxClientOptions."""
+        extra: str
+
+class A2AClientConfig(BaseModel):
+    """Configuration for A2A client."""
+    discovery_urls: list[str] | None
+    known_agents: dict[str, AgentCard]
+    httpx_client_options: HttpxClientOptions | None
+
+class BaseAgentConfig(BaseModel):
+    """Base configuration for agent implementations."""
+    tools: list[Any] | None
+    default_hyperparameters: dict[str, Any] | None
+    model_config: Incomplete
+    class Config:
+        """Pydantic v1 fallback config for BaseAgentConfig."""
+        extra: str
+
+class AgentConfig(BaseAgentConfig):
+    """Configuration for agent implementations with language model settings."""
+    lm_name: str | None
+    lm_hyperparameters: dict[str, Any] | None
+    lm_provider: str | None
+    lm_base_url: str | None
+    lm_api_key: str | None
+    lm_credentials: str | dict[str, Any] | None
+    lm_retry_config: RetryConfig | None
+
+class LangflowAgentConfig(BaseAgentConfig):
+    """Configuration for Langflow agent implementations."""
+    flow_id: str
+    base_url: str | None
+    api_key: str | None
+    model_config: Incomplete
+    class Config:
+        """Pydantic v1 fallback config for LangflowAgentConfig."""
+        extra: str