clerk-sdk 0.4.17__py3-none-any.whl → 0.5.0__py3-none-any.whl

clerk/development/init_project.py

@@ -0,0 +1,325 @@
+"""Project initialization module for Clerk custom code projects."""
+import os
+import sys
+from pathlib import Path
+from typing import Optional, Dict
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.prompt import Confirm, Prompt
+
+console = Console()
+
+
+def prompt_for_env_var(var_name: str, description: str, required: bool = True, default: str = "") -> str:
+    """Prompt user for an environment variable value."""
+    prompt_text = f"{var_name}"
+    if description:
+        prompt_text = f"{description} ({var_name})"
+    
+    while True:
+        value = Prompt.ask(prompt_text, default=default if default else None)
+        if value or not required:
+            return value if value else ""
+        console.print(f"[yellow]{var_name} is required. Please provide a value.[/yellow]")
+
+
+def create_env_file(gui_automation: bool = False) -> Dict[str, str]:
+    """Interactively create .env file with user secrets.
+    
+    Args:
+        gui_automation: Whether GUI automation is enabled (adds REMOTE_DEVICE_NAME)
+        
+    Returns:
+        Dictionary of environment variable key-value pairs
+    """
+    console.print()
+    console.print(Panel(
+        "[bold]Environment Configuration[/bold]\n"
+        "Please provide the following configuration values.", 
+        style="cyan"
+    ))
+    
+    env_vars = {
+        "CLERK_API_KEY": ("Clerk API Key", True, ""),
+        "PROJECT_ID": ("Project ID", True, ""),
+    }
+    
+    # Add REMOTE_DEVICE_NAME if GUI automation is enabled
+    if gui_automation:
+        env_vars["REMOTE_DEVICE_NAME"] = ("Remote Device Name (for GUI automation)", True, "")
+    
+    env_content = []
+    env_values = {}
+    env_path = Path(".env")
+    
+    # Check if .env already exists
+    if env_path.exists():
+        if not Confirm.ask("\n[yellow].env file already exists. Overwrite?[/yellow]", default=False):
+            console.print("[dim]Using existing .env file[/dim]")
+            return load_env_file()
+    
+    for var_name, (description, required, default) in env_vars.items():
+        value = prompt_for_env_var(var_name, description, required, default)
+        if value:
+            env_content.append(f"{var_name}={value}")
+            env_values[var_name] = value
+    
+    # Write .env file
+    with open(env_path, 'w') as f:
+        f.write('\n'.join(env_content) + '\n')
+    
+    console.print(f"\n[green]✓[/green] Created .env file with {len(env_content)} variables")
+    return env_values
+
+
+def load_env_file() -> Dict[str, str]:
+    """Load environment variables from .env file.
+    
+    Returns:
+        Dictionary of environment variable key-value pairs
+    """
+    env_values = {}
+    env_path = Path(".env")
+
+    if env_path.exists():
+        with open(env_path, 'r') as f:
+            for line in f:
+                line = line.strip()
+                if line and not line.startswith('#') and '=' in line:
+                    key, value = line.split('=', 1)
+                    env_values[key.strip()] = value.strip()
+
+    return env_values
+
+
+def read_template(template_name: str) -> str:
+    """Read a template file from the templates directory."""
+    template_dir = Path(__file__).parent / "templates"
+    template_path = template_dir / template_name
+    
+    if not template_path.exists():
+        raise FileNotFoundError(f"Template not found: {template_name}")
+    
+    with open(template_path, 'r', encoding='utf-8') as f:
+        return f.read()
+
+
+def create_main_py(target_dir: Path, with_gui: bool = False) -> None:
+    """Create main.py with or without GUI automation setup.
+    
+    Args:
+        target_dir: Target directory where main.py should be created
+        with_gui: Whether to include GUI automation functionality
+    """
+    main_path = target_dir / "main.py"
+
+    if main_path.exists():
+        console.print(f"[yellow]![/yellow]  {main_path} already exists, skipping...")
+        return
+
+    template_name = "main_gui.py.template" if with_gui else "main_basic.py.template"
+    content = read_template(template_name)
+
+    with open(main_path, "w", encoding='utf-8') as f:
+        f.write(content)
+
+    console.print(f"[green]+[/green] Created {main_path}")
+
+
+def create_init_py(target_dir: Path) -> None:
+    """Create __init__.py in the target directory if it doesn't exist.
+
+    Args:
+        target_dir: Target directory where __init__.py should be created
+    """
+    init_path = target_dir / "__init__.py"
+
+    if init_path.exists():
+        console.print(f"[yellow]![/yellow]  {init_path} already exists, skipping...")
+        return
+
+    with open(init_path, "w", encoding="utf-8") as f:
+        f.write("# Init file for the package\n")
+
+    console.print(f"[green]+[/green] Created {init_path}")
+
+
+def create_gui_structure(target_dir: Path) -> None:
+    """Create GUI automation folder structure with template files.
+    
+    Args:
+        target_dir: Target directory where gui folder should be created
+    """
+    console.print("\n[dim]Creating GUI automation structure...[/dim]")
+
+    gui_path = target_dir / "gui"
+    gui_path.mkdir(parents=True, exist_ok=True)
+
+    # Create targets subfolder
+    targets_path = gui_path / "targets"
+    targets_path.mkdir(exist_ok=True)
+
+    # Template files to create
+    template_files = [
+        "states.py.template",
+        "transitions.py.template",
+        "rollbacks.py.template",
+        "exceptions.py.template",
+    ]
+
+    for template_name in template_files:
+        output_name = template_name.replace(".template", "")
+        output_path = gui_path / output_name
+
+        if output_path.exists():
+            console.print(
+                f"[yellow]![/yellow]  {output_path} already exists, skipping..."
+            )
+            continue
+
+        content = read_template(template_name)
+
+        with open(output_path, "w", encoding='utf-8') as f:
+            f.write(content)
+
+    console.print(f"[green]+[/green] Created GUI automation structure in {gui_path}")
+
+
+def init_project(
+    target_dir: Optional[Path] = None,
+    with_gui: Optional[bool] = None
+) -> None:
+    """Initialize a new Clerk custom code project.
+    
+    Args:
+        target_dir: Target directory for the project (defaults to ./src)
+        with_gui: Whether to include GUI automation functionality (prompts if None)
+    """
+    if target_dir is None:
+        target_dir = Path.cwd() / "src"
+
+    # Ensure target directory exists
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    # Welcome message
+    console.print(Panel(
+        "[bold cyan]Clerk Custom Code Setup[/bold cyan]\n\n"
+        "This will set up your Clerk custom code project.",
+        style="blue"
+    ))
+
+    # Prompt for GUI automation if not specified
+    if with_gui is None:
+        console.print()
+        with_gui = Confirm.ask(
+            "[cyan]Enable GUI automation functionality?[/cyan]",
+            default=False
+        )
+
+    gui_status = "ENABLED" if with_gui else "DISABLED"
+    console.print(f"\n[dim]GUI Automation: {gui_status}[/dim]")
+
+    # Create .env file and get environment variables
+    env_vars = create_env_file(gui_automation=with_gui)
+
+    if not env_vars:
+        console.print("\n[red]✗ Failed to configure environment[/red]")
+        sys.exit(1)
+
+    # Update os.environ with the new values for fetch_schema to use
+    for key, value in env_vars.items():
+        os.environ[key] = value
+
+    console.print("\n[bold]" + "=" * 60 + "[/bold]")
+    console.print("[bold cyan]Creating Project Structure[/bold cyan]")
+    console.print("[bold]" + "=" * 60 + "[/bold]")
+
+    # Create main.py
+    create_main_py(target_dir, with_gui=with_gui)
+
+    # Create __init__.py
+    create_init_py(target_dir)
+
+    # Create GUI automation structure if requested
+    if with_gui:
+        create_gui_structure(target_dir)
+
+    console.print("\n[bold]" + "=" * 60 + "[/bold]")
+    console.print("[bold cyan]Fetching Schema from Clerk[/bold cyan]")
+    console.print("[bold]" + "=" * 60 + "[/bold]")
+
+    # Fetch schema automatically
+    try:
+        from clerk.development.schema.fetch_schema import main_with_args as fetch_schema_main
+        project_id = env_vars.get("PROJECT_ID")
+        if project_id:
+            fetch_schema_main(project_id, Path.cwd())
+        else:
+            console.print("[yellow]⚠[/yellow]  PROJECT_ID not found, skipping schema fetch")
+    except Exception as e:
+        console.print(f"[yellow]⚠[/yellow]  Schema fetch failed: {e}")
+        console.print("[dim]You can run 'clerk fetch-schema' later to fetch the schema[/dim]")
+
+    # Final success message
+    console.print("\n[bold]" + "=" * 60 + "[/bold]")
+    console.print("[bold green]Setup Completed Successfully![/bold green]")
+    console.print("[bold]" + "=" * 60 + "[/bold]")
+
+    success_items = [
+        "Environment configured (.env created)",
+        "Schema fetched from Clerk",
+    ]
+
+    if with_gui:
+        success_items.insert(0, "GUI automation structure created")
+        success_items.insert(1, "main.py configured with ScreenPilot")
+    else:
+        success_items.insert(0, "Basic main.py created")
+
+    for item in success_items:
+        console.print(f"[green]✓[/green] {item}")
+
+    console.print("\n[cyan]Next steps:[/cyan]")
+    console.print("   1. Start developing your custom code in src/main.py")
+    console.print("   2. When ready, check README.md for deployment guidance.")
+    console.print("[bold]" + "=" * 60 + "[/bold]")
+
+
+def main_with_args(gui_automation: Optional[bool] = None, target_dir: Optional[str] = None):
+    """Main entry point for CLI usage.
+    
+    Args:
+        gui_automation: Whether to include GUI automation functionality (prompts if None)
+        target_dir: Target directory for the project
+    """
+    try:
+        target_path = Path(target_dir) if target_dir else None
+        init_project(target_dir=target_path, with_gui=gui_automation)
+    except KeyboardInterrupt:
+        console.print("\n\n[yellow]Setup cancelled by user[/yellow]")
+        sys.exit(1)
+    except Exception as e:
+        console.print(f"\n[red]✗ Error during project initialization: {e}[/red]")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    # For standalone testing
+    import argparse
+    
+    parser = argparse.ArgumentParser(description="Initialize Clerk custom code project")
+    parser.add_argument(
+        "--gui-automation",
+        action="store_true",
+        help="Include GUI automation functionality"
+    )
+    parser.add_argument(
+        "--target-dir",
+        type=str,
+        default=None,
+        help="Target directory for the project (default: ./src)"
+    )
+    
+    args = parser.parse_args()
+    main_with_args(gui_automation=args.gui_automation, target_dir=args.target_dir)

