supervaizer 0.9.6__py3-none-any.whl

supervaizer/common.py

@@ -0,0 +1,283 @@
+# 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.
+    """
+
+    @property
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert the model to a dictionary.
+
+        Note: Using mode="json" to handle datetime serialization.
+        Tested in tests/test_common.test_sv_base_model_json_conversion
+        """
+        return self.model_dump(mode="json")
+
+    @property
+    def to_json(self) -> str:
+        return self.model_dump_json()
+
+
+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
+    """
+
+    # Decode base64
+    combined = base64.b64decode(encrypted_value)
+
+    # 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/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,195 @@
+# 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,
+)
+
+account: Account = Account(
+    workspace_id=os.getenv("SUPERVAIZE_WORKSPACE_ID"),  # From supervaize.com
+    api_key=os.getenv("SUPERVAIZE_API_KEY"),  # From supervaize
+    api_url=os.getenv("SUPERVAIZE_API_URL"),  # From supervaize
+)
+
+# Define the supervaizer server capabilities
+sv_server: Server = Server(
+    agents=[agent],
+    a2a_endpoints=True,  # Enable A2A endpoints
+    acp_endpoints=True,  # Enable ACP endpoints
+    supervisor_account=account,  # Account of the supervisor from Supervaize
+)
+
+
+if __name__ == "__main__":
+    # Start the supervaize server
+    sv_server.launch(log_level="DEBUG")