Add persistent storage support for Hugging Face Spaces - Enhanced app.py with automatic persistent storage detection - Added comprehensive persistent storage utilities - Added documentation and examples - Automatic HF_HOME and cache configuration for /data directory

PERSISTENT_STORAGE_README.md

@@ -0,0 +1,384 @@
+# Persistent Storage Setup for Hugging Face Spaces
+
+This guide explains how to set up and use persistent storage in Hugging Face Spaces for your LMM-Vibes application.
+
+## Overview
+
+Hugging Face Spaces provides persistent storage at the `/data` directory that persists across app restarts and deployments. This storage is perfect for:
+
+- Caching models and datasets
+- Storing user uploads and results
+- Maintaining application state
+- Saving experiment results
+
+## Quick Start
+
+### 1. Automatic Setup (Already Implemented)
+
+Your application automatically detects and configures persistent storage when running in Hugging Face Spaces:
+
+```python
+# This is already handled in app.py
+if is_persistent_storage_available():
+    # Configure HF cache to persistent storage
+    hf_home = get_hf_home_dir()
+    os.environ.setdefault("HF_HOME", str(hf_home))
+    
+    # Set cache directories
+    cache_dir = get_cache_dir()
+    os.environ.setdefault("TRANSFORMERS_CACHE", str(cache_dir / "transformers"))
+    os.environ.setdefault("HF_DATASETS_CACHE", str(cache_dir / "datasets"))
+```
+
+### 2. Storage Structure
+
+When persistent storage is available, your data is organized as follows:
+
+```
+/data/
+├── app_data/                    # Main application data
+│   ├── experiments/             # Pipeline results and experiments
+│   ├── dataframes/              # Saved pandas DataFrames
+│   ├── logs/                    # Application logs
+│   └── uploads/                 # User uploaded files
+├── .cache/                      # Application cache
+│   ├── transformers/            # Hugging Face Transformers cache
+│   └── datasets/                # Hugging Face Datasets cache
+└── .huggingface/               # Hugging Face model cache
+```
+
+## Usage Examples
+
+### Saving Data
+
+```python
+from lmmvibes.utils.persistent_storage import (
+    save_data_to_persistent,
+    save_uploaded_file
+)
+
+# Save binary data
+data_bytes = b"your binary data"
+saved_path = save_data_to_persistent(
+    data=data_bytes,
+    filename="my_data.bin",
+    subdirectory="experiments"
+)
+
+# Save uploaded file from Gradio
+def handle_upload(uploaded_file):
+    if uploaded_file:
+        saved_path = save_uploaded_file(uploaded_file, "user_upload.zip")
+        return f"Saved to: {saved_path}"
+```
+
+### Loading Data
+
+```python
+from lmmvibes.utils.persistent_storage import load_data_from_persistent
+
+# Load binary data
+data_bytes = load_data_from_persistent("my_data.bin", "experiments")
+if data_bytes:
+    # Process the data
+    data = data_bytes.decode('utf-8')
+```
+
+### Listing Files
+
+```python
+from lmmvibes.utils.persistent_storage import list_persistent_files
+
+# List all files
+all_files = list_persistent_files()
+
+# List specific types of files
+json_files = list_persistent_files(subdirectory="experiments", pattern="*.json")
+parquet_files = list_persistent_files(subdirectory="dataframes", pattern="*.parquet")
+```
+
+### Checking Storage Status
+
+```python
+from lmmvibes.utils.persistent_storage import get_storage_info
+
+info = get_storage_info()
+print(f"Persistent storage available: {info['persistent_available']}")
+print(f"Data directory: {info['data_dir']}")
+print(f"Free space: {info['storage_paths']['free_gb']:.1f}GB")
+```
+
+## Integration with Your Application
+
+### 1. Data Loading
+
+Your application already uses persistent storage for loading pipeline results:
+
+```python
+# In data_loader.py - automatically uses persistent storage when available
+def load_pipeline_results(results_dir: str):
+    # The function automatically checks for data in persistent storage
+    # Falls back to local storage if persistent storage is not available
+    pass
+```
+
+### 2. Caching
+
+The application automatically caches data in persistent storage:
+
+```python
+# In data_loader.py - DataCache uses persistent storage when available
+class DataCache:
+    @classmethod
+    def get(cls, key: str):
+        # Check persistent storage first, then memory cache
+        return cls._cache.get(key)
+```
+
+### 3. User Uploads
+
+For handling user uploads in Gradio:
+
+```python
+import gradio as gr
+from lmmvibes.utils.persistent_storage import save_uploaded_file
+
+def handle_file_upload(file):
+    if file:
+        saved_path = save_uploaded_file(file, "user_upload.zip")
+        if saved_path:
+            return f"✅ File saved to persistent storage: {saved_path.name}"
+        else:
+            return "❌ Failed to save - persistent storage not available"
+    return "⚠️ No file uploaded"
+
+# In your Gradio interface
+with gr.Blocks() as demo:
+    file_input = gr.File(label="Upload data")
+    upload_btn = gr.Button("Save to persistent storage")
+    result = gr.Textbox(label="Status")
+    
+    upload_btn.click(handle_file_upload, inputs=[file_input], outputs=[result])
+```
+
+## Best Practices
+
+### 1. Check Availability
+
+Always check if persistent storage is available before trying to use it:
+
+```python
+from lmmvibes.utils.persistent_storage import is_persistent_storage_available
+
+if is_persistent_storage_available():
+    # Use persistent storage
+    save_data_to_persistent(data, "important_data.json")
+else:
+    # Fall back to local storage or in-memory
+    print("Persistent storage not available")
+```
+
+### 2. Organize Data
+
+Use subdirectories to organize your data:
+
+```python
+# Save experiments in their own directory
+save_data_to_persistent(
+    data=experiment_data,
+    filename=f"{experiment_name}_results.json",
+    subdirectory="experiments"
+)
+
+# Save dataframes separately
+save_data_to_persistent(
+    data=dataframe_bytes,
+    filename=f"{dataset_name}_data.parquet",
+    subdirectory="dataframes"
+)
+```
+
+### 3. Handle Errors Gracefully
+
+```python
+def safe_save_data(data, filename):
+    try:
+        saved_path = save_data_to_persistent(data, filename)
+        if saved_path:
+            return f"✅ Saved to {saved_path}"
+        else:
+            return "❌ Failed to save - storage not available"
+    except Exception as e:
+        return f"❌ Error saving data: {e}"
+```
+
+### 4. Clean Up Old Data
+
+Periodically clean up old files to manage storage space:
+
+```python
+from lmmvibes.utils.persistent_storage import list_persistent_files, delete_persistent_file
+
+def cleanup_old_files(days_old=30):
+    """Delete files older than specified days."""
+    import time
+    cutoff_time = time.time() - (days_old * 24 * 60 * 60)
+    
+    for file in list_persistent_files():
+        if file.stat().st_mtime < cutoff_time:
+            delete_persistent_file(file.name)
+```
+
+## Troubleshooting
+
+### 1. Storage Not Available
+
+If persistent storage is not working:
+
+```python
+from lmmvibes.utils.persistent_storage import get_storage_info
+
+info = get_storage_info()
+print(f"Storage available: {info['persistent_available']}")
+print(f"Data directory: {info['data_dir']}")
+```
+
+### 2. Permission Issues
+
+If you encounter permission issues:
+
+```python
+# The utilities automatically create directories with proper permissions
+# If issues persist, check if /data exists and is writable
+import os
+if os.path.isdir("/data") and os.access("/data", os.W_OK):
+    print("✅ Persistent storage is accessible and writable")
+else:
+    print("❌ Persistent storage not accessible")
+```
+
+### 3. Storage Full
+
+Monitor storage usage:
+
+```python
+info = get_storage_info()
+if info['storage_paths']:
+    usage_pct = (info['storage_paths']['used_gb'] / info['storage_paths']['total_gb']) * 100
+    if usage_pct > 90:
+        print(f"⚠️  Storage nearly full: {usage_pct:.1f}% used")
+        # Implement cleanup logic
+```
+
+## Migration from Local Storage
+
+If you're migrating from local storage to persistent storage:
+
+1. **Backup existing data**: Copy your local `data/` directory to persistent storage
+2. **Update paths**: Use the persistent storage utilities instead of hardcoded paths
+3. **Test thoroughly**: Ensure all functionality works with persistent storage
+4. **Monitor usage**: Keep track of storage usage and implement cleanup
+
+## Example: Complete Integration
+
+Here's a complete example of integrating persistent storage into your application:
+
+```python
+import gradio as gr
+import json
+import pandas as pd
+from lmmvibes.utils.persistent_storage import (
+    save_data_to_persistent,
+    load_data_from_persistent,
+    list_persistent_files,
+    get_storage_info,
+    is_persistent_storage_available
+)
+
+def save_experiment_results(results_data, experiment_name):
+    """Save experiment results to persistent storage."""
+    if not is_persistent_storage_available():
+        return "❌ Persistent storage not available"
+    
+    try:
+        results_json = json.dumps(results_data, indent=2)
+        results_bytes = results_json.encode('utf-8')
+        
+        filename = f"{experiment_name}_results.json"
+        saved_path = save_data_to_persistent(
+            data=results_bytes,
+            filename=filename,
+            subdirectory="experiments"
+        )
+        
+        if saved_path:
+            return f"✅ Saved experiment to: {saved_path.name}"
+        else:
+            return "❌ Failed to save experiment"
+    except Exception as e:
+        return f"❌ Error: {e}"
+
+def load_experiment_results(experiment_name):
+    """Load experiment results from persistent storage."""
+    filename = f"{experiment_name}_results.json"
+    results_bytes = load_data_from_persistent(
+        filename=filename,
+        subdirectory="experiments"
+    )
+    
+    if results_bytes:
+        results_data = json.loads(results_bytes.decode('utf-8'))
+        return json.dumps(results_data, indent=2)
+    else:
+        return "No results found"
+
+def get_available_experiments():
+    """List all available experiments."""
+    experiment_files = list_persistent_files(subdirectory="experiments", pattern="*_results.json")
+    if experiment_files:
+        return "\n".join([f.name for f in experiment_files])
+    else:
+        return "No experiments found"
+
+# Gradio interface
+with gr.Blocks(title="Persistent Storage Demo") as demo:
+    gr.Markdown("# Persistent Storage Demo")
+    
+    with gr.Tab("Save Experiment"):
+        experiment_name = gr.Textbox(label="Experiment Name")
+        results_json = gr.Textbox(label="Results (JSON)", lines=5)
+        save_btn = gr.Button("Save Experiment")
+        save_result = gr.Textbox(label="Save Result")
+        
+        save_btn.click(
+            save_experiment_results,
+            inputs=[results_json, experiment_name],
+            outputs=[save_result]
+        )
+    
+    with gr.Tab("Load Experiment"):
+        load_experiment_name = gr.Textbox(label="Experiment Name")
+        load_btn = gr.Button("Load Experiment")
+        load_result = gr.Textbox(label="Loaded Results", lines=10)
+        
+        load_btn.click(
+            load_experiment_results,
+            inputs=[load_experiment_name],
+            outputs=[load_result]
+        )
+    
+    with gr.Tab("Storage Info"):
+        info_btn = gr.Button("Get Storage Info")
+        storage_info = gr.Textbox(label="Storage Information", lines=10)
+        
+        def get_info():
+            info = get_storage_info()
+            return json.dumps(info, indent=2)
+        
+        info_btn.click(get_info, outputs=[storage_info])
+
+if __name__ == "__main__":
+    demo.launch()
+```
+
+This comprehensive setup ensures your application can take full advantage of Hugging Face Spaces' persistent storage capabilities while maintaining backward compatibility with local development. 

