add environment and path filter to pull operation

Author: AlePouroullis

src/humanloop/client.py

@@ -100,6 +100,7 @@ def __init__(
         opentelemetry_tracer_provider: Optional[TracerProvider] = None,
         opentelemetry_tracer: Optional[Tracer] = None,
         use_local_files: bool = False,
+        files_directory: str = "humanloop",
     ):
         """
         Extends the base client with custom evaluation utilities and
@@ -120,7 +121,7 @@ def __init__(
         )
 
         self.use_local_files = use_local_files
-        self.sync_client = SyncClient(client=self)
+        self._sync_client = SyncClient(client=self, base_dir=files_directory)
         eval_client = ExtendedEvalsClient(client_wrapper=self._client_wrapper)
         eval_client.client = self
         self.evaluations = eval_client
@@ -359,20 +360,26 @@ def agent():
             attributes=attributes,
         )
 
-    def pull(self) -> List[str]:
+    def pull(self, 
+        environment: str | None = None, 
+        path: str | None = None
+    ) -> List[str]:
         """Pull prompt and agent files from Humanloop to local filesystem.
 
         This method will:
         1. Fetch all prompt and agent files from your Humanloop workspace
-        2. Save them to the local filesystem in a 'humanloop/' directory
+        2. Save them to the local filesystem using the client's files_directory (set during initialization)
         3. Maintain the same directory structure as in Humanloop
         4. Add appropriate file extensions (.prompt or .agent)
 
+        By default, the operation will overwrite existing files with the latest version from Humanlooop
+        but will not delete local files that don't exist in the remote workspace.
+
         Currently only supports syncing prompt and agent files. Other file types will be skipped.
 
         The files will be saved with the following structure:
         ```
-        humanloop/
+        {files_directory}/
         ├── prompts/
         │   ├── my_prompt.prompt
         │   └── nested/
@@ -381,11 +388,16 @@ def pull(self) -> List[str]:
             └── my_agent.agent
         ```
 
-        :return: List of successfully processed file paths
+        :param environment: The environment to pull the files from.
+        :param path: The path to the files to pull on the Humanloop workspace. Can be a directory or a specific file.
+        :return: List of successfully processed file paths.
         """
-        return self.sync_client.pull()
-
+        return self._sync_client.pull(
+            environment=environment,
+            path=path
+        )
 
+ 
 class AsyncHumanloop(AsyncBaseHumanloop):
     """
     See docstring of AsyncBaseHumanloop.

src/humanloop/sync/sync_client.py

@@ -65,12 +65,26 @@ def _save_serialized_file(self, serialized_content: str, file_path: str, file_ty
             logger.error(f"Failed to sync {file_type} {file_path}: {str(e)}")
             raise
 
-    def pull(self) -> List[str]:
+    def pull(self, 
+            environment: str | None = None, 
+            directory: str | None = None,
+            path: str | None = None,
+        ) -> List[str]:
         """Sync prompt and agent files from Humanloop to local filesystem.
 
+        If `path` is provided, only the file at that path will be pulled.
+        If `directory` is provided, all files in that directory will be pulled (if both `path` and `directory` are provided, `path` will take precedence).
+        If `environment` is provided, the files will be pulled from that environment.
+
+        Args: 
+            environment: The environment to pull the files from.
+            directory: The directory to pull the files from.
+            path: The path of a specific file to pull from.
+
         Returns:
             List of successfully processed file paths
         """
+
         successful_files = []
         failed_files = []
         page = 1
@@ -80,7 +94,8 @@ def pull(self) -> List[str]:
                 response = self.client.files.list_files(
                     type=["prompt", "agent"], 
                     page=page,
-                    include_content=True
+                    include_content=True,
+                    environment=environment
                 )
 
                 if len(response.records) == 0:
@@ -93,6 +108,10 @@ def pull(self) -> List[str]:
                         logger.warning(f"Skipping unsupported file type: {file.type}")
                         continue
 
+                    if not file.path.startswith(path):
+                        # Filter by path
+                        continue
+
                     # Skip if no content
                     if not getattr(file, "content", None):
                         logger.warning(f"No content found for {file.type} {getattr(file, 'id', '<unknown>')}")

tests/sync/test_sync.py

@@ -140,6 +140,10 @@ def test_overload_log_with_local_files(humanloop_client: Humanloop, test_file_st
     1. Create files in remote (via test_file_structure fixture)
     2. Pull files locally
     3. Test logging using the pulled files
+
+    :param humanloop_client: The Humanloop client with local files enabled
+    :param test_file_structure: List of test files created in remote
+    :param cleanup_local_files: Fixture to clean up local files after test
     """
     # First pull the files locally
     humanloop_client.pull()