This project is a non-partisan, educational research tool. It is not intended to influence elections, predict future outcomes, or be used for political campaigning. Data reflects public historical records only. This project is free, open-source, and will never be monetized.
See DISCLAIMER.md for full data sources, model limitations, and use restrictions.
In 2020, a small team at SysWisdom set out to understand a simple question: what does historical county-level voting data actually tell us? We built a machine learning pipeline on top of publicly available presidential election records to explore turnout patterns, vote share trends, and the "wisdom" hidden in aggregated civic participation.
The project was shelved when the political climate made any election-adjacent work feel polarizing — even purely analytical, non-partisan work. We are now sharing it openly because we believe civic data education belongs to everyone. There is no commercial angle. There is no agenda. The code is here so researchers, educators, and curious citizens can learn from it, improve it, or build something better.
If you find it useful, we only ask that you keep that same spirit of openness.
- Predict county-level election outcomes using historical presidential voting data (2016–2024)
- Multiple ML models: Random Forest, Gradient Boosting, Logistic Regression, SVM
- Voter turnout trend analysis across election cycles
- AI-powered simulated Q&A on election-related queries (FAISS vector store)
- Flask web app with county/state selector and visual results
- Supports adding new counties and states dynamically
myvoterwisdom/
├── app.py # Flask web server — main entry point
├── main.py # Train + evaluate pipeline runner
├── main_vote2028.py # County prediction script (called by app.py)
├── main_all_county.py # Batch prediction across all counties
├── preprocess.py # Data cleaning & feature engineering
├── train_model.py # Random Forest model training
├── evaluate_model.py # Model evaluation & classification report
├── post_predictions_2028.py # Linear regression projections for 2028
├── getStateCounty.py # Builds county.json & state.json from CSV
├── Fetch_County_Data.py # Utility to fetch county data
├── requirements.txt # Python dependencies
│
├── data/
│ ├── voting_pres_data.csv # Historical presidential voting data (source of truth)
│ ├── prediction_pres_data.csv
│ ├── county.json # Generated county lookup
│ ├── state.json # Generated state lookup
│ ├── reasoning/ # AI simulation & Q&A training data
│ │ ├── simulated_questions.csv
│ │ ├── voter_questions.index # FAISS index
│ │ └── county_turnout_analysis.csv
│ └── vectorStore/
│ └── voterQuestions.py # Builds FAISS vector store from Q&A CSV
│
├── static/
│ ├── index.html # Web app frontend
│ └── styles.css
│
├── image/ # Screenshots and visualizations
├── model/ # Saved trained models (joblib)
├── tests/ # Test suite
│ ├── testMain2028.py # unittest for county prediction
│ ├── verify_wisdom.py # Wisdom column distribution check
│ ├── verify_preprocessing.py
│ ├── simulate_ai_2020_new.py
│ └── incompletness.py
└── results.json # Latest prediction output
No local install required. Click a badge to open the notebook directly in Colab
using the myvoterwisdom-497415 project environment.
| Notebook | Purpose | Open |
|---|---|---|
| 01 — Explore Data | Load & visualize voting_pres_data.csv |
 |
| 02 — Train Model | Step-by-step preprocessing & Random Forest training | |
| 03 — Predict County | Interactive county/state prediction with 4 models | |
Each notebook auto-clones this repo and installs dependencies on first run. Runtime → Change runtime type → T4 GPU is available on the free tier.
- Python 3.10+
- pip
git clone https://github.com/sysWisdom/myvoterwisdom.git
cd myvoterwisdompip install -r requirements.txtpython app.pyOpen your browser to http://127.0.0.1:5000, select a state and county, and click Predict.
-
data/voting_pres_data.csvis the source of truth — update it when new county records are available (columns:Election Year,State,County,Total Registered Voters,Total Ballots Cast,Democratic Votes,Republican Votes,Total Voted). -
To get county predictions:
python app.py # starts the web server # OR run directly: python main_vote2028.py "Orange County" CA # Results are written to results.json
If only one data record exists for a county, the model cannot train — you will get a 100% accuracy message, which means insufficient data, not a real result.
-
When a new county is added to the CSV:
python getStateCounty.py # rebuilds county.json and state.json python main_all_county.py # runs predictions for all counties
-
AI simulation files (
data/reasoning/,data/vectorStore/) contain training data for the FAISS-based Q&A layer. Rundata/vectorStore/voterQuestions.pyto rebuild the index after updatingsimulated_questions.csv. -
Tests:
python -m pytest tests/testMain2028.py -v python tests/verify_wisdom.py python tests/verify_preprocessing.py
Copyright © 2024 SysWisdom.AI LLC. Licensed under the BSD 3-Clause License.
What this means in plain language:
| You CAN | You CANNOT |
|---|---|
| Use this code freely, including in your own projects | Use the SysWisdom name to endorse your product without permission |
| Modify and redistribute the code | Remove the copyright notice from redistributed copies |
| Use it commercially (though we ask you don't monetize election data irresponsibly) | Hold SysWisdom liable for any outcomes |
| Publish research or educational material based on this work |
See the LICENSE file for the full legal text.
We welcome contributions that advance civic education and data transparency. Please read our CODE_OF_CONDUCT.md before contributing. Open an issue before submitting a pull request so we can discuss the change.
We will not merge contributions that:
- Add predictive features intended for use in active political campaigns
- Introduce any form of monetization or user tracking
- Include personally identifiable voter information