clerk/development/schema/fetch_schema.py

@@ -0,0 +1,339 @@
+from pathlib import Path
+from typing import Any, List, Optional, Dict, Tuple
+from enum import Enum
+from datetime import datetime
+from pydantic import BaseModel, Field
+import requests
+
+from rich.console import Console
+
+from clerk.client import Clerk
+from clerk.exceptions.exceptions import ApplicationException
+
+console = Console()
+
+
+class VariableTypes(str, Enum):
+    STRING = "string"
+    NUMBER = "number"
+    DATE = "date"
+    BOOLEAN = "boolean"
+    DATETIME = "datetime"
+    TIME = "time"
+    OBJECT = "object"
+    ENUM = "enum"
+
+
+class VariableData(BaseModel):
+    id: str
+    name: str
+    display_name: str
+    tags: List[str] = []
+    units: Optional[str] = None
+    description: Optional[str] = None
+    is_array: bool
+    parent_id: Optional[str] = None
+    type: VariableTypes
+    position_index: int
+    additional_properties: Optional[bool] = None
+    default: Any | None = None
+    enum_options: List[str] = Field(default_factory=list)
+
+
+def fetch_schema(project_id: str) -> List[VariableData]:
+    """
+    Fetch schema from Clerk backend for a given project.
+
+    Args:
+        project_id: The project ID to fetch schema for
+
+    Returns:
+        List of VariableData objects
+
+    Raises:
+        ApplicationException: If the API key is invalid (401)
+        ApplicationException: If the project_id is invalid or not found (404)
+        ApplicationException: If there's another API error
+    """
+    try:
+        client = Clerk()
+    except ValueError as e:
+        raise ApplicationException(
+            message=f"Invalid or missing API key. Please set CLERK_API_KEY environment variable or provide it explicitly. Error: {str(e)}"
+        )
+
+    endpoint = "/schema"
+    params = {"project_id": project_id}
+
+    try:
+        res = client.get_request(endpoint=endpoint, params=params)
+        return [VariableData.model_validate(item) for item in res.data]
+    except requests.exceptions.HTTPError as e:
+        if e.response is not None:
+            status_code = e.response.status_code
+            if status_code == 401:
+                raise ApplicationException(
+                    message="Invalid API key. Please check your CLERK_API_KEY."
+                )
+            elif status_code == 404:
+                raise ApplicationException(
+                    message=f"Project not found. The project_id '{project_id}' does not exist or you don't have access to it."
+                )
+            elif status_code == 403:
+                raise ApplicationException(
+                    message=f"Access forbidden. You don't have permission to access project '{project_id}'."
+                )
+            else:
+                raise ApplicationException(
+                    message=f"API error (HTTP {status_code}): {e.response.text}"
+                )
+        else:
+            raise ApplicationException(message=f"HTTP error occurred: {str(e)}")
+    except requests.exceptions.RequestException as e:
+        raise ApplicationException(
+            message=f"Network error while fetching schema: {str(e)}"
+        )
+
+
+def _python_type_from_variable(
+    var: VariableData, nested_models: Dict[str, str]
+) -> Tuple[str, bool]:
+    """Convert VariableData type to Python type string
+
+    Returns:
+        tuple of (type_string, is_leaf_value)
+        is_leaf_value is True for primitive types, False for lists and BaseModels
+    """
+    type_map = {
+        VariableTypes.STRING: "str",
+        VariableTypes.NUMBER: "float",
+        VariableTypes.DATE: "date",
+        VariableTypes.DATETIME: "datetime",
+        VariableTypes.TIME: "time",
+        VariableTypes.BOOLEAN: "bool",
+        VariableTypes.ENUM: "str",  # Will be refined with Literal if enum_options exist
+    }
+
+    is_leaf = True  # Assume leaf unless it's a list or object
+
+    if var.type == VariableTypes.OBJECT:
+        # Use the nested model class name
+        base_type = nested_models.get(var.id, "Dict[str, Any]")
+        is_leaf = False  # Objects are not leaf values
+    elif var.type == VariableTypes.ENUM and var.enum_options:
+        # Create Literal type for enum
+        options = ", ".join([f'"{opt}"' for opt in var.enum_options])
+        base_type = f"Literal[{options}]"
+    else:
+        base_type = type_map.get(var.type, "Any")
+
+    # Handle arrays
+    if var.is_array:
+        is_leaf = False  # Lists are not leaf values
+        return f"List[{base_type}]", is_leaf
+
+    return base_type, is_leaf
+
+
+def generate_models_from_schema(
+    variables: List[VariableData], output_file: Optional[Path] = None
+) -> str:
+    """
+    Generate Pydantic BaseModel classes from schema variables.
+    
+    Args:
+        variables: List of VariableData objects
+        output_file: Optional path to write the generated code
+        
+    Returns:
+        Generated Python code as string
+    """
+    # Group variables by parent_id
+    root_vars: List[VariableData] = []
+    nested_vars: Dict[str, List[VariableData]] = {}
+
+    for var in sorted(variables, key=lambda v: v.position_index):
+        if var.parent_id is None:
+            root_vars.append(var)
+        else:
+            if var.parent_id not in nested_vars:
+                nested_vars[var.parent_id] = []
+            nested_vars[var.parent_id].append(var)
+
+    # Map variable IDs to their generated class names using name field
+    nested_models: Dict[str, str] = {}
+    var_id_to_data: Dict[str, VariableData] = {var.id: var for var in variables}
+
+    for parent_id in nested_vars.keys():
+        parent_var = var_id_to_data.get(parent_id)
+        if parent_var and parent_var.name:
+            # Use name field and convert snake_case to PascalCase
+            class_name = "".join(
+                word.capitalize() for word in parent_var.name.split("_")
+            )
+        else:
+            # Fallback to parent_id
+            class_name = "".join(word.capitalize() for word in parent_id.split("_"))
+        nested_models[parent_id] = class_name
+
+    code_lines: List[str] = []
+
+    # Autogenerated code comment with sync timestamp
+    sync_timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    code_lines.append(
+        f"# Autogenerated by the fetch_schema tool - do not edit manually."
+    )
+    code_lines.append(f"# Last fetched: {sync_timestamp}\n")
+
+    # Generate imports
+    imports = [
+        "from typing import Any, List, Optional, Dict",
+        "from datetime import date, datetime, time",
+        "from pydantic import BaseModel, Field",
+    ]
+
+    # Check if we need Literal
+    has_enums = any(var.type == VariableTypes.ENUM and var.enum_options for var in variables)
+    if has_enums:
+        imports[0] = "from typing import Any, List, Optional, Dict, Literal"
+
+    code_lines.extend(imports)
+    code_lines.append("")
+
+    # Generate nested models first (bottom-up)
+    generated_classes = set()
+
+    def generate_class(var_id: str, vars_list: List[VariableData], class_name: str):
+        if class_name in generated_classes:
+            return
+
+        # First generate any nested children
+        for var in vars_list:
+            if var.type == VariableTypes.OBJECT and var.id in nested_vars:
+                child_class_name = nested_models[var.id]
+                generate_class(var.id, nested_vars[var.id], child_class_name)
+
+        # Generate this class
+        code_lines.append(f"class {class_name}(BaseModel):")
+
+        if not vars_list:
+            code_lines.append("    pass")
+        else:
+            for var in sorted(vars_list, key=lambda v: v.position_index):
+                field_name = var.name
+                python_type, is_leaf = _python_type_from_variable(var, nested_models)
+
+                # Make leaf values Optional and default to None
+                if is_leaf:
+                    python_type = f"Optional[{python_type}]"
+
+                # Build field definition
+                field_parts = []
+                if var.description:
+                    # Escape double quotes and newlines in description
+                    escaped_desc = (
+                        var.description.replace('"', '\\"')
+                        .replace("\n", "\\n")
+                        .replace("\r", "")
+                    )
+                    field_parts.append(f'description="{escaped_desc}"')
+
+                # Set default to None for leaf values, or use existing default
+                if is_leaf:
+                    if var.default is not None:
+                        field_parts.append(f"default={repr(var.default)}")
+                    else:
+                        field_parts.append("default=None")
+                elif var.default is not None:
+                    field_parts.append(f"default={repr(var.default)}")
+
+                if field_parts:
+                    field_def = f"Field({', '.join(field_parts)})"
+                    code_lines.append(f"    {field_name}: {python_type} = {field_def}")
+                else:
+                    code_lines.append(f"    {field_name}: {python_type}")
+
+        code_lines.append("")
+        generated_classes.add(class_name)
+
+    # Generate all nested models
+    for var_id, vars_list in nested_vars.items():
+        class_name = nested_models[var_id]
+        generate_class(var_id, vars_list, class_name)
+
+    # Generate root model
+    code_lines.append("class StructuredData(BaseModel):")
+    if not root_vars:
+        code_lines.append("    pass")
+    else:
+        for var in sorted(root_vars, key=lambda v: v.position_index):
+            field_name = var.name
+            python_type, is_leaf = _python_type_from_variable(var, nested_models)
+
+            # Make leaf values Optional and default to None
+            if is_leaf:
+                python_type = f"Optional[{python_type}]"
+
+            # Build field definition
+            field_parts = []
+            if var.description:
+                # Escape double quotes and newlines in description
+                escaped_desc = (
+                    var.description.replace('"', '\\"')
+                    .replace("\n", "\\n")
+                    .replace("\r", "")
+                )
+                field_parts.append(f'description="{escaped_desc}"')
+
+            # Set default to None for leaf values, or use existing default
+            if is_leaf:
+                if var.default is not None:
+                    field_parts.append(f"default={repr(var.default)}")
+                else:
+                    field_parts.append("default=None")
+            elif var.default is not None:
+                field_parts.append(f"default={repr(var.default)}")
+
+            if field_parts:
+                field_def = f"Field({', '.join(field_parts)})"
+                code_lines.append(f"    {field_name}: {python_type} = {field_def}")
+            else:
+                code_lines.append(f"    {field_name}: {python_type}")
+
+    generated_code = "\n".join(code_lines)
+
+    # Write to file if specified
+    if output_file:
+        output_file.parent.mkdir(parents=True, exist_ok=True)
+        output_file.write_text(generated_code)
+
+    return generated_code
+
+
+def main_with_args(project_id: str, project_root: Path | None = None):
+    """Main logic that can be called from CLI or programmatically"""
+    try:
+        with console.status(
+            f"[dim]Fetching schema for project: {project_id}...", spinner="dots"
+        ):
+            variables = fetch_schema(project_id)
+
+        console.print(f"[green]+[/green] Found {len(variables)} variables")
+
+        # Always save to schema.py in project root
+        if project_root is None:
+            project_root = Path.cwd()
+        output_file = project_root / "src" / "schema.py"
+
+        with console.status("[dim]Generating Pydantic models...", spinner="dots"):
+            generate_models_from_schema(variables, output_file)
+
+        console.print(
+            f"[green]+[/green] Schema generated and written to: {output_file}"
+        )
+    except ApplicationException as e:
+        console.print(f"[red]x Error: {e.message}[/red]")
+        raise
+    except Exception as e:
+        console.print(f"[red]x Unexpected error: {str(e)}[/red]")
+        raise

clerk/development/templates/exceptions.py.template

@@ -0,0 +1,16 @@
+"""
+# Instructions
+
+Define custom exceptions for ScreenPilot here.
+- Any exception will be caught by ScreenPilot's main loop, activating rollback mode and course correction.
+- Raise subclasses of BusinessException to indicate business process conditions that should not trigger rollbacks.
+
+# Example
+```python
+class CustomError(BusinessException):
+    pass
+```
+
+"""
+
+from clerk.gui_automation.ui_state_machine.exceptions import BusinessException

clerk/development/templates/main_basic.py.template

@@ -0,0 +1,22 @@
+from clerk.decorator import clerk_code
+from clerk.decorator.models import ClerkCodePayload
+from clerk.utils import logger
+
+from src.schema import StructuredData
+
+@clerk_code()
+def main(payload: ClerkCodePayload):
+    """Main program"""
+
+    data = StructuredData.model_validate(payload.structured_data)
+    logger.info("Custom code started")
+    
+    # TODO: Implement your custom code logic here
+    
+    logger.info("Custom code completed")
+    payload.structured_data = data.model_dump()
+    return payload
+
+
+if __name__ == "__main__":
+    main()