supervaizer 0.9.6__py3-none-any.whl

supervaizer/__init__.py

@@ -0,0 +1,88 @@
+# 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 supervaizer import protocol
+from supervaizer.account import Account
+from supervaizer.agent import (
+    Agent,
+    AgentCustomMethodParams,
+    AgentMethod,
+    AgentMethodParams,
+    AgentMethods,
+)
+from supervaizer.case import Case, CaseNodeUpdate, CaseNoteType, Cases
+from supervaizer.common import ApiError, ApiResult, ApiSuccess
+from supervaizer.event import (
+    AgentRegisterEvent,
+    CaseStartEvent,
+    CaseUpdateEvent,
+    Event,
+    EventType,
+    JobFinishedEvent,
+    JobStartConfirmationEvent,
+    ServerRegisterEvent,
+)
+from supervaizer.job import Job, JobContext, JobInstructions, JobResponse, Jobs
+from supervaizer.lifecycle import EntityEvents, EntityLifecycle, EntityStatus
+from supervaizer.parameter import Parameter, ParametersSetup
+from supervaizer.server import Server
+from supervaizer.server_utils import ErrorResponse, ErrorType, create_error_response
+from supervaizer.telemetry import (
+    Telemetry,
+    TelemetryCategory,
+    TelemetrySeverity,
+    TelemetryType,
+)
+
+__all__ = [
+    "Account",
+    "Agent",
+    "AgentCustomMethodParams",
+    "AgentMethod",
+    "AgentMethodParams",
+    "AgentMethods",
+    "AgentRegisterEvent",
+    "ApiError",
+    "ApiResult",
+    "ApiSuccess",
+    "Case",
+    "CaseNodeUpdate",
+    "CaseNoteType",
+    "Cases",
+    "CaseStartEvent",
+    "CaseUpdateEvent",
+    "create_error_response",
+    "EntityEvents",
+    "EntityEvents",
+    "EntityLifecycle",
+    "EntityLifecycle",
+    "EntityStatus",
+    "EntityStatus",
+    "ErrorResponse",
+    "ErrorType",
+    "Event",
+    "EventType",
+    "Job",
+    "JobContext",
+    "JobFinishedEvent",
+    "JobInstructions",
+    "JobResponse",
+    "Jobs",
+    "JobStartConfirmationEvent",
+    "Parameter",
+    "ParametersSetup",
+    "protocol",
+    "Server",
+    "ServerRegisterEvent",
+    "Telemetry",
+    "TelemetryCategory",
+    "TelemetrySeverity",
+    "TelemetryType",
+]
+
+# Rebuild models to resolve forward references after all imports are done
+Case.model_rebuild()

supervaizer/__version__.py

@@ -0,0 +1,10 @@
+# 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/.
+
+
+VERSION = "0.9.6"
+API_VERSION = "v1"
+TELEMETRY_VERSION = "v1"

supervaizer/account.py

