README.md

metadata

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:

git clone https://github.com/yourusername/ai-phone-leaderboard.git
cd ai-phone-leaderboard

2. Create a virtual environment and install dependencies:

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:

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

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

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:

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:

{"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:

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:

# 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