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

supervaizer/agent.py

@@ -28,6 +28,7 @@ from supervaizer.job import Job, JobContext, JobResponse
 from supervaizer.job_service import service_job_finished
 from supervaizer.lifecycle import EntityStatus
 from supervaizer.parameter import ParametersSetup
+from supervaizer.case import CaseNodes
 
 if TYPE_CHECKING:
     from supervaizer.server import Server
@@ -83,8 +84,7 @@ class AgentMethodField(BaseModel):
     description: str | None = Field(
         default=None, description="Description of the field - displayed in the UI"
     )
-    # TODO: confirm the structure of choices (list[str] or list[tuple(str)) - How do we integrate it in Supervaize
-    choices: list[str] | None = Field(
+    choices: list[tuple[str, str]] | list[str] | None = Field(
         default=None, description="For choice fields, list of [value, label] pairs"
     )
 
@@ -211,6 +211,11 @@ class AgentMethodAbstract(BaseModel):
         },
     }
 
+    nodes: CaseNodes | None = Field(
+        default=None,
+        description="The definition of the Case Nodes (=steps) for this method",
+    )
+
 
 class AgentMethod(AgentMethodAbstract):
     @property
@@ -244,32 +249,151 @@ class AgentMethod(AgentMethodAbstract):
             return type("EmptyFieldsModel", (BaseModel,), {"to_dict": lambda self: {}})
 
         field_annotations = {}
-        field_defaults: Dict[str, None] = {}
         for field in self.fields:
             field_name = field.name
             field_type = field.type
-            is_required = field.required
+
+            # Convert Python types to proper typing annotations
+            if field_type is str:
+                annotation_type: type = str
+            elif field_type is int:
+                annotation_type = int
+            elif field_type is bool:
+                annotation_type = bool
+            elif field_type is list:
+                annotation_type = list
+            elif field_type is dict:
+                annotation_type = dict
+            elif field_type is float:
+                annotation_type = float
+            elif hasattr(field_type, "__origin__") and field_type.__origin__ is list:
+                # Handle generic list types like list[str]
+                annotation_type = list
+            elif hasattr(field_type, "__origin__") and field_type.__origin__ is dict:
+                # Handle generic dict types like dict[str, Any]
+                annotation_type = dict
+            else:
+                # Default to Any for unknown types
+                annotation_type = Any
+
+            # Make field optional if not required
             field_annotations[field_name] = (
-                field_type if is_required else Optional[field_type]
+                annotation_type if field.required else Optional[annotation_type]
             )
-            if not is_required:
-                field_defaults[field_name] = None
 
-        def to_dict(self: BaseModel) -> Dict[str, Any]:
+        # Create the dynamic model with proper module information
+        model_dict = {
+            "__module__": "supervaizer.agent",
+            "__annotations__": field_annotations,
+            "to_dict": lambda self: {
+                k: getattr(self, k)
+                for k in field_annotations.keys()
+                if hasattr(self, k)
+            },
+        }
+
+        return type("DynamicFieldsModel", (BaseModel,), model_dict)
+
+    def validate_method_fields(self, job_fields: Dict[str, Any]) -> Dict[str, Any]:
+        """Validate job fields against the method's field definitions.
+
+        Args:
+            job_fields: Dictionary of field names and values to validate
+
+        Returns:
+            Dictionary with validation results:
+            - "valid": bool - whether all fields are valid
+            - "errors": List[str] - list of validation error messages
+            - "invalid_fields": Dict[str, str] - field name to error message mapping
+        """
+        if self.fields is None:
             return {
-                field_name: getattr(self, field_name)
-                for field_name in self.__annotations__
+                "valid": True,
+                "message": "Method has no field definitions",
+                "errors": [],
+                "invalid_fields": {},
             }
 
