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

alita_sdk/cli/toolkit.py

@@ -0,0 +1,327 @@
+"""
+Toolkit testing commands for Alita CLI.
+
+Provides commands to list, inspect, and test toolkits directly from the command line.
+"""
+
+import click
+import json
+import logging
+from typing import Optional, Dict, Any
+
+from .cli import get_client
+from .toolkit_loader import load_toolkit_config
+
+logger = logging.getLogger(__name__)
+
+
+@click.group()
+def toolkit():
+    """Toolkit testing commands."""
+    pass
+
+
+@toolkit.command('list')
+@click.option('--failed', is_flag=True, help='Show failed imports')
+@click.pass_context
+def toolkit_list(ctx, failed: bool):
+    """List all available toolkits."""
+    formatter = ctx.obj['formatter']
+    
+    try:
+        # Import toolkit registry
+        from alita_sdk.tools import AVAILABLE_TOOLS, AVAILABLE_TOOLKITS, FAILED_IMPORTS
+        
+        if failed:
+            # Show failed imports
+            if FAILED_IMPORTS:
+                click.echo("\nFailed toolkit imports:\n")
+                for name, error in FAILED_IMPORTS.items():
+                    click.echo(f"  - {name}: {error}")
+                click.echo(f"\nTotal failed: {len(FAILED_IMPORTS)}")
+            else:
+                click.echo("\nNo failed imports")
+            return
+        
+        # Build toolkit list
+        toolkits = []
+        for name, toolkit_dict in AVAILABLE_TOOLS.items():
+            toolkit_class_name = None
+            if 'toolkit_class' in toolkit_dict:
+                toolkit_class_name = toolkit_dict['toolkit_class'].__name__
+            
+            toolkits.append({
+                'name': name,
+                'class_name': toolkit_class_name,
+                'has_get_tools': 'get_tools' in toolkit_dict
+            })
+        
+        # Format and display
+        output = formatter.format_toolkit_list(toolkits)
+        click.echo(output)
+        
+    except Exception as e:
+        logger.exception("Failed to list toolkits")
+        click.echo(formatter.format_error(str(e)), err=True)
+        raise click.Abort()
+
+
+@toolkit.command('schema')
+@click.argument('toolkit_name')
+@click.pass_context
+def toolkit_schema(ctx, toolkit_name: str):
+    """
+    Show configuration schema for a toolkit.
+    
+    TOOLKIT_NAME: Name of the toolkit (e.g., 'jira', 'github', 'confluence')
+    """
+    formatter = ctx.obj['formatter']
+    
+    try:
+        # Import toolkit registry
+        from alita_sdk.tools import AVAILABLE_TOOLKITS
+        
+        # Find toolkit class
+        toolkit_class = None
+        for name, cls in AVAILABLE_TOOLKITS.items():
+            if name.lower().replace('toolkit', '').replace('alita', '').strip() == toolkit_name.lower():
+                toolkit_class = cls
+                break
+        
+        if not toolkit_class:
+            # Try direct match
+            for name, cls in AVAILABLE_TOOLKITS.items():
+                if toolkit_name.lower() in name.lower():
+                    toolkit_class = cls
+                    break
+        
+        if not toolkit_class:
+            available = [name.lower().replace('toolkit', '').replace('alita', '').strip() 
+                        for name in AVAILABLE_TOOLKITS.keys()]
+            raise click.ClickException(
+                f"Toolkit '{toolkit_name}' not found.\n"
+                f"Available toolkits: {', '.join(sorted(set(available)))}"
+            )
+        
+        # Get schema
+        schema_model = toolkit_class.toolkit_config_schema()
+        schema = schema_model.model_json_schema()
+        
+        # Format and display
+        if formatter.__class__.__name__ == 'JSONFormatter':
+            output = formatter.format_toolkit_schema(toolkit_name, schema)
+        else:
+            output = formatter.format_toolkit_schema(toolkit_name, schema)
+        
+        click.echo(output)
+        
+    except click.ClickException:
+        raise
+    except Exception as e:
+        logger.exception(f"Failed to get schema for toolkit '{toolkit_name}'")
+        click.echo(formatter.format_error(str(e)), err=True)
+        raise click.Abort()
+
+
+@toolkit.command('test')
+@click.argument('toolkit_type')
+@click.option('--tool', required=True, help='Tool name to execute')
+@click.option('--config', 'config_file', type=click.File('r'), 
+              help='Toolkit configuration JSON file')
+@click.option('--params', type=click.File('r'), 
+              help='Tool parameters JSON file')
+@click.option('--param', multiple=True, 
+              help='Tool parameter as key=value (can be used multiple times)')
+@click.option('--llm-model', default='gpt-4o-mini', 
+              help='LLM model to use (default: gpt-4o-mini)')
+@click.option('--temperature', default=0.1, type=float,
+              help='LLM temperature (default: 0.1)')
+@click.option('--max-tokens', default=1000, type=int,
+              help='LLM max tokens (default: 1000)')
+@click.pass_context
+def toolkit_test(ctx, toolkit_type: str, tool: str, config_file, params, 
+                param, llm_model: str, temperature: float, max_tokens: int):
+    """Test a specific tool from a toolkit.
+    
+    TOOLKIT_TYPE: Type of toolkit (e.g., 'jira', 'github', 'confluence')
+    
+    \b
+    Examples:
+      alita toolkit test jira --tool get_issue --config jira.json --params params.json
+      alita toolkit test jira --tool get_issue --config jira.json --param issue_key=PROJ-123
+      alita -o json toolkit test github --tool get_issue --config github.json
+    """
+    formatter = ctx.obj['formatter']
+    client = get_client(ctx)
+    
+    try:
+        # Load toolkit configuration
+        toolkit_config = {}
+        if config_file:
+            toolkit_config = load_toolkit_config(config_file.name)
+            logger.debug(f"Loaded toolkit config from {config_file.name}")
+        
+        # Add the tool to selected_tools in the config
+        if 'selected_tools' not in toolkit_config:
+            toolkit_config['selected_tools'] = []
+        if tool not in toolkit_config['selected_tools']:
+            toolkit_config['selected_tools'].append(tool)
+        
+        # Load tool parameters
+        tool_params = {}
+        if params:
+            tool_params = json.load(params)
+            logger.debug(f"Loaded tool params from {params.name}")
+        
+        # Parse inline parameters
+        if param:
+            for param_pair in param:
+                if '=' not in param_pair:
+                    raise click.ClickException(
+                        f"Invalid parameter format: '{param_pair}'. "
+                        "Use --param key=value"
+                    )
+                key, value = param_pair.split('=', 1)
+                
+                # Try to parse as JSON for complex values
+                try:
+                    tool_params[key] = json.loads(value)
+                except json.JSONDecodeError:
+                    tool_params[key] = value
+            
+            logger.debug(f"Parsed {len(param)} inline parameters")
+        
+        # Prepare full toolkit configuration
+        full_config = {
+            'toolkit_name': toolkit_type,
+            'type': toolkit_type,
+            'settings': toolkit_config
+        }
+        
+        # LLM configuration
+        llm_config = {
+            'temperature': temperature,
+            'max_tokens': max_tokens,
+        }
+        
+        # Execute test
+        logger.info(f"Testing tool '{tool}' from toolkit '{toolkit_type}'")
+        result = client.test_toolkit_tool(
+            toolkit_config=full_config,
+            tool_name=tool,
+            tool_params=tool_params,
+            llm_model=llm_model,
+            llm_config=llm_config
+        )
+        
+        # Format and display result
+        output = formatter.format_toolkit_result(result)
+        click.echo(output)
+        
+        # Exit with error code if test failed
+        if not result.get('success', False):
+            raise click.Abort()
+        
+    except click.ClickException:
+        raise
+    except Exception as e:
+        logger.exception("Failed to execute toolkit test")
+        click.echo(formatter.format_error(str(e)), err=True)
+        raise click.Abort()
+
+
+@toolkit.command('tools')
+@click.argument('toolkit_type')
+@click.option('--config', 'config_file', type=click.File('r'),
+              help='Toolkit configuration JSON file (required for some toolkits)')
+@click.pass_context
+def toolkit_tools(ctx, toolkit_type: str, config_file):
+    """
+    List available tools for a specific toolkit.
+    
+    TOOLKIT_TYPE: Type of toolkit (e.g., 'jira', 'github', 'confluence')
+    
+    Some toolkits require configuration to determine available tools.
+    Use --config to provide configuration if needed.
+    """
+    formatter = ctx.obj['formatter']
+    client = get_client(ctx)
+    
+    try:
+        # Load toolkit configuration if provided
+        toolkit_config = {}
+        if config_file:
+            toolkit_config = load_toolkit_config(config_file.name)
+        
+        # Import and instantiate toolkit
+        from alita_sdk.tools import AVAILABLE_TOOLS
+        
+        if toolkit_type not in AVAILABLE_TOOLS:
+            raise click.ClickException(
+                f"Toolkit '{toolkit_type}' not found. "
+                f"Use 'alita-cli toolkit list' to see available toolkits."
+            )
+        
+        toolkit_entry = AVAILABLE_TOOLS[toolkit_type]
+        
+        if 'toolkit_class' not in toolkit_entry:
+            raise click.ClickException(
+                f"Toolkit '{toolkit_type}' does not support tool listing"
+            )
+        
+        # Get toolkit class and instantiate
+        toolkit_class = toolkit_entry['toolkit_class']
+        
+        # Create minimal configuration
+        full_config = {
+            'toolkit_name': toolkit_type,
+            'type': toolkit_type,
+            'settings': toolkit_config
+        }
+        
+        # Try to get available tools via API wrapper
+        try:
+            # Instantiate API wrapper if possible
+            api_wrapper_class = None
+            
+            # Find API wrapper class by inspecting toolkit
+            import inspect
+            for name, obj in inspect.getmembers(toolkit_class):
+                if inspect.isclass(obj) and 'ApiWrapper' in obj.__name__:
+                    api_wrapper_class = obj
+                    break
+            
+            if api_wrapper_class:
+                try:
+                    api_wrapper = api_wrapper_class(**toolkit_config)
+                    available_tools = api_wrapper.get_available_tools()
+                    
+                    # Format tools list
+                    click.echo(f"\nAvailable tools for {toolkit_type}:\n")
+                    for tool_info in available_tools:
+                        tool_name = tool_info.get('name', 'unknown')
+                        description = tool_info.get('description', '')
+                        click.echo(f"  - {tool_name}")
+                        if description:
+                            click.echo(f"      {description}")
+                    
+                    click.echo(f"\nTotal: {len(available_tools)} tools")
+                    return
+                    
+                except Exception as e:
+                    logger.debug(f"Could not instantiate API wrapper: {e}")
+            
+            # Fallback: show general info
+            click.echo(f"\n{toolkit_type} toolkit is available")
+            click.echo("Use 'alita-cli toolkit schema {toolkit_type}' to see configuration options")
+            
+        except Exception as e:
+            logger.exception("Failed to list tools")
+            raise click.ClickException(str(e))
+        
+    except click.ClickException:
+        raise
+    except Exception as e:
+        logger.exception("Failed to list toolkit tools")
+        click.echo(formatter.format_error(str(e)), err=True)
+        raise click.Abort()