README.md

@@ -2,6 +2,7 @@
 title: Whatever This Is
 colorFrom: yellow
 colorTo: gray
+emoji: 🇬🇮
 sdk: gradio
 sdk_version: 5.41.1
 app_file: app.py

app.py

@@ -1,10 +1,39 @@
 import os
+from pathlib import Path
 
 from lmmvibes.vis_gradio.app import launch_app
+from lmmvibes.utils.persistent_storage import (
+    get_hf_home_dir, 
+    get_cache_dir, 
+    is_persistent_storage_available,
+    get_storage_info
+)
 
 # Launch the app for Hugging Face Spaces
 if __name__ == "__main__":
-    # Optimize HF cache to persistent storage in Spaces
-    if os.path.isdir("/data"):
-        os.environ.setdefault("HF_HOME", "/data/.huggingface")
+    # Set up persistent storage for Hugging Face Spaces
+    if is_persistent_storage_available():
+        print("🚀 Persistent storage available - configuring for HF Spaces")
+        
+        # Set Hugging Face cache to persistent storage
+        hf_home = get_hf_home_dir()
+        os.environ.setdefault("HF_HOME", str(hf_home))
+        
+        # Set cache directory for other libraries
+        cache_dir = get_cache_dir()
+        os.environ.setdefault("TRANSFORMERS_CACHE", str(cache_dir / "transformers"))
+        os.environ.setdefault("HF_DATASETS_CACHE", str(cache_dir / "datasets"))
+        
+        # Print storage info
+        storage_info = get_storage_info()
+        print(f"📁 Data directory: {storage_info['data_dir']}")
+        print(f"🗄️  Cache directory: {storage_info['cache_dir']}")
+        print(f"🤗 HF Home: {storage_info['hf_home']}")
+        
+        if storage_info['storage_paths']:
+            print(f"💾 Storage: {storage_info['storage_paths']['free_gb']:.1f}GB free / {storage_info['storage_paths']['total_gb']:.1f}GB total")
+    else:
+        print("⚠️  Persistent storage not available - using local storage")
+    
+    # Launch the Gradio app
     launch_app(share=False, server_name="0.0.0.0", server_port=7860)

