ml-dash 0.6.0__py3-none-any.whl → 0.6.2__py3-none-any.whl

ml_dash/files.py

@@ -6,6 +6,7 @@ Provides fluent API for file upload, download, list, and delete operations.
 
 import hashlib
 import mimetypes
+import fnmatch
 from typing import Dict, Any, List, Optional, Union, TYPE_CHECKING
 from pathlib import Path
 
@@ -18,38 +19,69 @@ class FileBuilder:
     Fluent interface for file operations.
 
     Usage:
-        # Upload file
-        experiment.files(file_path="./model.pt", prefix="/models").save()
+        # Upload existing file from disk
+        dxp.files("models").upload("./local_model.pt")
+        dxp.files("checkpoints").upload("./model.pt", to="latest.pt")
+
+        # Save objects as files (using keyword dir argument)
+        dxp.files(dir="models").save_torch(model, to="checkpoint.pt")
+        dxp.files(dir="configs").save_json({"lr": 0.001}, to="config.json")
+        dxp.files(dir="data").save_blob(b"binary data", to="data.bin")
 
         # List files
-        files = experiment.files().list()
-        files = experiment.files(prefix="/models").list()
+        files = experiment.files(dir="some/location").list()
+        files = experiment.files(dir="models").list()
 
         # Download file
-        experiment.files(file_id="123").download()
-        experiment.files(file_id="123", dest_path="./model.pt").download()
-
-        # Delete file
-        experiment.files(file_id="123").delete()
+        dxp.files("some.text").download()
+        dxp.files("some.text").download(to="./model.pt")
+
+        # Download files via glob pattern
+        file_paths = experiment.files("images").list("*.png")
+        dxp.files("images").download("*.png")
+
+        # Delete files
+        dxp.files("some.text").delete()
+
+        # Check if file exists
+        if dxp.files("config.json").exists():
+            config = dxp.files("config.json").read_text()
+
+        # Read file content as text
+        config_yaml = dxp.files("configs/view.yaml").read_text()
+
+    Specific Save Methods:
+        experiment.files.save_text("content", to="view.yaml")
+        experiment.files.save_json(dict(hey="yo"), to="config.json")
+        experiment.files.save_blob(b"xxx", to="data.bin")
+        experiment.files.save_torch(model, to="model.pt")
+        experiment.files.save_pkl(data, to="data.pkl")
+        experiment.files.save_fig(fig, to="plot.png")
+        experiment.files.save_video(frames, to="video.mp4")
     """
 
-    def __init__(self, experiment: 'Experiment', **kwargs):
+    def __init__(self, experiment: 'Experiment', path: Optional[str] = None, **kwargs):
         """
         Initialize file builder.
 
         Args:
             experiment: Parent experiment instance
-            **kwargs: File operation parameters
-                - file_path: Path to file to upload
-                - prefix: Logical path prefix (default: "/")
+            path: File path or prefix for operations. Can be:
+                - A prefix/directory (e.g., "checkpoints", "/models")
+                - A file path (e.g., "some.text", "images/photo.png")
+            **kwargs: Additional file operation parameters (for backwards compatibility)
+                - file_path: Path to file to upload (deprecated, use save(to=))
+                - prefix: Logical path prefix (deprecated, use path argument)
                 - description: Optional description
                 - tags: Optional list of tags
                 - bindrs: Optional list of bindrs
                 - metadata: Optional metadata dict
                 - file_id: File ID for download/delete/update operations
-                - dest_path: Destination path for download
+                - dest_path: Destination path for download (deprecated, use download(to=))
         """
         self._experiment = experiment
+        self._path = path
+        # Backwards compatibility
         self._file_path = kwargs.get('file_path')
         self._prefix = kwargs.get('prefix', '/')
         self._description = kwargs.get('description')
@@ -59,9 +91,30 @@ class FileBuilder:
         self._file_id = kwargs.get('file_id')
         self._dest_path = kwargs.get('dest_path')
 
-    def save(self) -> Dict[str, Any]:
+        # If path is provided, determine if it's a file or prefix
+        if path:
+            # Normalize path
+            path = path.lstrip('/')
+            self._normalized_path = '/' + path if not path.startswith('/') else path
+
+    def upload(
+        self,
+        fpath: str,
+        *,
+        to: Optional[str] = None,
+        description: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
         """
-        Upload and save the file.
+        Upload an existing file from disk.
+
+        Args:
+            fpath: Path to existing file to upload (required)
+            to: Optional new filename (uses original filename if not provided)
+            description: Optional description
+            tags: Optional list of tags
+            metadata: Optional metadata dict
 
         Returns:
             File metadata dict with id, path, filename, checksum, etc.
@@ -72,8 +125,19 @@ class FileBuilder:
             ValueError: If file size exceeds 100GB limit
 
         Examples:
-            result = experiment.files(file_path="./model.pt", prefix="/models").save()
-            # Returns: {"id": "123", "path": "/models", "filename": "model.pt", ...}
+            # Upload with original filename
+            dxp.files("models").upload("./local_model.pt")
+
+            # Upload with new filename
+            dxp.files("models").upload("./local_model.pt", to="remote_model.pt")
+
+            # Upload with metadata
+            dxp.files("checkpoints").upload(
+                "./checkpoint.pt",
+                to="epoch_10.pt",
+                description="Best model at epoch 10",
+                tags=["best", "training"]
+            )
         """
         if not self._experiment._is_open:
             raise RuntimeError("Experiment not open. Use experiment.open() or context manager.")
@@ -81,47 +145,312 @@ class FileBuilder:
         if self._experiment._write_protected:
             raise RuntimeError("Experiment is write-protected and cannot be modified.")
 
-        if not self._file_path:
-            raise ValueError("file_path is required for save() operation")
+        if not fpath:
+            raise ValueError("fpath is required")
+
+        # Use provided values or fall back to constructor values
+        desc = description if description is not None else self._description
+        file_tags = tags if tags is not None else self._tags
+        file_metadata = metadata if metadata is not None else self._metadata
+
+        # Determine prefix from path
+        prefix = self._prefix
+        if self._path:
+            prefix = '/' + self._path.lstrip('/')
+
+        return self._save_file(
+            fpath=fpath,
+            prefix=prefix,
+            description=desc,
+            tags=file_tags,
+            metadata=file_metadata,
+            to=to
+        )
+
+    def save(
+        self,
+        content: Any = None,
+        *,
+        to: Optional[str] = None,
+        description: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """
+        Unified save method that handles different content types.
+
+        Args:
+            content: Content to save - can be:
+                - str (file path): Uploads existing file
+                - bytes: Saves as binary blob (requires 'to' parameter)
+                - dict/list: Saves as JSON (requires 'to' parameter)
+                - None: Uses file_path from constructor (backwards compatibility)
+            to: Target filename (required for bytes/dict/list, optional for file paths)
+            description: Optional description
+            tags: Optional list of tags
+            metadata: Optional metadata dict
 