-        return type(
-            "DynamicFieldsModel",
-            (BaseModel,),
-            {
-                "__annotations__": field_annotations,
-                "to_dict": to_dict,
-                **field_defaults,
-            },
-        )
+        if len(self.fields) == 0:
+            return {
+                "valid": True,
+                "message": "Method fields validated successfully",
+                "errors": [],
+                "invalid_fields": {},
+            }
+
+        errors = []
+        invalid_fields = {}
+
+        # First check for missing required fields
+        for field in self.fields:
+            if field.required and field.name not in job_fields:
+                error_msg = f"Required field '{field.name}' is missing"
+                errors.append(error_msg)
+                invalid_fields[field.name] = error_msg
+
+        # Then validate the provided fields
+        for field_name, field_value in job_fields.items():
+            # Find the field definition
+            field_def = next((f for f in self.fields if f.name == field_name), None)
+            if not field_def:
+                error_msg = f"Unknown field '{field_name}'"
+                errors.append(error_msg)
+                invalid_fields[field_name] = error_msg
+                continue
+
+            # Skip validation for None values (optional fields)
+            if field_value is None:
+                continue
+
+            # Type validation
+            expected_type = field_def.type
+            if expected_type:
+                try:
+                    # Handle special cases for type validation
+                    if expected_type is str:
+                        if not isinstance(field_value, str):
+                            error_msg = f"Field '{field_name}' must be a string, got {type(field_value).__name__}"
+                            errors.append(error_msg)
+                            invalid_fields[field_name] = error_msg
+                    elif expected_type is int:
+                        if not isinstance(field_value, int):
+                            error_msg = f"Field '{field_name}' must be an integer, got {type(field_value).__name__}"
+                            errors.append(error_msg)
+                            invalid_fields[field_name] = error_msg
+                    elif expected_type is bool:
+                        if not isinstance(field_value, bool):
+                            error_msg = f"Field '{field_name}' must be a boolean, got {type(field_value).__name__}"
+                            errors.append(error_msg)
+                            invalid_fields[field_name] = error_msg
+                    elif expected_type is list:
+                        if not isinstance(field_value, list):
+                            error_msg = f"Field '{field_name}' must be a list, got {type(field_value).__name__}"
+                            errors.append(error_msg)
+                            invalid_fields[field_name] = error_msg
+                    elif expected_type is dict:
+                        if not isinstance(field_value, dict):
+                            error_msg = f"Field '{field_name}' must be a dictionary, got {type(field_value).__name__}"
+                            errors.append(error_msg)
+                            invalid_fields[field_name] = error_msg
+                    elif expected_type is float:
+                        if not isinstance(field_value, (int, float)):
+                            error_msg = f"Field '{field_name}' must be a number, got {type(field_value).__name__}"
+                            errors.append(error_msg)
+                            invalid_fields[field_name] = error_msg
+                except Exception as e:
+                    error_msg = f"Field '{field_name}' validation failed: {str(e)}"
+                    errors.append(error_msg)
+                    invalid_fields[field_name] = error_msg
+
+        return {
+            "valid": len(errors) == 0,
+            "message": "Method fields validated successfully"
+            if len(errors) == 0
+            else "Method field validation failed",
+            "errors": errors,
+            "invalid_fields": invalid_fields,
+        }
 
     @property
     def job_model(self) -> type[AgentJobContextBase]:
@@ -301,6 +425,7 @@ class AgentMethod(AgentMethodAbstract):
             "params": self.params,
             "fields": self.fields_definitions,
             "description": self.description,
+            "nodes": self.nodes.registration_info if self.nodes else None,
         }
 
 
@@ -322,8 +447,9 @@ class AgentCustomMethodParams(AgentMethodParams):
 
 class AgentMethodsAbstract(BaseModel):
     job_start: AgentMethod
-    job_stop: AgentMethod
-    job_status: AgentMethod
+    job_stop: AgentMethod | None = None
+    job_status: AgentMethod | None = None
+    human_answer: AgentMethod | None = None
     chat: AgentMethod | None = None
     custom: dict[str, AgentMethod] | None = None
 