@@ -0,0 +1,304 @@
+# 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 typing import TYPE_CHECKING, Any, ClassVar, Dict, Optional, Union
+
+import httpx
+from pydantic import Field
+
+from supervaizer.__version__ import VERSION
+from supervaizer.common import ApiError, ApiResult, ApiSuccess, SvBaseModel
+from supervaizer.telemetry import Telemetry
+
+if TYPE_CHECKING:
+    from supervaizer.agent import Agent
+    from supervaizer.case import Case, CaseNodeUpdate
+    from supervaizer.event import Event
+    from supervaizer.job import Job
+    from supervaizer.server import Server
+
+
+class AccountAbstract(SvBaseModel):
+    """
+    Account model for the Supervaize Control API.
+
+    This represents an account that can be used to authenticate and communicate
+    with the Supervaize SaaS API. Account parameters are provided by Supervaize.com.
+    Create an account at [https://supervaize.com/](https://supervaize.com/)
+
+    The account ID is generated by Supervaize.com. The account API key is provided
+    by Supervaize.com and is used to authenticate requests to the Supervaize Control API.
+    The API URL is provided by Supervaize.com and is the URL of the Supervaize SaaS API.
+
+    The account provides methods for registering servers and agents, sending events,
+    and communicating with the Supervaize platform.
+
+
+
+    Attributes:
+        workspace_id (str): The workspace ID provided by Supervaize.com
+        api_key (str): The API key provided by Supervaize.com for authentication
+        api_url (str): The URL of the Supervaize SaaS API provided by Supervaize.com
+    """
+
+    supervaizer_VERSION: ClassVar[str] = VERSION
+    workspace_id: str = Field(description="The workspace ID provided by Supervaize.com")
+    api_key: str = Field(
+        description="The API key provided by Supervaize.com for authentication"
+    )
+    api_url: str = Field(
+        description="The URL of the Supervaize SaaS API provided by Supervaize.com"
+    )
+
+    model_config = {
+        "reference_group": "Core",
+        "json_schema_extra": {
+            "examples": [
+                {
+                    "workspace_id": "ws_1234567890abcdef",
+                    "api_key": "sk_1234567890abcdef",
+                    "api_url": "https://api.supervaize.com",
+                }
+            ]
+        },
+    }
+
+
+class Account(AccountAbstract):
+    # URL patterns dictionary
+    _URL_PATTERNS = {
+        "team": "{api_url}/w/{workspace_id}",
+        "event": "{api_url}/w/{workspace_id}/api/v1/ctrl-events/",
+        "agent_by_id": "{api_url}/w/{workspace_id}/api/v1/agents/{agent_id}",
+        "agent_by_slug": "{api_url}/w/{workspace_id}/api/v1/agents/by-slug/{agent_slug}",
+        "telemetry": "{api_url}/{telemetry_version}/telemetry",
+    }
+
+    def __init__(self, **kwargs: Any) -> None:
+        """Account parameters are provided by Supervaize.com.
+        The account ID is generated by Supervaize.com. The account API key is provided by Supervaize.com and is used
+        to authenticate requests to the Supervaize Control API.
+        The API URL is provided by Supervaize.com and is the URL of the Supervaize
+        SaaS API.
+
+        Raises:
+            ValueError: If the account ID does not match the account name
+
+        Tested in tests/test_account.py
+        """
+        super().__init__(**kwargs)
+
+    @property
+    def api_url_w_v1(self) -> str:
+        """URL for the Supervaize Control API.
+        Tested in tests/test_account.py
+        """
+        return f"{self.api_url}/w/{self.workspace_id}/api/v1"
+
+    @property
+    def api_headers(self) -> Dict[str, str]:
+        """Headers for the Supervaize Control API.
+        Tested in tests/test_account.py
+        """
+        return {
+            "Authorization": f"Api-Key {self.api_key}",
+            "accept": "application/json",
+            "workspace": self.workspace_id,
+        }
+
+    @property
+    def api_url_team(self) -> str:
+        """URL for the Supervaize workspace team."""
+        return self.get_url("team")
+
+    @property
+    def url_event(self) -> str:
+        """URL for the Supervaize Control API.
+        Tested in tests/test_account.py
+        """
+        return f"{self.api_url_w_v1}/ctrl-events/"
+
+    def get_url(self, pattern_name: str, **kwargs: Any) -> str:
+        """Generate a URL using the predefined patterns.
+
+        Args:
+            pattern_name (str): The name of the URL pattern to use
+            **kwargs: Additional parameters for URL formatting
+
+        Returns:
+            str: The formatted URL
+
+        Raises:
+            KeyError: If the pattern_name is not found in _URL_PATTERNS
+        """
+        if pattern_name not in self._URL_PATTERNS:
+            raise KeyError(f"URL pattern '{pattern_name}' not found")
+
+        pattern = self._URL_PATTERNS[pattern_name]
+
+        # Default values from the account
+        url_params = {
+            "api_url": self.api_url,
+            "workspace_id": self.workspace_id,
+            "telemetry_version": "v1",  # Default telemetry version
+        }
+
+        # Override with any provided kwargs
+        url_params.update(kwargs)
+
+        return pattern.format(**url_params)
+
+    def send_event(
+        self,
+        sender: Union["Agent", "Job", "Server", "Case", "CaseNodeUpdate"],
+        event: "Event",
+    ) -> ApiResult:
+        """Send an event to the Supervaize SaaS API.
+
+        Args:
+            sender (Union[Agent, Server, Case, CaseNodeUpdate]): The sender of the event
+            event (Event): The event to be sent
+
+        Returns:
+            ApiResult: ApiSuccess with response details if successful,
+        Raises:
+            Request exception if the request fails.
+        """
+        # Import here to avoid circular imports
+        from supervaizer.account_service import send_event as service_send_event
+
+        return service_send_event(self, sender, event)
+
+    def register_server(self, server: "Server") -> ApiResult:
+        """Register a server with the Supervaize Control API.
+
+        Args:
+            server (Server): The server to register.
+
+        Returns:
+            ApiResult: ApiSuccess with response details if successful,
+                      ApiError with error details if request fails
+
+        Side effects:
+            - Sends a ServerRegisterEvent to the Supervaize Control API
+        """
+        # Import here to avoid circular imports
+        from supervaizer.event import ServerRegisterEvent
+
+        event = ServerRegisterEvent(server=server, account=self)
+        return self.send_event(sender=server, event=event)
+
+    def _create_api_result(
+        self,
+        success: bool,
+        message: str,
+        detail: Any = None,
+        url: str = "",
+        exception: Optional[Exception] = None,
+    ) -> ApiResult:
+        if success:
+            return ApiSuccess(message=message, detail=detail)
+        return ApiError(message=message, url=url, payload=None, exception=exception)
+
+    def get_agent_by(
+        self, agent_id: str | None = None, agent_slug: str | None = None
+    ) -> ApiSuccess | ApiError:
+        """Get an agent from the Supervaize Control API.
+
+        Args:
+            agent_id (str): The ID of the agent to get.
+            agent_slut (str): The name of the agent to get. (unique per workspace)
+
+        Returns:
+            ApiResult: ApiSuccess with response details if successful,ApiError with error details if request fails
+
+        """
+        url = ""
+        if agent_id:
+            url = f"{self.api_url_w_v1}/agents/{agent_id}"
+        elif agent_slug:
+            url = f"{self.api_url_w_v1}/agents/by-slug/{agent_slug}"
+        else:
+            raise ValueError("No agent ID or slug provided")
+
+        headers = self.api_headers
+
+        try:
+            response = httpx.get(url, headers=headers, follow_redirects=True)
+            response.raise_for_status()
+            return ApiSuccess(
+                message=f"GET Agent <{agent_slug or agent_id}>",
+                detail=response.json(),
+            )
+        except httpx.HTTPError as e:
+            return ApiError(
+                message=f"Error GET Agent <{agent_slug or agent_id}>",
+                url=url,
+                payload=None,
+                exception=e,
+            )
+
+    def register_agent(self, agent: "Agent", polling: bool = True) -> ApiResult:
+        """Send a registration event to the Supervaize Control API.
+            This will be used for polling, when the agent is registered without a server.
+        Args:
+            agent (Agent): The agent sending the registration event
+            polling (bool): If server is not defined, polling will be used.
+
+        Returns:
+            ApiResult: ApiSuccess with response details if successful,
+                      ApiError with error details if request fails
+        """
+        # Import here to avoid circular imports
+        from supervaizer.event import AgentRegisterEvent
+
+        event = AgentRegisterEvent(agent=agent, account=self, polling=polling)
+        return self.send_event(agent, event)
+
+    def send_start_case(self, case: "Case") -> ApiResult:
+        # Import here to avoid circular imports
+        from supervaizer.event import CaseStartEvent
+
+        event = CaseStartEvent(case=case, account=self)
+        return self.send_event(case, event)
+
+    def send_update_case(self, case: "Case", update: "CaseNodeUpdate") -> ApiResult:
+        # Import here to avoid circular imports
+        from supervaizer.event import CaseUpdateEvent
+
+        event = CaseUpdateEvent(case=case, update=update, account=self)
+        return self.send_event(update, event)
+
+    def send_telemetry(self, telemetry: Telemetry) -> ApiResult:
+        """Send telemetry data to the Supervaize Control API.
+
+        Args:
+            telemetry (Telemetry): The telemetry object to be sent
+
+        Returns:
+            ApiResult: ApiSuccess with response details if successful,
+                      ApiError with error details if request fails
+        """
+        url = self.get_url("telemetry")
+        headers = self.api_headers
+        payload = {"workspace_id": self.workspace_id} | telemetry.payload
+        result: ApiSuccess | ApiError
+        try:
+            response = httpx.post(url, headers=headers, json=payload)
+            response.raise_for_status()
+            result = ApiSuccess(
+                message=f"Telemetry sent {telemetry.type.name}", detail=response.text
+            )
+        except httpx.HTTPError as e:
+            result = ApiError(
+                message=f"Error sending telemetry {telemetry.type.name}",
+                url=url,
+                payload=payload,
+                exception=e,
+            )
+
+        return result

