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

glaip_sdk/utils/sync.py

@@ -0,0 +1,162 @@
+"""Agent and tool synchronization (create/update) operations.
+
+This module provides convenience functions for tool classes that need bundling.
+
+For direct upsert operations, use the client methods:
+    - client.agents.upsert_agent(identifier, **kwargs)
+    - client.tools.upsert_tool(identifier, code, **kwargs)
+    - client.mcps.upsert_mcp(identifier, **kwargs)
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from glaip_sdk.exceptions import ValidationError
+from glaip_sdk.utils.bundler import ToolBundler
+from glaip_sdk.utils.import_resolver import load_class
+from gllm_core.utils import LoggerManager
+
+if TYPE_CHECKING:
+    from glaip_sdk.models import Agent, Tool
+
+logger = LoggerManager().get_logger(__name__)
+
+
+def _extract_tool_name(tool_class: Any) -> str:
+    """Extract tool name from a class, handling Pydantic v2 models."""
+    # Direct attribute access (works for non-Pydantic classes)
+    if hasattr(tool_class, "name"):
+        name = getattr(tool_class, "name", None)
+        if isinstance(name, str):
+            return name
+
+    # Pydantic v2 model - check model_fields
+    if hasattr(tool_class, "model_fields"):
+        model_fields = getattr(tool_class, "model_fields", {})
+        if "name" in model_fields:
+            field_info = model_fields["name"]
+            if hasattr(field_info, "default") and isinstance(field_info.default, str):
+                return field_info.default
+
+    raise ValueError(f"Cannot extract name from tool class: {tool_class}")
+
+
+def _extract_tool_description(tool_class: Any) -> str:
+    """Extract tool description from a class, handling Pydantic v2 models."""
+    # Direct attribute access
+    if hasattr(tool_class, "description"):
+        desc = getattr(tool_class, "description", None)
+        if isinstance(desc, str):
+            return desc
+
+    # Pydantic v2 model - check model_fields
+    if hasattr(tool_class, "model_fields"):
+        model_fields = getattr(tool_class, "model_fields", {})
+        if "description" in model_fields:
+            field_info = model_fields["description"]
+            if hasattr(field_info, "default") and isinstance(field_info.default, str):
+                return field_info.default
+
+    return ""
+
+
+def update_or_create_tool(tool_ref: Any) -> Tool:
+    """Create or update a tool from a tool class with bundled source code.
+
+    This function takes a tool class (LangChain BaseTool), bundles its source
+    code with inlined imports, and creates/updates it in the backend.
+
+    Args:
+        tool_ref: A tool class (LangChain BaseTool subclass) or import path string.
+
+    Returns:
+        The created or updated tool.
+
+    Example:
+        >>> from glaip_sdk.utils.sync import update_or_create_tool
+        >>> from my_tools import WeatherAPITool
+        >>> tool = update_or_create_tool(WeatherAPITool)
+    """
+    from glaip_sdk.utils.client import get_client  # noqa: PLC0415
+
+    client = get_client()
+
+    # Handle string import path
+    if isinstance(tool_ref, str):
+        tool_class = load_class(tool_ref)
+    else:
+        tool_class = tool_ref
+
+    # Get tool info - handle Pydantic v2 model classes
+    tool_name = _extract_tool_name(tool_class)
+    tool_description = _extract_tool_description(tool_class)
+
+    # Bundle source code - try without decorator first (for newer servers 0.1.85+)
+    # If validation fails, retry with decorator for older servers (< 0.1.85)
+    bundler = ToolBundler(tool_class)
+
+    try:
+        # Try without decorator first (for newer servers where it's optional)
+        bundled_source = bundler.bundle(add_tool_plugin_decorator=False)
+        logger.info("Tool info: name='%s', description='%s...'", tool_name, tool_description[:50])
+        logger.info("Bundled source code (without decorator): %d characters", len(bundled_source))
+
+        # Attempt upload without decorator
+        return client.tools.upsert_tool(
+            tool_name,
+            code=bundled_source,
+            description=tool_description,
+        )
+    except ValidationError as e:
+        # Check if error is about missing @tool_plugin decorator
+        error_message = str(e).lower()
+        if "@tool_plugin decorator" in error_message or "no classes found" in error_message:
+            # Retry with decorator for older servers (< 0.1.85)
+            logger.info("Server requires @tool_plugin decorator, retrying with decorator added")
+            bundled_source = bundler.bundle(add_tool_plugin_decorator=True)
+            logger.info("Bundled source code (with decorator): %d characters", len(bundled_source))
+
+            return client.tools.upsert_tool(
+                tool_name,
+                code=bundled_source,
+                description=tool_description,
+            )
+        # Re-raise if it's a different validation error
+        raise
+
+
+def update_or_create_agent(agent_config: dict[str, Any]) -> Agent:
+    """Create or update an agent from configuration.
+
+    Args:
+        agent_config: Agent configuration dictionary containing:
+            - name (str): Agent name (required)
+            - description (str): Agent description
+            - instruction (str): Agent instruction
+            - tools (list, optional): List of tool IDs
+            - agents (list, optional): List of sub-agent IDs
+            - metadata (dict, optional): Additional metadata
+
+    Returns:
+        The created or updated agent.
+
+    Example:
+        >>> from glaip_sdk.utils.sync import update_or_create_agent
+        >>> config = {
+        ...     "name": "weather_reporter",
+        ...     "description": "Weather reporting agent",
+        ...     "instruction": "You are a weather reporter.",
+        ... }
+        >>> agent = update_or_create_agent(config)
+    """
+    from glaip_sdk.utils.client import get_client  # noqa: PLC0415
+
+    client = get_client()
+    agent_name = agent_config.pop("name")
+
+    # Use client's upsert method
+    return client.agents.upsert_agent(agent_name, **agent_config)

glaip_sdk/utils/tool_detection.py

@@ -0,0 +1,301 @@
+"""Shared utilities for tool type detection.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import ast
+import importlib
+import inspect
+import pkgutil
+from functools import lru_cache
+from typing import Any
+
+# Constants for frequently used strings to avoid duplication (S1192)
+_NAME = "name"
+_AIP_AGENTS_TOOLS = "aip_agents.tools"
+_BASE_TOOL = "BaseTool"
+
+# Internal map to store all discovered tools in the session
+_DISCOVERED_TOOLS: dict[str, type] | None = None
+
+
+def _should_skip_module(module_name: str) -> bool:
+    """Check if module should be skipped during tool discovery."""
+    short_name = module_name.rsplit(".", 1)[-1]
+    return short_name.startswith("_") or "test" in short_name
+
+
+def _get_pydantic_field_default(cls: type, attr_name: str, field_name: str) -> str | None:
+    """Extract default value from a Pydantic field."""
+    try:
+        fields = getattr(cls, attr_name, {})
+        field = fields.get(field_name)
+        # Broad exception handling needed because:
+        # - model_fields/__fields__ might be a descriptor that raises AttributeError
+        # - field.default might raise during access
+        # - Various Pydantic internals can raise unexpected exceptions
+        if field and hasattr(field, "default") and isinstance(field.default, str):
+            return field.default
+    except Exception:  # pylint: disable=broad-except
+        pass
+    return None
+
+
+def _get_name_from_pydantic_v2(cls: type) -> str | None:
+    """Extract name from Pydantic v2 model_fields."""
+    return _get_pydantic_field_default(cls, "model_fields", _NAME)
+
+
+def _get_name_from_pydantic_v1(cls: type) -> str | None:
+    """Extract name from Pydantic v1 __fields__."""
+    return _get_pydantic_field_default(cls, "__fields__", _NAME)
+
+
+def get_tool_name(ref: Any) -> str | None:
+    """Extract tool name from a tool class or instance.
+
+    Handles LangChain BaseTool (Pydantic v1/v2) and standard classes.
+
+    Args:
+        ref: Tool class or instance.
+
+    Returns:
+        The extracted tool name, or None if not found.
+    """
+    if ref is None:
+        return None
+
+    # 1. Try instance 'name' attribute
+    if not isinstance(ref, type):
+        try:
+            name = getattr(ref, _NAME, None)
+            if isinstance(name, str):
+                return name
+        except Exception:  # pylint: disable=broad-except
+            pass
+
+    cls = ref if isinstance(ref, type) else type(ref)
+
+    # 2. Try class 'model_fields' (Pydantic v2)
+    # Check Pydantic v2 first for forward compatibility
+    name = _get_name_from_pydantic_v2(cls)
+    if name:
+        return name
+
+    # 3. Try class '__fields__' (Pydantic v1)
+    name = _get_name_from_pydantic_v1(cls)
+    if name:
+        return name
+
+    # 4. Try direct class attribute
+    if hasattr(cls, _NAME):
+        try:
+            name_attr = getattr(cls, _NAME)
+            if isinstance(name_attr, str):
+                return name_attr
+        except Exception:  # pylint: disable=broad-except
+            pass
+
+    return None
+
+
+def _check_langchain_standard(ref: Any) -> bool:
+    """Perform standard isinstance/issubclass check for LangChain tool."""
+    try:
+        from langchain_core.tools import BaseTool  # noqa: PLC0415
+
+        # Check if BaseTool is actually a type to avoid TypeError in issubclass/isinstance
+        if isinstance(BaseTool, type):
+            if isinstance(ref, type) and issubclass(ref, BaseTool):
+                return True
+            if isinstance(ref, BaseTool):
+                return True
+    except (ImportError, TypeError):
+        pass
+    return False
+
+
+def _check_langchain_fallback(ref: Any) -> bool:
+    """Perform name-based fallback check for LangChain tool (robust for mocks).
+
+    This fallback handles cases where:
+    - BaseTool is mocked in tests
+    - BaseTool is re-imported through internal modules (e.g., runner)
+    - isinstance/issubclass checks fail due to module reloading
+    """
+    try:
+        cls = ref if isinstance(ref, type) else getattr(ref, "__class__", None)
+        if cls and hasattr(cls, "__mro__"):
+            for c in cls.__mro__:
+                c_name = getattr(c, "__name__", None)
+                c_module = getattr(c, "__module__", "")
+                if c_name == _BASE_TOOL and ("langchain" in c_module or "runner" in c_module):
+                    return True
+    except (AttributeError, TypeError):
+        pass
+    return False
+
+
+def is_langchain_tool(ref: Any) -> bool:
+    """Check if ref is a LangChain BaseTool class or instance.
+
+    Shared by:
+    - ToolRegistry._is_custom_tool() (for upload detection)
+    - LangChainToolAdapter._is_langchain_tool() (for adaptation)
+
+    Args:
+        ref: Object to check.
+
+    Returns:
+        True if ref is a LangChain BaseTool class or instance.
+    """
+    if ref is None:
+        return False
+
+    # 1. Standard check (preferred)
+    if _check_langchain_standard(ref):
+        return True
+
+    # 2. Name-based check (robust fallback for mocks and re-imports)
+    return _check_langchain_fallback(ref)
+
+
+def is_aip_agents_tool(ref: Any) -> bool:
+    """Check if ref is an aip-agents tool class or instance.
+
+    Args:
+        ref: Object to check.
+
+    Returns:
+        True if ref is from aip_agents.tools package.
+    """
+    try:
+        # Check class module
+        if isinstance(ref, type):
+            return ref.__module__.startswith(_AIP_AGENTS_TOOLS)
+
+        # Check instance class
+        if hasattr(ref, "__class__"):
+            return ref.__class__.__module__.startswith(_AIP_AGENTS_TOOLS)
+
+        return False
+    except (AttributeError, TypeError):
+        return False
+
+
+def _get_discovered_classes_from_module(module: Any) -> list[type]:
+    """Extract BaseTool subclasses from a module."""
+    discovered_classes = []
+    for attr_name in dir(module):
+        if attr_name.startswith("_"):
+            continue
+
+        try:
+            attr = getattr(module, attr_name)
+            if inspect.isclass(attr) and is_langchain_tool(attr):
+                # Ensure it's not the BaseTool class itself
+                if getattr(attr, "__name__", None) != _BASE_TOOL:
+                    discovered_classes.append(attr)
+        except Exception:  # pylint: disable=broad-except
+            continue
+    return discovered_classes
+
+
+def _import_and_map_module(module_name: str, tools_map: dict[str, type]) -> None:
+    """Import a single module and extract its tools."""
+    try:
+        module = importlib.import_module(module_name)
+        classes = _get_discovered_classes_from_module(module)
+        for tool_class in classes:
+            name = get_tool_name(tool_class)
+            if name:
+                tools_map[name] = tool_class
+    except Exception:  # pylint: disable=broad-except
+        # Broad catch to skip broken modules during discovery
+        pass
+
+
+def _walk_and_map_package(package: Any, tools_map: dict[str, type]) -> None:
+    """Walk through a package and map all tools found."""
+    try:
+        # Walk packages using the package's path and name
+        for _, module_name, _ in pkgutil.walk_packages(package.__path__, package.__name__ + "."):
+            if _should_skip_module(module_name):
+                continue  # pragma: no cover
+
+            _import_and_map_module(module_name, tools_map)
+    except Exception:  # pylint: disable=broad-except
+        # Broad catch for walk_packages failure
+        pass
+
+
+def _get_all_aip_agents_tools() -> dict[str, type]:
+    """Discover and map all tools in aip_agents.tools (once per session)."""
+    global _DISCOVERED_TOOLS  # pylint: disable=global-statement
+    if _DISCOVERED_TOOLS is None:
+        _DISCOVERED_TOOLS = {}
+        try:
+            package = importlib.import_module(_AIP_AGENTS_TOOLS)
+            if hasattr(package, "__path__"):
+                _walk_and_map_package(package, _DISCOVERED_TOOLS)
+        except (ImportError, AttributeError):
+            pass
+    return _DISCOVERED_TOOLS
+
+
+@lru_cache(maxsize=128)
+def find_aip_agents_tool_class(name: str) -> type | None:
+    """Find and return a native tool class by tool name.
+
+    Searches aip_agents.tools submodules for BaseTool subclasses
+    with matching 'name' attribute. Uses caching to improve performance.
+
+    Note:
+        Results are discovered once per session and cached. If tools are
+        dynamically added to the path after the first call, they may not
+        be discovered until the session restarts.
+
+    Args:
+        name (str): The tool name to search for (e.g., "google_serper").
+
+    Returns:
+        type|None: The discovered tool class, or None if not found.
+
+    Examples:
+        >>> find_aip_agents_tool_class("google_serper")
+        <class 'aip_agents.tools.web_search.serper_tool.GoogleSerperTool'>
+
+        >>> find_aip_agents_tool_class("nonexistent")
+        None
+    """
+    return _get_all_aip_agents_tools().get(name)
+
+
+def clear_discovery_cache() -> None:
+    """Clear the tool discovery cache (internal use for testing)."""
+    global _DISCOVERED_TOOLS  # pylint: disable=global-statement
+    _DISCOVERED_TOOLS = None
+    find_aip_agents_tool_class.cache_clear()
+
+
+def is_tool_plugin_decorator(decorator: ast.expr) -> bool:
+    """Check if an AST decorator node is @tool_plugin.
+
+    Shared by:
+    - ToolBundler._has_tool_plugin_decorator() (for bundling)
+    - ImportResolver._is_tool_plugin_decorator() (for import resolution)
+
+    Args:
+        decorator: AST decorator expression node to check.
+
+    Returns:
+        True if decorator is @tool_plugin.
+    """
+    if isinstance(decorator, ast.Name) and decorator.id == "tool_plugin":
+        return True
+    if isinstance(decorator, ast.Call) and isinstance(decorator.func, ast.Name) and decorator.func.id == "tool_plugin":
+        return True
+    return False

