supervaizer 0.9.7__py3-none-any.whl → 0.10.0__py3-none-any.whl

supervaizer/routes.py

@@ -6,6 +6,7 @@
 
 import traceback
 from functools import wraps
+from pathlib import Path
 from typing import (
     TYPE_CHECKING,
     Any,
@@ -26,11 +27,12 @@ from fastapi import (
     Depends,
     HTTPException,
     Query,
+    Request,
     Security,
     status as http_status,
 )
-from fastapi.responses import JSONResponse
-from rich import inspect
+from fastapi.responses import FileResponse, HTMLResponse, JSONResponse, Response
+from fastapi.templating import Jinja2Templates
 
 from supervaizer.agent import (
     Agent,
@@ -51,8 +53,6 @@ if TYPE_CHECKING:
 
 T = TypeVar("T")
 
-insp = inspect
-
 
 class CaseUpdateRequest(SvBaseModel):
     """Request model for updating a case with answer to a question."""
@@ -259,10 +259,13 @@ def create_default_routes(server: "Server") -> APIRouter:
         )
 
         # Update the case with the answer
-        case.update(update)
+        # case.update(update) - Redundant, receive_human_input calls update()
 
         # Transition the case from AWAITING to IN_PROGRESS
-        case.receive_human_input()
+        case.receive_human_input(update)
+
+        # TODO CALL CUSTOM HOOKS HERE - AS DEFINED IN THE AGENT CONFIGURATION
+        # TODO REDEFINE AGENT TO ADD CUSTOM HOOKS HERE
 
         log.info(
             f"[Case update] Job {job_id}, Case {case_id} - Answer processed successfully"
@@ -383,6 +386,238 @@ def create_agent_route(server: "Server", agent: Agent) -> APIRouter:
             **agent.registration_info,
         )
 
+    @router.get(
+        f"/{agent.instructions_path}",
+        summary=f"Get supervaize instructions page for agent {agent.name}",
+        description="HTML page displaying agent registration information and instructions",
+        response_class=HTMLResponse,
+        tags=tags,
+    )
+    @handle_route_errors()
+    async def supervaize_instructions(
+        request: Request, agent: Agent = Depends(get_agent)
+    ) -> Response:
+        """Serve the supervaize instructions HTML page for this agent."""
+        log.info(
+            f"📥  GET /{agent.instructions_path} [Supervaize Instructions] for agent{agent.name}"
+        )
+
+        registration_info = agent.registration_info
+
+        # Convert instructions_path string to Path object
+        instructions_path = Path(agent.instructions_path)
+
+        # Check if file exists - if not, return empty HTML
+        if not instructions_path.exists() or not instructions_path.is_file():
+            return HTMLResponse(content="", status_code=200)
+
+        # Serve the file (check if it's a Jinja2 template or static HTML)
+        with open(instructions_path, "r", encoding="utf-8") as f:
+            content = f.read()
+            # Simple check: if it contains Jinja2 syntax, render as template
+            if "{{" in content or "{%" in content:
+                # Render as Jinja2 template
+                custom_templates = Jinja2Templates(
+                    directory=str(instructions_path.parent)
+                )
+                return custom_templates.TemplateResponse(
+                    instructions_path.name,
+                    {
+                        "request": request,
+                        "registration_info": registration_info,
+                    },
+                )
+            else:
+                # Serve as static HTML file
+                return FileResponse(
+                    str(instructions_path),
+                    media_type="text/html",
+                )
+
+    @router.post(
+        "/validate-agent-parameters",
+        summary=f"Validate agent parameters for agent: {agent.name}",
+        description="Validate agent configuration parameters (secrets, API keys, etc.) before starting a job",
+        response_model=Dict[str, Any],
+        responses={
+            http_status.HTTP_200_OK: {"model": Dict[str, Any]},
+            http_status.HTTP_400_BAD_REQUEST: {"model": Dict[str, Any]},
+            http_status.HTTP_500_INTERNAL_SERVER_ERROR: {"model": ErrorResponse},
+        },
+        dependencies=[Security(server.verify_api_key)],
+    )
+    @handle_route_errors()
+    async def validate_agent_parameters(
+        body_params: Any = Body(...),
+        agent: Agent = Depends(get_agent),
+    ) -> Dict[str, Any]:
+        """Validate agent parameters for this agent"""
+        log.info(
+            f"📥 POST /validate-agent-parameters [Validate agent parameters] {agent.name}"
+        )
+
+        if not agent.parameters_setup:
+            result = {
+                "valid": True,
+                "message": "Agent has no parameter setup defined",
+                "errors": [],
+                "invalid_parameters": {},
+            }
+            log.info(f"📤 Agent {agent.name}: No parameter setup defined → {result}")
+            return result
+
+        if body_params is None:
+            body_params = {}
+
+        encrypted_agent_parameters = body_params.get("encrypted_agent_parameters")
+
+        agent_parameters: Dict[str, Any] = {}
+        if encrypted_agent_parameters:
+            # Basic debug trace
+            log.info(
+                f"📥 Received encrypted_agent_parameters, length: {len(encrypted_agent_parameters)}"
+            )
+
+            try:
+                import json
+
+                from supervaizer.common import decrypt_value
+
+                agent_parameters_str = decrypt_value(
+                    encrypted_agent_parameters, server.private_key
+                )
+                agent_parameters = (
+                    json.loads(agent_parameters_str) if agent_parameters_str else {}
+                )
+
+                # Debug: Log the parsed data type and structure
+                log.info(f"🔍 Parsed agent_parameters type: {type(agent_parameters)}")
+                if isinstance(agent_parameters, list):
+                    log.info(
+                        f"🔍 Converting list to dict with {len(agent_parameters)} items"
+                    )
+                    # Convert list to dict if needed (common when frontend sends array)
+                    agent_parameters = {
+                        f"param_{i}": param for i, param in enumerate(agent_parameters)
+                    }
+                elif isinstance(agent_parameters, dict):
+                    log.info(
+                        f"🔍 Agent parameters keys: {list(agent_parameters.keys())}"
+                    )
+                else:
+                    log.warning(
+                        f"🔍 Unexpected type: {type(agent_parameters)}, converting to empty dict"
+                    )
+                    agent_parameters = {}
+
+            except Exception as e:
+                log.error(f"❌ Decryption failed: {type(e).__name__}: {str(e)}")
+                result = {
+                    "valid": False,
+                    "message": f"Failed to decrypt agent parameters: {str(e)}",
+                    "errors": [f"Decryption failed: {str(e)}"],
+                    "invalid_parameters": {
+                        "encrypted_agent_parameters": f"Decryption failed: {str(e)}"
+                    },
+                }
+                log.info(f"📤 Agent {agent.name}: Decryption failed → {result}")
+                return result
+
+        # Log the incoming request details
+        log.info(
+            f"🔍 Agent {agent.name}: Incoming request - encrypted_params: {bool(encrypted_agent_parameters)}, parsed_params: {agent_parameters}"
+        )
+
+        # Validate agent parameters
+        validation_result = agent.parameters_setup.validate_parameters(agent_parameters)
+
+        result = {
+            "valid": validation_result["valid"],
+            "message": "Agent parameters validated successfully"
+            if validation_result["valid"]
+            else "Agent parameter validation failed",
+            "errors": validation_result["errors"],
+            "invalid_parameters": validation_result["invalid_parameters"],
+        }
+
+        log.info(f"📤 Agent {agent.name}: Validation result → {result}")
+        return result
+
+    @router.post(
+        "/validate-method-fields",
+        summary=f"Validate method fields for agent: {agent.name}",
+        description="Validate job input fields against the method's field definitions before starting a job",
+        response_model=Dict[str, Any],
+        responses={
+            http_status.HTTP_200_OK: {"model": Dict[str, Any]},
+            http_status.HTTP_400_BAD_REQUEST: {"model": Dict[str, Any]},
+            http_status.HTTP_500_INTERNAL_SERVER_ERROR: {"model": ErrorResponse},
+        },
+        dependencies=[Security(server.verify_api_key)],
+    )
+    @handle_route_errors()
+    async def validate_method_fields(
+        body_params: Any = Body(...),
+        agent: Agent = Depends(get_agent),
+    ) -> Dict[str, Any]:
+        """Validate method fields for this agent"""
+        log.info(
+            f"📥 POST /validate-method-fields [Validate method fields] {agent.name}"
+        )
+
+        if body_params is None:
+            body_params = {}
+
+        method_name = body_params.get("method_name", "job_start")
+        job_fields = body_params.get("job_fields", {})
+
+        # Log the incoming request details
+        log.info(
+            f"🔍 Agent {agent.name}: Incoming request - method: {method_name}, fields: {job_fields}"
+        )
+
+        # Get the method to validate against
+        if not agent.methods:
+            result = {
+                "valid": False,
+                "message": "Agent has no methods defined",
+                "errors": ["Agent has no methods defined"],
+                "invalid_fields": {},
+            }
+            log.info(f"📤 Agent {agent.name}: No methods defined → {result}")
+            return result
+
+        if method_name == "job_start":
+            method = agent.methods.job_start
+        elif agent.methods.custom and method_name in agent.methods.custom:
+            method = agent.methods.custom[method_name]
+        else:
+            result = {
+                "valid": False,
+                "message": f"Method '{method_name}' not found",
+                "errors": [f"Method '{method_name}' not found"],
+                "invalid_fields": {},
+            }
+            log.info(
+                f"📤 Agent {agent.name}: Method '{method_name}' not found → {result}"
+            )
+            return result
+
+        # Validate method fields
+        validation_result = method.validate_method_fields(job_fields)
+
+        result = {
+            "valid": validation_result["valid"],
+            "message": validation_result["message"],
+            "errors": validation_result["errors"],
+            "invalid_fields": validation_result["invalid_fields"],
+        }
+
+        log.info(
+            f"📤 Agent {agent.name}: Method '{method_name}' validation result → {result}"
+        )
+        return result
+
     if not agent.methods:
         raise ValueError(f"Agent {agent.name} has no methods defined")
 
@@ -400,6 +635,7 @@ def create_agent_route(server: "Server", agent: Agent) -> APIRouter:
         description=f"{agent.methods.job_start.description}",
         responses={
             http_status.HTTP_202_ACCEPTED: {"model": Job},
+            http_status.HTTP_400_BAD_REQUEST: {"model": Dict[str, Any]},
             http_status.HTTP_409_CONFLICT: {"model": ErrorResponse},
             http_status.HTTP_500_INTERNAL_SERVER_ERROR: {"model": ErrorResponse},
         },
@@ -415,13 +651,19 @@ def create_agent_route(server: "Server", agent: Agent) -> APIRouter:
     ) -> Union[Job, JSONResponse]:
         """Start a new job for this agent"""
         log.info(f"📥 POST /jobs [Start job] {agent.name} with params {body_params}")