alita_sdk/cli/toolkit_loader.py

@@ -0,0 +1,85 @@
+"""
+Toolkit configuration loading and management.
+
+Handles loading toolkit configurations from JSON/YAML files.
+"""
+
+import json
+import yaml
+from pathlib import Path
+from typing import Dict, Any, List
+
+from .config import substitute_env_vars
+
+
+# All available tools in the inventory toolkit
+INVENTORY_TOOLS = [
+    "search_graph",
+    "get_entity",
+    "get_entity_content",
+    "impact_analysis",
+    "get_related_entities",
+    "get_stats",
+    "get_citations",
+    "list_entities_by_type",
+    "list_entities_by_layer",
+]
+
+
+def load_toolkit_config(file_path: str) -> Dict[str, Any]:
+    """Load toolkit configuration from JSON or YAML file with env var substitution."""
+    path = Path(file_path)
+    
+    if not path.exists():
+        raise FileNotFoundError(f"Toolkit configuration not found: {file_path}")
+    
+    with open(path) as f:
+        content = f.read()
+    
+    # Apply environment variable substitution
+    content = substitute_env_vars(content)
+    
+    # Parse based on file extension
+    if path.suffix in ['.yaml', '.yml']:
+        return yaml.safe_load(content)
+    else:
+        return json.loads(content)
+
+
+def load_toolkit_configs(agent_def: Dict[str, Any], toolkit_config_paths: tuple) -> List[Dict[str, Any]]:
+    """Load all toolkit configurations from agent definition and CLI options.
+    
+    Args:
+        agent_def: Agent definition dictionary
+        toolkit_config_paths: Tuple of file paths or dict configs from CLI options
+        
+    Returns:
+        List of toolkit configuration dictionaries
+    """
+    toolkit_configs = []
+    
+    # Load from agent definition if present
+    if 'toolkit_configs' in agent_def:
+        for tk_config in agent_def['toolkit_configs']:
+            if isinstance(tk_config, dict):
+                if 'file' in tk_config:
+                    config = load_toolkit_config(tk_config['file'])
+                    toolkit_configs.append(config)
+                elif 'config' in tk_config:
+                    toolkit_configs.append(tk_config['config'])
+                elif 'type' in tk_config:
+                    # Direct toolkit config (e.g., {'type': 'inventory', ...})
+                    toolkit_configs.append(tk_config)
+    
+    # Load from CLI options - can be file paths (str) or dict configs
+    if toolkit_config_paths:
+        for config_item in toolkit_config_paths:
+            if isinstance(config_item, dict):
+                # Direct config dict (e.g., from /inventory command)
+                toolkit_configs.append(config_item)
+            elif isinstance(config_item, str):
+                # File path
+                config = load_toolkit_config(config_item)
+                toolkit_configs.append(config)
+    
+    return toolkit_configs

