{
  "markdown": "<p align=\"center\">\n  <img src=\"public/images/civiq-logo-hero.webp\" alt=\"CIV.IQ\" width=\"160\">\n</p>\n\n<h1 align=\"center\">CIV.IQ</h1>\n\n<p align=\"center\">Civic intelligence from government sources, organized for public use.</p>\n\n<p align=\"center\">\n  <a href=\"https://civdotiq.org\">civdotiq.org</a> &bull;\n  <a href=\"docs/API_REFERENCE.md\">API Reference</a> &bull;\n  <a href=\"CONTRIBUTING.md\">Contribute</a> &bull;\n  <a href=\"LICENSE\">License</a>\n</p>\n\n---\n\n## What this is\n\nA civic intelligence platform. Enter an address to find your federal and state representatives, with voting records, federal campaign finance, committee assignments, legislative activity, and machine-learning-powered analysis of money-in-politics patterns. Local-government coverage is limited to a pilot list of 10 cities.\n\nAll data comes from government APIs. All analysis is statistical, with confidence scores and methodology disclosed. If data is unavailable, the interface and the response payload say so explicitly. Nothing is fabricated.\n\nHonest coverage matrix: [docs/COVERAGE.md](docs/COVERAGE.md). It is the canonical answer to \"what does CIV.IQ actually cover?\" — every other claim in this README defers to that page.\n\n## What it does\n\n**Representatives**: Federal and state legislators with photos, contact info, committee assignments, and voting records.\n\n**Campaign Finance**: Federal only — FEC contributions, PAC spending, expenditure tracking, and donor sector analysis. State campaign finance is not currently available (FollowTheMoney.org is in maintenance mode during the OpenSecrets merger).\n\n**Intelligence Layer**: Statistical analyzers that cross-reference voting records with campaign finance, lobbying filings, stock trades, and committee jurisdictions to surface patterns of potential influence. Every insight carries a confidence score, methodology note, and correlation-not-causation disclaimer.\n\n**Vote Prediction**: An XGBoost model (trained on historical roll call data, exported to ONNX) predicts how representatives are likely to vote on upcoming legislation, with an independence score measuring deviation from party line.\n\n**Money Report**: Address-based lookup that traces the path from campaign contributions through committee assignments to legislative outcomes for your specific representatives.\n\n**Sector Leaderboard**: Rankings of legislators by industry sector, showing which members receive the most from a given industry relative to their peers.\n\n**Regulations & Comment Periods**: Federal Register integration for proposed rules, final rules, executive orders, and open public comment periods.\n\n**State Legislatures**: All 50 states via OpenStates — legislators, bills, committees, votes, and calendars. Interactive district boundary maps for all 7,383 state legislative districts. State-level campaign finance, lobbying, and stock-trade data are **not** part of state coverage.\n\n**Local Government**: City council data for 10 pilot cities via Legistar (Austin, Boston, Chicago, Denver, Detroit, Minneapolis, Oakland, Philadelphia, Portland, Seattle). Outside this list, local-government routes return `dataQuality: 'unavailable'` rather than empty arrays. There is no national local-government API; coverage expands one city at a time.\n\n**District Intelligence**: Demographics, economic indicators (BLS employment data), federal spending (USASpending), infrastructure metrics, and bills ranked by relevance to each congressional district.\n\n**Nostr Publishing**: Civic events (new bills, votes, hearings) are signed and published to the Nostr network for decentralized, verifiable distribution.\n\n## Developer integrations\n\n| Integration                                            | What it provides                                                |\n| ------------------------------------------------------ | --------------------------------------------------------------- |\n| [OpenAPI spec](public/openapi.json)                    | 39 paths, 29 schemas — generate clients in any language         |\n| [@civiq/sdk](packages/sdk)                             | Zero-dependency TypeScript client (`npm install @civiq/sdk`)    |\n| [MCP server](/api/mcp)                                 | 47 tools for AI assistants (Claude, Cursor, etc.)               |\n| [Atom feeds](/api/feed/bills/latest)                   | RSS-compatible feeds for bills, members, districts, committees  |\n| [Embeddable widgets](https://civdotiq.org/open/embeds) | Drop-in HTML for legislator cards, district lookup, bill status |\n| [llms.txt](public/llms.txt)                            | AI-discoverable documentation                                   |\n\n## Data sources\n\n| Source                     | What it provides                                            |\n| -------------------------- | ----------------------------------------------------------- |\n| Congress.gov v3            | Bills, votes, members, committees, hearings                 |\n| FEC.gov                    | Campaign contributions, expenditures, PAC filings           |\n| U.S. Census Bureau         | Demographics, geocoding, economic data                      |\n| Senate.gov XML             | Senate floor votes, roll calls                              |\n| House Clerk XML            | House voting records                                        |\n| OpenStates GraphQL         | State legislators, bills, committees, votes (all 50 states) |\n| GovInfo                    | Hearing transcripts, legislative documents                  |\n| Federal Register           | Executive orders, proposed rules, comment periods           |\n| USASpending.gov v2         | Federal contracts, grants, awards by district               |\n| Senate LDA                 | Lobbying disclosure filings                                 |\n| Bureau of Labor Statistics | Employment, wages, labor force data                         |\n| SEC EDGAR                  | Financial disclosures, stock trades (STOCK Act)             |\n| Wikidata SPARQL            | State executives, judiciary, biographies                    |\n| FRED                       | Federal Reserve economic indicators                         |\n| Regulations.gov            | Public comments on proposed rules                           |\n| Census TIGER/Line          | Congressional and state district boundaries                 |\n\nThe table lists the primary sources. Additional federal agency datasets — CDC PLACES, CMS, Medicaid, FEMA, FBI UCR, FDIC, VA, Treasury, CFPB, NHTSA, College Scorecard, and more — power district and intelligence features, for **26 live government data sources** in total. The canonical, continuously verified list is [docs/COVERAGE.md](docs/COVERAGE.md).\n\nNo data is fabricated, scraped, or generated.\n\n## Setup\n\n```bash\ngit clone https://github.com/civdotiq/civ.iq.git\ncd civ.iq\nnpm install\ncp .env.example .env.local\n```\n\nAdd API keys to `.env.local`. All are free:\n\n```env\n# Required\nCONGRESS_API_KEY=       # api.congress.gov/sign-up\nFEC_API_KEY=            # api.open.fec.gov/developers\nCENSUS_API_KEY=         # api.census.gov/data/key_signup.html\nOPENSTATES_API_KEY=     # openstates.org/accounts/profile\n\n# Recommended\nUPSTASH_REDIS_REST_URL= # upstash.com (caching)\nUPSTASH_REDIS_REST_TOKEN=\nGOOGLE_GENERATIVE_AI_API_KEY= # aistudio.google.com/apikey (AI summaries)\n\n# Optional (enhanced features)\nFRED_API_KEY=           # fredaccount.stlouisfed.org/apikeys\nDATA_GOV_API_KEY=       # api.data.gov/signup (Regulations.gov)\nGOVINFO_API_KEY=        # api.govinfo.gov/docs\n```\n\nSee `.env.example` for the full list, including Nostr publishing and ActivityPub federation.\n\n```bash\nnpm run dev\n```\n\nVerify at [localhost:3000/api/health](http://localhost:3000/api/health).\n\n## Structure\n\n```\nsrc/\n├── app/\n│   ├── api/                  # 181 API routes\n│   └── (civic)/              # Pages (representatives, districts, legislation, etc.)\n├── components/\n│   ├── intelligence/         # Insight cards, leaderboards, influence chains\n│   └── ...                   # Shared UI, search, visualizations\n├── features/                 # Feature modules\n│   ├── campaign-finance/\n│   ├── legislation/\n│   ├── representatives/\n│   └── state-legislature/\n├── lib/\n│   ├── intelligence/         # Analyzers, ML models, embeddings, entity resolution\n│   ├── nostr/                # Nostr event signing and relay publishing\n│   ├── data-sources/         # Federal Register, FRED, SEC, lobbying services\n│   └── ...                   # API clients, services, utilities\n├── hooks/                    # Custom React hooks\n└── types/                    # TypeScript definitions\npackages/\n├── sdk/                      # @civiq/sdk (TypeScript API client)\n├── civic-statistics/         # @civiq/civic-statistics (confidence scoring, correlation)\n└── entity-resolution/        # @civiq/entity-resolution (entity matching, deduplication)\n```\n\n## Stack\n\nNext.js 16, React 18, TypeScript (strict), Tailwind CSS, SWR, Zustand, MapLibre GL, D3.js, Recharts, Redis (Upstash + ioredis), Zod, simple-statistics, HuggingFace Transformers (small models), Google Gemini AI, nostr-tools.\n\n## Intelligence layer\n\n12 statistical analyzers cross-reference government data domains:\n\n| Analyzer                     | What it detects                                            |\n| ---------------------------- | ---------------------------------------------------------- |\n| Finance-Jurisdiction Overlap | Donor sectors that match a member's committee jurisdiction |\n| Vote-Finance Correlation     | Voting alignment with campaign contributor industries      |\n| Temporal Vote Shifts         | Quarterly changes in party-line voting patterns            |\n| Lobbying Pipeline            | Lobbying spend → committee activity → bill output chains   |\n| PAC-to-Vote Tracing          | PAC contributions traced to recipient voting records       |\n| Stock-Committee Overlap      | STOCK Act trades in sectors a member's committee regulates |\n| Influence Chain              | Full money → committee → legislation → vote pathways       |\n| Sector Leaderboard           | Industry-by-industry legislator rankings                   |\n| Vote Prediction              | ML model (XGBoost/ONNX) for roll call vote forecasting     |\n| Bill Intelligence            | Sponsor funding sources cross-referenced with lobbying     |\n| Bill-Lobbying Similarity     | Semantic similarity between bill text and lobbied issues   |\n| Federal Register Analysis    | Regulatory intelligence from proposed and final rules      |\n\nEvery insight carries: confidence score (0–1), data-as-of timestamp, methodology description, and a disclaimer that correlation does not imply causation.\n\n### ML pipeline\n\n- **Vote prediction**: Training data collected via `npm run collect:training-data`, model trained in Python (`scripts/train-vote-model.py`), exported to ONNX, inference in TypeScript (`src/lib/intelligence/ml/vote-predictor.ts`)\n- **Text similarity**: all-MiniLM-L6-v2 embeddings for bill-to-lobbying matching\n- **Classification**: nli-deberta-v3-xsmall for zero-shot stance detection\n- **Named entity recognition**: bert-base-NER for extracting entities from civic text\n- **Influence clusters**: Offline Python computation (`scripts/compute-influence-clusters.py`) served as JSON\n\n### Open-source packages\n\nThree packages are extracted as standalone npm workspace packages:\n\n- **@civiq/sdk** — TypeScript API client with typed methods for all 39 endpoints, error hierarchy, custom fetch injection\n- **@civiq/civic-statistics** — Confidence scoring, peer comparison, correlation (Spearman/Pearson), anomaly detection, sample size enforcement\n- **@civiq/entity-resolution** — Committee alias resolution, ticker-to-industry mapping, FEC recipient deduplication\n\n## Commands\n\n```bash\nnpm run dev            # Dev server at localhost:3000\nnpm run build          # Production build\nnpm run lint           # ESLint\nnpm run type-check     # TypeScript strict check\nnpm test               # Run all tests (Jest)\nnpm run test:e2e       # Playwright end-to-end tests\nnpm run validate:all   # lint + type-check + test + build\nnpm run diagnose:apis  # Test API connectivity\n```\n\nAdditional scripts for performance benchmarking, data/ML processing, and security scanning are defined in [`package.json`](package.json).\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License\n\nApache License 2.0. Copyright 2019-2026 Mark Sandford.\n\nUse it, modify it, distribute it. Include the copyright, license, and NOTICE file per Apache 2.0 Section 4. Provide visible attribution: \"Powered by CIV.IQ.\" The CIV.IQ name and logo are trademarks and require written permission to use. See [LICENSE](LICENSE) and [NOTICE](NOTICE).\n\n---\n\nMark Sandford - contact@civdotiq.org\n",
  "bytes": 12729,
  "sha": "0379ab6ce56432c406a157b3da2f6155dc74c779863a22d6f2cc7e431fd4ad19",
  "repo_slug": "civdotiq/civ.iq",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_civdotiq_civiq_2ed2511a/readme"
}