glaip_sdk/utils/tool_storage_provider.py

@@ -0,0 +1,140 @@
+"""Helpers for local tool output storage setup.
+
+This module bridges agent_config.tool_output_sharing to ToolOutputManager
+for local execution without modifying aip-agents.
+
+Authors:
+    Fachriza Adhiatma (fachriza.d.adhiatma@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from gllm_core.utils import LoggerManager
+
+logger = LoggerManager().get_logger(__name__)
+
+
+def build_tool_output_manager(agent_name: str, agent_config: dict[str, Any]) -> Any | None:
+    """Build a ToolOutputManager for local tool output sharing.
+
+    Args:
+        agent_name: Name of the agent whose tool outputs will be stored.
+        agent_config: Agent configuration that may enable tool output sharing and contain task_id.
+
+    Returns:
+        A ToolOutputManager instance when tool output sharing is enabled and
+        dependencies are available, otherwise ``None``.
+    """
+    tool_output_sharing_enabled = agent_config.get("tool_output_sharing", False)
+    if not tool_output_sharing_enabled:
+        return None
+
+    try:
+        from aip_agents.storage.clients.minio_client import MinioConfig, MinioObjectStorage  # noqa: PLC0415
+        from aip_agents.storage.providers.memory import InMemoryStorageProvider  # noqa: PLC0415
+        from aip_agents.storage.providers.object_storage import ObjectStorageProvider  # noqa: PLC0415
+        from aip_agents.utils.langgraph.tool_output_management import (  # noqa: PLC0415
+            ToolOutputConfig,
+            ToolOutputManager,
+        )
+    except ImportError:
+        logger.warning("Tool output sharing requested but aip-agents is unavailable; skipping.")
+        return None
+
+    task_id = agent_config.get("task_id")
+
+    storage_provider = _build_tool_output_storage_provider(
+        agent_name=agent_name,
+        task_id=task_id,
+        minio_config_cls=MinioConfig,
+        minio_client_cls=MinioObjectStorage,
+        object_storage_provider_cls=ObjectStorageProvider,
+        memory_storage_provider_cls=InMemoryStorageProvider,
+    )
+    tool_output_config = _build_tool_output_config(storage_provider, ToolOutputConfig)
+    return ToolOutputManager(tool_output_config)
+
+
+def _build_tool_output_storage_provider(
+    agent_name: str,
+    task_id: str | None,
+    minio_config_cls: Any,
+    minio_client_cls: Any,
+    object_storage_provider_cls: Any,
+    memory_storage_provider_cls: Any,
+) -> Any:
+    """Create a storage provider for tool output sharing.
+
+    Args:
+        agent_name: Name of the agent whose tool outputs are stored.
+        task_id: Optional task identifier for coordination context.
+        minio_config_cls: Class exposing a ``from_env`` constructor for MinIO config.
+        minio_client_cls: MinIO client class used to talk to the object store.
+        object_storage_provider_cls: Storage provider wrapping the MinIO client.
+        memory_storage_provider_cls: In-memory provider used as a fallback.
+
+    Returns:
+        An instance of ``object_storage_provider_cls`` when MinIO initialization
+        succeeds, otherwise an instance of ``memory_storage_provider_cls``.
+    """
+    try:
+        config_obj = minio_config_cls.from_env()
+        minio_client = minio_client_cls(config=config_obj)
+        prefix = _build_tool_output_prefix(agent_name, task_id)
+        return object_storage_provider_cls(client=minio_client, prefix=prefix, use_json=False)
+    except Exception as exc:
+        logger.warning("Failed to initialize MinIO for tool outputs: %s. Using in-memory storage.", exc)
+        return memory_storage_provider_cls()
+
+
+def _build_tool_output_prefix(agent_name: str, task_id: str | None) -> str:
+    """Build object storage prefix for tool outputs in local mode.
+
+    Args:
+        agent_name: Name of the agent whose outputs are stored.
+        task_id: Optional task identifier for coordination context.
+
+    Returns:
+        Object storage key prefix dedicated to the provided agent.
+    """
+    if task_id:
+        return f"tool-outputs/tasks/{task_id}/agents/{agent_name}/"
+    return f"tool-outputs/agents/{agent_name}/"
+
+
+def _build_tool_output_config(storage_provider: Any, config_cls: Any) -> Any:
+    """Build ToolOutputConfig using env vars, with safe defaults.
+
+    Args:
+        storage_provider: Provider that will persist tool outputs.
+        config_cls: Tool output configuration class to instantiate.
+
+    Returns:
+        A configured ``config_cls`` instance ready for ToolOutputManager use.
+    """
+
+    def safe_int_conversion(env_var: str, default: str) -> int:
+        """Convert an environment variable to int with a fallback default.
+
+        Args:
+            env_var: Environment variable name to read.
+            default: Default string value used when parsing fails.
+
+        Returns:
+            Integer representation of the environment variable or the default.
+        """
+        try:
+            return int(os.getenv(env_var, default))
+        except (ValueError, TypeError):
+            logger.warning("Invalid value for %s, using default: %s", env_var, default)
+            return int(default)
+
+    return config_cls(
+        max_stored_outputs=safe_int_conversion("TOOL_OUTPUT_MAX_STORED", "200"),
+        max_age_minutes=safe_int_conversion("TOOL_OUTPUT_MAX_AGE_MINUTES", str(24 * 60)),
+        cleanup_interval=safe_int_conversion("TOOL_OUTPUT_CLEANUP_INTERVAL", "50"),
+        storage_provider=storage_provider,
+    )

glaip_sdk/utils/validation.py

@@ -18,6 +18,16 @@ from glaip_sdk.utils.resource_refs import validate_name_format
 RESERVED_NAMES = ["admin", "root", "system", "api", "test", "demo"]
 
 
+def _validate_named_resource(name: str, resource_type: str) -> str:
+    """Shared validator that prevents reserved-name duplication."""
+    cleaned_name = validate_name_format(name, resource_type)
+
+    if cleaned_name.lower() in RESERVED_NAMES:
+        raise ValueError(f"{resource_type.capitalize()} name '{cleaned_name}' is reserved and cannot be used")
+
+    return cleaned_name
+
+
 def validate_agent_name(name: str) -> str:
     """Validate agent name and return cleaned version.
 
