supervaizer 0.9.7__py3-none-any.whl → 0.10.0__py3-none-any.whl

supervaizer/cli.py

@@ -4,6 +4,7 @@
 # If a copy of the MPL was not distributed with this file, you can obtain one at
 # https://mozilla.org/MPL/2.0/.
 
+import asyncio
 import os
 import shutil
 import signal
@@ -12,16 +13,94 @@ import sys
 from typing import Any
 from pathlib import Path
 from typing import Optional
+from supervaizer.deploy.cli import deploy_app
 
 import typer
 from rich.console import Console
+from rich.prompt import Confirm
 
 from supervaizer.__version__ import VERSION
+from supervaizer.utils.version_check import check_is_latest_version
+
+console = Console()
+
+# Cache version status to avoid multiple checks
+_version_status: tuple[bool, str | None] | None = None
+
+
+def _check_version() -> tuple[bool, str | None]:
+    """Check version status, caching the result."""
+    global _version_status
+    if _version_status is None:
+        try:
+            _version_status = asyncio.run(check_is_latest_version())
+        except Exception:
+            # On error, assume we're on latest to avoid false positives
+            _version_status = (True, None)
+    return _version_status
+
+
+def _display_version_info() -> None:
+    """Display version information."""
+    is_latest, latest_version = _check_version()
+    console.print(f"Supervaizer v{VERSION}")
+    if latest_version:
+        if is_latest:
+            console.print(f"[green]✓[/] Up to date (latest: v{latest_version})")
+        else:
+            console.print(f"[yellow]⚠[/] Latest available: v{latest_version}")
+            console.print("Update with: [bold]pip install --upgrade supervaizer[/]")
+    else:
+        console.print("(Unable to check for latest version)")
+
+
+def _display_update_warning() -> None:
+    """Display update warning for commands."""
+    is_latest, latest_version = _check_version()
+    if latest_version and not is_latest:
+        console.print(
+            f"\n[bold yellow]⚠ Warning:[/] You are running Supervaizer v{VERSION}, "
+            f"but v{latest_version} is available.\n"
+            f"Update with: [bold]pip install --upgrade supervaizer[/]\n",
+            style="yellow",
+        )
+
 
 app = typer.Typer(
-    help=f"Supervaizer Controller CLI v{VERSION} - Documentation @ https://docs.supervaize.com"
+    help=f"Supervaizer Controller CLI v{VERSION} - Documentation @ https://doc.supervaize.com/docs/category/supervaizer-controller"
 )
-console = Console()
+
+
+@app.callback(invoke_without_command=True)
+def main_callback(
+    ctx: typer.Context,
+    version: bool = typer.Option(
+        False, "--version", "-v", help="Show version information and exit"
+    ),
+) -> None:
+    """CLI callback that runs before any command."""
+    # Handle --version option
+    if version:
+        _display_version_info()
+        raise typer.Exit()
+
+    # Show version status in help or as warning for commands
+    if ctx.invoked_subcommand is None:
+        # For help display, show version status
+        _display_version_info()
+    else:
+        # For actual commands, show warning if not latest
+        _display_update_warning()
+
+
+# Add deploy subcommand
+app.add_typer(
+    deploy_app, name="deploy", help="Deploy Supervaizer agents to cloud platforms"
+)
+
+# Create scaffold subcommand group
+scaffold_app = typer.Typer(help="Scaffold commands for creating project files")
+app.add_typer(scaffold_app, name="scaffold", invoke_without_command=True)
 
 
 @app.command()