-        sv_context: JobContext = body_params.job_context
-        job_fields = body_params.job_fields.to_dict()
+
+        if body_params is None:
+            body_params = {}
+
+        job_context_data = body_params.get("job_context")
+        if job_context_data is None:
+            raise ValueError("job_context is required")
+
+        sv_context: JobContext = JobContext(**job_context_data)
+        job_fields = body_params.get("job_fields", {})
 
         # Get job encrypted parameters if available
-        encrypted_agent_parameters = getattr(
-            body_params, "encrypted_agent_parameters", None
-        )
+        encrypted_agent_parameters = body_params.get("encrypted_agent_parameters")
 
         # Delegate job creation and scheduling to the service
         new_job = await service_job_start(
@@ -526,7 +768,9 @@ def create_agent_route(server: "Server", agent: Agent) -> APIRouter:
         agent: Agent = Depends(get_agent),
     ) -> AgentResponse:
         log.info(f"📥  POST /stop [Stop agent] {agent.name} with params {params}")
-        result = agent.job_stop(params.get("job_context", {}))
+        # Pass job_context as 'context' parameter to match agent method expectations
+        job_context = params.get("job_context", {})
+        result = agent.job_stop({"context": job_context})
         res_info = result.registration_info if result else {}
         return AgentResponse(
             name=agent.name,
@@ -623,6 +867,7 @@ def create_agent_custom_routes(server: "Server", agent: Agent) -> APIRouter:
             response_model=JobResponse,
             responses={
                 http_status.HTTP_202_ACCEPTED: {"model": JobResponse},
+                http_status.HTTP_400_BAD_REQUEST: {"model": Dict[str, Any]},
                 http_status.HTTP_405_METHOD_NOT_ALLOWED: {"model": ErrorResponse},
             },
             dependencies=[Security(server.verify_api_key)],
@@ -637,6 +882,11 @@ def create_agent_custom_routes(server: "Server", agent: Agent) -> APIRouter:
             log.info(
                 f"📥 POST /custom/{method_name} [custom job] {agent.name} with params {body_params}"
             )
+            log.info(f"body_params: {body_params}")
+
+            if body_params is None:
+                raise ValueError("body_params cannot be None")
+
             sv_context: JobContext = body_params.job_context
             job_fields = body_params.job_fields.to_dict()
 

supervaizer/server.py

@@ -38,7 +38,6 @@ from supervaizer.common import (
 )
 from supervaizer.instructions import display_instructions
 from supervaizer.protocol.a2a import create_routes as create_a2a_routes
-from supervaizer.protocol.acp import create_routes as create_acp_routes
 from supervaizer.routes import (
     create_agents_routes,
     create_default_routes,
@@ -82,6 +81,9 @@ def save_server_info_to_storage(server_instance: "Server") -> None:
                         "name": agent.name,
                         "description": agent.description,
                         "version": agent.version,
+                        "api_path": agent.path,
+                        "slug": agent.slug,
+                        "instructions_path": agent.instructions_path,
                     }
                 )
 
