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

aip_agents/storage/providers/object_storage.py

@@ -0,0 +1,214 @@
+"""Object storage provider implementation.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+    Fachriza Adhiatma (fachriza.d.adhiatma@gdplabs.id)
+"""
+
+import json
+import pickle
+from typing import Any
+
+from aip_agents.storage.base import BaseObjectStorageClient
+from aip_agents.storage.providers.base import BaseStorageProvider, StorageError
+from aip_agents.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class ObjectStorageProvider(BaseStorageProvider):
+    """Object storage provider for S3-compatible storage.
+
+    Works with any S3-compatible storage including AWS S3, MinIO,
+    Google Cloud Storage (with S3 compatibility), etc.
+
+    Best for:
+    - Very large datasets
+    - Distributed systems
+    - Cloud deployments
+    - Long-term storage
+    - Multi-region access
+    """
+
+    def __init__(self, client: BaseObjectStorageClient, prefix: str = "", use_json: bool = False):
+        """Initialize object storage provider.
+
+        Args:
+            client: Object storage client instance
+            prefix: Prefix for all keys (like a directory)
+            use_json: Use JSON format (True) or pickle (False)
+        """
+        self.client = client
+        self.prefix = prefix.rstrip("/") + "/" if prefix else ""
+        self.use_json = use_json
+
+    def _get_object_key(self, key: str) -> str:
+        """Get full object key with prefix.
+
+        Args:
+            key: Storage key
+
+        Returns:
+            Full object key with prefix
+        """
+        return f"{self.prefix}{key}"
+
+    def _serialize_data(self, data: Any) -> bytes:
+        """Serialize data to bytes.
+
+        Args:
+            data: Data to serialize
+
+        Returns:
+            Serialized data as bytes
+
+        Raises:
+            StorageError: If serialization fails
+        """
+        try:
+            if self.use_json:
+                return json.dumps(data, default=str).encode("utf-8")
+            return pickle.dumps(data)
+        except Exception as e:
+            raise StorageError(f"Failed to serialize data: {e}") from e
+
+    def _deserialize_data(self, data_bytes: bytes) -> Any:
+        """Deserialize data from bytes.
+
+        Args:
+            data_bytes: Serialized data
+
+        Returns:
+            Deserialized data
+
+        Raises:
+            StorageError: If deserialization fails
+        """
+        try:
+            if self.use_json:
+                return json.loads(data_bytes.decode("utf-8"))
+            return pickle.loads(data_bytes)
+        except Exception as e:
+            raise StorageError(f"Failed to deserialize data: {e}") from e
+
+    def store(self, key: str, data: Any) -> None:
+        """Store data in object storage.
+
+        Args:
+            key: Unique identifier for the data
+            data: Data to store
+
+        Raises:
+            StorageError: If storage operation fails
+        """
+        object_key = self._get_object_key(key)
+
+        try:
+            data_bytes = self._serialize_data(data)
+
+            self.client.upload(
+                object_key=object_key,
+                file_stream=data_bytes,
+                content_type="application/json" if self.use_json else "application/octet-stream",
+                metadata={"storage_key": key, "format": "json" if self.use_json else "pickle"},
+            )
+
+            logger.debug(f"Stored data to object storage: {object_key}")
+
+        except Exception as e:
+            raise StorageError(f"Failed to store data in object storage: {e}") from e
+
+    def retrieve(self, key: str) -> Any:
+        """Retrieve data from object storage.
+
+        Args:
+            key: Unique identifier for the data
+
+        Returns:
+            The stored data
+
+        Raises:
+            KeyError: If key not found
+            StorageError: If retrieval operation fails
+        """
+        object_key = self._get_object_key(key)
+
+        try:
+            data_bytes = self.client.get(object_key)
+            return self._deserialize_data(data_bytes)
+
+        except KeyError as e:
+            raise KeyError(f"Key '{key}' not found in object storage: {e}") from e
+        except Exception as e:
+            raise StorageError(f"Failed to retrieve data from object storage: {e}") from e
+
+    def exists(self, key: str) -> bool:
+        """Check if object exists.
+
+        Args:
+            key: Unique identifier to check
+
+        Returns:
+            True if key exists, False otherwise
+        """
+        object_key = self._get_object_key(key)
+
+        try:
+            return self.client.object_exists(object_key)
+        except Exception as e:
+            logger.warning(f"Failed to check object existence: {e}")
+            return False
+
+    def delete(self, key: str) -> None:
+        """Delete object.
+
+        Args:
+            key: Unique identifier for the data
+        """
+        object_key = self._get_object_key(key)
+
+        try:
+            self.client.delete(object_key)
+            logger.debug(f"Deleted object: {object_key}")
+        except Exception as e:
+            logger.warning(f"Failed to delete object {object_key}: {e}")
+
+    def list_keys(self, prefix: str = "") -> list[str]:
+        """List all keys with optional prefix.
+
+        Args:
+            prefix: Optional prefix to filter keys
+
+        Raises:
+            NotImplementedError: list_keys is not implemented
+        """
+        raise NotImplementedError("list_keys not yet implemented for object storage")
+
+    def clear(self) -> None:
+        """Clear all objects with the configured prefix.
+
+        Warning:
+            This is a dangerous operation!
+        """
+        logger.warning("clear() not implemented for object storage - too dangerous")
+        raise NotImplementedError("Batch clear not implemented for safety reasons")
+
+    def get_presigned_url(self, key: str, expires_hours: int = 24) -> str | None:
+        """Generate presigned URL for direct access.
+
+        Args:
+            key: Storage key
+            expires_hours: URL expiration in hours
+
+        Returns:
+            Presigned URL for direct access
+
+        Raises:
+            StorageError: If URL generation fails
+        """
+        object_key = self._get_object_key(key)
+
+        try:
+            return self.client.generate_presigned_url(object_key=object_key, expires=expires_hours)
+        except Exception as e:
+            raise StorageError(f"Failed to generate presigned URL: {e}") from e

