clerk-sdk 0.5.2__py3-none-any.whl → 0.5.4__py3-none-any.whl

clerk/__init__.py

@@ -1,4 +1,4 @@
 from .client import Clerk
 
 
-__version__ = "0.5.2"
+__version__ = "0.5.4"

clerk/development/cli.py

@@ -53,26 +53,58 @@ def main():
         help="GUI automation commands"
     )
     gui_subparsers = gui_parser.add_subparsers(dest="gui_command", help="GUI subcommands")
-    
+
     # GUI connect subcommand
     gui_connect_parser = gui_subparsers.add_parser(
         "connect",
         help="Start interactive GUI automation test session"
     )
 
+    # GUI graph check subcommand
+    gui_graph_parser = gui_subparsers.add_parser(
+        "graph", help="Graph analysis commands"
+    )
+    gui_graph_subparsers = gui_graph_parser.add_subparsers(
+        dest="graph_command", help="Graph subcommands"
+    )
+
+    gui_graph_check_parser = gui_graph_subparsers.add_parser(
+        "check", help="Check and visualize state machine graph structure"
+    )
+    gui_graph_check_parser.add_argument(
+        "--module-path",
+        type=str,
+        required=False,
+        default=None,
+        help="Path to the Python file containing the state machine (defaults to src/main.py)",
+    )
+
     # Schema command group
     schema_parser = subparsers.add_parser(
         "schema",
         help="Schema management commands"
     )
     schema_subparsers = schema_parser.add_subparsers(dest="schema_command", help="Schema subcommands")
-    
+
     # Schema fetch subcommand
     schema_fetch_parser = schema_subparsers.add_parser(
         "fetch",
         help="Fetch and generate Pydantic models from project schema"
     )
 
+    # Code command group
+    code_parser = subparsers.add_parser(
+        "code", help="Custom code development and testing commands"
+    )
+    code_subparsers = code_parser.add_subparsers(
+        dest="code_command", help="Code subcommands"
+    )
+
+    # Code run subcommand
+    code_run_parser = code_subparsers.add_parser(
+        "run", help="Run custom code with test payloads"
+    )
+
     args = parser.parse_args()
 
     # Show help if no command specified
@@ -90,16 +122,27 @@ def main():
         if not hasattr(args, 'gui_command') or not args.gui_command:
             gui_parser.print_help()
             sys.exit(1)
-        
+
         if args.gui_command == "connect":
             from clerk.development.gui.test_session import main as gui_main
             gui_main()
 
+        elif args.gui_command == "graph":
+            if not hasattr(args, "graph_command") or not args.graph_command:
+                print("Error: graph command requires a subcommand")
+                print("Available subcommands: check")
+                sys.exit(1)
+
+            if args.graph_command == "check":
+                from clerk.development.gui.graph_checker import check_graph
+
+                check_graph(args.module_path)
+
     elif args.command == "schema":
         if not hasattr(args, 'schema_command') or not args.schema_command:
             schema_parser.print_help()
             sys.exit(1)
-        
+
         if args.schema_command == "fetch":
             from clerk.development.schema.fetch_schema import main_with_args
             project_id = os.getenv("PROJECT_ID")
@@ -108,6 +151,16 @@ def main():
                 sys.exit(1)
             main_with_args(project_id, project_root)
 
+    elif args.command == "code":
+        if not hasattr(args, "code_command") or not args.code_command:
+            code_parser.print_help()
+            sys.exit(1)
+
+        if args.code_command == "run":
+            from clerk.development.code_runner import main_with_args
+
+            main_with_args(project_root)
+
 
 if __name__ == "__main__":
     main()

clerk/development/code_runner.py

