supervaizer 0.10.5__py3-none-any.whl

supervaizer/common.py

@@ -0,0 +1,324 @@
+# 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/.
+
+
+import base64
+import json
+import os
+import traceback
+from typing import Any, Callable, Dict, Optional, TypeVar
+
+import demjson3
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.asymmetric import padding, rsa
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+from loguru import logger
+from pydantic import BaseModel
+
+log = logger.bind(module="supervaize")
+
+T = TypeVar("T")
+
+
+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: Handles datetime serialization and type objects by converting them
+        to their string representation.
+        Tested in tests/test_common.test_sv_base_model_json_conversion
+        """
+        # 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 json.dumps(self.to_dict)
+
+
+class ApiResult:
+    def __init__(self, message: str, detail: Optional[Dict[str, Any]], code: str):
+        self.message = message
+        self.code = str(code)
+        self.detail = detail
+
+    def __str__(self) -> str:
+        return f"{self.json_return}"
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__} ({self.message})"
+
+    @property
+    def dict(self) -> Dict[str, Any]:
+        return {key: value for key, value in self.__dict__.items()}
+
+    @property
+    def json_return(self) -> str:
+        return json.dumps(self.dict)
+
+
+class ApiSuccess(ApiResult):
+    """
+    ApiSuccess is a class that extends ApiResult.
+    It is used to return a success response from the API.
+
+    If the detail is a string, it is decoded as a JSON object: Expects a JSON object with a
+    key "object" and a value of the JSON object to return.
+    If the detail is a dictionary, it is used as is.
+
+
+    Tested in tests/test_common.py
+    """
+
+    def __init__(
+        self, message: str, detail: Optional[Dict[str, Any] | str], code: int = 200
+    ):
+        log_message = "✅ "
+        if isinstance(detail, str):
+            result = demjson3.decode(detail, return_errors=True)
+            detail = {"object": result.object}
+            id = result.object.get("id") or None
+            if id is not None:
+                log_message += f"{message} : {id}"
+            else:
+                log_message += f"{message}"
+        else:
+            id = None
+            detail = detail
+            log_message += f"{message}"
+
+        super().__init__(
+            message=message,
+            detail=detail,
+            code=str(code),
+        )
+        self.id: Optional[str] = id
+        self.log_message = log_message
+        log.debug(f"[API Success] {self.log_message}")
+
+
+class ApiError(ApiResult):
+    """
+    ApiError is a class that extends ApiResult.
+    It can be used to return an error response from the API.
+    Note : not really useful for the moment, as API errors raise exception.
+
+    Tested in tests/test_common.py
+    """
+
+    def __init__(
+        self,
+        message: str,
+        code: str = "",
+        detail: Optional[Dict[str, Any]] = None,
+        exception: Optional[Exception] = None,
+        url: str = "",
+        payload: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(message, detail, code)
+        self.exception = exception
+        self.url = url
+        self.payload = payload
+        self.log_message = f"❌ {message} : {self.exception}"
+
+    @property
+    def dict(self) -> Dict[str, Any]:
+        if self.exception:
+            exception_dict: Dict[str, Any] = {
+                "type": type(self.exception).__name__,
+                "message": str(self.exception),
+                "traceback": traceback.format_exc(),
+                "attributes": {},
+            }
+            if (
+                response := hasattr(self.exception, "response")
+                and self.exception.response
+            ):
+                self.code = str(response.status_code) or ""
+
+                try:
+                    response_text = self.exception.response.text
+                    exception_dict["response"] = json.loads(response_text)
+                except json.JSONDecodeError:
+                    pass
+            for attr in dir(self.exception):
+                try:
+                    if (
+                        not attr.startswith("__")
+                        and not callable(attribute := getattr(self.exception, attr))
+                        and getattr(self.exception, attr)
+                    ):
+                        try:
+                            exception_dict["attributes"][attr] = json.loads(
+                                str(attribute)
+                            )
+                        except json.JSONDecodeError:
+                            pass
+                except Exception:
+                    pass
+
+        result: Dict[str, Any] = {
+            "message": self.message,
+            "code": self.code,
+            "url": self.url,
+            "payload": self.payload,
+            "detail": self.detail,
+        }
+        if self.exception:
+            result["exception"] = exception_dict
+        return result
+
+
+def singleton(cls: type[T]) -> Callable[..., T]:
+    """Decorator to create a singleton class
+    Tested in tests/test_common.py
+    """
+    instances: Dict[type[T], T] = {}
+
+    def get_instance(*args: Any, **kwargs: Any) -> T:
+        if cls not in instances:
+            instances[cls] = cls(*args, **kwargs)
+        return instances[cls]
+
+    return get_instance
+
+
+def encrypt_value(value_to_encrypt: str, public_key: rsa.RSAPublicKey) -> str:
+    """Encrypt using hybrid RSA+AES encryption to handle messages of any size.
+
+    Args:
+        value_to_encrypt (str): Value to encrypt
+        public_key (rsa.RSAPublicKey): RSA public key
+
+    Returns:
+        str: Base64 encoded encrypted value containing both the encrypted AES key and encrypted data
+
+    Raises:
+        ValueError: If encryption fails
+    """
+
+    # Generate random AES key and IV
+    aes_key = os.urandom(32)  # 256-bit key
+    iv = os.urandom(16)
+
+    # Encrypt the AES key with RSA
+    encrypted_key = public_key.encrypt(
+        aes_key,
+        padding.OAEP(
+            mgf=padding.MGF1(algorithm=hashes.SHA256()),
+            algorithm=hashes.SHA256(),
+            label=None,
+        ),
+    )
+
+    # Create AES cipher
+    cipher = Cipher(algorithms.AES(aes_key), modes.CBC(iv))
+    encryptor = cipher.encryptor()
+
+    # Pad data to block size
+    value_bytes = value_to_encrypt.encode("utf-8")
+    pad_length = 16 - (len(value_bytes) % 16)
+    value_bytes += bytes([pad_length]) * pad_length
+
+    # Encrypt data with AES
+    encrypted_data = encryptor.update(value_bytes) + encryptor.finalize()
+
+    # Combine encrypted key, IV and data
+    combined = encrypted_key + iv + encrypted_data
+
+    # Return base64 encoded result
+    return base64.b64encode(combined).decode("utf-8")
+
+
+def decrypt_value(encrypted_value: str, private_key: rsa.RSAPrivateKey) -> str:
+    """Decrypt using hybrid RSA+AES decryption.
+
+    Args:
+        encrypted_value (str): Base64 encoded encrypted value
+        private_key (rsa.RSAPrivateKey): RSA private key
+
+    Returns:
+        str: Decrypted value as string
+
+    Raises:
+        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
+    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
+    iv = combined[256:272]  # 16 bytes IV
+    encrypted_data = combined[272:]  # Rest is encrypted data
+
+    # Decrypt AES key
+    aes_key = private_key.decrypt(
+        encrypted_key,
+        padding.OAEP(
+            mgf=padding.MGF1(algorithm=hashes.SHA256()),
+            algorithm=hashes.SHA256(),
+            label=None,
+        ),
+    )
+
+    # Create AES cipher
+    cipher = Cipher(algorithms.AES(aes_key), modes.CBC(iv))
+    decryptor = cipher.decryptor()
+
+    # Decrypt data
+    decrypted_padded = decryptor.update(encrypted_data) + decryptor.finalize()
+
+    # Remove padding
+    pad_length = decrypted_padded[-1]
+    decrypted = decrypted_padded[:-pad_length]
+
+    return decrypted.decode("utf-8")

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,305 @@
+# 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 if deploy extras are installed (e.g., docker, cloud SDKs)
+    try:
+        import docker
+    except ImportError:
+        console.print(
+            "[bold red]Error:[/] 'deploy' extra requirements are not installed. "
+            "Install them with: [bold]pip install supervaizer[deploy][/]"
+        )
+        raise typer.Exit(1)
+    _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)

supervaizer/deploy/commands/__init__.py

@@ -0,0 +1,9 @@
+# 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/.
+
+from . import plan, up, down, status
+
+__all__ = ["plan", "up", "down", "status"]