# QuitSure AI Support — Plan

## Goal
Today, app users ask questions → Freshchat → one of 7-8 coaches answers by hand.
We want an **AI to answer first**, automatically, and hand off to a real coach only when needed.

## How it works (plain version)
1. User asks a question in the app chat.
2. The AI searches our **approved knowledge** and answers.
3. If it can't answer confidently — or it's a sensitive/medical question — it **passes the
   chat to a human coach**, with the full conversation already in front of them.

## Knowledge — what the AI learns from
Curated, approved material ONLY:
- Coach common-questions Excel (questions + approved answers).
- Help docs / FAQ.
- Ram's program & policy docs.

**Not used:** raw Freshchat coach transcripts. Messy/inconsistent coach phrasing dilutes
the AI's reasoning (Ram's call, 2026-06-29). Clean-in → smart-out.

Account-specific answers (refund status, subscription state, payment ref) are **not** in the
knowledge base — those are live DB lookups done in code.

## When the AI hands off to a coach
- User asks for a human.
- AI isn't confident (no good knowledge match → don't guess, escalate).
- **Medical/health topic** (medication, withdrawal, mental health, self-harm) → always a human + crisis resources.
- User is frustrated.
- AI already failed a couple of times.
- Anything that *does* an action (issue a refund) — AI can check eligibility, a human executes.

## Scope — phased (full coach-replacement is the long-term goal)
1. **Account/support first** — refunds, subscriptions, payments, how-to. Low risk, biggest volume.
2. **Then quitting coaching** (cravings, motivation) behind strict safety guardrails + disclaimers.
3. **Medical questions** always go to a human, forever.

## Build phases
| Phase | What | Done when |
|---|---|---|
| 0 — Foundation | Project setup; build KB from the Excel + docs; Gemini answering loop | AI answers a real question from our KB |
| 1 — Support bot | Confidence + escalation logic; DB lookups (sub/refund status) | AI handles account questions, hands hard ones to a coach |
| 2 — Coaching scope | Add motivation/cravings + safety classifier + disclaimers | AI safely covers a wider slice |
| 3 — Custom UI | Frontend builds in-app chat surface | Full control of the chat experience |

## Tech
- **Gemini Flash** for answering (fast, cheap, uses our credits).
- **RAG:** embed the knowledge with `gemini-embedding-001`, search it per question, answer
  **only from what's retrieved** — else escalate. This is the main anti-hallucination guard.
- **FastAPI** service, same pull-and-go style as our other QuitSure web projects.

## OPEN QUESTION (needs Ram / Suraj decision)
Ram said don't connect Freshchat. That's clear for *knowledge*. But we still need a path for
**how an escalated chat reaches a coach**. Two options:
- **A.** Still route the *handoff* into Freshchat's coach inbox (coaches keep their current tool),
  but never use Freshchat data to train the AI. ("Don't connect" = don't learn from it.)
- **B.** Build our own coach hand-off (a simple coach inbox / notification), fully independent of
  Freshchat. More work, but zero Freshchat dependency.

Need to confirm which Ram means before Phase 1.