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

ml_dash/files.py

@@ -19,28 +19,45 @@ class FileBuilder:
     Fluent interface for file operations.
 
     Usage:
-        # Upload file
-        experiment.files("checkpoints").save(net, to="checkpoint.pt")
+        # 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("/some/location").list()
-        files = experiment.files("/models").list()
+        files = experiment.files(dir="some/location").list()
+        files = experiment.files(dir="models").list()
 
         # Download file
-        experiment.files("some.text").download()
-        experiment.files("some.text").download(to="./model.pt")
+        dxp.files("some.text").download()
+        dxp.files("some.text").download(to="./model.pt")
 
-        # Download Files via Glob Pattern
+        # Download files via glob pattern
         file_paths = experiment.files("images").list("*.png")
-        experiment.files("images").download("*.png")
+        dxp.files("images").download("*.png")
 
         # Delete files
-        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")
+        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', path: Optional[str] = None, **kwargs):
@@ -80,9 +97,9 @@ class FileBuilder:
             path = path.lstrip('/')
             self._normalized_path = '/' + path if not path.startswith('/') else path
 
-    def save(
+    def upload(
         self,
-        obj: Optional[Any] = None,
+        fpath: str,
         *,
         to: Optional[str] = None,
         description: Optional[str] = None,
@@ -90,21 +107,14 @@ class FileBuilder:
         metadata: Optional[Dict[str, Any]] = None
     ) -> Dict[str, Any]:
         """
-        Upload and save a file or object.
+        Upload an existing file from disk.
 
         Args:
-            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)
+            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.
@@ -115,19 +125,19 @@ class FileBuilder:
             ValueError: If file size exceeds 100GB limit
 
         Examples:
-            # 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")
+            # 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.")
@@ -135,6 +145,9 @@ 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
@@ -145,136 +158,109 @@ class FileBuilder:
         if self._path:
             prefix = '/' + self._path.lstrip('/')
 
-        # 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
-            )
+        return self._save_file(
+            fpath=fpath,
+            prefix=prefix,
+            description=desc,
+            tags=file_tags,
+            metadata=file_metadata,
+            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
-            )
+    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.
 
-        if isinstance(obj, bytes):
-            # Save bytes directly
+        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")
+
+        # 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_bytes(
-                data=obj,
-                filename=to,
-                prefix=prefix,
-                description=desc,
-                tags=file_tags,
-                metadata=file_metadata
-            )
+            return self.save_blob(content, to=to)
 
-        if isinstance(obj, (dict, list)):
-            # Try JSON first
+        # 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=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
+            return self.save_json(content, to=to)
 
-        # 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
-        )
+        raise ValueError(f"Unsupported content type: {type(content)}. Expected str (file path), bytes, dict, or list.")
 
     def _save_file(
         self,
-        file_path: str,
+        fpath: str,
         prefix: str,
         description: Optional[str],
         tags: Optional[List[str]],
-        metadata: Optional[Dict[str, Any]]
+        metadata: Optional[Dict[str, Any]],
+        to: Optional[str] = None
     ) -> Dict[str, Any]:
         """Internal method to save an existing file."""
-        file_path_obj = Path(file_path)
-        if not file_path_obj.exists():
-            raise ValueError(f"File not found: {file_path}")
+        fpath_obj = Path(fpath)
+        if not fpath_obj.exists():
+            raise ValueError(f"File not found: {fpath}")
 
-        if not file_path_obj.is_file():
-            raise ValueError(f"Path is not a file: {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_obj.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_obj))
+        checksum = compute_sha256(str(fpath_obj))
 
         # Detect MIME type
-        content_type = get_mime_type(str(file_path_obj))
+        content_type = get_mime_type(str(fpath_obj))
 
-        # Get filename
-        filename = file_path_obj.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_obj),
+            file_path=str(fpath_obj),
             prefix=prefix,
             filename=filename,
             description=description,
@@ -300,11 +286,13 @@ 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(
-                file_path=temp_path,
+                fpath=temp_path,
                 prefix=prefix,
                 description=description,
                 tags=tags,
@@ -333,11 +321,13 @@ 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(
-                file_path=temp_path,
+                fpath=temp_path,
                 prefix=prefix,
                 description=description,
                 tags=tags,
@@ -366,10 +356,12 @@ 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(
-                file_path=temp_path,
+                fpath=temp_path,
                 prefix=prefix,
                 description=description,
                 tags=tags,
@@ -399,11 +391,13 @@ 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(
-                file_path=temp_path,
+                fpath=temp_path,
                 prefix=prefix,
                 description=description,
                 tags=tags,
@@ -432,11 +426,13 @@ 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(
-                file_path=temp_path,
+                fpath=temp_path,
                 prefix=prefix,
                 description=description,
                 tags=tags,
@@ -721,34 +717,36 @@ class FileBuilder:
     def save_json(
         self,
         content: Any,
-        file_name: Optional[str] = None,
         *,
-        to: Optional[str] = None
+        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 (deprecated, use 'to')
-            to: Target filename (preferred)
+            to: Target filename
 
         Returns:
             File metadata dict with id, path, filename, checksum, etc.
 
         Examples:
             config = {"model": "resnet50", "lr": 0.001}
-            result = experiment.files("configs").save_json(config, to="config.json")
+            result = dxp.files("configs").save_json(config, to="config.json")
         """
-        filename = to or file_name
-        if not filename:
-            raise ValueError("'to' parameter is required")
-
         prefix = '/' + self._path.lstrip('/') if self._path else self._prefix
 
+        # 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=filename,
+            filename=to_filename,
             prefix=prefix,
             description=self._description,
             tags=self._tags,
@@ -770,14 +768,18 @@ class FileBuilder:
             result = experiment.files().save_text("Hello, world!", to="greeting.txt")
             result = experiment.files("configs").save_text(yaml_content, to="view.yaml")
         """
-        if not to:
-            raise ValueError("'to' parameter is required")
-
         prefix = '/' + self._path.lstrip('/') if self._path else self._prefix
 
+        # 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=to_filename,
             prefix=prefix,
             description=self._description,
             tags=self._tags,
@@ -798,14 +800,18 @@ class FileBuilder:
         Examples:
             result = experiment.files("data").save_blob(binary_data, to="model.bin")
         """
-        if not to:
-            raise ValueError("'to' parameter is required")
-
         prefix = '/' + self._path.lstrip('/') if self._path else self._prefix
 
+        # 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=to_filename,
             prefix=prefix,
             description=self._description,
             tags=self._tags,
@@ -815,34 +821,29 @@ class FileBuilder:
     def save_torch(
         self,
         model: Any,
-        file_name: Optional[str] = None,
         *,
-        to: Optional[str] = None
+        to: str
     ) -> Dict[str, Any]:
         """
         Save PyTorch model to a file.
 
         Args:
             model: PyTorch model or state dict to save
-            file_name: Name of the file to create (deprecated, use 'to')
-            to: Target filename (preferred)
+            to: Target filename
 
         Returns:
             File metadata dict with id, path, filename, checksum, etc.
 
         Examples:
-            result = experiment.files("models").save_torch(model, to="model.pt")
-            result = experiment.files("models").save_torch(model.state_dict(), to="weights.pth")
+            result = dxp.files("models").save_torch(model, to="model.pt")
+            result = dxp.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=filename,
+            filename=to,
             prefix=prefix,
             description=self._description,
             tags=self._tags,
@@ -852,34 +853,28 @@ class FileBuilder:
     def save_pkl(
         self,
         content: Any,
-        file_name: Optional[str] = None,
         *,
-        to: Optional[str] = None
+        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 (deprecated, use 'to')
-            to: Target filename (preferred)
+            to: Target filename
 
         Returns:
             File metadata dict with id, path, filename, checksum, etc.
 
         Examples:
             data = {"model": "resnet50", "weights": np.array([1, 2, 3])}
-            result = experiment.files("data").save_pkl(data, to="data.pkl")
+            result = dxp.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=filename,
+            filename=to,
             prefix=prefix,
             description=self._description,
             tags=self._tags,
@@ -889,9 +884,8 @@ class FileBuilder:
     def save_fig(
         self,
         fig: Optional[Any] = None,
-        file_name: Optional[str] = None,
         *,
-        to: Optional[str] = None,
+        to: str,
         **kwargs
     ) -> Dict[str, Any]:
         """
@@ -899,8 +893,7 @@ class FileBuilder:
 
         Args:
             fig: Matplotlib figure object. If None, uses plt.gcf() (current figure)
-            file_name: Name of file to create (deprecated, use 'to')
-            to: Target filename (preferred)
+            to: Target filename
             **kwargs: Additional arguments passed to fig.savefig()
 
         Returns:
@@ -908,17 +901,13 @@ class FileBuilder:
 
         Examples:
             plt.plot([1, 2, 3], [1, 4, 9])
-            result = experiment.files("plots").save_fig(to="plot.png")
+            result = dxp.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()
 
@@ -926,7 +915,7 @@ class FileBuilder:
 
         return self._save_fig(
             fig=fig,
-            filename=filename,
+            filename=to,
             prefix=prefix,
             description=self._description,
             tags=self._tags,
@@ -937,9 +926,8 @@ class FileBuilder:
     def save_video(
         self,
         frame_stack: Union[List, Any],
-        file_name: Optional[str] = None,
         *,
-        to: Optional[str] = None,
+        to: str,
         fps: int = 20,
         **imageio_kwargs
     ) -> Dict[str, Any]:
@@ -948,8 +936,7 @@ class FileBuilder:
 
         Args:
             frame_stack: List of numpy arrays or stacked array
-            file_name: Name of file to create (deprecated, use 'to')
-            to: Target filename (preferred)
+            to: Target filename
             fps: Frames per second (default: 20)
             **imageio_kwargs: Additional arguments passed to imageio
 
@@ -958,7 +945,7 @@ class FileBuilder:
 
         Examples:
             frames = [np.random.rand(480, 640) for _ in range(30)]
-            result = experiment.files("videos").save_video(frames, to="output.mp4")
+            result = dxp.files("videos").save_video(frames, to="output.mp4")
         """
         import tempfile
         import os
@@ -973,10 +960,6 @@ 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:
@@ -987,7 +970,9 @@ class FileBuilder:
         prefix = '/' + self._path.lstrip('/') if self._path else self._prefix
 
         temp_dir = tempfile.mkdtemp()
-        temp_path = os.path.join(temp_dir, filename)
+        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:
             frames_ubyte = img_as_ubyte(frame_stack)
@@ -999,7 +984,7 @@ class FileBuilder:
                 iio.imwrite(temp_path, frames_ubyte, fps=fps, **imageio_kwargs)
 
             return self._save_file(
-                file_path=temp_path,
+                fpath=temp_path,
                 prefix=prefix,
                 description=self._description,
                 tags=self._tags,
@@ -1069,7 +1054,7 @@ class FileBuilder:
             )
 
             return self._save_file(
-                file_path=downloaded_path,
+                fpath=downloaded_path,
                 prefix=target_prefix,
                 description=self._description,
                 tags=self._tags,
@@ -1083,14 +1068,119 @@ 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:
-        experiment.files("path")          # Returns FileBuilder
-        experiment.files.save(...)        # Direct method call
+        dxp.files("models")          # Returns FileBuilder
+        dxp.files(dir="models")      # Keyword argument form
+        experiment.files.upload(...)        # Direct method call
         experiment.files.download(...)    # Direct method call
     """
 
@@ -1098,27 +1188,55 @@ class FilesAccessor:
         self._experiment = experiment
         self._builder = FileBuilder(experiment)
 
-    def __call__(self, path: Optional[str] = None, **kwargs) -> FileBuilder:
-        """Create a FileBuilder with the given path."""
-        return FileBuilder(self._experiment, path=path, **kwargs)
+    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 save(
+    def upload(
         self,
-        obj: Optional[Any] = None,
+        fpath: str,
         *,
         to: Optional[str] = None,
         **kwargs
     ) -> Dict[str, Any]:
         """
-        Save a file directly.
+        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:
-            experiment.files.save("./model.pt")
-            experiment.files.save(model, to="checkpoints/model.pt")
+            # 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
+        # Parse 'to' to extract prefix and filename if provided
         if to:
             to_path = to.lstrip('/')
             if '/' in to_path:
@@ -1127,13 +1245,10 @@ class FilesAccessor:
             else:
                 prefix = '/'
                 filename = to_path
-            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)
+            return FileBuilder(self._experiment, path=prefix, **kwargs).upload(fpath, to=filename)
 
-        raise ValueError("'to' parameter is required when not saving an existing file path")
+        # No prefix, just upload with original or specified filename
+        return FileBuilder(self._experiment, **kwargs).upload(fpath)
 
     def download(
         self,