lmmvibes/utils/persistent_storage.py

@@ -1,14 +1,22 @@
 """
 Utilities for persistent storage in Hugging Face Spaces.
+
+This module provides utilities for managing persistent storage in Hugging Face Spaces,
+including data directories, cache management, and file operations.
 """
 import os
+import shutil
 from pathlib import Path
-from typing import Optional
+from typing import Optional, Union
+import tempfile
 
 
 def get_persistent_data_dir() -> Optional[Path]:
     """Get the persistent data directory if available.
     
+    In Hugging Face Spaces, this will be `/data/app_data`.
+    Returns None if persistent storage is not available.
+    
     Returns:
         Path to persistent storage directory if available, None otherwise.
     """
@@ -22,6 +30,9 @@ def get_persistent_data_dir() -> Optional[Path]:
 def get_cache_dir() -> Path:
     """Get the appropriate cache directory (persistent if available, temp otherwise).
     
+    In Hugging Face Spaces, this will be `/data/.cache`.
+    Falls back to temp directory in local development.
+    
     Returns:
         Path to cache directory.
     """
@@ -31,10 +42,27 @@ def get_cache_dir() -> Path:
         return cache_dir
     else:
         # Fallback to temp directory
-        import tempfile
         return Path(tempfile.gettempdir()) / "app_cache"
 
 