@@ -98,8 +177,45 @@ def start(
     process.wait()
 
 
-@app.command()
+def _create_instructions_file(
+    output_dir: Path, force: bool = False, silent: bool = False
+) -> Path:
+    """Create supervaize_instructions.html file in the given directory.
+
+    Args:
+        output_dir: Directory where to create the instructions file
+        force: If True, overwrite existing file
+        silent: If True, don't show warnings if file already exists (just skip)
+    """
+    instructions_path = output_dir / "supervaize_instructions.html"
+
+    # Check if file already exists
+    if instructions_path.exists() and not force:
+        if not silent:
+            console.print(
+                f"[bold yellow]Warning:[/] {instructions_path} already exists"
+            )
+            console.print(
+                "Use [bold]--force[/] to overwrite it, or run [bold]supervaizer refresh-instructions[/]"
+            )
+        return instructions_path
+
+    # Get the path to the admin templates directory
+    admin_templates_dir = Path(__file__).parent / "admin" / "templates"
+    template_file = admin_templates_dir / "supervaize_instructions.html"
+
+    if not template_file.exists():
+        console.print("[bold red]Error:[/] Template file not found")
+        sys.exit(1)
+
+    # Copy the template file
+    shutil.copy(template_file, instructions_path)
+    return instructions_path
+
+
+@scaffold_app.callback(invoke_without_command=True)
 def scaffold(
+    ctx: typer.Context,
     output_path: str = typer.Option(
         os.environ.get("SUPERVAIZER_OUTPUT_PATH", "supervaizer_control.py"),
         help="Path to save the script",
@@ -109,7 +225,10 @@ def scaffold(
         help="Overwrite existing file",
     ),
 ) -> None:
-    """Create a draft supervaizer_control.py script."""
+    """Create a draft supervaizer_control.py script and supervaize_instructions.html."""
+    # Only run if no subcommand was invoked
+    if ctx.invoked_subcommand is not None:
+        return
     # Check if file already exists
     if os.path.exists(output_path) and not force:
         console.print(f"[bold red]Error:[/] {output_path} already exists")
@@ -118,7 +237,7 @@ def scaffold(
 
     # Get the path to the examples directory
     examples_dir = Path(__file__).parent / "examples"
-    example_file = examples_dir / "controller-template.py"
+    example_file = examples_dir / "controller_template.py"
 
     if not example_file.exists():
         console.print("[bold red]Error:[/] Example file not found")
@@ -129,18 +248,139 @@ def scaffold(
     console.print(
         f"[bold green]Success:[/] Created an example file at [bold blue]{output_path}[/]"
     )
+
+    # Create instructions file in the same directory (silently if it already exists)
+    output_dir = Path(output_path).parent
+    instructions_path = output_dir / "supervaize_instructions.html"
+    instructions_existed = instructions_path.exists()
+    _create_instructions_file(output_dir, force=force, silent=True)
+    # Only show success message if we actually created the file (didn't exist before or force was used)
+    if not instructions_existed or force:
+        console.print(
+            f"[bold green]Success:[/] Created instructions template at [bold blue]{instructions_path}[/]"
+        )
+
     console.print(
         "1. Copy this file to [bold]supervaizer_control.py[/] and edit it to configure your agent(s)"
     )
     console.print(
-        "2. (Optional) Get your API from [bold]supervaizer.com and setup your environment variables"
+        "2. Customize [bold]supervaize_instructions.html[/] to match your agent's documentation"
     )
     console.print(
-        "3. Run [bold]supervaizer start[/] to start the supervaizer controller"
+        "3. (Optional) Get your API from [bold]supervaizer.com and setup your environment variables"
     )
-    console.print("4. Open [bold]http://localhost:8000/docs[/] to explore the API")
+    console.print(
+        "4. Run [bold]supervaizer start[/] to start the supervaizer controller"
+    )
+    console.print("5. Open [bold]http://localhost:8000/docs[/] to explore the API")
     sys.exit(0)
 
 
+@scaffold_app.command(name="instructions")
+def scaffold_instructions(
+    control_file: Optional[str] = typer.Option(
+        None,
+        help="Path to supervaizer_control.py (default: auto-detect)",
+    ),
+    output_path: Optional[str] = typer.Option(
+        None,
+        help="Path to save supervaize_instructions.html (default: same directory as control file)",
+    ),
+    force: bool = typer.Option(
+        False,
+        help="Overwrite existing file",
+    ),
+) -> None:
+    """Create supervaize_instructions.html file."""
+    # Determine control file path
+    if control_file is None:
+        control_file = (
+            os.environ.get("SUPERVAIZER_SCRIPT_PATH") or "supervaizer_control.py"
+        )
+
+    control_path = Path(control_file)
+
+    # Determine output directory
+    if output_path is None:
+        output_dir = control_path.parent
+        instructions_path = output_dir / "supervaize_instructions.html"
+    else:
+        instructions_path = Path(output_path)
+        output_dir = instructions_path.parent
+
+    # Check if control file exists (informational)
+    if not control_path.exists():
+        console.print(f"[bold yellow]Warning:[/] Control file {control_file} not found")
+        console.print("Creating instructions file anyway...")
+
+    # Create instructions file
+    _create_instructions_file(output_dir, force=force)
+    console.print(
+        f"[bold green]Success:[/] Created instructions template at [bold blue]{instructions_path}[/]"
+    )
+    console.print(
+        "Customize this file to match your agent's documentation and instructions."
+    )
+
+
+@scaffold_app.command(name="refresh-instructions")
+def refresh_instructions(
+    control_file: Optional[str] = typer.Option(
+        None,
+        help="Path to supervaizer_control.py (default: auto-detect)",
+    ),
+    output_path: Optional[str] = typer.Option(
+        None,
+        help="Path to supervaize_instructions.html (default: same directory as control file)",
+    ),
+    force: bool = typer.Option(
+        False,
+        help="Skip confirmation prompt",
+    ),
+) -> None:
+    """Refresh/update supervaize_instructions.html file."""
+    # Determine control file path
+    if control_file is None:
+        control_file = (
+            os.environ.get("SUPERVAIZER_SCRIPT_PATH") or "supervaizer_control.py"
+        )
+
+    control_path = Path(control_file)
+
+    # Determine output path
+    if output_path is None:
+        output_dir = control_path.parent
+        instructions_path = output_dir / "supervaize_instructions.html"
+    else:
+        instructions_path = Path(output_path)
+
+    # Check if instructions file exists
+    if instructions_path.exists():
+        if not force:
+            console.print(
+                f"[bold yellow]Warning:[/] {instructions_path} already exists"
+            )
+            if not Confirm.ask(
+                "Delete existing file and create a fresh template?",
+                default=False,
+            ):
+                console.print("[bold]Cancelled.[/]")
+                sys.exit(0)
+
+        # Delete existing file
+        instructions_path.unlink()
+        console.print(f"[bold]Deleted[/] existing {instructions_path}")
+
+    # Create new instructions file
+    output_dir = instructions_path.parent
+    _create_instructions_file(output_dir, force=True)
+    console.print(
+        f"[bold green]Success:[/] Created fresh instructions template at [bold blue]{instructions_path}[/]"
+    )
+    console.print(
+        "Customize this file to match your agent's documentation and instructions."
+    )
+
+
 if __name__ == "__main__":
     app()

supervaizer/common.py

@@ -28,19 +28,44 @@ class SvBaseModel(BaseModel):
     Base model for all Supervaize models.
     """
 
+    @staticmethod
+    def serialize_value(value: Any) -> Any:
+        """Recursively serialize values, converting type objects and datetimes to strings."""
+        from datetime import datetime
+
+        if isinstance(value, type):
+            # Convert type objects to their string name
+            return value.__name__
+        elif isinstance(value, datetime):
+            # Convert datetime to ISO format string
+            return value.isoformat()
+        elif isinstance(value, dict):
+            # Recursively process dictionaries
+            return {k: SvBaseModel.serialize_value(v) for k, v in value.items()}
+        elif isinstance(value, (list, tuple)):
+            # Recursively process lists and tuples
+            return [SvBaseModel.serialize_value(item) for item in value]
+        else:
+            # Return value as-is for other types
+            return value
+
     @property
     def to_dict(self) -> Dict[str, Any]:
         """
         Convert the model to a dictionary.
 
-        Note: Using mode="json" to handle datetime serialization.
+        Note: Handles datetime serialization and type objects by converting them
+        to their string representation.
         Tested in tests/test_common.test_sv_base_model_json_conversion
         """
-        return self.model_dump(mode="json")
+        # Use mode="python" to avoid Pydantic's JSON serialization errors with type objects
+        # Then post-process to handle type objects and datetimes
+        data = self.model_dump(mode="python")
+        return self.serialize_value(data)
 
     @property
     def to_json(self) -> str:
-        return self.model_dump_json()
+        return json.dumps(self.to_dict)
 
 
 class ApiResult:
@@ -251,8 +276,24 @@ def decrypt_value(encrypted_value: str, private_key: rsa.RSAPrivateKey) -> str:
         ValueError: If decryption fails
     """
 
+    # Basic validation
+    if not encrypted_value:
+        raise ValueError("Empty encrypted value")
+
+    # Clean the string
+    encrypted_value = encrypted_value.strip()
+
     # Decode base64
-    combined = base64.b64decode(encrypted_value)
+    try:
+        combined = base64.b64decode(encrypted_value)
+    except Exception as e:
+        raise ValueError(f"Base64 decode failed: {str(e)}")
+
+    # Validate combined data structure
+    if len(combined) < 272:
+        raise ValueError(
+            f"Invalid encrypted data structure: too short ({len(combined)} bytes)"
+        )
 
     # Extract components - first 256 bytes are RSA encrypted key
     encrypted_key = combined[:256]  # RSA-2048 output is 256 bytes

supervaizer/deploy/__init__.py

@@ -0,0 +1,16 @@
+# Copyright (c) 2024-2025 Alain Prasquier - Supervaize.com. All rights reserved.
+#
+# This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+# If a copy of the MPL was not distributed with this file, you can obtain one at
+# https://mozilla.org/MPL/2.0/.
+
+"""
+Supervaizer Deployment CLI
+
+This module provides automated deployment capabilities for Supervaizer agents
+to cloud platforms including GCP Cloud Run, AWS App Runner, and DigitalOcean App Platform.
+"""
+
+from supervaizer.__version__ import VERSION
+
+__version__ = VERSION

supervaizer/deploy/cli.py

@@ -0,0 +1,296 @@
+# Copyright (c) 2024-2025 Alain Prasquier - Supervaize.com. All rights reserved.
+#
+# This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+# If a copy of the MPL was not distributed with this file, you can obtain one at
+# https://mozilla.org/MPL/2.0/.
+
+"""
+Deployment CLI Commands
+
+This module contains the main CLI commands for the deploy subcommand.
+"""
+
+import typer
+from pathlib import Path
+from rich.console import Console
+
+from supervaizer.deploy.commands.plan import plan_deployment
+from supervaizer.deploy.commands.up import deploy_up
+from supervaizer.deploy.commands.down import deploy_down
+from supervaizer.deploy.commands.status import deploy_status
+from supervaizer.deploy.commands.local import local_docker
+from supervaizer.deploy.commands.clean import (
+    clean_deployment,
+    clean_docker_artifacts,
+    clean_state_only,
+)
+
+console = Console()
+
+# Create the deploy subcommand
+deploy_app = typer.Typer(
+    name="deploy",
+    help="Deploy Supervaizer agents to cloud platforms. Python dependencies must be managed in pyproject.toml file.",
+    no_args_is_help=True,
+)
+
+# Common parameters
+platform_option = typer.Option(
+    None,
+    "--platform",
+    "-p",
+    help="Target platform (cloud-run|aws-app-runner|do-app-platform)",
+)
+name_option = typer.Option(
+    ...,
+    "--name",
+    "-n",
+    help="Service name. Required for local command.",
+    prompt="Service name (e.g. my-service)",
+)
+env_option = typer.Option("dev", "--env", "-e", help="Environment (dev|staging|prod)")
+region_option = typer.Option(None, "--region", "-r", help="Provider region")
+project_id_option = typer.Option(
+    None, "--project-id", help="GCP project / AWS account / DO project"
+)
+verbose_option = typer.Option(False, "--verbose", "-v", help="Show detailed output")
+
+# Additional parameters for specific commands
+image_option = typer.Option(None, "--image", help="Container image (registry/repo:tag)")
+port_option = typer.Option(8000, "--port", help="Application port")
+generate_api_key_option = typer.Option(
+    False, "--generate-api-key", help="Generate secure API key"
+)
+generate_rsa_option = typer.Option(
+    False, "--generate-rsa", help="Generate RSA private key"
+)
+yes_option = typer.Option(False, "--yes", "-y", help="Non-interactive mode")
+no_rollback_option = typer.Option(False, "--no-rollback", help="Keep failed revision")
+timeout_option = typer.Option(300, "--timeout", help="Deployment timeout in seconds")
+docker_files_only_option = typer.Option(
+    False, "--docker-files-only", help="Only generate Docker files without running them"
+)
+
+controller_file_option = typer.Option(
+    "supervaizer_control.py",
+    "--controller-file",
+    help="Controller file name (default: supervaizer_control.py)",
+)
+
+# Clean command options
+force_option = typer.Option(False, "--force", "-f", help="Skip confirmation prompts")
+verbose_option_clean = typer.Option(
+    False, "--verbose", "-v", help="Show detailed output"
+)
+
+
+def _check_pyproject_toml() -> Path:
+    """Check if pyproject.toml exists in current directory or parent directories."""
+    current_dir = Path.cwd()
+
+    # Check current directory first
+    pyproject_path = current_dir / "pyproject.toml"
+    if pyproject_path.exists():
+        return current_dir
+
+    # Check parent directories up to 3 levels
+    for _ in range(3):
+        current_dir = current_dir.parent
+        pyproject_path = current_dir / "pyproject.toml"
+        if pyproject_path.exists():
+            return current_dir
+
+    # If not found, show help and exit
+    _show_pyproject_toml_help()
+    raise typer.Exit(1)
+
+
+def _show_pyproject_toml_help() -> None:
+    """Show help message when pyproject.toml is not found."""
+    console.print("[bold red]Error:[/] pyproject.toml file not found")
+    console.print(
+        "The supervaizer deploy command must be run from a directory containing pyproject.toml"
+    )
+    console.print("or from a subdirectory of such a directory.")
+    console.print("\n[bold]Current directory:[/] " + str(Path.cwd()))
+    console.print("\n[bold]Please ensure:[/]")
+    console.print("  • You are in the correct project directory")
+    console.print("  • The pyproject.toml file exists in the project root")
+    console.print("  • Python dependencies are properly defined in pyproject.toml")
+    console.print("\n[bold]Available deploy commands:[/]")
+    console.print(
+        "  • [bold]supervaizer deploy local[/] - Test deployment locally using Docker Compose"
+    )
+    console.print("  • [bold]supervaizer deploy up[/] - Deploy or update the service")
+    console.print(
+        "  • [bold]supervaizer deploy down[/] - Destroy the service and cleanup resources"
+    )
+    console.print(
+        "  • [bold]supervaizer deploy status[/] - Show deployment status and health information"
+    )
+    console.print(
+        "  • [bold]supervaizer deploy plan[/] - Plan deployment changes without applying them"
+    )
+    console.print(
+        "  • [bold]supervaizer deploy clean[/] - Clean up deployment artifacts and generated files"
+    )
+    console.print(
+        "\nUse [bold]supervaizer deploy <command> --help[/] for more information about each command."
+    )
+
+
+@deploy_app.callback()
+def deploy_callback() -> None:
+    """Deploy Supervaizer agents to cloud platforms."""
+    # This callback is called when no subcommand is provided
+    # The no_args_is_help=True will automatically show help
+    pass
+
+
+def _check_platform_required(platform: str, command_name: str) -> None:
+    """Check if platform is provided and show helpful error if not."""
+    if platform is None:
+        console.print("[bold red]Error:[/] --platform is required")
+        console.print(
+            f"Use [bold]supervaizer deploy {command_name} --help[/] for more information"
+        )
+        raise typer.Exit(1)
+
+
+@deploy_app.command(no_args_is_help=True)
+def plan(
+    platform: str = platform_option,
+    name: str = name_option,
+    env: str = env_option,
+    region: str = region_option,
+    project_id: str = project_id_option,
+    verbose: bool = verbose_option,
+) -> None:
+    """Plan deployment changes without applying them."""
+    _check_platform_required(platform, "plan")
+    source_dir = _check_pyproject_toml()
+    plan_deployment(platform, name, env, region, project_id, verbose, source_dir)
+
+
+@deploy_app.command(no_args_is_help=True)
+def up(
+    platform: str = platform_option,
+    name: str = name_option,
+    env: str = env_option,
+    region: str = region_option,
+    project_id: str = project_id_option,
+    image: str = image_option,
+    port: int = port_option,
+    generate_api_key: bool = generate_api_key_option,
+    generate_rsa: bool = generate_rsa_option,
+    yes: bool = yes_option,
+    no_rollback: bool = no_rollback_option,
+    timeout: int = timeout_option,
+    verbose: bool = verbose_option,
+) -> None:
+    """Deploy or update the service."""
+    _check_platform_required(platform, "up")
+    source_dir = _check_pyproject_toml()
+    deploy_up(
+        platform,
+        name,
+        env,
+        region,
+        project_id,
+        image,
+        port,
+        generate_api_key,
+        generate_rsa,
+        yes,
+        no_rollback,
+        timeout,
+        verbose,
+        source_dir,
+    )
+
+
+@deploy_app.command(no_args_is_help=True)
+def down(
+    platform: str = platform_option,
+    name: str = name_option,
+    env: str = env_option,
+    region: str = region_option,
+    project_id: str = project_id_option,
+    yes: bool = yes_option,
+    verbose: bool = verbose_option,
+) -> None:
+    """Destroy the service and cleanup resources."""
+    _check_platform_required(platform, "down")
+    source_dir = _check_pyproject_toml()
+    deploy_down(platform, name, env, region, project_id, yes, verbose, source_dir)
+
+
+@deploy_app.command(no_args_is_help=True)
+def status(
+    platform: str = platform_option,
+    name: str = name_option,
+    env: str = env_option,
+    region: str = region_option,
+    project_id: str = project_id_option,
+    verbose: bool = verbose_option,
+) -> None:
+    """Show deployment status and health information."""
+    _check_platform_required(platform, "status")
+    source_dir = _check_pyproject_toml()
+    deploy_status(platform, name, env, region, project_id, verbose, source_dir)
+
+
+@deploy_app.command()
+def local(
+    name: str = name_option,
+    env: str = env_option,
+    port: int = port_option,
+    generate_api_key: bool = generate_api_key_option,
+    generate_rsa: bool = generate_rsa_option,
+    timeout: int = timeout_option,
+    verbose: bool = verbose_option,
+    docker_files_only: bool = docker_files_only_option,
+    controller_file: str = controller_file_option,
+) -> None:
+    """Test deployment locally using Docker Compose. Requires --name."""
+    source_dir = _check_pyproject_toml()
+    local_docker(
+        name,
+        env,
+        port,
+        generate_api_key,
+        generate_rsa,
+        timeout,
+        verbose,
+        docker_files_only,
+        str(source_dir),
+        controller_file,
+    )
+
+
+@deploy_app.command()
+def clean(
+    force: bool = force_option,
+    verbose: bool = verbose_option_clean,
+    docker_only: bool = typer.Option(
+        False, "--docker-only", help="Clean only Docker artifacts"
+    ),
+    state_only: bool = typer.Option(
+        False, "--state-only", help="Clean only deployment state"
+    ),
+) -> None:
+    """Clean up deployment artifacts and generated files."""
+    _check_pyproject_toml()
+
+    if docker_only and state_only:
+        console.print(
+            "[bold red]Error:[/] Cannot use both --docker-only and --state-only"
+        )
+        raise typer.Exit(1)
+
+    if docker_only:
+        clean_docker_artifacts(force=force, verbose=verbose)
+    elif state_only:
+        clean_state_only(force=force, verbose=verbose)
+    else:
+        clean_deployment(force=force, verbose=verbose)