@@ -0,0 +1,384 @@
+"""Code runner module for testing custom code with payloads."""
+import json
+import sys
+from pathlib import Path
+from typing import Any, Dict, Optional
+from importlib import import_module
+import importlib.util
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.prompt import Confirm, Prompt
+from rich import print as rprint
+
+console = Console()
+
+
+def _generate_structured_data_code(structured_data_class) -> str:
+    """Generate code for StructuredData initialization with all fields.
+    
+    Args:
+        structured_data_class: The StructuredData class from schema
+        
+    Returns:
+        String with indented field assignments
+    """
+    from typing import get_origin, get_args
+    from pydantic import BaseModel
+    
+    lines = []
+    
+    # Get model fields
+    if hasattr(structured_data_class, 'model_fields'):
+        fields = structured_data_class.model_fields
+        
+        for field_name, field_info in fields.items():
+            annotation = field_info.annotation
+            
+            # Check if it's a List type
+            origin = get_origin(annotation)
+            if origin is list:
+                lines.append(f"        {field_name}=[],")
+            # Check if it's an Optional type
+            elif origin is type(None) or (hasattr(annotation, '__origin__') and annotation.__origin__ is type(None)):
+                lines.append(f"        {field_name}=None,")
+            # Check if the annotation is a BaseModel subclass
+            else:
+                # Try to check if it's a BaseModel (handle Optional types)
+                actual_type = annotation
+                if origin:
+                    # For Optional[Type], get the actual type
+                    args = get_args(annotation)
+                    if args:
+                        # Filter out NoneType
+                        non_none_args = [arg for arg in args if arg is not type(None)]
+                        if non_none_args:
+                            actual_type = non_none_args[0]
+                
+                # Check if actual_type is a class and subclass of BaseModel
+                try:
+                    if isinstance(actual_type, type) and issubclass(actual_type, BaseModel):
+                        class_name = actual_type.__name__
+                        lines.append(f"        {field_name}={class_name}(),")
+                    else:
+                        lines.append(f"        {field_name}=None,")
+                except (TypeError, AttributeError):
+                    lines.append(f"        {field_name}=None,")
+    
+    return "\n".join(lines)
+
+
+def find_test_payloads(project_root: Path) -> list[Path]:
+    """Find all test payload Python files in test/payloads directory.
+    
+    Args:
+        project_root: Project root directory
+        
+    Returns:
+        List of Path objects for payload files
+    """
+    payload_dir = project_root / "test" / "payloads"
+    
+    if not payload_dir.exists():
+        return []
+    
+    # Find all .py files except __init__.py
+    return [p for p in payload_dir.glob("*.py") if p.name != "__init__.py"]
+
+
+def create_test_payload_template(project_root: Path) -> Path:
+    """Create a template test payload Python file.
+    
+    Args:
+        project_root: Project root directory
+        
+    Returns:
+        Path to the created template file
+    """
+    payload_dir = project_root / "test" / "payloads"
+    payload_dir.mkdir(parents=True, exist_ok=True)
+    
+    # Check if schema exists
+    schema_path = project_root / "src" / "schema.py"
+    if not schema_path.exists():
+        console.print("[red]x[/red] No schema found. Run 'clerk schema fetch' first.")
+        console.print("[dim]Cannot generate test payload without schema.[/dim]")
+        sys.exit(1)
+    
+    console.print("[green]✓[/green] Found schema at src/schema.py")
+    
+    # Load schema to generate structured data template
+    structured_data_code = None
+    try:
+        # Add src to path
+        src_path = str(project_root / "src")
+        if src_path not in sys.path:
+            sys.path.insert(0, src_path)
+        
+        spec = importlib.util.spec_from_file_location("schema", schema_path)
+        if spec and spec.loader:
+            schema_module = importlib.util.module_from_spec(spec)
+            spec.loader.exec_module(schema_module)
+            
+            if hasattr(schema_module, "StructuredData"):
+                structured_data_class = getattr(schema_module, "StructuredData")
+                # Generate code with all fields
+                structured_data_code = _generate_structured_data_code(structured_data_class)
+    except Exception as e:
+        console.print(f"[red]x[/red] Could not load schema: {str(e)}")
+        sys.exit(1)
+    
+    if not structured_data_code:
+        console.print("[red]x[/red] Could not generate structured data code from schema.")
+        sys.exit(1)
+    
+    # Get name from user
+    name = Prompt.ask(
+        "Enter a name for this test payload",
+        default="test_payload_1"
+    )
+    
+    # Ensure .py extension
+    if not name.endswith(".py"):
+        name = f"{name}.py"
+    
+    payload_path = payload_dir / name
+    
+    # Load and populate template
+    template_dir = Path(__file__).parent / "templates"
+    template_path = template_dir / "test_payload.py.template"
+    template_code = template_path.read_text(encoding="utf-8")
+    # Replace placeholder with actual fields
+    template_code = template_code.replace("{structured_data_fields}", structured_data_code)
+    
+    # Write the template
+    with open(payload_path, "w", encoding="utf-8") as f:
+        f.write(template_code)
+    
+    console.print(f"\n[green]✓[/green] Created template payload: {payload_path}")
+    console.print("\n[yellow]Please edit this file to customize your test data before continuing.[/yellow]")
+    
+    return payload_path
+
+
+def select_payload(payloads: list[Path]) -> Path:
+    """Let user select a payload by number.
+    
+    Args:
+        payloads: List of payload file paths
+        
+    Returns:
+        Selected payload path
+    """
+    console.print("\n[bold]Available test payloads:[/bold]")
+    for i, payload in enumerate(payloads, 1):
+        console.print(f"  [cyan]{i}[/cyan]. {payload.stem}")
+    
+    while True:
+        try:
+            choice = Prompt.ask(
+                "\nSelect a payload",
+                default="1"
+            )
+            idx = int(choice) - 1
+            if 0 <= idx < len(payloads):
+                return payloads[idx]
+            else:
+                console.print(f"[red]Please enter a number between 1 and {len(payloads)}[/red]")
+        except ValueError:
+            console.print("[red]Please enter a valid number[/red]")
+
+
+def load_payload(payload_path: Path, project_root: Path):
+    """Load payload from Python module.
+    
+    Args:
+        payload_path: Path to payload Python file
+        project_root: Project root directory
+        
+    Returns:
+        ClerkCodePayload object
+    """
+    # Add project root and src to path so imports work
+    project_root_str = str(project_root)
+    src_path = str(project_root / "src")
+    
+    if project_root_str not in sys.path:
+        sys.path.insert(0, project_root_str)
+    if src_path not in sys.path:
+        sys.path.insert(0, src_path)
+    
+    # Load the payload module
+    spec = importlib.util.spec_from_file_location(
+        f"test_payload_{payload_path.stem}", 
+        payload_path
+    )
+    if not spec or not spec.loader:
+        raise ImportError(f"Could not load payload module from {payload_path}")
+    
+    payload_module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(payload_module)
+    
+    # Get the payload object
+    if not hasattr(payload_module, "payload"):
+        raise AttributeError(f"Payload module must define a 'payload' variable")
+    
+    return payload_module.payload
+
+
+def run_main_with_payload(project_root: Path, payload_path: Path):
+    """Run main() from src/main.py with the selected payload.
+
+    Args:
+        project_root: Project root directory
+        payload_path: Path to the payload Python file
+    """
+    console.print()
+    console.print(Panel(
+        f"[bold]Running main() with payload: {payload_path.name}[/bold]",
+        style="cyan"
+    ))
+
+    # Load payload
+    try:
+        payload_obj = load_payload(payload_path, project_root)
+        console.print("[green]✓[/green] Loaded payload")
+    except Exception as e:
+        console.print(f"[red]x[/red] Failed to load payload: {str(e)}")
+        import traceback
+        console.print("[dim]" + traceback.format_exc() + "[/dim]")
+        sys.exit(1)
+
+    # Find main.py
+    main_path = project_root / "src" / "main.py"
+    if not main_path.exists():
+        console.print(f"[red]x[/red] main.py not found at {main_path}")
+        sys.exit(1)
+
+    # Add src to path
+    src_path = str(project_root / "src")
+    if src_path not in sys.path:
+        sys.path.insert(0, src_path)
+
+    # Start debugpy server and wait for VS Code to attach
+    import debugpy
+    
+    debug_port = 5678
+    
+    # Check if already running under debugger
+    if not debugpy.is_client_connected():
+        console.print(f"\n[cyan]Starting debug server on port {debug_port}...[/cyan]")
+        debugpy.listen(("localhost", debug_port))
+        
+        console.print()
+        console.print("[bold yellow]⚡ Ready for debugging![/bold yellow]")
+        console.print()
+        console.print("[bold]To start debugging:[/bold]")
+        console.print("  [cyan]→ Press F5 in VS Code[/cyan]")
+        console.print("  [dim]or select 'Clerk: Debug Code Run' from the debug panel[/dim]")
+        console.print()
+        console.print("[dim]Press Ctrl+C to skip debugging and run without debugger[/dim]\n")
+        
+        try:
+            debugpy.wait_for_client()
+            console.print("[green]✓[/green] Debugger attached!\n")
+        except KeyboardInterrupt:
+            console.print("\n[yellow]Skipping debugger, running without debug...[/yellow]\n")
+    else:
+        console.print("\n[green]✓[/green] Already running under debugger\n")
+
+    # Import and run
+    try:
+        console.print()
+        console.print("[bold cyan]═══════════════════════════════════════════════════════[/bold cyan]")
+        console.print("[bold cyan]                    Starting Execution                    [/bold cyan]")
+        console.print("[bold cyan]═══════════════════════════════════════════════════════[/bold cyan]")
+        console.print()
+
+        # Import main module
+        spec = importlib.util.spec_from_file_location("main", main_path)
+        if spec and spec.loader:
+            main_module = importlib.util.module_from_spec(spec)
+            spec.loader.exec_module(main_module)
+
+            # Call main
+            if hasattr(main_module, "main"):
+                # Run main with the loaded payload
+                result = main_module.main(payload_obj)
+
+                console.print()
+                console.print("[bold cyan]═══════════════════════════════════════════════════════[/bold cyan]")
+                console.print("[bold cyan]                   Execution Complete                    [/bold cyan]")
+                console.print("[bold cyan]═══════════════════════════════════════════════════════[/bold cyan]")
+                console.print()
+
+                # Show result
+                if result:
+                    console.print("[bold]Result:[/bold]")
+                    console.print(Panel(
+                        f"Document ID: {result.document.id}\n"
+                        f"Run ID: {result.run_id}",
+                        title="Execution Result",
+                        style="green"
+                    ))
+
+                    # Show updated structured_data
+                    if result.structured_data:
+                        console.print("\n[bold]Updated Structured Data:[/bold]")
+                        rprint(result.structured_data)
+                else:
+                    console.print("[yellow]![/yellow] No result returned")
+            else:
+                console.print(f"[red]x[/red] No main() function found in {main_path}")
+                sys.exit(1)
+        else:
+            console.print(f"[red]x[/red] Could not load {main_path}")
+            sys.exit(1)
+
+    except Exception as e:
+        console.print()
+        console.print(f"[red]x Error during execution:[/red] {str(e)}")
+        import traceback
+        console.print("[dim]" + traceback.format_exc() + "[/dim]")
+        sys.exit(1)
+
+
+def main_with_args(project_root: Path):
+    """Main entry point for code runner.
+    
+    Args:
+        project_root: Project root directory
+    """
+    console.print()
+    console.print(Panel(
+        "[bold]Clerk Code Runner[/bold]\n"
+        "Run your custom code with test payloads",
+        style="cyan"
+    ))
+    
+    # Find payloads
+    payloads = find_test_payloads(project_root)
+    
+    if not payloads:
+        console.print("\n[yellow]No test payloads found in test/payloads/[/yellow]")
+        
+        if Confirm.ask("Would you like to generate a template payload?", default=True):
+            payload_path = create_test_payload_template(project_root)
+            
+            console.print("\n[bold]Next steps:[/bold]")
+            console.print(f"1. Edit {payload_path} with your test data")
+            console.print("2. Run [cyan]clerk code run[/cyan] again to execute")
+            return
+        else:
+            console.print("\n[dim]Create a Python file in test/payloads/ and run again.[/dim]")
+            return
+    
+    # Show available payloads
+    console.print(f"\n[green]✓[/green] Found {len(payloads)} test payload(s)")
+    
+    # Let user select
+    selected_payload = select_payload(payloads)
+    console.print(f"\n[green]→[/green] Selected: {selected_payload.name}")
+    
+    # Run with selected payload
+    run_main_with_payload(project_root, selected_payload)

