supervaizer 0.10.5__py3-none-any.whl

supervaizer/deploy/templates/debug_env.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+# 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/.
+
+"""Debug script to check environment variables in container."""
+
+import os
+import sys
+
+
+def debug_environment_variables() -> None:
+    """Print all environment variables for debugging."""
+    print("=== Environment Variables Debug ===")
+    print(f"Python version: {sys.version}")
+    print(f"Working directory: {os.getcwd()}")
+    print()
+
+    # Check specific Supervaize environment variables
+    supervaize_vars = [
+        "SUPERVAIZE_API_KEY",
+        "SUPERVAIZE_WORKSPACE_ID",
+        "SUPERVAIZE_API_URL",
+        "SUPERVAIZER_PORT",
+        "SUPERVAIZER_PUBLIC_URL",
+        "SUPERVAIZER_ENVIRONMENT",
+        "SUPERVAIZER_HOST",
+        "SUPERVAIZER_API_KEY",
+        "SV_RSA_PRIVATE_KEY",
+        "SV_LOG_LEVEL",
+    ]
+
+    print("=== Supervaize Environment Variables ===")
+    for var_name in supervaize_vars:
+        value = os.getenv(var_name)
+        if value is None:
+            print(f"{var_name}: [NOT SET]")
+        elif value == "":
+            print(f"{var_name}: [EMPTY STRING]")
+        else:
+            # Mask sensitive values
+            if "KEY" in var_name or "SECRET" in var_name:
+                masked_value = (
+                    value[:4] + "*" * (len(value) - 8) + value[-4:]
+                    if len(value) > 8
+                    else "*" * len(value)
+                )
+                print(f"{var_name}: {masked_value}")
+            else:
+                print(f"{var_name}: {value}")
+
+    print()
+    print("=== All Environment Variables ===")
+    for key, value in sorted(os.environ.items()):
+        if "KEY" in key or "SECRET" in key or "PASSWORD" in key:
+            masked_value = (
+                value[:4] + "*" * (len(value) - 8) + value[-4:]
+                if len(value) > 8
+                else "*" * len(value)
+            )
+            print(f"{key}: {masked_value}")
+        else:
+            print(f"{key}: {value}")
+
+
+if __name__ == "__main__":
+    debug_environment_variables()

supervaizer/deploy/templates/docker-compose.yml.template

@@ -0,0 +1,37 @@
+services:
+  {{SERVICE_NAME}}:
+    build:
+      context: ..
+      dockerfile: .deployment/Dockerfile
+      args:
+        - SUPERVAIZE_API_KEY={{API_KEY}}
+        - SUPERVAIZE_WORKSPACE_ID={{WORKSPACE_ID}}
+        - SUPERVAIZE_API_URL={{API_URL}}
+        - SUPERVAIZER_PORT=8000
+        - SUPERVAIZER_PUBLIC_URL={{PUBLIC_URL}}
+    ports:
+      - "{{PORT}}:8000"
+    environment:
+      - SUPERVAIZER_ENVIRONMENT={{ENVIRONMENT}}
+      - SUPERVAIZER_HOST=0.0.0.0
+      - SUPERVAIZER_PORT=8000
+      - SV_LOG_LEVEL={{ env.SV_LOG_LEVEL | default('INFO') }}
+      - SUPERVAIZER_API_KEY={{API_KEY}}
+      - SV_RSA_PRIVATE_KEY={{RSA_KEY}}
+      - SUPERVAIZE_API_KEY={{API_KEY}}
+      - SUPERVAIZE_WORKSPACE_ID={{WORKSPACE_ID}}
+      - SUPERVAIZE_API_URL={{API_URL}}
+      - SUPERVAIZER_PUBLIC_URL={{PUBLIC_URL}}
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8000/.well-known/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+    restart: unless-stopped
+    networks:
+      - supervaizer-network
+
+networks:
+  supervaizer-network:
+    driver: bridge

supervaizer/deploy/templates/dockerignore.template

@@ -0,0 +1,66 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+env.bak/
+venv.bak/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Git
+.git/
+.gitignore
+
+# Documentation
+docs/
+*.md
+README*
+
+# Tests
+tests/
+test_*
+*_test.py
+
+# Deployment artifacts
+.deployment/
+!.deployment/debug_env.py
+
+# Logs
+*.log
+logs/
+
+# Temporary files
+tmp/
+temp/

