This site should show where information comes from, what is known, what is uncertain, and what happens when something needs correction.
Official sources include Congress.gov (Library of Congress), govinfo (Government Publishing Office), the Federal Register, the FEC, the Census Bureau, the National Archives, USA.gov, and state or local government websites. These are the primary records the site relies on for factual claims.
Secondary sources include OpenSecrets, FollowTheMoney, Ballotpedia, and Vote Smart. These can add useful context, but they are not official government records. The site labels them clearly and does not treat them as authoritative for bill status, legal text, or official government action.
The MVP prioritizes free, official, public data sources. No paid data feeds are required. Sources are evaluated for coverage, reliability, access method, authentication needs, terms of use, and refresh frequency before being added to the source library.
Every source listed on the source library page shows its owner, coverage, access method, authentication requirements, constraints, terms, reliability notes, and recommended use. Status labels (MVP, Phase 2+, Legal review) make clear which sources are production-ready and which are not.
Federal bill search calls the Congress.gov API server-side through a Netlify Function. The function normalizes bill numbers, Congress.gov URLs, and topic queries into structured search objects. Results include title, bill type, number, congress, sponsor, latest action, status, official URL, source owner, retrieved timestamp, and last-checked timestamp.
The site attempts to retrieve official bill text and package metadata from govinfo when a GovInfo API key is configured. If govinfo data is unavailable, the source packet records a govinfo_unavailable warning so readers know the official text was not retrieved.
State bill search calls the Open States API server-side through a separate Netlify Function. State queries normalize state bill numbers, official state legislature URLs, and topic searches. Results include the same trust metadata as federal results: source owner, retrieved timestamp, last-checked timestamp, and freshness status.
Active federal bill metadata should refresh at least daily in production. The MVP does not yet implement scheduled refresh jobs, but the cache contract is designed to support daily or on-demand refresh. Source packets and explanations are cached by deterministic keys (packet hash, prompt version, model version) so repeated lookups can reuse cached data without re-calling upstream APIs.
Before any AI generation happens, the server builds a source packet from Congress.gov metadata and govinfo package data. The packet includes the bill identity, official URLs, retrieval timestamps, a packet hash, and any missing-source warnings. The packet is the bounded context the AI model is allowed to use.
The explainer sends the source packet to an OpenAI-compatible API with a system prompt that enforces neutral, source-grounded output. The model is instructed to return strict JSON with required sections: TLDR, what the bill does, who is affected, what changes, supporter arguments, critic arguments, knowns, uncertainties, status, questions, and citations.
After the model returns, the server validates every citation against the source packet. Citations that do not match the packet's official URL, packet ID, or package ID are rejected. If unsupported citations are found, the response is marked as blocked and the invalid citations are surfaced to the reader.
If no source packet can be built (missing API key, upstream failure, or no matching bill), the explainer refuses to generate. If the source packet exists but the AI provider is unavailable, the explainer returns a partial response using the source packet directly, with visible limits. The site never generates an explanation that sounds complete when the source context is missing or too thin.
Citations may point to the source packet's official URL (Congress.gov bill page), the packet ID, or the govinfo package ID. The validator checks that every citation URL or ID already exists in the packet before accepting it.
If the AI model returns citations not present in the source packet, the response is marked as blocked. The invalid citations are listed in the response so the reader can see what was rejected. The site does not silently upgrade unsupported claims to trusted citations.
Every explanation includes a "What is known" section and a "What is uncertain" section. The model is instructed to separate verifiable facts from unknowns, pending votes, agency discretion, fiscal unknowns, and data gaps.
Data-driven pages show source owner, retrieval timestamp, last-checked timestamp, and a freshness status (current, needs-refresh, incomplete, unavailable). Missing or stale data produces an explicit degraded state, not a fake confident answer.
The site avoids party names, candidate endorsements, ideological framing, and "dunking" tone. Misconceptions are corrected using "common confusion" framing, not confrontational myth-busting. The AI system prompt enforces neutral, source-grounded language.
When public record supports both sides, the explanation includes attributable supporter and critic arguments. If sourced arguments are not available for one side, the explanation says so explicitly rather than inventing a false balance.
Every data-driven page and the explainer surface include a link to the corrections page. Reports capture page URL, error type, description, and optional contact email. The system stores only minimal metadata (boolean flags for presence of description and email) and does not retain raw personal data beyond what is needed for review.
Reports should be reviewed as product trust work. That can mean checking a source link, clarifying wording, tightening how uncertainty is shown, or flagging an AI explanation issue. The current MVP returns a receipt with a request ID; a full public correction ledger is a future-phase goal.
State bill search relies on the Open States API. Coverage depends on scraper availability and state site changes. Some states may lag or have incomplete data. The site does not scrape local government sites at scale.
The MVP does not provide address-to-representative lookup. Location features remain educational and location-light. A future phase may add geocoding with strong privacy minimization, but v1 does not store raw addresses.
The site does not ingest local government agendas, ordinances, budgets, or meeting records. Local government context is educational and link-based only.
The money-in-politics page is educational and link-based. The site does not ingest FEC, OpenSecrets, or FollowTheMoney data in the MVP. Campaign finance integration requires legal review of contributor data use restrictions.
Both are listed as MVP-supporting sources in the product spec, but neither has been integrated into a page or function yet. Federal Register context for bill-to-rulemaking relationships and Treasury fiscal data for debt/revenue education are future integration targets.
The site retrieves bill metadata and latest actions from Congress.gov, but it does not provide real-time vote tracking, amendment text, or committee hearing transcripts. Readers should check Congress.gov directly for real-time legislative activity.
The MVP does not require raw address storage. The "Find My Government" page is educational and directs readers to official election office directories. No geocoding, district lookup, or address collection is implemented in v1.
If a future phase adds address-to-district lookup, the site will explain what is sent to external providers, avoid storing raw addresses by default, let users clear location data immediately, and disclose all processing. Location data will never be sold or used for ad targeting.