supervaizer/account_service.py

@@ -0,0 +1,87 @@
+# 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 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 logging
+from typing import TYPE_CHECKING, Union
+
+import httpx
+
+from supervaizer.common import ApiError, ApiResult, ApiSuccess, log
+
+logger = logging.getLogger("httpx")
+# Enable httpx debug logging (optional - uncomment for transport-level debugging)
+logger.setLevel(logging.DEBUG)
+
+if TYPE_CHECKING:
+    from supervaizer.account import Account
+    from supervaizer.agent import Agent
+    from supervaizer.case import Case, CaseNodeUpdate
+    from supervaizer.event import Event
+    from supervaizer.job import Job
+    from supervaizer.server import Server
+
+
+def send_event(
+    account: "Account",
+    sender: Union["Agent", "Server", "Job", "Case", "CaseNodeUpdate"],
+    event: "Event",
+) -> ApiResult:
+    """Send an event to the Supervaize SaaS API.
+
+    Args:
+        account (Account): The account used to authenticate the request
+        sender (Union[Agent, Server, Case, CaseNodeUpdate]): The sender of the event
+        event (Event): The event to be sent
+
+    Returns:
+        ApiResult: ApiSuccess with response details if successful,
+    Raises:
+        Request exception if the request fails.
+
+    Side effects:
+        - Sends an event to the Supervaize Control API
+
+        Tested in tests/test_account_service.py
+    """
+
+    headers = account.api_headers
+    payload = event.payload
+
+    # Generate curl equivalent for debugging
+
+    curl_headers = " ".join([f'-H "{k}: {v}"' for k, v in headers.items()])
+    curl_cmd = f"curl -X 'GET' '{account.url_event}'  {curl_headers}"
+
+    try:
+        response = httpx.post(account.url_event, headers=headers, json=payload)
+
+        # Log response details before raising for status
+
+        response.raise_for_status()
+        result = ApiSuccess(
+            message=f"POST Event {event.type.name} sent", detail=response.text
+        )
+
+        log.success(result.log_message)
+    except httpx.HTTPError as e:
+        # Enhanced error logging
+        log.error("[Send event] HTTP Error occurred")
+        log.warning(f"⚠️ Try to connect via curl:\n{curl_cmd}")
+
+        error_result = ApiError(
+            message=f"Error sending event {event.type.name}",
+            url=account.url_event,
+            payload=event.payload,
+            exception=e,
+        )
+        log.error(f"[Send event] Error details: {error_result.dict}")
+        log.error(error_result.log_message)
+        raise e
+    return result