clerk/development/gui/graph_checker.py

@@ -0,0 +1,216 @@
+"""Graph checker utility for ScreenPilot state machines"""
+import sys
+import importlib.util
+import logging
+from pathlib import Path
+from typing import Set, List, Optional
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+console = Console()
+
+
+class ErrorCapturingHandler(logging.Handler):
+    """Custom logging handler to capture error messages during module load"""
+    
+    def __init__(self):
+        super().__init__()
+        self.errors: List[str] = []
+        self.setLevel(logging.ERROR)
+    
+    def emit(self, record):
+        if "involves undefined state" in record.getMessage():
+            self.errors.append(record.getMessage())
+
+
+def load_module_from_path(module_path: str) -> ErrorCapturingHandler:
+    """
+    Load a Python module from a file path.
+    
+    Args:
+        module_path: Path to the Python file containing the state machine
+        
+    Returns:
+        ErrorCapturingHandler with any errors captured during load
+    """
+    path = Path(module_path).resolve()
+    if not path.exists():
+        raise FileNotFoundError(f"Module not found: {module_path}")
+    
+    # Set up error capturing handler
+    error_handler = ErrorCapturingHandler()
+    logger = logging.getLogger("state_machine.py")
+    logger.addHandler(error_handler)
+    
+    try:
+        # Add the parent directory to sys.path for relative imports
+        parent_dir = str(path.parent)
+        if parent_dir not in sys.path:
+            sys.path.insert(0, parent_dir)
+        
+        # Load the module
+        spec = importlib.util.spec_from_file_location(path.stem, path)
+        if spec is None or spec.loader is None:
+            raise ImportError(f"Could not load module from {module_path}")
+        
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[path.stem] = module
+        
+        # Capture ValueError exceptions during module execution
+        try:
+            spec.loader.exec_module(module)
+        except ValueError as e:
+            error_msg = str(e)
+            if "already registered" in error_msg or "provide a condition function" in error_msg:
+                # This is a fatal error - the transition can't be registered
+                # Re-raise it so we can show it properly
+                raise ValueError(f"Duplicate transition error: {error_msg}") from e
+            else:
+                raise
+    finally:
+        # Clean up handler
+        logger.removeHandler(error_handler)
+    
+    return error_handler
+
+
+def check_graph(module_path: Optional[str] = None):
+    """
+    Main function to check a ScreenPilot state machine graph.
+    
+    Args:
+        module_path: Path to the Python file containing the state machine.
+                    If None, defaults to src/main.py in current directory.
+    """
+    try:
+        # Clear any existing graph state from ScreenPilot before loading
+        from clerk.gui_automation.ui_state_machine import ScreenPilot
+        import networkx as nx
+        ScreenPilot._graph = nx.MultiDiGraph()
+        
+        # Default to src/main.py if no path provided
+        if module_path is None:
+            default_path = Path.cwd() / "src" / "main.py"
+            if not default_path.exists():
+                console.print(f"\n[red]Error: Default file not found: {default_path}[/red]")
+                console.print("[dim]Specify --module-path to check a different file[/dim]")
+                sys.exit(1)
+            module_path = str(default_path)
+            console.print(f"[dim]Using default: {module_path}[/dim]")
+        
+        # Load the module (this will trigger state/transition registrations)
+        console.print(f"\n[dim]Loading module: {module_path}[/dim]")
+        error_handler = load_module_from_path(module_path)
+        
+        graph = ScreenPilot._graph
+        
+        if len(graph.nodes()) == 0:
+            console.print("\n[yellow]⚠️  Warning: No states found in the graph.[/yellow]")
+            console.print("[dim]Make sure your module imports and registers states using decorators[/dim]")
+            return
+        
+        # Count states and transitions
+        state_count = len(graph.nodes())
+        transition_count = len(graph.edges())
+        
+        # Show statistics
+        console.print()
+        stats_table = Table(show_header=False, box=None, padding=(0, 2))
+        stats_table.add_column(style="cyan bold")
+        stats_table.add_column(style="white")
+        stats_table.add_row("States:", str(state_count))
+        stats_table.add_row("Transitions:", str(transition_count))
+        
+        console.print(Panel(
+            stats_table,
+            title="[bold]Graph Statistics[/bold]",
+            style="cyan"
+        ))
+        
+        # Collect all valid state names
+        valid_states: Set[str] = set(graph.nodes())
+        
+        # Collect all state names referenced in transitions
+        referenced_states: Set[str] = set()
+        for u, v in graph.edges():
+            referenced_states.add(u)
+            referenced_states.add(v)
+        
+        console.print()
+        console.print(Panel("[bold]Graph Checks[/bold]", style="cyan"))
+        console.print()
+        
+        has_warnings = False
+        has_info = False
+        
+        # Check for invalid state names in transitions (from captured errors)
+        if error_handler.errors:
+            has_warnings = True
+            console.print(f"[yellow]⚠️  WARNING: Found {len(error_handler.errors)} transition(s) with invalid state names:[/yellow]")
+            for error in error_handler.errors:
+                # Extract the relevant info from the error message
+                console.print(f"   [yellow]• {error.replace('Error: ', '')}[/yellow]")
+            console.print()
+        
+        # Check for orphaned states (no incoming AND no outgoing transitions)
+        orphaned = [
+            node for node in graph.nodes() 
+            if graph.in_degree(node) == 0 and graph.out_degree(node) == 0
+        ]
+        if orphaned:
+            has_warnings = True
+            console.print(f"[yellow]⚠️  WARNING: Found {len(orphaned)} orphaned state(s) (no incoming or outgoing transitions):[/yellow]")
+            for state in sorted(orphaned):
+                console.print(f"   [yellow]• {state}[/yellow]")
+            console.print()
+        
+        # Info: States with no incoming transitions
+        no_incoming = [node for node in graph.nodes() if graph.in_degree(node) == 0 and graph.out_degree(node) > 0]
+        if no_incoming:
+            has_info = True
+            console.print(f"[blue]ℹ️  INFO: Found {len(no_incoming)} state(s) with no incoming transitions (entry points):[/blue]")
+            for state in sorted(no_incoming):
+                console.print(f"   [blue]• {state}[/blue]")
+            console.print()
+        
+        # Info: States with no outgoing transitions
+        no_outgoing = [node for node in graph.nodes() if graph.out_degree(node) == 0 and graph.in_degree(node) > 0]
+        if no_outgoing:
+            has_info = True
+            console.print(f"[blue]ℹ️  INFO: Found {len(no_outgoing)} state(s) with no outgoing transitions (terminal states):[/blue]")
+            for state in sorted(no_outgoing):
+                console.print(f"   [blue]• {state}[/blue]")
+            console.print()
+        
+        # All good message
+        if not has_warnings:
+            console.print("[green]✅ No issues detected.[/green]")
+            console.print()
+        
+    except Exception as e:
+        console.print(f"\n[red]Error checking graph: {e}[/red]")
+        import traceback
+        console.print(f"[dim]{traceback.format_exc()}[/dim]")
+        sys.exit(1)
+
+
+def main():
+    """Entry point for standalone script execution"""
+    import argparse
+    
+    parser = argparse.ArgumentParser(description="Check ScreenPilot state machine graph")
+    parser.add_argument(
+        "--module-path",
+        required=False,
+        default=None,
+        help="Path to the Python file containing the state machine (defaults to src/main.py)"
+    )
+    
+    args = parser.parse_args()
+    check_graph(args.module_path)
+
+
+if __name__ == "__main__":
+    main()

