futurehouse-client 0.3.19.dev129__py3-none-any.whl → 0.3.20.dev55__py3-none-any.whl

futurehouse_client/__init__.py

@@ -1,11 +1,22 @@
 from .clients.job_client import JobClient, JobNames
 from .clients.rest_client import RestClient as FutureHouseClient
-from .clients.rest_client import TaskResponse, TaskResponseVerbose
+from .models.app import (
+    FinchTaskResponse,
+    PhoenixTaskResponse,
+    PQATaskResponse,
+    TaskRequest,
+    TaskResponse,
+    TaskResponseVerbose,
+)
 
 __all__ = [
+    "FinchTaskResponse",
     "FutureHouseClient",
     "JobClient",
     "JobNames",
+    "PQATaskResponse",
+    "PhoenixTaskResponse",
+    "TaskRequest",
     "TaskResponse",
     "TaskResponseVerbose",
 ]

futurehouse_client/clients/rest_client.py

@@ -54,7 +54,11 @@ from futurehouse_client.models.app import (
     TaskResponse,
     TaskResponseVerbose,
 )
-from futurehouse_client.models.rest import ExecutionStatus
+from futurehouse_client.models.rest import (
+    ExecutionStatus,
+    WorldModel,
+    WorldModelResponse,
+)
 from futurehouse_client.utils.auth import RefreshingJWT
 from futurehouse_client.utils.general import gather_with_concurrency
 from futurehouse_client.utils.module_utils import (
@@ -100,6 +104,14 @@ class JobCreationError(RestClientError):
     """Raised when there's an error creating a job."""
 
 
+class WorldModelFetchError(RestClientError):
+    """Raised when there's an error fetching a world model."""
+
+
+class WorldModelCreationError(RestClientError):
+    """Raised when there's an error creating a world model."""
+
+
 class InvalidTaskDescriptionError(Exception):
     """Raised when the task description is invalid or empty."""
 
@@ -791,10 +803,9 @@ class RestClient:
                 pickled_env = cloudpickle.dumps(config.functional_environment)
                 encoded_pickle = base64.b64encode(pickled_env).decode("utf-8")
             files = []
+            ignore_parts = set(FILE_UPLOAD_IGNORE_PARTS) | set(config.ignore_dirs or [])
             for file_path in Path(config.path).rglob("*") if config.path else []:
-                if any(
-                    ignore in file_path.parts for ignore in FILE_UPLOAD_IGNORE_PARTS
-                ):
+                if any(ignore in file_path.parts for ignore in ignore_parts):
                     continue
 
                 if file_path.is_file():
@@ -1053,24 +1064,11 @@ class RestClient:
         status_url = None
 
         try:
-            # Upload all chunks except the last one in parallel
-            if total_chunks > 1:
-                self._upload_chunks_parallel(
-                    job_name,
-                    file_path,
-                    file_name,
-                    upload_id,
-                    total_chunks - 1,
-                    total_chunks,
-                )
-
-            # Upload the last chunk separately (handles assembly)
-            status_url = self._upload_final_chunk(
+            status_url = self._upload_chunks_parallel(
                 job_name,
                 file_path,
                 file_name,
                 upload_id,
-                total_chunks - 1,
                 total_chunks,
             )
 
@@ -1086,149 +1084,74 @@ class RestClient:
         file_path: Path,
         file_name: str,
         upload_id: str,
-        num_regular_chunks: int,
         total_chunks: int,
-    ) -> None:
-        """Upload chunks in parallel batches.
+    ) -> str | None:
+        """Upload all chunks in parallel batches, including the final chunk.
 
         Args:
             job_name: The key of the crow to upload to.
             file_path: The path to the file to upload.
             file_name: The name to use for the file.
             upload_id: The upload ID to use.
-            num_regular_chunks: Number of regular chunks (excluding final chunk).
             total_chunks: Total number of chunks.
 
-        Raises:
-            FileUploadError: If there's an error uploading any chunk.
-        """
-        if num_regular_chunks <= 0:
-            return
-
-        # Process chunks in batches
-        for batch_start in range(0, num_regular_chunks, self.MAX_CONCURRENT_CHUNKS):
-            batch_end = min(
-                batch_start + self.MAX_CONCURRENT_CHUNKS, num_regular_chunks
-            )
-
-            # Upload chunks in this batch concurrently
-            with ThreadPoolExecutor(max_workers=self.MAX_CONCURRENT_CHUNKS) as executor:
-                futures = {
-                    executor.submit(
-                        self._upload_single_chunk,
-                        job_name,
-                        file_path,
-                        file_name,
-                        upload_id,
-                        chunk_index,
-                        total_chunks,
-                    ): chunk_index
-                    for chunk_index in range(batch_start, batch_end)
-                }
-
-                for future in as_completed(futures):
-                    chunk_index = futures[future]
-                    try:
-                        future.result()
-                        logger.debug(
-                            f"Uploaded chunk {chunk_index + 1}/{total_chunks} of {file_name}"
-                        )
-                    except Exception as e:
-                        logger.error(f"Error uploading chunk {chunk_index}: {e}")
-                        raise FileUploadError(
-                            f"Error uploading chunk {chunk_index} of {file_name}: {e}"
-                        ) from e
-
-    def _upload_single_chunk(
-        self,
-        job_name: str,
-        file_path: Path,
-        file_name: str,
-        upload_id: str,
-        chunk_index: int,
-        total_chunks: int,
-    ) -> None:
-        """Upload a single chunk.
-
-        Args:
-            job_name: The key of the crow to upload to.
-            file_path: The path to the file to upload.
-            file_name: The name to use for the file.
-            upload_id: The upload ID to use.
-            chunk_index: The index of this chunk.
-            total_chunks: Total number of chunks.
+        Returns:
+            The status URL from the final chunk response, or None if no chunks.
 
         Raises:
-            Exception: If there's an error uploading the chunk.
+            FileUploadError: If there's an error uploading any chunk.
         """
-        with open(file_path, "rb") as f:
-            # Read the chunk from the file
-            f.seek(chunk_index * self.CHUNK_SIZE)
-            chunk_data = f.read(self.CHUNK_SIZE)
+        if total_chunks <= 0:
+            return None
 
-            # Prepare and send the chunk
-            with tempfile.NamedTemporaryFile() as temp_file:
-                temp_file.write(chunk_data)
-                temp_file.flush()
+        if total_chunks > 1:
+            num_regular_chunks = total_chunks - 1
+            for batch_start in range(0, num_regular_chunks, self.MAX_CONCURRENT_CHUNKS):
+                batch_end = min(
+                    batch_start + self.MAX_CONCURRENT_CHUNKS, num_regular_chunks
+                )
 
-                # Create form data
-                with open(temp_file.name, "rb") as chunk_file_obj:
-                    files = {
-                        "chunk": (
+                # Upload chunks in this batch concurrently
+                with ThreadPoolExecutor(
+                    max_workers=self.MAX_CONCURRENT_CHUNKS
+                ) as executor:
+                    futures = {
+                        executor.submit(
+                            self._upload_single_chunk,
+                            job_name,
+                            file_path,
                             file_name,
-                            chunk_file_obj,
-                            "application/octet-stream",
-                        )
+                            upload_id,
+                            chunk_index,
+                            total_chunks,
+                        ): chunk_index
+                        for chunk_index in range(batch_start, batch_end)
                     }
-                    data = {
-                        "file_name": file_name,
-                        "chunk_index": chunk_index,
-                        "total_chunks": total_chunks,
-                        "upload_id": upload_id,
-                    }
-
-                    # Send the chunk
-                    response = self.multipart_client.post(
-                        f"/v0.1/crows/{job_name}/upload-chunk",
-                        files=files,
-                        data=data,
-                    )
-                    response.raise_for_status()
-
-    def _upload_final_chunk(
-        self,
-        job_name: str,
-        file_path: Path,
-        file_name: str,
-        upload_id: str,
-        chunk_index: int,
-        total_chunks: int,
-    ) -> str | None:
-        """Upload the final chunk with retry logic for missing chunks.
-
-        Args:
-            job_name: The key of the crow to upload to.
-            file_path: The path to the file to upload.
-            file_name: The name to use for the file.
-            upload_id: The upload ID to use.
-            chunk_index: The index of the final chunk.
-            total_chunks: Total number of chunks.
 
-        Returns:
-            The status URL from the response.
-
-        Raises:
-            FileUploadError: If there's an error uploading the final chunk.
-        """
+                    for future in as_completed(futures):
+                        chunk_index = futures[future]
+                        try:
+                            future.result()
+                            logger.debug(
+                                f"Uploaded chunk {chunk_index + 1}/{total_chunks} of {file_name}"
+                            )
+                        except Exception as e:
+                            logger.error(f"Error uploading chunk {chunk_index}: {e}")
+                            raise FileUploadError(
+                                f"Error uploading chunk {chunk_index} of {file_name}: {e}"
+                            ) from e
+
+        # Upload the final chunk with retry logic
+        final_chunk_index = total_chunks - 1
         retries = 0
         max_retries = 3
-        retry_delay = 2.0  # seconds
+        retry_delay = 2.0
 
         while retries < max_retries:
             try:
                 with open(file_path, "rb") as f:
                     # Read the final chunk from the file
-                    f.seek(chunk_index * self.CHUNK_SIZE)
+                    f.seek(final_chunk_index * self.CHUNK_SIZE)
                     chunk_data = f.read(self.CHUNK_SIZE)
 
                     # Prepare and send the chunk
@@ -1247,7 +1170,7 @@ class RestClient:
                             }
                             data = {
                                 "file_name": file_name,
-                                "chunk_index": chunk_index,
+                                "chunk_index": final_chunk_index,
                                 "total_chunks": total_chunks,
                                 "upload_id": upload_id,
                             }
@@ -1274,7 +1197,7 @@ class RestClient:
                             status_url = response_data.get("status_url")
 
                             logger.debug(
-                                f"Uploaded final chunk {chunk_index + 1}/{total_chunks} of {file_name}"
+                                f"Uploaded final chunk {final_chunk_index + 1}/{total_chunks} of {file_name}"
                             )
                             return status_url
 
@@ -1293,6 +1216,62 @@ class RestClient:
             f"Failed to upload final chunk of {file_name} after {max_retries} retries"
         )
 
+    def _upload_single_chunk(
+        self,
+        job_name: str,
+        file_path: Path,
+        file_name: str,
+        upload_id: str,
+        chunk_index: int,
+        total_chunks: int,
+    ) -> None:
+        """Upload a single chunk.
+
+        Args:
+            job_name: The key of the crow to upload to.
+            file_path: The path to the file to upload.
+            file_name: The name to use for the file.
+            upload_id: The upload ID to use.
+            chunk_index: The index of this chunk.
+            total_chunks: Total number of chunks.
+
+        Raises:
+            Exception: If there's an error uploading the chunk.
+        """
+        with open(file_path, "rb") as f:
+            # Read the chunk from the file
+            f.seek(chunk_index * self.CHUNK_SIZE)
+            chunk_data = f.read(self.CHUNK_SIZE)
+
+            # Prepare and send the chunk
+            with tempfile.NamedTemporaryFile() as temp_file:
+                temp_file.write(chunk_data)
+                temp_file.flush()
+
+                # Create form data
+                with open(temp_file.name, "rb") as chunk_file_obj:
+                    files = {
+                        "chunk": (
+                            file_name,
+                            chunk_file_obj,
+                            "application/octet-stream",
+                        )
+                    }
+                    data = {
+                        "file_name": file_name,
+                        "chunk_index": chunk_index,
+                        "total_chunks": total_chunks,
+                        "upload_id": upload_id,
+                    }
+
+                    # Send the chunk
+                    response = self.multipart_client.post(
+                        f"/v0.1/crows/{job_name}/upload-chunk",
+                        files=files,
+                        data=data,
+                    )
+                    response.raise_for_status()
+
     @retry(
         stop=stop_after_attempt(MAX_RETRY_ATTEMPTS),
         wait=wait_exponential(multiplier=RETRY_MULTIPLIER, max=MAX_RETRY_WAIT),
@@ -1416,6 +1395,170 @@ class RestClient:
                 destination_path.unlink()  # Clean up partial file
             raise RestClientError(f"Error downloading file: {e!s}") 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,
+    )
+    def get_world_model(
+        self, world_model_id: UUID | None = None, name: str | None = None
+    ) -> WorldModelResponse:
+        """Get a world model snapshot by its ID or name.
+
+        Args:
+            world_model_id: The unique ID of the world model snapshot.
+            name: The name of the world model to get the latest version of.
+
+        Returns:
+            The requested world model snapshot.
+
+        Raises:
+            ValueError: If neither or both `world_model_id` and `name` are provided.
+            WorldModelFetchError: If the API call fails or the model is not found.
+        """
+        if not (world_model_id or name) or (world_model_id and name):
+            raise ValueError("Provide either 'world_model_id' or 'name', but not both.")
+
+        params = {
+            "id": str(world_model_id) if world_model_id else None,
+            "name": name,
+        }
+        # Filter out None values before making the request
+        params = {k: v for k, v in params.items() if v is not None}
+
+        try:
+            response = self.client.get("/v0.1/world-model", params=params)
+            response.raise_for_status()
+            return WorldModelResponse.model_validate(response.json())
+        except HTTPStatusError as e:
+            if e.response.status_code == codes.NOT_FOUND:
+                raise WorldModelFetchError(
+                    "World model not found with the specified identifier."
+                ) from e
+            raise WorldModelFetchError(
+                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
+
+    @retry(
+        stop=stop_after_attempt(MAX_RETRY_ATTEMPTS),
+        wait=wait_exponential(multiplier=RETRY_MULTIPLIER, max=MAX_RETRY_WAIT),
+        retry=retry_if_connection_error,
+    )
+    async def aget_world_model(
+        self, world_model_id: UUID | None = None, name: str | None = None
+    ) -> WorldModelResponse:
+        """Asynchronously get a world model snapshot by its ID or name.
+
+        Args:
+            world_model_id: The unique ID of the world model snapshot.
+            name: The name of the world model to get the latest version of.
+
+        Returns:
+            The requested world model snapshot.
+
+        Raises:
+            ValueError: If neither or both `world_model_id` and `name` are provided.
+            WorldModelFetchError: If the API call fails or the model is not found.
+        """
+        if not (world_model_id or name) or (world_model_id and name):
+            raise ValueError("Provide either 'world_model_id' or 'name', but not both.")
+
+        params = {
+            "id": str(world_model_id) if world_model_id else None,
+            "name": name,
+        }
+        params = {k: v for k, v in params.items() if v is not None}
+
+        try:
+            response = await self.async_client.get("/v0.1/world-model", params=params)
+            response.raise_for_status()
+            return WorldModelResponse.model_validate(response.json())
+        except HTTPStatusError as e:
+            if e.response.status_code == codes.NOT_FOUND:
+                raise WorldModelFetchError(
+                    "World model not found with the specified identifier."
+                ) from e
+            raise WorldModelFetchError(
+                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
+
+    @retry(
+        stop=stop_after_attempt(MAX_RETRY_ATTEMPTS),
+        wait=wait_exponential(multiplier=RETRY_MULTIPLIER, max=MAX_RETRY_WAIT),
+        retry=retry_if_connection_error,
+    )
+    def create_world_model(self, payload: WorldModel) -> UUID:
+        """Create a new, immutable world model snapshot.
+
+        Args:
+            payload: An instance of WorldModel with the snapshot's data.
+
+        Returns:
+            The UUID of the newly created world model.
+
+        Raises:
+            WorldModelCreationError: If the API call fails.
+        """
+        try:
+            response = self.client.post(
+                "/v0.1/world-models", json=payload.model_dump(mode="json")
+            )
+            response.raise_for_status()
+            # The server returns a raw UUID string in the body
+            return UUID(response.json())
+        except HTTPStatusError as e:
+            if e.response.status_code == codes.BAD_REQUEST:
+                raise WorldModelCreationError(
+                    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}"
+            ) from e
+        except Exception as e:
+            raise WorldModelCreationError(
+                f"An unexpected error occurred during world model creation: {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,
+    )
+    async def acreate_world_model(self, payload: WorldModel) -> UUID:
+        """Asynchronously create a new, immutable world model snapshot.
+
+        Args:
+            payload: An instance of WorldModel with the snapshot's data.
+
+        Returns:
+            The UUID of the newly created world model.
+
+        Raises:
+            WorldModelCreationError: If the API call fails.
+        """
+        try:
+            response = await self.async_client.post(
+                "/v0.1/world-models", json=payload.model_dump(mode="json")
+            )
+            response.raise_for_status()
+            return UUID(response.json())
+        except HTTPStatusError as e:
+            if e.response.status_code == codes.BAD_REQUEST:
+                raise WorldModelCreationError(
+                    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}"
+            ) from e
+        except Exception as e:
+            raise WorldModelCreationError(
+                f"An unexpected error occurred during world model creation: {e}"
+            ) from e
+
 
 def get_installed_packages() -> dict[str, str]:
     """Returns a dictionary of installed packages and their versions."""

futurehouse_client/models/app.py

@@ -365,6 +365,12 @@ class JobDeploymentConfig(BaseModel):
         "Can be None if we are deploying a functional environment (through the functional_environment parameter).",
     )
 
+    ignore_dirs: list[str] | None = Field(
+        default=None,
+        description="A list of directories to ignore when deploying the job. "
+        "This is a list of directories relative to the path parameter.",
+    )
+
     name: str | None = Field(
         default=None,
         description="The name of the crow job. If None, the crow job will be "
@@ -604,6 +610,10 @@ class RuntimeConfig(BaseModel):
         default=None,
         description="Optional job identifier for a continued job",
     )
+    world_model_id: UUID | None = Field(
+        default=None,
+        description="Optional world model identifier for the task",
+    )
 
     @field_validator("agent")
     @classmethod

futurehouse_client/models/rest.py

@@ -1,4 +1,6 @@
+from datetime import datetime
 from enum import StrEnum, auto
+from uuid import UUID
 
 from pydantic import BaseModel, JsonValue
 
@@ -34,3 +36,37 @@ class ExecutionStatus(StrEnum):
     @classmethod
     def terminal_states(cls) -> set["ExecutionStatus"]:
         return {cls.SUCCESS, cls.FAIL, cls.CANCELLED}
+
+
+class WorldModel(BaseModel):
+    """
+    Payload for creating a new world model snapshot.
+
+    This model is sent to the API.
+    """
+
+    content: str
+    prior: UUID | None = None
+    name: str | None = None
+    description: str | None = None
+    trajectory_id: UUID | None = None
+    model_metadata: JsonValue | None = None
+
+
+class WorldModelResponse(BaseModel):
+    """
+    Response model for a world model snapshot.
+
+    This model is received from the API.
+    """
+
+    id: UUID
+    prior: UUID | None
+    name: str
+    description: str | None
+    content: str
+    trajectory_id: UUID | None
+    email: str | None
+    model_metadata: JsonValue | None
+    enabled: bool
+    created_at: datetime

futurehouse_client/version.py

@@ -0,0 +1,21 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = ["__version__", "__version_tuple__", "version", "version_tuple"]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+else:
+    VERSION_TUPLE = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+
+__version__ = version = '0.3.20.dev55'
+__version_tuple__ = version_tuple = (0, 3, 20, 'dev55')