aip-agents-binary 0.0.0b2__py3-none-any.whl → 0.5.12__py3-none-any.whl

aip_agents/tools/document_loader/pdf_reader_tool.py

@@ -0,0 +1,67 @@
+"""Tool to read and extract text from PDF files.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+
+References:
+    https://github.com/GDP-ADMIN/gdplabs-exploration/blob/ai-agent-app/backend/aip_agents/tools/
+      reader/pdf_reader_tool.py
+"""
+
+from gllm_docproc.loader.pdf import PDFPlumberLoader, PyMuPDFLoader
+
+from aip_agents.tools.document_loader.base_reader import BaseDocumentReaderTool
+from aip_agents.tools.document_loader.pdf_splitter import PDFSplitter
+from aip_agents.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class PDFReaderTool(BaseDocumentReaderTool):
+    """Tool to read and extract text from PDF files."""
+
+    name: str = "pdf_reader_tool"
+    description: str = "Read a PDF file and extract its text content. Input should be the path to the PDF file."
+
+    def _setup_loader(self):
+        self.loader.add_loader(PyMuPDFLoader())
+        self.loader.add_loader(PDFPlumberLoader())
+
+    def _split_file(self, file_path: str, batch_size: int) -> list[str]:
+        """Split PDF file into temporary files for batch processing.
+
+        This method uses PDFSplitter.split_by_pages to split the PDF into
+        temporary files containing the specified number of pages per batch.
+
+        Args:
+            file_path: Path to the PDF file to be split
+            batch_size: Number of pages to include in each split file (1-10)
+
+        Returns:
+            List of temporary file paths containing the split content
+
+        Raises:
+            FileNotFoundError: If the input PDF file doesn't exist
+            ValueError: If batch_size is invalid or PDF processing fails
+            Exception: For other unexpected errors during PDF splitting
+        """
+        logger.info(f"Splitting PDF file '{file_path}' with batch_size={batch_size}")
+
+        try:
+            # Use PDFSplitter utility to split the PDF by pages
+            temp_files = PDFSplitter.split_by_pages(file_path, batch_size)
+
+            logger.info(f"Successfully split PDF into {len(temp_files)} batch files")
+            logger.debug(f"Created temporary files: {temp_files}")
+
+            return temp_files
+
+        except FileNotFoundError:
+            logger.error(f"PDF file not found: {file_path}")
+            raise
+        except ValueError as e:
+            logger.error(f"Invalid parameters or corrupted PDF: {str(e)}")
+            raise
+        except Exception as e:
+            logger.error(f"Unexpected error splitting PDF '{file_path}': {str(e)}")
+            raise Exception(f"Failed to split PDF file: {str(e)}") from e

aip_agents/tools/document_loader/pdf_splitter.py

