Rename old router to legacy_base_router (#2048)

Co-authored-by: Suchintan Singh <suchintansingh@gmail.com>

skyvern/schemas/runs.py

@@ -9,12 +9,12 @@ from skyvern.utils.url_validators import validate_url
 
 
 class ProxyLocation(StrEnum):
+    RESIDENTIAL = "RESIDENTIAL"
     US_CA = "US-CA"
     US_NY = "US-NY"
     US_TX = "US-TX"
     US_FL = "US-FL"
     US_WA = "US-WA"
-    RESIDENTIAL = "RESIDENTIAL"
     RESIDENTIAL_ES = "RESIDENTIAL_ES"
     RESIDENTIAL_IE = "RESIDENTIAL_IE"
     RESIDENTIAL_GB = "RESIDENTIAL_GB"
@@ -113,23 +113,56 @@ class RunStatus(StrEnum):
 
 
 class TaskRunRequest(BaseModel):
-    prompt: str
-    url: str | None = None
-    title: str | None = None
-    engine: RunEngine = RunEngine.skyvern_v2
-    proxy_location: ProxyLocation | None = None
-    data_extraction_schema: dict | list | str | None = None
-    error_code_mapping: dict[str, str] | None = None
-    max_steps: int | None = None
-    webhook_url: str | None = None
-    totp_identifier: str | None = None
-    totp_url: str | None = None
-    browser_session_id: str | None = None
-    publish_workflow: bool = False
+    prompt: str = Field(description="The goal or task description for Skyvern to accomplish")
+    url: str | None = Field(
+        default=None,
+        description="The starting URL for the task. If not provided, Skyvern will attempt to determine an appropriate URL",
+    )
+    title: str | None = Field(default=None, description="Optional title for the task")
+    engine: RunEngine = Field(
+        default=RunEngine.skyvern_v2, description="The Skyvern engine version to use for this task"
+    )
+    proxy_location: ProxyLocation = Field(
+        default=ProxyLocation.RESIDENTIAL, description="Geographic Proxy location to route the browser traffic through"
+    )
+    data_extraction_schema: dict | list | str | None = Field(
+        default=None, description="Schema defining what data should be extracted from the webpage"
+    )
+    error_code_mapping: dict[str, str] | None = Field(
+        default=None, description="Custom mapping of error codes to error messages if Skyvern encounters an error"
+    )
+    max_steps: int | None = Field(
+        default=None, description="Maximum number of steps the task can take before timing out"
+    )
+    webhook_url: str | None = Field(
+        default=None, description="URL to send task status updates to after a run is finished"
+    )
+    totp_identifier: str | None = Field(
+        default=None,
+        description="Identifier for TOTP (Time-based One-Time Password) authentication if codes are being pushed to Skyvern",
+    )
+    totp_url: str | None = Field(
+        default=None,
+        description="URL for TOTP authentication setup if Skyvern should be polling endpoint for 2FA codes",
+    )
+    browser_session_id: str | None = Field(
+        default=None,
+        description="ID of an existing browser session to reuse, having it continue from the current screen state",
+    )
+    publish_workflow: bool = Field(default=False, description="Whether to publish this task as a reusable workflow. ")
 
     @field_validator("url", "webhook_url", "totp_url")
     @classmethod
     def validate_urls(cls, url: str | None) -> str | None:
+        """
+        Validates that URLs provided to Skyvern are properly formatted.
+
+        Args:
+            url: The URL for Skyvern to validate
+
+        Returns:
+            The validated URL or None if no URL was provided
+        """
         if url is None:
             return None
 
@@ -137,13 +170,27 @@ class TaskRunRequest(BaseModel):
 
 
 class WorkflowRunRequest(BaseModel):
-    title: str | None = None
-    parameters: dict[str, Any] | None = None
-    proxy_location: ProxyLocation | None = None
-    webhook_url: str | None = None
-    totp_url: str | None = None
-    totp_identifier: str | None = None
-    browser_session_id: str | None = None
+    workflow_id: str = Field(description="ID of the workflow to run")
+    title: str | None = Field(default=None, description="Optional title for this workflow run")
+    parameters: dict[str, Any] = Field(default={}, description="Parameters to pass to the workflow")
+    proxy_location: ProxyLocation = Field(
+        default=ProxyLocation.RESIDENTIAL, description="Location of proxy to use for this workflow run"
+    )
+    webhook_url: str | None = Field(
+        default=None, description="URL to send workflow status updates to after a run is finished"
+    )
+    totp_url: str | None = Field(
+        default=None,
+        description="URL for TOTP authentication setup if Skyvern should be polling endpoint for 2FA codes",
+    )
+    totp_identifier: str | None = Field(
+        default=None,
+        description="Identifier for TOTP (Time-based One-Time Password) authentication if codes are being pushed to Skyvern",
+    )
+    browser_session_id: str | None = Field(
+        default=None,
+        description="ID of an existing browser session to reuse, having it continue from the current screen state",
+    )
 
     @field_validator("webhook_url", "totp_url")
     @classmethod
@@ -154,22 +201,30 @@ class WorkflowRunRequest(BaseModel):
 
 
 class BaseRunResponse(BaseModel):
-    run_id: str
-    status: RunStatus
-    output: dict | list | str | None = None
-    failure_reason: str | None = None
-    created_at: datetime
-    modified_at: datetime
+    run_id: str = Field(description="Unique identifier for this run")
+    status: RunStatus = Field(description="Current status of the run")
+    output: dict | list | str | None = Field(
+        default=None, description="Output data from the run, if any. Format depends on the schema in the input"
+    )
+    failure_reason: str | None = Field(default=None, description="Reason for failure if the run failed")
+    created_at: datetime = Field(description="Timestamp when this run was created")
+    modified_at: datetime = Field(description="Timestamp when this run was last modified")
 
 
 class TaskRunResponse(BaseRunResponse):
-    run_type: Literal[RunType.task_v1, RunType.task_v2]
-    run_request: TaskRunRequest | None = None
+    run_type: Literal[RunType.task_v1, RunType.task_v2] = Field(
+        description="Type of task run - either task_v1 or task_v2"
+    )
+    run_request: TaskRunRequest | None = Field(
+        default=None, description="The original request parameters used to start this task run"
+    )
 
 
 class WorkflowRunResponse(BaseRunResponse):
-    run_type: Literal[RunType.workflow_run]
-    run_request: WorkflowRunRequest | None = None
+    run_type: Literal[RunType.workflow_run] = Field(description="Type of run - always workflow_run for workflow runs")
+    run_request: WorkflowRunRequest | None = Field(
+        default=None, description="The original request parameters used to start this workflow run"
+    )
 
 
 RunResponse = Annotated[Union[TaskRunResponse, WorkflowRunResponse], Field(discriminator="run_type")]