@@ -166,9 +168,6 @@ class ServerAbstract(SvBaseModel):
     a2a_endpoints: bool = Field(
         default=True, description="Whether to enable A2A endpoints"
     )
-    acp_endpoints: bool = Field(
-        default=True, description="Whether to enable ACP endpoints"
-    )
     private_key: RSAPrivateKey = Field(
         description="RSA private key for secret parameters encryption - Used in server-to-agent communication - Not needed by user"
     )
@@ -206,7 +205,6 @@ class ServerAbstract(SvBaseModel):
                     "debug": False,
                     "reload": False,
                     "a2a_endpoints": True,
-                    "acp_endpoints": True,
                 },
             ]
         },
@@ -237,7 +235,6 @@ class Server(ServerAbstract):
         agents: List[Agent],
         supervisor_account: Optional[Account] = None,
         a2a_endpoints: bool = True,
-        acp_endpoints: bool = True,
         admin_interface: bool = True,
         scheme: str = "http",
         environment: str = os.getenv("SUPERVAIZER_ENVIRONMENT", "dev"),
@@ -259,7 +256,6 @@ class Server(ServerAbstract):
             agents: List of agents to register with the server
             supervisor_account: Account of the supervisor
             a2a_endpoints: Whether to enable A2A endpoints
-            acp_endpoints: Whether to enable ACP endpoints
             admin_interface: Whether to enable admin interface
             scheme: URL scheme (http or https)
             environment: Environment name (e.g., dev, staging, prod)
