CivIQ — Political Literacy Through AI

Inspiration

Political engagement in the United States isn’t declining because people don’t care; it’s declining because the gap between caring and knowing has become too wide. Voters face hundreds of legislators, thousands of bills, and a media environment that frames everything as team sports rather than policy substance.

CivIQ closes that gap. The guiding question:

What if you could understand, in under three minutes and plain English, which elected officials and active legislation actually reflect your priorities?

Not party labels. Not endorsements. Just real voting behavior mapped to what you care about.

---

What We Built

CivIQ is a non-partisan political literacy tool. Users describe their priorities (via sliders or plain English) and receive:

• A ranked list of legislators aligned with those priorities
  
• Matching bills they can explore or act on
  
• Clear explanations of why the alignment exists
  

Every output is framed as “based on your stated priorities,” never as a recommendation.

---

How It Works

User Flow

1. Input: user chooses sliders or free text
   
2. Survey: priorities across four categories: Climate, Healthcare, Economy, Criminal Justice
   
3. Clarify: up to 4 targeted follow-up questions
   
4. Results: ranked matches, bills, and gap alerts
   

Technical Architecture

• Frontend: React, Vite, Tailwind, shadcn/ui (Landing, Survey, Chat, Results)
• Backend: Express API with four core routes:

Route	Purpose
POST /api/extract	Convert input → weight vector
POST /api/clarify	Multi-turn clarification
POST /api/score	Similarity + explanation
GET /api/legislators	Fetch vote vectors

---

Claude Integration

Claude powers three tightly-scoped steps:

1. Extraction

Free text (e.g., “I want universal healthcare and strong climate policy”) is mapped to:

$$\text{weights} = {Climate, Healthcare, Economy, CriminalJustice}, \quad w_i \in [0,100]$$

• 50 = neutral / not mentioned
  
• No inference from demographics; only explicit statements
  

2. Clarification

Claude identifies uncertain categories (40–60 range) and asks targeted open-ended questions to clarify a user’s nuanced opinion.

3. Scoring

Claude receives:

• User weight vector
  
• Legislator vote vector
  

It returns a short, plain-English explanation of alignment. No jargon, no party references, no endorsements.

---

Similarity Scoring

We compute alignment using cosine similarity:

$$\text{score}(u,v) = \frac{u \cdot v}{|u| \cdot |v|} \times 100$$

This prioritizes directional alignment — shared priorities matter more than absolute intensity.

---

Data Pipeline

• Congress.gov API — bill data and voting records
  
• Supabase — cached vote vectors (24h TTL)
  

---

Risks & Safeguards

Bias in Extraction

Risk: Inferring political lean from tone or wording
Safeguard: Only explicit statements are used; neutral input → neutral scores

Framing Effects

Risk: Results perceived as endorsements
Safeguard: Explicit “not an endorsement” framing + strict prompt constraints

Neutral Categories

Risk: Unstated views influencing results
Safeguard: “Explore both sides” section for unclear categories

Data Skew

Risk: Uneven legislative data biasing results
Safeguard: Vote-based vectors only; no party signals used

Hallucinated Explanations

Risk: Fabricated rationale
Safeguard: Claude grounded in numeric vectors; fallback = “Explanation unavailable”

Graceful Degradation

If APIs fail:

• Neutral weights returned
  
• Mock data served
  
• App remains functional
  

---

Empowering, Not Replacing

CivIQ is designed to inform, not decide:

• Users define all inputs
  
• Claude asks questions, not opinions
  
• Results include transparent reasoning
  
• Misalignments are surfaced, not hidden
  
• “Both sides” panels expand understanding
  

The goal: better-informed voters, not directed ones.

---

Ethical Considerations

Non-Partisanship by Design

Neutrality is enforced across prompts, UI, and scoring. Cosine similarity avoids party-based assumptions entirely.

Data Provenance

All data comes from public government records: no advocacy ratings or ideological scoring systems.

No Persistent User Data

Preferences live only in sessionStorage. Nothing is stored or tracked.

Transparency

We explicitly communicate:

• Limited category coverage
  
• Approximate vote vectors
  
• Non-endorsement nature of results
  

AI Confidence Calibration

Uncertainty is surfaced, not hidden.

• Low-confidence → follow-up questions
  
• Max 4 questions prevents overfitting
  

---

What We Learned

• Prompt discipline > prompt length. Precision beats verbosity.
  
• Question UX matters. Structured formats improved clarity and engagement.
  
• Cosine similarity struggles with neutrality. Clarification is essential.
  
• True neutrality is hard. Even wording required careful iteration to remove bias.
  

---

CivIQ reframes political engagement from identity and affiliation to alignment and understanding, making it faster and easier for people to connect their values to real policy decisions.

Built With

• claude
• claude-sonnet-4-6
• congress.gov
• express-?-backend-claude-claude-sonnet-4-6-(anthropic-api)-?-nlp-extraction-+-alignment-explanation-congress.gov-api-?-535-real-legislators
• express.js
• node.js
• radix
• radix-ui-?-frontend-node.js
• react
• supabase
• tailwind-css
• vite