clerk-sdk 0.5.2__tar.gz → 0.5.4__tar.gz

{clerk_sdk-0.5.2 → clerk_sdk-0.5.4}/PKG-INFO

@@ -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 → clerk_sdk-0.5.4}/clerk/__init__.py

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

{clerk_sdk-0.5.2 → clerk_sdk-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_sdk-0.5.4/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_sdk-0.5.4/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_sdk-0.5.2 → clerk_sdk-0.5.4}/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_sdk-0.5.2 → clerk_sdk-0.5.4}/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_sdk-0.5.4/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_sdk-0.5.2 → clerk_sdk-0.5.4}/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_sdk-0.5.4/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_sdk-0.5.4/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_sdk-0.5.2 → clerk_sdk-0.5.4}/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 → clerk_sdk-0.5.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "clerk-sdk"
-version = "0.5.2"
+version = "0.5.4"
 description = "Library for interacting with Clerk"
 readme = "README.md"
 authors = [
@@ -22,6 +22,7 @@ dependencies = [
     "requests>=2.32.3,<3.0.0",
     "python-dotenv>=1.0.0",
     "rich>=14.2.0",
+    "debugpy>=1.8.0,<2.0.0",
 ]
 
 [project.optional-dependencies]

{clerk_sdk-0.5.2 → clerk_sdk-0.5.4}/requirements.txt

@@ -3,3 +3,4 @@ backoff >=2.0.0, <3.0.0
 requests >=2.32.3, <3.0.0
 dotenv
 rich >=14.2.0, <15.0.0
+debugpy >=1.8.0, <2.0.0

{clerk_sdk-0.5.2 → clerk_sdk-0.5.4}/setup.py

@@ -13,7 +13,7 @@ gui_requirements = get_requirements("./clerk/gui_automation")
 
 setup(
     name="clerk-sdk",
-    version="0.5.2",
+    version="0.5.4",
     description="Library for interacting with Clerk",
     long_description=open("README.md").read(),
     long_description_content_type="text/markdown",

{clerk_sdk-0.5.2 → clerk_sdk-0.5.4}/uv.lock

@@ -108,6 +108,7 @@ version = "0.5.0.dev0"
 source = { editable = "." }
 dependencies = [
     { name = "backoff" },
+    { name = "debugpy" },
     { name = "pydantic" },
     { name = "python-dotenv" },
     { name = "requests" },
@@ -127,6 +128,7 @@ gui-automation = [
 [package.metadata]
 requires-dist = [
     { name = "backoff", specifier = ">=2.0.0,<3.0.0" },
+    { name = "debugpy", specifier = ">=1.8.0,<2.0.0" },
     { name = "networkx", marker = "extra == 'all'", specifier = ">=3.5.0,<4.0.0" },
     { name = "networkx", marker = "extra == 'gui-automation'", specifier = ">=3.5.0,<4.0.0" },
     { name = "pydantic", specifier = ">=2.0.0,<3.0.0" },
@@ -138,6 +140,31 @@ requires-dist = [
 ]
 provides-extras = ["gui-automation", "all"]
 
+[[package]]
+name = "debugpy"
+version = "1.8.19"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/73/75/9e12d4d42349b817cd545b89247696c67917aab907012ae5b64bbfea3199/debugpy-1.8.19.tar.gz", hash = "sha256:eea7e5987445ab0b5ed258093722d5ecb8bb72217c5c9b1e21f64efe23ddebdb", size = 1644590, upload-time = "2025-12-15T21:53:28.044Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/80/e2/48531a609b5a2aa94c6b6853afdfec8da05630ab9aaa96f1349e772119e9/debugpy-1.8.19-cp311-cp311-macosx_15_0_universal2.whl", hash = "sha256:c5dcfa21de1f735a4f7ced4556339a109aa0f618d366ede9da0a3600f2516d8b", size = 2207620, upload-time = "2025-12-15T21:53:37.1Z" },
+    { url = "https://files.pythonhosted.org/packages/1b/d4/97775c01d56071969f57d93928899e5616a4cfbbf4c8cc75390d3a51c4a4/debugpy-1.8.19-cp311-cp311-manylinux_2_34_x86_64.whl", hash = "sha256:806d6800246244004625d5222d7765874ab2d22f3ba5f615416cf1342d61c488", size = 3170796, upload-time = "2025-12-15T21:53:38.513Z" },
+    { url = "https://files.pythonhosted.org/packages/8d/7e/8c7681bdb05be9ec972bbb1245eb7c4c7b0679bb6a9e6408d808bc876d3d/debugpy-1.8.19-cp311-cp311-win32.whl", hash = "sha256:783a519e6dfb1f3cd773a9bda592f4887a65040cb0c7bd38dde410f4e53c40d4", size = 5164287, upload-time = "2025-12-15T21:53:40.857Z" },
+    { url = "https://files.pythonhosted.org/packages/f2/a8/aaac7ff12ddf5d68a39e13a423a8490426f5f661384f5ad8d9062761bd8e/debugpy-1.8.19-cp311-cp311-win_amd64.whl", hash = "sha256:14035cbdbb1fe4b642babcdcb5935c2da3b1067ac211c5c5a8fdc0bb31adbcaa", size = 5188269, upload-time = "2025-12-15T21:53:42.359Z" },
+    { url = "https://files.pythonhosted.org/packages/4a/15/d762e5263d9e25b763b78be72dc084c7a32113a0bac119e2f7acae7700ed/debugpy-1.8.19-cp312-cp312-macosx_15_0_universal2.whl", hash = "sha256:bccb1540a49cde77edc7ce7d9d075c1dbeb2414751bc0048c7a11e1b597a4c2e", size = 2549995, upload-time = "2025-12-15T21:53:43.773Z" },
+    { url = "https://files.pythonhosted.org/packages/a7/88/f7d25c68b18873b7c53d7c156ca7a7ffd8e77073aa0eac170a9b679cf786/debugpy-1.8.19-cp312-cp312-manylinux_2_34_x86_64.whl", hash = "sha256:e9c68d9a382ec754dc05ed1d1b4ed5bd824b9f7c1a8cd1083adb84b3c93501de", size = 4309891, upload-time = "2025-12-15T21:53:45.26Z" },
+    { url = "https://files.pythonhosted.org/packages/c5/4f/a65e973aba3865794da65f71971dca01ae66666132c7b2647182d5be0c5f/debugpy-1.8.19-cp312-cp312-win32.whl", hash = "sha256:6599cab8a783d1496ae9984c52cb13b7c4a3bd06a8e6c33446832a5d97ce0bee", size = 5286355, upload-time = "2025-12-15T21:53:46.763Z" },
+    { url = "https://files.pythonhosted.org/packages/d8/3a/d3d8b48fec96e3d824e404bf428276fb8419dfa766f78f10b08da1cb2986/debugpy-1.8.19-cp312-cp312-win_amd64.whl", hash = "sha256:66e3d2fd8f2035a8f111eb127fa508469dfa40928a89b460b41fd988684dc83d", size = 5328239, upload-time = "2025-12-15T21:53:48.868Z" },
+    { url = "https://files.pythonhosted.org/packages/71/3d/388035a31a59c26f1ecc8d86af607d0c42e20ef80074147cd07b180c4349/debugpy-1.8.19-cp313-cp313-macosx_15_0_universal2.whl", hash = "sha256:91e35db2672a0abaf325f4868fcac9c1674a0d9ad9bb8a8c849c03a5ebba3e6d", size = 2538859, upload-time = "2025-12-15T21:53:50.478Z" },
+    { url = "https://files.pythonhosted.org/packages/4a/19/c93a0772d0962294f083dbdb113af1a7427bb632d36e5314297068f55db7/debugpy-1.8.19-cp313-cp313-manylinux_2_34_x86_64.whl", hash = "sha256:85016a73ab84dea1c1f1dcd88ec692993bcbe4532d1b49ecb5f3c688ae50c606", size = 4292575, upload-time = "2025-12-15T21:53:51.821Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/56/09e48ab796b0a77e3d7dc250f95251832b8bf6838c9632f6100c98bdf426/debugpy-1.8.19-cp313-cp313-win32.whl", hash = "sha256:b605f17e89ba0ecee994391194285fada89cee111cfcd29d6f2ee11cbdc40976", size = 5286209, upload-time = "2025-12-15T21:53:53.602Z" },
+    { url = "https://files.pythonhosted.org/packages/fb/4e/931480b9552c7d0feebe40c73725dd7703dcc578ba9efc14fe0e6d31cfd1/debugpy-1.8.19-cp313-cp313-win_amd64.whl", hash = "sha256:c30639998a9f9cd9699b4b621942c0179a6527f083c72351f95c6ab1728d5b73", size = 5328206, upload-time = "2025-12-15T21:53:55.433Z" },
+    { url = "https://files.pythonhosted.org/packages/f6/b9/cbec520c3a00508327476c7fce26fbafef98f412707e511eb9d19a2ef467/debugpy-1.8.19-cp314-cp314-macosx_15_0_universal2.whl", hash = "sha256:1e8c4d1bd230067bf1bbcdbd6032e5a57068638eb28b9153d008ecde288152af", size = 2537372, upload-time = "2025-12-15T21:53:57.318Z" },
+    { url = "https://files.pythonhosted.org/packages/88/5e/cf4e4dc712a141e10d58405c58c8268554aec3c35c09cdcda7535ff13f76/debugpy-1.8.19-cp314-cp314-manylinux_2_34_x86_64.whl", hash = "sha256:d40c016c1f538dbf1762936e3aeb43a89b965069d9f60f9e39d35d9d25e6b809", size = 4268729, upload-time = "2025-12-15T21:53:58.712Z" },
+    { url = "https://files.pythonhosted.org/packages/82/a3/c91a087ab21f1047db328c1d3eb5d1ff0e52de9e74f9f6f6fa14cdd93d58/debugpy-1.8.19-cp314-cp314-win32.whl", hash = "sha256:0601708223fe1cd0e27c6cce67a899d92c7d68e73690211e6788a4b0e1903f5b", size = 5286388, upload-time = "2025-12-15T21:54:00.687Z" },
+    { url = "https://files.pythonhosted.org/packages/17/b8/bfdc30b6e94f1eff09f2dc9cc1f9cd1c6cde3d996bcbd36ce2d9a4956e99/debugpy-1.8.19-cp314-cp314-win_amd64.whl", hash = "sha256:8e19a725f5d486f20e53a1dde2ab8bb2c9607c40c00a42ab646def962b41125f", size = 5327741, upload-time = "2025-12-15T21:54:02.148Z" },
+    { url = "https://files.pythonhosted.org/packages/25/3e/e27078370414ef35fafad2c06d182110073daaeb5d3bf734b0b1eeefe452/debugpy-1.8.19-py2.py3-none-any.whl", hash = "sha256:360ffd231a780abbc414ba0f005dad409e71c78637efe8f2bd75837132a41d38", size = 5292321, upload-time = "2025-12-15T21:54:16.024Z" },
+]
+
 [[package]]
 name = "idna"
 version = "3.11"