alita-sdk 0.3.379__py3-none-any.whl → 0.3.627__py3-none-any.whl

alita_sdk/runtime/utils/serialization.py

@@ -0,0 +1,155 @@
+"""
+Serialization utilities for safe JSON encoding of complex objects.
+
+Handles Pydantic models, LangChain messages, datetime objects, and other
+non-standard types that may appear in state variables.
+"""
+import json
+import logging
+from datetime import datetime, date
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def _convert_to_serializable(obj: Any, _seen: set = None) -> Any:
+    """
+    Recursively convert an object to JSON-serializable primitives.
+
+    Handles nested dicts and lists that may contain non-serializable objects.
+    Uses a seen set to prevent infinite recursion with circular references.
+
+    Args:
+        obj: Any object to convert
+        _seen: Internal set to track seen object ids (for circular reference detection)
+
+    Returns:
+        JSON-serializable representation of the object
+    """
+    # Initialize seen set for circular reference detection
+    if _seen is None:
+        _seen = set()
+
+    # Check for circular references (only for mutable objects)
+    obj_id = id(obj)
+    if isinstance(obj, (dict, list, set)) and obj_id in _seen:
+        return f"<circular reference: {type(obj).__name__}>"
+
+    # Primitives - return as-is
+    if obj is None or isinstance(obj, (str, int, float, bool)):
+        return obj
+
+    # Add to seen set for mutable containers
+    if isinstance(obj, (dict, list, set)):
+        _seen = _seen | {obj_id}  # Create new set to avoid mutation issues
+
+    # Dict - recursively process all values
+    if isinstance(obj, dict):
+        return {
+            _convert_to_serializable(k, _seen): _convert_to_serializable(v, _seen)
+            for k, v in obj.items()
+        }
+
+    # List/tuple - recursively process all items
+    if isinstance(obj, (list, tuple)):
+        return [_convert_to_serializable(item, _seen) for item in obj]
+
+    # Set - convert to list and process
+    if isinstance(obj, set):
+        return [_convert_to_serializable(item, _seen) for item in obj]
+
+    # Bytes - decode to string
+    if isinstance(obj, bytes):
+        try:
+            return obj.decode('utf-8')
+        except UnicodeDecodeError:
+            return obj.decode('utf-8', errors='replace')
+
+    # Datetime objects
+    if isinstance(obj, datetime):
+        return obj.isoformat()
+    if isinstance(obj, date):
+        return obj.isoformat()
+
+    # Pydantic BaseModel (v2) - check for model_dump method
+    if hasattr(obj, 'model_dump') and callable(getattr(obj, 'model_dump')):
+        try:
+            return _convert_to_serializable(obj.model_dump(), _seen)
+        except Exception as e:
+            logger.debug(f"Failed to call model_dump on {type(obj).__name__}: {e}")
+
+    # Pydantic BaseModel (v1) - check for dict method
+    if hasattr(obj, 'dict') and callable(getattr(obj, 'dict')) and hasattr(obj, '__fields__'):
+        try:
+            return _convert_to_serializable(obj.dict(), _seen)
+        except Exception as e:
+            logger.debug(f"Failed to call dict on {type(obj).__name__}: {e}")
+
+    # LangChain BaseMessage - extract key fields
+    if hasattr(obj, 'type') and hasattr(obj, 'content'):
+        try:
+            result = {
+                "type": obj.type,
+                "content": _convert_to_serializable(obj.content, _seen),
+            }
+            if hasattr(obj, 'additional_kwargs') and obj.additional_kwargs:
+                result["additional_kwargs"] = _convert_to_serializable(obj.additional_kwargs, _seen)
+            if hasattr(obj, 'name') and obj.name:
+                result["name"] = obj.name
+            return result
+        except Exception as e:
+            logger.debug(f"Failed to extract message fields from {type(obj).__name__}: {e}")
+
+    # Objects with __dict__ attribute (custom classes)
+    if hasattr(obj, '__dict__'):
+        try:
+            return _convert_to_serializable(obj.__dict__, _seen)
+        except Exception as e:
+            logger.debug(f"Failed to serialize __dict__ of {type(obj).__name__}: {e}")
+
+    # UUID objects
+    if hasattr(obj, 'hex') and hasattr(obj, 'int'):
+        return str(obj)
+
+    # Enum objects
+    if hasattr(obj, 'value') and hasattr(obj, 'name') and hasattr(obj.__class__, '__members__'):
+        return obj.value
+
+    # Last resort - convert to string
+    try:
+        return str(obj)
+    except Exception:
+        return f"<non-serializable: {type(obj).__name__}>"
+
+
+def safe_serialize(obj: Any, **kwargs) -> str:
+    """
+    Safely serialize any object to a JSON string.
+
+    Pre-processes the entire object tree to convert non-serializable
+    objects before passing to json.dumps. This ensures nested dicts
+    and lists with non-standard objects are handled correctly.
+
+    Args:
+        obj: Any object to serialize
+        **kwargs: Additional arguments passed to json.dumps
+            (e.g., indent, sort_keys)
+
+    Returns:
+        JSON string representation of the object
+
+    Example:
+        >>> from pydantic import BaseModel
+        >>> class User(BaseModel):
+        ...     name: str
+        >>> state = {"user": User(name="Alice"), "count": 5}
+        >>> safe_serialize(state)
+        '{"user": {"name": "Alice"}, "count": 5}'
+    """
+    # Pre-process the entire object tree
+    serializable = _convert_to_serializable(obj)
+
+    # Set defaults
+    kwargs.setdefault('ensure_ascii', False)
+
+    return json.dumps(serializable, **kwargs)

