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

ml_dash/files.py

@@ -19,45 +19,28 @@ class FileBuilder:
     Fluent interface for file operations.
 
     Usage:
-        # 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")
+        # Upload file
+        experiment.files("checkpoints").save(net, to="checkpoint.pt")
 
         # List files
-        files = experiment.files(dir="some/location").list()
-        files = experiment.files(dir="models").list()
+        files = experiment.files("/some/location").list()
+        files = experiment.files("/models").list()
 
         # Download file
-        dxp.files("some.text").download()
-        dxp.files("some.text").download(to="./model.pt")
+        experiment.files("some.text").download()
+        experiment.files("some.text").download(to="./model.pt")
 
-        # Download files via glob pattern
+        # Download Files via Glob Pattern
         file_paths = experiment.files("images").list("*.png")
-        dxp.files("images").download("*.png")
+        experiment.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")
+        experiment.files("some.text").delete()
+
+    Specific File Types:
+        dxp.files.save_text("content", to="view.yaml")
+        dxp.files.save_json(dict(hey="yo"), to="config.json")
+        dxp.files.save_blob(b"xxx", to="data.bin")
     """
 
     def __init__(self, experiment: 'Experiment', path: Optional[str] = None, **kwargs):
@@ -97,9 +80,9 @@ class FileBuilder:
             path = path.lstrip('/')
             self._normalized_path = '/' + path if not path.startswith('/') else path
 
-    def upload(
+    def save(
         self,
-        fpath: str,
+        obj: Optional[Any] = None,
         *,
         to: Optional[str] = None,
         description: Optional[str] = None,
@@ -107,14 +90,21 @@ class FileBuilder:
         metadata: Optional[Dict[str, Any]] = None
     ) -> Dict[str, Any]:
         """
-        Upload an existing file from disk.
+        Upload and save a file or object.
 
         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
+            obj: Object to save. Can be:
+                - None: Uses file_path from constructor (backwards compatibility)
+                - str: Path to an existing file
+                - bytes: Binary data to save
+                - dict/list: JSON-serializable data
+                - PyTorch model/state_dict: Saved with torch.save()
+                - matplotlib figure: Saved as image
+                - Any picklable object: Saved with pickle
+            to: Target filename (required when obj is not a file path)
+            description: Optional description (overrides constructor)
+            tags: Optional list of tags (overrides constructor)
+            metadata: Optional metadata dict (overrides constructor)
 
         Returns:
             File metadata dict with id, path, filename, checksum, etc.
@@ -125,19 +115,19 @@ class FileBuilder:
             ValueError: If file size exceeds 100GB limit
 
         Examples:
