supervaizer 0.9.6__py3-none-any.whl

supervaizer/instructions.py

@@ -0,0 +1,145 @@
+# 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 sys
+
+from art import text2art
+from rich import box, print
+from rich.align import Align
+from rich.console import Console, Group
+from rich.layout import Layout
+from rich.panel import Panel
+from rich.syntax import Syntax
+from rich.table import Table
+
+from supervaizer.__version__ import VERSION
+
+console = Console()
+
+
+def make_layout() -> Layout:
+    """Define the layout."""
+    layout = Layout(name="root")
+
+    layout.split(
+        Layout(name="header", size=10),
+        Layout(name="main", ratio=1),
+        Layout(name="footer", size=7),
+    )
+    layout["main"].split_row(
+        Layout(name="side"),
+        Layout(name="body", ratio=2, minimum_size=100),
+    )
+    return layout
+
+
+def make_documentation_message(server_url: str) -> Panel:
+    """Some example content."""
+    sponsor_message = Table.grid(padding=1)
+    sponsor_message.add_column(style="green", justify="right")
+    sponsor_message.add_column(no_wrap=True)
+    sponsor_message.add_row(
+        "Integration documentation",
+        "[u blue link=https://supervaize.com/docs/integration]https://supervaize.com/docs/integration[/]",
+    )
+    sponsor_message.add_row()
+    sponsor_message.add_row(
+        "Swagger",
+        f"[u blue link={server_url}/docs]{server_url}/docs[/]",
+    )
+    sponsor_message.add_row(
+        "Redoc",
+        f"[u blue link={server_url}/redoc]{server_url}/redoc[/]",
+    )
+    sponsor_message.add_row(
+        "API",
+        f"[u blue link={server_url}/api]{server_url}/api[/]",
+    )
+
+    message = Table.grid(padding=1)
+    message.add_column()
+    message.add_column(no_wrap=True)
+    message.add_row(sponsor_message)
+
+    message_panel = Panel(
+        Align.center(
+            Group("\n", Align.center(sponsor_message)),
+            vertical="middle",
+        ),
+        box=box.ROUNDED,
+        padding=(1, 2),
+        title="[b red]Check Supervaize documentation",
+        border_style="bright_blue",
+    )
+    return message_panel
+
+
+class Header:
+    def __rich__(self) -> Panel:
+        grid = Table.grid(expand=True)
+        grid.add_column(justify="center", ratio=1)
+        grid.add_column(justify="right")
+        logo = text2art("Supervaize Control")
+        grid.add_row(logo, f"[b]v{VERSION}[/]")
+        return Panel(grid, border_style="blue")
+
+
+def make_syntax() -> Panel:
+    """Create a syntax-highlighted code panel."""
+    code = """\
+from supervaizer Server, Account, Agent
+sv_account = Account(
+    name="CUSTOMERFIRST",
+    id="xxxxxxxxxxxx",
+    api_key=os.getenv("SUPERVAIZE_API_KEY"),
+    api_url=os.getenv("SUPERVAIZE_API_URL"),
+    )
+
+job_start = AgentMethod(
+    name="job_start",
+    method="control.job_start",
+    params={"action": "run"},
+    description="Start the job",
+    )
+agent = Agent(
+    name="my_agent",
+    account=sv_account,
+    method=job_start_method,
+)
+server = Server()
+server.launch()
+    """
+    syntax = Syntax(code, "python", line_numbers=True)
+    panel = Panel(syntax, border_style="green", title="Sample integration code")
+    return panel
+
+
+def make_footer(status_message: str) -> Panel:
+    """Create a footer panel with status message."""
+    return Panel(status_message, border_style="green")
+
+
+def display_instructions(server_url: str, status_message: str) -> None:
+    """Display the full instructions layout.
+
+    Args:
+        server_url: The URL where the server is running
+        status_message: Status message to display in footer
+    """
+    layout = make_layout()
+    layout["header"].update(Header())
+    layout["body"].update(make_documentation_message(server_url))
+    layout["side"].update(make_syntax())
+    layout["footer"].update(make_footer(status_message))
+
+    print(layout)
+    sys.exit(0)  # This function never returns normally
+
+
+if __name__ == "__main__":
+    display_instructions(
+        "http://127.0.0.1:8000", "Starting server on http://127.0.0.1:8000"
+    )

