Inspiration

Public and social support systems are critical safety nets, yet they are notoriously fragmented and buried under dense legal jargon. Many individuals miss out on stability because complex bureaucratic rules are highly confusing.

Inspired by civic tech leaders like Code for America, we built BEACON AI—a dynamic reasoning engine rather than a static directory. It acts as a conversational partner that translates eligibility guidelines into plain language, asking targeted questions to guide users toward essential support.

How We Built It

We structured development across milestones to align our frontend, backend, and data layers rapidly:

• Frozen API Architecture: Established an initial contract (mock_api.json) with diverse testing scenarios, allowing independent frontend styling while the backend logic was constructed.
• Cloud-Native Vector Pipeline: Developed a Python 3.11 RAG system using FastAPI. Policy documents are securely stored and queried in the cloud using Pinecone, entirely offloading embedding computation from the runtime platform.
• AI Logic & Resiliency: Integrated **Integrated Google Gemini 3.5 Flash for main conversational processing, backed by a high-availability fallback architecture using the Groq API running Llama 3.1 70B.
• State-Driven Frontend: Built with React, Vite, and Tailwind CSS using Shadcn/ui and DaisyUI. The interface maps eligibility codes straight to context-specific UI blocks (may_qualify, need_more_info, refer_to_human).

Challenges We Faced

• Server Memory Limits & OOM Crashes: Deploying heavy local database instances onto Render's Free Tier (512MB RAM limit) initially caused severe Out-of-Memory crashes. We completely bypassed this hurdle by removing the local configuration and migrating our vector database infrastructure to Pinecone, eliminating the server-side memory footprint entirely.
• Cross-Origin Security Blocks (CORS): Connecting our live cloud server to the local development environment threw severe preflight rejections. We updated the FastAPI middleware pipeline to explicitly permit the local and production domains while disabling general credential locks.
• Dependency Instability: Mid-hackathon updates forced a breaking version of NumPy (2.0+) into our system environment, triggering library failures. We solved this by locking requirements files to stable, backward-compatible package releases.

What We Learned

• Conditional Language Framing: In high-stakes social domains, an AI should never guarantee outcomes. We designed the engine to present outputs conditionally under a may_qualify threshold rather than declaring final eligibility.
• Algorithmic Transparency: We learned to parse raw source metadata straight into an expandable Tailwind Accordion, displaying clear mathematical reasoning to the user:

User Income ( \leq 130\% \times ) Federal Poverty Level (FPL)

• Human-in-the-Loop Safeguards: AI should act as a guide, not a final bureaucrat. Whenever input data is too complex, vague, or impacts highly delicate legal criteria, the engine enforces an immediate refer_to_human status to bridge the user directly to live caseworkers.

Built With

• axios
• chromadb
• daisyui
• fastapi
• github
• google-gemini-3.5-flash
• groq-api-(llama-3.1-70b)
• langchain
• pinecone
• python-3.11
• react
• render
• sentence-transformers-(all-minilm-l6-v2)
• shadcn/ui
• sqlite
• tailwind-css
• vercel
• vite