# QuitSure Assistant — Integration Overview (for frontend)

For the frontend dev researching how to incorporate the AI assistant and how Freshchat keeps
living alongside it. This is the "what it does and how it slots in" picture, not the API spec.
The exact request/response contract is in `API.md`.

---

## 1. What the AI assistant does

It is a tier-1 support assistant that sits in front of your existing human support.

- **Answers** common user questions from an approved QuitSure knowledge base (program, subscription,
  billing, app how-to, quit-journey coaching). The answers are warm, coach-like, and grounded only
  in approved content (it does not make things up, and it does not use general internet knowledge).
- **Escalates to a human** when it should: medical questions, crisis, account-specific billing
  (paid but no access, refund status), explicit "talk to a human", frustration, or anything it has
  no approved answer for. When it escalates it returns a one-line summary for the human.
- **Politely declines** off-topic / time-pass questions (weather, jokes) without bothering a human.
- **Context aware:** you can pass the user's `program` (P3 / P9) and `platform` (ios / android) so
  it gives the right program-specific and platform-specific answer.

It is exposed as **one stateless HTTP endpoint** (`POST /chat`). Our team owns that service. Your
team owns the chat UI and the human handoff.

---

## 2. The integration model (recommended)

```
   user types in the app chat
            |
            v
   app calls  POST /chat  (our AI service)   <--- you build this call
            |
   response: { answer, escalate, escalate_reason, coach_summary }
            |
     +------+---------------------------------+
     |                                         |
 escalate = false                         escalate = true
     |                                         |
 show answer in the chat bubble        show answer, THEN hand the
 (done, no human)                      conversation to a human via
                                       Freshchat (your existing flow)
                                       passing coach_summary + transcript
```

The AI handles the easy majority. Freshchat handles the rest. The user ideally sees one continuous
chat where the handoff is invisible.

---

## 3. How Freshchat keeps living

Freshchat does **not** go away. It becomes the **human layer**, the place a conversation lands when
the AI escalates. Nothing changes for the 7-8 coaches: they keep their existing Freshchat inbox,
routing, and tools. The only change is that fewer conversations reach them, and the ones that do
arrive with context already attached.

So the split is:
- **AI assistant** = automated first responder (new).
- **Freshchat** = human coach layer / escalation destination (your existing integration, reused).

Important constraint from Ram: the AI's knowledge must stay restricted to content we provide. We do
**not** feed Freshchat coach transcripts into the AI. Freshchat is the handoff target, not a data
source for the AI.

---

## 4. Two ways to wire the handoff (your research call)

Both keep Freshchat as the human layer. The question is what surface the user chats in.

**Option A — app-owned chat surface, bridge to Freshchat on escalate (cleaner)**
- The app has its own chat UI. Every user message goes to our `/chat` API. The AI replies inline.
- On `escalate: true`, the app opens / creates a Freshchat conversation, pre-fills it with the
  transcript + `coach_summary`, and moves the user into the coach flow.
- Pros: full control of UX, low latency, the AI never depends on Freshchat. Cons: you build the
  chat surface and the bridge into Freshchat.

**Option B — keep the Freshchat widget as the surface, inject AI server-side**
- Keep the existing Freshchat chat widget. AI replies are posted into the Freshchat conversation via
  Freshchat's Conversation API (server-side), and on escalate the conversation is assigned to a coach.
- Pros: reuses the Freshchat UI you already integrated, everything stays in one Freshchat thread.
  Cons: more moving parts, tighter coupling to Freshchat, and it routes user messages through
  Freshchat before they reach the AI.

Our lean is **Option A** for control and to keep the AI independent of Freshchat, but you know the
Freshchat side best, so this is exactly what your research should weigh.

---

## 5. What the frontend is responsible for

1. Call `POST /chat` on each user message, sending recent `history` plus `program` and `platform`
   (you already know the logged-in user's program and device).
2. Render `answer`.
3. When `escalate` is true, route the conversation to a human (Freshchat) and pass `coach_summary`
   (and ideally the transcript) so the coach has context and the user does not repeat themselves.
4. (Optional) thumbs up / down that calls `POST /feedback`, which feeds our improvement loop.

We handle everything else: retrieval, the answer, the escalation decision, safety, and logging.

---

## 6. Open decisions worth settling during research
- **Option A vs B** for the chat surface (above).
- **Seamless thread:** how to make the AI to human handoff feel like one continuous conversation.
- **Where the AI service is hosted** so the app can reach it (we will deploy, you tell us the
  network constraints).
- **Context source:** confirm the app can pass `program` and `platform` on each call (from the
  logged-in user / DB).

The exact endpoint contract, fields, and a curl example are in `API.md`.