@@ -358,8 +484,13 @@ class AgentMethods(AgentMethodsAbstract):
     def registration_info(self) -> Dict[str, Any]:
         return {
             "job_start": self.job_start.registration_info,
-            "job_stop": self.job_stop.registration_info,
-            "job_status": self.job_status.registration_info,
+            "job_stop": self.job_stop.registration_info if self.job_stop else None,
+            "job_status": self.job_status.registration_info
+            if self.job_status
+            else None,
+            "human_answer": self.human_answer.registration_info
+            if self.human_answer
+            else None,
             "chat": self.chat.registration_info if self.chat else None,
             "custom": {
                 name: method.registration_info
@@ -457,6 +588,14 @@ class AgentAbstract(SvBaseModel):
         default=60 * 60,
         description="Maximum execution time in seconds, defaults to 1 hour",
     )
+    supervaize_instructions_template_path: Optional[str] = Field(
+        default=None,
+        description="Optional path to a custom template file for supervaize_instructions.html page",
+    )
+    instructions_path: str = Field(
+        default="supervaize_instructions.html",
+        description="Path where the supervaize instructions page is served (relative to agent path)",
+    )
 
     model_config = {
         "reference_group": "Core",
@@ -572,6 +711,7 @@ class Agent(AgentAbstract):
             "server_agent_onboarding_status": self.server_agent_onboarding_status,
             "server_encrypted_parameters": self.server_encrypted_parameters,
             "max_execution_time": self.max_execution_time,
+            "instructions_path": self.instructions_path,
         }
 
     def update_agent_from_server(self, server: "Server") -> Optional["Agent"]:
@@ -770,13 +910,13 @@ class Agent(AgentAbstract):
         return job
 
     def job_stop(self, params: Dict[str, Any] = {}) -> Any:
-        if not self.methods:
+        if not self.methods or not self.methods.job_stop:
             raise ValueError("Agent methods not defined")
         method = self.methods.job_stop.method
         return self._execute(method, params)
 
     def job_status(self, params: Dict[str, Any] = {}) -> Any:
-        if not self.methods:
+        if not self.methods or not self.methods.job_status:
             raise ValueError("Agent methods not defined")
         method = self.methods.job_status.method
         return self._execute(method, params)

supervaizer/case.py

@@ -10,9 +10,9 @@ from enum import Enum
 from typing import TYPE_CHECKING, Any, Dict, List, Optional
 
 import shortuuid
-from pydantic import ConfigDict
-from typing_extensions import deprecated
-
+from pydantic import ConfigDict, Field
+from pydantic.json_schema import SkipJsonSchema
+from typing import Callable
 from supervaizer.common import SvBaseModel, log, singleton
 from supervaizer.lifecycle import EntityEvents, EntityStatus
 from supervaizer.storage import PersistentEntityLifecycle, StorageManager
@@ -55,7 +55,6 @@ class CaseNodeUpdate(SvBaseModel):
             payload (Dict[str, Any]): Additional data for the update - when a question is requested to the user, the payload is the question
             is_final (bool): Whether this is the final update. Default to False
             index (int): Index of the node to update. This is set by Case.update()
-
             error (Optional[str]): Error message if any. Default to None
 
         When payload contains a question (supervaizer_form):
@@ -101,24 +100,32 @@ class CaseNodeUpdate(SvBaseModel):
     @property
     def registration_info(self) -> Dict[str, Any]:
         """Returns registration info for the case node update"""
+        # Serialize payload to convert type objects to strings for JSON serialization
+        serialized_payload = (
+            self.serialize_value(self.payload) if self.payload else None
+        )
         return {
             "index": self.index,
             "name": self.name,
             "error": self.error,
             "cost": self.cost,
-            "payload": self.payload,
+            "payload": serialized_payload,
             "is_final": self.is_final,
         }
 
 
-class CaseNoteType(Enum):
+class CaseNodeType(Enum):
     """
-    CaseNoteType is an enum that represents the type of a case note.
+    CaseNodeType is an enum that represents the type of a case note.
     """
 
     CHAT = "chat"
     TRIGGER = "trigger"
     NOTIFICATION = "notification"
+    STATUS_UPDATE = "status_update"
+    INTERMEDIARY_DELIVERY = "intermediary_delivery"
+    HITL = "human_in_the_loop"
+    DELIVERABLE = "deliverable"
     VALIDATION = "validation"
     DELIVERY = "delivery"
     ERROR = "error"
@@ -126,22 +133,43 @@ class CaseNoteType(Enum):
     INFO = "info"
 
 
-@deprecated("Not used")
 class CaseNode(SvBaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
     name: str
-    description: str
-    type: CaseNoteType
+    type: CaseNodeType
+    factory: SkipJsonSchema[Callable[..., CaseNodeUpdate]] = Field(
+        exclude=True, repr=False
+    )  # Exclude from JSON schema generation and representation
+    description: str | None = None
+    can_be_confirmed: bool = False  # Whether the user can decide that this node needs to be confirmed. This must be set in the job definition.
 
-    class Config:
-        arbitrary_types_allowed = True
+    def __call__(self, *args: Any, **kwargs: Any) -> CaseNodeUpdate:
+        """Make it callable directly."""
+        return self.factory(*args, **kwargs)
 
     @property
     def registration_info(self) -> Dict[str, Any]:
         """Returns registration info for the case node"""
         return {
             "name": self.name,
-            "description": self.description,
             "type": self.type.value,
+            "description": self.description,
+            "can_be_confirmed": self.can_be_confirmed,
+        }
+
+
+class CaseNodes(SvBaseModel):
+    nodes: List[CaseNode] = []
+
+    def get(self, name: str) -> CaseNode | None:
+        return next((node for node in self.nodes if node.name == name), None)
+
+    @property
+    def registration_info(self) -> Dict[str, Any]:
+        """Returns registration info for the case nodes"""
+        return {
+            "nodes": [node.registration_info for node in self.nodes],
         }
 
 
@@ -216,7 +244,11 @@ class Case(CaseAbstractModel):
         storage = StorageManager()
         storage.save_object("Case", self.to_dict)
 
-    def receive_human_input(self, **kwargs: Any) -> None:
+    def receive_human_input(
+        self, updateCaseNode: CaseNodeUpdate, **kwargs: Any
+    ) -> None:
+        # Add the update to the case (this handles index, send_update_case, and persistence)
+        self.update(updateCaseNode)
         # Transition from AWAITING to IN_PROGRESS
         from supervaizer.storage import PersistentEntityLifecycle