aip_agents/tools/__init__.py

@@ -0,0 +1,65 @@
+"""Initialize Tools Module for AIP Agents."""
+
+from importlib import import_module
+from typing import TYPE_CHECKING
+
+from aip_agents.tools.date_range_tool import DateRangeTool
+from aip_agents.tools.gl_connector import GLConnectorTool
+from aip_agents.tools.gl_connector_tools import (
+    BOSA_AUTOMATED_TOOLS,
+    GL_CONNECTORS_AUTOMATED_TOOLS,
+)
+from aip_agents.tools.time_tool import TimeTool
+from aip_agents.tools.web_search import GoogleSerperTool
+from aip_agents.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+__all__ = [
+    "BOSA_AUTOMATED_TOOLS",
+    "GL_CONNECTORS_AUTOMATED_TOOLS",
+    "GLConnectorTool",
+    "GoogleSerperTool",
+    "TimeTool",
+    "DateRangeTool",
+]
+
+
+def _register_optional(module_path: str, export_name: str) -> None:
+    """Try to import optional tool module and expose it in __all__.
+
+    Args:
+        module_path: The module path to import.
+        export_name: The name to export in __all__.
+    """
+    try:
+        module = import_module(module_path)
+        tool = getattr(module, export_name)
+        __all__.append(export_name)
+        globals()[export_name] = tool
+
+    except ImportError as e:
+        logger.debug(f"Module {module_path} not found: {e}")
+    except AttributeError as e:
+        logger.debug(f"Tool {export_name} not found in module {module_path}: {e}")
+    except Exception as e:
+        logger.debug(f"Unexpected error loading {export_name}: {e}")
+
+
+_register_optional("aip_agents.tools.browser_use", "BrowserUseTool")
+_register_optional("aip_agents.tools.code_sandbox", "CodeSandboxTool")
+_register_optional("aip_agents.tools.code_sandbox", "E2BCodeSandboxTool")
+_register_optional("aip_agents.tools.document_loader", "DocxReaderTool")
+_register_optional("aip_agents.tools.document_loader", "ExcelReaderTool")
+_register_optional("aip_agents.tools.document_loader", "PDFReaderTool")
+_register_optional("aip_agents.tools.execute_ptc_code", "create_execute_ptc_code_tool")
+
+if TYPE_CHECKING:
+    from aip_agents.tools.browser_use import BrowserUseTool
+    from aip_agents.tools.code_sandbox import CodeSandboxTool, E2BCodeSandboxTool
+    from aip_agents.tools.document_loader import (
+        DocxReaderTool,
+        ExcelReaderTool,
+        PDFReaderTool,
+    )
+    from aip_agents.tools.execute_ptc_code import create_execute_ptc_code_tool

