xpander-sdk 1.60.4__py3-none-any.whl → 2.0.155__py3-none-any.whl

xpander_sdk/modules/tools_repository/tools_repository_module.py

@@ -0,0 +1,259 @@
+"""
+Tools Repository module for managing tools in the xpander.ai platform.
+
+This module provides functionality to register, list, and manage tools within
+the xpander.ai Backend-as-a-Service platform, supporting tool syncronization and
+integration with AI agents.
+"""
+
+from inspect import Parameter, Signature
+from typing import Any, Callable, ClassVar, List, Optional, Type
+from pydantic import BaseModel, computed_field
+from xpander_sdk.consts.api_routes import APIRoute
+from xpander_sdk.core.xpander_api_client import APIClient
+from xpander_sdk.exceptions.module_exception import ModuleException
+from xpander_sdk.models.configuration import Configuration
+from xpander_sdk.models.shared import XPanderSharedModel
+from xpander_sdk.modules.tools_repository.sub_modules.tool import Tool
+from xpander_sdk.utils.event_loop import run_sync
+import json
+
+class ToolsRepository(XPanderSharedModel):
+    """
+    Repository for managing tools in xpander.ai.
+
+    This class provides methods for tool registration, discovery, and
+    management. It supports dealing with both local tools defined via decorators
+    and tools managed by the backend, ensuring integration consistency.
+
+    Attributes:
+        configuration (Optional[Configuration]): SDK configuration.
+        tools (List[Tool]): List of tools managed by the backend.
+        _local_tools (ClassVar[List[Tool]]): Registry of tools defined via decorators.
+
+    Methods:
+        register_tool: Register a local tool.
+        list: Return a list of all tools.
+        get_tool_by_id: Retrieve a tool by its ID.
+        should_sync_local_tools: Check if local tools need syncing.
+        get_local_tools_for_sync: Retrieve local tools that require syncing.
+        functions: Return normalized callable functions for each tool.
+
+    Example:
+        >>> repo = ToolsRepository()
+        >>> tools = repo.list
+        >>> specific_tool = repo.get_tool_by_id("tool-id")
+    """
+
+    configuration: Optional[Configuration] = Configuration()
+
+    # Mutable list that can be set/overwritten by backend
+    tools: List[Tool] = []
+
+    agent_graph: Optional[Any] = None
+    is_async: Optional[bool] = True
+
+    # Immutable registry for tools defined via decorator
+    _local_tools: ClassVar[List[Tool]] = []
+
+    @classmethod
+    def register_tool(cls, tool: Tool):
+        """
+        Register a new local tool.
+
+        Args:
+            tool (Tool): The tool to register.
+        """
+        cls._local_tools.append(tool)
+    
+    @computed_field
+    @property
+    def list(self) -> List[Tool]:
+        """
+        Return a list of all available tools.
+
+        Merges both backend-managed tools and locally registered tools,
+        ensuring no duplicate IDs. Sets each tool's configuration for
+        further communication.
+
+        Returns:
+            List[Tool]: A list of all available tools.
+        """
+        # Merge _local_tools and _tools, ensuring no duplicates by id
+        all_tools = {tool.id: tool for tool in self.tools}
+        for local_tool in self._local_tools:
+            all_tools.setdefault(local_tool.id, local_tool)
+
+        tools: List[Tool] = list(all_tools.values())
+
+        for tool in tools:
+            tool.set_configuration(configuration=self.configuration)
+            if self.agent_graph:
+                tool.set_schema_overrides(agent_graph=self.agent_graph)
+
+        return tools
+
+    def get_tool_by_id(self, tool_id: str):
+        """
+        Retrieve a tool by its unique identifier.
+
+        Args:
+            tool_id (str): The ID of the tool to retrieve.
+
+        Returns:
+            Tool: The tool corresponding to the given ID.
+        """
+        return next((tool for tool in self.list if tool.id == tool_id), None)
+
+    def get_tool_by_name(self, tool_name: str):
+        """
+        Retrieve a tool by its unique identifier.
+
+        Args:
+            tool_name (str): The ID of the tool to retrieve.
+
+        Returns:
+            Tool: The tool corresponding to the given ID.
+        """
+        return next((tool for tool in self.list if tool.name == tool_name), None)
+
+    def should_sync_local_tools(self):
+        """
+        Determine if local tools need to be synchronized with the backend.
+
+        Checks whether any local tool is marked for graph addition and
+        has not been synced yet.
+
+        Returns:
+            bool: True if any local tools need syncing, False otherwise.
+        """
+        return any(tool.is_local and tool.should_add_to_graph for tool in self.list)
+
+    def get_local_tools_for_sync(self):
+        """
+        Retrieve local tools that require synchronization with the backend.
+
+        Returns:
+            List[Tool]: List of local tools marked for graph addition that are not yet synced.
+        """
+        return [
+            tool
+            for tool in self.list
+            if tool.is_local and tool.should_add_to_graph and not tool.is_synced
+        ]
+
+    @computed_field
+    @property
+    def functions(self) -> List[Callable[..., Any]]:
+        """
+        Get a list of normalized callable functions for each registered tool.
+
+        Each function is designed to accept a single payload matching the
+        tool's expected schema, allowing for direct execution with
+        schema-validated data.
+
+        Returns:
+            List[Callable[..., Any]]: List of callable functions corresponding to tools.
+        """
+        fn_list = []
+
+        for tool in self.list:
+            
+            # add json schema to the model doc
+            tool.schema.__doc__ = "Pay attention to the schema, dont miss. " + json.dumps(tool.schema.model_json_schema(mode="serialization"))
+            
+            schema_cls: Type[BaseModel] = tool.schema
+
+            # Create closure to capture tool and schema_cls
+            def make_tool_function(tool_ref, schema_ref, is_async: bool = False):
+                """
+                Factory that builds a normalized tool function.
+                - If is_async=True, returns an async function (awaitable).
+                - If is_async=False, returns a sync function (blocking, calls run_sync).
+                """
+
+                async def _execute(payload_dict: dict) -> Any:
+                    return await tool_ref.ainvoke(
+                        agent_id=self.configuration.state.agent.id,
+                        agent_version=self.configuration.state.agent.version,
+                        payload=payload_dict,
+                        configuration=self.configuration,
+                        task_id=(
+                            self.configuration.state.task.id
+                            if self.configuration.state.task
+                            else None
+                        ),
+                    )
+
+                if is_async:
+
+                    async def tool_function(payload: schema_ref) -> Any:
+                        """
+                        Normalized async tool function that accepts a single Pydantic model payload.
+                        """
+                        payload_dict = payload.model_dump(exclude_none=True)
+                        return await _execute(payload_dict)
+
+                else:
+
+                    def tool_function(payload: schema_ref) -> Any:
+                        """
+                        Normalized sync tool function that accepts a single Pydantic model payload.
+                        """
+                        if isinstance(payload, dict):
+                            payload_dict = payload
+                        else:
+                            payload_dict = payload.model_dump(exclude_none=True)
+                        return run_sync(_execute(payload_dict))
+
+                # --- Metadata ---
+                tool_function.__name__ = tool_ref.id
+                tool_function.__doc__ = tool_ref.description or tool_ref.name
+
+                # --- Signature ---
+                payload_param = Parameter(
+                    name="payload",
+                    kind=Parameter.POSITIONAL_OR_KEYWORD,
+                    annotation=schema_ref,
+                )
+                tool_function.__signature__ = Signature(
+                    [payload_param],
+                    return_annotation=Any,
+                )
+
+                # --- Annotations (for libraries that read __annotations__) ---
+                ann = getattr(tool_function, "__annotations__", {})
+                ann["payload"] = schema_ref
+                ann["return"] = Any
+                tool_function.__annotations__ = ann
+
+                return tool_function
+
+            fn = make_tool_function(tool, schema_cls, self.is_async)
+            fn_list.append(fn)
+
+        return fn_list
+
+    async def aload_tool_by_id(self, tool_id: str):
+        try:
+            connector_id, operation_id = tool_id.split("_")
+            client = APIClient(configuration=self.configuration)
+            tool = await client.make_request(
+                path=APIRoute.GetOrInvokeToolById.format(tool_id=tool_id)
+            )
+            self.tools = [
+                Tool(
+                    configuration=self.configuration,
+                    **tool,
+                    method="POST",
+                    path="tool",
+                    is_standalone=True,
+                    connector_id=connector_id,
+                    operation_id=operation_id,
+                )
+            ]
+        except Exception as e:
+            raise ModuleException(500, f"Failed to load tool by id - {str(e)}")
+
+    def load_tool_by_id(self, tool_id: str):
+        return run_sync(self.aload_tool_by_id(tool_id=tool_id))

