futurehouse-client 0.3.20.dev225__tar.gz → 0.3.20.dev266__tar.gz

{futurehouse_client-0.3.20.dev225/futurehouse_client.egg-info → futurehouse_client-0.3.20.dev266}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: futurehouse-client
-Version: 0.3.20.dev225
+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.dev225 → futurehouse_client-0.3.20.dev266}/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
@@ -54,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,
 )
@@ -105,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."""
 
@@ -535,6 +557,52 @@ class RestClient:
             return verbose_response
         return JobNames.get_response_object_from_job(verbose_response.job_name)(**data)
 
+    @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 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),
@@ -927,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",
@@ -1787,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-0.3.20.dev225 → futurehouse_client-0.3.20.dev266}/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-0.3.20.dev225 → futurehouse_client-0.3.20.dev266}/futurehouse_client/models/client.py

@@ -27,13 +27,17 @@ class InitialState(BaseState):
 
 class ASVState(BaseState, Generic[T]):
     action: OpResult[T] = Field()
-    next_agent_state: Any = Field()
+    next_state: Any = Field()
     value: float = Field()
 
     @field_serializer("action")
     def serialize_action(self, action: OpResult[T]) -> dict:
         return action.to_dict()
 
+    @field_serializer("next_state")
+    def serialize_next_state(self, state: Any) -> str:
+        return str(state)
+
 
 class EnvResetState(BaseState):
     observations: list[Message] = Field()

{futurehouse_client-0.3.20.dev225 → futurehouse_client-0.3.20.dev266}/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-0.3.20.dev225 → futurehouse_client-0.3.20.dev266}/futurehouse_client/version.py

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

{futurehouse_client-0.3.20.dev225 → futurehouse_client-0.3.20.dev266/futurehouse_client.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: futurehouse-client
-Version: 0.3.20.dev225
+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.dev225 → futurehouse_client-0.3.20.dev266}/tests/test_rest.py

@@ -7,6 +7,7 @@ import tempfile
 import time
 import types
 from pathlib import Path
+from typing import cast
 from unittest.mock import MagicMock, mock_open, patch
 from uuid import UUID, uuid4
 
@@ -19,6 +20,8 @@ from futurehouse_client.clients.rest_client import (
     ProjectError,
     RestClient,
     RestClientError,
+    UserAgentRequestCreationError,
+    UserAgentRequestFetchError,
 )
 from futurehouse_client.models.app import (
     PhoenixTaskResponse,
@@ -27,7 +30,13 @@ from futurehouse_client.models.app import (
     TaskRequest,
     TaskResponseVerbose,
 )
-from futurehouse_client.models.rest import ExecutionStatus, WorldModel
+from futurehouse_client.models.rest import (
+    ExecutionStatus,
+    UserAgentRequestPostPayload,
+    UserAgentRequestStatus,
+    UserAgentResponsePayload,
+    WorldModel,
+)
 from pytest_subtests import SubTests
 
 ADMIN_API_KEY = os.environ["PLAYWRIGHT_ADMIN_API_KEY"]
@@ -78,6 +87,11 @@ def phoenix_task_req():
     )
 
 
+@pytest.fixture
+def running_trajectory_id(admin_client: RestClient, task_req: TaskRequest) -> str:
+    return admin_client.create_task(task_req)
+
+
 @pytest.mark.timeout(300)
 @pytest.mark.flaky(reruns=3)
 def test_futurehouse_dummy_env_crow(admin_client: RestClient, task_req: TaskRequest):
@@ -247,6 +261,41 @@ async def test_timeout_run_until_done_futurehouse_dummy_env_crow(
     )
 
 
+@pytest.mark.timeout(300)
+@pytest.mark.flaky(reruns=3)
+def test_cancel_task(admin_client: RestClient):
+    """Test successful task cancellation using MagicMock."""
+    task_id = "1c28bb94-efbf-442f-954c-f0d8ddb0cff5"
+
+    with (
+        patch.object(admin_client.client, "post") as mock_post,
+        patch.object(admin_client, "get_task") as mock_get_task,
+    ):
+        mock_response = MagicMock()
+        mock_response.raise_for_status.return_value = None
+        mock_post.return_value = mock_response
+
+        mock_task_response_running = MagicMock()
+        mock_task_response_running.status = "in progress"
+
+        mock_task_response_cancelled = MagicMock()
+        mock_task_response_cancelled.status = ExecutionStatus.CANCELLED.value
+
+        mock_get_task.side_effect = [
+            mock_task_response_running,
+            mock_task_response_cancelled,
+        ]
+
+        result = admin_client.cancel_task(task_id)
+
+        assert result is True
+
+        expected_url = f"/v0.1/trajectories/{task_id}/cancel"
+        mock_post.assert_called_once_with(expected_url)
+
+        assert mock_get_task.call_count == 2
+
+
 class TestParallelChunking:
     """Test suite for parallel chunk upload functionality."""
 
@@ -752,7 +801,7 @@ def test_world_model_create_and_get(admin_client: RestClient):
 class TestProjectOperations:
     @pytest.fixture
     def test_project_name(self):
-        return f"test-project-{int(time.time())}"
+        return f"test-project-{uuid4()}"
 
     def test_create_project_success(
         self, admin_client: RestClient, test_project_name: str
@@ -821,7 +870,7 @@ class TestProjectOperations:
 class TestAsyncProjectOperations:
     @pytest.fixture
     def test_project_name(self):
-        return f"test-async-project-{int(time.time())}"
+        return f"test-async-project-{uuid4()}"
 
     @pytest.mark.asyncio
     async def test_acreate_project_success(
@@ -873,3 +922,230 @@ class TestAsyncProjectOperations:
                 await admin_client.aadd_task_to_project(
                     fake_project_id, fake_trajectory_id
                 )
+
+
+@pytest.mark.timeout(300)
+@pytest.mark.flaky(reruns=3)
+def test_get_tasks_with_project_filter(admin_client: RestClient, task_req: TaskRequest):
+    """Test retrieving trajectories filtered by project_id using real API calls."""
+    project_name = f"e2e-trajectories-fetch-{uuid4()}"
+    project_id = admin_client.create_project(project_name)
+
+    trajectory_id = admin_client.create_task(task_req)
+    admin_client.add_task_to_project(UUID(project_id), trajectory_id)
+
+    while (task_status := admin_client.get_task(trajectory_id).status) in {
+        "queued",
+        "in progress",
+    }:
+        time.sleep(5)
+
+    trajectories = admin_client.get_tasks(project_id=UUID(project_id))
+
+    trajectory_ids = [t["id"] for t in trajectories]
+    assert trajectory_id in trajectory_ids
+
+
+@pytest.mark.timeout(300)
+@pytest.mark.flaky(reruns=3)
+@pytest.mark.asyncio
+async def test_aget_tasks_with_project_filter(
+    admin_client: RestClient, task_req: TaskRequest
+):
+    """Test async retrieving trajectories filtered by project_id using real API calls."""
+    project_name = f"e2e-trajectories-async-fetch-{uuid4()}"
+    project_id = await admin_client.acreate_project(project_name)
+
+    trajectory_id = await admin_client.acreate_task(task_req)
+    await admin_client.aadd_task_to_project(UUID(project_id), trajectory_id)
+
+    while True:
+        task = await admin_client.aget_task(trajectory_id)
+        if task.status not in {"queued", "in progress"}:
+            break
+        await asyncio.sleep(5)
+
+    trajectories = await admin_client.aget_tasks(project_id=UUID(project_id))
+
+    trajectory_ids = [t["id"] for t in trajectories]
+    assert trajectory_id in trajectory_ids
+
+
+class TestUserAgentRequestOperations:
+    """Test suite for synchronous User Agent Request operations."""
+
+    @pytest.mark.flaky(reruns=3)
+    def test_e2e_user_agent_request_flow(
+        self,
+        admin_client: RestClient,
+        running_trajectory_id: str,
+    ):
+        """Tests the full lifecycle: create, get, list, and respond."""
+        payload = UserAgentRequestPostPayload(
+            trajectory_id=running_trajectory_id,
+            request={"question": "Do you approve?"},
+        )
+        request_id = admin_client.create_user_agent_request(payload)
+        assert isinstance(request_id, UUID)
+
+        # 2. GET the created request
+        retrieved_req = admin_client.get_user_agent_request(request_id)
+        assert retrieved_req.id == request_id
+        assert str(retrieved_req.trajectory_id) == str(payload.trajectory_id)
+        assert retrieved_req.status == UserAgentRequestStatus.PENDING
+        assert retrieved_req.request == payload.request
+
+        # 3. LIST requests and find the created one
+        request_list = admin_client.list_user_agent_requests(
+            trajectory_id=UUID(running_trajectory_id),
+            request_status=UserAgentRequestStatus.PENDING,
+        )
+        assert isinstance(request_list, list)
+        assert any(req.id == request_id for req in request_list)
+
+        # 4. RESPOND to the request
+        response_payload = UserAgentResponsePayload(response={"answer": "Yes"})
+        admin_client.respond_to_user_agent_request(request_id, response_payload)
+
+        # 5. GET the request again to verify the response
+        responded_req = admin_client.get_user_agent_request(request_id)
+        assert responded_req.status == UserAgentRequestStatus.RESPONDED
+        assert responded_req.response == response_payload.response
+
+    def test_get_nonexistent_request_fails(self, admin_client: RestClient):
+        """Verifies that fetching a non-existent request raises an error."""
+        non_existent_id = uuid4()
+        with pytest.raises(UserAgentRequestFetchError):
+            admin_client.get_user_agent_request(non_existent_id)
+
+    def test_unauthorized_access_fails(self, pub_client: RestClient):
+        """Ensures a client with insufficient permissions cannot perform actions."""
+        # Using a public client that shouldn't have access
+        with pytest.raises((UserAgentRequestCreationError, PermissionError)):  # noqa: PT012
+            payload = UserAgentRequestPostPayload(
+                trajectory_id=uuid4(),
+                request={"data": "test"},
+            )
+            pub_client.create_user_agent_request(payload)
+
+        with pytest.raises((UserAgentRequestFetchError, PermissionError)):
+            # Attempt to fetch a request that the user doesn't own
+            pub_client.get_user_agent_request(uuid4())
+
+
+class TestAsyncUserAgentRequestOperations:
+    """Test suite for asynchronous User Agent Request operations."""
+
+    @pytest.mark.asyncio
+    async def test_async_expiring_e2e_user_agent_request_flow(
+        self,
+        admin_client: RestClient,
+        running_trajectory_id: str,
+    ):
+        """Tests the full async lifecycle: acreate, aget, alist, and arespond."""
+        payload = UserAgentRequestPostPayload(
+            trajectory_id=running_trajectory_id,
+            request={"question": "Async: Do you approve?"},
+            user_response_task=TaskRequest(
+                name=JobNames.from_string("dummy"),
+                query="Why would I follow up on this query?",
+            ).model_dump(mode="json"),
+            expires_in_seconds=10,
+        )
+
+        request_id = await admin_client.acreate_user_agent_request(payload)
+        assert isinstance(request_id, UUID)
+
+        retrieved_req = await admin_client.aget_user_agent_request(request_id)
+        assert retrieved_req.id == request_id
+        assert str(retrieved_req.trajectory_id) == str(payload.trajectory_id)
+        assert retrieved_req.status == UserAgentRequestStatus.PENDING
+
+        request_list = await admin_client.alist_user_agent_requests(
+            trajectory_id=UUID(running_trajectory_id)
+        )
+        assert isinstance(request_list, list)
+        assert any(req.id == request_id for req in request_list)
+
+        # ensure we allow it to expire so auto response can happen
+        await asyncio.sleep(10)
+
+        # now this should be expired
+        retrieved_req = await admin_client.aget_user_agent_request(request_id)
+        assert retrieved_req.status == UserAgentRequestStatus.EXPIRED
+
+        # we should also see the job having started -- along with the registration of the job in the
+        job_data = await admin_client.aget_task(
+            cast(str, retrieved_req.response_trajectory_id)
+        )
+        assert job_data.status == "in progress"
+
+        # 4. RESPOND to the request -- ensure nothing changes
+        ignored_response = {"answer": "Async Yes"}
+        response_payload = UserAgentResponsePayload(response=ignored_response)
+        await admin_client.arespond_to_user_agent_request(request_id, response_payload)
+
+        retrieved_req = await admin_client.aget_user_agent_request(request_id)
+        assert retrieved_req.response != ignored_response
+
+    @pytest.mark.asyncio
+    async def test_async_e2e_user_agent_request_flow(
+        self,
+        admin_client: RestClient,
+        running_trajectory_id: str,
+    ):
+        """Tests the full async lifecycle: acreate, aget, alist, and arespond."""
+        # 1. CREATE a request
+        payload = UserAgentRequestPostPayload(
+            trajectory_id=running_trajectory_id,
+            request={"question": "Async: Do you approve?"},
+            user_response_task=TaskRequest(
+                name=JobNames.from_string("dummy"),
+                query="Why would I follow up on this query?",
+            ).model_dump(mode="json"),
+        )
+
+        request_id = await admin_client.acreate_user_agent_request(payload)
+        assert isinstance(request_id, UUID)
+
+        # 2. GET the created request
+        retrieved_req = await admin_client.aget_user_agent_request(request_id)
+        assert retrieved_req.id == request_id
+        assert str(retrieved_req.trajectory_id) == str(payload.trajectory_id)
+        assert retrieved_req.status == UserAgentRequestStatus.PENDING
+
+        # 3. LIST requests and find the created one
+        request_list = await admin_client.alist_user_agent_requests(
+            trajectory_id=UUID(running_trajectory_id)
+        )
+        assert isinstance(request_list, list)
+        assert any(req.id == request_id for req in request_list)
+
+        # 4. RESPOND to the request
+        response_payload = UserAgentResponsePayload(response={"answer": "Async Yes"})
+        await admin_client.arespond_to_user_agent_request(request_id, response_payload)
+
+        # 5. GET the request again to verify the response
+        responded_req = await admin_client.aget_user_agent_request(request_id)
+        assert responded_req.status == UserAgentRequestStatus.RESPONDED
+        assert responded_req.response == response_payload.response
+
+    @pytest.mark.asyncio
+    async def test_aget_nonexistent_request_fails(self, admin_client: RestClient):
+        """Verifies fetching a non-existent request asynchronously raises an error."""
+        non_existent_id = uuid4()
+        with pytest.raises(UserAgentRequestFetchError):
+            await admin_client.aget_user_agent_request(non_existent_id)
+
+    @pytest.mark.asyncio
+    async def test_async_unauthorized_access_fails(self, pub_client: RestClient):
+        """Ensures an unauthorized client fails on async methods."""
+        with pytest.raises((UserAgentRequestCreationError, PermissionError)):  # noqa: PT012
+            payload = UserAgentRequestPostPayload(
+                trajectory_id=uuid4(),
+                request={"data": "test"},
+            )
+            await pub_client.acreate_user_agent_request(payload)
+
+        with pytest.raises((UserAgentRequestFetchError, PermissionError)):
+            await pub_client.aget_user_agent_request(uuid4())