futurehouse-client 0.3.20.dev215__py3-none-any.whl → 0.3.20.dev266__py3-none-any.whl

futurehouse_client/clients/rest_client.py

@@ -14,6 +14,7 @@ import time
 import uuid
 from collections.abc import Collection
 from concurrent.futures import ThreadPoolExecutor, as_completed
+from http import HTTPStatus
 from pathlib import Path
 from types import ModuleType
 from typing import Any, ClassVar, cast
@@ -37,6 +38,7 @@ from httpx import (
 from ldp.agent import AgentConfig
 from requests.exceptions import RequestException, Timeout
 from tenacity import (
+    before_sleep_log,
     retry,
     retry_if_exception_type,
     stop_after_attempt,
@@ -53,9 +55,14 @@ from futurehouse_client.models.app import (
     TaskRequest,
     TaskResponse,
     TaskResponseVerbose,
+    TrajectoryQueryParams,
 )
 from futurehouse_client.models.rest import (
     ExecutionStatus,
+    UserAgentRequest,
+    UserAgentRequestPostPayload,
+    UserAgentRequestStatus,
+    UserAgentResponsePayload,
     WorldModel,
     WorldModelResponse,
 )
@@ -104,6 +111,22 @@ class JobCreationError(RestClientError):
     """Raised when there's an error creating a job."""
 
 
+class UserAgentRequestError(RestClientError):
+    """Base exception for User Agent Request operations."""
+
+
+class UserAgentRequestFetchError(UserAgentRequestError):
+    """Raised when there's an error fetching a user agent request."""
+
+
+class UserAgentRequestCreationError(UserAgentRequestError):
+    """Raised when there's an error creating a user agent request."""
+
+
+class UserAgentRequestResponseError(UserAgentRequestError):
+    """Raised when there's an error responding to a user agent request."""
+
+
 class WorldModelFetchError(RestClientError):
     """Raised when there's an error fetching a world model."""
 
@@ -295,7 +318,7 @@ class RestClient:
             response.raise_for_status()
             return response.json()
         except Exception as e:
-            raise JobFetchError(f"Error checking job: {e!s}") from e
+            raise JobFetchError(f"Error checking job: {e!r}.") from e
 
     def _fetch_my_orgs(self) -> list[str]:
         response = self.client.get(f"/v0.1/organizations?filter={True}")
@@ -325,7 +348,7 @@ class RestClient:
             response.raise_for_status()
             return response.json()
         except Exception as e:
-            raise RestClientError(f"Error checking assembly status: {e}") from e
+            raise RestClientError(f"Error checking assembly status: {e!r}.") from e
 
     def _wait_for_all_assemblies_completion(
         self,
@@ -375,7 +398,7 @@ class RestClient:
                     elif status == ExecutionStatus.FAIL.value:
                         error_msg = status_data.get("error", "Unknown assembly error")
                         raise RestClientError(
-                            f"Assembly failed for {file_name}: {error_msg}"
+                            f"Assembly failed for {file_name}: {error_msg}."
                         )
                     elif status == ExecutionStatus.IN_PROGRESS.value:
                         logger.debug(f"Assembly in progress for {file_name}...")
@@ -384,7 +407,7 @@ class RestClient:
                     raise  # Re-raise assembly errors
                 except Exception as e:
                     logger.warning(
-                        f"Error checking assembly status for {file_name}: {e}"
+                        f"Error checking assembly status for {file_name}: {e!r}."
                     )
 
             # Don't sleep if all files are complete
@@ -394,7 +417,7 @@ class RestClient:
         if len(completed_files) < len(file_names):
             remaining_files = set(file_names) - completed_files
             logger.warning(
-                f"Assembly timeout for files: {remaining_files} after {timeout} seconds"
+                f"Assembly timeout for files: {remaining_files} after {timeout} seconds."
             )
             return False
 
@@ -413,7 +436,7 @@ class RestClient:
 
         """
         if not path.is_dir():
-            raise JobFetchError(f"Path {path} is not a directory")
+            raise JobFetchError(f"Path {path} is not a directory.")
 
     @staticmethod
     def _validate_template_path(template_path: str | os.PathLike) -> None:
@@ -450,12 +473,13 @@ class RestClient:
 
         """
         if not files:
-            raise TaskFetchError(f"No files found in {path}")
+            raise TaskFetchError(f"No files found in {path}.")
 
     @retry(
         stop=stop_after_attempt(MAX_RETRY_ATTEMPTS),
         wait=wait_exponential(multiplier=RETRY_MULTIPLIER, max=MAX_RETRY_WAIT),
         retry=retry_if_connection_error,
+        before_sleep=before_sleep_log(logger, logging.WARNING),
     )
     def get_task(
         self, task_id: str | None = None, history: bool = False, verbose: bool = False
@@ -496,6 +520,7 @@ class RestClient:
         stop=stop_after_attempt(MAX_RETRY_ATTEMPTS),
         wait=wait_exponential(multiplier=RETRY_MULTIPLIER, max=MAX_RETRY_WAIT),
         retry=retry_if_connection_error,
+        before_sleep=before_sleep_log(logger, logging.WARNING),
     )
     async def aget_task(
         self, task_id: str | None = None, history: bool = False, verbose: bool = False
@@ -519,7 +544,7 @@ class RestClient:
             ) as response:
                 if response.status_code in {401, 403}:
                     raise PermissionError(
-                        f"Error getting task: Permission denied for task {task_id}"
+                        f"Error getting task: Permission denied for task {task_id}."
                     )
                 response.raise_for_status()
                 json_data = "".join([chunk async for chunk in response.aiter_text()])
@@ -536,6 +561,53 @@ class RestClient:
         stop=stop_after_attempt(MAX_RETRY_ATTEMPTS),
         wait=wait_exponential(multiplier=RETRY_MULTIPLIER, max=MAX_RETRY_WAIT),
         retry=retry_if_connection_error,
+        before_sleep=before_sleep_log(logger, logging.WARNING),
+    )
+    def cancel_task(self, task_id: str | None = None) -> bool:
+        """Cancel a specific task/trajectory."""
+        task_id = task_id or self.trajectory_id
+        url = f"/v0.1/trajectories/{task_id}/cancel"
+        full_url = f"{self.base_url}{url}"
+
+        with external_trace(
+            url=full_url,
+            method="POST",
+            library="httpx",
+            custom_params={
+                "operation": "cancel_job",
+                "job_id": task_id,
+            },
+        ):
+            get_task_response = self.get_task(task_id)
+            # cancel if task is in progress
+            if get_task_response.status == ExecutionStatus.IN_PROGRESS.value:
+                response = self.client.post(url)
+                try:
+                    response.raise_for_status()
+
+                except HTTPStatusError as e:
+                    if e.response.status_code in {
+                        HTTPStatus.UNAUTHORIZED,
+                        HTTPStatus.FORBIDDEN,
+                    }:
+                        raise PermissionError(
+                            f"Error canceling task: Permission denied for task {task_id}"
+                        ) from e
+                    if e.response.status_code == HTTPStatus.NOT_FOUND:
+                        raise TaskFetchError(
+                            f"Error canceling task: Trajectory not found for task {task_id}"
+                        ) from e
+                    raise
+
+                get_task_response = self.get_task(task_id)
+                return get_task_response.status == ExecutionStatus.CANCELLED.value
+        return False
+
+    @retry(
+        stop=stop_after_attempt(MAX_RETRY_ATTEMPTS),
+        wait=wait_exponential(multiplier=RETRY_MULTIPLIER, max=MAX_RETRY_WAIT),
+        retry=retry_if_connection_error,
+        before_sleep=before_sleep_log(logger, logging.WARNING),
     )
     def create_task(
         self,
@@ -560,7 +632,7 @@ class RestClient:
         )
         if response.status_code in {401, 403}:
             raise PermissionError(
-                f"Error creating task: Permission denied for task {task_data.name}"
+                f"Error creating task: Permission denied for task {task_data.name}."
             )
         response.raise_for_status()
         trajectory_id = response.json()["trajectory_id"]
@@ -571,6 +643,7 @@ class RestClient:
         stop=stop_after_attempt(MAX_RETRY_ATTEMPTS),
         wait=wait_exponential(multiplier=RETRY_MULTIPLIER, max=MAX_RETRY_WAIT),
         retry=retry_if_connection_error,
+        before_sleep=before_sleep_log(logger, logging.WARNING),
     )
     async def acreate_task(
         self,
@@ -595,7 +668,7 @@ class RestClient:
         )
         if response.status_code in {401, 403}:
             raise PermissionError(
-                f"Error creating task: Permission denied for task {task_data.name}"
+                f"Error creating task: Permission denied for task {task_data.name}."
             )
         response.raise_for_status()
         trajectory_id = response.json()["trajectory_id"]
@@ -747,6 +820,7 @@ class RestClient:
         stop=stop_after_attempt(MAX_RETRY_ATTEMPTS),
         wait=wait_exponential(multiplier=RETRY_MULTIPLIER, max=MAX_RETRY_WAIT),
         retry=retry_if_connection_error,
+        before_sleep=before_sleep_log(logger, logging.WARNING),
     )
     def get_build_status(self, build_id: UUID | None = None) -> dict[str, Any]:
         """Get the status of a build."""