@@ -30,13 +40,7 @@ def validate_agent_name(name: str) -> str:
     Raises:
         ValueError: If name is invalid
     """
-    cleaned_name = validate_name_format(name, "agent")
-
-    # Check for reserved names
-    if cleaned_name.lower() in RESERVED_NAMES:
-        raise ValueError(f"'{cleaned_name}' is a reserved name and cannot be used")
-
-    return cleaned_name
+    return _validate_named_resource(name, "agent")
 
 
 def validate_agent_instruction(instruction: str) -> str:
@@ -74,13 +78,7 @@ def validate_tool_name(name: str) -> str:
     Raises:
         ValueError: If name is invalid
     """
-    cleaned_name = validate_name_format(name, "tool")
-
-    # Check for reserved names
-    if cleaned_name.lower() in RESERVED_NAMES:
-        raise ValueError(f"'{cleaned_name}' is a reserved name and cannot be used")
-
-    return cleaned_name
+    return _validate_named_resource(name, "tool")
 
 
 def validate_mcp_name(name: str) -> str:
@@ -95,13 +93,7 @@ def validate_mcp_name(name: str) -> str:
     Raises:
         ValueError: If name is invalid
     """
-    cleaned_name = validate_name_format(name, "mcp")
-
-    # Check for reserved names
-    if cleaned_name.lower() in RESERVED_NAMES:
-        raise ValueError(f"'{cleaned_name}' is a reserved name and cannot be used")
-
-    return cleaned_name
+    return _validate_named_resource(name, "mcp")
 
 
 def validate_timeout(timeout: int) -> int:
@@ -213,7 +205,7 @@ def validate_directory_path(dir_path: str | Path, must_exist: bool = True) -> Pa
 
 
 def validate_url(url: str) -> str:
-    """Validate URL format.
+    """Validate URL format (HTTPS only).
 
     Args:
         url: URL to validate
@@ -225,7 +217,7 @@ def validate_url(url: str) -> str:
         ValueError: If URL is invalid
     """
     url_pattern = re.compile(
-        r"^https?://"  # http:// or https://
+        r"^https://"  # https:// only
         r"(?:(?:[A-Z0-9](?:[A-Z0-9-]{0,61}[A-Z0-9])?\.)+[A-Z]{2,6}\.?|"  # domain...
         r"localhost|"  # localhost...
         r"\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})"  # ...or ip
@@ -235,7 +227,7 @@ def validate_url(url: str) -> str:
     )
 
     if not url_pattern.match(url):
-        raise ValueError(f"Invalid URL format: {url}")
+        raise ValueError("API URL must start with https:// and be a valid host.")
 
     return url