-        file_path = Path(self._file_path)
-        if not file_path.exists():
-            raise ValueError(f"File not found: {self._file_path}")
+        Returns:
+            File metadata dict with id, path, filename, checksum, etc.
+        """
+        # Override builder metadata if provided
+        if description is not None:
+            self._description = description
+        if tags is not None:
+            self._tags = tags
+        if metadata is not None:
+            self._metadata = metadata
+
+        # Backwards compatibility: use file_path from constructor if no content provided
+        if content is None:
+            if self._file_path:
+                content = self._file_path
+            else:
+                raise ValueError("No content provided and no file_path set in constructor")
+
+        # Check if content is a file path
+        if isinstance(content, str) and Path(content).exists():
+            return self.upload(content, to=to)
+
+        # Check if content is bytes
+        if isinstance(content, bytes):
+            if not to:
+                raise ValueError("'to' parameter is required when saving bytes")
+            return self.save_blob(content, to=to)
+
+        # Check if content is dict or list (save as JSON)
+        if isinstance(content, (dict, list)):
+            if not to:
+                raise ValueError("'to' parameter is required when saving dict/list")
+            return self.save_json(content, to=to)
+
+        raise ValueError(f"Unsupported content type: {type(content)}. Expected str (file path), bytes, dict, or list.")
+
+    def _save_file(
+        self,
+        fpath: str,
+        prefix: str,
+        description: Optional[str],
+        tags: Optional[List[str]],
+        metadata: Optional[Dict[str, Any]],
+        to: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """Internal method to save an existing file."""
+        fpath_obj = Path(fpath)
+        if not fpath_obj.exists():
+            raise ValueError(f"File not found: {fpath}")
 
-        if not file_path.is_file():
-            raise ValueError(f"Path is not a file: {self._file_path}")
+        if not fpath_obj.is_file():
+            raise ValueError(f"Path is not a file: {fpath}")
 
         # Check file size (max 100GB)
-        file_size = file_path.stat().st_size
+        file_size = fpath_obj.stat().st_size
         MAX_FILE_SIZE = 100 * 1024 * 1024 * 1024  # 100GB in bytes
         if file_size > MAX_FILE_SIZE:
             raise ValueError(f"File size ({file_size} bytes) exceeds 100GB limit")
 
         # Compute checksum
-        checksum = compute_sha256(str(file_path))
+        checksum = compute_sha256(str(fpath_obj))
 
         # Detect MIME type
-        content_type = get_mime_type(str(file_path))
+        content_type = get_mime_type(str(fpath_obj))
 
-        # Get filename
-        filename = file_path.name
+        # Get filename (use provided 'to' or original)
+        filename = to if to else fpath_obj.name
 
         # Upload through experiment
         return self._experiment._upload_file(
-            file_path=str(file_path),
-            prefix=self._prefix,
+            file_path=str(fpath_obj),
+            prefix=prefix,
             filename=filename,
-            description=self._description,
-            tags=self._tags,
-            metadata=self._metadata,
+            description=description,
+            tags=tags or [],
+            metadata=metadata,
             checksum=checksum,
             content_type=content_type,
             size_bytes=file_size
         )
 
-    def list(self) -> List[Dict[str, Any]]:
+    def _save_bytes(
+        self,
+        data: bytes,
+        filename: str,
+        prefix: str,
+        description: Optional[str],
+        tags: Optional[List[str]],
+        metadata: Optional[Dict[str, Any]]
+    ) -> Dict[str, Any]:
+        """Save bytes data to a file."""
+        import tempfile
+        import os
+
+        temp_dir = tempfile.mkdtemp()
+        temp_path = os.path.join(temp_dir, filename)
+        # Create parent directories if filename contains path
+        os.makedirs(os.path.dirname(temp_path), exist_ok=True)
+        try:
+            with open(temp_path, 'wb') as f:
+                f.write(data)
+            return self._save_file(
+                fpath=temp_path,
+                prefix=prefix,
+                description=description,
+                tags=tags,
+                metadata=metadata
+            )
+        finally:
+            try:
+                os.unlink(temp_path)
+                os.rmdir(temp_dir)
+            except Exception:
+                pass
+
+    def _save_json(
+        self,
+        content: Any,
+        filename: str,
+        prefix: str,
+        description: Optional[str],
+        tags: Optional[List[str]],
+        metadata: Optional[Dict[str, Any]]
+    ) -> Dict[str, Any]:
+        """Save JSON content to a file."""
+        import json
+        import tempfile
+        import os
+
+        temp_dir = tempfile.mkdtemp()
+        temp_path = os.path.join(temp_dir, filename)
+        # Create parent directories if filename contains path
+        os.makedirs(os.path.dirname(temp_path), exist_ok=True)
+        try:
+            with open(temp_path, 'w') as f:
+                json.dump(content, f, indent=2)
+            return self._save_file(
+                fpath=temp_path,
+                prefix=prefix,
+                description=description,
+                tags=tags,
+                metadata=metadata
+            )
+        finally:
+            try:
+                os.unlink(temp_path)
+                os.rmdir(temp_dir)
+            except Exception:
+                pass
+
+    def _save_torch(
+        self,
+        model: Any,
+        filename: str,
+        prefix: str,
+        description: Optional[str],
+        tags: Optional[List[str]],
+        metadata: Optional[Dict[str, Any]]
+    ) -> Dict[str, Any]:
+        """Save PyTorch model to a file."""
+        import tempfile
+        import os
+        import torch
+
+        temp_dir = tempfile.mkdtemp()
+        temp_path = os.path.join(temp_dir, filename)
+        # Create parent directories if filename contains path
+        os.makedirs(os.path.dirname(temp_path), exist_ok=True)
+        try:
+            torch.save(model, temp_path)
+            return self._save_file(
+                fpath=temp_path,
+                prefix=prefix,
+                description=description,
+                tags=tags,
+                metadata=metadata
+            )
+        finally:
+            try:
+                os.unlink(temp_path)
+                os.rmdir(temp_dir)
+            except Exception:
+                pass
+
+    def _save_fig(
+        self,
+        fig: Any,
+        filename: str,
+        prefix: str,
+        description: Optional[str],
+        tags: Optional[List[str]],
+        metadata: Optional[Dict[str, Any]],
+        **kwargs
+    ) -> Dict[str, Any]:
+        """Save matplotlib figure to a file."""
+        import tempfile
+        import os
+        import matplotlib.pyplot as plt
+
+        temp_dir = tempfile.mkdtemp()
+        temp_path = os.path.join(temp_dir, filename)
+        # Create parent directories if filename contains path
+        os.makedirs(os.path.dirname(temp_path), exist_ok=True)
+        try:
+            fig.savefig(temp_path, **kwargs)
+            plt.close(fig)
+            return self._save_file(
+                fpath=temp_path,
+                prefix=prefix,
+                description=description,
+                tags=tags,
+                metadata=metadata
+            )
+        finally:
+            try:
+                os.unlink(temp_path)
+                os.rmdir(temp_dir)
+            except Exception:
+                pass
+
+    def _save_pickle(
+        self,
+        content: Any,
+        filename: str,
+        prefix: str,
+        description: Optional[str],
+        tags: Optional[List[str]],
+        metadata: Optional[Dict[str, Any]]
+    ) -> Dict[str, Any]:
+        """Save Python object to a pickle file."""
+        import pickle
+        import tempfile
+        import os
+
+        temp_dir = tempfile.mkdtemp()
+        temp_path = os.path.join(temp_dir, filename)
+        # Create parent directories if filename contains path
+        os.makedirs(os.path.dirname(temp_path), exist_ok=True)
+        try:
+            with open(temp_path, 'wb') as f:
+                pickle.dump(content, f)
+            return self._save_file(
+                fpath=temp_path,
+                prefix=prefix,
+                description=description,
+                tags=tags,
+                metadata=metadata
+            )
+        finally:
+            try:
+                os.unlink(temp_path)
+                os.rmdir(temp_dir)
+            except Exception:
+                pass
+
+    def list(self, pattern: Optional[str] = None) -> List[Dict[str, Any]]:
         """