clerk/development/gui/test_session.py

@@ -318,9 +318,9 @@ def main():
         run_id="test-session-run",
     )
 
-    # Show spinner while the decorator establishes WebSocket connection
-    with console.status("[dim]Waiting for tool to connect...", spinner="dots"):
-        start_interactive_session(payload)
+    # The @gui_automation decorator will establish the connection
+    # and the function itself will print the connection status
+    start_interactive_session(payload)
 
 
 if __name__ == "__main__":

clerk/development/init_project.py

@@ -145,6 +145,25 @@ def create_init_py(target_dir: Path) -> None:
     console.print(f"[green]+[/green] Created {init_path}")
 
 
+def create_vscode_launch_config() -> None:
+    """Create .vscode/launch.json for debugging."""
+    vscode_dir = Path(".vscode")
+    vscode_dir.mkdir(exist_ok=True)
+    
+    launch_path = vscode_dir / "launch.json"
+    
+    if launch_path.exists():
+        console.print(f"[yellow]![/yellow]  {launch_path} already exists, skipping...")
+        return
+    
+    content = read_template("launch.json.template")
+    
+    with open(launch_path, "w", encoding='utf-8') as f:
+        f.write(content)
+    
+    console.print(f"[green]+[/green] Created {launch_path}")
+
+
 def create_gui_structure(target_dir: Path) -> None:
     """Create GUI automation folder structure with template files.
     
@@ -241,6 +260,9 @@ def init_project(
     # Create __init__.py
     create_init_py(target_dir)
 
+    # Create VS Code launch configuration
+    create_vscode_launch_config()
+
     # Create GUI automation structure if requested
     if with_gui:
         create_gui_structure(target_dir)

clerk/development/templates/launch.json.template

@@ -0,0 +1,20 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Clerk: Debug Code Run",
+            "type": "debugpy",
+            "request": "attach",
+            "connect": {
+                "host": "localhost",
+                "port": 5678
+            },
+            "pathMappings": [
+                {
+                    "localRoot": "${workspaceFolder}/src",
+                    "remoteRoot": "${workspaceFolder}/src"
+                }
+            ]
+        }
+    ]
+}

clerk/development/templates/main_gui.py.template

@@ -19,7 +19,7 @@ def main(payload: ClerkCodePayload):
     data = StructuredData.model_validate(payload.structured_data)
     logger.info("Custom code started")    
 
-    def goal_function(current_state: str, process_variables: StructuredData) -> None:
+    def goal_function(current_state: str, data: StructuredData) -> None:
         """
         Goal function for the state machine.
         Args:
@@ -31,7 +31,7 @@ def main(payload: ClerkCodePayload):
         if True:  # Use an actual condition based on state and/or process variables to complete the automation
             raise SuccessfulCompletion()
 
-    ai_recovery_instructions = "\\n - ".join(
+    ai_recovery_instructions = "\n - ".join(
         [
             "Instructions on how to deal with possible issues using Clerk UI Actions.",            
         ]
@@ -39,7 +39,7 @@ def main(payload: ClerkCodePayload):
 
     ScreenPilot.configure(ai_recovery_instructions=ai_recovery_instructions)
     exit_reason = ScreenPilot.run(
-        goal_function, process_variables=process_variables, doc_id=payload.document.id
+        goal_function, data=data, doc_id=payload.document.id
     )
         
 

clerk/development/templates/tasks.json.template

@@ -0,0 +1,25 @@
+{
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "Start Clerk Code Run Debug Server",
+            "type": "shell",
+            "command": "clerk",
+            "args": ["code", "run"],
+            "isBackground": true,
+            "problemMatcher": {
+                "pattern": {
+                    "regexp": "^$",
+                    "file": 1,
+                    "location": 2,
+                    "message": 3
+                },
+                "background": {
+                    "activeOnStart": true,
+                    "beginsPattern": "Starting debug server",
+                    "endsPattern": "Waiting for debugger to attach"
+                }
+            }
+        }
+    ]
+}