alita_sdk/cli/tools/__init__.py

@@ -0,0 +1,43 @@
+"""
+CLI tools package.
+
+Contains specialized tools for CLI agents.
+"""
+
+from .filesystem import get_filesystem_tools, FilesystemApiWrapper
+from .terminal import get_terminal_tools, create_default_blocked_patterns_file
+from .planning import (
+    get_planning_tools, 
+    PlanState, 
+    list_sessions, 
+    generate_session_id,
+    create_session_memory,
+    save_session_metadata,
+    load_session_metadata,
+    update_session_metadata,
+    get_session_dir,
+    to_portable_path,
+    from_portable_path,
+)
+from .approval import create_approval_wrapper, ApprovalToolWrapper, prompt_approval
+
+__all__ = [
+    'get_filesystem_tools',
+    'FilesystemApiWrapper',
+    'get_terminal_tools',
+    'create_default_blocked_patterns_file',
+    'get_planning_tools',
+    'PlanState',
+    'list_sessions',
+    'generate_session_id',
+    'create_session_memory',
+    'save_session_metadata',
+    'load_session_metadata',
+    'update_session_metadata',
+    'get_session_dir',
+    'to_portable_path',
+    'from_portable_path',
+    'create_approval_wrapper',
+    'ApprovalToolWrapper',
+    'prompt_approval',
+]