@@ -0,0 +1,169 @@
+"""PDF splitting utility for batching optimization.
+
+Authors
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+import os
+import tempfile
+
+from PyPDF2 import PdfReader, PdfWriter
+
+
+class PDFSplitter:
+    """Utility class for splitting PDF files into page-based temporary files."""
+
+    @staticmethod
+    def split_by_pages(file_path: str, batch_size: int) -> list[str]:
+        """Split PDF into temporary files containing batch_size pages each.
+
+        Args:
+            file_path: Path to the PDF file to split
+            batch_size: Number of pages to include in each batch (1-10)
+
+        Returns:
+            List of temporary file paths containing the split PDF batches
+
+        Raises:
+            FileNotFoundError: If the input PDF file doesn't exist
+            ValueError: If batch_size is invalid or PDF is corrupted
+            Exception: For other PDF processing errors
+        """
+        PDFSplitter._validate_inputs(file_path, batch_size)
+
+        try:
+            reader = PdfReader(file_path)
+            PDFSplitter._validate_pdf_content(reader, file_path)
+
+            temp_files = []
+
+            # Split PDF into batches
+            for i in range(0, len(reader.pages), batch_size):
+                batch_number = i // batch_size + 1
+                temp_path = PDFSplitter._create_batch_file(reader, i, batch_size, batch_number, temp_files)
+                temp_files.append(temp_path)
+
+            return temp_files
+
+        except Exception as e:
+            # Handle corrupted or invalid PDF files
+            if "temp_files" in locals():
+                PDFSplitter._cleanup_temp_files(temp_files)
+
+            if isinstance(e, FileNotFoundError | ValueError):
+                raise
+            else:
+                raise ValueError(f"Error processing PDF file {file_path}: {str(e)}") from e
+
+    @staticmethod
+    def _validate_inputs(file_path: str, batch_size: int) -> None:
+        """Validate input parameters.
+
+        Args:
+            file_path: Path to the PDF file to validate
+            batch_size: Batch size to validate
+
+        Raises:
+            FileNotFoundError: If the input PDF file doesn't exist
+            ValueError: If batch_size is invalid
+        """
+        if not os.path.exists(file_path):
+            raise FileNotFoundError(f"PDF file not found: {file_path}")
+
+    @staticmethod
+    def _validate_pdf_content(reader: PdfReader, file_path: str) -> None:
+        """Validate PDF content has pages.
+
+        Args:
+            reader: PdfReader instance to validate
+            file_path: Path to the PDF file for error messages
+
+        Raises:
+            ValueError: If PDF has no pages
+        """
+        if len(reader.pages) == 0:
+            raise ValueError(f"PDF file has no pages: {file_path}")
+
+    @staticmethod
+    def _create_batch_file(
+        reader: PdfReader,
+        start_page: int,
+        batch_size: int,
+        batch_number: int,
+        temp_files: list[str],
+    ) -> str:
+        """Create a temporary file containing a batch of PDF pages.
+
+        Args:
+            reader: PdfReader instance containing the source pages
+            start_page: Starting page index for this batch
+            batch_size: Number of pages to include in the batch
+            batch_number: Batch number for file naming
+            temp_files: List of existing temp files for cleanup on error
+
+        Returns:
+            Path to the created temporary file
+
+        Raises:
+            ValueError: If page processing or file writing fails
+        """
+        writer = PdfWriter()
+
+        # Add pages to this batch
+        batch_end = min(start_page + batch_size, len(reader.pages))
+        for j in range(start_page, batch_end):
+            try:
+                writer.add_page(reader.pages[j])
+            except Exception as e:
+                # Clean up any created temp files before re-raising
+                PDFSplitter._cleanup_temp_files(temp_files)
+                raise ValueError(f"Error processing page {j + 1}: {str(e)}") from e
+
+        # Create and write temporary file
+        return PDFSplitter._write_batch_to_temp_file(writer, batch_number, temp_files)
+
+    @staticmethod
+    def _write_batch_to_temp_file(writer: PdfWriter, batch_number: int, temp_files: list[str]) -> str:
+        """Write a PDF batch to a temporary file.
+
+        Args:
+            writer: PdfWriter instance containing the batch pages
+            batch_number: Batch number for file naming
+            temp_files: List of existing temp files for cleanup on error
+
+        Returns:
+            Path to the created temporary file
+
+        Raises:
+            ValueError: If file writing fails
+        """
+        # Create temporary file with proper naming
+        temp_fd, temp_path = tempfile.mkstemp(suffix=f"_batch_{batch_number}.pdf", prefix="pdf_split_")
+
+        try:
+            with os.fdopen(temp_fd, "wb") as temp_file:
+                writer.write(temp_file)
+            return temp_path
+        except Exception as e:
+            # Close the file descriptor if write fails
+            try:
+                os.close(temp_fd)
+            except OSError:
+                pass
+            # Clean up any created temp files
+            PDFSplitter._cleanup_temp_files(temp_files)
+            raise ValueError(f"Error writing batch {batch_number}: {str(e)}") from e
+
+    @staticmethod
+    def _cleanup_temp_files(temp_files: list[str]) -> None:
+        """Clean up temporary files.
+
+        Args:
+            temp_files: List of temporary file paths to clean up
+        """
+        for temp_file in temp_files:
+            try:
+                if os.path.exists(temp_file):
+                    os.unlink(temp_file)
+            except OSError:
+                pass

aip_agents/tools/gl_connector/__init__.py

@@ -0,0 +1,5 @@
+"""GL Connector tool wrapper exports."""
+
+from aip_agents.tools.gl_connector.tool import GLConnectorTool
+
+__all__ = ["GLConnectorTool"]

aip_agents/tools/gl_connector/tool.py

@@ -0,0 +1,351 @@
+"""GL Connector tool wrapper for BOSA connector tools.
+
+Authors:
+    Saul Sayers (saul.sayers@gdplabs.id)
+
+Reference:
+    https://gl-docs.gitbook.io/bosa/gl-connector/gl-connector
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterable
+from typing import Any
+
+from bosa_connectors import BosaConnector, BOSAConnectorToolGenerator
+from langchain_core.runnables import RunnableConfig
+from langchain_core.tools import BaseTool
+from pydantic import ConfigDict, PrivateAttr
+
+from aip_agents.tools.constants import ToolType
+
+_REQUIRED_ENV_VARS: tuple[str, ...] = (
+    "BOSA_BASE_URL",
+    "BOSA_API_KEY",
+    "BOSA_USERNAME",
+    "BOSA_PASSWORD",
+)
+_TOP_LEVEL_KEYS: tuple[str, ...] = (
+    "token",
+    "identifier",
+    "timeout",
+    "request",
+)
+
+
+class _InjectedTool(BaseTool):
+    """Wrap a BaseTool to inject token and optional identifier into inputs."""
+
+    _base_tool: BaseTool = PrivateAttr()
+    _token: str = PrivateAttr()
+    _identifier: str | None = PrivateAttr(default=None)
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    def __init__(self, base_tool: BaseTool, token: str, identifier: str | None) -> None:
+        """Initialize the injected tool wrapper.
+
+        Args:
+            base_tool: The base tool to wrap.
+            token: Authentication token to inject into tool inputs.
+            identifier: Optional identifier to inject into tool inputs.
+
+        Returns:
+            None
+        """
+        base_fields = {field: getattr(base_tool, field) for field in BaseTool.model_fields}
+        super().__init__(**base_fields)
+        self._base_tool = base_tool
+        self._token = token
+        self._identifier = identifier
+
+    def _run(self, *args: Any, **kwargs: Any) -> Any:
+        """Execute the wrapped tool synchronously.
+
+        Args:
+            *args: Positional arguments to pass to the base tool.
+            **kwargs: Keyword arguments to pass to the base tool.
+
+        Returns:
+            The result of executing the base tool.
+        """
+        return self._base_tool._run(*args, **kwargs)
+
+    async def _arun(self, *args: Any, **kwargs: Any) -> Any:
+        """Execute the wrapped tool asynchronously.
+
+        Args:
+            *args: Positional arguments to pass to the base tool.
+            **kwargs: Keyword arguments to pass to the base tool.
+
+        Returns:
+            The result of executing the base tool.
+        """
+        return await self._base_tool._arun(*args, **kwargs)
+
+    def invoke(self, input: Any, config: RunnableConfig | None = None, **kwargs: Any) -> Any:
+        """Invoke the tool with token and optional identifier injected.
+
+        Args:
+            input: Tool input to process.
+            config: Optional runnable configuration.
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            The result of invoking the tool with injected parameters.
+        """
+        injected = _inject_params(input, self._token, self._identifier, self._base_tool)
+        return super().invoke(injected, config=config, **kwargs)
+
+    async def ainvoke(self, input: Any, config: RunnableConfig | None = None, **kwargs: Any) -> Any:
+        """Invoke the tool asynchronously with token and optional identifier injected.
+
+        Args:
+            input: Tool input to process.
+            config: Optional runnable configuration.
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            The result of invoking the tool with injected parameters.
+        """
+        injected = _inject_params(input, self._token, self._identifier, self._base_tool)
+        return await super().ainvoke(injected, config=config, **kwargs)
+
+    def run(self, tool_input: Any, **kwargs: Any) -> Any:
+        """Run the tool with token and optional identifier injected.
+
+        Args:
+            tool_input: Tool input to process.
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            The result of running the tool with injected parameters.
+        """
+        injected = _inject_params(tool_input, self._token, self._identifier, self._base_tool)
+        return super().run(injected, **kwargs)
+
+    async def arun(self, tool_input: Any, **kwargs: Any) -> Any:
+        """Run the tool asynchronously with token and optional identifier injected.
+
+        Args:
+            tool_input: Tool input to process.
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            The result of running the tool with injected parameters.
+        """
+        injected = _inject_params(tool_input, self._token, self._identifier, self._base_tool)
+        return await super().arun(injected, **kwargs)
+
+
+def GLConnectorTool(
+    tool_name: str,
+    *,
+    api_key: str | None = None,
+    identifier: str | None = None,
+) -> BaseTool:
+    """Create a single GL Connector tool by exact tool name.
+
+    Args:
+        tool_name: Exact tool name (not module name).
+        api_key: Optional override for BOSA API key.
+        identifier: Optional override for BOSA identifier.
+
+    Returns:
+        A single LangChain BaseTool with token injection.
+    """
+    if not tool_name or not tool_name.strip():
+        raise ValueError("tool_name must be a non-empty string")
+
+    env_values = _load_env(api_key=api_key, identifier=identifier)
+    connector = BosaConnector(api_base_url=env_values["BOSA_BASE_URL"], api_key=env_values["BOSA_API_KEY"])
+
+    modules = _get_available_modules(connector)
+    module_name = _resolve_module(tool_name, modules)
+
+    generator = BOSAConnectorToolGenerator(
+        api_base_url=env_values["BOSA_BASE_URL"],
+        api_key=env_values["BOSA_API_KEY"],
+        app_name=module_name,
+    )
+    tools = generator.generate_tools(tool_type=ToolType.LANGCHAIN)
+
+    matching = [tool for tool in tools if getattr(tool, "name", None) == tool_name]
+    if not matching:
+        raise ValueError(f"Tool '{tool_name}' not found in module '{module_name}'")
+    if len(matching) > 1:
+        raise ValueError(f"Multiple tools named '{tool_name}' found in module '{module_name}'")
+
+    token = _create_token(connector, env_values["BOSA_USERNAME"], env_values["BOSA_PASSWORD"])
+    return _InjectedTool(matching[0], token, env_values.get("BOSA_IDENTIFIER"))
+
+
+def _load_env(*, api_key: str | None, identifier: str | None) -> dict[str, str]:
+    """Load and validate environment configuration for connector access.
+
+    Args:
+        api_key: Optional override for BOSA API key.
+        identifier: Optional override for BOSA identifier.
+
+    Returns:
+        Dictionary containing environment configuration values.
+
+    Raises:
+        ValueError: If required environment variables are missing.
+    """
+    env = {key: os.getenv(key) for key in _REQUIRED_ENV_VARS}
+
+    resolved_api_key = api_key or env["BOSA_API_KEY"]
+    env["BOSA_API_KEY"] = resolved_api_key
+
+    optional_identifier = identifier or os.getenv("BOSA_IDENTIFIER")
+
+    if optional_identifier:
+        env["BOSA_IDENTIFIER"] = optional_identifier
+
+    missing = [key for key, value in env.items() if key in _REQUIRED_ENV_VARS and not value]
+    if missing:
+        raise ValueError(f"Missing required environment variables: {', '.join(missing)}")
+
+    return {key: value for key, value in env.items() if value is not None}
+
+
+def _get_available_modules(connector: BosaConnector) -> list[str]:
+    """Return available connector modules or raise an actionable error.
+
+    Args:
+        connector: BOSA connector instance to query for modules.
+
+    Returns:
+        List of available module names.
+
+    Raises:
+        ValueError: If module fetching fails or no modules are available.
+    """
+    try:
+        modules = list(connector.get_available_modules())
+    except Exception as exc:
+        raise ValueError("Failed to fetch available connector modules") from exc
+
+    if not modules:
+        raise ValueError("No connector modules available")
+    return modules
+
+
+def _resolve_module(tool_name: str, modules: Iterable[str]) -> str:
+    """Resolve the module name by longest prefix match.
+
+    Args:
+        tool_name: Name of the tool to resolve module for.
+        modules: Iterable of available module names.
+
+    Returns:
+        The resolved module name.
+
+    Raises:
+        ValueError: If no matching module is found or multiple ambiguous matches exist.
+    """
+    candidates = [module for module in modules if tool_name == module or tool_name.startswith(f"{module}_")]
+    if not candidates:
+        raise ValueError(f"Unable to resolve module for tool '{tool_name}'. Available modules: {', '.join(modules)}")
+
+    candidates.sort(key=len, reverse=True)
+    if len(candidates) > 1 and len(candidates[0]) == len(candidates[1]):
+        raise ValueError(f"Ambiguous module match for tool '{tool_name}'. Matches: {', '.join(candidates)}")
+    return candidates[0]
+
+
+def _create_token(connector: BosaConnector, username: str, password: str) -> str:
+    """Authenticate the connector user and return a user token.
+
+    Args:
+        connector: BOSA connector instance for authentication.
+        username: BOSA username for authentication.
+        password: BOSA password for authentication.
+
+    Returns:
+        Authentication token string.
+
+    Raises:
+        ValueError: If authentication fails or token is missing.
+    """
+    try:
+        user = connector.authenticate_bosa_user(username, password)
+    except Exception as exc:
+        raise ValueError("Failed to authenticate BOSA user") from exc
+
+    token = getattr(user, "token", None)
+    if not token:
+        raise ValueError("BOSA user token missing after authentication")
+    return token
+
+
+def _inject_params(tool_input: Any, token: str, identifier: str | None, base_tool: BaseTool) -> dict[str, Any]:
+    """Inject token and optional identifier into tool input.
+
+    Args:
+        tool_input: Original tool input dictionary.
+        token: Authentication token to inject.
+        identifier: Optional identifier to inject.
+        base_tool: Base tool instance for schema inspection.
+
+    Returns:
+        Dictionary with token and optional identifier injected.
+
+    Raises:
+        TypeError: If tool_input is not a dictionary.
+    """
+    if tool_input is None:
+        tool_input = {}
+
+    if not isinstance(tool_input, dict):
+        raise TypeError("Connector tool input must be a dict to inject token")
+
+    if "args" in tool_input and isinstance(tool_input.get("args"), dict):
+        injected_args = dict(tool_input["args"])
+        injected_args["token"] = token
+        if identifier:
+            injected_args["identifier"] = identifier
+        injected = dict(tool_input)
+        injected["args"] = injected_args
+        return injected
+
+    injected = dict(tool_input)
+    injected = _wrap_request_if_needed(injected, base_tool)
+    injected["token"] = token
+    if identifier:
+        injected["identifier"] = identifier
+    return injected
+
+
+def _wrap_request_if_needed(tool_input: dict[str, Any], base_tool: BaseTool) -> dict[str, Any]:
+    """Wrap flat inputs into a 'request' payload when required by schema.
+
+    Args:
+        tool_input: Tool input dictionary to potentially wrap.
+        base_tool: Base tool instance for schema inspection.
+
+    Returns:
+        Dictionary with inputs wrapped in 'request' key if needed, otherwise unchanged.
+    """
+    args_schema = getattr(base_tool, "args_schema", None)
+    if not (isinstance(args_schema, dict) and "request" in args_schema.get("properties", {})):
+        return tool_input
+
+    request_payload = {}
+    existing_request = tool_input.get("request")
+    if isinstance(existing_request, dict):
+        request_payload.update(existing_request)
+
+    for key, value in tool_input.items():
+        if key in _TOP_LEVEL_KEYS:
+            continue
+        request_payload.setdefault(key, value)
+
+    wrapped = dict(tool_input)
+    wrapped["request"] = request_payload
+    for key in list(wrapped.keys()):
+        if key not in _TOP_LEVEL_KEYS:
+            wrapped.pop(key, None)
+    return wrapped

aip_agents/tools/memory_search/__init__.py

@@ -0,0 +1,22 @@
+"""Memory search tool package exposing shared schemas and implementations.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from aip_agents.tools.memory_search.base import LongTermMemorySearchTool
+from aip_agents.tools.memory_search.mem0 import (
+    MEMORY_SEARCH_TOOL_NAME,
+    Mem0SearchInput,
+    Mem0SearchTool,
+)
+from aip_agents.tools.memory_search.schema import LongTermMemorySearchInput, MemoryConfig
+
+__all__ = [
+    "MemoryConfig",
+    "LongTermMemorySearchInput",
+    "LongTermMemorySearchTool",
+    "Mem0SearchInput",
+    "Mem0SearchTool",
+    "MEMORY_SEARCH_TOOL_NAME",
+]