# CLAUDE.md — QuitSure AI Support

This repo is QuitSure's in-house AI customer-support assistant: a standalone FastAPI service that
answers user questions **strictly from a curated, approved knowledge base** (RAG with Gemini),
abstains/escalates when it can't answer, and has a deterministic self-harm safety gate. It replaces
the manual Freshchat coach-shortcut flow. Do not widen the bot's knowledge beyond the approved KB.

Key files: `app.py` (service), `db.py` (logging), `scripts/build_kb.py` +
`scripts/build_index.py` (KB build), `eval/run_eval.py` (safety + regression gate),
`data/kb.json` + `data/index.npz` (the committed KB, pull-and-go), `docs/` (design, API, deployment).

Deploy branch is **`development`** (BE deploys from there; leave `main` untouched).

---

## Updating the knowledge base (self-serve — this is the automated flow)

Anyone with repo access can update what the bot knows **without editing code**. They add material to
`knowledge/additions/` and ask you (Claude) to update the KB. When asked to "update the knowledge
base" (or when there is new/changed content in `knowledge/additions/`), do exactly this:

### Step 1 — Normalize the new knowledge into approved Q&A
- If they dropped a **`.json`** in `knowledge/additions/` already in the entry format, use it as-is.
- If they dropped **raw material** (a doc, notes, a paragraph, pasted coach answer), read it and turn
  it into one or more entries in a new `knowledge/additions/<descriptive-name>.json`. Each entry:
  ```json
  {"question": "...", "answer": "...(verbatim, final wording)...", "programs": ["all"], "topic": "..."}
  ```
  - `answer` is sent to users **verbatim** — keep it clean, complete, and in approved wording. Do not
    invent facts. If the source is ambiguous or you are unsure it's approved, STOP and ask, do not guess.
  - `programs`: `["all"]` unless it is Original-only (`["P3"]`) or Relaxed-only (`["P9"]`).
  - Never add coach-only instructions or placeholders (`%name%`, "send only after...") as answers.
  - `example.json.template` is a format reference only — it is not loaded by the build; don't edit it.

### Step 2 — Rebuild the KB
```
python3 scripts/build_kb.py       # folds additions into data/kb.json (no API key needed)
python3 scripts/build_index.py    # rebuilds data/index.npz  (needs GEMINI_API_KEY + internet)
```
Report the entry-count change build_kb prints. If `build_index.py` cannot run (no key/network here),
say so clearly — the KB text is updated but the embeddings are not, so it is NOT deployable yet.

### Step 3 — Validate (mandatory, this is the safety gate)
```
python3 eval/run_eval.py
```
Must PASS (content/leak + crisis gates are hard-fail). If it fails, fix the entry and re-run. Also
sanity-check the new answers by asking the bot the new questions if the service is runnable.

### Step 4 — Commit + hand off
- Commit `data/kb.json`, `data/index.npz`, and the file(s) under `knowledge/additions/` to
  `development` with a message naming what was added.
- Tell the user it is committed, and that **BE must pull `development` and restart the service** for
  it to go live (the KB is loaded at startup).

### Guardrails
- **Only approved content.** A wrong entry here becomes a wrong answer to a real user. When in doubt
  about correctness or approval, ask before adding.
- Do not touch `TAG_OVERRIDE` / `ANSWER_OVERRIDE` / `EXCLUDE_IDS` in `build_kb.py` for a normal add —
  those are for the Excel-sourced entries and are keyed to positional IDs. New knowledge goes through
  `knowledge/additions/` only.
- Never modify the database schema or delete existing KB entries as part of an "add" request.