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

alita_sdk/cli/__init__.py

@@ -0,0 +1,10 @@
+"""
+Alita SDK CLI - Command-line interface for testing agents and toolkits.
+
+This module provides a CLI alternative to the Streamlit interface, enabling
+direct terminal access for GitHub Copilot integration and automation workflows.
+"""
+
+from .cli import cli
+
+__all__ = ['cli']

alita_sdk/cli/__main__.py

@@ -0,0 +1,17 @@
+"""
+Entry point for running the Alita CLI as a module.
+
+Usage:
+    python -m alita_sdk.cli [command] [options]
+"""
+
+# Suppress warnings before any imports
+import warnings
+warnings.filterwarnings('ignore', category=DeprecationWarning)
+warnings.filterwarnings('ignore', category=UserWarning)
+warnings.filterwarnings('ignore', message='Unverified HTTPS request')
+
+from .cli import cli
+
+if __name__ == '__main__':
+    cli()

alita_sdk/cli/agent_executor.py

@@ -0,0 +1,144 @@
+"""
+Agent executor creation and management.
+
+Creates LLM instances and agent executors with support for MCP tools.
+"""
+
+from typing import Optional, Dict, Any, List, Tuple
+from rich.console import Console
+
+from .agent_loader import build_agent_data_structure
+from alita_sdk.runtime.langchain.assistant import Assistant
+
+console = Console()
+
+
+def create_llm_instance(client, model: Optional[str], agent_def: Dict[str, Any], 
+                       temperature: Optional[float], max_tokens: Optional[int]):
+    """Create LLM instance with appropriate configuration."""
+    llm_model = model or agent_def.get('model', 'gpt-4o')
+    llm_temperature = temperature if temperature is not None else agent_def.get('temperature', 0.7)
+    llm_max_tokens = max_tokens or agent_def.get('max_tokens', 2000)
+    
+    try:
+        llm = client.get_llm(
+            model_name=llm_model,
+            model_config={
+                'temperature': llm_temperature,
+                'max_tokens': llm_max_tokens
+            }
+        )
+        return llm, llm_model, llm_temperature, llm_max_tokens
+    except Exception as e:
+        console.print(f"\n✗ [red]Failed to create LLM instance:[/red] {e}")
+        console.print("[yellow]Hint: Make sure OPENAI_API_KEY or other LLM credentials are set[/yellow]")
+        raise
+
+
+def _create_assistant(client, agent_data: Dict[str, Any], llm, memory, tools: List) -> Assistant:
+    """Create Assistant instance with given configuration.
+    
+    Args:
+        client: Alita client instance
+        agent_data: Agent configuration data
+        llm: LLM instance
+        memory: Memory/checkpoint instance
+        tools: List of tools to add to agent
+        
+    Returns:
+        Assistant instance
+    """
+    return Assistant(
+        alita=client,
+        data=agent_data,
+        client=llm,
+        chat_history=[],
+        app_type=agent_data.get('agent_type', 'react'),
+        tools=tools,
+        memory=memory,
+        store=None,
+        debug_mode=False,
+        mcp_tokens=None
+    )
+
+
+def create_agent_executor(client, agent_def: Dict[str, Any], toolkit_configs: List[Dict[str, Any]],
+                         llm, llm_model: str, llm_temperature: float, llm_max_tokens: int, memory,
+                         filesystem_tools: Optional[List] = None, mcp_tools: Optional[List] = None):
+    """Create agent executor for local agents with tools (sync version).
+    
+    Note: mcp_tools parameter is deprecated - use create_agent_executor_with_mcp for MCP support.
+    """
+    agent_data = build_agent_data_structure(
+        agent_def=agent_def,
+        toolkit_configs=toolkit_configs,
+        llm_model=llm_model,
+        llm_temperature=llm_temperature,
+        llm_max_tokens=llm_max_tokens
+    )
+    
+    # Combine all tools
+    additional_tools = []
+    if filesystem_tools:
+        additional_tools.extend(filesystem_tools)
+    if mcp_tools:
+        additional_tools.extend(mcp_tools)
+    
+    assistant = _create_assistant(client, agent_data, llm, memory, additional_tools)
+    return assistant.runnable()
+
+
+async def create_agent_executor_with_mcp(
+    client, 
+    agent_def: Dict[str, Any], 
+    toolkit_configs: List[Dict[str, Any]],
+    llm, 
+    llm_model: str, 
+    llm_temperature: float, 
+    llm_max_tokens: int, 
+    memory,
+    filesystem_tools: Optional[List] = None
+) -> Tuple[Any, Optional[Any]]:
+    """Create agent executor with MCP tools using persistent sessions.
+    
+    Returns:
+        Tuple of (agent_executor, mcp_session_manager) where session_manager must be kept alive
+        to maintain stateful MCP server state (e.g., Playwright browser sessions).
+        
+    See: https://github.com/langchain-ai/langchain-mcp-adapters/issues/178
+    """
+    from .mcp_loader import load_mcp_tools_async
+    
+    # Separate MCP toolkit configs from regular configs
+    mcp_configs = [tc for tc in toolkit_configs if tc.get('toolkit_type') == 'mcp']
+    regular_configs = [tc for tc in toolkit_configs if tc.get('toolkit_type') != 'mcp']
+    
+    # Load MCP tools with persistent sessions
+    mcp_session_manager = None
+    mcp_tools = []
+    if mcp_configs:
+        console.print("\n[cyan]Loading MCP tools with persistent sessions...[/cyan]")
+        mcp_session_manager, mcp_tools = await load_mcp_tools_async(mcp_configs)
+        if mcp_tools:
+            console.print(f"[green]✓ Loaded {len(mcp_tools)} MCP tools with persistent sessions[/green]\n")
+    
+    # Build agent data structure
+    agent_data = build_agent_data_structure(
+        agent_def=agent_def,
+        toolkit_configs=regular_configs,
+        llm_model=llm_model,
+        llm_temperature=llm_temperature,
+        llm_max_tokens=llm_max_tokens
+    )
+    
+    # Combine all tools
+    additional_tools = []
+    if filesystem_tools:
+        additional_tools.extend(filesystem_tools)
+    if mcp_tools:
+        additional_tools.extend(mcp_tools)
+    
+    assistant = _create_assistant(client, agent_data, llm, memory, additional_tools)
+    
+    # Return agent and session manager (must be kept alive for stateful MCP tools)
+    return assistant.runnable(), mcp_session_manager