+def get_hf_home_dir() -> Path:
+    """Get the Hugging Face home directory for model caching.
+    
+    In Hugging Face Spaces, this will be `/data/.huggingface`.
+    Falls back to default ~/.cache/huggingface in local development.
+    
+    Returns:
+        Path to HF home directory.
+    """
+    if os.path.isdir("/data"):
+        hf_home = Path("/data/.huggingface")
+        hf_home.mkdir(exist_ok=True)
+        return hf_home
+    else:
+        # Fallback to default location
+        return Path.home() / ".cache" / "huggingface"
+
+
 def save_uploaded_file(uploaded_file, filename: str) -> Optional[Path]:
     """Save an uploaded file to persistent storage.
     
@@ -51,12 +79,112 @@ def save_uploaded_file(uploaded_file, filename: str) -> Optional[Path]:
         save_path.parent.mkdir(parents=True, exist_ok=True)
         
         # Copy the uploaded file to persistent storage
-        import shutil
-        shutil.copy2(uploaded_file, save_path)
+        if hasattr(uploaded_file, 'name'):
+            # Gradio file object
+            shutil.copy2(uploaded_file.name, save_path)
+        else:
+            # Direct file path
+            shutil.copy2(uploaded_file, save_path)
+        return save_path
+    return None
+
+
+def save_data_to_persistent(data: bytes, filename: str, subdirectory: str = "") -> Optional[Path]:
+    """Save binary data to persistent storage.
+    
+    Args:
+        data: Binary data to save
+        filename: Name to save the file as
+        subdirectory: Optional subdirectory within persistent storage
+        
+    Returns:
+        Path to saved file if successful, None otherwise.
+    """
+    persistent_dir = get_persistent_data_dir()
+    if persistent_dir:
+        if subdirectory:
+            save_dir = persistent_dir / subdirectory
+            save_dir.mkdir(exist_ok=True)
+        else:
+            save_dir = persistent_dir
+        
+        save_path = save_dir / filename
+        save_path.parent.mkdir(parents=True, exist_ok=True)
+        
+        with open(save_path, 'wb') as f:
+            f.write(data)
         return save_path
     return None
 
 
+def load_data_from_persistent(filename: str, subdirectory: str = "") -> Optional[bytes]:
+    """Load binary data from persistent storage.
+    
+    Args:
+        filename: Name of the file to load
+        subdirectory: Optional subdirectory within persistent storage
+        
+    Returns:
+        Binary data if successful, None otherwise.
+    """
+    persistent_dir = get_persistent_data_dir()
+    if persistent_dir:
+        if subdirectory:
+            load_path = persistent_dir / subdirectory / filename
+        else:
+            load_path = persistent_dir / filename
+        
+        if load_path.exists():
+            with open(load_path, 'rb') as f:
+                return f.read()
+    return None
+
+
+def list_persistent_files(subdirectory: str = "", pattern: str = "*") -> list[Path]:
+    """List files in persistent storage.
+    
+    Args:
+        subdirectory: Optional subdirectory within persistent storage
+        pattern: Glob pattern to match files (e.g., "*.json", "data_*")
+        
+    Returns:
+        List of Path objects for matching files.
+    """
+    persistent_dir = get_persistent_data_dir()
+    if persistent_dir:
+        if subdirectory:
+            search_dir = persistent_dir / subdirectory
+        else:
+            search_dir = persistent_dir
+        
+        if search_dir.exists():
+            return list(search_dir.glob(pattern))
+    return []
+
+
+def delete_persistent_file(filename: str, subdirectory: str = "") -> bool:
+    """Delete a file from persistent storage.
+    
+    Args:
+        filename: Name of the file to delete
+        subdirectory: Optional subdirectory within persistent storage
+        
+    Returns:
+        True if successful, False otherwise.
+    """
+    persistent_dir = get_persistent_data_dir()
+    if persistent_dir:
+        if subdirectory:
+            file_path = persistent_dir / subdirectory / filename
+        else:
+            file_path = persistent_dir / filename
+        
+        if file_path.exists():
+            file_path.unlink()
+            return True
+    return False
+
+
 def is_persistent_storage_available() -> bool:
     """Check if persistent storage is available.
     