clerk/development/templates/test_payload.py.template

@@ -0,0 +1,32 @@
+"""Test payload for local testing."""
+from datetime import datetime
+from clerk.decorator.models import ClerkCodePayload, Document, File
+from src.schema import *
+
+# Define your test payload here
+# 
+# NOTE: Files can be local! The mock Clerk client will read from local paths.
+# Put your test files in test/payloads/ and reference them like:
+#   File(name="invoice.pdf", url="test/payloads/invoice.pdf")
+# 
+# When your code calls client.get_files_document(), it will return ParsedFile
+# objects with the actual content from these local files.
+
+payload = ClerkCodePayload(
+    document=Document(
+        id="test-doc-123",
+        message_subject="Test Document",
+        message_content="This is a test document for local testing",
+        files=[
+            File(
+                name="example.pdf",
+                url="test/payloads/example.pdf"  # Use local file path
+            )
+        ],
+        upload_date=datetime(2025, 1, 1, 0, 0, 0)
+    ),
+    structured_data=StructuredData(
+{structured_data_fields}
+    ).model_dump(),
+    run_id="test-run-001"
+)

clerk/gui_automation/client_actor/client_actor.py

@@ -58,7 +58,7 @@ async def _perform_action_ws(payload: Dict[str, Any]) -> PerformActionResponse:
         try:
             ack = await asyncio.wait_for(global_ws.recv(), 10)
             if ack == "OK":
