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

aip_agents/sandbox/template_builder.py

@@ -0,0 +1,240 @@
+"""Template policy for sandbox templates.
+
+This module owns the *aip-agents* template policy and a thin orchestration
+wrapper that delegates the generic build mechanics to gllm-tools'
+``E2BTemplateBuilder``.
+
+Two build inputs are supported, selected at runtime:
+
+- **Image registry (preferred).** When ``AIP_SANDBOX_IMAGE_REGISTRY`` is set, the
+  template is built from a prebuilt image (see ``image_registry``).
+- **Dockerfile (DEPRECATED — legacy fallback).** When the image registry is not
+  configured, the build falls back to the packaged ``dockerfiles/*.Dockerfile``.
+  This path and the packaged Dockerfiles are slated for removal once image-based
+  building is validated in production; do not extend it.
+
+The generic E2B build primitives now live in
+``gllm_tools.code_interpreter.code_template``; aip-agents no longer imports the
+base ``e2b`` package directly.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+import shlex
+from pathlib import Path
+
+from aip_agents.sandbox import image_registry
+from aip_agents.sandbox.defaults import DEFAULT_SANDBOX_TEMPLATE
+from aip_agents.sandbox.validation import validate_package_names
+from aip_agents.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+# DEPRECATED: packaged Dockerfile build path. Kept as a gated fallback for
+# environments without an image registry; remove with the packaged Dockerfiles
+# once image-based building is proven in production.
+DEFAULT_SANDBOX_DOCKERFILE_RELATIVE_PATH = Path("dockerfiles/aip-agents-sandbox-v2-3.Dockerfile")
+
+
+class DockerfileNotFoundError(ValueError):
+    """Raised when no packaged Dockerfile matches a requested template alias.
+
+    DEPRECATED: part of the legacy Dockerfile build path.
+    """
+
+
+def get_default_sandbox_dockerfile_path() -> Path:
+    """Return the absolute path to the packaged default sandbox Dockerfile.
+
+    DEPRECATED: legacy Dockerfile build path; superseded by the image registry
+    (``AIP_SANDBOX_IMAGE_REGISTRY``). Slated for removal once image-based
+    building is validated.
+    """
+    return Path(__file__).resolve().parent / DEFAULT_SANDBOX_DOCKERFILE_RELATIVE_PATH
+
+
+def get_sandbox_dockerfile_path(template_id: str) -> Path:
+    """Resolve the packaged Dockerfile path for a sandbox template alias.
+
+    DEPRECATED: legacy Dockerfile build path; superseded by the image registry
+    (``AIP_SANDBOX_IMAGE_REGISTRY``). Slated for removal once image-based
+    building is validated.
+
+    Args:
+        template_id: The template alias to resolve.
+
+    Returns:
+        Absolute Dockerfile path for the alias.
+
+    Raises:
+        DockerfileNotFoundError: If no packaged Dockerfile matches ``template_id``.
+    """
+    default_dockerfile = get_default_sandbox_dockerfile_path()
+    if template_id == DEFAULT_SANDBOX_TEMPLATE:
+        return default_dockerfile
+
+    candidate = default_dockerfile.parent / f"{template_id}.Dockerfile"
+    if candidate.is_file():
+        return candidate
+
+    raise DockerfileNotFoundError(f"No template-specific Dockerfile found for {template_id!r}. Expected: {candidate}")
+
+
+def _load_code_template_builder() -> tuple[type, type]:
+    """Load the gllm-tools template builder classes only when needed."""
+    from gllm_tools.code_interpreter.code_template import TemplateSpec
+    from gllm_tools.code_interpreter.code_template.e2b_template_builder import (
+        E2BTemplateBuilder,
+    )
+
+    return TemplateSpec, E2BTemplateBuilder
+
+
+def ensure_sandbox_template(
+    template_id: str,
+    base_template: str,
+    packages: list[str] | None,
+    force_rebuild: bool = False,
+    dockerfile: str | Path | None = None,
+) -> str | None:
+    """Ensure a 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. The generic build
+    mechanics are delegated to gllm-tools' ``E2BTemplateBuilder``; this wrapper
+    keeps the aip-agents policy (package validation) and the historical
+    string-or-``None`` return shape.
+
+    Build input is selected at runtime: when ``AIP_SANDBOX_IMAGE_REGISTRY`` is
+    set, the template is built from the resolved registry image; otherwise it
+    falls back to the **deprecated** Dockerfile path (the ``dockerfile`` arg or
+    ``base_template``).
+
+    Template building requires the base ``e2b`` package, provided transitively by
+    gllm-tools' sandbox support; the ``E2BTemplateBuilder`` import below raises
+    an actionable ``ImportError`` when it is absent.
+
+    Args:
+        template_id: Unique alias for the template (e.g., "aip-agents-sandbox-v2").
+        base_template: Base template alias to build from
+            (e.g., "code-interpreter-v1").
+        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.
+        dockerfile: Optional Dockerfile path used to create template via
+            ``from_dockerfile``. DEPRECATED: ignored when the image registry is
+            configured.
+
+    Returns:
+        The template_id on success, None if creation failed.
+        Never raises (apart from a missing-``e2b`` ImportError).
+    """
+    # Pre-validate packages here (aip-agents policy); the library treats the list
+    # as trusted. Keep the never-raises contract by mapping a validation error to
+    # a None result. Note: validation now runs ahead of the library's
+    # "already usable" fast path, so an already-built template re-requested with a
+    # now-invalid package list returns None rather than its existing alias.
+    if packages:
+        try:
+            validate_package_names(packages)
+        except Exception as e:
+            logger.warning(f"Package validation failed for {template_id}: {e}")
+            return None
+
+    if image_registry.resolve_image_ref() is not None:
+        try:
+            _, builder_type = _load_code_template_builder()
+        except ModuleNotFoundError as exc:
+            # Keep a stable failure mode for optional dependency availability:
+            # tests assert this remains an actionable e2b requirement error.
+            raise ImportError("'e2b' package is required to build sandbox templates") from exc
+
+        try:
+            spec = image_registry.build_spec(template_id, packages=packages, force_rebuild=force_rebuild)
+        except Exception as e:
+            logger.warning(f"Image-registry template config failed for {template_id}: {e}")
+            return None
+        result = builder_type().ensure(spec)
+    else:
+        # DEPRECATED: legacy Dockerfile build path. Remove once image-based
+        # building is validated in production.
+        logger.warning(
+            "Building sandbox template %r via the deprecated Dockerfile path (AIP_SANDBOX_IMAGE_REGISTRY not set).",
+            template_id,
+        )
+        if dockerfile is not None:
+            return _ensure_e2b_dockerfile_template(
+                template_id=template_id,
+                packages=packages,
+                force_rebuild=force_rebuild,
+                dockerfile=Path(dockerfile),
+            )
+
+        try:
+            template_spec_type, builder_type = _load_code_template_builder()
+        except ModuleNotFoundError as exc:
+            # Keep a stable failure mode for optional dependency availability:
+            # tests assert this remains an actionable e2b requirement error.
+            raise ImportError("'e2b' package is required to build sandbox templates") from exc
+
+        spec = template_spec_type(
+            template_id=template_id,
+            base_template=base_template,
+            packages=packages,
+            dockerfile=None,
+            force_rebuild=force_rebuild,
+        )
+        result = builder_type().ensure(spec)
+    # gllm-tools now returns a provider-tagged ``TemplateRef`` (None on failure);
+    # unwrap to the E2B alias string to keep this wrapper's historical contract.
+    return result.template_ref.value if result.template_ref is not None else None
+
+
+def _ensure_e2b_dockerfile_template(
+    template_id: str,
+    packages: list[str] | None,
+    force_rebuild: bool,
+    dockerfile: Path,
+) -> str | None:
+    """Build an E2B alias from a Dockerfile path with its directory as context.
+
+    E2B's deprecated ``Template().from_dockerfile(path)`` parser keeps COPY
+    sources relative to ``Template(file_context_path=...)``, not automatically
+    relative to the Dockerfile path. The generic gllm-tools wrapper currently
+    constructs ``Template()`` without that context, so aip-agents owns the
+    path-based Dockerfile branch until the generic wrapper grows first-class
+    context support.
+    """
+    from e2b import Template, default_build_logger
+
+    _, builder_type = _load_code_template_builder()
+
+    builder = builder_type()
+    if not force_rebuild and builder.is_usable(template_id):
+        return template_id
+
+    dockerfile_path = dockerfile.resolve()
+
+    try:
+        template = Template(file_context_path=dockerfile_path.parent).from_dockerfile(str(dockerfile_path))
+        if packages:
+            packages_str = " ".join(shlex.quote(package) for package in packages)
+            template = template.run_cmd(f"pip install -q {packages_str}")
+        Template.build(template, alias=template_id, on_build_logs=default_build_logger())
+        return template_id
+    except Exception as e:  # pragma: no cover
+        logger.warning(f"E2B Dockerfile template build failed for {template_id}: {e}")  # pragma: no cover
+        if not force_rebuild and builder.is_usable(template_id):  # pragma: no cover
+            return template_id  # pragma: no cover
+        return None  # pragma: no cover
+
+
+def ensure_ptc_template(
+    template_id: str,
+    base_template: str,
+    ptc_packages: list[str] | None,
+    force_rebuild: bool = False,
+) -> str | None:
+    """Deprecated: Use ensure_sandbox_template instead."""
+    return ensure_sandbox_template(template_id, base_template, ptc_packages, force_rebuild=force_rebuild)

aip_agents/sandbox/types.py

@@ -0,0 +1,141 @@
+"""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, field
+from typing import Any, TypeAlias, cast
+
+from langchain_core.messages.ai import UsageMetadata
+
+from aip_agents.utils.logger import get_logger
+from aip_agents.utils.token_usage_helper import add_usage_metadata
+
+logger = get_logger(__name__)
+
+JSONValue: TypeAlias = None | bool | int | float | str | list["JSONValue"] | dict[str, "JSONValue"]
+
+_USAGE_TOKEN_KEYS = ("input_tokens", "output_tokens", "total_tokens")
+_USAGE_DETAIL_KEYS = ("input_token_details", "output_token_details")
+
+
+def _is_usage_number(value: JSONValue) -> bool:
+    """Return whether a structured-output token value is safely additive."""
+    return isinstance(value, int | float) and not isinstance(value, bool)
+
+
+def _validated_usage_metadata(value: JSONValue | None) -> UsageMetadata | None:
+    """Return validated UsageMetadata or None when a sandbox payload is malformed."""
+    if not isinstance(value, dict):
+        return None
+
+    for key in _USAGE_TOKEN_KEYS:
+        if not _is_usage_number(value.get(key)):
+            logger.warning(f"Skipping malformed usage_metadata (expected numeric {key})")
+            return None
+
+    validated: dict[str, Any] = {key: value[key] for key in _USAGE_TOKEN_KEYS}
+    for key in _USAGE_DETAIL_KEYS:
+        details = value.get(key)
+        if details is None:
+            continue
+        if not isinstance(details, dict) or any(
+            not _is_usage_number(detail_value) for detail_value in details.values()
+        ):
+            logger.warning(f"Skipping malformed usage_metadata (expected numeric {key} values)")
+            return None
+        validated[key] = details  # pragma: no cover
+    return cast(UsageMetadata, validated)
+
+
+@dataclass
+class PTCStructuredOutput:
+    """Supported structured updates emitted by sandboxed PTC custom tools."""
+
+    metadata: dict[str, JSONValue] = field(default_factory=dict)
+    artifacts: list[JSONValue] = field(default_factory=list)
+    pii_mapping: dict[str, JSONValue] = field(default_factory=dict)
+    usage_metadata: dict[str, JSONValue] = field(default_factory=dict)
+    warnings: list[str] = field(default_factory=list)
+
+    def has_updates(self) -> bool:
+        """Return True when at least one supported update field is present."""
+        return bool(self.metadata or self.artifacts or self.pii_mapping or self.usage_metadata or self.warnings)
+
+    def merge(self, update: dict[str, JSONValue]) -> None:
+        """Merge one supported update using ToolExecutionEngine-compatible semantics."""
+        metadata = update.get("metadata")
+        if isinstance(metadata, dict):
+            self.metadata.update(metadata)
+
+        artifacts = update.get("artifacts")
+        if isinstance(artifacts, list):
+            self.artifacts.extend(artifacts)
+
+        pii_mapping = update.get("pii_mapping")
+        if isinstance(pii_mapping, dict):
+            # Only accept str->str entries. Downstream masking sorts and matches on
+            # value length/content, so a non-string tag or value would poison every
+            # later anonymization call.
+            for tag, value in pii_mapping.items():
+                if isinstance(tag, str) and isinstance(value, str):
+                    self.pii_mapping[tag] = value
+                else:
+                    logger.warning(f"Skipping malformed pii_mapping entry (expected str->str): {tag!r} -> {value!r}")
+
+        usage_metadata = _validated_usage_metadata(update.get("usage_metadata"))
+        if usage_metadata is not None:
+            current_usage = cast(UsageMetadata | None, self.usage_metadata or None)
+            self.usage_metadata = cast(dict[str, JSONValue], add_usage_metadata(current_usage, usage_metadata) or {})
+
+        warnings = update.get("warnings")
+        if isinstance(warnings, list):
+            self.warnings.extend(warning for warning in warnings if isinstance(warning, str))  # pragma: no cover
+
+    def add_warning(self, warning: str) -> None:
+        """Record a caller-visible non-fatal structured-output warning."""
+        self.warnings.append(warning)
+
+    def to_command_update(self) -> dict[str, JSONValue]:
+        """Return only populated supported fields for an outer Command.update."""
+        update: dict[str, JSONValue] = {}
+        if self.metadata:
+            update["metadata"] = self.metadata
+        if self.artifacts:
+            update["artifacts"] = self.artifacts
+        if self.pii_mapping:
+            update["pii_mapping"] = self.pii_mapping
+        if self.usage_metadata:
+            update["usage_metadata"] = self.usage_metadata
+        if self.warnings:
+            update["warnings"] = cast(JSONValue, list(self.warnings))
+        return update
+
+
+@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).
+        timed_out: Whether the sandbox runtime reported an execution timeout.
+        execution_backend: Runtime backend that executed the code or command.
+        timeout_source: Specific timeout layer when known.
+        timeout_seconds: Timeout value enforced by that layer when known.
+        diagnostics: Extra machine-readable execution diagnostics.
+    """
+
+    stdout: str
+    stderr: str
+    exit_code: int
+    structured_output: PTCStructuredOutput = field(default_factory=PTCStructuredOutput)
+    timed_out: bool = False
+    execution_backend: str | None = None
+    timeout_source: str | None = None
+    timeout_seconds: float | None = None
+    diagnostics: dict[str, Any] = field(default_factory=dict)

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/schema/__init__.py

@@ -0,0 +1,106 @@
+"""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.artifacts import (
+    ArtifactBuildError,
+    ArtifactPayload,
+    ToolArtifactResponse,
+    ToolMultiArtifactResponse,
+    TrackedArtifact,
+)
+from aip_agents.schema.attachments import AttachmentEntryPayload
+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.model_usage import ModelUsageDelta, ModelUsageRow
+from aip_agents.schema.runtime_metadata import (
+    LocalizedMessages,
+    RuntimeMetadata,
+)
+from aip_agents.schema.step_limit import (
+    MaxDelegationDepthExceededError,
+    MaxStepsExceededError,
+    StepLimitConfig,
+    StepLimitError,
+    StepLimitErrorResponse,
+    StepLimitErrorType,
+)
+from aip_agents.schema.storage import OBJECT_STORAGE_PREFIX, StorageConfig, StorageType
+from aip_agents.schema.tool_payloads import (
+    ToolArgs,
+    ToolInvocationPayload,
+    ToolOutputStorageStats,
+    ToolOutputSummaryEntry,
+)
+
+__all__ = [
+    # A2A
+    "A2AEvent",
+    "A2AStreamEventType",
+    "ToolCallInfo",
+    "ToolResultInfo",
+    # Agent
+    "A2AClientConfig",
+    "AgentConfig",
+    "BaseAgentConfig",
+    "CredentialType",
+    "HttpxClientOptions",
+    "LangflowAgentConfig",
+    "StreamMode",
+    # Artifacts
+    "ArtifactBuildError",
+    "ArtifactPayload",
+    "ToolArtifactResponse",
+    "ToolMultiArtifactResponse",
+    "TrackedArtifact",
+    # Attachments
+    "AttachmentEntryPayload",
+    # HITL
+    "ApprovalDecision",
+    "ApprovalDecisionType",
+    "ApprovalLogEntry",
+    "ApprovalRequest",
+    "HitlMetadata",
+    # LangGraph
+    "ToolCallResult",
+    "ToolStorageParams",
+    # Model
+    "ModelId",
+    "ModelProvider",
+    "ModelUsageDelta",
+    "ModelUsageRow",
+    # Runtime metadata
+    "LocalizedMessages",
+    "RuntimeMetadata",
+    # Storage
+    "OBJECT_STORAGE_PREFIX",
+    "StorageConfig",
+    "StorageType",
+    # Step Limit
+    "MaxDelegationDepthExceededError",
+    "MaxStepsExceededError",
+    "StepLimitConfig",
+    "StepLimitError",
+    "StepLimitErrorResponse",
+    "StepLimitErrorType",
+    # Tool payloads
+    "ToolArgs",
+    "ToolInvocationPayload",
+    "ToolOutputStorageStats",
+    "ToolOutputSummaryEntry",
+]

aip_agents/schema/a2a.py

@@ -0,0 +1,58 @@
+"""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
+    model_usage_delta: dict[str, Any] | None
+    model_usage: list[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