docs: improve comment clarity

Author: AlePouroullis

src/humanloop/overload.py

@@ -91,7 +91,23 @@ def _handle_local_files(
     client: Any,
     sync_client: SyncClient,
 ) -> Dict[str, Any]:
-    """Handle local file loading."""
+    """Load prompt/agent file content from local filesystem into API request.
+
+    Retrieves the file content at the specified path and adds it to kwargs
+    under the appropriate field ('prompt' or 'agent'), allowing local files
+    to be used in API calls instead of fetching from Humanloop API.
+
+    Args:
+        kwargs: API call arguments
+        client: Client instance making the call
+        sync_client: SyncClient handling local file operations
+
+    Returns:
+        Updated kwargs with file content in prompt/agent field
+
+    Raises:
+        HumanloopRuntimeError: On validation or file loading failures
+    """
     if "id" in kwargs:
         raise HumanloopRuntimeError("Can only specify one of `id` or `path`")
 
@@ -170,11 +186,19 @@ def _overload_log(self: Any, sync_client: Optional[SyncClient], use_local_files:
 
         kwargs = _handle_tracing_context(kwargs, self)
 
-        # Handle local files for Prompts and Agents clients
+        # Handle loading files from local filesystem when using Prompts and Agents clients
+        # This enables users to define prompts/agents in local files rather than fetching from the Humanloop API
         if use_local_files and _get_file_type_from_client(self) in SyncClient.SERIALIZABLE_FILE_TYPES:
+            # Developer note: sync_client should always be provided during SDK initialization when
+            # use_local_files=True. If we hit this error, there's likely an initialization issue
+            # in Humanloop.__init__ where the sync_client wasn't properly created or passed to the
+            # overload_client function.
             if sync_client is None:
                 logger.error("sync_client is None but client has log method and use_local_files=%s", use_local_files)
-                raise HumanloopRuntimeError("sync_client is required for clients that support local file operations")
+                raise HumanloopRuntimeError(
+                    "SDK initialization error: sync_client is missing but required for local file operations. "
+                    "This is likely a bug in the SDK initialization - please report this issue to the Humanloop team."
+                )
             kwargs = _handle_local_files(kwargs, self, sync_client)
 
         kwargs, eval_callback = _handle_evaluation_context(kwargs)
@@ -194,6 +218,7 @@ def _overload_call(self: Any, sync_client: Optional[SyncClient], use_local_files
     try:
         kwargs = _handle_tracing_context(kwargs, self)
         if use_local_files and _get_file_type_from_client(self) in SyncClient.SERIALIZABLE_FILE_TYPES:
+            # Same sync_client requirement as in _overload_log - see developer note there
             if sync_client is None:
                 logger.error("sync_client is None but client has call method and use_local_files=%s", use_local_files)
                 raise HumanloopRuntimeError("sync_client is required for clients that support call operations")

src/humanloop/path_utils.py

@@ -10,5 +10,6 @@ def normalize_path(path: str, strip_extension: bool = False) -> str:
     if strip_extension:
         path_obj = path_obj.with_suffix("")
 
-    # Use as_posix() to normalize separators consistently
+    # Convert path to string with forward slashes, regardless of OS
+    # This ensures consistent path format (e.g., "path/to/resource") across Windows/Unix
     return path_obj.as_posix()

src/humanloop/sync/sync_client.py

@@ -12,7 +12,11 @@
 if TYPE_CHECKING:
     from humanloop.base_client import BaseHumanloop
 
-# Set up logging
+# Set up isolated logger for sync operations
+# This logger uses the "humanloop.sdk.sync" namespace, separate from the main client's logger,
+# allowing CLI commands and other consumers to control sync logging verbosity independently.
+# This approach ensures that increasing verbosity for sync operations doesn't affect
+# other components of the system.
 logger = logging.getLogger("humanloop.sdk.sync")
 logger.setLevel(logging.INFO)
 console_handler = logging.StreamHandler()
@@ -80,18 +84,25 @@ def __init__(
         cache_size: int = DEFAULT_CACHE_SIZE,
         log_level: int = logging.WARNING,
     ):
-        """
+        """Initialize the SyncClient.
+
         Parameters
         ----------
         client: Humanloop client instance
         base_dir: Base directory for synced files (default: "humanloop")
         cache_size: Maximum number of files to cache (default: DEFAULT_CACHE_SIZE)
         log_level: Log level for logging (default: WARNING)
+            Note: The SyncClient uses an isolated logger (humanloop.sdk.sync) separate from
+            the main Humanloop client logger. This allows controlling the verbosity of
+            sync operations independently from other client operations, which is particularly
+            useful in CLI contexts where users may want detailed sync logs without affecting
+            the main client's log level.
         """
         self.client = client
         self.base_dir = Path(base_dir)
         self._cache_size = cache_size
 
+        # Set log level for the isolated SyncClient logger
         logger.setLevel(log_level)
 
         # Create a new cached version of get_file_content with the specified cache size
@@ -156,14 +167,13 @@ def clear_cache(self) -> None:
         """Clear the LRU cache."""
         self.get_file_content.cache_clear()  # type: ignore [attr-defined]
 
-
     def is_file(self, path: str) -> bool:
         """Check if the path is a file by checking for .{file_type} extension for serializable file types.
-        
+
         Files are identified by having a supported extension (.prompt or .agent).
         This method performs case-insensitive comparison and handles whitespace.
 
-        Returns: 
+        Returns:
             bool: True if the path ends with a supported file extension
         """
         clean_path = path.strip().lower()  # Convert to lowercase for case-insensitive comparison