xpander_sdk/modules/tools_repository/utils/generic.py

@@ -0,0 +1,57 @@
+import re
+from typing import Any, List
+
+
+def deep_merge(a: dict, b: dict) -> dict:
+    result = a.copy()
+    for key, b_value in b.items():
+        if key in result:
+            a_value = result[key]
+            if isinstance(a_value, dict) and isinstance(b_value, dict):
+                result[key] = deep_merge(a_value, b_value)
+            else:
+                result[key] = b_value
+        else:
+            result[key] = b_value
+    return result
+
+
+def json_type_to_python(json_type: str, prop_schema: dict = None):
+    # Handle anyOf schemas (union types)
+    if prop_schema and "anyOf" in prop_schema:
+        # Extract non-null types from anyOf
+        non_null_types = []
+        for any_of_item in prop_schema["anyOf"]:
+            item_type = any_of_item.get("type")
+            if item_type and item_type != "null":
+                non_null_types.append(json_type_to_python(item_type, any_of_item))
+        
+        # Return the first non-null type (this will be wrapped in Optional later)
+        if non_null_types:
+            return non_null_types[0]
+        else:
+            return Any
+    
+    # Extend to support arrays of objects, etc.
+    if json_type == "array" and prop_schema:
+        items = prop_schema.get("items", {})
+        item_type = json_type_to_python(items.get("type"), items)
+        return List[item_type]
+    
+    return {
+        "string": str,
+        "integer": int,
+        "number": float,
+        "boolean": bool,
+        "object": dict,
+        "array": list,
+        None: Any
+    }.get(json_type, Any)
+
+
+def pascal_case(name: str) -> str:
+    """
+    Converts a string to PascalCase.
+    Example: 'my_tool-name' -> 'MyToolName'
+    """
+    return "".join(word.capitalize() for word in re.split(r"[\s_\-]+", name) if word)