-        List files with optional filters.
+        List files with optional glob pattern filtering.
+
+        Args:
+            pattern: Optional glob pattern to filter files (e.g., "*.png", "model_*.pt")
 
         Returns:
             List of file metadata dicts
@@ -131,62 +460,169 @@ class FileBuilder:
 
         Examples:
             files = experiment.files().list()  # All files
-            files = experiment.files(prefix="/models").list()  # Filter by prefix
-            files = experiment.files(tags=["checkpoint"]).list()  # Filter by tags
+            files = experiment.files("/models").list()  # Files in /models prefix
+            files = experiment.files("images").list("*.png")  # PNG files in images
+            files = experiment.files().list("**/*.pt")  # All .pt files
         """
         if not self._experiment._is_open:
             raise RuntimeError("Experiment not open. Use experiment.open() or context manager.")
 
-        return self._experiment._list_files(
-            prefix=self._prefix if self._prefix != '/' else None,
+        # Determine prefix filter - support both new (path) and old (prefix) API
+        prefix = None
+        if self._path:
+            prefix = '/' + self._path.lstrip('/')
+        elif self._prefix and self._prefix != '/':
+            prefix = self._prefix
+
+        # Get all files matching prefix
+        files = self._experiment._list_files(
+            prefix=prefix,
             tags=self._tags if self._tags else None
         )
 
-    def download(self) -> str:
+        # Apply glob pattern if provided
+        if pattern:
+            pattern = pattern.lstrip('/')
+            filtered = []
+            for f in files:
+                filename = f.get('filename', '')
+                full_path = f.get('path', '/').rstrip('/') + '/' + filename
+                full_path = full_path.lstrip('/')
+
+                # Match against filename or full path
+                if fnmatch.fnmatch(filename, pattern) or fnmatch.fnmatch(full_path, pattern):
+                    filtered.append(f)
+            return filtered
+
+        return files
+
+    def download(
+        self,
+        pattern: Optional[str] = None,
+        *,
+        to: Optional[str] = None
+    ) -> Union[str, List[str]]:
         """
-        Download file with automatic checksum verification.
+        Download file(s) with automatic checksum verification.
 
-        If dest_path not provided, downloads to current directory with original filename.
+        Args:
+            pattern: Optional glob pattern for batch download (e.g., "*.png")
+            to: Destination path. For single files, this is the file path.
+                For patterns, this is the destination directory.
 
         Returns:
-            Path to downloaded file
+            For single file: Path to downloaded file
+            For pattern: List of paths to downloaded files
 
         Raises:
             RuntimeError: If experiment is not open
-            ValueError: If file_id not provided
-            ValueError: If checksum verification fails
+            ValueError: If file not found or checksum verification fails
 
         Examples:
-            # Download to current directory with original filename
+            # Download single file
+            path = experiment.files("model.pt").download()
+            path = experiment.files("model.pt").download(to="./local_model.pt")
+
+            # Download by file ID (backwards compatibility)
             path = experiment.files(file_id="123").download()
 
-            # Download to custom path
-            path = experiment.files(file_id="123", dest_path="./model.pt").download()
+            # Download multiple files matching pattern
+            paths = experiment.files("images").download("*.png")
+            paths = experiment.files("images").download("*.png", to="./local_images")
         """
         if not self._experiment._is_open:
             raise RuntimeError("Experiment not open. Use experiment.open() or context manager.")
 
-        if not self._file_id:
-            raise ValueError("file_id is required for download() operation")
+        # If file_id is set (backwards compatibility)
+        if self._file_id:
+            return self._experiment._download_file(
+                file_id=self._file_id,
+                dest_path=to or self._dest_path
+            )
 
-        return self._experiment._download_file(
-            file_id=self._file_id,
-            dest_path=self._dest_path
-        )
+        # If pattern is provided, download multiple files
+        if pattern:
+            files = self.list(pattern)
+            if not files:
+                raise ValueError(f"No files found matching pattern: {pattern}")
+
+            downloaded = []
+            dest_dir = Path(to) if to else Path('.')
+            if to and not dest_dir.exists():
+                dest_dir.mkdir(parents=True, exist_ok=True)
+
+            for f in files:
+                file_id = f.get('id')
+                filename = f.get('filename', 'file')
+                dest_path = str(dest_dir / filename)
+                path = self._experiment._download_file(
+                    file_id=file_id,
+                    dest_path=dest_path
+                )
+                downloaded.append(path)
+
+            return downloaded
+
+        # Download single file by path
+        if self._path:
+            # Find file by path
+            files = self._experiment._list_files(prefix=None, tags=None)
+            matching = []
+            search_path = self._path.lstrip('/')
+
+            for f in files:
+                filename = f.get('filename', '')
+                prefix = f.get('path', '/').lstrip('/')
+                full_path = prefix.rstrip('/') + '/' + filename if prefix else filename
+                full_path = full_path.lstrip('/')
+
+                if full_path == search_path or filename == search_path:
+                    matching.append(f)
+
+            if not matching:
+                raise ValueError(f"File not found: {self._path}")
+
+            if len(matching) > 1:
+                # If multiple matches, prefer exact path match
+                exact = [f for f in matching if
+                         (f.get('path', '/').lstrip('/').rstrip('/') + '/' + f.get('filename', '')).lstrip('/') == search_path]
+                if exact:
+                    matching = exact[:1]
+                else:
+                    matching = matching[:1]
+
+            file_info = matching[0]
+            return self._experiment._download_file(
+                file_id=file_info['id'],
+                dest_path=to
+            )
+
+        raise ValueError("No file path or pattern specified")
 
-    def delete(self) -> Dict[str, Any]:
+    def delete(self, pattern: Optional[str] = None) -> Union[Dict[str, Any], List[Dict[str, Any]]]:
         """
