Explain the Bill

Explain the Bill is a public-facing, demo-ready web app that explains government bills, executive orders, and public policies in clear, neutral, plain English. It supports three starting paths: paste/upload full text, search by name, or describe a bill in your own words.

What this app does

• Explains bills, executive orders, and policies in structured sections
• Provides an Identify step with confidence scores and candidate selection
• Works offline by default using a bundled catalog
• Optionally supports online lookup via a public API
• Includes export options (copy + PDF)

Run the app

npm install
npm run dev

Open http://localhost:3000

Environment variables

Create a .env.local file if you want to enable online lookup or live AI calls.

OPENAI_API_KEY=your_key_here
OPENAI_BASE_URL=https://api.openai.com/v1
MOCK_MODE=true
BILL_LOOKUP_MODE=offline
CONGRESS_API_KEY=your_congress_key

• OPENAI_API_KEY: Required for live AI calls. If missing, enable MOCK_MODE=true.
• OPENAI_BASE_URL: Optional override for OpenAI-compatible endpoints.
• MOCK_MODE: true returns deterministic example output without calling an API.
• BILL_LOOKUP_MODE: offline (default) or online.
• CONGRESS_API_KEY: Required if BILL_LOOKUP_MODE=online.

Privacy and neutrality

• Educational explanation only. Not legal advice or advocacy.
• No accounts, tracking, or analytics.
• User inputs are not stored beyond the current session.
• The app is neutral and non-partisan by design.

AI limitations and verification guidance

• The output is a plain-language summary for general understanding.
• It may omit details or context.
• Always verify against official sources (full text, agency guidance, and legislative status).
• The app includes an Uncertainty & Verification section in every response.

Offline catalog

The demo includes a local JSON catalog at:

• src/data/bill-catalog.json

Each entry includes:

• id, title, aliases, short_description, date, type, source_note, full_text

To add an entry, append a new object with the same shape. The app uses this catalog for offline identification and explanations.

Optional online mode

If you set BILL_LOOKUP_MODE=online and provide CONGRESS_API_KEY, the app will call the Congress.gov API to fetch candidate matches by name. Online mode is optional and never required for the demo.

Notes:

• Sign up for an API key at https://api.congress.gov
• The app uses the Congress.gov bill search endpoint and attempts to fetch summaries when available.
• If online mode is enabled but not configured correctly, the app falls back to offline results without breaking.

Development notes

• Built with Next.js App Router, TypeScript, TailwindCSS, and Node runtime.
• Uses server actions for AI calls and file text extraction.