xpander_sdk/modules/tools_repository/utils/local_tools.py

@@ -0,0 +1,52 @@
+import inspect
+import asyncio
+from inspect import Parameter
+from pydantic import BaseModel
+from typing import Any, get_type_hints
+
+
+async def invoke_local_fn(fn, payload: Any):
+    sig = inspect.signature(fn)
+    params = sig.parameters
+    is_coroutine = inspect.iscoroutinefunction(fn)
+    type_hints = get_type_hints(fn)
+
+    args = []
+    kwargs = {}
+
+    def build_param_value(param_name, param_type):
+        if isinstance(payload, dict):
+            if issubclass(param_type, BaseModel):
+                return param_type(**payload.get(param_name, {}))
+            elif param_name in payload:
+                return payload[param_name]
+            else:
+                raise TypeError(f"Missing required argument: {param_name}")
+        else:
+            if issubclass(param_type, BaseModel) and isinstance(payload, dict):
+                return param_type(**payload)
+            return payload  # fallback for scalar values
+
+    # Handle no parameters
+    if not params:
+        return await fn() if is_coroutine else await asyncio.to_thread(fn)
+
+    # Match each parameter
+    for name, param in params.items():
+        expected_type = type_hints.get(name, Any)
+        if param.kind in [Parameter.POSITIONAL_ONLY, Parameter.POSITIONAL_OR_KEYWORD]:
+            val = build_param_value(name, expected_type)
+            args.append(val)
+        elif param.kind == Parameter.KEYWORD_ONLY:
+            val = build_param_value(name, expected_type)
+            kwargs[name] = val
+        elif param.kind == Parameter.VAR_POSITIONAL:
+            if isinstance(payload, (list, tuple)):
+                args.extend(payload)
+        elif param.kind == Parameter.VAR_KEYWORD:
+            if isinstance(payload, dict):
+                kwargs.update(payload)
+
+    if is_coroutine:
+        return await fn(*args, **kwargs)
+    return await asyncio.to_thread(fn, *args, **kwargs)

