MATRIXVOTERDOCS
Back to Simulation Sandbox
Chapter 1: The Core Philosophy

What is MatrixVoter? (In Plain English)

Traditional election polling is fundamentally broken. Pollsters spend weeks calling landline phones that young and mobile voters never answer, delivering stale snapshots by the time news cycles have already shifted.

MatrixVoter solves this by combining three real-time signals into a single probabilistic forecasting engine:

1

Live Betting Markets

Connects to Kalshi and Polymarket 24/7. When millions of dollars move on swing state odds, probabilities update instantly.

2

Census Demographics (MRP)

Breaks voters down by state, age, race, education, and urbanicity so no community is over- or under-represented.

3

AI Synthetic Electorate

Thousands of diverse AI voter personas deliberate in a small-world social network, reacting to inflation, policy news, and local peers.

Chapter 2: The Policy Sandbox

How to Run What-If Simulations

The Policy Sandbox allows analysts, journalists, and voters to test hypothetical election scenarios interactively. Adjusting any slider recalculates state-by-state electoral odds in under 50 milliseconds.

1. Suburban Turnout Delta (±15%)Key Swing: PA, MI, WI, NC, GA

Simulates shifts in suburban collar county engagement. Increasing this benefits college-educated suburban coalitions in critical Rust Belt and Sun Belt tipping-point states.

2. Economic Shock Factor (±20%)Key Swing: All 50 States

Models consumer confidence shocks, stock market swings, or unemployment spikes. Positive values lift the incumbent party baseline; negative values trigger national headwinds.

3. Youth Mobilization Surge (±25%)Key Swing: AZ, NV, GA, MI

Simulates high vs. low college campus and Gen-Z turnout. High youth turnout expands margins in university counties in Madison, Ann Arbor, Maricopa, and Fulton counties.

4. Inflation Pressure (0% to +15%)Key Swing: Elastic Independents

Models grocery, gas, and housing cost-of-living sentiment. High inflation pressure shifts undecided and moderate swing voters toward the challenger.

5. Rural Mobilization Surge (±20%)Key Swing: OH, FL, TX, IA, NC

Models non-metro voter turnout. High rural mobilization expands conservative margins and puts Rust Belt states in play.

Chapter 3: The Calculation Engine

How It Calculates (The Math in Plain English)

MatrixVoter uses a dual-pipeline statistical architecture: closed-form conjugate Bayesian updates in Polars for instant UI interactions, backed by PyMC Hierarchical GLMs.

Beta-Binomial Conjugacy (Polars)

Instead of running slow MCMC simulations on every slider move, MatrixVoter uses closed-form Bayesian math:

Posterior(α, β) = Prior(α₀ + k, β₀ + n - k)

Vectorized across all 50 states using Polars column arrays, allowing instant updates in <15 milliseconds.

Multilevel Regression & Poststratification (MRP)

Instead of treating a state as a monolithic pool:

  • Divides population into demographic slices (Strata).
  • Estimates vote choice for each slice using hierarchical priors.
  • Poststratifies (weights) using US Census population matrices.
Chapter 4: The Synthetic Town Hall

AI Agent-to-Agent (A2A) Deliberation

MatrixVoter instantiates a synthetic electorate of diverse AI personas connected in a small-world social graph (Watts-Strogatz topology).

1. Persona Synthesis

Each agent receives realistic demographic traits, occupation, concerns (e.g. mortgage rates, healthcare), and baseline political priors.

2. Peer Interactions

Agents are connected to realistic local social circles. When events occur, neighbors share thoughts and arguments.

3. DeGroot Opinion Cascades

Agents update beliefs based on confidence bounds. If an argument is persuasive and within their trust window, opinion shifts cascade through the community.

Chapter 5: API Connections & Feeds

Connecting Live APIs & Feeds

MatrixVoter runs 100% offline out-of-the-box using synthetic Brownian drift and cognitive heuristic models. To connect live streaming prediction markets and LLMs, add your API keys to .env:

LLM Engine (OpenAI, Groq, Ollama, vLLM)Runtime Only

Enables GPT-4o-mini or Llama-3 to generate contextual reasoning for synthetic voters during town halls:

LLM_API_KEY=sk-...
LLM_MODEL=gpt-4o-mini
LLM_BASE_URL=https://api.openai.com/v1
Kalshi Trading WebSocket FeedRuntime Only

Connects to live CFTC-regulated political prediction markets:

KALSHI_API_KEY=your_kalshi_key
KALSHI_API_SECRET=your_kalshi_secret
KALSHI_WS_URL=wss://api.elections.kalshi.com/trade-api/ws/v2
Polymarket CLOB WebSocket FeedRuntime Only

Connects to Polymarket order books:

POLYMARKET_API_KEY=your_polymarket_key
POLYMARKET_WS_URL=wss://ws-subscriptions-clob.polymarket.com/ws/market
Chapter 6: Health & Troubleshooting

Gateway Health & Forwarding Troubleshooting

Gateway Log: "Could not forward tick to Python engine"

This message means the Rust Gateway generated/ingested a market tick, but the Python engine at GATEWAY_FORWARD_URL was temporarily busy or unreachable.

How to Resolve in Coolify or Docker Compose:

  1. Docker Compose Stack: Ensure both services are in the same network (e.g. matrixvoter-prod-net) and the forward URL is set to http://engine:8000/api/v1/ingest/market-tick.
  2. Separate Coolify Services: If deployed as separate items in Coolify, set GATEWAY_FORWARD_URL=http://matrixvoter-engine-prod:8000/api/v1/ingest/market-tick or the internal Coolify DNS address.
  3. Health Checks: The Gateway responds on /health and /api/v1/health. Ensure your health check is configured to check port 8080 on path /health.