-            # 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"]
-            )
+            # Save existing file
+            experiment.files("models").save("./model.pt")
+            experiment.files("models").save(to="model.pt")  # copies from self._file_path
+
+            # Save PyTorch model
+            experiment.files("checkpoints").save(model, to="checkpoint.pt")
+            experiment.files("checkpoints").save(model.state_dict(), to="weights.pt")
+
+            # Save dict as JSON
+            experiment.files("configs").save({"lr": 0.001}, to="config.json")
+
+            # Save bytes
+            experiment.files("data").save(b"binary data", to="data.bin")
         """
         if not self._experiment._is_open:
             raise RuntimeError("Experiment not open. Use experiment.open() or context manager.")
@@ -145,9 +135,6 @@ class FileBuilder:
         if self._experiment._write_protected:
             raise RuntimeError("Experiment is write-protected and cannot be modified.")
 
-        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
@@ -158,109 +145,136 @@ class FileBuilder:
         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
-
-        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")
+        # Handle different object types
+        if obj is None:
+            # Backwards compatibility: use file_path from constructor
+            if not self._file_path:
+                raise ValueError("No file or object provided. Pass a file path or object to save().")
+            return self._save_file(
+                file_path=self._file_path,
+                prefix=prefix,
+                description=desc,
+                tags=file_tags,
+                metadata=file_metadata
+            )
 
-        # Check if content is a file path
-        if isinstance(content, str) and Path(content).exists():
-            return self.upload(content, to=to)
+        if isinstance(obj, str) and Path(obj).exists():
+            # obj is a path to an existing file
+            return self._save_file(
+                file_path=obj,
+                prefix=prefix,
+                description=desc,
+                tags=file_tags,
+                metadata=file_metadata
+            )
 
-        # Check if content is bytes
-        if isinstance(content, bytes):
+        if isinstance(obj, bytes):
+            # Save bytes directly
             if not to:
                 raise ValueError("'to' parameter is required when saving bytes")
-            return self.save_blob(content, to=to)
+            return self._save_bytes(
+                data=obj,
+                filename=to,
+                prefix=prefix,
+                description=desc,
+                tags=file_tags,
+                metadata=file_metadata
+            )
 
-        # Check if content is dict or list (save as JSON)
-        if isinstance(content, (dict, list)):
+        if isinstance(obj, (dict, list)):
+            # Try JSON first
             if not to:
                 raise ValueError("'to' parameter is required when saving dict/list")
-            return self.save_json(content, to=to)
+            return self._save_json(
+                content=obj,
+                filename=to,
+                prefix=prefix,
+                description=desc,
+                tags=file_tags,
+                metadata=file_metadata
+            )
+
+        # Check for PyTorch model
+        try:
+            import torch
+            if isinstance(obj, (torch.nn.Module, dict)) or hasattr(obj, 'state_dict'):
+                if not to:
+                    raise ValueError("'to' parameter is required when saving PyTorch model")
+                return self._save_torch(
+                    model=obj,
+                    filename=to,
+                    prefix=prefix,
+                    description=desc,
+                    tags=file_tags,
+                    metadata=file_metadata
+                )
+        except ImportError:
+            pass
 
-        raise ValueError(f"Unsupported content type: {type(content)}. Expected str (file path), bytes, dict, or list.")
+        # Check for matplotlib figure
+        try:
+            import matplotlib.pyplot as plt
+            from matplotlib.figure import Figure
+            if isinstance(obj, Figure):
+                if not to:
+                    raise ValueError("'to' parameter is required when saving matplotlib figure")
+                return self._save_fig(
+                    fig=obj,
+                    filename=to,
+                    prefix=prefix,
+                    description=desc,
+                    tags=file_tags,
+                    metadata=file_metadata
+                )
+        except ImportError:
+            pass
+
+        # Fall back to pickle
+        if not to:
+            raise ValueError("'to' parameter is required when saving object")
+        return self._save_pickle(
+            content=obj,
+            filename=to,
+            prefix=prefix,
+            description=desc,
+            tags=file_tags,
+            metadata=file_metadata
+        )
 
     def _save_file(
         self,
-        fpath: str,
+        file_path: str,
         prefix: str,
         description: Optional[str],
         tags: Optional[List[str]],
-        metadata: Optional[Dict[str, Any]],
-        to: Optional[str] = None
+        metadata: Optional[Dict[str, Any]]
     ) -> 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}")
+        file_path_obj = Path(file_path)
+        if not file_path_obj.exists():
+            raise ValueError(f"File not found: {file_path}")
 
-        if not fpath_obj.is_file():
-            raise ValueError(f"Path is not a file: {fpath}")
+        if not file_path_obj.is_file():
+            raise ValueError(f"Path is not a file: {file_path}")
 
         # Check file size (max 100GB)
-        file_size = fpath_obj.stat().st_size
+        file_size = file_path_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(fpath_obj))
+        checksum = compute_sha256(str(file_path_obj))
 
         # Detect MIME type
-        content_type = get_mime_type(str(fpath_obj))
+        content_type = get_mime_type(str(file_path_obj))
 
-        # Get filename (use provided 'to' or original)
-        filename = to if to else fpath_obj.name
+        # Get filename
+        filename = file_path_obj.name
 
         # Upload through experiment
         return self._experiment._upload_file(
-            file_path=str(fpath_obj),
+            file_path=str(file_path_obj),
             prefix=prefix,
             filename=filename,
             description=description,
@@ -286,13 +300,11 @@ class FileBuilder:
 
         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,
+                file_path=temp_path,
                 prefix=prefix,
                 description=description,
                 tags=tags,
@@ -321,13 +333,11 @@ class FileBuilder:
 
         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,
+                file_path=temp_path,
                 prefix=prefix,
                 description=description,
                 tags=tags,
@@ -356,12 +366,10 @@ class FileBuilder:
 
         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,
+                file_path=temp_path,
                 prefix=prefix,
                 description=description,
                 tags=tags,
@@ -391,13 +399,11 @@ class FileBuilder:
 
         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,
+                file_path=temp_path,
                 prefix=prefix,
                 description=description,
                 tags=tags,
@@ -426,13 +432,11 @@ class FileBuilder:
 
         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,
+                file_path=temp_path,
                 prefix=prefix,
                 description=description,
                 tags=tags,
@@ -717,36 +721,34 @@ class FileBuilder:
     def save_json(
         self,
         content: Any,
+        file_name: Optional[str] = None,
         *,
-        to: str
+        to: Optional[str] = None
     ) -> Dict[str, Any]:
         """
         Save JSON content to a file.
 
         Args:
             content: Content to save as JSON (dict, list, or any JSON-serializable object)
