supervaizer 0.9.8__py3-none-any.whl → 0.10.1__py3-none-any.whl

supervaizer/agent.py

@@ -28,6 +28,7 @@ from supervaizer.job import Job, JobContext, JobResponse
 from supervaizer.job_service import service_job_finished
 from supervaizer.lifecycle import EntityStatus
 from supervaizer.parameter import ParametersSetup
+from supervaizer.case import CaseNodes
 
 if TYPE_CHECKING:
     from supervaizer.server import Server
@@ -210,6 +211,11 @@ class AgentMethodAbstract(BaseModel):
         },
     }
 
+    nodes: CaseNodes | None = Field(
+        default=None,
+        description="The definition of the Case Nodes (=steps) for this method",
+    )
+
 
 class AgentMethod(AgentMethodAbstract):
     @property
@@ -419,6 +425,7 @@ class AgentMethod(AgentMethodAbstract):
             "params": self.params,
             "fields": self.fields_definitions,
             "description": self.description,
+            "nodes": self.nodes.registration_info if self.nodes else None,
         }
 
 
@@ -440,8 +447,9 @@ class AgentCustomMethodParams(AgentMethodParams):
 
 class AgentMethodsAbstract(BaseModel):
     job_start: AgentMethod
-    job_stop: AgentMethod
-    job_status: AgentMethod
+    job_stop: AgentMethod | None = None
+    job_status: AgentMethod | None = None
+    human_answer: AgentMethod | None = None
     chat: AgentMethod | None = None
     custom: dict[str, AgentMethod] | None = None
 