alita_sdk/cli/agent_loader.py

@@ -0,0 +1,197 @@
+"""
+Agent loading and definition management.
+
+Handles loading agent definitions from various file formats (YAML, JSON, Markdown).
+"""
+
+import json
+import yaml
+from pathlib import Path
+from typing import Dict, Any
+
+from .config import substitute_env_vars
+
+
+def load_agent_definition(file_path: str) -> Dict[str, Any]:
+    """
+    Load agent definition from file.
+    
+    Supports:
+    - YAML files (.yaml, .yml)
+    - JSON files (.json)
+    - Markdown files with YAML frontmatter (.md)
+    
+    Args:
+        file_path: Path to agent definition file
+        
+    Returns:
+        Dictionary with agent configuration
+    """
+    path = Path(file_path)
+    
+    if not path.exists():
+        raise FileNotFoundError(f"Agent definition not found: {file_path}")
+    
+    content = path.read_text()
+    
+    # Handle markdown with YAML frontmatter
+    if path.suffix == '.md':
+        if content.startswith('---'):
+            parts = content.split('---', 2)
+            if len(parts) >= 3:
+                frontmatter = yaml.safe_load(parts[1])
+                system_prompt = parts[2].strip()
+                
+                # Apply environment variable substitution
+                system_prompt = substitute_env_vars(system_prompt)
+                
+                return {
+                    'name': frontmatter.get('name', path.stem),
+                    'description': frontmatter.get('description', ''),
+                    'system_prompt': system_prompt,
+                    'model': frontmatter.get('model'),
+                    'tools': frontmatter.get('tools', []),
+                    'temperature': frontmatter.get('temperature'),
+                    'max_tokens': frontmatter.get('max_tokens'),
+                    'toolkit_configs': frontmatter.get('toolkit_configs', []),
+                    'filesystem_tools_preset': frontmatter.get('filesystem_tools_preset'),
+                    'filesystem_tools_include': frontmatter.get('filesystem_tools_include'),
+                    'filesystem_tools_exclude': frontmatter.get('filesystem_tools_exclude'),
+                    'mcps': frontmatter.get('mcps', [])
+                }
+        
+        # Plain markdown - use content as system prompt
+        return {
+            'name': path.stem,
+            'system_prompt': substitute_env_vars(content),
+        }
+    
+    # Handle YAML
+    if path.suffix in ['.yaml', '.yml']:
+        content = substitute_env_vars(content)
+        config = yaml.safe_load(content)
+        if 'system_prompt' in config:
+            config['system_prompt'] = substitute_env_vars(config['system_prompt'])
+        return config
+    
+    # Handle JSON
+    if path.suffix == '.json':
+        content = substitute_env_vars(content)
+        config = json.loads(content)
+        if 'system_prompt' in config:
+            config['system_prompt'] = substitute_env_vars(config['system_prompt'])
+        return config
+    
+    raise ValueError(f"Unsupported file format: {path.suffix}")
+
+
+def build_agent_data_structure(agent_def: Dict[str, Any], toolkit_configs: list, 
+                               llm_model: str, llm_temperature: float, llm_max_tokens: int) -> Dict[str, Any]:
+    """
+    Convert a local agent definition to the data structure expected by the Assistant class.
+    
+    This utility function bridges between simple agent definition formats (e.g., from markdown files)
+    and the structured format that the Assistant class requires internally.
+    
+    Args:
+        agent_def: The agent definition loaded from a local file (markdown, YAML, or JSON)
+        toolkit_configs: List of toolkit configurations to be used by the agent
+        llm_model: The LLM model name (e.g., 'gpt-4o')
+        llm_temperature: Temperature setting for the model
+        llm_max_tokens: Maximum tokens for model responses
+        
+    Returns:
+        A dictionary in the format expected by the Assistant constructor with keys:
+        - instructions: System prompt for the agent
+        - tools: List of tool/toolkit configurations
+        - variables: Agent variables (empty for local agents)
+        - meta: Metadata including step_limit and internal_tools
+        - llm_settings: Complete LLM configuration
+        - agent_type: Type of agent (react, openai, etc.)
+    """
+    # Import toolkit registry to validate configs
+    from alita_sdk.tools import AVAILABLE_TOOLS
+    
+    # Build the tools list from agent definition and toolkit configs
+    tools = []
+    processed_toolkit_names = set()
+    
+    # Validate and process toolkit configs through their Pydantic schemas
+    validated_toolkit_configs = []
+    for toolkit_config in toolkit_configs:
+        toolkit_type = toolkit_config.get('type')
+        if toolkit_type and toolkit_type in AVAILABLE_TOOLS:
+            try:
+                toolkit_info = AVAILABLE_TOOLS[toolkit_type]
+                if 'toolkit_class' in toolkit_info:
+                    toolkit_class = toolkit_info['toolkit_class']
+                    if hasattr(toolkit_class, 'toolkit_config_schema'):
+                        schema = toolkit_class.toolkit_config_schema()
+                        validated_config = schema(**toolkit_config)
+                        validated_dict = validated_config.model_dump()
+                        validated_dict['type'] = toolkit_config.get('type')
+                        validated_dict['toolkit_name'] = toolkit_config.get('toolkit_name')
+                        validated_toolkit_configs.append(validated_dict)
+                    else:
+                        validated_toolkit_configs.append(toolkit_config)
+                else:
+                    validated_toolkit_configs.append(toolkit_config)
+            except Exception:
+                validated_toolkit_configs.append(toolkit_config)
+        else:
+            validated_toolkit_configs.append(toolkit_config)
+    
+    # Add tools from agent definition
+    for tool_name in agent_def.get('tools', []):
+        toolkit_config = next((tk for tk in validated_toolkit_configs if tk.get('toolkit_name') == tool_name), None)
+        if toolkit_config:
+            tools.append({
+                'type': toolkit_config.get('type'),
+                'toolkit_name': toolkit_config.get('toolkit_name'),
+                'settings': toolkit_config,
+                'selected_tools': toolkit_config.get('selected_tools', [])
+            })
+            processed_toolkit_names.add(tool_name)
+        else:
+            tools.append({
+                'type': tool_name,
+                'name': tool_name
+            })
+    
+    # Add toolkit_configs that weren't already referenced
+    for toolkit_config in validated_toolkit_configs:
+        toolkit_name = toolkit_config.get('toolkit_name')
+        if toolkit_name and toolkit_name not in processed_toolkit_names:
+            tools.append({
+                'type': toolkit_config.get('type'),
+                'toolkit_name': toolkit_name,
+                'settings': toolkit_config,
+                'selected_tools': toolkit_config.get('selected_tools', [])
+            })
+    
+    return {
+        'instructions': agent_def.get('system_prompt', ''),
+        'tools': tools,
+        'variables': [],
+        'meta': {
+            'step_limit': agent_def.get('step_limit', 25),
+            'internal_tools': agent_def.get('internal_tools', [])
+        },
+        'llm_settings': {
+            'model_name': llm_model,
+            'max_tokens': llm_max_tokens,
+            'temperature': llm_temperature,
+            'top_p': 1.0,
+            'top_k': 0,
+            'integration_uid': None,
+            'indexer_config': {
+                'ai_model': 'langchain_openai.ChatOpenAI',
+                'ai_model_params': {
+                    'model': llm_model,
+                    'temperature': llm_temperature,
+                    'max_tokens': llm_max_tokens
+                }
+            }
+        },
+        'agent_type': agent_def.get('agent_type', 'react')
+    }

