benē — Know What You're Owed

An AI-powered U.S. government benefits eligibility navigator. Answer 5 questions, get a personalized eligibility report in under 60 seconds.

What it does

benē evaluates eligibility across food assistance (SNAP, WIC), healthcare (Medicaid, Medicare, CHIP), housing (Section 8, LIHEAP), cash aid (SSI, TANF), and educational assistance (FAFSA, Pell Grant, VA benefits) — localized to your state from your zip code.

Output includes:

• Programs ranked by eligibility status with confidence scores
• Estimated monthly and annual benefit values
• Clickable priority actions linking directly to official application portals
• Document checklist to get application-ready
• Persistent dashboard to track saved benefits
• Follow-up chatbot that re-evaluates eligibility in real time as you share new information

Zero data persistence. All inputs live in sessionStorage and are gone when the tab closes.

---

Stack

Layer	Tech
Frontend	Next.js 14 (App Router), TypeScript, Tailwind CSS
Backend	FastAPI, Python, Uvicorn
AI	Anthropic Claude Haiku (claude-haiku-4-5-20251001) via tool_use
Deployment	Vercel (frontend + API routes), Railway (FastAPI)
State	sessionStorage only — no database, no user accounts

---

How it works

Initial evaluation — The Next.js API route loads four .txt knowledge base files (~40KB of 2026 federal benefit guidelines) and injects them as context alongside user data. Claude Haiku is called with tool_choice: { type: "tool", name: "report_eligibility_analysis" } to guarantee a structured JSON response every time.

State localization — Zip code resolves to state via a prefix-range lookup (no external API), injecting state-specific program aliases (CalFresh, Apple Health, MassHealth) and Medicaid expansion status into the context.

Follow-up chat — The chatbot has the eligibility tool available on every turn. If new information is disclosed (income change, disability, household size), it silently re-evaluates and refreshes the dashboard.

RAG pipeline — Knowledge base files are bundled with the Vercel serverless function via outputFileTracingIncludes in next.config.ts. The full context is injected on every evaluation rather than using chunked retrieval — benefits eligibility is deeply interconnected and requires the complete rulebook.

---

Project structure

├── frontend/eligibility-checker/
│   ├── src/app/
│   │   ├── api/chat/
│   │   │   ├── route.ts          # Main API route (Anthropic calls, RAG injection)
│   │   │   └── prompts/          # 2026 federal benefit knowledge base (.txt files)
│   │   ├── wizard/page.tsx       # Questionnaire (step 1)
│   │   ├── chat/page.tsx         # Chat + eligibility results (step 2)
│   │   ├── dashboard/page.tsx    # Full eligibility dashboard (step 3)
│   │   └── blueprint/page.tsx    # About page
│   └── next.config.ts
└── backend/
    ├── main.py                   # FastAPI app
    ├── services/llm_engine.py    # Anthropic tool_use implementation
    └── prompts/                  # Knowledge base (mirrored in frontend)

---

Running locally

Frontend

cd frontend/eligibility-checker
npm install
cp .env.local.example .env.local  # add ANTHROPIC_API_KEY
npm run dev

Backend (optional — frontend calls Anthropic directly)

cd backend
pip install -r requirements.txt
uvicorn main:app --reload

---

Environment variables

Variable	Where	Description
ANTHROPIC_API_KEY	Vercel + Railway	Anthropic API key

---

Key implementation details

• Forced tool use: tool_choice: { type: "tool", name: "report_eligibility_analysis" } on the initial evaluation ensures structured JSON output every time. Without forcing it, Haiku frequently skips the tool call entirely.
• Haiku over Sonnet: The 40KB context + Vercel's 60s function timeout requires Haiku. Sonnet consistently timed out.
• Fallback narrative: When forced tool use returns no text block, the route handler generates a clean markdown summary from the structured JSON — the user always sees readable output.
• Household income vs. individual income: Field is named household_gross_monthly_income (not income) and the system prompt embeds the full 2026 FPL table with an explicit instruction to scale by household size.
• No flash on dashboard load: Data is read from sessionStorage synchronously inside the useState initializer, not in a useEffect, so the dashboard renders fully on first paint.