-        Delete file (soft delete).
+        Delete file(s) (soft delete).
+
+        Args:
+            pattern: Optional glob pattern for batch delete (e.g., "*.png")
 
         Returns:
-            Dict with id and deletedAt timestamp
+            For single file: Dict with id and deletedAt timestamp
+            For pattern: List of deletion results
 
         Raises:
             RuntimeError: If experiment is not open or write-protected
-            ValueError: If file_id not provided
+            ValueError: If file not found
 
         Examples:
+            # Delete single file
+            result = experiment.files("some.text").delete()
+
+            # Delete by file ID (backwards compatibility)
             result = experiment.files(file_id="123").delete()
+
+            # Delete multiple files matching pattern
+            results = experiment.files("images").delete("*.png")
         """
         if not self._experiment._is_open:
             raise RuntimeError("Experiment not open. Use experiment.open() or context manager.")
@@ -194,10 +630,52 @@ class FileBuilder:
         if self._experiment._write_protected:
             raise RuntimeError("Experiment is write-protected and cannot be modified.")
 
-        if not self._file_id:
-            raise ValueError("file_id is required for delete() operation")
-
-        return self._experiment._delete_file(file_id=self._file_id)
+        # If file_id is set (backwards compatibility)
+        if self._file_id:
+            return self._experiment._delete_file(file_id=self._file_id)
+
+        # If pattern is provided, delete multiple files
+        if pattern:
+            files = self.list(pattern)
+            if not files:
+                raise ValueError(f"No files found matching pattern: {pattern}")
+
+            results = []
+            for f in files:
+                file_id = f.get('id')
+                result = self._experiment._delete_file(file_id=file_id)
+                results.append(result)
+            return results
+
+        # Delete single file by path
+        if self._path:
+            files = self._experiment._list_files(prefix=None, tags=None)
+            matching = []
+            search_path = self._path.lstrip('/')
+
+            for f in files:
+                filename = f.get('filename', '')
+                prefix = f.get('path', '/').lstrip('/')
+                full_path = prefix.rstrip('/') + '/' + filename if prefix else filename
+                full_path = full_path.lstrip('/')
+
+                if full_path == search_path or filename == search_path:
+                    matching.append(f)
+
+            if not matching:
+                raise ValueError(f"File not found: {self._path}")
+
+            # Delete all matching files
+            if len(matching) == 1:
+                return self._experiment._delete_file(file_id=matching[0]['id'])
+
+            results = []
+            for f in matching:
+                result = self._experiment._delete_file(file_id=f['id'])
+                results.append(result)
+            return results
+
+        raise ValueError("No file path or pattern specified")
 
     def update(self) -> Dict[str, Any]:
         """
@@ -234,271 +712,222 @@ class FileBuilder:
             metadata=self._metadata
         )
 
-    def save_json(self, content: Any, file_name: str) -> Dict[str, Any]:
+    # Convenience methods for specific file types
+
+    def save_json(
+        self,
+        content: Any,
+        *,
+        to: str
+    ) -> Dict[str, Any]:
         """
         Save JSON content to a file.
 
         Args:
             content: Content to save as JSON (dict, list, or any JSON-serializable object)
-            file_name: Name of the file to create
+            to: Target filename
 
         Returns:
             File metadata dict with id, path, filename, checksum, etc.
 
-        Raises:
-            RuntimeError: If experiment is not open or write-protected
-            ValueError: If content is not JSON-serializable
-
         Examples:
             config = {"model": "resnet50", "lr": 0.001}
-            result = experiment.files(prefix="/configs").save_json(config, "config.json")
+            result = dxp.files("configs").save_json(config, to="config.json")
         """
-        import json
-        import tempfile
-        import os
-
-        if not self._experiment._is_open:
-            raise RuntimeError("Experiment not open. Use experiment.run.start() or context manager.")
+        prefix = '/' + self._path.lstrip('/') if self._path else self._prefix
 
-        if self._experiment._write_protected:
-            raise RuntimeError("Experiment is write-protected and cannot be modified.")
+        # Extract path component from 'to' if present (e.g., "configs/settings.json")
+        import os
+        to_dirname = os.path.dirname(to)
+        to_filename = os.path.basename(to)
+        if to_dirname:
+            # Merge the path component into prefix
+            prefix = prefix.rstrip('/') + '/' + to_dirname.lstrip('/')
+
+        return self._save_json(
+            content=content,
+            filename=to_filename,
+            prefix=prefix,
+            description=self._description,
+            tags=self._tags,
+            metadata=self._metadata
+        )
 
-        # Create temporary file with desired filename
-        temp_dir = tempfile.mkdtemp()
-        temp_path = os.path.join(temp_dir, file_name)
-        try:
-            # Write JSON content to temp file
-            with open(temp_path, 'w') as f:
-                json.dump(content, f, indent=2)
+    def save_text(self, content: str, *, to: str) -> Dict[str, Any]:
+        """
+        Save text content to a file.
 
-            # Save using existing save() method
-            original_file_path = self._file_path
-            self._file_path = temp_path
+        Args:
+            content: Text content to save
+            to: Target filename
 
-            # Upload and get result
-            result = self.save()
+        Returns:
+            File metadata dict with id, path, filename, checksum, etc.
 
-            # Restore original file_path
-            self._file_path = original_file_path
+        Examples:
+            result = experiment.files().save_text("Hello, world!", to="greeting.txt")
+            result = experiment.files("configs").save_text(yaml_content, to="view.yaml")
+        """
+        prefix = '/' + self._path.lstrip('/') if self._path else self._prefix
 
-            return result
-        finally:
-            # Clean up temp file and directory
-            try:
-                os.unlink(temp_path)
-                os.rmdir(temp_dir)
-            except Exception:
-                pass
+        # Extract path component from 'to' if present
+        import os
+        to_dirname = os.path.dirname(to)
+        to_filename = os.path.basename(to)
+        if to_dirname:
+            prefix = prefix.rstrip('/') + '/' + to_dirname.lstrip('/')
+
+        return self._save_bytes(
+            data=content.encode('utf-8'),
+            filename=to_filename,
+            prefix=prefix,
+            description=self._description,
+            tags=self._tags,
+            metadata=self._metadata
+        )
 
