# Project export: PolicyPulse — see the effects of a law before it passes This document was generated by HackStack to give an AI agent context about a hackathon project. Sections are labeled with their provenance; content marked as truncated was cut to keep this document small. ## Project metadata - Hackathon: UC Berkeley AI Hackathon 2026 - Tagline: See the real laws moving around you, simulate who they help and hurt on a Census-grounded model of your city, and contact the people who vote on them. - Devpost: https://devpost.com/software/policypulse-see-the-effects-of-a-law-before-it-passes - GitHub: https://github.com/lukeeskinner/PolicyPulse - Video: https://www.youtube.com/embed/PUahmkfhUOw?enablejsapi=1&hl=en_US&rel=0&start=&version=3&wmode=transparent - Team: 5 GitHub contributor(s) — Devin (12 commits), Zablon Tesfaye (11 commits), Luke Skinner (10 commits), kunjrathod2005 (5 commits), Abrham Dawit (3 commits) ## Devpost submission (written by the team) ### Inspiration When a city debates rent control, a minimum wage, or an upzoning plan, nobody actually knows who it will help and who it will hurt until years later — after it's law, and the damage or benefit is already done. Policy gets made on ideology and vibes, and the people hurt most are usually the ones with the least voice in the room. Even when someone does care, they have no easy way to turn that concern into action. We wanted to flip the order of operations: see the distributional consequences of a policy before anyone votes — on a model of your own community — and then act on it. ### What it does PolicyPulse has two halves that flow into each other. The Pulse Map finds your area and surfaces the real bills moving around you right now — live federal legislation from Congress.gov and state bills from OpenStates — plotted as markers on a 3D map, alongside a rail of real local policy news. Every marker is a real bill; nothing is mock data. The Simulator lets you click any bill (or paste your own) and watch it play out across a statistically representative population of synthetic residents built from live U.S. Census (ACS) data for that state — real population, income, rent, racial composition, and housing tenure. The residents live through three years. Second-order effects cascade: a landlord facing rent control sells the building, so tenants get displaced; a wage floor rises, so a small business cuts hours. An inequality spotlight then reveals exactly who gets hurt and who benefits — broken down by race, income, and housing status — with the Gini coefficient before and after. Then we close the civic loop three ways. First, hear the people: click any resident to read — and now hear — their AI-generated, first-person story, voiced aloud with a voice matched to that resident. Second, find your fit: a personalized mode simulates whether a specific location is a good fit for you in particular, based on your own situation, rather than the community in aggregate. Third, act on it: "Email your representative" looks up your real federal and state legislators, then drafts a respectful constituent email citing the exact bill and the simulation's findings about who it affects — opening a prefilled email for state legislators, or the official contact form with the draft copied for members of Congress. Two more surfaces back up the credibility. A /validate page runs real, studied policies (like San Francisco's 1994 rent-control expansion) through the same engine and checks the predicted direction of effects against published research. And a /lab runs Monte Carlo uncertainty bands and sensitivity analysis, so you see the range of outcomes rather than a single cherry-picked run. ### How we built it Our stack is Next.js (App Router, React Server Components, server-sent-event streaming), React, TypeScript, and Tailwind on the front end. Agent orchestration runs on Mastra with multiple Anthropic Claude agents. Deepgram Aura powers the resident voices. Mapbox GL + deck.gl render the 3D map and geocoding. Live civic data comes from U.S. Census ACS, Congress.gov, OpenStates, and GNews, with optional Redis mirroring every run. The engine is the technical core. We ground a population in live Census ACS data, then spawn individual residents whose joint distribution of race × income × housing tenure × neighborhood matches the real community — so a low-income renter of a given background appears at the real-world rate, not by independent chance, and spatial segregation emerges naturally. A Claude PolicyAnalyst agent parses a free-text bill into a structured impact model: mechanism, intensity, who benefits, who pays, and likely unintended consequences. The simulation then runs in two passes per round. In the first pass, actor agents — small landlords and business owners — make probabilistic decisions that generate shocks. In the second, those shocks ripple out to every other resident across Month 1 → Month 6 → Year 1 → Year 3, tracking rent burden, displacement, wellbeing, and whether each person had to leave. The entire run streams to the dashboard in real time over SSE, backed by a durable event log so a shared link can replay the whole run from scratch. Graceful degradation is built in: with zero API keys the app still runs end to end on heuristic parsing, template stories, and clearly-labeled fallback datasets. Every live surface degrades to an honest empty state rather than ever inventing data. ### Challenges we ran into The first challenge was making synthetic residents representative, not just random. Matching each demographic on its own is easy; matching the joint distribution — so income–tenure correlation and segregation emerge naturally — is what makes the inequality analysis meaningful rather than decorative. That took real care in the spawning logic. The second was a subtle, invisible metric bug. Per-group impact was being read before each run finalized, so the headline "net impact by demographic" panel silently showed zero for every group, on every policy. We caught it by testing deterministically across policy types, confirmed the real differentiated numbers existed, and fixed where they were surfaced rather than touching the numbers themselves. The third was keeping the model honest. It would have been easy to make every bill "show displacement" for drama. We made the engine principled instead: displacement only appears where a real housing mechanism exists, so a privacy law correctly shows ~0% while rent control and upzoning move the needle. The fourth was voice without overreach. We match Deepgram voices to resident gender (inferred from our name pools) and a slight age lean — deliberately not race, to avoid stereotyping — and keep it deterministic so a resident always sounds the same. ### Accomplishments we're proud of We built a simulation grounded in real U.S. Census data that produces genuinely differentiated, defensible distributional outcomes rather than random noise dressed up as analysis. We wired seven real external data and AI integrations — Census, Congress.gov, OpenStates, GNews, Mapbox, Anthropic, and Deepgram — into one coherent product, each with an honest fallback. We landed an emotional payload that actually works: hearing a displaced resident tell their own story in a human voice turns an abstract statistic into something you feel. We treated intellectual honesty as a design principle, with directional validation against published studies, visible uncertainty bands, and honest empty states instead of fabricated data. And we closed the loop from awareness to action: you don't just learn who a bill hurts, you can email the person who votes on it in two clicks. ### What we learned The hard part of "AI for policy" isn't the AI — it's earning trust. Real Census grounding, directional validation, transparent assumptions, and honest empty states matter more than any single model output. PolicyPulse is a tool for building intuition about who's affected, not a forecast, and stating that clearly makes it more credible, not less. We also learned how much rigor it takes to make a simulation defensible: the difference between "the numbers look plausible" and "we can show you why each number is what it is" is most of the work. ### What's next for PolicyPulse We want deeper validation against more published studies, additional policy mechanisms beyond housing and labor, and finer-grained Census grounding at the county and city level. We also want to grow the personalized "find your fit" mode into a full planner that answers a bigger question: where should I live, and how would these policies actually treat someone like me? ## README (from the GitHub repository) # PolicyPulse **See the law moving around you — then stress-test it on a digital twin of your own community.** PolicyPulse has two halves that flow into each other: 1. **The Pulse Map** (homepage) — a live, tilted 3D map of the United States that finds your area and surfaces the *real* federal and state bills moving around you right now, alongside a rail of local policy news. No mock data: every marker is a real bill from Congress.gov / OpenStates, every story is real local news. 2. **The Simulator** (`/simulate`) — click any bill (or paste your own) and watch it play out across a statistically representative population of AI residents **built from live U.S. Census (ACS) data** for that state. Residents live through three years; second-order effects cascade (a landlord sells → tenants get displaced; a wage floor rises → a small business cuts hours), and an inequality spotlight reveals exactly **who gets hurt** — before anyone votes. --- ## What it does ### The Pulse Map (homepage) - **Finds your area** from the browser's geolocation (or a ZIP / city search), reverse-geocoded with Mapbox. - **Pulls the real bills around you** — live federal legislation from the Congress.gov API and state legislation from OpenStates — and plots them as glowing markers on a 3D map that flies to your state. - **Streams local policy news** for your area from GNews in an auto-scrolling rail. - Click a marker to read the bill, then **“Simulate this policy”** hands it off to the simulator. ### The Simulator (`/simulate`) 1. **A bill arrives from the map** (or you paste your own and pick a state). 2. **Ingestion** grounds the population in **live U.S. Census ACS data** for that state — real population, median income, rent, racial composition, income distribution, tenure, and industry mix. Without a Census key it falls back to grounded, clearly-labeled datasets. 3. A **Mastra PolicyAnalyst agent** parses the free-text bill into a structured *impact model* (mechanism, intensity, who benefits, who pays, likely unintended consequences). 4. **Proportional spawning** creates individual residents whose joint distribution of race × neighborhood × income × tenure × employment matches the real community. 5. Residents **live through Month 1 → Year 3**. Each round layers market drift, direct policy effects, and **cascading shocks** between agents — streamed live to the dashboard. 6. The **Inequality Spotlight** quantifies disparities (e.g., displacement by race), the Gini shift, materialized unintended consequences, and ranked *who-gets-hurt / who-benefits* segments. 7. Click any resident to read their **AI-generated first-person story** (a Mastra Resident agent on Claude Haiku). There's also a **/validate** page that runs real, studied policies (e.g., SF's 1994 rent-control expansion) through the same engine and compares the predicted *direction* of effects against the documented findings of published research. ## Tech & sponsor integrations | Layer | Tech | | --- | --- | | Framework | **Next.js 16** (App Router, RSC, SSE streaming), React 19, TypeScript, Tailwind v4 | | Agents & orchestration | **Mastra** — `PolicyAnalyst` + `Resident` agents, a jurisdiction-ingestion tool, and a 2-step simulation workflow | | LLM | **Anthropic Claude Haiku** via Mastra's model router | | Nervous system | **Redis** — Streams (event log), JSON (snapshots), TimeSeries (metric trends), Pub/Sub | | Live civic data | **U.S. Census ACS** (population), **Congress.gov** (federal bills), **OpenStates** (state bills), **GNews** (local news), **Mapbox** (3D map + geocoding) | | Live ingestion | **Browserbase** — optional headless session to verify community data | | Viz | **Mapbox GL + deck.gl** (3D map), Recharts, Framer Motion, Lucide | **Graceful degradation is a feature:** with *no API keys at all*, the app still runs end-to-end — heuristic policy parsing, template resident stories, grounded datasets, and an in-memory event bus. Each live surface degrades to an **honest empty state** (“connect this key” / “no results”) rather than ever inventing data: no Mapbox token shows a connect-token prompt, no Census key falls back to labeled datasets, and no Congress / OpenStates / GNews key shows an empty rail. Add keys to light up the live integrations. ## Getting started ```bash npm install npm run dev ``` Open the printed URL (e.g. http://localhost:3000). With no keys you'll get the Pulse Map's “connect Mapbox” prompt and the `/simulate` dashboard running on labeled datasets — fully functional. Add keys (below) to go fully live, then restart `npm run dev` (env vars load on boot). ### Environment variables Copy `.env.example` to `.env.local` and add what you have — **everything is optional** and each key lights up one surface: **Live Pulse Map + Census-grounded population:** - `NEXT_PUBLIC_MAPBOX_TOKEN` — renders the 3D map and powers geolocation / search ([account.mapbox.com](https://account.mapbox.com/access-tokens/)). - `CENSUS_API_KEY` — grounds the simulated population in real ACS data ([api.census.gov](https://api.census.gov/data/key_signup.html)). - `CONGRESS_API_KEY` — real federal bills ([api.congress.gov](https://api.congress.gov/sign-up/)). - `OPENSTATES_API_KEY` — real state-legislature bills ([open.pluralpolicy.com](https://open.pluralpolicy.com/accounts/profile/)). - `GNEWS_API_KEY` — real local policy news ([gnews.io](https://gnews.io/)). **Simulator agents + nervous system:** - `ANTHROPIC_API_KEY` — enables the Mastra Haiku agents (policy analysis + resident stories). - `REDIS_URL` — mirrors every run into Redis Stack (Streams/JSON/TimeSeries/Pub-Sub). - `BROWSERBASE_API_KEY` + `BROWSERBASE_PROJECT_ID` + `ENABLE_BROWSERBASE=1` — optional live ingestion (also `npm i playwright-core`). ## Architecture ``` src/ app/ page.tsx Pulse Map landing (live bills near you, client) simulate/page.tsx The simulator dashboard (client) validate/page.tsx Historical validation api/ geo/ Reverse/forward geocoding (Mapbox) policies/ Real federal (Congress.gov) + state (OpenStates) bills news/ Real local policy news (GNews) census/ Live ACS demographic profile for a state simulate/ POST: start a run stream/[runId]/ SSE: live event stream (backlog replay + live tail) run/[runId]/ Full run snapshot agent/[runId]/[id]/ Resident narrative (Haiku) + trajectory runs/ · health/ · validate/ lib/ civic.ts Pulse Map types + geometry (markers, arcs) usePulse.ts Homepage hook (locate -> fetch bills/news/census) states.ts US state metadata (FIPS, centroids) cache.ts TTL cache for live API calls (quota-friendly) sources/ census · congress · openstates · news · geocode engine.ts Simulation engine (rounds, cascades, second-order effects) metrics.ts Aggregation + inequality analysis (disparities, segments, Gini) personas.ts Proportional agent spawning demographics.ts Grounded Census/ACS/BLS-shaped fallback datasets policy.ts Heuristic policy parser (offline brain) orchestrator.ts Paced live run driver -> bus events bus.ts · runStore.ts · redis.ts The "nervous system" ingest.ts Jurisdiction ingestion (live Census, + optional Browserbase) historical.ts Validation cases vs. published studies useSimulation.ts Simulator client hook (SSE consumption, rAF-batched) mastra/ index.ts Mastra instance agents/ policy-analyst, resident tools/ ingest-jurisdiction workflows/ simulation components/ Pulse Map (PulseMap, NewsRail, PolicyDetail, LocationBadge) + dashboard UI ``` ## A note on hon [README truncated for size] ## Detected evidence (automated analysis) Indexed codebase: 144 recognized source files, 839 KB. - CSS (language) — detected in the code - Next.js (technology) — detected in the code - React (technology) — detected in the code - Redis (technology) — detected in the code - Tailwind CSS (technology) — detected in the code - TypeScript (language) — detected in the code - Anthropic (technology) — claimed on Devpost, not found in the code - Node.js (technology) — claimed on Devpost, not found in the code - AI coding agent: Claude Code — evidence: config files committed to the repository - AI coding agent: Codex — evidence: config files committed to the repository ## Codebase structure (from repository index) ### Files (120 of 153) ``` .claude/skills/frontend-design/SKILL.md .env.example .gitignore AGENTS.md CLAUDE.md docs/presentation/PolicyPulse.md eslint.config.mjs NEXT_STEPS.md next.config.ts package.json postcss.config.mjs README.md scripts/shots.mjs scripts/shots2.mjs scripts/shots3.mjs src/app/api/agent/[runId]/[agentId]/route.ts src/app/api/census/route.ts src/app/api/compare/route.ts src/app/api/council/route.ts src/app/api/council/stream/[runId]/route.ts src/app/api/draft-email/route.ts src/app/api/geo/route.ts src/app/api/ghost/health/route.ts src/app/api/ghost/narrate/route.ts src/app/api/ghost/route.ts src/app/api/ghost/run/[runId]/route.ts src/app/api/ghost/stream/[runId]/route.ts src/app/api/health/route.ts src/app/api/impact/route.ts src/app/api/montecarlo/route.ts src/app/api/news/route.ts src/app/api/policies/route.ts src/app/api/representatives/route.ts src/app/api/run/[runId]/route.ts src/app/api/runs/route.ts src/app/api/sensitivity/route.ts src/app/api/simulate/route.ts src/app/api/speak/route.ts src/app/api/stream/[runId]/route.ts src/app/api/validate/route.ts src/app/council/page.tsx src/app/ghost/page.tsx src/app/globals.css src/app/lab/page.tsx src/app/layout.tsx src/app/me/page.tsx src/app/page.tsx src/app/runs/page.tsx src/app/simulate/page.tsx src/app/validate/page.tsx src/components/AgentDrawer.tsx src/components/AgentGrid.tsx src/components/AppHeader.tsx src/components/Brand.tsx src/components/ContactRep.tsx src/components/council/AmendmentImpact.tsx src/components/council/CouncilBench.tsx src/components/council/CouncilConsole.tsx src/components/council/DebateStream.tsx src/components/council/DeliberationFlow.tsx src/components/council/GroundingBrief.tsx src/components/council/IntegrationRail.tsx src/components/council/NarrationFeed.tsx src/components/council/Verdict.tsx src/components/EventTicker.tsx src/components/ghost/AgentPanels.tsx src/components/ghost/CrisisHud.tsx src/components/ghost/IntegrationRail.tsx src/components/ghost/NarrationFeed.tsx src/components/ghost/NegotiationBus.tsx src/components/ghost/PostMortem.tsx src/components/ghost/ScenarioConsole.tsx src/components/ghost/WorkflowViz.tsx src/components/ghost/WorldGraph.tsx src/components/InequalitySpotlight.tsx src/components/IngestionPanel.tsx src/components/lab/CompareView.tsx src/components/lab/labFormat.ts src/components/lab/MonteCarloView.tsx src/components/lab/SensitivityView.tsx src/components/LocationBadge.tsx src/components/MetricsTimeline.tsx src/components/NewsRail.tsx src/components/persona/PersonaForm.tsx src/components/persona/PersonalImpactCard.tsx src/components/PolicyConsole.tsx src/components/PolicyDetail.tsx src/components/PulseMap.tsx src/components/ThemeProvider.tsx src/components/ThemeToggle.tsx src/lib/bus.ts src/lib/cache.ts src/lib/civic.ts src/lib/council/brain.ts src/lib/council/bus.ts src/lib/council/grounding.ts src/lib/council/orchestrator.ts src/lib/council/stakeholders.ts src/lib/council/types.ts src/lib/council/ui.ts src/lib/council/useCouncil.ts src/lib/demographics.ts src/lib/engine.ts src/lib/ghost/agents.ts src/lib/ghost/brain.ts src/lib/ghost/bus.ts src/lib/ghost/engine.ts src/lib/ghost/grounding.ts src/lib/ghost/integrations.ts src/lib/ghost/observability.ts src/lib/ghost/orchestrator.ts src/lib/ghost/orkes.ts src/lib/ghost/redis.ts src/lib/ghost/runStore.ts src/lib/ghost/scenarios.ts src/lib/ghost/types.ts src/lib/ghost/ui.ts src/lib/ghost/useGhost.ts src/lib/headless.ts src/lib/historical.ts [33 more files omitted for size] ``` ### Dependencies - package.json: @browserbasehq/sdk@^2.14.1, @deck.gl/core@^9.3.4, @deck.gl/layers@^9.3.4, @deck.gl/mapbox@^9.3.4, @deck.gl/react@^9.3.4, @mastra/core@^1.45.0, @tailwindcss/postcss@^4, @types/node@^20, @types/react@^19, @types/react-dom@^19, clsx@^2.1.1, deck.gl@^9.3.4, eslint@^9, eslint-config-next@16.2.9, framer-motion@^12.40.0, lucide-react@^1.21.0, mapbox-gl@^3.25.0, next@16.2.9, playwright-core@^1.61.0, react@19.2.4, react-dom@19.2.4, react-map-gl@^8.1.1, recharts@^3.8.1, redis@^6.0.0, tailwind-merge@^3.6.0, tailwindcss@^4, typescript@^5, zod@^4.4.3 ### Recent commits (newest first) - fix ui - Merge remote-tracking branch 'origin/main' - personalization is nice - Merge origin/main (5 teammate PRs) into local work - Add Stakeholder Council, presentation docs, and agent/data refinements - fix outline for input - Merge pull request #5 from lukeeskinner/abrham/homepage-polish-perf - Zoom header logo mark - Merge pull request #4 from lukeeskinner/zablon/sim-fixes - Homepage: click-to-locate, logo, faster first load - Merge remote-tracking branch 'origin/main' into zablon/sim-fixes - feat: enhance AgentGrid with donut visualization and group stats - Fix all-zero per-group net impact + flesh out results page - Keep map dark in both themes (demo-safe) - Fix zoning displacement gap + fill Live Feed post-run - Merge light/dark theme + point-to-locate map dwell into main - Suppress hydration warning from browser-extension body attributes - Add polished light/dark theme with toggle - Merge pull request #3 from lukeeskinner/zablon/resident-voice - Add point-to-locate map dwell UX ## Key source files (fetched from GitHub, selected and truncated for size) ### CLAUDE.md ```markdown @AGENTS.md ``` ### AGENTS.md ```markdown # This is NOT the Next.js you know This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices. do not manufacture dat, NO FAKE MOCK DATA OR IMPLEMENTATIONS ST ``` ### package.json ``` { "name": "policypulse", "version": "0.1.0", "private": true, "scripts": { "dev": "next dev", "build": "next build", "start": "next start", "lint": "eslint" }, "dependencies": { "@browserbasehq/sdk": "^2.14.1", "@deck.gl/core": "^9.3.4", "@deck.gl/layers": "^9.3.4", "@deck.gl/mapbox": "^9.3.4", "@deck.gl/react": "^9.3.4", "@mastra/core": "^1.45.0", "clsx": "^2.1.1", "deck.gl": "^9.3.4", "framer-motion": "^12.40.0", "lucide-react": "^1.21.0", "mapbox-gl": "^3.25.0", "next": "16.2.9", "playwright-core": "^1.61.0", "react": "19.2.4", "react-dom": "19.2.4", "react-map-gl": "^8.1.1", "recharts": "^3.8.1", "redis": "^6.0.0", "tailwind-merge": "^3.6.0", "zod": "^4.4.3" }, "devDependencies": { "@tailwindcss/postcss": "^4", "@types/node": "^20", "@types/react": "^19", "@types/react-dom": "^19", "eslint": "^9", "eslint-config-next": "16.2.9", "tailwindcss": "^4", "typescript": "^5" } } ``` ### src/mastra/index.ts ```typescript import { Mastra } from "@mastra/core/mastra"; import { advocateAgent } from "./agents/advocate"; import { policyAnalystAgent } from "./agents/policy-analyst"; import { residentAgent } from "./agents/resident"; import { ghostReasoningAgent } from "./agents/ghost"; import { ingestJurisdictionTool } from "./tools/ingest-jurisdiction"; import { simulationWorkflow } from "./workflows/simulation"; // The Mastra instance: policy analysis + resident narration for PolicyPulse, // the Ghost Protocol crisis-reasoning agent, the jurisdiction ingestion tool, // and the simulation workflow. export const mastra = new Mastra({ agents: { policyAnalyst: policyAnalystAgent, resident: residentAgent, advocate: advocateAgent, ghostReasoner: ghostReasoningAgent, }, workflows: { simulation: simulationWorkflow, }, tools: { ingestJurisdiction: ingestJurisdictionTool, }, }); ``` ### src/app/layout.tsx ```typescript import type { Metadata } from "next"; import { Space_Grotesk, Inter, Instrument_Serif, JetBrains_Mono } from "next/font/google"; import { ThemeProvider } from "@/components/ThemeProvider"; import "./globals.css"; // Applied before paint so there's no flash and no hydration mismatch: dark is // the default, a stored choice wins, otherwise we respect the system setting. const themeScript = `(function(){try{var t=localStorage.getItem('pp-theme');if(t!=='light'&&t!=='dark'){t=window.matchMedia('(prefers-color-scheme: light)').matches?'light':'dark';}document.documentElement.setAttribute('data-theme',t);}catch(e){document.documentElement.setAttribute('data-theme','dark');}})();`; const display = Space_Grotesk({ variable: "--font-grotesk", subsets: ["latin"], weight: ["400", "500", "600", "700"], }); const sans = Inter({ variable: "--font-inter", subsets: ["latin"], }); const serif = Instrument_Serif({ variable: "--font-instrument", subsets: ["latin"], weight: "400", style: ["normal", "italic"], }); const mono = JetBrains_Mono({ variable: "--font-jetbrains", subsets: ["latin"], }); export const metadata: Metadata = { title: "PolicyPulse — See the law land before it passes", description: "A live civic map of the bills moving around you, paired with a demographic digital twin that shows exactly who each policy helps and who it hurts.", icons: { icon: "/policypulse-icon.png", shortcut: "/policypulse-icon.png", apple: "/policypulse-icon.png", }, }; export default function RootLayout({ children, }: Readonly<{ children: React.ReactNode; }>) { return (