aip_agents/tools/agent_schedule_tool.py

@@ -0,0 +1,392 @@
+"""Agent-bound schedule CRUD native tool.
+
+Authors:
+    Saul Sayers (saul.sayers@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import re
+from typing import Any, Literal
+
+import httpx
+from langchain_core.runnables import RunnableConfig
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, Field, SecretStr
+
+
+class AgentScheduleToolConfig(BaseModel):
+    """Runtime configuration for AgentScheduleNativeTool."""
+
+    api_base_url: str = Field(description="Base URL for AIP backend API")
+    api_key: SecretStr = Field(description="API key used for schedule endpoint calls")
+    request_timeout_seconds: int = Field(default=30, ge=1, le=120)
+
+
+class AgentScheduleToolInput(BaseModel):
+    """Action-based input for schedule CRUD operations."""
+
+    action: Literal["create", "list", "update", "delete"] = Field(description="CRUD action to perform")
+    schedule_id: str | None = Field(default=None)
+    input: str | None = Field(default=None)
+    schedule: dict[str, Any] | None = Field(default=None)
+    page: int | None = Field(default=None)
+    limit: int | None = Field(default=None)
+
+    class Config:
+        """Reject unknown fields like agent_id/account_id in payload."""
+
+        extra = "forbid"
+
+
+class AgentScheduleNativeTool(BaseTool):
+    """Native tool for schedule CRUD scoped to trusted bound agent."""
+
+    name: str = "agent_schedule_native_tool"
+    description: str = (
+        "Create, list, update, or delete schedules for the current bound agent only. "
+        "Identity is resolved from trusted runtime metadata."
+    )
+    args_schema: type[BaseModel] = AgentScheduleToolInput
+    tool_config_schema: type[BaseModel] = AgentScheduleToolConfig
+
+    def _run(
+        self,
+        action: str,
+        schedule_id: str | None = None,
+        input: str | None = None,
+        schedule: dict[str, Any] | None = None,
+        page: int | None = None,
+        limit: int | None = None,
+        metadata: dict[str, Any] | None = None,
+        config: RunnableConfig | None = None,
+    ) -> dict[str, Any]:
+        """Execute schedule CRUD action with bound-agent safeguards."""
+        effective_metadata = self._resolve_effective_metadata(config, metadata)
+        validation_error = self._validate_action_inputs(action, schedule_id, input, schedule, page, limit)
+        if validation_error:
+            return self._error(action, validation_error)
+
+        runtime = self._resolve_runtime_config(config, effective_metadata)
+        if isinstance(runtime, dict) and runtime.get("error"):
+            return self._error(action, runtime["error"])
+
+        bound_agent_id = self._resolve_bound_agent_id(effective_metadata)
+        if not bound_agent_id:
+            return self._error(action, "bound_agent_id not found in runtime metadata")
+
+        action_handlers: dict[str, tuple[str, Any]] = {
+            "create": ("Schedule created", lambda: self._handle_create(bound_agent_id, input, schedule, runtime)),
+            "list": ("Schedules listed", lambda: self._handle_list(bound_agent_id, page, limit, runtime)),
+            "update": (
+                "Schedule updated",
+                lambda: self._handle_update(bound_agent_id, schedule_id, input, schedule, runtime),
+            ),
+            "delete": ("Schedule deleted", lambda: self._handle_delete(bound_agent_id, schedule_id, runtime)),
+        }
+
+        handler_entry = action_handlers.get(action)
+        if handler_entry is None:
+            return self._error(action, "Unsupported action")  # pragma: no cover
+
+        success_message, handler = handler_entry
+        try:
+            data = handler()
+            if isinstance(data, dict) and data.get("_error"):
+                return self._error(action, data["_error"])
+            return self._success(action, success_message, data)
+        except RuntimeError as exc:
+            # Sanitize: extract only the part after the first ": " to avoid leaking raw API bodies
+            # into tool responses consumed by the LLM.
+            msg = str(exc)
+            safe_msg = msg.split(": ", 1)[-1] if ": " in msg else "Schedule action failed"
+            if " {" in safe_msg:
+                safe_msg = safe_msg.split(" {", 1)[0]
+            return self._error(action, safe_msg)
+        except Exception:
+            return self._error(action, "Schedule action failed")
+
+    async def _arun(
+        self,
+        action: str,
+        schedule_id: str | None = None,
+        input: str | None = None,
+        schedule: dict[str, Any] | None = None,
+        page: int | None = None,
+        limit: int | None = None,
+        metadata: dict[str, Any] | None = None,
+        config: RunnableConfig | None = None,
+    ) -> dict[str, Any]:
+        return await asyncio.to_thread(
+            self._run,
+            action,
+            schedule_id,
+            input,
+            schedule,
+            page,
+            limit,
+            metadata,
+            config,
+        )
+
+    def _handle_create(
+        self,
+        bound_agent_id: str,
+        input_value: str | None,
+        schedule: dict[str, Any] | None,
+        runtime: dict[str, Any],
+    ) -> dict[str, Any]:
+        path = f"/agents/{bound_agent_id}/schedule"
+        payload = {"input": input_value, "schedule": schedule}
+        return self._call_api("POST", path, runtime, payload)
+
+    def _handle_list(
+        self,
+        bound_agent_id: str,
+        page: int | None,
+        limit: int | None,
+        runtime: dict[str, Any],
+    ) -> dict[str, Any]:
+        query_params: dict[str, Any] = {"agent_id": bound_agent_id}
+        if page is not None:
+            query_params["page"] = page
+        if limit is not None:
+            query_params["limit"] = limit
+        return self._call_api("GET", "/agents/schedules", runtime, query_params=query_params)
+
+    def _check_schedule_ownership(
+        self,
+        bound_agent_id: str,
+        schedule_id: str | None,
+        runtime: dict[str, Any],
+    ) -> str | None:
+        detail = self._call_api("GET", f"/agents/schedules/{schedule_id}", runtime)
+        owner_id = self._extract_owner_id(detail)
+        if owner_id != bound_agent_id:
+            return "Forbidden: schedule does not belong to bound agent"
+        return None
+
+    def _handle_update(
+        self,
+        bound_agent_id: str,
+        schedule_id: str | None,
+        input_value: str | None,
+        schedule: dict[str, Any] | None,
+        runtime: dict[str, Any],
+    ) -> dict[str, Any]:
+        ownership_error = self._check_schedule_ownership(bound_agent_id, schedule_id, runtime)
+        if ownership_error:
+            return {"_error": ownership_error}
+        payload = {"input": input_value, "schedule": schedule}
+        return self._call_api("PUT", f"/agents/schedules/{schedule_id}", runtime, payload)
+
+    def _handle_delete(
+        self,
+        bound_agent_id: str,
+        schedule_id: str | None,
+        runtime: dict[str, Any],
+    ) -> dict[str, Any]:
+        ownership_error = self._check_schedule_ownership(bound_agent_id, schedule_id, runtime)
+        if ownership_error:
+            return {"_error": ownership_error}
+        return self._call_api("DELETE", f"/agents/schedules/{schedule_id}", runtime)
+
+    @staticmethod
+    def _resolve_effective_metadata(
+        config: RunnableConfig | None,
+        metadata: dict[str, Any] | None,
+    ) -> dict[str, Any]:
+        effective_metadata: dict[str, Any] = {}
+        if isinstance(config, dict):
+            config_metadata = config.get("metadata")
+            if isinstance(config_metadata, dict):
+                effective_metadata.update(config_metadata)
+        if isinstance(metadata, dict):
+            # These keys carry trusted runtime config values (from agent runner) and must not be overridden by untrusted metadata.
+            PROTECTED_KEYS = {
+                "bound_agent_id",
+                "api_base_url",
+                "api_key",
+                "aip_base_url",
+                "aip_api_key",
+                "request_timeout_seconds",
+            }
+            for key, value in metadata.items():
+                key_str = str(key)
+                if key_str in PROTECTED_KEYS and key_str in effective_metadata:
+                    continue
+                effective_metadata[key_str] = value
+        return effective_metadata
+
+    @staticmethod
+    def _validate_action_inputs(
+        action: str,
+        schedule_id: str | None,
+        input_value: str | None,
+        schedule: dict[str, Any] | None,
+        page: int | None,
+        limit: int | None,
+    ) -> str | None:
+        valid_actions = {"create", "list", "update", "delete"}
+        if action not in valid_actions:
+            return f"Invalid action '{action}'"
+        return (
+            AgentScheduleNativeTool._validate_schedule_payload(action, input_value, schedule)
+            or AgentScheduleNativeTool._validate_schedule_id(action, schedule_id)
+            or AgentScheduleNativeTool._validate_pagination(action, page, limit)
+        )
+
+    @staticmethod
+    def _validate_schedule_payload(action: str, input_value: str | None, schedule: dict[str, Any] | None) -> str | None:
+        if action not in {"create", "update"}:
+            return None
+        if not input_value or not schedule:
+            return "'input' and 'schedule' are required for create/update"  # pragma: no cover
+        required_schedule_fields = {"minute", "hour", "day_of_month", "month", "day_of_week"}
+        missing_fields = sorted(
+            field
+            for field in required_schedule_fields
+            if not isinstance(schedule.get(field), str) or not schedule.get(field)
+        )
+        if missing_fields:
+            return f"Incomplete schedule payload, missing fields: {', '.join(missing_fields)}"
+        return None
+
+    @staticmethod
+    def _validate_schedule_id(action: str, schedule_id: str | None) -> str | None:
+        if action not in {"update", "delete"}:
+            return None
+        if not schedule_id:
+            return "'schedule_id' is required for update/delete"
+        if not re.match(r"^[a-zA-Z0-9\-_]+$", schedule_id):
+            return "'schedule_id' contains invalid characters"
+        return None
+
+    @staticmethod
+    def _validate_pagination(action: str, page: int | None, limit: int | None) -> str | None:
+        if action != "list":
+            return None
+        if page is not None and page < 1:
+            return "'page' must be a positive integer"
+        if limit is not None and limit < 1:
+            return "'limit' must be a positive integer"
+        return None
+
+    def _resolve_runtime_config(
+        self,
+        config: RunnableConfig | None,
+        metadata: dict[str, Any] | None,
+    ) -> dict[str, Any]:
+        tool_cfg = None
+        get_tool_config = getattr(self, "get_tool_config", None)
+        if callable(get_tool_config):
+            tool_cfg = get_tool_config(config)
+
+        if tool_cfg is not None:
+            if hasattr(tool_cfg, "model_dump"):
+                dumped = tool_cfg.model_dump(exclude_none=True)
+                api_key = dumped.get("api_key")
+                if isinstance(api_key, SecretStr):
+                    dumped["api_key"] = api_key.get_secret_value()
+                return self._normalize_runtime_config(
+                    dumped.get("api_base_url"),
+                    dumped.get("api_key"),
+                    dumped.get("request_timeout_seconds", 30),
+                )
+            if isinstance(tool_cfg, dict):
+                api_key = tool_cfg.get("api_key")
+                if isinstance(api_key, SecretStr):
+                    tool_cfg = {**tool_cfg, "api_key": api_key.get_secret_value()}
+                return self._normalize_runtime_config(
+                    tool_cfg.get("api_base_url"),
+                    tool_cfg.get("api_key"),
+                    tool_cfg.get("request_timeout_seconds", 30),
+                )
+
+        flat = metadata or {}
+        api_base_url = flat.get("api_base_url") or flat.get("aip_base_url")
+        api_key = flat.get("api_key") or flat.get("aip_api_key")
+        timeout = flat.get("request_timeout_seconds", 30)
+        return self._normalize_runtime_config(api_base_url, api_key, timeout)
+
+    @staticmethod
+    def _normalize_runtime_config(
+        api_base_url: Any,
+        api_key: Any,
+        timeout: Any,
+    ) -> dict[str, Any]:
+        if not api_base_url or not api_key:
+            return {"error": "Missing tool runtime config: api_base_url/api_key"}
+
+        try:
+            timeout_seconds = int(timeout)
+        except (TypeError, ValueError):
+            return {"error": "Invalid tool runtime config: request_timeout_seconds must be an integer"}
+
+        if timeout_seconds < 1 or timeout_seconds > 120:
+            return {"error": "Invalid tool runtime config: request_timeout_seconds must be between 1 and 120"}
+
+        return {
+            "api_base_url": str(api_base_url),
+            "api_key": str(api_key),
+            "request_timeout_seconds": timeout_seconds,
+        }
+
+    @staticmethod
+    def _resolve_bound_agent_id(metadata: dict[str, Any] | None) -> str | None:
+        if not isinstance(metadata, dict):
+            return None  # pragma: no cover
+        value = metadata.get("bound_agent_id")
+        return str(value) if value else None
+
+    @staticmethod
+    def _extract_owner_id(schedule_detail: dict[str, Any]) -> str | None:
+        metadata = schedule_detail.get("metadata") if isinstance(schedule_detail, dict) else None
+        if not isinstance(metadata, dict):
+            wrapped = schedule_detail.get("data") if isinstance(schedule_detail, dict) else None
+            metadata = wrapped.get("metadata") if isinstance(wrapped, dict) else None
+        if isinstance(metadata, dict):
+            raw = metadata.get("bound_agent_id")
+            if raw:
+                return str(raw)
+        return None
+
+    def _call_api(
+        self,
+        method: str,
+        path: str,
+        runtime: dict[str, Any],
+        payload: dict[str, Any] | None = None,
+        query_params: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        base_url = runtime["api_base_url"].rstrip("/")
+        url = f"{base_url}{path}"
+        headers = {
+            "X-API-Key": runtime["api_key"],
+        }
+        try:
+            with httpx.Client(timeout=runtime["request_timeout_seconds"]) as client:
+                resp = client.request(method, url, json=payload, params=query_params, headers=headers)
+                resp.raise_for_status()
+                if not resp.content:
+                    return {}
+                try:
+                    decoded = resp.json()
+                except ValueError as exc:
+                    raise RuntimeError(f"Schedule API {method} {path} returned invalid JSON") from exc
+                if isinstance(decoded, dict):
+                    return decoded
+                return {"items": decoded}
+        except httpx.HTTPStatusError as exc:
+            raise RuntimeError(f"Schedule API {method} {path} failed: {exc.response.status_code}") from exc
+        except httpx.RequestError as exc:
+            raise RuntimeError(f"Schedule API {method} {path} unreachable: {exc}") from exc
+
+    @staticmethod
+    def _success(action: str, message: str, data: dict[str, Any]) -> dict[str, Any]:
+        return {"success": True, "action": action, "message": message, "data": data}
+
+    @staticmethod
+    def _error(action: str, message: str) -> dict[str, Any]:
+        return {"success": False, "action": action, "message": message, "data": {}}