Franchise Partner Acquisition, Geo-Selection & Onboarding Engine
Upload the case Excel file as-is and every applicant gets one decision (Approved / Waitlisted / On hold / Not approved),
the reasons with numbers, what to do next, and, if approved, a dated onboarding checklist and a training plan
in their language. A chat panel answers "why" questions and accepts new facts ("APP-012 has now found a ground-floor
space"), re-runs the whole engine and lists every knock-on change. No login.
Rules decide, AI explains. Every decision comes from a deterministic rule engine (same input → same output). The LLM
is used only to read the two free-text columns into fixed fields and to phrase chat answers / parse chat updates. With no
API key the app works fully: keyword rules read the free text and template sentences explain the stored reasons.
Run locally
pip install -r requirements-dev.txt
uvicorn app:app --reload # web app at http://localhost:8000
pytest -q # 65 tests, no API key needed
app.py is a FastAPI app (JSON API under /api/*) serving the single-page front end in web/index.html.
An older Streamlit UI is kept as streamlit_app.py (pip install -r requirements-streamlit.txt, then
streamlit run streamlit_app.py).
Optional: ANTHROPIC_API_KEY (and ANTHROPIC_MODEL, default claude-sonnet-5-5) as environment variables. The key
stays on the server.
Deploy (Vercel)
Import the GitHub repository in Vercel. It detects the FastAPI app in app.py and installs requirements.txt; no
build settings are needed. Add ANTHROPIC_API_KEY under Project → Settings → Environment Variables (optional) and
redeploy. To make the link public, turn off Deployment Protection (Settings → Deployment Protection → Vercel
Authentication) or share the production domain.
The server keeps no state between requests: the browser holds the uploaded data and sends it with each request, and
the engine re-runs deterministically. So several judges can use the link at once without interfering, and a page
refresh keeps your session (stored in the tab's sessionStorage).
How a decision is made
parse → validate (Gate A) → derive (territory, distance, cost, payback) → Gate B (location) → Gate C (readiness)
→ score (100 pts) → allocate per territory → reasons, next steps, checklist, training → invariant checks
| Gate | Check | Outcome |
|---|
| A – data | missing ID / city / pin / investment / space; invalid pin; city ≠ pin prefix; city/state not allowed; Owned/Rented without size or floor; notes contradict the space field | On hold, with the exact fix |
| B – location | pin in no territory; pin already has a brand store | Not approved (other open pins / territories offered) |
| C – readiness | funds < 80% of required | Not approved |
| funds 80–100% of required | On hold ("add ₹X lakh or choose a space up to N sq ft") |
| no space, upper floor (non-mall), < 300 sq ft, funding not confirmed in the notes | On hold |
If several gates fail, all reasons are recorded. Precedence: withdrawn/duplicate → Not approved; an unreliable
location (bad pin, city/pin mismatch) → On hold (Gate B can't be judged yet); any Not-approved reason → Not approved;
any other blocking issue → On hold.
Cost model (what a store costs to open) – config.yaml
| ₹ | Tier 1 | Tier 2 | Tier 3 |
|---|
| Franchise fee | 5,00,000 | 4,00,000 | 3,00,000 |
| Fit-out per sq ft | 3,000 | 2,500 | 2,000 |
| Initial inventory | 8,00,000 | 6,00,000 | 5,00,000 |
| Working capital (3 months) | 4,00,000 | 3,00,000 | 2,00,000 |
| Rent per sq ft per month (rented only; deposit = 6 months) | 150 | 80 | 50 |
required = fee + fit-out × size + inventory + working capital + rent deposit (size = actual, or 400 sq ft if unknown).
| Worked example | Required |
|---|
| Tier 2, 400 sq ft, rented | 4 + 10 + 6 + 3 + 1.92 = ₹24.9 lakh |
| Tier 1, 400 sq ft, rented | 5 + 12 + 8 + 4 + 3.6 = ₹32.6 lakh |
| Tier 3, 400 sq ft, owned | 3 + 8 + 5 + 2 + 0 = ₹18.0 lakh |
| Tier 2, 600 sq ft, rented | 4 + 15 + 6 + 3 + 2.88 = ₹30.9 lakh |
Payback = required ÷ (revenue per sq ft × size × 15% margin); revenue ₹2,500 / 2,000 / 1,500 per sq ft per month by tier.
Example: Tier 2, 400 sq ft rented → ₹1.2 lakh profit a month → about 20.8 months.
Score card (100 points, eligible applicants only)
| Factor | Max | Rule |
|---|
| Investment adequacy | 25 | min(25, 10 + 30 × (ratio − 1)), ratio = offered ÷ required. More money for the same store → higher score; same money for a bigger store → lower score. |
| Retail experience | 15 | 0 yrs 0 · 1–2 yrs 7 · 3–5 yrs 12 · 6+ yrs 15 |
| Business background | 5 | runs/ran a shop or customer-facing business 5 · other business 2 · none/unclear 0 |
| Space quality | 15 | Owned 8 / Rented 5 + Ground 5 / Mall 4 + size 300–600: 2, 600–800: 1, > 800: 0 |
| Territory priority | 15 | High 15 · Medium 8 · Low 3 |
| Location & cannibalisation | 15 | nearest brand store > 3 km 15 · 1.5–3 km 8 · < 1.5 km 0 (flagged) · no store in city 15 · unknown 8 |
| Timeline fit | 5 | target ≥ realistic 5 · 1 month short 2 · more 0 · no target 2 |
| Payback | 5 | ≤ 18 months 5 · 18–30 3 · > 30 0 |
Tie-break (fixed order, unique result): score → investment ratio → retail experience → shorter time to open →
lower Application ID. The level that decided a tie is written into both applicants' reasons.
Allocation per territory: walk the ranking; pin already won (or holds a store) → Waitlisted; slots full →
Waitlisted; otherwise Approved and the pin is taken. Invariants (no shared pin, no store pin, slots respected, one
decision + reason each, checklist + training for every approval) are checked after every run, including chat re-runs.
Next steps and onboarding
- Approved: dated 9-step checklist (fee, KYC, site visit, fit-out with ₹ estimate, hiring 2–3 staff, training,
systems, launch, 30/60/90-day check-ins), scheduled backwards from the target launch, or forwards from today with
the gap explained if the target is unrealistic. High-priority territories are fast-tracked. Training: Foundation
(0 yrs, 10 days + 2 weeks shadowing), Standard (1–5 yrs, 6 days + 1 week), Fast track (6+ yrs, 3 days), all in the
preferred language, shadowing at the nearest existing store (Tumakuru/Davanagere use the nearest store in another city).
- On hold: the exact items to supply, a 30-day window, and a what-if prediction ("If funds are confirmed, the score
would be about 69/100, ranking 2nd of 3 in TER-03 → likely Waitlisted").
- Waitlisted: rank, who is ahead, how much more investment would lift them, open pins in the territory.
- Not approved: the reason with numbers and any open territory/pin or the smallest store they could afford.
Chat
- Questions: "Why is APP-007 on hold?", "Why did APP-004 beat APP-009?" (leads with the deciding factor),
"Who is waitlisted in TER-02?", "What training will APP-024 get?", names work too ("Why is Arjun on hold?").
- New facts: "APP-012 has now found a ground-floor space", "APP-015 can now invest ₹30 lakh", "APP-006 has withdrawn",
"APP-008's bank loan has been sanctioned". The update is echoed, validated against allowed fields/values, the full
engine re-runs, and every decision change is listed. Implied changes are stated (a found space is Rented unless
"own/bought" is said; size/floor kept from the application are named). Missing items keep the applicant On hold.
- "What if …" runs the same simulation without saving. Unknown IDs: "There is no APP-099 in the uploaded file."
- Reset to uploaded file drops all chat updates; the change log is shown on each applicant page.
Follow-up emails for On hold applicants
Every On hold applicant gets a ready-to-send email built from the stored reasons: what we found, exactly
what to update, and a reply-by date (30 days). On the dashboard's "Needs follow-up" list and on the
applicant profile, Draft in Gmail opens Gmail's compose window with the email filled in; you review it and
press Send. Nothing is sent automatically, and no Google account setup or API key is needed. "Other email app"
uses a mailto link, and "Copy" puts the text on the clipboard. The Excel export has a "Follow-up emails" sheet
with every draft for mail merge. If the uploaded Applications sheet has an optional Email column, the
recipient is filled in; otherwise type it in the draft window (it is remembered for the session).
Data
data/pin_coords.csv – built once by scripts/build_pin_coords.py from the Department of Posts All India Pincode
Directory (data.gov.in, Government Open Data Licence; GitHub mirror). 427 pins in the 7 cities. No internet at runtime.data/existing_stores.csv, data/city_reference.csv – Sheet 3 and the allowed values. data/template.xlsx – the official template.tests/test_data.xlsx – generated by scripts/make_test_file.py; 27 applicants covering every tricky case
(see the case map at the top of that script).
Assumptions beyond the brief
- All cost, revenue, score and timing numbers are team assumptions in
config.yaml.
- Pin coordinates: the brief's "drop rows > 30 km from the city centre" would discard half the valid pins (prefixes cover
whole districts). Instead, per pin, rows within 30 km of the centre are preferred; otherwise rows within 150 km are kept
after removing per-pin outliers. This still fixes the bad 560066 row.
- A space "Not yet identified" is costed as rented (the cautious choice).
- Missing preferred language is a warning (English assumed), not a blocker – the template marks it optional.
- The template's grey example row (APP-001 Ravi Kumar / TER-01) is skipped when it is unchanged.
- Chat may set three flags besides Sheet 1 fields:
withdrawn, funds_confirmed, space_confirmed.
- The Messages API no longer accepts
temperature; repeat answers stay identical because LLM results are cached by input hash.
- LLM calls use server-side refusal fallback (
fallbacks: "default"); if unavailable they fall back to a plain call, then to rules.