-    def save_torch(self, model: Any, file_name: str) -> Dict[str, Any]:
+    def save_blob(self, data: bytes, *, to: str) -> Dict[str, Any]:
         """
-        Save PyTorch model to a file.
+        Save binary data to a file.
 
         Args:
-            model: PyTorch model or state dict to save
-            file_name: Name of the file to create (should end with .pt or .pth)
+            data: Binary data to save
+            to: Target filename
 
         Returns:
             File metadata dict with id, path, filename, checksum, etc.
 
-        Raises:
-            RuntimeError: If experiment is not open or write-protected
-            ImportError: If torch is not installed
-            ValueError: If model cannot be saved
-
         Examples:
-            import torch
-            model = torch.nn.Linear(10, 5)
-            result = experiment.files(prefix="/models").save_torch(model, "model.pt")
-
-            # Or save state dict
-            result = experiment.files(prefix="/models").save_torch(model.state_dict(), "model.pth")
+            result = experiment.files("data").save_blob(binary_data, to="model.bin")
         """
-        import tempfile
-        import os
+        prefix = '/' + self._path.lstrip('/') if self._path else self._prefix
 
-        try:
-            import torch
-        except ImportError:
-            raise ImportError("PyTorch is not installed. Install it with: pip install torch")
-
-        if not self._experiment._is_open:
-            raise RuntimeError("Experiment not open. Use experiment.run.start() or context manager.")
-
-        if self._experiment._write_protected:
-            raise RuntimeError("Experiment is write-protected and cannot be modified.")
+        # Extract path component from 'to' if present
+        import os
+        to_dirname = os.path.dirname(to)
+        to_filename = os.path.basename(to)
+        if to_dirname:
+            prefix = prefix.rstrip('/') + '/' + to_dirname.lstrip('/')
+
+        return self._save_bytes(
+            data=data,
+            filename=to_filename,
+            prefix=prefix,
+            description=self._description,
+            tags=self._tags,
+            metadata=self._metadata
+        )
 
-        # Create temporary file with desired filename
-        temp_dir = tempfile.mkdtemp()
-        temp_path = os.path.join(temp_dir, file_name)
+    def save_torch(
+        self,
+        model: Any,
+        *,
+        to: str
+    ) -> Dict[str, Any]:
+        """
+        Save PyTorch model to a file.
 
-        try:
-            # Save model to temp file
-            torch.save(model, temp_path)
+        Args:
+            model: PyTorch model or state dict to save
+            to: Target filename
 
-            # Save using existing save() method
-            original_file_path = self._file_path
-            self._file_path = temp_path
+        Returns:
+            File metadata dict with id, path, filename, checksum, etc.
 
-            # Upload and get result
-            result = self.save()
+        Examples:
+            result = dxp.files("models").save_torch(model, to="model.pt")
+            result = dxp.files("models").save_torch(model.state_dict(), to="weights.pth")
+        """
 
-            # Restore original file_path
-            self._file_path = original_file_path
+        prefix = '/' + self._path.lstrip('/') if self._path else self._prefix
 
-            return result
-        finally:
-            # Clean up temp file and directory
-            try:
-                os.unlink(temp_path)
-                os.rmdir(temp_dir)
-            except Exception:
-                pass
+        return self._save_torch(
+            model=model,
+            filename=to,
+            prefix=prefix,
+            description=self._description,
+            tags=self._tags,
+            metadata=self._metadata
+        )
 
-    def save_pkl(self, content: Any, file_name: str) -> Dict[str, Any]:
+    def save_pkl(
+        self,
+        content: Any,
+        *,
+        to: str
+    ) -> Dict[str, Any]:
         """
         Save Python object to a pickle file.
 
         Args:
             content: Python object to pickle (must be pickle-serializable)
-            file_name: Name of the file to create (should end with .pkl or .pickle)
+            to: Target filename
 
         Returns:
             File metadata dict with id, path, filename, checksum, etc.
 
-        Raises:
-            RuntimeError: If experiment is not open or write-protected
-            ValueError: If content cannot be pickled
-
         Examples:
             data = {"model": "resnet50", "weights": np.array([1, 2, 3])}
-            result = experiment.files(prefix="/data").save_pkl(data, "data.pkl")
-
-            # Or save any Python object
-            result = experiment.files(prefix="/models").save_pkl(trained_model, "model.pickle")
+            result = dxp.files("data").save_pkl(data, to="data.pkl")
         """
-        import pickle
-        import tempfile
-        import os
-
-        if not self._experiment._is_open:
-            raise RuntimeError("Experiment not open. Use experiment.run.start() or context manager.")
-
-        if self._experiment._write_protected:
-            raise RuntimeError("Experiment is write-protected and cannot be modified.")
+        prefix = '/' + self._path.lstrip('/') if self._path else self._prefix
 
-        # Create temporary file with desired filename
-        temp_dir = tempfile.mkdtemp()
-        temp_path = os.path.join(temp_dir, file_name)
-        try:
-            # Write pickled content to temp file
-            with open(temp_path, 'wb') as f:
-                pickle.dump(content, f)
-
-            # Save using existing save() method
-            original_file_path = self._file_path
-            self._file_path = temp_path
-
-            # Upload and get result
-            result = self.save()
-
-            # Restore original file_path
-            self._file_path = original_file_path
-
-            return result
-        finally:
-            # Clean up temp file and directory
-            try:
-                os.unlink(temp_path)
-                os.rmdir(temp_dir)
-            except Exception:
-                pass
+        return self._save_pickle(
+            content=content,
+            filename=to,
+            prefix=prefix,
+            description=self._description,
+            tags=self._tags,
+            metadata=self._metadata
+        )
 
