docs/05-needs-analysis-flow.md

05 — Needs Analysis Flow (Fact-Find)

Field	Value
Project	Insurance Sales Portfolio Expert
Version	0.1
Date	2026-05-13
Implementation	backend/needs_finder.py

0. Why an explicit graph (not "let the LLM figure it out")

A good Independent Financial Advisor opens with a stable, repeatable set of questions — and conditionally deep-dives based on the buyer's signal. We replicate this with an explicit question graph, not an LLM that improvises every session.

Why:

1. Auditable behavior. A reviewer can see the graph, trace any session, and check why a question was (or wasn't) asked.
2. Testable. Pure functions of Profile → Question. Every branch can be unit-tested.
3. Fail-soft. Even if the LLM brain degrades, the question flow still works.
4. Bilingual by construction. Each node has English + Hindi prompts side by side.

1. The graph

                    ┌─────────────────────────────┐
                    │  Q1: age (core)             │
                    │  "What is your age?"        │
                    └────────────┬────────────────┘
                                 ▼
                    ┌─────────────────────────────┐
                    │  Q2: dependents (core)      │
                    │  "Who else do you cover?"   │
                    └────────────┬────────────────┘
                                 ▼
                    ┌─────────────────────────────┐
                    │  Q3: income_band (core)     │
                    │  "Annual income?"           │
                    └────────────┬────────────────┘
                                 ▼
                    ┌─────────────────────────────┐
                    │  Q4: existing_cover (core)  │
                    │  "Already have health ins?" │
                    └────────────┬────────────────┘
                                 ▼
                    ┌─────────────────────────────┐
                    │  Q5: primary_goal (core)    │
                    │  "Why are you here?"        │
                    └────────────┬────────────────┘
                                 ▼
                    ┌─────────────────────────────┐
                    │  Q6: location (core)        │
                    │  "Which city / tier?"       │
                    └────────────┬────────────────┘
                                 ▼
                         (conditional branches)
                                 ▼
        ┌────────────────────────┴────────────────────────┐
        ▼                                                  ▼
┌──────────────────────────────┐         ┌────────────────────────────────┐
│ Q7: parents_age (cond)       │         │ Q8: health_conditions (always) │
│ asked IF dependents include  │         │ "Any pre-existing condition    │
│ 'parent'                     │         │  on your side?"                │
└──────────────┬───────────────┘         └─────────────────┬──────────────┘
               ▼                                            ▼
                                ┌──────────────────────────────────────┐
                                │  Q9: budget_band (core)              │
                                │  "Premium budget?"                   │
                                └──────────────┬───────────────────────┘
                                               ▼
                          ┌─────────────────────────────────────┐
                          │  Profile complete → readback +      │
                          │  policy recommendation              │
                          └─────────────────────────────────────┘

2. Termination criteria

The graph emits next_question = None (i.e., ready to recommend) when all of:

1. All 6 core questions answered (age, dependents, income, existing_cover, primary_goal, location)
2. All applicable conditional questions answered (parents_age if dependents include parents)
3. health_conditions and budget_band answered

Or when the user sets profile.free_form_session = True — the orchestrator skips fact-find and answers free questions directly.

3. Bilingual prompts

Every node has both prompt_en and prompt_hi. The orchestrator picks based on the user's detected language. Example:

Node	English	Hindi
age	"To start, what's your age?"	"शुरू करते हैं — आपकी उम्र क्या है?"
dependents	"Who else do you want to cover…"	"आपके अलावा किस-किस को cover करना है…"
budget	"What annual premium budget…"	"Premium के लिए सालाना कितना खर्च…"

This is what "Indic-native, not translated" (Doc 01 §5.3) looks like in practice — the question is authored in both languages, not machine-translated at runtime.

4. Parsing user answers

Each node has a parser callable that normalizes the user's natural-language answer into a typed Profile field:

• age: lambda s: int("".join(c for c in s if c.isdigit())[:3] or 0) or None
• dependents: free-form string (will be normalized via LLM in v1.1)
• income_band: bucketed via keyword match ("5 lakh" → "under_5L")

When the parser returns None, we treat the question as unanswered and re-ask (v1 simply leaves the field as None and moves on — re-ask is v1.1).

5. How the orchestrator uses this

profile = Profile.from_session(session_id)
q = next_question(profile, language=detected_language)
if q is not None:
    # Still in fact-find phase — ask the next question
    reply = q.prompt_hi if language == "indic" else q.prompt_en
    profile.asked.append(q.id)
else:
    # Profile complete — proceed to retrieval + recommendation
    chunks = retrieve(user_query, top_k=5)
    reply = brain.generate(...)

The orchestrator can also let the user drive the conversation freely — if the user immediately asks a specific question like "compare Star and HDFC ERGO," we set free_form_session = True and skip the fact-find.

6. What the user sees

Bot: "Hi, I'm your AI insurance advisor. To start, what's your age?"
User: "I'm 32"
Bot: "Got it. Who else do you want to cover — just yourself, spouse, kids, or parents?"
User: "self + spouse, kids later"
Bot: "Roughly what's your annual income — under 5 lakh, 5-10, 10-25, or 25+ lakh?"
User: "around 18 lakhs"
... [continues through the core 6] ...
Bot: "Here's what I've understood: 32 years old; covering self+spouse; income 10L-25L;
      no existing cover; goal: first health policy; in a metro; budget 15K-30K.
      Did I get that right?"
User: "yes"
Bot: "Based on that, three policies stand out: [...] — let me explain why."

7. v2 enhancements

#	Enhancement	Why
1	LLM-parser for free-form answers ("I'm in my early 30s with 2 kids")	Handles natural-language replies instead of rigid bucket-matching
2	Re-ask on None parse	Robust to user confusion
3	Skip-confirm flow ("you can skip this — say 'skip'")	Buyer autonomy
4	Save profile across sessions	Returning user picks up where they left off
5	Tone-match the user's energy (formal vs casual)	Conversation feels human