supervaizer/deploy/templates/entrypoint.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+set -e
+
+# Change to app directory
+cd /app
+
+# Remove any stale .venv references that might cause issues
+if [ -d ".venv" ] && [ ! -f ".venv/bin/python3" ]; then
+    rm -rf .venv
+fi
+
+# Install the project if not already installed
+# This ensures the supervaizer command is available
+if ! command -v supervaizer &> /dev/null; then
+    echo "Installing supervaizer..."
+    uv sync --frozen --no-dev
+fi
+
+# Run supervaizer start
+exec uv run supervaizer start

supervaizer/deploy/utils.py

@@ -0,0 +1,52 @@
+# 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 State Management
+
+This module handles deployment state persistence and management.
+"""
+
+import subprocess
+from pathlib import Path
+
+from supervaizer.common import log
+
+
+def create_deployment_directory(project_root: Path) -> Path:
+    """Create deployment directory and add to .gitignore."""
+    deployment_dir = project_root / ".deployment"
+    deployment_dir.mkdir(exist_ok=True)
+
+    # Create logs subdirectory
+    logs_dir = deployment_dir / "logs"
+    logs_dir.mkdir(exist_ok=True)
+
+    # Add to .gitignore if not already present
+    gitignore_path = project_root / ".gitignore"
+    gitignore_entry = ".deployment/"
+
+    if gitignore_path.exists():
+        gitignore_content = gitignore_path.read_text()
+        if gitignore_entry not in gitignore_content:
+            gitignore_path.write_text(gitignore_content + f"\n{gitignore_entry}\n")
+            log.info(f"Added {gitignore_entry} to .gitignore")
+    else:
+        gitignore_path.write_text(f"{gitignore_entry}\n")
+        log.info(f"Created .gitignore with {gitignore_entry}")
+
+    return deployment_dir
+
+
+def get_git_sha() -> str:
+    """Get the current git SHA for tagging."""
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "HEAD"], capture_output=True, text=True, check=True
+        )
+        return result.stdout.strip()[:8]  # Use short SHA
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return "latest"

supervaizer/event.py

@@ -0,0 +1,181 @@
+# 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 enum import Enum
+from typing import TYPE_CHECKING, Any, ClassVar, Dict
+
+from supervaizer.__version__ import VERSION
+from supervaizer.common import SvBaseModel
+from supervaizer.lifecycle import EntityStatus
+
+if TYPE_CHECKING:
+    from supervaizer.agent import Agent
+    from supervaizer.case import Case, CaseNodeUpdate
+    from supervaizer.job import Job
+    from supervaizer.server import Server
+
+
+class EventType(str, Enum):
+    AGENT_REGISTER = "agent.register"
+    SERVER_REGISTER = "server.register"
+    AGENT_WAKEUP = "agent.wakeup"
+    AGENT_SEND_ANOMALY = "agent.anomaly"
+    INTERMEDIARY = "agent.intermediary"
+    JOB_START_CONFIRMATION = "agent.job.start.confirmation"
+    JOB_END = "agent.job.end"
+    JOB_STATUS = "agent.job.status"
+    JOB_RESULT = "agent.job.result"
+    JOB_ERROR = "agent.job.error"
+    CASE_START = "agent.case.start"
+    CASE_END = "agent.case.end"
+    CASE_STATUS = "agent.case.status"
+    CASE_RESULT = "agent.case.result"
+    CASE_UPDATE = "agent.case.update"
+
+
+class AbstractEvent(SvBaseModel):
+    supervaizer_VERSION: ClassVar[str] = VERSION
+    source: Dict[str, Any]
+    account: Any  # Use Any to avoid Pydantic type resolution issues
+    type: EventType
+    object_type: str
+    details: Dict[str, Any]
+
+
+class Event(AbstractEvent):
+    """Base class for all events in the Supervaize Control system.
+
+    Events represent messages sent from agents to the control system to communicate
+    status, anomalies, deliverables and other information.
+
+    Inherits from AbstractEvent which defines the core event attributes:
+        - source: The source/origin of the event (e.g. agent/server URI)
+        - type: The EventType enum indicating the event category
+        - account: The account that the event belongs to
+        - details: A dictionary containing event-specific details
+
+    Tests in tests/test_event.py
+    """
+
+    def __init__(self, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+
+    @property
+    def payload(self) -> Dict[str, Any]:
+        """
+        Returns the payload for the event.
+        This must be a dictionary that can be serialized to JSON to be sent in the request body.
+        """
+        return {
+            "source": self.source,
+            "workspace": f"{self.account.workspace_id}",
+            "event_type": f"{self.type.value}",
+            "object_type": self.object_type,
+            "details": self.details,
+        }
+
+
+class AgentRegisterEvent(Event):
+    """Event sent when an agent registers with the control system.
+
+    Test in tests/test_agent_register_event.py
+    """
+
+    def __init__(
+        self,
+        agent: "Agent",
+        account: Any,  # Use Any to avoid type resolution issues
+        polling: bool = True,
+    ) -> None:
+        super().__init__(
+            type=EventType.AGENT_REGISTER,
+            account=account,
+            source={"agent": agent.slug},
+            object_type="agent",
+            details=agent.registration_info | {"polling": polling},
+        )
+
+
+class ServerRegisterEvent(Event):
+    def __init__(
+        self,
+        account: Any,  # Use Any to avoid type resolution issues
+        server: "Server",
+    ) -> None:
+        super().__init__(
+            type=EventType.SERVER_REGISTER,
+            source={"server": server.uri},
+            account=account,
+            object_type="server",
+            details=server.registration_info,
+        )
+
+
+class JobStartConfirmationEvent(Event):
+    def __init__(
+        self,
+        job: "Job",
+        account: Any,  # Use Any to avoid type resolution issues
+    ) -> None:
+        super().__init__(
+            type=EventType.JOB_START_CONFIRMATION,
+            account=account,
+            source={"job": job.id},
+            object_type="job",
+            details=job.registration_info,
+        )
+
+
+class JobFinishedEvent(Event):
+    def __init__(self, job: "Job", account: Any) -> None:
+        # Check if job has responses, otherwise use the job's current status
+        if job.responses:
+            details = job.responses[-1].status
+        else:
+            details = job.status
+
+        event_type = (
+            EventType.JOB_END
+            if details == EntityStatus.COMPLETED
+            else EventType.JOB_ERROR
+        )
+
+        super().__init__(
+            type=event_type,
+            account=account,
+            source={"job": job.id},
+            object_type="job",
+            details=job.registration_info,
+        )
+
+
+class CaseStartEvent(Event):
+    def __init__(
+        self, case: "Case", account: Any
+    ) -> None:  # Use Any to avoid type resolution issues
+        super().__init__(
+            type=EventType.CASE_START,
+            account=account,
+            source={"job": case.job_id, "case": case.id},
+            object_type="case",
+            details=case.registration_info,
+        )
+
+
+class CaseUpdateEvent(Event):
+    def __init__(
+        self,
+        case: "Case",
+        account: Any,
+        update: "CaseNodeUpdate",
+    ) -> None:
+        super().__init__(
+            type=EventType.CASE_UPDATE,
+            account=account,
+            source={"job": case.job_id, "case": case.id},
+            object_type="case",
+            details=update.registration_info,
+        )

supervaizer/examples/controller_template.py

@@ -0,0 +1,196 @@
+# 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/.
+
+# This is an example file.
+# It must be copied / renamed to supervaizer_control.py
+# and edited to configure your agent(s)
+
+import os
+import shortuuid
+from rich.console import Console
+
+from supervaizer import (
+    Agent,
+    AgentMethod,
+    AgentMethods,
+    Parameter,
+    ParametersSetup,
+    Server,
+)
+from supervaizer.account import Account
+
+# Create a console with default style set to yellow
+console = Console(style="yellow")
+
+# Public url of your hosted agent  (including port if needed)
+# Use loca.lt or ngrok to get a public url during development.
+# This can be setup from environment variables.
+# SUPERVAIZER_HOST and SUPERVAIZER_PORT
+DEV_PUBLIC_URL = "https://myagent-dev.loca.lt"
+# Public url of your hosted agent
+PROD_PUBLIC_URL = "https://myagent.cloud-hosting.net:8001"
+
+# Define the parameters and secrets expected by the agent
+agent_parameters: ParametersSetup | None = ParametersSetup.from_list(
+    [
+        Parameter(
+            name="OPEN_API_KEY",
+            description="OpenAPI Key",
+            is_environment=True,
+            is_secret=True,
+        ),
+        Parameter(
+            name="SERPER_API",
+            description="Server API key updated",
+            is_environment=True,
+            is_secret=True,
+        ),
+        Parameter(
+            name="COMPETITOR_SUMMARY_URL",
+            description="Competitor Summary URL",
+            is_environment=True,
+            is_secret=False,
+        ),
+    ]
+)
+
+# Define the method used to start a job
+job_start_method: AgentMethod = AgentMethod(
+    name="start",  # This is required
+    method="example_agent.example_synchronous_job_start",  # Path to the main function in dotted notation.
+    is_async=False,  # Only use sync methods for the moment
+    params={"action": "start"},  # If default parameters must be passed to the function.
+    fields=[
+        {
+            "name": "Company to research",  # Field name - displayed in the UI
+            "type": str,  # Python type of the field for pydantic validation - note , ChoiceField and MultipleChoiceField are a list[str]
+            "field_type": "CharField",  # Field type for persistence.
+            "description": "Company to research",  # Optional -  Description of the field - displayed in the UI
+            "default": "Google",  # Optional - Default value for the field
+            "required": True,  # Whether the field is required
+        },
+        {
+            "name": "Max number of results",
+            "type": int,
+            "field_type": "IntegerField",
+            "required": True,
+        },
+        {
+            "name": "Subscribe to updates",
+            "type": bool,
+            "field_type": "BooleanField",
+            "required": False,
+        },
+        {
+            "name": "Type of research",
+            "type": str,
+            "field_type": "ChoiceField",
+            "choices": [["A", "Advanced"], ["R", "Restricted"]],
+            "widget": "RadioSelect",
+            "required": True,
+        },
+        {
+            "name": "Details of research",
+            "type": str,
+            "field_type": "CharField",
+            "widget": "Textarea",
+            "required": False,
+        },
+        {
+            "name": "List of countries",
+            "type": list[str],
+            "field_type": "MultipleChoiceField",
+            "choices": [
+                ["PA", "Panama"],
+                ["PG", "Papua New Guinea"],
+                ["PY", "Paraguay"],
+                ["PE", "Peru"],
+                ["PH", "Philippines"],
+                ["PN", "Pitcairn"],
+                ["PL", "Poland"],
+            ],
+            "required": True,
+        },
+        {
+            "name": "languages",
+            "type": list[str],
+            "field_type": "MultipleChoiceField",
+            "choices": [["en", "English"], ["fr", "French"], ["es", "Spanish"]],
+            "required": False,
+        },
+    ],
+    description="Start the collection of new competitor summary",
+)
+
+job_stop_method: AgentMethod = AgentMethod(
+    name="stop",
+    method="control.stop",
+    params={"action": "stop"},
+    description="Stop the agent",
+)
+job_status_method: AgentMethod = AgentMethod(
+    name="status",
+    method="hello.mystatus",
+    params={"status": "statusvalue"},
+    description="Get the status of the agent",
+)
+custom_method: AgentMethod = AgentMethod(
+    name="custom",
+    method="control.custom",
+    params={"action": "custom"},
+    description="Custom method",
+)
+
+custom_method2: AgentMethod = AgentMethod(
+    name="custom2",
+    method="control.custom2",
+    params={"action": "custom2"},
+    description="Custom method",
+)
+
+
+agent_name = "competitor_summary"
+
+# Define the Agent
+agent: Agent = Agent(
+    name=agent_name,
+    id=shortuuid.uuid(f"{agent_name}"),
+    author="John Doe",  # Author of the agent
+    developer="Developer",  # Developer of the controller integration
+    maintainer="Ive Maintained",  # Maintainer of the integration
+    editor="DevAiExperts",  # Editor (usually a company)
+    version="1.3",  # Version string
+    description="This is a test agent",
+    tags=["testtag", "testtag2"],
+    methods=AgentMethods(
+        job_start=job_start_method,
+        job_stop=job_stop_method,
+        job_status=job_status_method,
+        chat=None,
+        custom={"custom1": custom_method, "custom2": custom_method2},
+    ),
+    parameters_setup=agent_parameters,
+    instructions_path="supervaize_instructions.html",  # Path where instructions page is served
+)
+
+# For export purposes, use dummy values if environment variables are not set
+account: Account = Account(
+    workspace_id=os.getenv("SUPERVAIZE_WORKSPACE_ID") or "dummy_workspace_id",
+    api_key=os.getenv("SUPERVAIZE_API_KEY") or "dummy_api_key",
+    api_url=os.getenv("SUPERVAIZE_API_URL") or "https://api.supervaize.com",
+)
+
+# Define the supervaizer server capabilities
+sv_server: Server = Server(
+    agents=[agent],
+    a2a_endpoints=True,  # Enable A2A endpoints
+    supervisor_account=account,  # Account of the supervisor from Supervaize
+)
+
+
+if __name__ == "__main__":
+    # Start the supervaize server
+    sv_server.launch(log_level="DEBUG")