alita_sdk/cli/tools/approval.py

@@ -0,0 +1,224 @@
+"""
+Tool approval wrapper for CLI.
+
+Wraps tools to require user approval before execution based on approval mode.
+Modes:
+- 'always': Always require approval for each tool call
+- 'auto': No approval required (automatic execution)
+- 'yolo': No approval and no safety checks (use with caution)
+"""
+
+import functools
+from typing import Any, Callable, Dict, List, Optional, Set
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich import box
+from rich.text import Text
+import json
+
+from langchain_core.tools import BaseTool, StructuredTool, Tool
+
+console = Console()
+
+# Tools that always require approval in 'always' mode (dangerous built-in operations)
+# These are the built-in CLI tools that modify the filesystem or execute commands
+DANGEROUS_TOOLS = {
+    'terminal_run_command',  # Shell command execution
+    'write_file',
+    'create_file', 
+    'delete_file',
+    'move_file',
+    'copy_file',
+    'create_directory',
+}
+
+# Note: Tools NOT in DANGEROUS_TOOLS are auto-approved, including:
+# - Read-only filesystem tools (read_file, list_directory, etc.)
+# - User-added toolkit tools (via --toolkit_config or /add_toolkit)
+# - MCP server tools (via --mcp or /add_mcp)
+# 
+# The assumption is that users explicitly add toolkits they trust.
+# Only built-in tools that can modify files or run commands require approval.
+
+
+def prompt_approval(tool_name: str, tool_args: Dict[str, Any], approval_mode: str) -> bool:
+    """
+    Prompt user for approval before executing a tool.
+    
+    Args:
+        tool_name: Name of the tool to execute
+        tool_args: Arguments to pass to the tool
+        approval_mode: Current approval mode ('always', 'auto', 'yolo')
+        
+    Returns:
+        True if approved, False if rejected
+    """
+    # Auto mode - always approve
+    if approval_mode == 'auto':
+        return True
+    
+    # Yolo mode - always approve, no questions asked
+    if approval_mode == 'yolo':
+        return True
+    
+    # Always mode - only prompt for dangerous built-in tools
+    # User-added toolkits and MCP tools are auto-approved (user explicitly added them)
+    if tool_name not in DANGEROUS_TOOLS:
+        return True
+    
+    # Create approval prompt panel for dangerous tools
+    console.print()
+    
+    # Build args display
+    args_content = []
+    for key, value in tool_args.items():
+        if isinstance(value, str) and len(value) > 100:
+            display_value = value[:100] + "..."
+        elif isinstance(value, (dict, list)):
+            try:
+                formatted = json.dumps(value, indent=2)
+                if len(formatted) > 200:
+                    formatted = formatted[:200] + "..."
+                display_value = formatted
+            except:
+                display_value = str(value)[:100]
+        else:
+            display_value = str(value)
+        args_content.append(f"  [cyan]{key}[/cyan]: {display_value}")
+    
+    args_text = "\n".join(args_content) if args_content else "  (no arguments)"
+    
+    # All tools reaching here are dangerous (in DANGEROUS_TOOLS)
+    icon = "⚠️"
+    border_style = "yellow"
+    title_style = "bold yellow"
+    
+    panel = Panel(
+        Text.from_markup(f"[bold]{tool_name}[/bold]\n\n[dim]Arguments:[/dim]\n{args_text}"),
+        title=f"[{title_style}]{icon} Approve Tool Call?[/{title_style}]",
+        title_align="left",
+        subtitle="[dim][y]es / [n]o / [a]uto-approve / [q]uit[/dim]",
+        subtitle_align="right",
+        border_style=border_style,
+        box=box.ROUNDED,
+        padding=(1, 2),
+    )
+    console.print(panel)
+    
+    # Get user input
+    while True:
+        try:
+            response = input("→ ").strip().lower()
+        except (KeyboardInterrupt, EOFError):
+            console.print("\n[yellow]Cancelled[/yellow]")
+            return False
+        
+        if response in ('y', 'yes', ''):
+            console.print("[green]✓ Approved[/green]")
+            return True
+        elif response in ('n', 'no'):
+            console.print("[red]✗ Rejected[/red]")
+            return False
+        elif response in ('a', 'auto'):
+            console.print("[cyan]→ Switching to auto mode for this session[/cyan]")
+            # Signal to switch to auto mode
+            return 'switch_auto'
+        elif response in ('q', 'quit'):
+            console.print("[yellow]Quitting...[/yellow]")
+            raise KeyboardInterrupt()
+        else:
+            console.print("[dim]Please enter y/n/a/q[/dim]")
+
+
+class ApprovalToolWrapper:
+    """
+    Wrapper that adds approval prompts to tools based on approval mode.
+    
+    This wrapper intercepts tool calls and prompts for user approval
+    before executing dangerous operations.
+    """
+    
+    def __init__(self, approval_mode_ref: List[str]):
+        """
+        Initialize the approval wrapper.
+        
+        Args:
+            approval_mode_ref: A mutable list containing the current approval mode.
+                              Using a list allows the mode to be changed externally.
+                              access as approval_mode_ref[0]
+        """
+        self.approval_mode_ref = approval_mode_ref
+    
+    @property
+    def approval_mode(self) -> str:
+        """Get current approval mode."""
+        return self.approval_mode_ref[0] if self.approval_mode_ref else 'always'
+    
+    def wrap_tool(self, tool: BaseTool) -> BaseTool:
+        """
+        Wrap a tool to add approval prompts.
+        
+        Args:
+            tool: The tool to wrap
+            
+        Returns:
+            Wrapped tool with approval logic
+        """
+        original_func = tool.func if hasattr(tool, 'func') else tool._run
+        tool_name = tool.name
+        wrapper_self = self
+        
+        @functools.wraps(original_func)
+        def wrapped_func(*args, **kwargs):
+            # Get approval
+            approval = prompt_approval(tool_name, kwargs, wrapper_self.approval_mode)
+            
+            if approval == 'switch_auto':
+                # Switch to auto mode
+                wrapper_self.approval_mode_ref[0] = 'auto'
+                console.print("[cyan]Mode switched to 'auto' - tools will auto-approve[/cyan]")
+            elif not approval:
+                return f"Tool execution rejected by user"
+            
+            # Execute the tool
+            return original_func(*args, **kwargs)
+        
+        # Create new tool with wrapped function
+        if isinstance(tool, StructuredTool):
+            return StructuredTool(
+                name=tool.name,
+                description=tool.description,
+                func=wrapped_func,
+                args_schema=tool.args_schema,
+                return_direct=tool.return_direct,
+            )
+        else:
+            # Clone the tool with wrapped function
+            tool.func = wrapped_func
+            return tool
+    
+    def wrap_tools(self, tools: List[BaseTool]) -> List[BaseTool]:
+        """
+        Wrap multiple tools with approval logic.
+        
+        Args:
+            tools: List of tools to wrap
+            
+        Returns:
+            List of wrapped tools
+        """
+        return [self.wrap_tool(tool) for tool in tools]
+
+
+def create_approval_wrapper(approval_mode_ref: List[str]) -> ApprovalToolWrapper:
+    """
+    Create an approval wrapper with a reference to the current mode.
+    
+    Args:
+        approval_mode_ref: Mutable list containing current approval mode [0]
+        
+    Returns:
+        ApprovalToolWrapper instance
+    """
+    return ApprovalToolWrapper(approval_mode_ref)