DEPLOY_TO_IOS.md

# 📱 Deploy DE Assistant to iOS — Step by Step ($0)

## What you get
A PWA that installs on your iPhone home screen like a native app, with:
- Full chat interface with markdown rendering
- **Voice input** (speak your question)
- **Voice output** (AI reads the answer aloud)
- Works offline for the UI shell
- Connected to Groq's free-tier LLM (sub-500ms responses)

---

## Option A: Hugging Face Spaces (Recommended — 5 minutes)

HF Spaces gives you a free public HTTPS URL — required for the PWA to work on iOS.

### Step 1 — Get a free Groq API key
1. Go to [console.groq.com](https://console.groq.com)
2. Sign up → API Keys → Create API Key
3. Copy the key (starts with `gsk_`)

### Step 2 — Create a Hugging Face Space
1. Go to [huggingface.co/new-space](https://huggingface.co/new-space)
2. Space name: `de-knowledge-assistant`
3. SDK: **Docker** (not Gradio/Streamlit)
4. Visibility: Public

### Step 3 — Create a Dockerfile in the Space
```dockerfile
FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 7860
CMD ["python", "app.py"]
```

### Step 4 — Upload all files
Push these files to the Space repo (via git or HF UI):
```
app.py
rag.py
agent.py
requirements.txt
static/index.html
static/manifest.json
static/sw.js
knowledge/data_engineering_patterns.pdf
Dockerfile
```

```bash
# Using git
git clone https://huggingface.co/spaces/your-username/de-knowledge-assistant
cd de-knowledge-assistant
# copy all de-assistant/ files here
git add .
git commit -m "Initial deployment"
git push
```

### Step 5 — Set the Groq API key as a secret
In HF Spaces → Settings → Repository Secrets:
- Name: `GROQ_API_KEY`
- Value: your `gsk_...` key

### Step 6 — Add to iPhone home screen
1. Wait for the Space to build (~3 min)
2. Open your Space URL in **Safari on iPhone**:
   `https://your-username-de-knowledge-assistant.hf.space`
3. Tap the **Share** button (box with arrow) → **Add to Home Screen**
4. Name it "DE Assistant" → **Add**

Done! It now appears on your home screen like a native app. 🎉

---

## Option B: Local + Ngrok (instant, for testing)

Run locally and expose with a free ngrok tunnel so Safari can reach it:

```bash
# Terminal 1 — start the app
./setup.sh

# Terminal 2 — expose publicly
brew install ngrok  # or download at ngrok.com
ngrok http 8000
```

Copy the `https://xxxx.ngrok.io` URL → open in iPhone Safari → Add to Home Screen.

---

## Enabling Voice on iOS

Voice requires HTTPS (which HF Spaces provides). After installing the PWA:

1. Open the app from your home screen
2. Tap the **🎤 microphone button**
3. iOS will ask for microphone permission → **Allow**
4. Speak your question — the AI will reply and read the answer aloud

> **Tip**: The voice assistant also reads back the AI's answer using the device's
> built-in text-to-speech (no extra API needed).

---

## Architecture Overview

```
iPhone (Safari PWA)
    │
    │  HTTPS / SSE streaming
    ▼
Hugging Face Spaces (free)
    │  FastAPI  app.py
    │     ├─ /api/chat  → agent.py (streaming)
    │     └─ /api/search → rag.py (vector search)
    │
    ├─ RAG pipeline
    │     ├─ PDF → PyPDF2 → 800-char chunks
    │     ├─ sentence-transformers/all-MiniLM-L6-v2 (free, CPU)
    │     └─ ChromaDB in-memory (MMR retrieval)
    │
    └─ Groq API (free tier)
          └─ llama-3.1-8b-instant (< 500ms latency)
```

---

## Connecting to Databricks (optional upgrade)

Once you have a Databricks workspace:

1. Run `databricks/agent_notebook.py` to register the MLflow model
2. Create a Model Serving endpoint (free on Databricks trial)
3. Add `DATABRICKS_ENDPOINT_URL` and `DATABRICKS_TOKEN` to HF Spaces secrets
4. The agent automatically routes to Databricks when those vars are set

---

## Free Tier Limits (as of 2024)

| Service | Free Limit |
|---------|------------|
| Groq API | 14,400 requests/day, 30 req/min |
| HF Spaces | 2 vCPU, 16 GB RAM, always-on |
| ChromaDB | Unlimited (in-memory) |
| sentence-transformers | Unlimited (local) |

The embedding model (~90 MB) is downloaded on first start and cached in HF Spaces.