alita_sdk/runtime/utils/streamlit.py

@@ -287,7 +287,6 @@ def run_streamlit(st, ai_icon=None, user_icon=None):
                     model_config={
                         "temperature": 0.1,
                         "max_tokens": 1000,
-                        "top_p": 1.0
                     }
                 )
             except Exception as e:
@@ -868,10 +867,24 @@ def run_streamlit(st, ai_icon=None, user_icon=None):
                                 label = f"{'🔒 ' if is_secret else ''}{'*' if is_required else ''}{field_name.replace('_', ' ').title()}"
                                 
                                 if field_type == 'string':
-                                    if is_secret:
+                                    # Check if this is an enum field
+                                    if field_schema.get('enum'):
+                                        # Dropdown for enum values
+                                        options = field_schema['enum']
+                                        default_index = 0
+                                        if default_value and str(default_value) in options:
+                                            default_index = options.index(str(default_value))
+                                        toolkit_config_values[field_name] = st.selectbox(
+                                            label,
+                                            options=options,
+                                            index=default_index,
+                                            help=field_description,
+                                            key=f"config_{field_name}_{selected_toolkit_idx}"
+                                        )
+                                    elif is_secret:
                                         toolkit_config_values[field_name] = st.text_input(
                                             label,
-                                            value=str(default_value) if default_value else '', 
+                                            value=str(default_value) if default_value else '',
                                             help=field_description,
                                             type="password",
                                             key=f"config_{field_name}_{selected_toolkit_idx}"
@@ -879,7 +892,7 @@ def run_streamlit(st, ai_icon=None, user_icon=None):
                                     else:
                                         toolkit_config_values[field_name] = st.text_input(
                                             label,
-                                            value=str(default_value) if default_value else '', 
+                                            value=str(default_value) if default_value else '',
                                             help=field_description,
                                             key=f"config_{field_name}_{selected_toolkit_idx}"
                                         )
@@ -971,6 +984,23 @@ def run_streamlit(st, ai_icon=None, user_icon=None):
                                                 key=f"config_{field_name}_{selected_toolkit_idx}"
                                             )
                                         toolkit_config_values[field_name] = [line.strip() for line in array_input.split('\n') if line.strip()]