xpander_sdk/modules/tools_repository/utils/schemas.py

@@ -0,0 +1,308 @@
+from typing import Optional, Type
+from copy import deepcopy
+
+from pydantic import BaseModel, ConfigDict, Field, create_model
+
+from xpander_sdk.modules.tools_repository.utils.generic import json_type_to_python, pascal_case
+
+from pydantic import BaseModel, create_model, ConfigDict
+from typing import Optional, Type, Dict, Any
+
+def build_model_from_schema(
+    model_name: str,
+    schema: dict,
+    with_defaults: Optional[bool] = False
+) -> Type[BaseModel]:
+    fields = {}
+    properties = schema.get("properties", {})
+    required = set(schema.get("required", []))
+    
+    # CRITICAL FIX: Add default={} to empty parameter containers
+    # This allows LLMs to omit them when they have no actual content
+    for param_name in ("body_params", "query_params", "path_params", "headers"):
+        if param_name in properties:
+            param_schema = properties[param_name]
+            if (param_schema.get("type") == "object" and
+                "properties" in param_schema and
+                len(param_schema.get("properties", {})) == 0 and
+                "default" not in param_schema):
+                param_schema["default"] = {}
+
+    FIELD_SPECS = {
+        "body_params": (
+            Optional[Dict[str, Any]],
+            Field(
+                default={},
+                description="Request body parameters (default: empty object)."
+            )
+        ),
+        "query_params": (
+            Optional[Dict[str, Any]],
+            Field(
+                default={},
+                description="Request query parameters (default: empty object)."
+            )
+        ),
+        "path_params": (
+            Optional[Dict[str, Any]],
+            Field(
+                default={},
+                description="Request path parameters (default: empty object)."
+            )
+        ),
+    }
+
+    # If with_defaults is True and schema is empty, set all three params
+    if with_defaults and not properties:
+        fields = FIELD_SPECS.copy()
+    else:
+        for prop_name, prop_schema in properties.items():
+            # Skip invalid field names starting with "_"
+            if prop_name.startswith("_"):
+                continue
+            prop_type = prop_schema.get("type")
+            description = prop_schema.get("description", None)
+            default = prop_schema.get("default", None)
+
+            # Nested object support
+            # CRITICAL: Check if this is an empty parameter container
+            is_empty_param_container = False
+            if prop_type == "object" and "properties" in prop_schema:
+                nested_props = prop_schema.get("properties", {})
+                nested_required = prop_schema.get("required", [])
+                # Empty if no properties or all properties are optional/empty
+                is_empty_param_container = len(nested_props) == 0 or \
+                    (len(nested_required) == 0 and all(
+                        p.get("type") == "object" and len(p.get("properties", {})) == 0 
+                        for p in nested_props.values()
+                    ))
+                
+                # For empty parameter containers, use Dict instead of nested model
+                if is_empty_param_container and prop_name in ("body_params", "query_params", "path_params", "headers"):
+                    base_type = Dict[str, Any]
+                else:
+                    nested_model_name = f"{model_name}{pascal_case(prop_name)}"
+                    base_type = build_model_from_schema(nested_model_name, prop_schema)
+            else:
+                # Pass the full property schema to handle anyOf correctly
+                base_type = json_type_to_python(prop_type, prop_schema)
+
+            # Field annotation and Field() construction
+            # IMPORTANT: For fields marked as required in the JSON schema, don't wrap in Optional[]
+            # Even if they might be nullable, the type annotation determines Pydantic's required array
+            # EXCEPTION: Empty parameter containers should always be Optional with default={}
+            if is_empty_param_container:
+                annotation = Optional[base_type]
+            else:
+                annotation = base_type if prop_name in required else Optional[base_type]
+            
+            field_args = {}
+            
+            # Enhance description to clarify optional vs required status
+            enhanced_description = description or f"Parameter: {prop_name}"
+            if is_empty_param_container:
+                enhanced_description = f"[OPTIONAL - empty container] {enhanced_description} (default: empty object)"
+            elif prop_name in required:
+                if default is not None:
+                    enhanced_description = f"[REQUIRED with default] {enhanced_description} (default: {default})"
+                else:
+                    enhanced_description = f"[REQUIRED] {enhanced_description}"
+            else:
+                if default is not None:
+                    enhanced_description = f"[OPTIONAL with default] {enhanced_description} (default: {default})"
+                else:
+                    enhanced_description = f"[OPTIONAL] {enhanced_description} - can be omitted or set to null"
+            
+            field_args["description"] = enhanced_description
+
+            # Set default or ... (required)
+            # The key insight: Pydantic includes a field in the 'required' array of model_json_schema()
+            # if and only if the field has Field(...) (no default) AND is not Optional[] in type annotation
+            if is_empty_param_container:
+                # Empty containers always get default={}
+                field_info = Field(default={}, **field_args)
+            elif prop_name in required:
+                if default is not None:
+                    # Has a default but still required in schema - use the default
+                    field_info = Field(default, **field_args)
+                else:
+                    # No default and required - use ellipsis  
+                    field_info = Field(..., **field_args)
+            else:
+                # Optional fields - always provide a default to keep them out of 'required' array
+                if default is not None:
+                    field_info = Field(default, **field_args)
+                else:
+                    # Optional with no explicit default - use None
+                    field_info = Field(default=None, **field_args)
+
+            fields[prop_name] = (annotation, field_info)
+
+
+        # Ensure the presence of all three params if with_defaults is True
+        if with_defaults:
+            for key, (annotation, field_info) in FIELD_SPECS.items():
+                if key not in fields:
+                    fields[key] = (annotation, field_info)
+
+    # After building fields, relax body/query/path if present and not already optional with a default
+    # CRITICAL FIX: Empty parameter containers (query_params, path_params, body_params) that are marked
+    # as required but have no actual properties should default to {} so LLMs can omit them
+    for param in ("body_params", "query_params", "path_params"):
+        if param in fields:
+            ann, fld = fields[param]
+            # Check if this field is required (has Ellipsis as default) or has no useful default
+            has_no_default = (getattr(fld, 'default', ...) is ... or 
+                            getattr(fld, 'default', None) is None) and \
+                           getattr(fld, 'default_factory', None) is None
+            
+            # Always make param containers Optional with default={} to allow LLMs to omit empty ones
+            if has_no_default or ann is dict or ann is Dict[str, Any] or \
+               (hasattr(ann, '__origin__') and ann.__origin__ in (dict, Dict)):
+                desc = getattr(fld, 'description', None) or f"Request {param.replace('_', ' ')} (default: empty object)."
+                fields[param] = (
+                    Optional[Dict[str, Any]],
+                    Field(default={}, description=desc)
+                )
+
+    model_config = ConfigDict(
+        strict=False,  # Allow flexibility with types to handle AI agent inputs better
+        extra="allow",
+        title=model_name,
+        description="IMPORTANT: Required fields must be provided. Optional fields can be omitted entirely or set to null. All parameters with defaults will use those defaults if not provided. Check the 'required' array in the schema to see which fields are mandatory."
+    )
+    return create_model(
+        model_name,
+        __config__=model_config,
+        **fields
+    )
+
+def schema_enforcement_block_and_descriptions(target_schema: dict, reference_schema: dict) -> dict:
+    updated_schema = deepcopy(target_schema)
+
+    def update_properties(target_props: dict, ref_props: dict):
+        to_delete = []
+        for key, ref_value in ref_props.items():
+            if key not in target_props:
+                continue
+
+            # Remove if isBlocked or permanentValue present
+            if ref_value.get("isBlocked") is True or "permanentValue" in ref_value:
+                to_delete.append(key)
+                continue
+
+            target_field = target_props[key]
+
+            # Override description if available
+            if "description" in ref_value:
+                target_field["description"] = ref_value["description"]
+
+            # Recursively update nested objects
+            if (
+                ref_value.get("type") == "object"
+                and "properties" in ref_value
+                and target_field.get("type") == "object"
+                and "properties" in target_field
+            ):
+                update_properties(target_field["properties"], ref_value["properties"])
+
+        # Remove blocked/permanent fields
+        for key in to_delete:
+            del target_props[key]
+
+    def walk(target: dict, ref: dict):
+        if not isinstance(target, dict) or not isinstance(ref, dict):
+            return
+
+        if target.get("type") == "object" and "properties" in target and "properties" in ref:
+            update_properties(target["properties"], ref["properties"])
+            for key in list(target["properties"]):
+                walk(target["properties"][key], ref["properties"].get(key, {}))
+
+    walk(updated_schema, reference_schema)
+    return updated_schema
+
+def apply_permanent_values_to_payload(schema: dict, payload: dict | list) -> dict | list:
+    payload = deepcopy(payload)
+
+    def apply(schema_node, payload_node):
+        if not isinstance(schema_node, dict):
+            return
+
+        schema_type = schema_node.get("type")
+
+        if schema_type == "object" and "properties" in schema_node:
+            if not isinstance(payload_node, dict):
+                return  # skip if payload_node is not an object
+
+            for key, sub_schema in schema_node["properties"].items():
+                # If permanentValue is present, enforce it
+                if "permanentValue" in sub_schema:
+                    payload_node[key] = sub_schema["permanentValue"]
+
+                # Recurse
+                if sub_schema.get("type") == "object":
+                    payload_node.setdefault(key, {})
+                    apply(sub_schema, payload_node[key])
+                elif sub_schema.get("type") == "array" and sub_schema.get("items", {}).get("type") == "object":
+                    payload_node.setdefault(key, [{}])  # if empty, create one
+                    if isinstance(payload_node[key], list):
+                        for item in payload_node[key]:
+                            apply(sub_schema["items"], item)
+
+        elif schema_type == "array" and schema_node.get("items", {}).get("type") == "object":
+            if isinstance(payload_node, list):
+                for item in payload_node:
+                    apply(schema_node["items"], item)
+
+    apply(schema, payload)
+    return payload
+
+
+def enforce_schema_on_response(schema: dict, response: dict | list) -> dict | list:
+    response = deepcopy(response)
+
+    def apply(schema_node, response_node):
+        if not isinstance(schema_node, dict):
+            return
+
+        schema_type = schema_node.get("type")
+
+        if schema_type == "object" and "properties" in schema_node:
+            if not isinstance(response_node, dict):
+                return
+
+            for key in list(response_node.keys()):
+                sub_schema = schema_node["properties"].get(key)
+
+                # If key not in schema, ignore
+                if not sub_schema:
+                    continue
+
+                # Remove if blocked
+                if sub_schema.get("isBlocked"):
+                    del response_node[key]
+                    continue
+
+                # Set permanentValue if defined
+                if "permanentValue" in sub_schema:
+                    response_node[key] = sub_schema["permanentValue"]
+
+                # Recurse if it's a nested object
+                if sub_schema.get("type") == "object" and isinstance(response_node.get(key), dict):
+                    apply(sub_schema, response_node[key])
+
+                # Recurse if it's an array of objects
+                elif sub_schema.get("type") == "array" and isinstance(response_node.get(key), list):
+                    item_schema = sub_schema.get("items")
+                    if item_schema and item_schema.get("type") == "object":
+                        for item in response_node[key]:
+                            apply(item_schema, item)
+
+        elif schema_type == "array" and schema_node.get("items", {}).get("type") == "object":
+            if isinstance(response_node, list):
+                for item in response_node:
+                    apply(schema_node["items"], item)
+
+    apply(schema, response)
+    return response