README Spaces deployment.md

🚀 HuggingFace Spaces Deployment Guide

Quick Deploy

Method 1: Using Spaces UI (Recommended)

1. Create New Space

   • Go to HuggingFace Spaces
   • Click "Create new Space"
   • Choose any name: code-interpreter-sandbox
   • Select License: mit
   • Select Hardware: t4-small (free tier available)
   • Select SDK: docker
   • Click "Create Space"

2. Upload Files

   # Clone your space repository
   git clone https://huggingface.co/spaces/your-username/code-interpreter-sandbox
   cd code-interpreter-sandbox
   
   # Copy all files from the code_interpreter directory
   cp /path/to/code_interpreter/* .
   
   # Add, commit and push
   git add .
   git commit -m "Initial commit: Advanced Code Interpreter"
   git push
   

3. Wait for Build

   • Spaces will automatically build your Docker image
   • Check the "Logs" tab for progress
   • Should take 5-10 minutes

4. Access Your Space

   • Once built, your space will be available at:
   • https://your-username-code-interpreter-sandbox.hf.space

Method 2: Using GitHub Integration

1. Create GitHub Repository

   # Create a new repo on GitHub
   # Upload all files to the repository
   

2. Connect to HuggingFace

   • Go to HuggingFace Spaces
   • Click "Create new Space"
   • Choose "Create from GitHub repo"
   • Select your repository
   • Follow the same steps as Method 1

🛠️ Configuration

Hardware Requirements

• Free Tier: t4-small or cpu-basic
• GPU: t4-medium or better for ML workloads
• Memory: 16GB+ recommended for large datasets

Environment Variables

No special environment variables required. All configuration is in app.py.

Port Configuration

• Port: 7860
• Host: 0.0.0.0
• Protocol: HTTP

📁 File Structure

code-interpreter-sandbox/
├── app.py                           # Main application
├── requirements.txt                 # Python dependencies
├── Dockerfile                       # Docker configuration
├── .huggingface/spaces_metadata     # Space metadata
├── README.md                        # Documentation
├── examples/
│   ├── data_analysis_example.py     # Data analysis demo
│   ├── ml_example.py                # Machine learning demo
│   └── visualization_example.py     # Visualization demo
└── config/
    ├── packages.json                # Pre-configured packages
    └── settings.json                # App settings

🎯 Features Overview

✅ Implemented Features

1. Code Execution Engine

   • Secure Python execution
   • Timeout protection
   • Error handling
   • Output capture (stdout/stderr)

2. File Management

   • Upload files
   • Download results
   • File browser
   • Multi-file support
   • Session isolation

3. Package Manager

   • pip installation
   • Popular packages pre-installed
   • Batch installation
   • Package tracking

4. Visualization Support

   • Matplotlib integration
   • Plotly support
   • Seaborn compatibility
   • Bokeh and Altair ready

5. Session Management

   • State persistence
   • Uptime tracking
   • File history
   • Package history

6. User Interface

   • Gradio-based UI
   • Tabbed interface
   • Syntax highlighting
   • Dark theme
   • Responsive design

📊 Pre-installed Packages

Essential packages included in requirements.txt:

# Data Science
numpy>=1.24.0          # Numerical computing
pandas>=2.0.0          # Data manipulation
matplotlib>=3.7.0      # Plotting
plotly>=5.15.0         # Interactive plots
seaborn>=0.12.0        # Statistical visualization
scipy>=1.10.0          # Scientific computing
scikit-learn>=1.3.0    # Machine learning

# Image Processing
Pillow>=10.0.0         # Image handling

# Web & APIs
requests>=2.31.0       # HTTP client
beautifulsoup4>=4.12.0 # Web scraping

# NLP
nltk>=3.8.0            # Natural language processing
spacy>=3.6.0           # Advanced NLP

# Graphs
networkx>=3.1          # Graph library

# Math
sympy>=1.12            # Symbolic math

# Visualization
bokeh>=3.2.0           # Interactive plots
altair>=5.0.0          # Declarative visualization

🔧 Customization

Adding Pre-installed Packages

Edit requirements.txt to add more packages:

# Add your packages here
your-package>=1.0.0
another-package>=2.0.0

Customizing Timeout/Resource Limits

Edit the CodeExecutor class in app.py:

class CodeExecutor:
    def __init__(self, timeout=30, memory_limit=1024):  # Increase limits
        self.timeout = timeout
        self.memory_limit = memory_limit

Adding New Tabs/Features

Add new tabs in the Gradio interface:

with gr.Tab("Your New Tab"):
    # Your custom interface
    pass

Custom CSS Styling

Edit the CUSTOM_CSS variable in app.py:

CUSTOM_CSS = """
.gradio-container {
    max-width: 1600px !important;  /* Wider interface */
}
"""

🚨 Troubleshooting

Build Fails

• Check Dockerfile syntax
• Verify requirements.txt format
• Review build logs
• Ensure all imports are correct

App Not Loading

• Check port configuration
• Verify environment variables
• Review application logs
• Test locally first

Package Installation Issues

• Use correct package names (PyPI names)
• Check version compatibility
• Some packages may require system dependencies
• Review pip output for errors

Memory/Timeout Issues

• Adjust timeout parameter
• Use smaller datasets
• Process data in chunks
• Consider upgrading hardware tier

📈 Performance Optimization

For Free Tier (t4-small)

• Use efficient algorithms
• Avoid large data loading
• Clear variables between runs
• Use generators/iterators

For GPU Tier

• Enable GPU acceleration
• Install CUDA packages
• Use libraries like TensorFlow/PyTorch
• Optimize for parallel processing

🔒 Security

Built-in Protections

• Execution timeouts
• Memory limits
• Isolated file system
• Session-based isolation

Best Practices

• Don't execute untrusted code
• Monitor resource usage
• Clear sensitive data
• Use secure package sources

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Support

• Check HuggingFace Spaces Docs
• Review Gradio Documentation
• Open an Issue for bugs
• Join our Community

🙏 Credits

• Gradio: Amazing UI framework
• HuggingFace: Excellent hosting platform
• Python: Core language
• Community: Users and contributors

---

Happy Coding! 🚀