+                                elif field_type == 'object':
+                                    # Handle object/dict types (like headers)
+                                    obj_input = st.text_area(
+                                        f"{label} (JSON object)",
+                                        value=json.dumps(default_value) if isinstance(default_value, dict) else str(default_value) if default_value else '',
+                                        help=f"{field_description} - Enter as JSON object, e.g. {{\"Authorization\": \"Bearer token\"}}",
+                                        placeholder='{"key": "value"}',
+                                        key=f"config_{field_name}_{selected_toolkit_idx}"
+                                    )
+                                    try:
+                                        if obj_input.strip():
+                                            toolkit_config_values[field_name] = json.loads(obj_input)
+                                        else:
+                                            toolkit_config_values[field_name] = None
+                                    except json.JSONDecodeError as e:
+                                        st.error(f"Invalid JSON format for {field_name}: {e}")
+                                        toolkit_config_values[field_name] = None
                         else:
                             st.info("This toolkit doesn't require additional configuration.")
                         
@@ -1225,7 +1255,6 @@ def run_streamlit(st, ai_icon=None, user_icon=None):
                     model_config={
                         "temperature": 0.1,
                         "max_tokens": 1000,
-                        "top_p": 1.0
                     }
                 )
             except Exception as e:
@@ -1356,20 +1385,18 @@ def run_streamlit(st, ai_icon=None, user_icon=None):
                                 help="Maximum number of tokens in the AI response"
                             )
                             
-                            top_p = st.slider(
-                                "Top-p:",
-                                min_value=0.1,
-                                max_value=1.0,
-                                value=1.0,
-                                step=0.1,
-                                help="Controls diversity via nucleus sampling"
+                            reasoning_effort = st.selectbox(
+                                "Reasoning effort:",
+                                options=['null', 'low', 'medium', 'high'],
+                                index=0,
+                                help="Higher effort better reasoning, slower response"
                             )
                         
                         # Create LLM config
                         llm_config = {
                             'max_tokens': max_tokens,
                             'temperature': temperature,
-                            'top_p': top_p
+                            'reasoning_effort': reasoning_effort
                         }
                         
                         col1, col2 = st.columns([3, 1])

alita_sdk/runtime/utils/toolkit_utils.py

@@ -12,7 +12,9 @@ logger = logging.getLogger(__name__)
 
 def instantiate_toolkit_with_client(toolkit_config: Dict[str, Any], 
                                    llm_client: Any, 
-                                   alita_client: Optional[Any] = None) -> List[Any]:
+                                   alita_client: Optional[Any] = None,
+                                   mcp_tokens: Optional[Dict[str, Any]] = None,
+                                   use_prefix: bool = False) -> List[Any]:
     """
     Instantiate a toolkit with LLM client support.
     
@@ -22,20 +24,25 @@ def instantiate_toolkit_with_client(toolkit_config: Dict[str, Any],
     Args:
         toolkit_config: Configuration dictionary for the toolkit
         llm_client: LLM client instance for tools that need LLM capabilities
-        client: Optional additional client instance
+        alita_client: Optional additional client instance
+        mcp_tokens: Optional dictionary of MCP OAuth tokens by server URL
+        use_prefix: If True, tools get prefixed with toolkit_name to prevent collisions
+                   (for agent use). If False, tools use base names only (for testing interface).
+                   Default False for backward compatibility with testing.
     
     Returns:
         List of instantiated tools from the toolkit
         
     Raises:
         ValueError: If required configuration or client is missing
+        McpAuthorizationRequired: If MCP server requires OAuth authorization
         Exception: If toolkit instantiation fails
     """
+    toolkit_name = toolkit_config.get('toolkit_name', 'unknown')
     try:
         from ..toolkits.tools import get_tools
         
-        toolkit_name = toolkit_config.get('toolkit_name')
-        if not toolkit_name:
+        if not toolkit_name or toolkit_name == 'unknown':
             raise ValueError("toolkit_name is required in configuration")
         
         if not llm_client:
@@ -46,18 +53,24 @@ def instantiate_toolkit_with_client(toolkit_config: Dict[str, Any],
         # Log the configuration being used
         logger.info(f"Instantiating toolkit {toolkit_name} with LLM client")
         logger.debug(f"Toolkit {toolkit_name} configuration: {toolkit_config}")
-        
+
+        # Use toolkit type from config, or fall back to lowercase toolkit name
+        toolkit_type = toolkit_config.get('type', toolkit_name.lower())
+
         # Create a tool configuration dict with required fields
+        # Note: MCP toolkit always requires toolkit_name, other toolkits respect use_prefix flag
+        # Note: 'name' is always set for provider-based toolkits (used by provider_worker.utils.tools)
         tool_config = {
             'id': toolkit_config.get('id', random.randint(1, 1000000)),
-            'type': toolkit_config.get('type', toolkit_name.lower()),
+            'type': toolkit_config.get('type', toolkit_type),
             'settings': settings,
-            'toolkit_name': toolkit_name
+            'name': toolkit_name,  # Always pass name for provider toolkits
+            'toolkit_name': toolkit_name if (use_prefix or toolkit_type == 'mcp') else None
         }
         
         # Get tools using the toolkit configuration with clients
-        # Parameter order: get_tools(tools_list, alita_client, llm, memory_store)
-        tools = get_tools([tool_config], alita_client, llm_client)
+        # Parameter order: get_tools(tools_list, alita_client, llm, memory_store, debug_mode, mcp_tokens)
+        tools = get_tools([tool_config], alita_client, llm_client, mcp_tokens=mcp_tokens)
         
         if not tools:
             logger.warning(f"No tools returned for toolkit {toolkit_name}")
@@ -67,6 +80,14 @@ def instantiate_toolkit_with_client(toolkit_config: Dict[str, Any],
         return tools
             
     except Exception as e:
+        # Re-raise McpAuthorizationRequired without logging as error
+        from ..utils.mcp_oauth import McpAuthorizationRequired
+        
+        if isinstance(e, McpAuthorizationRequired):
+            logger.info(f"Toolkit {toolkit_name} requires MCP OAuth authorization")
+            raise
+        
+        # Log and re-raise other errors
         logger.error(f"Error instantiating toolkit {toolkit_name} with client: {str(e)}")
         raise
 

alita_sdk/runtime/utils/utils.py

@@ -1,6 +1,11 @@
+import base64
+import logging
 import re
 from enum import Enum
+from typing import Any
 
+# DEPRECATED: Tool names no longer use prefixes
+# Kept for backward compatibility only
 TOOLKIT_SPLITTER = "___"
 
 class IndexerKeywords(Enum):
@@ -30,3 +35,34 @@ def clean_node_str(s: str) -> str:
     """Cleans a node string by removing all non-alphanumeric characters except underscores and spaces."""
     cleaned_string = re.sub(r'[^\w\s]', '', s)
     return cleaned_string
+
+
+def resolve_image_from_cache(client: Any, cached_image_id: str) -> bytes:
+    """
+    Resolve cached_image_id from client's image cache and return decoded binary data.
+
+    Args:
+        client: AlitaClient instance with _generated_images_cache attribute
+        cached_image_id: The cached image ID to resolve
+
+    Returns:
+        bytes: Decoded binary image data
+
+    Raises:
+        ValueError: If cached_image_id not found or decoding fails
+    """
+    cache = getattr(client, '_generated_images_cache', {})
+
+    if cached_image_id not in cache:
+        raise ValueError(f"Image reference '{cached_image_id}' not found. The image may have expired.")
+
+    cached_data = cache[cached_image_id]
+    base64_data = cached_data.get('base64_data', '')
+    logging.debug(f"Resolved cached_image_id '{cached_image_id}' from cache (length: {len(base64_data)} chars)")
+    # Decode base64 to binary data for image files
+    try:
+        binary_data = base64.b64decode(base64_data)
+        logging.debug(f"Decoded base64 to binary data ({len(binary_data)} bytes)")
+        return binary_data
+    except Exception as e:
+        raise ValueError(f"Failed to decode image data for '{cached_image_id}': {e}")

alita_sdk/tools/__init__.py

@@ -13,6 +13,30 @@ AVAILABLE_TOOLS = {}
 AVAILABLE_TOOLKITS = {}
 FAILED_IMPORTS = {}
 
+
+def _inject_toolkit_id(tool_conf: dict, toolkit_tools) -> None:
+    """Inject `toolkit_id` into tools that expose `api_wrapper.toolkit_id`.
+
+    This reads 'id' from the tool configuration and, if it is an integer,
+    assigns it to the 'toolkit_id' attribute of the 'api_wrapper' for each
+    tool in 'toolkit_tools' that supports it.
+
+    Args:
+        tool_conf: Raw tool configuration item from 'tools_list'.
+        toolkit_tools: List of instantiated tools produced by a toolkit.
+    """
+    toolkit_id = tool_conf.get('id')
+    if isinstance(toolkit_id, int):
+        for t in toolkit_tools:
+            if hasattr(t, 'api_wrapper') and hasattr(t.api_wrapper, 'toolkit_id'):
+                t.api_wrapper.toolkit_id = toolkit_id
+    else:
+        logger.error(
+            f"Toolkit ID is missing or not an integer for tool "
+            f"`{tool_conf.get('type', '')}` with name `{tool_conf.get('name', '')}`"
+        )
+
+
 def _safe_import_tool(tool_name, module_path, get_tools_name=None, toolkit_class_name=None):
     """Safely import a tool module and register available functions/classes."""
     try:
@@ -21,6 +45,12 @@ def _safe_import_tool(tool_name, module_path, get_tools_name=None, toolkit_class
         imported = {}
         if get_tools_name and hasattr(module, get_tools_name):
             imported['get_tools'] = getattr(module, get_tools_name)
+        
+        if hasattr(module, 'get_toolkit'):
+            imported['get_toolkit'] = getattr(module, 'get_toolkit')
+
+        if hasattr(module, 'get_toolkit_available_tools'):
+            imported['get_toolkit_available_tools'] = getattr(module, 'get_toolkit_available_tools')
 
         if toolkit_class_name and hasattr(module, toolkit_class_name):
             imported['toolkit_class'] = getattr(module, toolkit_class_name)
@@ -34,9 +64,10 @@ def _safe_import_tool(tool_name, module_path, get_tools_name=None, toolkit_class
         FAILED_IMPORTS[tool_name] = str(e)
         logger.debug(f"Failed to import {tool_name}: {e}")
 
+
 # Safe imports for all tools
 _safe_import_tool('github', 'github', 'get_tools', 'AlitaGitHubToolkit')
-_safe_import_tool('openapi', 'openapi', 'get_tools')
+_safe_import_tool('openapi', 'openapi', 'get_tools', 'AlitaOpenAPIToolkit')
 _safe_import_tool('jira', 'jira', 'get_tools', 'JiraToolkit')
 _safe_import_tool('confluence', 'confluence', 'get_tools', 'ConfluenceToolkit')
 _safe_import_tool('service_now', 'servicenow', 'get_tools', 'ServiceNowToolkit')
@@ -71,7 +102,7 @@ _safe_import_tool('k8s', 'cloud.k8s', None, 'KubernetesToolkit')
 _safe_import_tool('elastic', 'elastic', None, 'ElasticToolkit')
 _safe_import_tool('keycloak', 'keycloak', None, 'KeycloakToolkit')
 _safe_import_tool('localgit', 'localgit', None, 'AlitaLocalGitToolkit')
-_safe_import_tool('pandas', 'pandas', 'get_tools', 'PandasToolkit')
+# pandas toolkit removed - use Data Analysis internal tool instead
 _safe_import_tool('azure_search', 'azure_ai.search', 'get_tools', 'AzureSearchToolkit')
 _safe_import_tool('figma', 'figma', 'get_tools', 'FigmaToolkit')
 _safe_import_tool('salesforce', 'salesforce', 'get_tools', 'SalesforceToolkit')
@@ -90,64 +121,83 @@ available_count = len(AVAILABLE_TOOLS)
 total_attempted = len(AVAILABLE_TOOLS) + len(FAILED_IMPORTS)
 logger.info(f"Tool imports completed: {available_count}/{total_attempted} successful")
 
+# Import community module to trigger community toolkit registration
+try:
+    from alita_sdk import community  # noqa: F401
+    logger.debug("Community toolkits registered successfully")
+except ImportError as e:
+    logger.debug(f"Community module not available: {e}")
+
+
 def get_tools(tools_list, alita, llm, store: Optional[BaseStore] = None, *args, **kwargs):
     tools = []
+
     for tool in tools_list:
-        # validate tool name syntax - it cannot be started with _
-        for tool_name in tool.get('settings', {}).get('selected_tools', []):
-            if isinstance(tool_name, str) and tool_name.startswith('_'):
-                raise ValueError(f"Tool name '{tool_name}' from toolkit '{tool.get('type', '')}' cannot start with '_'")
-        if not tool.get('settings'):
+        toolkit_tools = []
+        settings = tool.get('settings')
+
+        # Skip tools without settings early
+        if not settings:
             logger.warning(f"Tool '{tool.get('type', '')}' has no settings, skipping...")
             continue
-        tool['settings']['alita'] = alita
-        tool['settings']['llm'] = llm
-        tool['settings']['store'] = store
-        tool_type = tool['type']
 
-        # Handle special cases for ADO tools
-        if tool_type in ['ado_boards', 'ado_wiki', 'ado_plans']:
-            tools.extend(AVAILABLE_TOOLS['ado']['get_tools'](tool_type, tool))
+        # Validate tool names once
+        selected_tools = settings.get('selected_tools', [])
+        invalid_tools = [name for name in selected_tools if isinstance(name, str) and name.startswith('_')]
+        if invalid_tools:
+            raise ValueError(f"Tool names {invalid_tools} from toolkit '{tool.get('type', '')}' cannot start with '_'")
 
-        # Check if tool is available and has get_tools function
-        elif tool_type in AVAILABLE_TOOLS and 'get_tools' in AVAILABLE_TOOLS[tool_type]:
-            try:
-                get_tools_func = AVAILABLE_TOOLS[tool_type]['get_tools']
-                tools.extend(get_tools_func(tool))
+        # Cache tool type and add common settings
+        tool_type = tool['type']
+        settings['alita'] = alita
+        settings['llm'] = llm
+        settings['store'] = store
 
-            except Exception as e:
-                logger.error(f"Error getting tools for {tool_type}: {e}")
-                raise ToolException(f"Error getting tools for {tool_type}: {e}")
+        # Set pgvector collection schema if present
+        if settings.get('pgvector_configuration'):
+            # Use tool id if available, otherwise use toolkit_name or type as fallback
+            collection_id = tool.get('id') or tool.get('toolkit_name') or tool_type
+            settings['pgvector_configuration']['collection_schema'] = str(collection_id)
 
-        # Handle ADO repos special case (it might be requested as azure_devops_repos)
+        # Handle ADO special cases
+        if tool_type in ['ado_boards', 'ado_wiki', 'ado_plans']:
+            toolkit_tools.extend(AVAILABLE_TOOLS['ado']['get_tools'](tool_type, tool))
         elif tool_type in ['ado_repos', 'azure_devops_repos'] and 'ado_repos' in AVAILABLE_TOOLS:
             try:
-                get_tools_func = AVAILABLE_TOOLS['ado_repos']['get_tools']
-                tools.extend(get_tools_func(tool))
+                toolkit_tools.extend(AVAILABLE_TOOLS['ado_repos']['get_tools'](tool))
             except Exception as e:
                 logger.error(f"Error getting ADO repos tools: {e}")
-
-        # Handle custom modules
-        elif tool.get("settings", {}).get("module"):
+        elif tool_type == 'mcp':
+            logger.debug(f"Skipping MCP toolkit '{tool.get('toolkit_name')}' - handled by runtime toolkit system")
+        elif tool_type == 'planning':
+            logger.debug(f"Skipping planning toolkit '{tool.get('toolkit_name')}' - handled by runtime toolkit system")
+        elif tool_type in AVAILABLE_TOOLS and 'get_tools' in AVAILABLE_TOOLS[tool_type]:
+            try:
+                toolkit_tools.extend(AVAILABLE_TOOLS[tool_type]['get_tools'](tool))
+            except Exception as e:
+                logger.error(f"Error getting tools for {tool_type}: {e}")
+                raise ToolException(f"Error getting tools for {tool_type}: {e}")
+        elif settings.get("module"):
             try:
-                settings = tool.get("settings", {})
                 mod = import_module(settings.pop("module"))
                 tkitclass = getattr(mod, settings.pop("class"))
-                #
-                get_toolkit_params = tool["settings"].copy()
+                get_toolkit_params = settings.copy()
                 get_toolkit_params["name"] = tool.get("name")
-                #
                 toolkit = tkitclass.get_toolkit(**get_toolkit_params)
-                tools.extend(toolkit.get_tools())
+                toolkit_tools.extend(toolkit.get_tools())
             except Exception as e:
+                import traceback
                 logger.error(f"Error in getting custom toolkit: {e}")
-
+                logger.error(f"Traceback:\n{traceback.format_exc()}")
         else:
-            # Tool not available or not found
             if tool_type in FAILED_IMPORTS:
                 logger.warning(f"Tool '{tool_type}' is not available: {FAILED_IMPORTS[tool_type]}")
             else:
                 logger.warning(f"Unknown tool type: {tool_type}")
+        #
+        # Always inject toolkit_id to each tool 
+        _inject_toolkit_id(tool, toolkit_tools)
+        tools.extend(toolkit_tools)
 
     return tools
 
@@ -167,6 +217,18 @@ def get_toolkits():
     logger.info(f"Successfully loaded {len(toolkit_configs)} toolkit configurations")
     return toolkit_configs
 
+def instantiate_toolkit(tool_config):
+    """Instantiate a toolkit from its configuration."""
+    tool_type = tool_config.get('type')
+    
+    if tool_type in AVAILABLE_TOOLS:
+        tool_module = AVAILABLE_TOOLS[tool_type]
+        
+        if 'get_toolkit' in tool_module:
+             return tool_module['get_toolkit'](tool_config)
+             
+    raise ValueError(f"Toolkit type '{tool_type}' does not support direct instantiation or is not available.")
+
 def get_available_tools():
     """Return list of available tool types."""
     return list(AVAILABLE_TOOLS.keys())
@@ -183,6 +245,42 @@ def get_available_toolkit_models():
     """Return dict with available toolkit classes."""
     return deepcopy(AVAILABLE_TOOLS)
 
+
+def get_toolkit_available_tools(toolkit_type: str, settings: dict) -> dict:
+    """Return dynamic available tools + per-tool JSON schemas for a toolkit instance.
+
+    This is the single SDK entrypoint used by backend services (e.g. indexer_worker)
+    when the UI needs spec/instance-dependent tool enumeration. Toolkits that don't
+    support dynamic enumeration should return an empty payload.
+
+    Args:
+        toolkit_type: toolkit type string (e.g. 'openapi')
+        settings: persisted toolkit settings
+
+    Returns:
+        {
+          "tools": [{"name": str, "description": str}],
+          "args_schemas": {"tool_name": <json schema dict>}
+        }
+    """
+    toolkit_type = (toolkit_type or '').strip().lower()
+    if not isinstance(settings, dict):
+        settings = {}
+
+    tool_module = AVAILABLE_TOOLS.get(toolkit_type) or {}
+    enumerator = tool_module.get('get_toolkit_available_tools')
+    if not callable(enumerator):
+        return {"tools": [], "args_schemas": {}}
+
+    try:
+        result = enumerator(settings)
+        if not isinstance(result, dict):
+            return {"tools": [], "args_schemas": {}, "error": "Invalid response from toolkit enumerator"}
+        return result
+    except Exception as e:  # pylint: disable=W0718
+        logger.exception("Failed to compute available tools for toolkit_type=%s", toolkit_type)
+        return {"tools": [], "args_schemas": {}, "error": str(e)}
+
 def diagnose_imports():
     """Print diagnostic information about tool imports."""
     available_count = len(AVAILABLE_TOOLS)
@@ -219,6 +317,7 @@ def diagnose_imports():
 __all__ = [
     'get_tools',
     'get_toolkits',
+    'get_toolkit_available_tools',
     'get_available_tools',
     'get_failed_imports',
     'get_available_toolkits',