docs: expand normalize_path docstring with usage and examples

- Add detailed explanation of function's purpose and usage contexts\n- Document rationale for stripping leading/trailing slashes\n- Add comprehensive examples for different path formats\n- Reference SyncClient.pull usage for context

Author: AlePouroullis

src/humanloop/path_utils.py

@@ -2,7 +2,45 @@
 
 
 def normalize_path(path: str, strip_extension: bool = False) -> str:
-    """Normalize a path to the standard API format: path/to/resource, where resource can be a file or a directory."""
+    """Normalize a path to the standard Humanloop API format.
+
+    This function is primarily used when interacting with the Humanloop API to ensure paths
+    follow the standard format: 'path/to/resource' without leading/trailing slashes.
+    It's used in several contexts:
+    1. When pulling files from Humanloop to local filesystem (see SyncClient.pull)
+    2. When making API calls that reference files by path
+    3. When handling local file operations that need to match API path conventions
+
+    The function:
+    - Converts Windows backslashes to forward slashes
+    - Normalizes consecutive slashes
+    - Optionally strips file extensions (e.g. .prompt, .agent)
+    - Removes leading/trailing slashes to match API conventions
+
+    Leading/trailing slashes are stripped because the Humanloop API expects paths in the
+    format 'path/to/resource' without them. This is consistent with how the API stores
+    and references files, and ensures paths work correctly in both API calls and local
+    filesystem operations.
+
+    Args:
+        path: The path to normalize. Can be a Windows or Unix-style path.
+        strip_extension: If True, removes the file extension (e.g. .prompt, .agent)
+
+    Returns:
+        Normalized path string in the format 'path/to/resource'
+
+    Examples:
+        >>> normalize_path("path/to/file.prompt")
+        'path/to/file.prompt'
+        >>> normalize_path("path/to/file.prompt", strip_extension=True)
+        'path/to/file'
+        >>> normalize_path("\\windows\\style\\path.prompt")
+        'windows/style/path.prompt'
+        >>> normalize_path("/leading/slash/path/")
+        'leading/slash/path'
+        >>> normalize_path("multiple//slashes//path")
+        'multiple/slashes/path'
+    """
     # Handle backslashes for Windows paths before passing to PurePosixPath
     # This is needed because some backslash sequences are treated as escape chars
     path = path.replace("\\", "/")