Rename base_dir to local_files_directory in CLI for consistency + docs cleanup

Author: AlePouroullis

src/humanloop/cli/__main__.py

@@ -99,8 +99,9 @@ def common_options(f: Callable) -> Callable:
         show_default=False,
     )
     @click.option(
-        "--base-dir",
-        help="Base directory for pulled files (default: humanloop/)",
+        "--local-files-directory",
+        "--local-dir",
+        help="Directory (relative to the current working directory) where Humanloop files are stored locally (default: humanloop/).",
         default="humanloop",
         type=click.Path(),
     )
@@ -151,7 +152,7 @@ def cli():  # Does nothing because used as a group for other subcommands (pull,
     "-p",
     help="Path in the Humanloop workspace to pull from (file or directory). You can pull an entire directory (e.g. 'my/directory') "
     "or a specific file (e.g. 'my/directory/my_prompt.prompt'). When pulling a directory, all files within that directory and its subdirectories will be included. "
-    "If not specified, pulls from the root of the workspace.",
+    "If not specified, pulls from the root of the remote workspace.",
     default=None,
 )
 @click.option(
@@ -179,7 +180,7 @@ def pull(
     environment: Optional[str],
     api_key: Optional[str],
     env_file: Optional[str],
-    base_dir: str,
+    local_files_directory: str,
     base_url: Optional[str],
     verbose: bool,
     quiet: bool,
@@ -189,13 +190,13 @@ def pull(
     \b
     This command will:
     1. Fetch Prompt and Agent files from your Humanloop workspace
-    2. Save them to your local filesystem (default directory: humanloop/)
+    2. Save them to your local filesystem (directory specified by --local-files-directory, default: humanloop/)
     3. Maintain the same directory structure as in Humanloop
     4. Add appropriate file extensions (.prompt or .agent)
 
     \b
-    The files will be saved with the following structure:
-    humanloop/
+    For example, with the default --local-files-directory=humanloop, files will be saved as:
+    ./humanloop/
     ├── my_project/
     │   ├── prompts/
     │   │   ├── my_prompt.prompt
@@ -207,12 +208,17 @@ def pull(
         └── prompts/
             └── other_prompt.prompt
 
+    \b
+    If you specify --local-files-directory=data/humanloop, files will be saved in ./data/humanloop/ instead.
+
     If a file exists both locally and in the Humanloop workspace, the local file will be overwritten
     with the version from Humanloop. Files that only exist locally will not be affected.
 
     Currently only supports syncing Prompt and Agent files. Other file types will be skipped."""
     client = get_client(api_key, env_file, base_url)
-    sync_client = SyncClient(client, base_dir=base_dir, log_level=logging.DEBUG if verbose else logging.WARNING)
+    sync_client = SyncClient(
+        client, base_dir=local_files_directory, log_level=logging.DEBUG if verbose else logging.WARNING
+    )
 
     click.echo(click.style("Pulling files from Humanloop...", fg=INFO_COLOR))
     click.echo(click.style(f"Path: {path or '(root)'}", fg=INFO_COLOR))

src/humanloop/client.py

@@ -131,7 +131,13 @@ def __init__(
         opentelemetry_tracer_provider: Optional tracer provider for telemetry
         opentelemetry_tracer: Optional tracer for telemetry
         use_local_files: Whether to use local files for prompts and agents
-        local_files_directory: Directory for local files (default: "humanloop")
+        local_files_directory: Base directory where local prompt and agent files are stored (default: "humanloop").
+                      This is relative to the current working directory. For example:
+                      - "humanloop" will look for files in "./humanloop/"
+                      - "data/humanloop" will look for files in "./data/humanloop/"
+                      When using paths in the API, they must be relative to this directory. For example,
+                      if local_files_directory="humanloop" and you have a file at "humanloop/samples/test.prompt",
+                      you would reference it as "samples/test" in your code.
         cache_size: Maximum number of files to cache when use_local_files is True (default: DEFAULT_CACHE_SIZE).
                    This parameter has no effect if use_local_files is False.
         """
@@ -389,40 +395,50 @@ def agent():
             attributes=attributes,
         )
 
-    def pull(self, environment: str | None = None, path: str | None = None) -> Tuple[List[str], List[str]]:
+    def pull(self, path: str | None = None, environment: str | None = None) -> Tuple[List[str], List[str]]:
         """Pull Prompt and Agent files from Humanloop to local filesystem.
 
         This method will:
         1. Fetch Prompt and Agent files from your Humanloop workspace
-        2. Save them to the local filesystem using the client's files_directory (set during initialization)
+        2. Save them to your local filesystem (directory specified by `local_files_directory`, default: "humanloop")
         3. Maintain the same directory structure as in Humanloop
-        4. Add appropriate file extensions (.prompt or .agent)
+        4. Add appropriate file extensions (`.prompt` or `.agent`)
 
         The path parameter can be used in two ways:
         - If it points to a specific file (e.g. "path/to/file.prompt" or "path/to/file.agent"), only that file will be pulled
-        - If it points to a directory (e.g. "path/to/directory"), all Prompt and Agent files in that directory will be pulled
+        - If it points to a directory (e.g. "path/to/directory"), all Prompt and Agent files in that directory and its subdirectories will be pulled
         - If no path is provided, all Prompt and Agent files will be pulled
 
         The operation will overwrite existing files with the latest version from Humanloop
         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.
+        Currently only supports syncing Prompt and Agent files. Other file types will be skipped.
 
-        The files will be saved with the following structure:
+        For example, with the default `local_files_directory="humanloop"`, files will be saved as:
         ```
-        {files_directory}/
-        ├── prompts/
-        │   ├── my_prompt.prompt
-        │   └── nested/
-        │       └── another_prompt.prompt
-        └── agents/
-            └── my_agent.agent
+        ./humanloop/
+        ├── my_project/
+        │   ├── prompts/
+        │   │   ├── my_prompt.prompt
+        │   │   └── nested/
+        │   │       └── another_prompt.prompt
+        │   └── agents/
+        │       └── my_agent.agent
+        └── another_project/
+            └── prompts/
+                └── other_prompt.prompt
         ```
 
-        :param environment: The environment to pull the files from.
+        If you specify `local_files_directory="data/humanloop"`, files will be saved in ./data/humanloop/ instead.
+
         :param path: Optional path to either a specific file (e.g. "path/to/file.prompt") or a directory (e.g. "path/to/directory").
                     If not provided, all Prompt and Agent files will be pulled.
-        :return: List of successfully processed file paths.
+        :param environment: The environment to pull the files from.
+        :return: Tuple of two lists:
+             - First list contains paths of successfully synced files
+             - Second list contains paths of files that failed to sync (due to API errors, missing content,
+               or filesystem issues)
+        :raises HumanloopRuntimeError: If there's an error communicating with the API
         """
         return self._sync_client.pull(environment=environment, path=path)
 

src/humanloop/sync/sync_client.py

@@ -163,8 +163,8 @@ def _normalize_path(self, path: str) -> str:
         # Convert to Path object to handle platform-specific separators
         path_obj = Path(path)
 
-        # Paths are considered absolute on unix-like systems if they start with a forward slash.
-        # This is because we want to ensure seamless toggling between the local and remote filesystems.
+        # Reject absolute paths to ensure all paths are relative to base_dir.
+        # This maintains consistency with the remote filesystem where paths are relative to project root.
         if path_obj.is_absolute():
             raise HumanloopRuntimeError(
                 f"Absolute paths are not supported: `{path}`. "
@@ -329,7 +329,7 @@ def pull(self, path: str | None = None, environment: str | None = None) -> Tuple
         Returns:
             Tuple of two lists:
             - First list contains paths of successfully synced files
-            - Second list contains paths of files that failed to sync
+            - Second list contains paths of files that failed to sync (e.g. failed to write to disk or missing raw content)
 
         Raises:
             HumanloopRuntimeError: If there's an error communicating with the API