@@ -755,7 +829,7 @@ class RestClient:
             response = self.client.get(f"/v0.1/builds/{build_id}")
             response.raise_for_status()
         except Exception as e:
-            raise JobFetchError(f"Error getting build status: {e!s}") from e
+            raise JobFetchError(f"Error getting build status: {e!r}.") from e
         return response.json()
 
     # TODO: Refactor later so we don't have to ignore PLR0915
@@ -763,6 +837,7 @@ class RestClient:
         stop=stop_after_attempt(MAX_RETRY_ATTEMPTS),
         wait=wait_exponential(multiplier=RETRY_MULTIPLIER, max=MAX_RETRY_WAIT),
         retry=retry_if_connection_error,
+        before_sleep=before_sleep_log(logger, logging.WARNING),
     )
     def create_job(self, config: JobDeploymentConfig) -> dict[str, Any]:  # noqa: PLR0915
         """Creates a futurehouse job deployment from the environment and environment files.
@@ -920,6 +995,13 @@ class RestClient:
                     if config.task_queues_config
                     else None
                 ),
+                "user_input_config": (
+                    json.dumps([
+                        entity.model_dump() for entity in config.user_input_config
+                    ])
+                    if config.user_input_config
+                    else None
+                ),
             }
             response = self.multipart_client.post(
                 "/v0.1/builds",
@@ -940,10 +1022,10 @@ class RestClient:
                 error_detail = response.json()
                 error_message = error_detail.get("detail", str(e))
                 raise JobCreationError(
-                    f"Server validation error: {error_message}"
+                    f"Server validation error: {error_message}."
                 ) from e
         except Exception as e:
-            raise JobCreationError(f"Error generating docker image: {e!s}") from e
+            raise JobCreationError(f"Error generating docker image: {e!r}.") from e
         return build_context
 
     # TODO: we should have have an async upload_file, check_assembly_status,
@@ -952,6 +1034,7 @@ class RestClient:
         stop=stop_after_attempt(MAX_RETRY_ATTEMPTS),
         wait=wait_exponential(multiplier=RETRY_MULTIPLIER, max=MAX_RETRY_WAIT),
         retry=retry_if_connection_error,
+        before_sleep=before_sleep_log(logger, logging.WARNING),
     )
     def upload_file(
         self,
@@ -999,7 +1082,7 @@ class RestClient:
             )
             if not success:
                 raise RestClientError(
-                    f"Assembly failed or timed out for one or more files: {uploaded_files}"
+                    f"Assembly failed or timed out for one or more files: {uploaded_files}."
                 )
 
         logger.info(f"Successfully uploaded {file_path} to {upload_id}")
@@ -1044,7 +1127,9 @@ class RestClient:
                     )
                     uploaded_files.append(file_name)
         except Exception as e:
-            raise FileUploadError(f"Error uploading directory {dir_path}: {e}") from e
+            raise FileUploadError(
+                f"Error uploading directory {dir_path}: {e!r}."
+            ) from e
 
         return uploaded_files
 
@@ -1095,7 +1180,7 @@ class RestClient:
             logger.info(f"Successfully uploaded {file_name}")
         except Exception as e:
             logger.exception(f"Error uploading file {file_path}")
-            raise FileUploadError(f"Error uploading file {file_path}: {e}") from e
+            raise FileUploadError(f"Error uploading file {file_path}: {e!r}.") from e
         return status_url
 
     def _upload_chunks_parallel(
@@ -1156,9 +1241,9 @@ class RestClient:
                                 f"Uploaded chunk {chunk_index + 1}/{total_chunks} of {file_name}"
                             )
                         except Exception as e:
-                            logger.error(f"Error uploading chunk {chunk_index}: {e}")
+                            logger.error(f"Error uploading chunk {chunk_index}: {e!r}.")
                             raise FileUploadError(
-                                f"Error uploading chunk {chunk_index} of {file_name}: {e}"
+                                f"Error uploading chunk {chunk_index} of {file_name}: {e!r}."
                             ) from e
 
         # Upload the final chunk with retry logic
@@ -1224,11 +1309,11 @@ class RestClient:
             except Exception as e:
                 if retries >= max_retries - 1:
                     raise FileUploadError(
-                        f"Error uploading final chunk of {file_name}: {e}"
+                        f"Error uploading final chunk of {file_name}: {e!r}."
                     ) from e
                 retries += 1
                 logger.warning(
-                    f"Error uploading final chunk of {file_name}, retrying in {retry_delay}s... (attempt {retries}/{max_retries}): {e}"
+                    f"Error uploading final chunk of {file_name}, retrying in {retry_delay}s... (attempt {retries}/{max_retries}): {e!r}."
                 )
                 time.sleep(retry_delay)
 
@@ -1296,6 +1381,7 @@ class RestClient:
         stop=stop_after_attempt(MAX_RETRY_ATTEMPTS),
         wait=wait_exponential(multiplier=RETRY_MULTIPLIER, max=MAX_RETRY_WAIT),
         retry=retry_if_connection_error,
+        before_sleep=before_sleep_log(logger, logging.WARNING),
     )
     def list_files(
         self,
@@ -1318,7 +1404,7 @@ class RestClient:
         """
         if not bool(trajectory_id) ^ bool(upload_id):
             raise RestClientError(
-                "Must at least specify one of trajectory_id or upload_id, but not both"
+                "Must at least specify one of trajectory_id or upload_id, but not both."
             )
         try:
             url = f"/v0.1/crows/{job_name}/list-files"
