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:

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:

   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:

# 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:

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:

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:

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)

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):

   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

# 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.