-    def save_fig(self, fig: Optional[Any] = None, file_name: str = "figure.png", **kwargs) -> Dict[str, Any]:
+    def save_fig(
+        self,
+        fig: Optional[Any] = None,
+        *,
+        to: str,
+        **kwargs
+    ) -> Dict[str, Any]:
         """
         Save matplotlib figure to a file.
 
         Args:
             fig: Matplotlib figure object. If None, uses plt.gcf() (current figure)
-            file_name: Name of file to create (extension determines format: .png, .pdf, .svg, .jpg)
-            **kwargs: Additional arguments passed to fig.savefig():
-                - dpi: Resolution (int or 'figure')
-                - transparent: Make background transparent (bool)
-                - bbox_inches: 'tight' to auto-crop (str or Bbox)
-                - quality: JPEG quality 0-100 (int)
-                - format: Override format detection (str)
+            to: Target filename
+            **kwargs: Additional arguments passed to fig.savefig()
 
         Returns:
             File metadata dict with id, path, filename, checksum, etc.
 
-        Raises:
-            RuntimeError: If experiment not open or write-protected
-            ImportError: If matplotlib not installed
-
         Examples:
-            import matplotlib.pyplot as plt
-
-            # Use current figure
             plt.plot([1, 2, 3], [1, 4, 9])
-            result = experiment.files(prefix="/plots").save_fig(file_name="plot.png")
-
-            # Specify figure explicitly
-            fig, ax = plt.subplots()
-            ax.plot([1, 2, 3])
-            result = experiment.files(prefix="/plots").save_fig(fig=fig, file_name="plot.pdf", dpi=150)
+            result = dxp.files("plots").save_fig(to="plot.png")
         """
-        import tempfile
-        import os
-
         try:
             import matplotlib.pyplot as plt
         except ImportError:
             raise ImportError("Matplotlib is not installed. Install it with: pip install matplotlib")
 
-        if not self._experiment._is_open:
-            raise RuntimeError("Experiment not open. Use experiment.run.start() or context manager.")
-
-        if self._experiment._write_protected:
-            raise RuntimeError("Experiment is write-protected and cannot be modified.")
-
-        # Get figure
         if fig is None:
             fig = plt.gcf()
 
-        # Create temporary file with desired filename
-        temp_dir = tempfile.mkdtemp()
-        temp_path = os.path.join(temp_dir, file_name)
-
-        try:
-            # Save figure to temp file
-            fig.savefig(temp_path, **kwargs)
-
-            # Close figure to prevent memory leaks
-            plt.close(fig)
-
-            # Save using existing save() method
-            original_file_path = self._file_path
-            self._file_path = temp_path
-
-            # Upload and get result
-            result = self.save()
+        prefix = '/' + self._path.lstrip('/') if self._path else self._prefix
 
-            # Restore original file_path
-            self._file_path = original_file_path
-
-            return result
-        finally:
-            # Clean up temp file and directory
-            try:
-                os.unlink(temp_path)
-                os.rmdir(temp_dir)
-            except Exception:
-                pass
+        return self._save_fig(
+            fig=fig,
+            filename=to,
+            prefix=prefix,
+            description=self._description,
+            tags=self._tags,
+            metadata=self._metadata,
+            **kwargs
+        )
 
     def save_video(
         self,
         frame_stack: Union[List, Any],
-        file_name: str,
+        *,
+        to: str,
         fps: int = 20,
         **imageio_kwargs
     ) -> Dict[str, Any]:
@@ -506,42 +935,17 @@ class FileBuilder:
         Save video frame stack to a file.
 
         Args:
-            frame_stack: List of numpy arrays or stacked array (shape: [N, H, W] or [N, H, W, C])
-            file_name: Name of file to create (extension determines format: .mp4, .gif, .avi, .webm)
+            frame_stack: List of numpy arrays or stacked array
+            to: Target filename
             fps: Frames per second (default: 20)
-            **imageio_kwargs: Additional arguments passed to imageio.v3.imwrite():
-                - codec: Video codec (e.g., 'libx264', 'h264')
-                - quality: Quality level (int, higher is better)
-                - pixelformat: Pixel format (e.g., 'yuv420p')
-                - macro_block_size: Macro block size for encoding
+            **imageio_kwargs: Additional arguments passed to imageio
 
         Returns:
             File metadata dict with id, path, filename, checksum, etc.
 
-        Raises:
-            RuntimeError: If experiment not open or write-protected
-            ImportError: If imageio or scikit-image not installed
-            ValueError: If frame_stack is empty or invalid format
-
         Examples:
-            import numpy as np
-
-            # Grayscale frames (float values 0-1)
             frames = [np.random.rand(480, 640) for _ in range(30)]
-            result = experiment.files(prefix="/videos").save_video(frames, "output.mp4")
-
-            # RGB frames with custom FPS
-            frames = [np.random.rand(480, 640, 3) for _ in range(60)]
-            result = experiment.files(prefix="/videos").save_video(frames, "output.mp4", fps=30)
-
-            # Save as GIF
-            frames = [np.random.rand(200, 200) for _ in range(20)]
-            result = experiment.files(prefix="/videos").save_video(frames, "animation.gif")
-
-            # With custom codec and quality
-            result = experiment.files(prefix="/videos").save_video(
-                frames, "output.mp4", fps=30, codec='libx264', quality=8
-            )
+            result = dxp.files("videos").save_video(frames, to="output.mp4")
         """
         import tempfile
         import os
@@ -556,51 +960,37 @@ class FileBuilder:
         except ImportError:
             raise ImportError("scikit-image is not installed. Install it with: pip install scikit-image")
 
-        if not self._experiment._is_open:
-            raise RuntimeError("Experiment not open. Use experiment.run.start() or context manager.")
-
-        if self._experiment._write_protected:
-            raise RuntimeError("Experiment is write-protected and cannot be modified.")
-
         # Validate frame_stack
         try:
-            # Handle both list and numpy array
             if len(frame_stack) == 0:
                 raise ValueError("frame_stack is empty")
         except TypeError:
             raise ValueError("frame_stack must be a list or numpy array")
 
-        # Create temporary file with desired filename
+        prefix = '/' + self._path.lstrip('/') if self._path else self._prefix
+
         temp_dir = tempfile.mkdtemp()
-        temp_path = os.path.join(temp_dir, file_name)
+        temp_path = os.path.join(temp_dir, to)
+        # Create parent directories if filename contains path
+        os.makedirs(os.path.dirname(temp_path), exist_ok=True)
 
         try:
-            # Convert frames to uint8 format (handles float32/64, grayscale, RGB, etc.)
-            # img_as_ubyte automatically scales [0.0, 1.0] floats to [0, 255] uint8
             frames_ubyte = img_as_ubyte(frame_stack)
-
-            # Encode video to temp file
             try:
                 iio.imwrite(temp_path, frames_ubyte, fps=fps, **imageio_kwargs)
             except iio.core.NeedDownloadError:
-                # Auto-download FFmpeg if not available
                 import imageio.plugins.ffmpeg
                 imageio.plugins.ffmpeg.download()
                 iio.imwrite(temp_path, frames_ubyte, fps=fps, **imageio_kwargs)
 
-            # Save using existing save() method
-            original_file_path = self._file_path
-            self._file_path = temp_path
-
-            # Upload and get result
-            result = self.save()
-
-            # Restore original file_path
-            self._file_path = original_file_path
-
-            return result
+            return self._save_file(
+                fpath=temp_path,
+                prefix=prefix,
+                description=self._description,
+                tags=self._tags,
+                metadata=self._metadata
+            )
         finally:
-            # Clean up temp file and directory
             try:
                 os.unlink(temp_path)
                 os.rmdir(temp_dir)
@@ -611,31 +1001,16 @@ class FileBuilder:
         """
         Duplicate an existing file to a new path within the same experiment.
 