supervaizer/job.py

@@ -0,0 +1,379 @@
+# 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 time
+import traceback
+import uuid
+from datetime import datetime
+from typing import TYPE_CHECKING, Any, ClassVar, Dict, List, Optional
+
+from supervaizer.__version__ import VERSION
+from supervaizer.common import SvBaseModel, log, singleton
+from supervaizer.lifecycle import (
+    EntityEvents,
+    EntityStatus,
+    Lifecycle,
+)
+from supervaizer.storage import storage_manager
+
+if TYPE_CHECKING:
+    pass
+
+
+@singleton
+class Jobs:
+    """Global registry for all jobs, organized by agent."""
+
+    def __init__(self) -> None:
+        # Structure: {agent_name: {job_id: Job}}
+        self.jobs_by_agent: dict[str, dict[str, "Job"]] = {}
+
+    def reset(self) -> None:
+        self.jobs_by_agent.clear()
+
+    def add_job(self, job: "Job") -> None:
+        """Add a job to the registry under its agent
+
+        Args:
+            job (Job): The job to add
+
+        Raises:
+            ValueError: If job with same ID already exists for this agent
+        """
+        agent_name = job.agent_name
+
+        # Initialize agent's job dict if not exists
+        if agent_name not in self.jobs_by_agent:
+            self.jobs_by_agent[agent_name] = {}
+
+        # Check if job already exists for this agent
+        if job.id in self.jobs_by_agent[agent_name]:
+            log.warning(f"Job ID '{job.id}' already exists for agent {agent_name}.")
+
+        self.jobs_by_agent[agent_name][job.id] = job
+
+    def get_job(
+        self,
+        job_id: str,
+        agent_name: str | None = None,
+        include_persisted: bool = False,
+    ) -> "Job | None":
+        """Get a job by its ID and optionally agent name
+
+        Args:
+            job_id (str): The ID of the job to get
+            agent_name (str | None): The name of the agent. If None, searches all agents.
+            include_persisted (bool): Whether to include persisted jobs. Defaults to False.
+
+        Returns:
+            Job | None: The job if found, None otherwise
+        """
+        found_job = None
+
+        if agent_name:
+            # Search in specific agent's jobs
+            found_job = self.jobs_by_agent.get(agent_name, {}).get(job_id)
+
+        # Search across all agents
+        for agent_jobs in self.jobs_by_agent.values():
+            if job_id in agent_jobs:
+                found_job = agent_jobs[job_id]
+
+        if include_persisted:
+            job_from_storage = storage_manager.get_object_by_id("Job", job_id)
+            if job_from_storage:
+                found_job = Job(**job_from_storage)
+        return found_job
+
+    def get_agent_jobs(self, agent_name: str) -> dict[str, "Job"]:
+        """Get all jobs for a specific agent
+
+        Args:
+            agent_name (str): The name of the agent
+
+        Returns:
+            dict[str, Job]: Dictionary of jobs for this agent, empty if agent not found
+        """
+        return self.jobs_by_agent.get(agent_name, {})
+
+    def __contains__(self, job_id: str) -> bool:
+        """Check if job exists in any agent's registry"""
+        return any(job_id in jobs for jobs in self.jobs_by_agent.values())
+
+
+class JobInstructions(SvBaseModel):
+    max_cases: int | None = None
+    max_duration: int | None = None  # in seconds
+    max_cost: float | None = None
+    stop_on_warning: bool = False
+    stop_on_error: bool = True
+
+    job_start_time: float | None = None
+
+    def check(self, cases: int, cost: float) -> tuple[bool, str]:
+        """Check if the job conditions are met
+
+        Args:
+            cases (int): Number of cases processed so far
+            start_time (float): Start time of the job - using time.perf_counter()
+
+        Returns:
+            tuple[bool, str]: True if job can continue, False if it should stop,
+                with explanation message
+        """
+        if not self.job_start_time:
+            self.job_start_time = time.perf_counter()
+        if self.max_cases and cases >= self.max_cases:
+            return (False, f"Max cases {self.max_cases} reached")
+
+        duration = time.perf_counter() - self.job_start_time
+        if self.max_duration and duration >= self.max_duration:
+            return (False, f"Max duration {self.max_duration} seconds reached")
+
+        if self.max_cost and cost >= self.max_cost:
+            return (False, f"Max cost {self.max_cost} reached")
+
+        return (True, "")
+
+    @property
+    def registration_info(self) -> Dict[str, Any]:
+        """Returns registration info for the job instructions"""
+        return {
+            "max_cases": self.max_cases,
+            "max_duration": self.max_duration,
+            "max_cost": self.max_cost,
+            "stop_on_warning": self.stop_on_warning,
+            "stop_on_error": self.stop_on_error,
+        }
+
+
+class JobContext(SvBaseModel):
+    workspace_id: str
+    job_id: str
+    started_by: str
+    started_at: datetime
+    mission_id: str
+    mission_name: str
+    mission_context: Any = None
+    job_instructions: Optional[JobInstructions] = None
+
+    @property
+    def registration_info(self) -> Dict[str, Any]:
+        """Returns registration info for the job context"""
+        return {
+            "workspace_id": self.workspace_id,
+            "job_id": self.job_id,
+            "started_by": self.started_by,
+            "started_at": self.started_at.isoformat() if self.started_at else "",
+            "mission_id": self.mission_id,
+            "mission_name": self.mission_name,
+            "mission_context": self.mission_context,
+            "job_instructions": self.job_instructions.registration_info
+            if self.job_instructions
+            else None,
+        }
+
+
+class JobResponse(SvBaseModel):
+    job_id: str
+    status: EntityStatus
+    message: str
+    payload: Optional[dict[str, Any]] = None
+    error_message: Optional[str] = None
+    error_traceback: Optional[str] = None
+
+    def __init__(
+        self,
+        job_id: str,
+        status: EntityStatus,
+        message: str,
+        payload: Optional[dict[str, Any]] = None,
+        error: Optional[Exception] = None,
+        **kwargs: Any,
+    ) -> None:
+        log.debug(
+            f"[JobResponse __init__] job_id={job_id}, status={status}, message={message}, payload={payload}, error={error}, kwargs={kwargs}"
+        )
+        if error:
+            error_message = str(error)
+            error_traceback = traceback.format_exc()
+        else:
+            error_message = error_traceback = ""
+        kwargs["job_id"] = job_id
+        kwargs["status"] = status
+        kwargs["message"] = message
+        kwargs["payload"] = payload
+        kwargs["error_message"] = error_message
+        kwargs["error_traceback"] = error_traceback
+        super().__init__(**kwargs)
+
+        if error:
+            log.error(
+                f"[Job Response] Execution failed - Job ID <{self.job_id}>: {self.error_message}"
+            )
+            log.error(self.error_traceback)
+
+    @property
+    def registration_info(self) -> Dict[str, Any]:
+        """Returns registration info for the job response"""
+        return {
+            "job_id": self.job_id,
+            "status": self.status.value,
+            "message": self.message,
+            "payload": self.payload,
+            "error_message": self.error_message,
+            "error_traceback": self.error_traceback,
+        }
+
+
+class AbstractJob(SvBaseModel):
+    supervaizer_VERSION: ClassVar[str] = VERSION
+    id: str
+    name: str
+    agent_name: str
+    status: EntityStatus
+    job_context: JobContext
+    payload: Any | None = None
+    result: Any | None = None
+    error: str | None = None
+    responses: list["JobResponse"] = []
+    finished_at: datetime | None = None
+    created_at: datetime | None = None
+    agent_parameters: List[dict[str, Any]] | None = None
+    case_ids: List[str] = []  # Foreign key relationship to cases
+
+
+class Job(AbstractJob):
+    """
+    Jobs are typically created by the platform and are not created by the agent.
+
+    Args:
+        id (str): Unique identifier for the job - provided by the platform
+        agent_name (str): Name (slug) of the agent running the job
+        status (EntityStatus): Current status of the job
+        job_context (JobContext): Context information for the job
+        payload (Any, optional): Job payload data. Defaults to None
+        result (Any, optional): Job result data. Defaults to None
+        error (str, optional): Error message if job failed. Defaults to None
+        responses (list[JobResponse], optional): List of job responses. Defaults to empty list
+        finished_at (datetime, optional): When job completed. Defaults to None
+        created_at (datetime, optional): When job was created. Defaults to None
+    """
+
+    def __init__(self, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self.created_at = datetime.now()
+        Jobs().add_job(
+            job=self,
+        )
+        # Persist job to storage
+
+        storage_manager.save_object("Job", self.to_dict)
+
+    def add_response(self, response: JobResponse) -> None:
+        """Add a response to the job and update status based on the event lifecycle.
+
+        Args:
+            response: The response to add
+        """
+        if response.status in Lifecycle.get_terminal_states():
+            self.finished_at = datetime.now()
+
+        # Update payload
+        self.payload = response.payload
+        self.status = response.status
+        # Additional handling for completed or failed jobs
+        if response.status == EntityStatus.COMPLETED:
+            self.result = response.payload
+
+        if response.status == EntityStatus.FAILED:
+            self.error = response.message
+
+        self.responses.append(response)
+
+        # Persist updated job to storage
+
+        storage_manager.save_object("Job", self.to_dict)
+
+    def add_case_id(self, case_id: str) -> None:
+        """Add a case ID to this job's case list.
+
+        Args:
+            case_id: The case ID to add
+        """
+        if case_id not in self.case_ids:
+            self.case_ids.append(case_id)
+            log.debug(f"[Job add_response] Added case {case_id} to job {self.id}")
+            # Persist updated job to storage
+            storage_manager.save_object("Job", self.to_dict)
+
+    def remove_case_id(self, case_id: str) -> None:
+        """Remove a case ID from this job's case list.
+
+        Args:
+            case_id: The case ID to remove
+        """
+        if case_id in self.case_ids:
+            self.case_ids.remove(case_id)
+            log.debug(f"Removed case {case_id} from job {self.id}")
+            # Persist updated job to storage
+            storage_manager.save_object("Job", self.to_dict)
+
+    @property
+    def registration_info(self) -> Dict[str, Any]:
+        """Returns registration info for the job"""
+        return {
+            "id": self.id,
+            "agent_name": self.agent_name,
+            "status": self.status.value,
+            "job_context": self.job_context.registration_info,
+            "payload": self.payload,
+            "result": self.result,
+            "error": self.error,
+            "responses": [response.registration_info for response in self.responses],
+            "finished_at": self.finished_at.isoformat() if self.finished_at else "",
+            "created_at": self.created_at.isoformat() if self.created_at else "",
+            "case_ids": self.case_ids,
+        }
+
+    @classmethod
+    def new(
+        cls,
+        job_context: "JobContext",
+        agent_name: str,
+        agent_parameters: Optional[List[dict[str, Any]]] = None,
+        name: Optional[str] = None,
+    ) -> "Job":
+        """Create a new job
+
+        Args:
+            job_context (JobContext): The context of the job
+            agent_name (str): The name of the agent
+            agent_parameters (dict[str, Any] | None): Optional parameters for the job
+            name (str | None): Optional name for the job, defaults to mission name if not provided
+
+        Returns:
+            Job: The new job
+        """
+        job_id = job_context.job_id or str(uuid.uuid4())
+        # Use provided name or fallback to mission name from context
+        job_name = name or job_context.mission_name
+
+        job = cls(
+            id=job_id,
+            name=job_name,
+            agent_name=agent_name,
+            job_context=job_context,
+            status=EntityStatus.STOPPED,
+            agent_parameters=agent_parameters,
+        )
+
+        # Transition from STOPPED to IN_PROGRESS
+        from supervaizer.storage import PersistentEntityLifecycle
+
+        PersistentEntityLifecycle.handle_event(job, EntityEvents.START_WORK)
+
+        return job

supervaizer/job_service.py

@@ -0,0 +1,155 @@
+# 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 json
+from typing import TYPE_CHECKING, Any, Dict, Optional
+
+from rich import inspect
+
+from supervaizer.common import decrypt_value, log
+from supervaizer.event import JobFinishedEvent
+from supervaizer.job import Job, Jobs
+from supervaizer.lifecycle import EntityStatus
+
+if TYPE_CHECKING:
+    from fastapi import BackgroundTasks
+
+    from supervaizer.agent import Agent
+    from supervaizer.job import JobContext
+    from supervaizer.server import Server
+
+
+async def service_job_start(
+    server: "Server",
+    background_tasks: "BackgroundTasks",
+    agent: "Agent",
+    sv_context: "JobContext",
+    job_fields: Dict[str, Any],
+    encrypted_agent_parameters: Optional[str] = None,
+) -> "Job":
+    """
+    Create a new job and schedule its execution.
+
+    Args:
+        server: The server instance
+        background_tasks: FastAPI background tasks
+        agent: The agent to run the job
+        sv_context: The supervaize context
+        job_fields: Fields for the job
+        encrypted_agent_parameters: Optional encrypted parameters
+
+    Returns:
+        The created job
+    """
+    agent_parameters: dict[str, Any] | None = None
+    # If agent has parameters_setup defined, validate parameters
+    if getattr(agent, "parameters_setup") and encrypted_agent_parameters:
+        agent_parameters_str = decrypt_value(
+            encrypted_agent_parameters, server.private_key
+        )
+        agent_parameters = (
+            json.loads(agent_parameters_str) if agent_parameters_str else None
+        )
+
+        inspect(agent)
+        log.debug(f"[Decrypted parameters] : parameters = {agent_parameters}")
+
+    # Create and prepare the job
+    new_saas_job = Job.new(
+        job_context=sv_context,
+        agent_name=agent.name,
+        agent_parameters=[agent_parameters] if agent_parameters else None,
+        name=sv_context.job_id,
+    )
+
+    # Start the background execution
+    background_tasks.add_task(
+        agent.job_start, new_saas_job, job_fields, sv_context, server
+    )
+    return new_saas_job
+
+
+def service_job_finished(job: Job, server: "Server") -> None:
+    """
+    Service to handle the completion of a job.
+
+    Args:
+        job: The job that has finished
+        server: The server instance
+
+    Tested in tests/test_job_service.py
+    """
+    assert server.supervisor_account is not None, "No account defined"
+    account = server.supervisor_account
+    event = JobFinishedEvent(
+        job=job,
+        account=account,
+    )
+    account.send_event(sender=job, event=event)
+
+
+async def service_job_custom(
+    method_name: str,
+    server: "Server",
+    background_tasks: "BackgroundTasks",
+    agent: "Agent",
+    sv_context: "JobContext",
+    job_fields: Dict[str, Any],
+    encrypted_agent_parameters: Optional[str] = None,
+) -> "Job":
+    """
+    Create a new job and schedule its execution for a custom method.
+
+    Args:
+        server: The server instance
+        background_tasks: FastAPI background tasks
+        agent: The agent to run the job
+        sv_context: The supervaize context
+        job_fields: Fields for the job
+        encrypted_agent_parameters: Optional encrypted parameters
+
+    Returns:
+        The created job
+    """
+    log.info(
+        f"[service_job_custom] /custom/{method_name} [custom job] {agent.name} with params {job_fields}"
+    )
+    _agent_parameters: dict[str, Any] | None = None
+    # If agent has parameters_setup defined, validate parameters
+    if getattr(agent, "parameters_setup") and encrypted_agent_parameters:
+        agent_parameters_str = decrypt_value(
+            encrypted_agent_parameters, server.private_key
+        )
+        _agent_parameters = (
+            json.loads(agent_parameters_str) if agent_parameters_str else None
+        )
+        log.debug("[Decrypted parameters] : parameters decrypted")
+
+    # Create and prepare the job
+    job_id = sv_context.job_id
+
+    if not job_id:
+        raise ValueError(
+            "[service_job_custom] Job ID is required to start a custom job"
+        )
+
+    job = Jobs().get_job(job_id) or Job(
+        id=job_id,
+        job_context=sv_context,
+        agent_name=agent.name,
+        name=sv_context.mission_name,
+        status=EntityStatus.STOPPED,
+    )  # TODO clean the name
+    # Start the background execution
+    background_tasks.add_task(
+        agent.job_start,
+        job,
+        job_fields,
+        sv_context,
+        server,
+        method_name,
+    )
+    return job