-                action_info = await asyncio.wait_for(global_ws.recv(), 10)
+                action_info = await asyncio.wait_for(global_ws.recv(), 60)
                 return PerformActionResponse(**json.loads(action_info))
             else:
                 raise RuntimeError("Received ACK != OK")

{clerk_sdk-0.5.2.dist-info → clerk_sdk-0.5.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clerk-sdk
-Version: 0.5.2
+Version: 0.5.4
 Summary: Library for interacting with Clerk
 Project-URL: Homepage, https://github.com/F-ONE-Group/clerk_pypi
 Author-email: F-One <contact@f-one.group>
@@ -10,6 +10,7 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Requires-Python: >=3.11
 Requires-Dist: backoff<3.0.0,>=2.0.0
+Requires-Dist: debugpy<2.0.0,>=1.8.0
 Requires-Dist: pydantic<3.0.0,>=2.0.0
 Requires-Dist: python-dotenv>=1.0.0
 Requires-Dist: requests<3.0.0,>=2.32.3

{clerk_sdk-0.5.2.dist-info → clerk_sdk-0.5.4.dist-info}/RECORD

@@ -1,19 +1,24 @@
-clerk/__init__.py,sha256=9nx4P_SmXMhJwrqwChgZ2aTJHSWCp3h64vMPXt06Ab4,50
+clerk/__init__.py,sha256=sQnCEW-ctm8zuDSgan3OWyjXaHvo3pZCgzRADiavzbI,50
 clerk/base.py,sha256=lbFTdpdDfsmYIQUFH93S1aw0-L6GNJwAcubW1tdMFX4,3967
 clerk/client.py,sha256=JGhDUb4m8R7ZTHLxFsAwAw0vNA1kxewg5-GC6qOFYDk,5244
 clerk/decorator/__init__.py,sha256=yGGcS17VsZ7cZ-hVGCm3I3vGDJMiJIAqmDGzriIi0DI,65
 clerk/decorator/models.py,sha256=nFMdVSG3nJ4hrEXs9YbI_GgjHbVjhSWZokOCzUh-lqQ,521
 clerk/decorator/task_decorator.py,sha256=H8caRvNvvl-IRwyREP66gBGVM-SpQJ1W7oAFImO-6Jw,3769
 clerk/development/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-clerk/development/cli.py,sha256=-2VwjWiGHypxrOSCpFMXSAuJKvLfBqeCmaOXsUAOraE,3431
-clerk/development/init_project.py,sha256=pjEQKkpqStA-Z21sc4jswhIcOxJ3xgrxHLalNOsCiBU,10665
-clerk/development/gui/test_session.py,sha256=Lal3Q4kw9e-QXshE2v5zaV7aSWm4ilaWKyZzeHfAOJ4,10554
+clerk/development/cli.py,sha256=hfe0FECLBsxUhio8mJvpkiu8d1lWNtXz3sW1c-vbcHk,5187
+clerk/development/code_runner.py,sha256=GNMAO_Lb23jI6TnEWBoevzuha8OW8icS30teR3Qe5xs,14350
+clerk/development/init_project.py,sha256=Rqw_CVyPzAxNj0LVQSJfDC-Xt6ldvtjiM_QNM2ExB5Q,11304
+clerk/development/gui/graph_checker.py,sha256=3PaKplOt6UN-zeYtGmwMF42CjVQfQEV1xo7U-uiKEfs,8176
+clerk/development/gui/test_session.py,sha256=TRhkachA8jEYGOqA5Xda0Oddo8AcVFe7urkjURGtqj8,10527
 clerk/development/schema/fetch_schema.py,sha256=jIGO2ZFvgVnFz5_pw1C2Nf48OR1skZEf7fTyOLJAg5A,12046
 clerk/development/templates/exceptions.py.template,sha256=BN9MhFhH435WX3e6HTd7bmakOD6Kh24bDPDMHBrArvQ,446
+clerk/development/templates/launch.json.template,sha256=BoaXaQwuwekyZgNydifnB5Xh_VpQzSygOAXNBt8-1Xk,491
 clerk/development/templates/main_basic.py.template,sha256=9Cs5BC8FK2uFbxYEJfyHfpzbSz9tq2Q47XdUncbL0rM,550
-clerk/development/templates/main_gui.py.template,sha256=e06QKs54DAVUWtz7xiDq1IKnAPNA5ecmnBuKlk9wC30,1796
+clerk/development/templates/main_gui.py.template,sha256=sg0BcWBRFykXzR8AmxNZo5CTWZzVcwJtEqFFSKyEJR4,1756
 clerk/development/templates/rollbacks.py.template,sha256=VeCVJhEwqol9LwRL5OfxIQUSOadbhGYYWrqjuqxO1bM,486
 clerk/development/templates/states.py.template,sha256=d0OjZTdP8DNMt4YE0PIBPQ8jSpgll4u31s6n9aSJ1Mw,404
+clerk/development/templates/tasks.json.template,sha256=mrx-YZEokdv8RsqxxFeW-hi8K8w5VrqLVxkgoJ3djPk,711
+clerk/development/templates/test_payload.py.template,sha256=7X5hDITUWNngrIAREn6TPt13gGReHlfqyXjurv7kNbI,1062
 clerk/development/templates/transitions.py.template,sha256=PtkBbRxbEzqTqRa7zNDxrk8I1UhrithhBSKaO9r65uA,728
 clerk/exceptions/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 clerk/exceptions/exceptions.py,sha256=gSCma06b6W6c0NrA2rhzd5YjFhZGa6caShX07lo-_3E,1291
@@ -25,7 +30,7 @@ clerk/gui_automation/action_model/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeR
 clerk/gui_automation/action_model/model.py,sha256=yzaCyEMOH3YMkPBf6IwUMuu69-xyf78HzmthiewgWQY,3811
 clerk/gui_automation/action_model/utils.py,sha256=xzFxgN-bTK6HKGS7J-esQZ-ePj_yG72T-2ZVhcWvKjw,798
 clerk/gui_automation/client_actor/__init__.py,sha256=SVuL6-oo1Xc0oJkjMKrO6mJwpPGjrCLKhDV6r2Abtf8,66
-clerk/gui_automation/client_actor/client_actor.py,sha256=D2mQAHitF5x-dZzt70ZPw_fZGwuwWTAAwuHXbdKVKfE,5475
+clerk/gui_automation/client_actor/client_actor.py,sha256=05gju2A7kvklO1vjc2v6UJ_jKLFUXDQuH7952Qq6loE,5475
 clerk/gui_automation/client_actor/exception.py,sha256=zdnImHZ88yf52Xq3aMHivEU3aJg-r2c-r8x8XZnI3ic,407
 clerk/gui_automation/client_actor/model.py,sha256=wVpFCi1w2kh4kAV8oNx489vf_SLUQnqhc02rFD5NIJA,6335
 clerk/gui_automation/decorators/__init__.py,sha256=OCgXStEumscgT-RyVy5OKS7ml1w9y-lEnjCVnxuRnQs,43
@@ -58,8 +63,8 @@ clerk/models/ui_operator.py,sha256=mKTJUFZgv7PeEt5oys28HVZxHOJsofmRQOcRpqj0dbU,2
 clerk/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 clerk/utils/logger.py,sha256=NrMIlJfVmRjjRw_N_Jngkl0qqv7btXUbg5wxcRmFEH4,3800
 clerk/utils/save_artifact.py,sha256=94aYkYNVGcSUaSWZmdjiY6Oc-3yCKb2XWCZ56IAXQqk,1158
-clerk_sdk-0.5.2.dist-info/METADATA,sha256=XWZZCU8fiiqy_m5Babh1Zd1AgnOV9esd3LpFK1OPE8o,9598
-clerk_sdk-0.5.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-clerk_sdk-0.5.2.dist-info/entry_points.txt,sha256=VoUmW07sRRSioms5pqQ4A6CYxNEyhGA93GtyBlB_wGw,53
-clerk_sdk-0.5.2.dist-info/licenses/LICENSE,sha256=GTVQl3vH6ht70wJXKC0yMT8CmXKHxv_YyO_utAgm7EA,1065
-clerk_sdk-0.5.2.dist-info/RECORD,,
+clerk_sdk-0.5.4.dist-info/METADATA,sha256=bn-CQWNQvCxpMBSl2mrPC-10sVtwvmUrt0ekLQ0FcfU,9635
+clerk_sdk-0.5.4.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+clerk_sdk-0.5.4.dist-info/entry_points.txt,sha256=VoUmW07sRRSioms5pqQ4A6CYxNEyhGA93GtyBlB_wGw,53
+clerk_sdk-0.5.4.dist-info/licenses/LICENSE,sha256=GTVQl3vH6ht70wJXKC0yMT8CmXKHxv_YyO_utAgm7EA,1065
+clerk_sdk-0.5.4.dist-info/RECORD,,