-        Useful for checkpoint rotation patterns where you save versioned checkpoints
-        and maintain a "latest" or "best" pointer.
-
         Args:
             source: Source file - either file ID (str) or metadata dict with 'id' key
             to: Target path like "models/latest.pt" or "/checkpoints/best.pt"
 
         Returns:
-            File metadata dict for the duplicated file with id, path, filename, checksum, etc.
-
-        Raises:
-            RuntimeError: If experiment is not open or write-protected
-            ValueError: If source file not found or target path invalid
+            File metadata dict for the duplicated file
 
         Examples:
-            # Using file ID
-            dxp.files().duplicate("file-id-123", to="models/latest.pt")
-
-            # Using metadata dict from save_torch
-            snapshot = dxp.files(prefix="/models").save_torch(model, f"model_{epoch:05d}.pt")
+            snapshot = dxp.files("models").save_torch(model, to=f"model_{epoch:05d}.pt")
             dxp.files().duplicate(snapshot, to="models/latest.pt")
-
-            # Checkpoint rotation pattern
-            snap = dxp.files(prefix="/checkpoints").save_torch(model, f"model_{epoch:05d}.pt")
-            dxp.files().duplicate(snap, to="checkpoints/best.pt")
         """
         import tempfile
         import os
@@ -669,34 +1044,127 @@ class FileBuilder:
         if not target_filename:
             raise ValueError(f"Invalid target path '{to}': must include filename")
 
-        # Download source file to temp location
         temp_dir = tempfile.mkdtemp()
         temp_path = os.path.join(temp_dir, target_filename)
 
         try:
-            # Download the source file
             downloaded_path = self._experiment._download_file(
                 file_id=source_id,
                 dest_path=temp_path
             )
 
-            # Save to new location using existing save() method
-            original_file_path = self._file_path
-            original_prefix = self._prefix
+            return self._save_file(
+                fpath=downloaded_path,
+                prefix=target_prefix,
+                description=self._description,
+                tags=self._tags,
+                metadata=self._metadata
+            )
+        finally:
+            try:
+                if os.path.exists(temp_path):
+                    os.unlink(temp_path)
+                os.rmdir(temp_dir)
+            except Exception:
+                pass
+
+    def exists(self) -> bool:
+        """
+        Check if a file exists at the specified path.
+
+        Returns:
+            True if file exists, False otherwise
+
+        Raises:
+            RuntimeError: If experiment is not open
+            ValueError: If no file path specified
+
+        Examples:
+            # Check if file exists
+            if dxp.files("models/checkpoint.pt").exists():
+                print("File exists!")
+
+            # Check before downloading
+            if not dxp.files("config.json").exists():
+                raise FileNotFoundError("Config file missing")
+        """
+        if not self._experiment._is_open:
+            raise RuntimeError("Experiment not open. Use experiment.open() or context manager.")
+
+        if not self._path:
+            raise ValueError("No file path specified. Use: experiment.files('path/to/file').exists()")
+
+        # Try to find the file
+        try:
+            files = self._experiment._list_files(prefix=None, tags=None)
+            search_path = self._path.lstrip('/')
+
+            for f in files:
+                filename = f.get('filename', '')
+                prefix = f.get('path', '/').lstrip('/')
+                full_path = prefix.rstrip('/') + '/' + filename if prefix else filename
+                full_path = full_path.lstrip('/')
+
+                # Check if this file matches (by full path or just filename)
+                if full_path == search_path or filename == search_path:
+                    # Make sure it's not deleted
+                    if f.get('deletedAt') is None:
+                        return True
+
+            return False
+        except Exception:
+            return False
+
+    def read_text(self, encoding: str = 'utf-8') -> str:
+        """
+        Download file and read its content as text.
+
+        Args:
+            encoding: Text encoding to use (default: 'utf-8')
+
+        Returns:
+            File content as string
+
+        Raises:
+            RuntimeError: If experiment is not open
+            ValueError: If file not found or no path specified
+            UnicodeDecodeError: If file cannot be decoded with specified encoding
+
+        Examples:
+            # Read configuration file
+            config_yaml = dxp.files("configs/view.yaml").read_text()
+
+            # Read log file
+            logs = dxp.files("logs/training.log").read_text()
+
+            # Read with different encoding
+            content = dxp.files("data.txt").read_text(encoding='latin-1')
+        """
+        import tempfile
+        import os
+
+        if not self._experiment._is_open:
+            raise RuntimeError("Experiment not open. Use experiment.open() or context manager.")
+
+        if not self._path:
+            raise ValueError("No file path specified. Use: experiment.files('path/to/file').read_text()")
 
-            self._file_path = downloaded_path
-            self._prefix = target_prefix
+        # Create temporary file for download
+        temp_dir = tempfile.mkdtemp()
+        temp_filename = Path(self._path).name
+        temp_path = os.path.join(temp_dir, temp_filename)
 
-            # Upload and get result
-            result = self.save()
+        try:
+            # Download the file
+            downloaded_path = self.download(to=temp_path)
 
-            # Restore original values
-            self._file_path = original_file_path
-            self._prefix = original_prefix
+            # Read content as text
+            with open(downloaded_path, 'r', encoding=encoding) as f:
+                content = f.read()
 
-            return result
+            return content
         finally:
-            # Clean up temp file and directory
+            # Clean up temporary file
             try:
                 if os.path.exists(temp_path):
                     os.unlink(temp_path)
@@ -705,6 +1173,249 @@ class FileBuilder:
                 pass
 
 
+class FilesAccessor:
+    """
+    Accessor that enables both callable and attribute-style access to file operations.
+
+    This allows:
+        dxp.files("models")          # Returns FileBuilder
+        dxp.files(dir="models")      # Keyword argument form
+        experiment.files.upload(...)        # Direct method call
+        experiment.files.download(...)    # Direct method call
+    """
+
+    def __init__(self, experiment: 'Experiment'):
+        self._experiment = experiment
+        self._builder = FileBuilder(experiment)
+
+    def __call__(self, dir: Optional[str] = None, **kwargs) -> FileBuilder:
+        """
+        Create a FileBuilder with the given directory.
+
+        Supports flexible argument styles:
+        - Positional: files("models")
+        - Keyword: files(dir="models")
+        - No args (root): files()
+
+        Args:
+            dir: Directory/path for file operations
+            **kwargs: Additional FileBuilder options
+
+        Returns:
+            FileBuilder instance
+        """
+        return FileBuilder(self._experiment, path=dir, **kwargs)
+
+    # Direct methods that don't require a path first
+
+    def upload(
+        self,
+        fpath: str,
+        *,
+        to: Optional[str] = None,
+        **kwargs
+    ) -> Dict[str, Any]:
+        """
+        Upload a file directly without specifying a path prefix first.
+
+        Args:
+            fpath: Path to existing file to upload (required)
+            to: Optional destination path, e.g., "models/model.pt" or "renamed.pt"
+            **kwargs: Additional FileBuilder options
+
+        Returns:
+            File metadata dict with id, path, filename, checksum, etc.
+
+        Examples:
+            # Upload with original filename
+            experiment.files.upload("./model.pt")
+
+            # Upload with destination path
+            experiment.files.upload("./model.pt", to="models/model.pt")
+
+            # Upload with metadata
+            experiment.files.upload("./model.pt", to="best.pt", description="Best model")
+        """
+        # Parse 'to' to extract prefix and filename if provided
+        if to:
+            to_path = to.lstrip('/')
+            if '/' in to_path:
+                prefix, filename = to_path.rsplit('/', 1)
+                prefix = '/' + prefix
+            else:
+                prefix = '/'
+                filename = to_path
+            return FileBuilder(self._experiment, path=prefix, **kwargs).upload(fpath, to=filename)
+
+        # No prefix, just upload with original or specified filename
+        return FileBuilder(self._experiment, **kwargs).upload(fpath)
+
+    def download(
+        self,
+        path: str,
+        *,
+        to: Optional[str] = None
+    ) -> Union[str, List[str]]:
+        """
+        Download file(s) directly.
+
+        Examples:
+            experiment.files.download("model.pt")
+            experiment.files.download("images/*.png", to="local_images")
+        """
+        path = path.lstrip('/')
+
+        # Check if path contains glob pattern
+        if '*' in path or '?' in path:
+            # Extract prefix and pattern
+            if '/' in path:
+                parts = path.split('/')
+                # Find where the pattern starts
+                prefix_parts = []
+                pattern_parts = []
+                in_pattern = False
+                for part in parts:
+                    if '*' in part or '?' in part:
+                        in_pattern = True
+                    if in_pattern:
+                        pattern_parts.append(part)
+                    else:
+                        prefix_parts.append(part)
+
+                prefix = '/'.join(prefix_parts) if prefix_parts else None
+                pattern = '/'.join(pattern_parts)
+            else:
+                prefix = None
+                pattern = path
+
+            return FileBuilder(self._experiment, path=prefix).download(pattern, to=to)
+
+        # Single file download
+        return FileBuilder(self._experiment, path=path).download(to=to)
+
+    def delete(self, path: str) -> Union[Dict[str, Any], List[Dict[str, Any]]]:
+        """
+        Delete file(s) directly.
+
+        Examples:
+            experiment.files.delete("some.text")
+            experiment.files.delete("images/*.png")
+        """
+        path = path.lstrip('/')
+
+        # Check if path contains glob pattern
+        if '*' in path or '?' in path:
+            # Extract prefix and pattern
+            if '/' in path:
+                parts = path.split('/')
+                prefix_parts = []
+                pattern_parts = []
+                in_pattern = False
+                for part in parts:
+                    if '*' in part or '?' in part:
+                        in_pattern = True
+                    if in_pattern:
+                        pattern_parts.append(part)
+                    else:
+                        prefix_parts.append(part)
+
+                prefix = '/'.join(prefix_parts) if prefix_parts else None
+                pattern = '/'.join(pattern_parts)
+            else:
+                prefix = None
+                pattern = path
+
+            return FileBuilder(self._experiment, path=prefix).delete(pattern)
+
+        # Single file delete
+        return FileBuilder(self._experiment, path=path).delete()
+
+    def list(self, pattern: Optional[str] = None) -> List[Dict[str, Any]]:
+        """
+        List files directly.
+
+        Examples:
+            files = experiment.files.list()
+            files = experiment.files.list("*.pt")
+        """
+        return FileBuilder(self._experiment).list(pattern)
+
+    def save_text(self, content: str, *, to: str) -> Dict[str, Any]:
+        """
+        Save text content to a file.
+
+        Examples:
+            experiment.files.save_text("content", to="view.yaml")
+        """
+        to_path = to.lstrip('/')
+        if '/' in to_path:
+            prefix, filename = to_path.rsplit('/', 1)
+            prefix = '/' + prefix
+        else:
+            prefix = '/'
+            filename = to_path
+        return FileBuilder(self._experiment, path=prefix).save_text(content, to=filename)
+
+    def save_json(self, content: Any, *, to: str) -> Dict[str, Any]:
+        """
+        Save JSON content to a file.
+
+        Examples:
+            experiment.files.save_json({"key": "value"}, to="config.json")
+        """
+        to_path = to.lstrip('/')
+        if '/' in to_path:
+            prefix, filename = to_path.rsplit('/', 1)
+            prefix = '/' + prefix
+        else:
+            prefix = '/'
+            filename = to_path
+        return FileBuilder(self._experiment, path=prefix).save_json(content, to=filename)
+
+    def save_blob(self, data: bytes, *, to: str) -> Dict[str, Any]:
+        """
+        Save binary data to a file.
+
+        Examples:
+            experiment.files.save_blob(b"data", to="data.bin")
+        """
+        to_path = to.lstrip('/')
+        if '/' in to_path:
+            prefix, filename = to_path.rsplit('/', 1)
+            prefix = '/' + prefix
+        else:
+            prefix = '/'
+            filename = to_path
+        return FileBuilder(self._experiment, path=prefix).save_blob(data, to=filename)
+
+
+class BindrsBuilder:
+    """
+    Fluent interface for bindr (collection) operations.
+
+    Usage:
+        file_paths = experiment.bindrs("some-bindr").list()
+    """
+
+    def __init__(self, experiment: 'Experiment', bindr_name: str):
+        self._experiment = experiment
+        self._bindr_name = bindr_name
+
+    def list(self) -> List[Dict[str, Any]]:
+        """
+        List files in this bindr.
+
+        Returns:
+            List of file metadata dicts belonging to this bindr
+        """
+        if not self._experiment._is_open:
+            raise RuntimeError("Experiment not open. Use experiment.open() or context manager.")
+
+        # Get all files and filter by bindr
+        all_files = self._experiment._list_files(prefix=None, tags=None)
+        return [f for f in all_files if self._bindr_name in f.get('bindrs', [])]
+
+
 def compute_sha256(file_path: str) -> str:
     """
     Compute SHA256 checksum of a file.