QUICK_START_GUIDE.md

# Quick Start Guide: CSV-First Deployment

This guide shows you exactly how to run the CSV-first deployment for your Hugging Face Space.

## Prerequisites

Make sure you have Python installed with these packages:
```bash
pip install pandas requests plotly gradio logging datetime typing os
```

## Step 1: Generate CSV Files Locally

### Option A: Using the Interactive Script (Recommended)

1. **Open your terminal** in the project directory
2. **Run the CSV generation script**:
   ```bash
   python generate_csv_for_space.py
   ```

3. **Follow the interactive prompts**:
   ```
   ============================================================
   CSV Generation for Hugging Face Space Deployment
   ============================================================

   1. Checking existing CSV files...
   2. Checking data freshness...
   3. Data generation options:
      [1] Generate fresh data from API (recommended)
      [2] Skip if CSV files are fresh (< 24 hours old)
      [3] Exit without generating

   Enter your choice (1-3): 1
   ```

4. **Choose option 1** to generate fresh data
5. **Wait for completion** - the script will:
   - Fetch data from the API
   - Apply preprocessing
   - Save CSV files
   - Show you what files were created

### Option B: Using Python Directly

If you prefer to run it programmatically:

```python
# Run this in Python or Jupyter notebook
from app import fetch_apr_data_from_db, save_to_csv, save_roi_to_csv
from initial_value_fixer import fix_apr_and_roi

# Fetch data
df_apr, df_roi = fetch_apr_data_from_db()

# Apply preprocessing
df_apr_processed = fix_apr_and_roi(df_apr)

# Save CSV files
save_to_csv(df_apr_processed)
save_roi_to_csv(df_roi)

print("CSV files generated successfully!")
```

## Step 2: Verify CSV Files Were Created

Check that these files exist in your directory:
```bash
ls -la *.csv
```

You should see:
- `optimus_apr_values.csv`
- `optimus_apr_statistics.csv`
- `optimus_roi_values.csv`

## Step 3: Test CSV Loading Locally (Optional)

Test that the CSV files load correctly:

```python
from load_from_csv import load_apr_data_from_csv, load_roi_data_from_csv

# Test loading
df_apr, csv_file = load_apr_data_from_csv()
df_roi, csv_file = load_roi_data_from_csv()

print(f"APR data loaded: {len(df_apr)} records")
print(f"ROI data loaded: {len(df_roi)} records")
```

## Step 4: Test the App Locally

Run your app locally to make sure everything works:

```bash
python app.py
```

The app should:
1. Try to load from CSV files first
2. Show visualizations using CSV data
3. Display "Successfully loaded APR/ROI data from CSV" in logs

## Step 5: Deploy to Hugging Face Space

### Upload These Files to Your Space:

**Required Files:**
- `app.py` (modified with CSV-first logic)
- `load_from_csv.py` (new CSV loading functions)
- `initial_value_fixer.py` (existing preprocessing)
- `fetch_and_preprocess_data.py` (existing data functions)

**Generated CSV Files:**
- `optimus_apr_values.csv`
- `optimus_apr_statistics.csv`
- `optimus_roi_values.csv`

### Upload Methods:

**Method 1: Hugging Face Web Interface**
1. Go to your Space on huggingface.co
2. Click "Files" tab
3. Upload each file individually
4. Commit changes

**Method 2: Git (if you have git setup)**
```bash
git add *.py *.csv
git commit -m "Add CSV-first deployment files"
git push
```

## Step 6: Monitor Your Space

After deployment:

1. **Check Space logs** for these messages:
   ```
   Successfully loaded APR data from CSV: X records
   Successfully loaded ROI data from CSV: Y records
   Creating APR visualizations from CSV data...
   ```

2. **Verify fast loading** - graphs should appear instantly

3. **No API calls** - you shouldn't see API-related errors in logs

## Troubleshooting

### Problem: "No module named 'load_from_csv'"
**Solution:** Make sure you uploaded `load_from_csv.py` to your Space

### Problem: "CSV file not found"
**Solution:** 
1. Check CSV files are in the Space root directory
2. Verify file names match exactly: `optimus_apr_values.csv`, `optimus_roi_values.csv`

### Problem: "Error loading data from CSV"
**Solution:**
1. Regenerate CSV files locally: `python generate_csv_for_space.py`
2. Re-upload the new CSV files to your Space

### Problem: App falls back to API calls
**Solution:** This means CSV loading failed. Check Space logs for specific error messages.

## Updating Data

To update your Space with fresh data:

1. **Run locally** (every few days or weekly):
   ```bash
   python generate_csv_for_space.py
   ```

2. **Upload new CSV files** to your Space

3. **Space automatically updates** with new data

## Expected Results

✅ **Fast Loading**: Graphs appear instantly  
✅ **No Rate Limits**: No API calls from the Space  
✅ **Smooth Graphs**: ROI graph has smooth curves  
✅ **All Features**: All preprocessing and visualization features work  
✅ **Reliable**: No dependency on external API availability  

## Commands Summary

```bash
# Generate CSV files
python generate_csv_for_space.py

# Test locally
python app.py

# Check what files were created
ls -la *.csv

# Check file sizes
du -h *.csv
```

That's it! Your Hugging Face Space will now run without rate limiting issues using the preprocessed CSV data.