README.md

---
title: Garmin AI Coach
emoji: 🏃‍♂️
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: "5.x"
app_file: app.py
pinned: false
---

# Garmin AI Coach

Your personalized AI fitness assistant powered by Garmin Connect data. Analyse your activities, track progress, and get intelligent coaching recommendations through a conversational interface.

## Features

- 🏃‍♂️ **Activity Analysis**: Query your Garmin Connect activities using natural language
- 💬 **Conversational AI**: Powered by state-of-the-art language models
- 📊 **Progress Tracking**: Monitor your fitness journey over time
- 🔐 **Multi-User Support**: Secure authentication with per-user data isolation
- ☁️ **Cloud Storage**: Firestore backend for reliable data persistence

## Deployment Guide

This guide explains how to deploy the Garmin AI Coach application to HuggingFace Spaces.

### Prerequisites

1. **HuggingFace Account**: [Sign up](https://huggingface.co/join) if you don't have one
2. **Google Cloud Service Account Key**: See [Terraform setup](../../terraform/README.md)
3. **HuggingFace CLI**: Install with `pip install huggingface_hub[cli]`

### Quick Start

#### Option A: Automated Deployment (Recommended)

Use the deployment script from repository root:

```bash
# Generate requirements.txt
./infrastructure/deployment/scripts/generate-requirements.sh

# Deploy to HuggingFace Spaces
./infrastructure/deployment/scripts/deploy-to-hf.sh
```

#### Option B: Manual Deployment

1. **Authenticate with HuggingFace**:

```bash
huggingface-cli login
```

2. **Create a private Space**:
   - Go to [HuggingFace Spaces](https://huggingface.co/spaces)
   - Click "Create new Space"
   - Set name: `garmin-agent` (or your preferred name)
   - Choose SDK: **Gradio**
   - Visibility: **Private**

3. **Prepare deployment files**:

```bash
# From repository root
cd infrastructure/deployment/scripts
./generate-requirements.sh

# Copy files to repository root
cp infrastructure/deployment/huggingface/app.py ./app.py
cp infrastructure/deployment/huggingface/requirements.txt ./requirements.txt
cp infrastructure/deployment/huggingface/README.md ./README.md
```

4. **Deploy to Space**:

```bash
# Clone your Space repository
git clone https://huggingface.co/spaces/YOUR_USERNAME/garmin-agent
cd garmin-agent

# Copy application files and workspace
cp /path/to/repo/app.py ./
cp /path/to/repo/requirements.txt ./
cp /path/to/repo/README.md ./
cp -r /path/to/repo/packages ./
cp -r /path/to/repo/services ./

# Commit and push
git add .
git commit -m "Initial deployment"
git push
```

5. **Configure Secrets and Variables**:

   Go to your Space Settings:
   - **Settings → Secrets** (for sensitive values)
   - **Settings → Variables** (for non-sensitive configuration)

   **Required Secret** (Settings → Secrets):
   - `GOOGLE_CREDENTIALS_JSON`: Paste the **entire contents** of your service account key JSON file

     ```json
     {
       "type": "service_account",
       "project_id": "savvy-bit-472903-g9",
       ...
     }
     ```

   **Required Variables** (Settings → Variables):
   - `DATABASE_TYPE=firestore`
   - `GOOGLE_CLOUD_PROJECT=savvy-bit-472903-g9`
   - `ENABLE_AUTH=true`
   - `ENVIRONMENT=production`
   - `CHAT_AGENT_MODEL=hf:meta-llama/Llama-3.2-3B-Instruct`

   **Optional Variables**:
   - `HUGGINGFACE_HUB_TOKEN`: Your HF token (required for HF models)
   - `TELEMETRY_BACKEND=disabled`: Telemetry configuration

6. **Restart Space**: After configuring secrets, restart your Space from the Settings page.

### File Structure for Deployment

HuggingFace Spaces requires the following structure at repository root:

```
repository-root/
├── app.py                    # Entry point (from infrastructure/deployment/huggingface/app.py)
├── requirements.txt          # Generated dependencies
├── README.md                 # This file with HF metadata header
├── packages/                 # Full workspace structure
│   ├── ai-core/
│   └── shared-config/
└── services/
    ├── cli/
    └── web-app/
```

**Important**: Deploy the entire workspace structure to maintain package imports and dependencies.

### Environment Variables Reference

| Variable | Required | Description | Example |
|----------|----------|-------------|---------|
| `GOOGLE_CREDENTIALS_JSON` | Yes (Secret) | Service account key JSON content | See Terraform outputs |
| `DATABASE_TYPE` | Yes | Database backend type | `firestore` |
| `GOOGLE_CLOUD_PROJECT` | Yes | GCP project ID | `savvy-bit-472903-g9` |
| `ENABLE_AUTH` | Yes | Enable multi-user authentication | `true` |
| `ENVIRONMENT` | Yes | Deployment environment | `production` |
| `CHAT_AGENT_MODEL` | Yes | AI model specification | `hf:meta-llama/Llama-3.2-3B-Instruct` |
| `HUGGINGFACE_HUB_TOKEN` | Conditional | HF token for HF models | `hf_xxxxx` |
| `TELEMETRY_BACKEND` | No | Telemetry configuration | `disabled` |

### Monitoring and Troubleshooting

#### View Application Logs

In your Space:

1. Go to your Space page
2. Click "Logs" tab
3. Monitor startup messages and errors

#### Common Issues

#### 1. "Missing required environment variables"

- Solution: Verify all required variables are set in Settings → Variables
- Check secret `GOOGLE_CREDENTIALS_JSON` is set in Settings → Secrets

#### 2. "Failed to parse GOOGLE_CREDENTIALS_JSON"

- Solution: Ensure the secret contains valid JSON (entire service account key file)
- Verify no extra quotes or formatting around the JSON content

#### 3. "Failed to import application modules"

- Solution: Ensure full workspace structure (packages/, services/) is deployed
- Verify requirements.txt includes all dependencies

**4. "Firestore connection failed"**

- Solution: Verify service account has `roles/datastore.user` permission
- Check `GOOGLE_CLOUD_PROJECT` matches your Firestore project
- Confirm Firestore database exists in your GCP project

**5. "Model not found" or authentication errors**

- Solution: For HF models, set `HUGGINGFACE_HUB_TOKEN` in Variables
- For OpenAI models, set `OPENAI_API_KEY`
- For Anthropic models, set `ANTHROPIC_API_KEY`

#### Testing the Deployment

After deployment:

1. Visit your Space URL: `https://huggingface.co/spaces/YOUR_USERNAME/garmin-agent`
2. Wait for the Space to build and start (first start takes 2-3 minutes)
3. Register a new user account
4. Test the chat interface with simple queries
5. Verify Firestore connection by checking data persistence

### Updating the Application

To update your deployed application:

1. **Update code locally** and test
2. **Regenerate requirements.txt** if dependencies changed:

   ```bash
   ./infrastructure/deployment/scripts/generate-requirements.sh
   ```

3. **Copy updated files** to Space repository
4. **Commit and push** changes
5. **HF Spaces will automatically rebuild** and restart

### Security Best Practices

1. **Keep Space Private**: Set visibility to "Private" for production
2. **Rotate Service Account Keys**: Follow GCP key rotation guidelines
3. **Use Secrets for Credentials**: Never commit credentials to repository
4. **Monitor Access Logs**: Review Space access logs regularly
5. **Enable Authentication**: Always deploy with `ENABLE_AUTH=true`

### Performance Optimization

- **Model Selection**: Smaller models (e.g., Llama-3.2-3B) start faster and use less memory
- **Cold Start**: First request after inactivity may take 30-60 seconds
- **Firestore Region**: Database in `australia-southeast1` optimises latency for APAC users
- **Space Hardware**: Upgrade to GPU Space for better performance with larger models

### Support

For issues specific to:

- **HuggingFace Spaces**: [HF Spaces Documentation](https://huggingface.co/docs/hub/spaces)
- **Firestore**: [Firestore Documentation](https://cloud.google.com/firestore/docs)
- **Application Issues**: See repository issues or documentation

---

**Note**: This deployment uses HuggingFace Spaces' native Gradio SDK support. The platform automatically handles server configuration, port binding, and SSL certificates.