README.md

---
title: AI Phone Leaderboard
emoji: 📱
colorFrom: blue
colorTo: purple
sdk: streamlit
sdk_version: 1.41.0
app_file: main.py
pinned: false
license: mit
short_description: AI Phone Leaderboard
---

# AI Phone Benchmark Leaderboard

A Streamlit dashboard for displaying and analyzing mobile device AI benchmark results. The dashboard fetches data from Firebase Firestore and provides interactive visualizations and filtering capabilities.

## Setup

### Prerequisites
- Python 3.10+
- Firebase project with Firestore database
- Hugging Face account (for deployment)

### Local Development

1. Clone the repository:
```bash
git clone https://github.com/yourusername/ai-phone-leaderboard.git
cd ai-phone-leaderboard
```

2. Create a virtual environment and install dependencies:
```bash
make venv
make setup-dev
```

### Firebase Configuration

1. Create a Firebase Service Account:
   - Go to Firebase Console → Project Settings → Service Accounts
   - Create a new service account for the dashboard:
     ```bash
     # Create service account
     gcloud iam service-accounts create dashboard-firestore-reader \
         --description="Service account for reading Firestore data in the dashboard" \
         --display-name="Dashboard Firestore Reader"
     ```
   - Grant minimal required permissions:
     ```bash
     # Grant Firestore read-only access
     gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
         --member="serviceAccount:dashboard-firestore-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
         --role="roles/datastore.viewer"
     ```
   - Generate and download the service account key:
     - Click "Generate New Private Key"
     - Save the JSON file (don't commit this to git)

2. For local development, create `.streamlit/secrets.toml`:
```toml
FIREBASE_CREDENTIALS = '''
{
  "type": "service_account",
  "project_id": "your-project-id",
  "private_key_id": "your-private-key-id",
  "private_key": "your-private-key",
  "client_email": "your-client-email",
  "client_id": "your-client-id",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "your-client-cert-url",
  "universe_domain": "googleapis.com"
}
'''
```

3. Run the application:
```bash
make run
```

## Deployment to Hugging Face Spaces

1. Create a new Space:
   - Go to huggingface.co/spaces
   - Click "Create new Space"
   - Select "Streamlit" as the SDK
   - Choose a name for your space

2. Add Firebase credentials to Spaces:
   - Go to Space Settings → Repository Secrets
   - Add a new secret named `FIREBASE_CREDENTIALS`
   - Value should be your Firebase credentials as a minified JSON string (single line)
   - Note: Convert the private key's newlines to `\n` in the JSON

Example of minified credentials for HF Spaces:
```json
{"type":"service_account","project_id":"your-project-id","private_key_id":"your-key-id","private_key":"-----BEGIN PRIVATE KEY-----\\nYour\\nPrivate\\nKey\\nHere\\n-----END PRIVATE KEY-----\\n","client_email":"your-email","client_id":"your-client-id","auth_uri":"https://accounts.google.com/o/oauth2/auth","token_uri":"https://oauth2.googleapis.com/token","auth_provider_x509_cert_url":"https://www.googleapis.com/oauth2/v1/certs","client_x509_cert_url":"your-cert-url","universe_domain":"googleapis.com"}
```

3. The application will automatically deploy when you push to the repository.

## Project Structure
```
.
├── .gitignore
├── .streamlit/
│   └── secrets.toml
├── requirements/
│   ├── base.txt
│   ├── dev.txt
│   └── prod.txt
├── src/
│   ├── components/
│   │   ├── filters.py
│   │   ├── header.py
│   │   └── visualizations.py
│   ├── core/
│   │   └── config.py
│   └── services/
│       └── firebase.py
├── main.py
└── requirements.txt
```

## Firebase Data Structure

The application expects the following Firestore collection structure:
```
benchmarks/
└── v1/
    └── submissions/
        └── [benchmark_uuid]/
            ├── benchmarkResult: {...}
            ├── deviceInfo: {...}
            └── metadata: {...}
```

## Development

Available make commands:
```bash
make help           # Show available commands
make setup-dev      # Setup development environment
make setup-prod     # Setup production environment
make run           # Run Streamlit application
make lint          # Run code linter
make format        # Format code using black
make test          # Run tests
make clean         # Clean cache files
```

## Security Considerations

1. Never commit sensitive credentials to git:
```gitignore
# Add to .gitignore
.streamlit/secrets.toml
*firebase*.json
```

2. Use environment-specific secrets:
   - Local: Use `.streamlit/secrets.toml`
   - Production: Use HF Spaces secrets

3. Firebase Security:
   - Create a dedicated service account with minimal permissions
   - Only grant read access to the required Firestore collections

## Dependencies

Key dependencies are pinned to specific versions to ensure stability:
```
firebase-admin==6.6.0
streamlit>=1.28.0
pandas>=2.1.3
plotly>=5.18.0
```

## License

[MIT License](LICENSE)