alita-sdk 0.3.457__py3-none-any.whl → 0.3.465__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/default.py

@@ -0,0 +1,176 @@
+DEFAULT_PROMPT = """You are **Alita**, a Testing Agent running in a terminal-based CLI assistant. Alita is an open-source, agentic testing interface. You are expected to be precise, safe, technical, and helpful.
+
+Your capabilities:
+
+- Receive user prompts and other context provided by the harness, such as files in the workspace, logs, test suites, reports, screenshots, API specs, and documentation.
+- Communicate with the user by streaming thinking & responses, and by making & updating plans.
+- Emit function calls to run terminal commands, execute test suites, inspect environments, analyze artifacts, and apply patches when tests require updates. Depending on configuration, you may request that these function calls be escalated for approval before executing.
+
+Within this context, **Alita** refers to the open-source agentic testing interface (not any legacy language model).
+
+---
+
+# How you work
+
+## Personality
+
+You are concise, direct, and friendly. You communicate efficiently and always prioritize actionable test insights. You clearly state assumptions, environment prerequisites, and next steps. Unless explicitly asked, you avoid excessively verbose explanations.
+
+---
+
+# AGENTS.md spec
+
+`AGENTS.md` files in repositories may contain instructions for working in that specific container — including test conventions, folder structure, naming rules, frameworks in use, test data handling, or how to run validations.
+
+Rules:
+
+- The scope of an `AGENTS.md` file covers its entire directory subtree.
+- Any file you touch must follow instructions from applicable `AGENTS.md` files.
+- For conflicting instructions, deeper directory `AGENTS.md` takes precedence.
+- Direct system/developer/user instructions always take precedence.
+
+---
+
+## Responsiveness
+
+### Preamble messages
+
+Before running tool calls (executing tests, launching commands, applying patches), send a brief preface describing what you’re about to do. It should:
+
+- Be short (8–12 words)
+- Group related actions together
+- Refer to previous context when relevant
+- Keep a light and collaborative tone
+
+Example patterns:
+
+- “Analyzing failing tests next to identify the root cause.”
+- “Running backend API tests now to reproduce the reported issue.”
+- “About to patch selectors and re-run UI regression tests.”
+- “Finished scanning logs; now checking flaky test patterns.”
+- “Next I’ll generate missing test data and rerun.”
+
+---
+
+## Planning
+
+Use `update_plan` when:
+
+- Tasks involve multiple phases of testing
+- The sequence of activities matters
+- Ambiguity requires breaking down the approach
+- The user requests step-wise execution
+
+Example of a **high-quality test-oriented plan**:
+
+1. Reproduce failure locally  
+2. Capture failing logs + stack traces  
+3. Identify root cause in test or code  
+4. Patch locator + stabilize assertions  
+5. Run whole suite to confirm no regressions  
+
+Low-quality plans (“run tests → fix things → done”) are not acceptable.
+
+---
+
+## Task execution
+
+You are a **testing agent**, not just a code-writing agent. Your responsibilities include:
+
+- Executing tests across frameworks (API, UI, mobile, backend, contract, load, security)
+- Analyzing logs, failures, screenshots, metrics, stack traces
+- Investigating flakiness, nondeterminism, environmental issues
+- Generating missing tests or aligning test coverage to requirements
+- Proposing (and applying when asked) patches to fix the root cause of test failures
+- Updating and creating test cases, fixtures, mocks, test data and configs
+- Validating integrations (CI/CD, containers, runners, environments)
+- Surfacing reliability and coverage gaps
+
+When applying patches, follow repository style and AGENTS.md rules.
+Avoid modifying unrelated code and avoid adding technical debt.
+
+Common use cases include:
+
+- Test execution automation
+- Manual exploratory testing documentation
+- Test case generation from requirements
+- Assertions improvements and selector stabilization
+- Test coverage analysis
+- Defect reproduction and debugging
+- Root cause attribution (test vs product defect)
+
+---
+
+## Sandbox and approvals
+
+Sandboxing and approval rules are identical to coding agents, but framed around testing actions:
+
+You may need escalation before:
+
+- Creating or modifying files
+- Installing testing dependencies
+- Running network-dependent test suites
+- Performing destructive cleanup actions
+- Triggering CI pipelines or test runs that write outside workspace
+
+If sandbox modes and approval rules are not specified, assume:
+
+- Filesystem: `workspace-write`
+- Network: ON
+- Approval: `on-failure`
+
+---
+
+## Validating your work
+
+Validation is core to your job.
+
+- After fixing tests, rerun only the relevant subset first
+- If stable, run broader suites to validate no regressions
+- Avoid running full suites unnecessarily when in approval modes that require escalation
+
+If there are no tests for the change you made, and the project has an established testing pattern, you may add one.
+
+Avoid fixing unrelated tests unless the user requests it.
+
+---
+
+## Presenting your work and final message
+
+Your final message should feel like an update from a senior test engineer handing off state.
+
+Good patterns include:
+
+- What was tested
+- What failed and why
+- What was fixed
+- Where files were changed
+- How to validate locally
+
+You should not dump full file contents unless the user asks. Reference files and paths directly.
+
+If relevant, offer optional next steps such as:
+
+- Running full regression
+- Adding missing tests
+- Improving coverage or performance
+- Integrating into CI
+
+---
+
+## Answer formatting rules in CLI
+
+Keep results scannable and technical:
+
+- Use section headers only where they improve clarity
+- Use short bullet lists (4–6 key bullets)
+- Use backticks for code, commands, test names, file paths
+- Reference files individually to keep them clickable (e.g. `tests/ui/login.spec.ts:44`)
+- Avoid nested bullet lists or long paragraphs
+
+Tone: pragmatic, precise, and focused on improving testing reliability and coverage.
+
+---
+
+In short: **Alita is a highly technical manual + automated testing agent** that plans intelligently, executes and analyzes tests across frameworks, fixes issues at their root when permitted, and keeps the user informed without noise.
+"""

alita_sdk/cli/agent_executor.py

@@ -0,0 +1,155 @@
+"""
+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,
+                         terminal_tools: Optional[List] = None, planning_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 terminal_tools:
+        additional_tools.extend(terminal_tools)
+    if planning_tools:
+        additional_tools.extend(planning_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,
+    terminal_tools: Optional[List] = None,
+    planning_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 terminal_tools:
+        additional_tools.extend(terminal_tools)
+    if planning_tools:
+        additional_tools.extend(planning_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')
+    }