-            to: Target filename
+            file_name: Name of the file to create (deprecated, use 'to')
+            to: Target filename (preferred)
 
         Returns:
             File metadata dict with id, path, filename, checksum, etc.
 
         Examples:
             config = {"model": "resnet50", "lr": 0.001}
-            result = dxp.files("configs").save_json(config, to="config.json")
+            result = experiment.files("configs").save_json(config, to="config.json")
         """
-        prefix = '/' + self._path.lstrip('/') if self._path else self._prefix
+        filename = to or file_name
+        if not filename:
+            raise ValueError("'to' parameter is required")
 
-        # 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('/')
+        prefix = '/' + self._path.lstrip('/') if self._path else self._prefix
 
         return self._save_json(
             content=content,
-            filename=to_filename,
+            filename=filename,
             prefix=prefix,
             description=self._description,
             tags=self._tags,
@@ -768,18 +770,14 @@ class FileBuilder:
             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
+        if not to:
+            raise ValueError("'to' parameter is required")
 
-        # 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('/')
+        prefix = '/' + self._path.lstrip('/') if self._path else self._prefix
 
         return self._save_bytes(
             data=content.encode('utf-8'),
-            filename=to_filename,
+            filename=to,
             prefix=prefix,
             description=self._description,
             tags=self._tags,
@@ -800,18 +798,14 @@ class FileBuilder:
         Examples:
             result = experiment.files("data").save_blob(binary_data, to="model.bin")
         """
-        prefix = '/' + self._path.lstrip('/') if self._path else self._prefix
+        if not to:
+            raise ValueError("'to' parameter is required")
 