@@ -1332,18 +1418,19 @@ class RestClient:
                 f"Error listing files for job {job_name}, trajectory {trajectory_id}, upload_id {upload_id}: {e.response.text}"
             )
             raise RestClientError(
-                f"Error listing files: {e.response.status_code} - {e.response.text}"
+                f"Error listing files: {e.response.status_code} - {e.response.text}."
             ) from e
         except Exception as e:
             logger.exception(
                 f"Error listing files for job {job_name}, trajectory {trajectory_id}, upload_id {upload_id}"
             )
-            raise RestClientError(f"Error listing files: {e!s}") from e
+            raise RestClientError(f"Error listing files: {e!r}.") from e
 
     @retry(
         stop=stop_after_attempt(MAX_RETRY_ATTEMPTS),
         wait=wait_exponential(multiplier=RETRY_MULTIPLIER, max=MAX_RETRY_WAIT),
         retry=retry_if_connection_error,
+        before_sleep=before_sleep_log(logger, logging.WARNING),
     )
     def download_file(
         self,
@@ -1394,7 +1481,7 @@ class RestClient:
             if destination_path.exists():
                 destination_path.unlink()
             raise RestClientError(
-                f"Error downloading file: {e.response.status_code} - {e.response.text}"
+                f"Error downloading file: {e.response.status_code} - {e.response.text}."
             ) from e
         except RemoteProtocolError as e:
             logger.error(
@@ -1413,12 +1500,13 @@ class RestClient:
             )
             if destination_path.exists():
                 destination_path.unlink()  # Clean up partial file
-            raise RestClientError(f"Error downloading file: {e!s}") from e
+            raise RestClientError(f"Error downloading file: {e!r}.") from e
 
     @retry(
         stop=stop_after_attempt(MAX_RETRY_ATTEMPTS),
         wait=wait_exponential(multiplier=RETRY_MULTIPLIER, max=MAX_RETRY_WAIT),
         retry=retry_if_connection_error,
+        before_sleep=before_sleep_log(logger, logging.WARNING),
     )
     def get_world_model(
         self, world_model_id: UUID | None = None, name: str | None = None
@@ -1450,15 +1538,16 @@ class RestClient:
                     "World model not found with the specified identifier."
                 ) from e
             raise WorldModelFetchError(
-                f"Error fetching world model: {e.response.status_code} - {e.response.text}"
+                f"Error fetching world model: {e.response.status_code} - {e.response.text}."
             ) from e
         except Exception as e:
-            raise WorldModelFetchError(f"An unexpected error occurred: {e}") from e
+            raise WorldModelFetchError(f"An unexpected error occurred: {e!r}.") from e
 
     @retry(
         stop=stop_after_attempt(MAX_RETRY_ATTEMPTS),
         wait=wait_exponential(multiplier=RETRY_MULTIPLIER, max=MAX_RETRY_WAIT),
         retry=retry_if_connection_error,
+        before_sleep=before_sleep_log(logger, logging.WARNING),
     )
     async def aget_world_model(
         self, world_model_id: UUID | None = None, name: str | None = None
@@ -1490,15 +1579,16 @@ class RestClient:
                     "World model not found with the specified identifier."
                 ) from e
             raise WorldModelFetchError(
-                f"Error fetching world model: {e.response.status_code} - {e.response.text}"
+                f"Error fetching world model: {e.response.status_code} - {e.response.text}."
             ) from e
         except Exception as e:
-            raise WorldModelFetchError(f"An unexpected error occurred: {e}") from e
+            raise WorldModelFetchError(f"An unexpected error occurred: {e!r}.") from e
 
     @retry(
         stop=stop_after_attempt(MAX_RETRY_ATTEMPTS),
         wait=wait_exponential(multiplier=RETRY_MULTIPLIER, max=MAX_RETRY_WAIT),
         retry=retry_if_connection_error,
+        before_sleep=before_sleep_log(logger, logging.WARNING),
     )
     def create_world_model(self, payload: WorldModel) -> UUID:
         """Create a new, immutable world model snapshot.
@@ -1522,20 +1612,21 @@ class RestClient:
         except HTTPStatusError as e:
             if e.response.status_code == codes.BAD_REQUEST:
                 raise WorldModelCreationError(
-                    f"Invalid payload for world model creation: {e.response.text}"
+                    f"Invalid payload for world model creation: {e.response.text}."
                 ) from e
             raise WorldModelCreationError(
-                f"Error creating world model: {e.response.status_code} - {e.response.text}"
+                f"Error creating world model: {e.response.status_code} - {e.response.text}."
             ) from e
         except Exception as e:
             raise WorldModelCreationError(
-                f"An unexpected error occurred during world model creation: {e}"
+                f"An unexpected error occurred during world model creation: {e!r}."
             ) from e
 
     @retry(
         stop=stop_after_attempt(MAX_RETRY_ATTEMPTS),
         wait=wait_exponential(multiplier=RETRY_MULTIPLIER, max=MAX_RETRY_WAIT),
         retry=retry_if_connection_error,
+        before_sleep=before_sleep_log(logger, logging.WARNING),
     )
     async def acreate_world_model(self, payload: WorldModel) -> UUID:
         """Asynchronously create a new, immutable world model snapshot.
@@ -1558,14 +1649,14 @@ class RestClient:
         except HTTPStatusError as e:
             if e.response.status_code == codes.BAD_REQUEST:
                 raise WorldModelCreationError(
-                    f"Invalid payload for world model creation: {e.response.text}"
+                    f"Invalid payload for world model creation: {e.response.text}."
                 ) from e
             raise WorldModelCreationError(
-                f"Error creating world model: {e.response.status_code} - {e.response.text}"
+                f"Error creating world model: {e.response.status_code} - {e.response.text}."
             ) from e
         except Exception as e:
             raise WorldModelCreationError(
-                f"An unexpected error occurred during world model creation: {e}"
+                f"An unexpected error occurred during world model creation: {e!r}."
             ) from e
 
     @retry(
@@ -1771,6 +1862,470 @@ class RestClient:
         except Exception as e:
             raise ProjectError(f"Error adding trajectory to project: {e}") from e
 
+    @retry(
+        stop=stop_after_attempt(MAX_RETRY_ATTEMPTS),
+        wait=wait_exponential(multiplier=RETRY_MULTIPLIER, max=MAX_RETRY_WAIT),
+        retry=retry_if_connection_error,
+        before_sleep=before_sleep_log(logger, logging.WARNING),
+    )
+    def get_tasks(
+        self,
+        query_params: TrajectoryQueryParams | None = None,
+        *,
+        project_id: UUID | None = None,
+        name: str | None = None,
+        user: str | None = None,
+        limit: int = 50,
+        offset: int = 0,
+        sort_by: str = "created_at",
+        sort_order: str = "desc",
+    ) -> list[dict[str, Any]]:
+        """Fetches trajectories with applied filtering.
+
+        Args:
+            query_params: Optional TrajectoryQueryParams model with all parameters
+            project_id: Optional project ID to filter trajectories by
+            name: Optional name filter for trajectories
+            user: Optional user email filter for trajectories
+            limit: Maximum number of trajectories to return (default: 50, max: 200)
+            offset: Number of trajectories to skip for pagination (default: 0)
+            sort_by: Field to sort by, either "created_at" or "name" (default: "created_at")
+            sort_order: Sort order, either "asc" or "desc" (default: "desc")
+
+        Returns:
+            List of trajectory dictionaries
+
+        Raises:
+            TaskFetchError: If there's an error fetching trajectories
+        """
+        try:
+            if query_params is not None:
+                params = query_params.to_query_params()
+            else:
+                params_model = TrajectoryQueryParams(
+                    project_id=project_id,
+                    name=name,
+                    user=user,
+                    limit=limit,
+                    offset=offset,
+                    sort_by=sort_by,
+                    sort_order=sort_order,
+                )
+                params = params_model.to_query_params()
+
+            response = self.client.get("/v0.1/trajectories", params=params)
+            response.raise_for_status()
+            return response.json()
+        except HTTPStatusError as e:
+            if e.response.status_code in {401, 403}:
+                raise PermissionError(
+                    "Error getting trajectories: Permission denied"
+                ) from e
+            raise TaskFetchError(
+                f"Error getting trajectories: {e.response.status_code} - {e.response.text}"
+            ) from e
+        except Exception as e:
+            raise TaskFetchError(f"Error getting trajectories: {e!r}") from e
+
+    @retry(
+        stop=stop_after_attempt(MAX_RETRY_ATTEMPTS),
+        wait=wait_exponential(multiplier=RETRY_MULTIPLIER, max=MAX_RETRY_WAIT),
+        retry=retry_if_connection_error,
+        before_sleep=before_sleep_log(logger, logging.WARNING),
+    )
+    async def aget_tasks(
+        self,
+        query_params: TrajectoryQueryParams | None = None,
+        *,
+        project_id: UUID | None = None,
+        name: str | None = None,
+        user: str | None = None,
+        limit: int = 50,
+        offset: int = 0,
+        sort_by: str = "created_at",
+        sort_order: str = "desc",
+    ) -> list[dict[str, Any]]:
+        """Asynchronously fetch trajectories with applied filtering.
+
+        Args:
+            query_params: Optional TrajectoryQueryParams model with all parameters
+            project_id: Optional project ID to filter trajectories by
+            name: Optional name filter for trajectories
+            user: Optional user email filter for trajectories
+            limit: Maximum number of trajectories to return (default: 50, max: 200)
+            offset: Number of trajectories to skip for pagination (default: 0)
+            sort_by: Field to sort by, either "created_at" or "name" (default: "created_at")
+            sort_order: Sort order, either "asc" or "desc" (default: "desc")
+
+        Returns:
+            List of trajectory dictionaries
+
+        Raises:
+            TaskFetchError: If there's an error fetching trajectories
+        """
+        try:
+            if query_params is not None:
+                params = query_params.to_query_params()
+            else:
+                params_model = TrajectoryQueryParams(
+                    project_id=project_id,
+                    name=name,
+                    user=user,
+                    limit=limit,
+                    offset=offset,
+                    sort_by=sort_by,
+                    sort_order=sort_order,
+                )
+                params = params_model.to_query_params()
+
+            response = await self.async_client.get("/v0.1/trajectories", params=params)
+            response.raise_for_status()
+            return response.json()
+        except HTTPStatusError as e:
+            if e.response.status_code in {401, 403}:
+                raise PermissionError(
+                    "Error getting trajectories: Permission denied"
+                ) from e
+            raise TaskFetchError(
+                f"Error getting trajectories: {e.response.status_code} - {e.response.text}"
+            ) from e
+        except Exception as e:
+            raise TaskFetchError(f"Error getting trajectories: {e!r}") from e
+
+    @retry(
+        stop=stop_after_attempt(MAX_RETRY_ATTEMPTS),
+        wait=wait_exponential(multiplier=RETRY_MULTIPLIER, max=MAX_RETRY_WAIT),
+        retry=retry_if_connection_error,
+        before_sleep=before_sleep_log(logger, logging.WARNING),
+    )
+    def list_user_agent_requests(
+        self,
+        user_id: str | None = None,
+        trajectory_id: UUID | None = None,
+        request_status: UserAgentRequestStatus | None = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> list[UserAgentRequest]:
+        """List user agent requests with optional filters.
+
+        Args:
+            user_id: Filter requests by user ID. Defaults to the authenticated user's ID if not provided.
+            trajectory_id: Filter requests by trajectory ID.
+            request_status: Filter requests by status (e.g., PENDING).
+            limit: Maximum number of requests to return.
+            offset: Offset for pagination.
+
+        Returns:
+            A list of user agent requests.
+
+        Raises:
+            UserAgentRequestFetchError: If the API call fails.
+        """
+        params = {
+            "user_id": user_id,
+            "trajectory_id": str(trajectory_id) if trajectory_id else None,
+            "request_status": request_status.value if request_status else None,
+            "limit": limit,
+            "offset": offset,
+        }
+        # Filter out None values
+        params = {k: v for k, v in params.items() if v is not None}
+        try:
+            response = self.client.get("/v0.1/user-agent-requests", params=params)
+            response.raise_for_status()
+            return [UserAgentRequest.model_validate(item) for item in response.json()]
+        except HTTPStatusError as e:
+            raise UserAgentRequestFetchError(
+                f"Error listing user agent requests: {e.response.status_code} - {e.response.text}"
+            ) from e
+        except Exception as e:
+            raise UserAgentRequestFetchError(
+                f"An unexpected error occurred: {e!r}"
+            ) from e
+
+    @retry(
+        stop=stop_after_attempt(MAX_RETRY_ATTEMPTS),
+        wait=wait_exponential(multiplier=RETRY_MULTIPLIER, max=MAX_RETRY_WAIT),
+        retry=retry_if_connection_error,
+        before_sleep=before_sleep_log(logger, logging.WARNING),
+    )
+    async def alist_user_agent_requests(
+        self,
+        user_id: str | None = None,
+        trajectory_id: UUID | None = None,
+        request_status: UserAgentRequestStatus | None = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> list[UserAgentRequest]:
+        """Asynchronously list user agent requests with optional filters.
+
+        Args:
+            user_id: Filter requests by user ID. Defaults to the authenticated user's ID if not provided.
+            trajectory_id: Filter requests by trajectory ID.
+            request_status: Filter requests by status (e.g., PENDING).
+            limit: Maximum number of requests to return.
+            offset: Offset for pagination.
+
+        Returns:
+            A list of user agent requests.
+
+        Raises:
+            UserAgentRequestFetchError: If the API call fails.
+        """
+        params = {
+            "user_id": user_id,
+            "trajectory_id": str(trajectory_id) if trajectory_id else None,
+            "request_status": request_status.value if request_status else None,
+            "limit": limit,
+            "offset": offset,
+        }
+        # Filter out None values
+        params = {k: v for k, v in params.items() if v is not None}
+        try:
+            response = await self.async_client.get(
+                "/v0.1/user-agent-requests", params=params
+            )
+            response.raise_for_status()
+            return [UserAgentRequest.model_validate(item) for item in response.json()]
+        except HTTPStatusError as e:
+            raise UserAgentRequestFetchError(
+                f"Error listing user agent requests: {e.response.status_code} - {e.response.text}"
+            ) from e
+        except Exception as e:
+            raise UserAgentRequestFetchError(
+                f"An unexpected error occurred: {e!r}"
+            ) from e
+
+    @retry(
+        stop=stop_after_attempt(MAX_RETRY_ATTEMPTS),
+        wait=wait_exponential(multiplier=RETRY_MULTIPLIER, max=MAX_RETRY_WAIT),
+        retry=retry_if_connection_error,
+        before_sleep=before_sleep_log(logger, logging.WARNING),
+    )
+    def get_user_agent_request(self, request_id: UUID) -> UserAgentRequest:
+        """Retrieve a single user agent request by its unique ID.
+
+        Args:
+            request_id: The unique ID of the request.
+
+        Returns:
+            The user agent request.
+
+        Raises:
+            UserAgentRequestFetchError: If the API call fails or the request is not found.
+        """
+        try:
+            response = self.client.get(f"/v0.1/user-agent-requests/{request_id}")
+            response.raise_for_status()
+            return UserAgentRequest.model_validate(response.json())
+        except HTTPStatusError as e:
+            if e.response.status_code == codes.NOT_FOUND:
+                raise UserAgentRequestFetchError(
+                    f"User agent request with ID {request_id} not found."
+                ) from e
+            raise UserAgentRequestFetchError(
+                f"Error fetching user agent request: {e.response.status_code} - {e.response.text}"
+            ) from e
+        except Exception as e:
+            raise UserAgentRequestFetchError(
+                f"An unexpected error occurred: {e!r}"
+            ) from e
+
+    @retry(
+        stop=stop_after_attempt(MAX_RETRY_ATTEMPTS),
+        wait=wait_exponential(multiplier=RETRY_MULTIPLIER, max=MAX_RETRY_WAIT),
+        retry=retry_if_connection_error,
+        before_sleep=before_sleep_log(logger, logging.WARNING),
+    )
+    async def aget_user_agent_request(self, request_id: UUID) -> UserAgentRequest:
+        """Asynchronously retrieve a single user agent request by its unique ID.
+
+        Args:
+            request_id: The unique ID of the request.
+
+        Returns:
+            The user agent request.
+
+        Raises:
+            UserAgentRequestFetchError: If the API call fails or the request is not found.
+        """
+        try:
+            response = await self.async_client.get(
+                f"/v0.1/user-agent-requests/{request_id}"
+            )
+            response.raise_for_status()
+            return UserAgentRequest.model_validate(response.json())
+        except HTTPStatusError as e:
+            if e.response.status_code == codes.NOT_FOUND:
+                raise UserAgentRequestFetchError(
+                    f"User agent request with ID {request_id} not found."
+                ) from e
+            raise UserAgentRequestFetchError(
+                f"Error fetching user agent request: {e.response.status_code} - {e.response.text}"
+            ) from e
+        except Exception as e:
+            raise UserAgentRequestFetchError(
+                f"An unexpected error occurred: {e!r}"
+            ) from e
+
+    @retry(
+        stop=stop_after_attempt(MAX_RETRY_ATTEMPTS),
+        wait=wait_exponential(multiplier=RETRY_MULTIPLIER, max=MAX_RETRY_WAIT),
+        retry=retry_if_connection_error,
+        before_sleep=before_sleep_log(logger, logging.WARNING),
+    )
+    def create_user_agent_request(self, payload: UserAgentRequestPostPayload) -> UUID:
+        """Creates a new request from an agent to a user.
+
+        Args:
+            payload: An instance of UserAgentRequestPostPayload with the request data.
+
+        Returns:
+            The UUID of the newly created user agent request.
+
+        Raises:
+            UserAgentRequestCreationError: If the API call fails.
+        """
+        try:
+            response = self.client.post(
+                "/v0.1/user-agent-requests", json=payload.model_dump(mode="json")
+            )
+            response.raise_for_status()
+            return UUID(response.json())
+        except HTTPStatusError as e:
+            if e.response.status_code == codes.UNPROCESSABLE_ENTITY:
+                raise UserAgentRequestCreationError(
+                    f"Invalid payload for user agent request creation: {e.response.text}."
+                ) from e
+            raise UserAgentRequestCreationError(
+                f"Error creating user agent request: {e.response.status_code} - {e.response.text}"
+            ) from e
+        except Exception as e:
+            raise UserAgentRequestCreationError(
+                f"An unexpected error occurred during user agent request creation: {e!r}."
+            ) from e
+
+    @retry(
+        stop=stop_after_attempt(MAX_RETRY_ATTEMPTS),
+        wait=wait_exponential(multiplier=RETRY_MULTIPLIER, max=MAX_RETRY_WAIT),
+        retry=retry_if_connection_error,
+        before_sleep=before_sleep_log(logger, logging.WARNING),
+    )
+    async def acreate_user_agent_request(
+        self, payload: UserAgentRequestPostPayload
+    ) -> UUID:
+        """Asynchronously creates a new request from an agent to a user.
+
+        Args:
+            payload: An instance of UserAgentRequestPostPayload with the request data.
+
+        Returns:
+            The UUID of the newly created user agent request.
+
+        Raises:
+            UserAgentRequestCreationError: If the API call fails.
+        """
+        try:
+            response = await self.async_client.post(
+                "/v0.1/user-agent-requests", json=payload.model_dump(mode="json")
+            )
+            response.raise_for_status()
+            return UUID(response.json())
+        except HTTPStatusError as e:
+            if e.response.status_code == codes.UNPROCESSABLE_ENTITY:
+                raise UserAgentRequestCreationError(
+                    f"Invalid payload for user agent request creation: {e.response.text}."
+                ) from e
+            raise UserAgentRequestCreationError(
+                f"Error creating user agent request: {e.response.status_code} - {e.response.text}"
+            ) from e
+        except Exception as e:
+            raise UserAgentRequestCreationError(
+                f"An unexpected error occurred during user agent request creation: {e!r}."
+            ) from e
+
+    @retry(
+        stop=stop_after_attempt(MAX_RETRY_ATTEMPTS),
+        wait=wait_exponential(multiplier=RETRY_MULTIPLIER, max=MAX_RETRY_WAIT),
+        retry=retry_if_connection_error,
+        before_sleep=before_sleep_log(logger, logging.WARNING),
+    )
+    def respond_to_user_agent_request(
+        self, request_id: UUID, payload: UserAgentResponsePayload
+    ) -> None:
+        """Submit a user's response to a pending agent request.
+
+        Args:
+            request_id: The unique ID of the request to respond to.
+            payload: An instance of UserAgentResponsePayload with the response data.
+
+        Raises:
+            UserAgentRequestResponseError: If the API call fails.
+        """
+        try:
+            response = self.client.post(
+                f"/v0.1/user-agent-requests/{request_id}/response",
+                json=payload.model_dump(mode="json"),
+            )
+            response.raise_for_status()
+        except HTTPStatusError as e:
+            if e.response.status_code == codes.NOT_FOUND:
+                raise UserAgentRequestResponseError(
+                    f"User agent request with ID {request_id} not found."
+                ) from e
+            if e.response.status_code == codes.UNPROCESSABLE_ENTITY:
+                raise UserAgentRequestResponseError(
+                    f"Invalid response payload: {e.response.text}."
+                ) from e
+            raise UserAgentRequestResponseError(
+                f"Error responding to user agent request: {e.response.status_code} - {e.response.text}"
+            ) from e
+        except Exception as e:
+            raise UserAgentRequestResponseError(
+                f"An unexpected error occurred while responding to the request: {e!r}."
+            ) from e
+
+    @retry(
+        stop=stop_after_attempt(MAX_RETRY_ATTEMPTS),
+        wait=wait_exponential(multiplier=RETRY_MULTIPLIER, max=MAX_RETRY_WAIT),
+        retry=retry_if_connection_error,
+        before_sleep=before_sleep_log(logger, logging.WARNING),
+    )
+    async def arespond_to_user_agent_request(
+        self, request_id: UUID, payload: UserAgentResponsePayload
+    ) -> None:
+        """Asynchronously submit a user's response to a pending agent request.
+
+        Args:
+            request_id: The unique ID of the request to respond to.
+            payload: An instance of UserAgentResponsePayload with the response data.
+
+        Raises:
+            UserAgentRequestResponseError: If the API call fails.
+        """
+        try:
+            response = await self.async_client.post(
+                f"/v0.1/user-agent-requests/{request_id}/response",
+                json=payload.model_dump(mode="json"),
+            )
+            response.raise_for_status()
+        except HTTPStatusError as e:
+            if e.response.status_code == codes.NOT_FOUND:
+                raise UserAgentRequestResponseError(
+                    f"User agent request with ID {request_id} not found."
+                ) from e
+            if e.response.status_code == codes.UNPROCESSABLE_ENTITY:
+                raise UserAgentRequestResponseError(
+                    f"Invalid response payload: {e.response.text}."
+                ) from e
+            raise UserAgentRequestResponseError(
+                f"Error responding to user agent request: {e.response.status_code} - {e.response.text}"
+            ) from e
+        except Exception as e:
+            raise UserAgentRequestResponseError(
+                f"An unexpected error occurred while responding to the request: {e!r}."
+            ) from e
+
 
 def get_installed_packages() -> dict[str, str]:
     """Returns a dictionary of installed packages and their versions."""

futurehouse_client/models/app.py

@@ -278,6 +278,20 @@ class FramePath(BaseModel):
     )
 
 
+class NamedEntity(BaseModel):
+    name: str = Field(
+        description=(
+            "Name of an entity for a user to provide a value to during query submission. "
+            "This will be used as a key to prompt users for a value. "
+            "Example: 'pdb' would result in <pdb>user input here</pdb> in the task string."
+        )
+    )
+    description: str | None = Field(
+        default=None,
+        description="Helper text to provide the user context to what the name or format needs to be.",
+    )
+
+
 class DockerContainerConfiguration(BaseModel):
     cpu: str = Field(description="CPU allotment for the container")
     memory: str = Field(description="Memory allotment for the container")
@@ -458,6 +472,15 @@ class JobDeploymentConfig(BaseModel):
         description="The configuration for the task queue(s) that will be created for this deployment.",
     )
 
+    user_input_config: list[NamedEntity] | None = Field(
+        default=None,
+        description=(
+            "List of NamedEntity objects that represent user input fields "
+            "to be included in the task string. "
+            "These will be used to prompt users for values during query submission."
+        ),
+    )
+
     @field_validator("markdown_template_path")
     @classmethod
     def validate_markdown_path(
@@ -646,6 +669,62 @@ class RuntimeConfig(BaseModel):
         return value
 
 
+class TrajectoryQueryParams(BaseModel):
+    """Params for trajectories with filtering."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    project_id: UUID | None = Field(
+        default=None, description="Optional project ID to filter trajectories by"
+    )
+    name: str | None = Field(
+        default=None, description="Optional name filter for trajectories"
+    )
+    user: str | None = Field(
+        default=None, description="Optional user email filter for trajectories"
+    )
+    limit: int = Field(
+        default=50,
+        ge=1,
+        le=200,
+        description="Maximum number of trajectories to return (max: 200)",
+    )
+    offset: int = Field(
+        default=0, ge=0, description="Number of trajectories to skip for pagination"
+    )
+    sort_by: str = Field(default="created_at", description="Field to sort by")
+    sort_order: str = Field(default="desc", description="Sort order")
+
+    @field_validator("sort_by")
+    @classmethod
+    def validate_sort_by(cls, v: str) -> str:
+        if v not in {"created_at", "name"}:
+            raise ValueError("sort_by must be either 'created_at' or 'name'")
+        return v
+
+    @field_validator("sort_order")
+    @classmethod
+    def validate_sort_order(cls, v: str) -> str:
+        if v not in {"asc", "desc"}:
+            raise ValueError("sort_order must be either 'asc' or 'desc'")
+        return v
+
+    def to_query_params(self) -> dict[str, str | int]:
+        params: dict[str, str | int] = {
+            "limit": self.limit,
+            "offset": self.offset,
+            "sort_by": self.sort_by,
+            "sort_order": self.sort_order,
+        }
+        if self.project_id is not None:
+            params["project_id"] = str(self.project_id)
+        if self.name is not None:
+            params["name"] = self.name
+        if self.user is not None:
+            params["user"] = self.user
+        return params
+
+
 class TaskRequest(BaseModel):
     model_config = ConfigDict(extra="forbid")
 

futurehouse_client/models/rest.py

@@ -2,7 +2,7 @@ from datetime import datetime
 from enum import StrEnum, auto
 from uuid import UUID
 
-from pydantic import BaseModel, JsonValue
+from pydantic import BaseModel, ConfigDict, JsonValue
 
 
 class FinalEnvironmentRequest(BaseModel):
@@ -70,3 +70,50 @@ class WorldModelResponse(BaseModel):
     model_metadata: JsonValue | None
     enabled: bool
     created_at: datetime
+
+
+class UserAgentRequestStatus(StrEnum):
+    """Enum for the status of a user agent request."""
+
+    PENDING = auto()
+    RESPONDED = auto()
+    EXPIRED = auto()
+    CANCELLED = auto()
+
+
+class UserAgentRequest(BaseModel):
+    """Sister model for UserAgentRequestsDB."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    id: UUID
+    user_id: str
+    trajectory_id: UUID
+    response_trajectory_id: UUID | None = None
+    request: JsonValue
+    response: JsonValue | None = None
+    request_world_model_edit_id: UUID | None = None
+    response_world_model_edit_id: UUID | None = None
+    expires_at: datetime | None = None
+    user_response_task: JsonValue | None = None
+    status: UserAgentRequestStatus
+    created_at: datetime | None = None
+    modified_at: datetime | None = None
+
+
+class UserAgentRequestPostPayload(BaseModel):
+    """Payload to create a new user agent request."""
+
+    trajectory_id: UUID
+    request: JsonValue
+    request_world_model_edit_id: UUID | None = None
+    status: UserAgentRequestStatus = UserAgentRequestStatus.PENDING
+    expires_in_seconds: int | None = None
+    user_response_task: JsonValue | None = None
+
+
+class UserAgentResponsePayload(BaseModel):
+    """Payload for a user to submit a response to a request."""
+
+    response: JsonValue
+    response_world_model_edit_id: UUID | None = None

futurehouse_client/version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.3.20.dev215'
-__version_tuple__ = version_tuple = (0, 3, 20, 'dev215')
+__version__ = version = '0.3.20.dev266'
+__version_tuple__ = version_tuple = (0, 3, 20, 'dev266')

{futurehouse_client-0.3.20.dev215.dist-info → futurehouse_client-0.3.20.dev266.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: futurehouse-client
-Version: 0.3.20.dev215
+Version: 0.3.20.dev266
 Summary: A client for interacting with endpoints of the FutureHouse service.
 Author-email: FutureHouse technical staff <hello@futurehouse.org>
 License:                                  Apache License

{futurehouse_client-0.3.20.dev215.dist-info → futurehouse_client-0.3.20.dev266.dist-info}/RECORD

@@ -1,20 +1,20 @@
 futurehouse_client/__init__.py,sha256=BztM_ntbgmIEjzvnBWcvPhvLjM8xGDFCK0Upf3-nIn8,488
 futurehouse_client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-futurehouse_client/version.py,sha256=pUKvLSR6DkrlymjAn81oaYqONXdmBS18_lBjSKnvJlc,530
+futurehouse_client/version.py,sha256=BuvmuyFVBsO4OXG69bB2-CE0nYFKK5whAaQhu308ukU,530
 futurehouse_client/clients/__init__.py,sha256=-HXNj-XJ3LRO5XM6MZ709iPs29YpApss0Q2YYg1qMZw,280
 futurehouse_client/clients/job_client.py,sha256=D51_qTxya6g5Wfg_ZfJdP031TV_YDJeXkGMiYAJ1qRc,11962
-futurehouse_client/clients/rest_client.py,sha256=v5INQ9Wsb3A3U2zdLfRUP2H1hXpsZHtiZdVEav3Sv6o,69215
+futurehouse_client/clients/rest_client.py,sha256=L8U3Ap-91_A90PkC00n-WwhVkK9oQjgxR59JAykyhjw,91929
 futurehouse_client/models/__init__.py,sha256=kQ4R7VEuRxO0IQEW_sk9CndBL7zzl8rUKI24ddyYLM0,647
-futurehouse_client/models/app.py,sha256=SvkXOu5Qx28_jCS84XKKepnpGyfrQUEVnxS-JGqmsaE,29128
+futurehouse_client/models/app.py,sha256=TGoAeENNPc5mSBkMHjh-Z8VIlnaUNcoWUJLxUhRIkEE,31868
 futurehouse_client/models/client.py,sha256=n4HD0KStKLm6Ek9nL9ylP-bkK10yzAaD1uIDF83Qp_A,1828
-futurehouse_client/models/rest.py,sha256=AwPMcB1ruoqaI8NIhX2ZzN8UuX6XsaQ7uzeSE8EpwKk,1573
+futurehouse_client/models/rest.py,sha256=LDHs6dINdbiwHlLBBP1RFd43PgP7mCAAnSAr7-l_2Mw,2924
 futurehouse_client/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 futurehouse_client/utils/auth.py,sha256=tgWELjKfg8eWme_qdcRmc8TjQN9DVZuHHaVXZNHLchk,2960
 futurehouse_client/utils/general.py,sha256=A_rtTiYW30ELGEZlWCIArO7q1nEmqi8hUlmBRYkMQ_c,767
 futurehouse_client/utils/module_utils.py,sha256=aFyd-X-pDARXz9GWpn8SSViUVYdSbuy9vSkrzcVIaGI,4955
 futurehouse_client/utils/monitoring.py,sha256=UjRlufe67kI3VxRHOd5fLtJmlCbVA2Wqwpd4uZhXkQM,8728
-futurehouse_client-0.3.20.dev215.dist-info/licenses/LICENSE,sha256=oQ9ZHjUi-_6GfP3gs14FlPb0OlGwE1QCCKFGnJ4LD2I,11341
-futurehouse_client-0.3.20.dev215.dist-info/METADATA,sha256=A7E-dfE-qS76wT9wco1IFgjynobKJnRmiXQoNZ5_ESg,26805
-futurehouse_client-0.3.20.dev215.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-futurehouse_client-0.3.20.dev215.dist-info/top_level.txt,sha256=TRuLUCt_qBnggdFHCX4O_BoCu1j2X43lKfIZC-ElwWY,19
-futurehouse_client-0.3.20.dev215.dist-info/RECORD,,
+futurehouse_client-0.3.20.dev266.dist-info/licenses/LICENSE,sha256=oQ9ZHjUi-_6GfP3gs14FlPb0OlGwE1QCCKFGnJ4LD2I,11341
+futurehouse_client-0.3.20.dev266.dist-info/METADATA,sha256=qJo9JB9L8Myv_ErPaEdr4e96gJx3JNPIYbbg8MZ7Qoc,26805
+futurehouse_client-0.3.20.dev266.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+futurehouse_client-0.3.20.dev266.dist-info/top_level.txt,sha256=TRuLUCt_qBnggdFHCX4O_BoCu1j2X43lKfIZC-ElwWY,19
+futurehouse_client-0.3.20.dev266.dist-info/RECORD,,