glaip-sdk 0.6.5b6__py3-none-any.whl → 0.7.12__py3-none-any.whl

glaip_sdk/utils/tool_detection.py

@@ -4,8 +4,140 @@ 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.
@@ -20,14 +152,150 @@ def is_langchain_tool(ref: Any) -> bool:
     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:
-        from langchain_core.tools import BaseTool  # noqa: PLC0415
+        # 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
+
 
-        if isinstance(ref, type) and issubclass(ref, BaseTool):
-            return True
-        if isinstance(ref, BaseTool):
-            return True
-    except ImportError:
+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-0.6.5b6.dist-info → glaip_sdk-0.7.12.dist-info}/METADATA

@@ -1,43 +1,45 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: glaip-sdk
-Version: 0.6.5b6
-Summary: Python SDK for GL AIP (GDP Labs AI Agent Package) - Simplified CLI Design
+Version: 0.7.12
+Summary: Python SDK and CLI for GL AIP (GDP Labs AI Agent Package) - Build, run, and manage AI agents
+Author-email: Raymond Christopher <raymond.christopher@gdplabs.id>
 License: MIT
-Author: Raymond Christopher
-Author-email: raymond.christopher@gdplabs.id
-Requires-Python: >=3.11,<3.13
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Provides-Extra: dev
-Requires-Dist: aip-agents-binary (>=0.5.0)
-Requires-Dist: click (>=8.2.0,<8.3.0)
-Requires-Dist: gllm-core-binary (>=0.1.0)
-Requires-Dist: gllm-tools-binary (>=0.1.3)
-Requires-Dist: httpx (>=0.28.1)
-Requires-Dist: langchain-core (>=0.3.0)
-Requires-Dist: packaging (>=23.2)
-Requires-Dist: pre-commit (>=4.3.0) ; extra == "dev"
-Requires-Dist: pydantic (>=2.0.0)
-Requires-Dist: pytest (>=7.0.0) ; extra == "dev"
-Requires-Dist: pytest-asyncio (>=0.23.6) ; extra == "dev"
-Requires-Dist: pytest-cov (>=4.0.0) ; extra == "dev"
-Requires-Dist: pytest-dotenv (>=0.5.2) ; extra == "dev"
-Requires-Dist: pytest-timeout (>=2.3.1) ; extra == "dev"
-Requires-Dist: pytest-xdist (>=3.8.0) ; extra == "dev"
-Requires-Dist: python-dotenv (>=1.1.1,<2.0.0)
-Requires-Dist: pyyaml (>=6.0.0)
-Requires-Dist: questionary (>=2.1.0,<3.0.0)
-Requires-Dist: readchar (>=4.2.1,<5.0.0)
-Requires-Dist: rich (>=13.0.0)
-Requires-Dist: ruff (>=0.14.0) ; extra == "dev"
-Requires-Dist: textual (>=0.52.0)
+Requires-Python: <3.13,>=3.11
 Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: python-dotenv<2.0.0,>=1.1.1
+Requires-Dist: readchar<5.0.0,>=4.2.1
+Requires-Dist: questionary<3.0.0,>=2.1.0
+Requires-Dist: click<8.3.0,>=8.2.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: packaging>=23.2
+Requires-Dist: textual>=0.52.0
+Requires-Dist: gllm-core-binary>=0.1.0
+Requires-Dist: langchain-core>=0.3.0
+Requires-Dist: gllm-tools-binary>=0.1.3
+Provides-Extra: local
+Requires-Dist: aip-agents-binary[local]>=0.5.23; (python_version >= "3.11" and python_version < "3.13") and extra == "local"
+Provides-Extra: memory
+Requires-Dist: aip-agents-binary[memory]>=0.5.23; (python_version >= "3.11" and python_version < "3.13") and extra == "memory"
+Provides-Extra: privacy
+Requires-Dist: aip-agents-binary[privacy]>=0.5.23; (python_version >= "3.11" and python_version < "3.13") and extra == "privacy"
+Provides-Extra: guardrails
+Requires-Dist: aip-agents-binary[guardrails]>=0.5.23; (python_version >= "3.11" and python_version < "3.13") and extra == "guardrails"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-dotenv>=0.5.2; extra == "dev"
+Requires-Dist: pre-commit>=4.3.0; extra == "dev"
+Requires-Dist: pytest-xdist>=3.8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.6; extra == "dev"
+Requires-Dist: pytest-timeout>=2.3.1; extra == "dev"
+Requires-Dist: ruff>=0.14.0; extra == "dev"
 
 # GL AIP — GDP Labs AI Agents Package
 
-[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![Python 3.11-3.12](https://img.shields.io/badge/python-3.11--3.12-blue.svg)](https://www.python.org/downloads/)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 
 GL stands for **GDP Labs**—GL AIP is our AI Agents Package for building, running, and operating agents.
@@ -48,15 +50,26 @@ GL stands for **GDP Labs**—GL AIP is our AI Agents Package for building, runni
 
 ### Installation
 
+Installing `glaip-sdk` provides both the **Python SDK** and the **`aip` CLI command** in a single package.
+
 ```bash
 # Using pip (recommended)
 pip install --upgrade glaip-sdk
 
 # Using uv (fast alternative)
 uv tool install glaip-sdk
+
+# Using pipx (CLI-focused, isolated environment)
+pipx install glaip-sdk
 ```
 
-**Requirements**: Python 3.10+
+**Requirements**: Python 3.11 or 3.12
+
+**Updating**: The `aip` CLI automatically detects your installation method and uses the correct update command:
+
+- If installed via `pip`: Uses `pip install --upgrade glaip-sdk`
+- If installed via `uv tool install`: Uses `uv tool install --upgrade glaip-sdk`
+- You can also update manually using the same command you used to install
 
 ## 🐍 Hello World - Python SDK
 
@@ -133,7 +146,7 @@ print("--- Stream complete ---")
 
 🎉 **SDK Success!** You're now ready to build AI-powered applications with Python.
 
----
+______________________________________________________________________
 
 ## 💻 Hello World - CLI
 
@@ -226,4 +239,3 @@ The script:
 - Resets module metadata afterwards so your environment remains untouched.
 
 You should see the Rich banner re-render with the mocked version (and optional marker) at the end of the run.
-