-        # 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('/')
+        prefix = '/' + self._path.lstrip('/') if self._path else self._prefix
 
         return self._save_bytes(
             data=data,
-            filename=to_filename,
+            filename=to,
             prefix=prefix,
             description=self._description,
             tags=self._tags,
@@ -821,29 +815,34 @@ class FileBuilder:
     def save_torch(
         self,
         model: Any,
+        file_name: Optional[str] = None,
         *,
-        to: str
+        to: Optional[str] = None
     ) -> Dict[str, Any]:
         """
         Save PyTorch model to a file.
 
         Args:
             model: PyTorch model or state dict to save
-            to: Target filename
+            file_name: Name of the file to create (deprecated, use 'to')
+            to: Target filename (preferred)
 
         Returns:
             File metadata dict with id, path, filename, checksum, etc.
 
         Examples:
-            result = dxp.files("models").save_torch(model, to="model.pt")
-            result = dxp.files("models").save_torch(model.state_dict(), to="weights.pth")
+            result = experiment.files("models").save_torch(model, to="model.pt")
+            result = experiment.files("models").save_torch(model.state_dict(), to="weights.pth")
         """
+        filename = to or file_name
+        if not filename:
+            raise ValueError("'to' parameter is required")
 
         prefix = '/' + self._path.lstrip('/') if self._path else self._prefix
 
         return self._save_torch(
             model=model,
-            filename=to,
+            filename=filename,
             prefix=prefix,
             description=self._description,
             tags=self._tags,
@@ -853,28 +852,34 @@ class FileBuilder:
     def save_pkl(
         self,
         content: Any,
+        file_name: Optional[str] = None,
         *,
-        to: str
+        to: Optional[str] = None
     ) -> Dict[str, Any]:
         """
         Save Python object to a pickle file.
 
         Args:
             content: Python object to pickle (must be pickle-serializable)
-            to: Target filename
+            file_name: Name of the file to create (deprecated, use 'to')
+            to: Target filename (preferred)
 
         Returns:
             File metadata dict with id, path, filename, checksum, etc.
 
         Examples:
             data = {"model": "resnet50", "weights": np.array([1, 2, 3])}
-            result = dxp.files("data").save_pkl(data, to="data.pkl")
+            result = experiment.files("data").save_pkl(data, to="data.pkl")
         """
+        filename = to or file_name
+        if not filename:
+            raise ValueError("'to' parameter is required")
+
         prefix = '/' + self._path.lstrip('/') if self._path else self._prefix
 
         return self._save_pickle(
             content=content,
-            filename=to,
+            filename=filename,
             prefix=prefix,
             description=self._description,
             tags=self._tags,
@@ -884,8 +889,9 @@ class FileBuilder:
     def save_fig(
         self,
         fig: Optional[Any] = None,
+        file_name: Optional[str] = None,
         *,
-        to: str,
+        to: Optional[str] = None,
         **kwargs
     ) -> Dict[str, Any]:
         """
@@ -893,7 +899,8 @@ class FileBuilder:
 
         Args:
             fig: Matplotlib figure object. If None, uses plt.gcf() (current figure)
-            to: Target filename
+            file_name: Name of file to create (deprecated, use 'to')
+            to: Target filename (preferred)
             **kwargs: Additional arguments passed to fig.savefig()
 
         Returns:
@@ -901,13 +908,17 @@ class FileBuilder:
 
         Examples:
             plt.plot([1, 2, 3], [1, 4, 9])
-            result = dxp.files("plots").save_fig(to="plot.png")
+            result = experiment.files("plots").save_fig(to="plot.png")
         """
         try:
             import matplotlib.pyplot as plt
         except ImportError:
             raise ImportError("Matplotlib is not installed. Install it with: pip install matplotlib")
 
+        filename = to or file_name
+        if not filename:
+            raise ValueError("'to' parameter is required")
+
         if fig is None:
             fig = plt.gcf()
 
@@ -915,7 +926,7 @@ class FileBuilder:
 
         return self._save_fig(
             fig=fig,
-            filename=to,
+            filename=filename,
             prefix=prefix,
             description=self._description,
             tags=self._tags,
@@ -926,8 +937,9 @@ class FileBuilder:
     def save_video(
         self,
         frame_stack: Union[List, Any],
+        file_name: Optional[str] = None,
         *,
-        to: str,
+        to: Optional[str] = None,
         fps: int = 20,
         **imageio_kwargs
     ) -> Dict[str, Any]:
@@ -936,7 +948,8 @@ class FileBuilder:
 
         Args:
             frame_stack: List of numpy arrays or stacked array
-            to: Target filename
+            file_name: Name of file to create (deprecated, use 'to')
+            to: Target filename (preferred)
             fps: Frames per second (default: 20)
             **imageio_kwargs: Additional arguments passed to imageio
 
@@ -945,7 +958,7 @@ class FileBuilder:
 
         Examples:
             frames = [np.random.rand(480, 640) for _ in range(30)]
-            result = dxp.files("videos").save_video(frames, to="output.mp4")
+            result = experiment.files("videos").save_video(frames, to="output.mp4")
         """
         import tempfile
         import os
@@ -960,6 +973,10 @@ class FileBuilder:
         except ImportError:
             raise ImportError("scikit-image is not installed. Install it with: pip install scikit-image")
 
+        filename = to or file_name
+        if not filename:
+            raise ValueError("'to' parameter is required")
+
         # Validate frame_stack
         try:
             if len(frame_stack) == 0:
@@ -970,9 +987,7 @@ class FileBuilder:
         prefix = '/' + self._path.lstrip('/') if self._path else self._prefix
 
         temp_dir = tempfile.mkdtemp()
-        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)
+        temp_path = os.path.join(temp_dir, filename)
 
         try:
             frames_ubyte = img_as_ubyte(frame_stack)
@@ -984,7 +999,7 @@ class FileBuilder:
                 iio.imwrite(temp_path, frames_ubyte, fps=fps, **imageio_kwargs)
 
             return self._save_file(
-                fpath=temp_path,
+                file_path=temp_path,
                 prefix=prefix,
                 description=self._description,
                 tags=self._tags,
@@ -1054,7 +1069,7 @@ class FileBuilder:
             )
 
             return self._save_file(
-                fpath=downloaded_path,
+                file_path=downloaded_path,
                 prefix=target_prefix,
                 description=self._description,
                 tags=self._tags,
@@ -1068,119 +1083,14 @@ class FileBuilder:
             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()")
-
-        # Create temporary file for download
-        temp_dir = tempfile.mkdtemp()
-        temp_filename = Path(self._path).name
-        temp_path = os.path.join(temp_dir, temp_filename)
-
-        try:
-            # Download the file
-            downloaded_path = self.download(to=temp_path)
-
-            # Read content as text
-            with open(downloaded_path, 'r', encoding=encoding) as f:
-                content = f.read()
-
-            return content
-        finally:
-            # Clean up temporary file
-            try:
-                if os.path.exists(temp_path):
-                    os.unlink(temp_path)
-                os.rmdir(temp_dir)
-            except Exception:
-                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("path")          # Returns FileBuilder
+        experiment.files.save(...)        # Direct method call
         experiment.files.download(...)    # Direct method call
     """
 
@@ -1188,55 +1098,27 @@ class FilesAccessor:
         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)
+    def __call__(self, path: Optional[str] = None, **kwargs) -> FileBuilder:
+        """Create a FileBuilder with the given path."""
+        return FileBuilder(self._experiment, path=path, **kwargs)
 
     # Direct methods that don't require a path first
 
-    def upload(
+    def save(
         self,
-        fpath: str,
+        obj: Optional[Any] = None,
         *,
         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.
+        Save a file directly.
 
         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")
+            experiment.files.save("./model.pt")
+            experiment.files.save(model, to="checkpoints/model.pt")
         """
-        # Parse 'to' to extract prefix and filename if provided
+        # Parse 'to' to extract prefix and filename
         if to:
             to_path = to.lstrip('/')
             if '/' in to_path:
@@ -1245,10 +1127,13 @@ class FilesAccessor:
             else:
                 prefix = '/'
                 filename = to_path
-            return FileBuilder(self._experiment, path=prefix, **kwargs).upload(fpath, to=filename)
+            return FileBuilder(self._experiment, path=prefix, **kwargs).save(obj, to=filename)
+
+        if isinstance(obj, str) and Path(obj).exists():
+            # obj is a file path, extract prefix from it
+            return FileBuilder(self._experiment, **kwargs).save(obj)
 
-        # No prefix, just upload with original or specified filename
-        return FileBuilder(self._experiment, **kwargs).upload(fpath)
+        raise ValueError("'to' parameter is required when not saving an existing file path")
 
     def download(
         self,