@@ -77,4 +205,50 @@ def get_persistent_results_dir() -> Optional[Path]:
         results_dir = persistent_dir / "results"
         results_dir.mkdir(exist_ok=True)
         return results_dir
-    return None 
+    return None
+
+
+def get_persistent_logs_dir() -> Optional[Path]:
+    """Get the persistent logs directory for storing application logs.
+    
+    Returns:
+        Path to persistent logs directory if available, None otherwise.
+    """
+    persistent_dir = get_persistent_data_dir()
+    if persistent_dir:
+        logs_dir = persistent_dir / "logs"
+        logs_dir.mkdir(exist_ok=True)
+        return logs_dir
+    return None
+
+
+def get_storage_info() -> dict:
+    """Get information about available storage.
+    
+    Returns:
+        Dictionary with storage information.
+    """
+    info = {
+        "persistent_available": is_persistent_storage_available(),
+        "data_dir": None,
+        "cache_dir": str(get_cache_dir()),
+        "hf_home": str(get_hf_home_dir()),
+        "storage_paths": {}
+    }
+    
+    if info["persistent_available"]:
+        data_dir = get_persistent_data_dir()
+        info["data_dir"] = str(data_dir)
+        
+        # Check available space
+        try:
+            total, used, free = shutil.disk_usage(data_dir)
+            info["storage_paths"] = {
+                "total_gb": round(total / (1024**3), 2),
+                "used_gb": round(used / (1024**3), 2),
+                "free_gb": round(free / (1024**3), 2)
+            }
+        except OSError:
+            pass
+    
+    return info 

