Improve overloading and warnings; content -> raw file content

Author: AlePouroullis

src/humanloop/overload.py

@@ -2,7 +2,7 @@
 import logging
 import types
 import warnings
-from typing import TypeVar, Union, Literal, Optional
+from typing import TypeVar, Union
 from pathlib import Path
 from humanloop.context import (
     get_decorator_context,
@@ -143,10 +143,25 @@ def overload_with_local_files(
 ) -> Union[PromptsClient, AgentsClient]:
     """Overload call and log methods to handle local files when use_local_files is True.
     
-    When use_local_files is True:
-    - If only path is specified (no version_id or environment), attempts to use local file
-    - If local file is not found or cannot be read, raises an error
-    - If version_id and/or environment is specified, uses remote version with a warning
+    When use_local_files is True, the following prioritization strategy is used:
+    1. Direct Parameters: If {file_type} parameters are provided directly (as a PromptKernelRequestParams or AgentKernelRequestParams object),
+       these take precedence and the local file is ignored.
+    2. Version/Environment: If version_id or environment is specified, the remote version is used instead
+       of the local file.
+    3. Local File: If neither of the above are specified, attempts to use the local file at the given path.
+    
+    For example, with a prompt client:
+    - If prompt={model: "gpt-4", ...} is provided, uses those parameters directly
+    - If version_id="123" is provided, uses that remote version
+    - Otherwise, tries to load from the local file at the given path
+    
+    Args:
+        client: The client to overload (PromptsClient or AgentsClient)
+        sync_client: The sync client used for file operations
+        use_local_files: Whether to enable local file handling
+        
+    Returns:
+        The client with overloaded methods
         
     Raises:
         HumanloopRuntimeError: If use_local_files is True and local file cannot be accessed
@@ -156,28 +171,34 @@ def overload_with_local_files(
     file_type = _get_file_type_from_client(client)
 
     def _overload(self, function_name: str, **kwargs) -> PromptCallResponse:
-        if "id" and "path" in kwargs: 
+        if "id" in kwargs and "path" in kwargs: 
             raise HumanloopRuntimeError(f"Can only specify one of `id` or `path` when {function_name}ing a {file_type}")
         # Handle local files if enabled
         if use_local_files and "path" in kwargs:
             # Check if version_id or environment is specified
             has_version_info = "version_id" in kwargs or "environment" in kwargs
+            normalized_path = sync_client._normalize_path(kwargs["path"])
 
             if has_version_info:
-                warnings.warn(
-                    f"Ignoring local file for {kwargs['path']} as version_id or environment was specified. "
-                    "Using remote version instead.",
-                    UserWarning
+                logger.warning(
+                    f"Ignoring local file for `{normalized_path}` as version_id or environment was specified. "
+                    "Using remote version instead."
                 )
             else:
                 # Only use local file if no version info is specified
-                normalized_path = sync_client._normalize_path(kwargs["path"])
                 try:
-                    file_content = sync_client.get_file_content(normalized_path, file_type)
-                    kwargs[file_type] = file_content
+                    # If file_type is already specified in kwargs, it means user provided a PromptKernelRequestParams object
+                    if file_type in kwargs and not isinstance(kwargs[file_type], str):
+                        logger.warning(
+                            f"Ignoring local file for `{normalized_path}` as {file_type} parameters were directly provided. "
+                            "Using provided parameters instead."
+                        )
+                    else:
+                        file_content = sync_client.get_file_content(normalized_path, file_type)
+                        kwargs[file_type] = file_content
                 except (HumanloopRuntimeError) as e:
                     # Re-raise with more context
-                    raise HumanloopRuntimeError(f"Failed to use local file for {kwargs['path']}: {str(e)}")
+                    raise HumanloopRuntimeError(f"Failed to use local file for `{normalized_path}`: {str(e)}")
 
         try:
             if function_name == "call":

src/humanloop/sync/sync_client.py

@@ -65,7 +65,7 @@ def _get_file_content_impl(self, path: str, file_type: FileType) -> str:
             file_type: The type of file (Prompt or Agent)
             
         Returns:
-            The file content
+            The raw file content
             
         Raises:
             HumanloopRuntimeError: If the file doesn't exist or can't be read
@@ -79,7 +79,7 @@ def _get_file_content_impl(self, path: str, file_type: FileType) -> str:
             raise HumanloopRuntimeError(f"Local file not found: {local_path}")
 
         try:
-            # Read the file content
+            # Read the raw file content
             with open(local_path) as f:
                 file_content = f.read()
             logger.debug(f"Using local file content from {local_path}")
@@ -88,7 +88,7 @@ def _get_file_content_impl(self, path: str, file_type: FileType) -> str:
             raise HumanloopRuntimeError(f"Error reading local file {local_path}: {str(e)}")
 
     def get_file_content(self, path: str, file_type: FileType) -> str:
-        """Get the content of a file from cache or filesystem.
+        """Get the raw file content of a file from cache or filesystem.
         
         This method uses an LRU cache to store file contents. When the cache is full,
         the least recently accessed files are automatically removed to make space.
@@ -98,7 +98,7 @@ def get_file_content(self, path: str, file_type: FileType) -> str:
             file_type: The type of file (Prompt or Agent)
             
         Returns:
-            The file content
+            The raw file content
             
         Raises:
             HumanloopRuntimeError: If the file doesn't exist or can't be read
@@ -153,7 +153,7 @@ def _save_serialized_file(self, serialized_content: str, file_path: str, file_ty
         """Save serialized file to local filesystem.
 
         Args:
-            serialized_content: The content to save
+            serialized_content: The raw file content to save
             file_path: The path to save the file to
             file_type: The type of file (Prompt or Agent)
 
@@ -169,7 +169,7 @@ def _save_serialized_file(self, serialized_content: str, file_path: str, file_ty
             # Add file type extension
             new_path = full_path.parent / f"{full_path.stem}.{file_type}"
 
-            # Write content to file
+            # Write raw file content to file
             with open(new_path, "w") as f:
                 f.write(serialized_content)
 
@@ -195,16 +195,16 @@ def _pull_file(self, path: str, environment: str | None = None) -> None:
         file = self.client.files.retrieve_by_path(
             path=path, 
             environment=environment,
-            include_content=True
+            include_raw_file_content=True
         )
 
         if file.type not in ["prompt", "agent"]:
             raise ValueError(f"Unsupported file type: {file.type}")
 
-        self._save_serialized_file(file.content, file.path, file.type)
+        self._save_serialized_file(file.raw_file_content, file.path, file.type)
 
     def _pull_directory(self, 
-            directory: str | None = None,    
+            path: str | None = None,    
             environment: str | None = None, 
         ) -> List[str]:
         """Sync Prompt and Agent files from Humanloop to local filesystem.
@@ -231,9 +231,9 @@ def _pull_directory(self,
                 response = self.client.files.list_files(
                     type=["prompt", "agent"], 
                     page=page,
-                    include_content=True,
+                    include_raw_file_content=True,
                     environment=environment,
-                    directory=directory
+                    path=path
                 )
 
                 if len(response.records) == 0:
@@ -246,13 +246,13 @@ def _pull_directory(self,
                         logger.warning(f"Skipping unsupported file type: {file.type}")
                         continue
 
-                    # Skip if no content
-                    if not getattr(file, "content", None):
+                    # Skip if no raw file content
+                    if not getattr(file, "raw_file_content", None):
                         logger.warning(f"No content found for {file.type} {getattr(file, 'id', '<unknown>')}")
                         continue
 
                     try:
-                        self._save_serialized_file(file.content, file.path, file.type)
+                        self._save_serialized_file(file.raw_file_content, file.path, file.type)
                         successful_files.append(file.path)
                     except Exception as e:
                         failed_files.append(file.path)
@@ -275,7 +275,7 @@ def pull(self, path: str | None = None, environment: str | None = None) -> List[
         """Pull files from Humanloop to local filesystem.
 
         If the path ends with .prompt or .agent, pulls that specific file.
-        Otherwise, pulls all files under the specified directory path.
+        Otherwise, pulls all files under the specified path.
         If no path is provided, pulls all files from the root.
 
         Args: