Benefits Navigator Agent

Benefits Navigator Agent is an AI-agent-style workspace for public benefits navigation. It helps social workers and nonprofit teams screen resident needs, retrieve relevant program guidance, create document checklists, and produce auditable handoffs without making final eligibility decisions.

Social Pain Point

Residents often need food, healthcare, housing, childcare, or emergency shelter support, but the path is fragmented across agencies, documents, deadlines, and local rules. Case workers lose time repeating intake and residents miss benefits because next steps are unclear. This project turns an intake profile into a grounded navigation handoff.

Features

• Agent loop with safety classification, tool execution, validation, and trace persistence.
• Program retrieval for food assistance, healthcare, housing stabilization, and childcare support.
• Case-plan engine that turns intake details into priority tier, risk flags, service windows, referral channels, and follow-up ownership.
• Crisis escalation for unsafe-night, self-harm, domestic violence, or medical emergency language.
• Fraud/bypass guardrail for fake documents or hidden-income requests.
• Document checklist and missing-information detection.
• React social-worker console with trace inspection.
• Scenario eval suite covering normal, crisis, and blocked runs.
• Optional path for OpenAI-compatible APIs, MySQL persistence, and Redis follow-up queues.

Quick Start

npm install
npm run dev

Open http://localhost:5173. The API defaults to http://localhost:4520.

Scripts

npm test
npm run eval
npm run build
npm run start

API

Method	Endpoint	Description
GET	/api/health	Service health and provider mode
GET	/api/tools	Agent tool catalog
GET	/api/metrics/runtime	Runtime counters
GET	/api/metrics/scorecard	Operational readiness score and checks
POST	/api/runs	Run benefits navigation and persist trace

Quality Gates

• npm test covers normal navigation, crisis escalation, fraud blocking, and dry-run guarantees.
• npm run eval replays scenario regressions for normal, crisis, eviction-prevention, unclear-intake, and blocked requests.
• GitHub Actions runs tests and build on pull requests and main.
• Architecture notes live in docs/ARCHITECTURE.md.

License

MIT

Enterprise Readiness

This repository now includes contribution guidelines, a security policy, operational runbook notes, PR review gates, and automated readiness checks. See docs/ENTERPRISE_READINESS.md and docs/OPERATIONS.md.