lmmvibes/utils/persistent_storage_example.py

@@ -0,0 +1,252 @@
+"""
+Example usage of persistent storage utilities for Hugging Face Spaces.
+
+This file demonstrates how to use the persistent storage utilities
+for saving and loading data in Hugging Face Spaces.
+"""
+
+import json
+import pandas as pd
+from pathlib import Path
+
+from .persistent_storage import (
+    get_persistent_data_dir,
+    get_cache_dir,
+    get_hf_home_dir,
+    save_data_to_persistent,
+    load_data_from_persistent,
+    save_uploaded_file,
+    list_persistent_files,
+    delete_persistent_file,
+    is_persistent_storage_available,
+    get_storage_info
+)
+
+
+def example_save_results(results_data: dict, experiment_name: str):
+    """Example: Save pipeline results to persistent storage.
+    
+    Args:
+        results_data: Dictionary containing pipeline results
+        experiment_name: Name of the experiment
+    """
+    if not is_persistent_storage_available():
+        print("⚠️  Persistent storage not available - skipping save")
+        return None
+    
+    # Save results as JSON
+    results_json = json.dumps(results_data, indent=2)
+    results_bytes = results_json.encode('utf-8')
+    
+    filename = f"{experiment_name}_results.json"
+    saved_path = save_data_to_persistent(
+        data=results_bytes,
+        filename=filename,
+        subdirectory="experiments"
+    )
+    
+    if saved_path:
+        print(f"✅ Saved results to: {saved_path}")
+        return saved_path
+    else:
+        print("❌ Failed to save results")
+        return None
+
+
+def example_load_results(experiment_name: str):
+    """Example: Load pipeline results from persistent storage.
+    
+    Args:
+        experiment_name: Name of the experiment
+        
+    Returns:
+        Dictionary containing the loaded results or None
+    """
+    filename = f"{experiment_name}_results.json"
+    results_bytes = load_data_from_persistent(
+        filename=filename,
+        subdirectory="experiments"
+    )
+    
+    if results_bytes:
+        results_data = json.loads(results_bytes.decode('utf-8'))
+        print(f"✅ Loaded results from: {filename}")
+        return results_data
+    else:
+        print(f"❌ No results found for: {filename}")
+        return None
+
+
+def example_save_dataframe(df: pd.DataFrame, filename: str):
+    """Example: Save a pandas DataFrame to persistent storage.
+    
+    Args:
+        df: DataFrame to save
+        filename: Name of the file (with .parquet extension)
+    """
+    if not is_persistent_storage_available():
+        print("⚠️  Persistent storage not available - skipping save")
+        return None
+    
+    # Convert DataFrame to parquet bytes
+    try:
+        parquet_bytes = df.to_parquet()
+        saved_path = save_data_to_persistent(
+            data=parquet_bytes,
+            filename=filename,
+            subdirectory="dataframes"
+        )
+        
+        if saved_path:
+            print(f"✅ Saved DataFrame to: {saved_path}")
+            return saved_path
+        else:
+            print("❌ Failed to save DataFrame")
+            return None
+    except Exception as e:
+        print(f"❌ Error saving DataFrame: {e}")
+        return None
+
+
+def example_list_saved_files():
+    """Example: List all files saved in persistent storage."""
+    if not is_persistent_storage_available():
+        print("⚠️  Persistent storage not available")
+        return []
+    
+    print("📁 Files in persistent storage:")
+    
+    # List all files
+    all_files = list_persistent_files()
+    if all_files:
+        for file in all_files:
+            print(f"  - {file.name}")
+    else:
+        print("  No files found")
+    
+    # List experiment files
+    experiment_files = list_persistent_files(subdirectory="experiments", pattern="*.json")
+    if experiment_files:
+        print("\n🔬 Experiment files:")
+        for file in experiment_files:
+            print(f"  - {file.name}")
+    
+    # List dataframe files
+    dataframe_files = list_persistent_files(subdirectory="dataframes", pattern="*.parquet")
+    if dataframe_files:
+        print("\n📊 DataFrame files:")
+        for file in dataframe_files:
+            print(f"  - {file.name}")
+    
+    return all_files
+
+
+def example_storage_cleanup(days_old: int = 30):
+    """Example: Clean up old files from persistent storage.
+    
+    Args:
+        days_old: Delete files older than this many days
+    """
+    if not is_persistent_storage_available():
+        print("⚠️  Persistent storage not available")
+        return
+    
+    import time
+    from datetime import datetime, timedelta
+    
+    cutoff_time = time.time() - (days_old * 24 * 60 * 60)
+    
+    print(f"🧹 Cleaning up files older than {days_old} days...")
+    
+    # List all files and check their modification time
+    all_files = list_persistent_files()
+    deleted_count = 0
+    
+    for file in all_files:
+        if file.stat().st_mtime < cutoff_time:
+            if delete_persistent_file(file.name):
+                print(f"🗑️  Deleted: {file.name}")
+                deleted_count += 1
+    
+    print(f"✅ Cleanup complete - deleted {deleted_count} files")
+
+
+def example_storage_info():
+    """Example: Display information about persistent storage."""
+    info = get_storage_info()
+    
+    print("📊 Persistent Storage Information:")
+    print(f"  Available: {info['persistent_available']}")
+    
+    if info['persistent_available']:
+        print(f"  Data directory: {info['data_dir']}")
+        print(f"  Cache directory: {info['cache_dir']}")
+        print(f"  HF Home: {info['hf_home']}")
+        
+        if info['storage_paths']:
+            print(f"  Total storage: {info['storage_paths']['total_gb']:.1f}GB")
+            print(f"  Used storage: {info['storage_paths']['used_gb']:.1f}GB")
+            print(f"  Free storage: {info['storage_paths']['free_gb']:.1f}GB")
+            
+            # Calculate usage percentage
+            usage_pct = (info['storage_paths']['used_gb'] / info['storage_paths']['total_gb']) * 100
+            print(f"  Usage: {usage_pct:.1f}%")
+
+
+# Example usage in a Gradio app
+def example_gradio_integration():
+    """Example: How to integrate persistent storage with Gradio."""
+    
+    def save_uploaded_data(uploaded_file):
+        """Save a file uploaded through Gradio."""
+        if uploaded_file:
+            saved_path = save_uploaded_file(uploaded_file, "user_upload.txt")
+            if saved_path:
+                return f"✅ File saved to persistent storage: {saved_path.name}"
+            else:
+                return "❌ Failed to save file - persistent storage not available"
+        return "⚠️  No file uploaded"
+    
+    def load_user_data():
+        """Load previously uploaded data."""
+        data_bytes = load_data_from_persistent("user_upload.txt")
+        if data_bytes:
+            return data_bytes.decode('utf-8')
+        return "No data found"
+    
+    # This would be used in a Gradio interface like:
+    # import gradio as gr
+    # 
+    # with gr.Blocks() as demo:
+    #     file_input = gr.File(label="Upload file")
+    #     upload_btn = gr.Button("Save to persistent storage")
+    #     download_btn = gr.Button("Load from persistent storage")
+    #     
+    #     upload_btn.click(save_uploaded_data, inputs=[file_input])
+    #     download_btn.click(load_user_data)
+
+
+if __name__ == "__main__":
+    # Run examples
+    print("🔍 Persistent Storage Examples")
+    print("=" * 40)
+    
+    example_storage_info()
+    print()
+    
+    example_list_saved_files()
+    print()
+    
+    # Example: Save some test data
+    test_data = {"experiment": "test", "results": [1, 2, 3], "timestamp": "2024-01-01"}
+    example_save_results(test_data, "test_experiment")
+    print()
+    
+    # Example: Load the test data
+    loaded_data = example_load_results("test_experiment")
+    if loaded_data:
+        print(f"📊 Loaded data: {loaded_data}")
+    print()
+    
+    # Example: List files again
+    example_list_saved_files()