feat: improve local file handling in overload

- Make local file access more explicit by throwing errors instead of silent fallbacks
- Add proper error handling for file not found and IO errors
- Improve version/environment handling with clear warnings
- Update docstrings to better document behavior

This change makes the behavior more predictable when use_local_files=True:
- Throws FileNotFoundError/IOError if local file can't be accessed
- Warns and uses remote when version_id/environment is specified
- No more silent fallbacks to remote API

Author: AlePouroullis

src/humanloop/overload.py

@@ -143,9 +143,19 @@ 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 or environment is specified, uses remote version with a warning
+    
     Args:
         client: The client to overload (PromptsClient or AgentsClient)
+        sync_client: The sync client for handling local files
         use_local_files: Whether to use local files
+        
+    Raises:
+        FileNotFoundError: If use_local_files is True and local file is not found
+        IOError: If use_local_files is True and local file cannot be read
     """
     original_call = client._call if hasattr(client, '_call') else client.call
     original_log = client._log if hasattr(client, '_log') else client.log
@@ -154,11 +164,24 @@ def overload_with_local_files(
     def _overload(self, function_name: str, **kwargs) -> PromptCallResponse:
         # Handle local files if enabled
         if use_local_files and "path" in kwargs:
-            # Normalize the path and get file content
-            normalized_path = sync_client._normalize_path(kwargs["path"])
-            file_content = sync_client.get_file_content(normalized_path, file_type)
-            if file_content is not None:
+            # Check if version_id or environment is specified
+            has_version_info = "version_id" in kwargs or "environment" in kwargs
+            
+            if has_version_info:
+                logger.warning(
+                    "Ignoring local file for %s as version_id or environment was specified. "
+                    "Using remote version instead.",
+                    kwargs["path"]
+                )
+            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
+                except (FileNotFoundError, IOError) as e:
+                    # Re-raise with more context
+                    raise type(e)(f"Failed to use local file for {kwargs['path']}: {str(e)}")
 
         try:
             if function_name == "call":

src/humanloop/sync/sync_client.py

@@ -54,31 +54,40 @@ def __init__(
         # Initialize metadata handler
         self.metadata = MetadataHandler(self.base_dir)
 
-    def _get_file_content_impl(self, path: str, file_type: FileType) -> Optional[str]:
+    def _get_file_content_impl(self, path: str, file_type: FileType) -> str:
         """Implementation of get_file_content without the cache decorator.
         
         This is the actual implementation that gets wrapped by lru_cache.
+        
+        Args:
+            path: The normalized path to the file (without extension)
+            file_type: The type of file (prompt or agent)
+            
+        Returns:
+            The file content
+            
+        Raises:
+            FileNotFoundError: If the file doesn't exist
+            IOError: If there's an error reading the file
         """
-        try:
-            # Construct path to local file
-            local_path = self.base_dir / path
-            # Add appropriate extension
-            local_path = local_path.parent / f"{local_path.stem}.{file_type}"
+        # Construct path to local file
+        local_path = self.base_dir / path
+        # Add appropriate extension
+        local_path = local_path.parent / f"{local_path.stem}.{file_type}"
+        
+        if not local_path.exists():
+            raise FileNotFoundError(f"Local file not found: {local_path}")
 
-            if local_path.exists():
-                # Read the file content
-                with open(local_path) as f:
-                    file_content = f.read()
-                logger.debug(f"Using local file content from {local_path}")
-                return file_content
-            else:
-                logger.warning(f"Local file not found: {local_path}, falling back to API")
-                return None
+        try:
+            # Read the file content
+            with open(local_path) as f:
+                file_content = f.read()
+            logger.debug(f"Using local file content from {local_path}")
+            return file_content
         except Exception as e:
-            logger.error(f"Error reading local file: {e}, falling back to API")
-            return None
+            raise IOError(f"Error reading local file {local_path}: {str(e)}")
 
-    def get_file_content(self, path: str, file_type: FileType) -> Optional[str]:
+    def get_file_content(self, path: str, file_type: FileType) -> str:
         """Get the content of a file from cache or filesystem.
         
         This method uses an LRU cache to store file contents. When the cache is full,
@@ -89,7 +98,11 @@ def get_file_content(self, path: str, file_type: FileType) -> Optional[str]:
             file_type: The type of file (prompt or agent)
             
         Returns:
-            The file content if found, None otherwise
+            The file content
+            
+        Raises:
+            FileNotFoundError: If the file doesn't exist
+            IOError: If there's an error reading the file
         """
         return self._get_file_content_impl(path, file_type)