alita_sdk/cli/agent_ui.py

@@ -0,0 +1,166 @@
+"""
+Agent UI and display utilities.
+
+Rich console formatting for agent interactions.
+"""
+
+from rich.console import Console, Group
+from rich.panel import Panel
+from rich.table import Table
+from rich.markdown import Markdown
+from rich import box
+from rich.text import Text
+from rich.align import Align
+from rich.columns import Columns
+from rich.rule import Rule
+
+console = Console()
+
+# ALITA ASCII Art Logo - block letters
+ALITA_LOGO = [
+    " █████╗ ██╗     ██╗████████╗ █████╗ ",
+    "██╔══██╗██║     ██║╚══██╔══╝██╔══██╗",
+    "███████║██║     ██║   ██║   ███████║",
+    "██╔══██║██║     ██║   ██║   ██╔══██║",
+    "██║  ██║███████╗██║   ██║   ██║  ██║",
+    "╚═╝  ╚═╝╚══════╝╚═╝   ╚═╝   ╚═╝  ╚═╝",
+]
+
+
+def get_version():
+    """Get CLI version from package."""
+    try:
+        from importlib.metadata import version
+        return version('alita_sdk')
+    except Exception:
+        return "0.3.x"
+
+
+def print_banner(agent_name: str, agent_type: str = "Local Agent"):
+    """Print a cool banner for the chat session with ASCII art."""
+    
+    version = get_version()
+    
+    # Create the main banner content
+    banner_text = Text()
+    
+    # Add logo lines with cyan styling
+    for line in ALITA_LOGO:
+        banner_text.append("    " + line + "\n", style="bold cyan")
+    
+    banner_text.append("\n")
+    banner_text.append("                    CLI ", style="dim")
+    banner_text.append(f"v{version}\n\n", style="bold white")
+    
+    # Agent info
+    banner_text.append("    ● ", style="bold green")
+    banner_text.append("Agent: ", style="bold white")
+    banner_text.append(f"{agent_name}\n", style="bold cyan")
+    banner_text.append("    ● ", style="bold green")
+    banner_text.append("Type:  ", style="bold white")
+    banner_text.append(f"{agent_type}\n", style="cyan")
+    
+    console.print()
+    console.print(Panel(
+        banner_text,
+        box=box.DOUBLE,
+        border_style="cyan",
+        padding=(0, 2),
+    ))
+
+
+def print_help():
+    """Print help message with commands using rich table."""
+    table = Table(
+        show_header=True,
+        header_style="bold cyan",
+        border_style="dim",
+        box=box.SIMPLE,
+        padding=(0, 1),
+    )
+    
+    table.add_column("Command", style="bold yellow", no_wrap=True, width=12)
+    table.add_column("Description", style="white")
+    
+    table.add_row("/clear", "Clear conversation history")
+    table.add_row("/history", "Show conversation history")
+    table.add_row("/save", "Save conversation to file")
+    table.add_row("/help", "Show this help")
+    table.add_row("exit", "End conversation")
+    
+    console.print(table)
+    console.print()
+
+
+def print_welcome(agent_name: str, agent_type: str = "Local Agent"):
+    """Print combined welcome banner with logo, agent info, and help."""
+    
+    version = get_version()
+    
+    # Build the complete welcome message using Text objects
+    content = Text()
+    
+    # Add logo lines with cyan styling
+    for line in ALITA_LOGO:
+        content.append("    " + line + "\n", style="bold cyan")
+    
+    content.append("                    CLI ", style="dim")
+    content.append(f"v{version}\n\n", style="bold white")
+    
+    # Connection status
+    content.append("    ● ", style="bold green")
+    content.append("Agent: ", style="bold white")
+    content.append(f"{agent_name}\n", style="bold cyan")
+    content.append("    ● ", style="bold green")
+    content.append("Type:  ", style="bold white")
+    content.append(f"{agent_type}\n\n", style="cyan")
+    
+    # Quick help section
+    content.append("    Type a message to chat, or use these commands:\n\n", style="dim")
+    
+    # Commands
+    content.append("    /help", style="bold yellow")
+    content.append("    Show all commands\n", style="white")
+    content.append("    /clear", style="bold yellow")
+    content.append("   Clear history\n", style="white")
+    content.append("    exit", style="bold yellow")
+    content.append("     End conversation\n", style="white")
+    
+    console.print()
+    console.print(Panel(
+        content,
+        box=box.DOUBLE,
+        border_style="cyan",
+        padding=(0, 2),
+    ))
+    console.print()
+
+
+def display_output(agent_name: str, message: str, output: str):
+    """Display agent output with markdown rendering if applicable."""
+    console.print(f"\n[bold cyan]🤖 Agent: {agent_name}[/bold cyan]\n")
+    console.print(f"[bold]Message:[/bold] {message}\n")
+    console.print("[bold]Response:[/bold]")
+    if any(marker in output for marker in ['```', '**', '##', '- ', '* ']):
+        console.print(Markdown(output))
+    else:
+        console.print(output)
+    console.print()
+
+
+def extract_output_from_result(result) -> str:
+    """Extract output string from agent result (handles multiple formats)."""
+    if isinstance(result, dict):
+        # Try different keys that might contain the response
+        output = result.get('output')
+        if output is None and 'messages' in result:
+            # LangGraph format - get last message
+            messages = result['messages']
+            if messages and len(messages) > 0:
+                last_msg = messages[-1]
+                output = last_msg.content if hasattr(last_msg, 'content') else str(last_msg)
+        if output is None:
+            output = str(result)
+    else:
+        output = str(result)
+    return output