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
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
2. Space name: de-knowledge-assistant
3. SDK: Docker (not Gradio/Streamlit)
4. Visibility: Public

Step 3 — Create a Dockerfile in the Space

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

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

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