@@ -350,7 +346,6 @@ class Server(ServerAbstract):
             reload=reload,
             supervisor_account=supervisor_account,
             a2a_endpoints=a2a_endpoints,
-            acp_endpoints=acp_endpoints,
             private_key=private_key,
             public_key=public_key,
             public_url=public_url,
@@ -371,9 +366,6 @@ class Server(ServerAbstract):
         if self.a2a_endpoints:
             log.info("[Server launch] 📢 Deploy A2A routes  ")
             self.app.include_router(create_a2a_routes(self))
-        if self.acp_endpoints:
-            log.info("[Server launch] 📢 Deploy ACP routes")
-            self.app.include_router(create_acp_routes(self))
 
         # Deploy admin routes if API key is available
         if self.api_key and admin_interface:
@@ -519,6 +511,8 @@ class Server(ServerAbstract):
             server_registration_result: ApiResult = (
                 self.supervisor_account.register_server(server=self)
             )
+            # log.debug(f"[Server launch] Server registration result: {server_registration_result}")
+            # inspect(server_registration_result)
             assert isinstance(
                 server_registration_result, ApiSuccess
             )  # If ApiError, exception should have been raised before

supervaizer/utils/__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/.
+
+
+from supervaizer.utils.version_check import (
+    check_is_latest_version,
+    get_latest_version,
+)
+
+__all__ = [
+    "check_is_latest_version",
+    "get_latest_version",
+]

supervaizer/utils/version_check.py

@@ -0,0 +1,56 @@
+# 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 httpx
+
+try:
+    from packaging import version
+except ImportError:
+    version = None
+
+from supervaizer import __version__
+
+
+async def get_latest_version() -> str | None:
+    """
+    Retrieve the latest version number of supervaizer from PyPI.
+
+    Returns:
+        The latest version string (e.g., "0.9.8") if successful, None otherwise.
+    """
+    try:
+        async with httpx.AsyncClient(timeout=10.0) as client:
+            response = await client.get("https://pypi.org/pypi/supervaizer/json")
+            response.raise_for_status()
+            data = response.json()
+            return data.get("info", {}).get("version")
+    except Exception:
+        return None
+
+
+async def check_is_latest_version() -> tuple[bool, str | None]:
+    """
+    Check if the currently running supervaizer version is the latest available on PyPI.
+
+    Returns:
+        A tuple of (is_latest: bool, latest_version: str | None).
+        - is_latest: True if current version is latest or if check failed
+        - latest_version: The latest version string if available, None otherwise
+    """
+    current_version = __version__.VERSION
+    latest_version = await get_latest_version()
+
+    if latest_version is None:
+        return True, None
+
+    # Compare versions using packaging.version for proper semantic version comparison
+    if version is not None:
+        is_latest = version.parse(current_version) >= version.parse(latest_version)
+    else:
+        # Fallback to simple string comparison if packaging is not available
+        is_latest = current_version >= latest_version
+    return is_latest, latest_version