@@ -476,8 +484,13 @@ class AgentMethods(AgentMethodsAbstract):
     def registration_info(self) -> Dict[str, Any]:
         return {
             "job_start": self.job_start.registration_info,
-            "job_stop": self.job_stop.registration_info,
-            "job_status": self.job_status.registration_info,
+            "job_stop": self.job_stop.registration_info if self.job_stop else None,
+            "job_status": self.job_status.registration_info
+            if self.job_status
+            else None,
+            "human_answer": self.human_answer.registration_info
+            if self.human_answer
+            else None,
             "chat": self.chat.registration_info if self.chat else None,
             "custom": {
                 name: method.registration_info
@@ -575,6 +588,14 @@ class AgentAbstract(SvBaseModel):
         default=60 * 60,
         description="Maximum execution time in seconds, defaults to 1 hour",
     )
+    supervaize_instructions_template_path: Optional[str] = Field(
+        default=None,
+        description="Optional path to a custom template file for supervaize_instructions.html page",
+    )
+    instructions_path: str = Field(
+        default="supervaize_instructions.html",
+        description="Path where the supervaize instructions page is served (relative to agent path)",
+    )
 
     model_config = {
         "reference_group": "Core",
@@ -690,6 +711,7 @@ class Agent(AgentAbstract):
             "server_agent_onboarding_status": self.server_agent_onboarding_status,
             "server_encrypted_parameters": self.server_encrypted_parameters,
             "max_execution_time": self.max_execution_time,
+            "instructions_path": self.instructions_path,
         }
 
     def update_agent_from_server(self, server: "Server") -> Optional["Agent"]:
@@ -888,13 +910,13 @@ class Agent(AgentAbstract):
         return job
 
     def job_stop(self, params: Dict[str, Any] = {}) -> Any:
-        if not self.methods:
+        if not self.methods or not self.methods.job_stop:
             raise ValueError("Agent methods not defined")
         method = self.methods.job_stop.method
         return self._execute(method, params)
 
     def job_status(self, params: Dict[str, Any] = {}) -> Any:
-        if not self.methods:
+        if not self.methods or not self.methods.job_status:
             raise ValueError("Agent methods not defined")
         method = self.methods.job_status.method
         return self._execute(method, params)

supervaizer/case.py

@@ -10,9 +10,9 @@ from enum import Enum
 from typing import TYPE_CHECKING, Any, Dict, List, Optional
 
 import shortuuid
-from pydantic import ConfigDict
-from typing_extensions import deprecated
-
+from pydantic import ConfigDict, Field
+from pydantic.json_schema import SkipJsonSchema
+from typing import Callable
 from supervaizer.common import SvBaseModel, log, singleton
 from supervaizer.lifecycle import EntityEvents, EntityStatus
 from supervaizer.storage import PersistentEntityLifecycle, StorageManager
@@ -55,7 +55,6 @@ class CaseNodeUpdate(SvBaseModel):
             payload (Dict[str, Any]): Additional data for the update - when a question is requested to the user, the payload is the question
             is_final (bool): Whether this is the final update. Default to False
             index (int): Index of the node to update. This is set by Case.update()
-
             error (Optional[str]): Error message if any. Default to None
 
         When payload contains a question (supervaizer_form):
@@ -101,24 +100,32 @@ class CaseNodeUpdate(SvBaseModel):
     @property
     def registration_info(self) -> Dict[str, Any]:
         """Returns registration info for the case node update"""
+        # Serialize payload to convert type objects to strings for JSON serialization
+        serialized_payload = (
+            self.serialize_value(self.payload) if self.payload else None
+        )
         return {
             "index": self.index,
             "name": self.name,
             "error": self.error,
             "cost": self.cost,
-            "payload": self.payload,
+            "payload": serialized_payload,
             "is_final": self.is_final,
         }
 
 
-class CaseNoteType(Enum):
+class CaseNodeType(Enum):
     """
-    CaseNoteType is an enum that represents the type of a case note.
+    CaseNodeType is an enum that represents the type of a case note.
     """
 
     CHAT = "chat"
     TRIGGER = "trigger"
     NOTIFICATION = "notification"
+    STATUS_UPDATE = "status_update"
+    INTERMEDIARY_DELIVERY = "intermediary_delivery"
+    HITL = "human_in_the_loop"
+    DELIVERABLE = "deliverable"
     VALIDATION = "validation"
     DELIVERY = "delivery"
     ERROR = "error"
@@ -126,22 +133,43 @@ class CaseNoteType(Enum):
     INFO = "info"
 
 
-@deprecated("Not used")
 class CaseNode(SvBaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
     name: str
-    description: str
-    type: CaseNoteType
+    type: CaseNodeType
+    factory: SkipJsonSchema[Callable[..., CaseNodeUpdate]] = Field(
+        exclude=True, repr=False
+    )  # Exclude from JSON schema generation and representation
+    description: str | None = None
+    can_be_confirmed: bool = False  # Whether the user can decide that this node needs to be confirmed. This must be set in the job definition.
 
-    class Config:
-        arbitrary_types_allowed = True
+    def __call__(self, *args: Any, **kwargs: Any) -> CaseNodeUpdate:
+        """Make it callable directly."""
+        return self.factory(*args, **kwargs)
 
     @property
     def registration_info(self) -> Dict[str, Any]:
         """Returns registration info for the case node"""
         return {
             "name": self.name,
-            "description": self.description,
             "type": self.type.value,
+            "description": self.description,
+            "can_be_confirmed": self.can_be_confirmed,
+        }
+
+
+class CaseNodes(SvBaseModel):
+    nodes: List[CaseNode] = []
+
+    def get(self, name: str) -> CaseNode | None:
+        return next((node for node in self.nodes if node.name == name), None)
+
+    @property
+    def registration_info(self) -> Dict[str, Any]:
+        """Returns registration info for the case nodes"""
+        return {
+            "nodes": [node.registration_info for node in self.nodes],
         }
 
 
@@ -216,7 +244,11 @@ class Case(CaseAbstractModel):
         storage = StorageManager()
         storage.save_object("Case", self.to_dict)
 
-    def receive_human_input(self, **kwargs: Any) -> None:
+    def receive_human_input(
+        self, updateCaseNode: CaseNodeUpdate, **kwargs: Any
+    ) -> None:
+        # Add the update to the case (this handles index, send_update_case, and persistence)
+        self.update(updateCaseNode)
         # Transition from AWAITING to IN_PROGRESS
         from supervaizer.storage import PersistentEntityLifecycle
 

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")
@@ -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