Quorum

Democracy, simulated. AI politicians with real-world memory based context debate bills while citizens shape the final vote. Transparent policy via smart contracts, cultivating accountability.

Comment 1

Inspiration

We were inspired by the opacity surrounding legislative processes and the growing need for citizens to understand how bills move through parliament. As blockchain technology and smart contracts become increasingly relevant to governance, we wanted to explore how these tools could improve transparency and trust.

Quorum was born from this idea: a simulation where AI representatives debate legislation, and every outcome—votes, amendments, and final decisions—is immutably recorded on-chain through smart contracts, backed by efficient token-based voting systems.

What It Does

Quorum is an interactive parliamentary simulation engine that:

  • Loads bills and routes them through a complete 8-stage legislative pipeline
    (parsing → agency assignment → committee deliberation → floor debate → public forum → voting → smart contract finalization)
  • Simulates realistic committee deliberations with AI-controlled representatives, each with distinct political personas
  • Integrates Kairos smart contracts to immutably record bill outcomes, amendments, and voting records on-chain
  • Implements Token Company’s tokenization system for vote-weight calculation and participation tracking
  • Provides a real-time web interface where users can vote, submit comments, and watch AI representatives debate live
  • Generates detailed interaction logs capturing every step: speeches, amendments, lobby assignments, vote tallies, and final outcomes
  • Allows failed bills to be revised a configurable number of times and re-run through the pipeline with feedback incorporated

The simulation is powered by LLMs (via Ollama), uses in-memory state management, and serves both backend logic and frontend assets through a single Java executable.

How We Built It

Frontend

  • HTML5, CSS3, and ES6 JavaScript (vanilla, no framework)
  • Real-time polling architecture using the Fetch API
  • Responsive UI with voting overlays, transcript panels, and public comment submission

Backend

  • Java 17 with Maven build system
  • Ollama LLM client (HTTP-based) for:
    • AI representative behavior
    • Bill summarization
    • Agency assignment
  • Jackson Databind 2.17.2 for JSON serialization/deserialization
  • Custom agent-based simulation framework:
    • PoliticianAgent, JudgeAgent, AgentRegistry
  • Graph-based pipeline executor (GraphRunner) with 8 modular nodes and loop-backs for bill revision cycles
  • In-memory state management:
    • LogStore – circular event logs
    • VoteBox – vote tallying with duplicate prevention
    • ChatStore – public messages
    • SimpleMemoryStore – per-agent context memory
  • Embedded web server with endpoints for:
    • Static assets
    • Representative profiles (/representatives)
    • Log polling (/log)
    • Vote submission and status (/vote, /status)
    • Public chat (/chat)

APIs & External Services

  • Ollama (local LLM inference)
    • Default model: gemma2:2b (configurable via environment variables)
  • Token Company API
    • Efficient tokenization of voting weights and participation metrics
  • Kairos Smart Contract Platform
    • Immutable on-chain recording of bill outcomes, amendments, and voting data

Data Files (JSON-based Configuration)

  • config/bill.txt – Plain-text bill content
  • config/representatives.json – Representative personas (party, ideology scores, red lines, pet issues, speaking style)
  • config/agencies.json – Agency metadata and scope keywords
  • config/facts.json – Verified statistics for agents to cite during debates

Build & Deployment

  • Maven Shade Plugin to produce a fat JAR
  • Single executable:
    • govsim-1.0-SNAPSHOT-shaded.jar
  • Effortless cross-platform deployment with no external database dependencies

Challenges We Ran Into

  1. LLM Output Variability
    Ollama occasionally returns malformed JSON or incomplete responses. We implemented multi-tier fallback logic with progressive token-limit increases and response normalization.

  2. Agent Consistency
    Maintaining personality and memory across debate phases (committee → floor → revision) required a context-aware MemoryStore that retrieves relevant past statements.

  3. Complex Prompt Engineering
    Generating valid JSON for amendments, lobby targets, and vote reasoning—while respecting agent constraints—required extensive iteration and testing.

  4. Kairos Smart Contract Integration
    Serializing complex simulation outcomes into gas-efficient, immutable records required careful schema design.

  5. Token Company Tokenization
    Mapping diverse participation types (committee votes, floor debates, public votes) into a unified token-weight system required a flexible abstraction layer.

Accomplishments That We’re Proud Of

  • End-to-End LLM-Driven Simulation
    A complete parliamentary workflow with AI agents debating and voting based on realistic political profiles.
  • Novel Smart Contract Integration
    Full bill lifecycles immutably recorded on-chain via Kairos.
  • Efficient Token-Based Voting
    Transparent, fair vote weighting using Token Company’s system.
  • Real-Time Interactive Platform
    Users can participate alongside AI representatives and watch results finalize on-chain live.
  • Modular Graph-Based Pipeline
    An 8-node executor with loop-backs for seamless revision and re-debate.
  • Single-Executable Full Stack
    Backend and frontend bundled into one JAR with zero deployment complexity.
  • Production-Ready Logging
    Comprehensive audit trails for every decision, vote, and amendment.

What We Learned

  • Prompt Engineering Is Critical
    Agent quality is directly tied to prompt design and edge-case handling.
  • Agent Memory Matters
    Even lightweight context retrieval significantly improves realism.
  • Smart Contracts Need Schema Discipline
    On-chain storage of complex data requires lean, gas-efficient schemas.
  • Token Systems Are Powerful Abstractions
    Tokenization enables diverse participation signals to be unified cleanly.
  • Polling Can Beat WebSockets
    For low-frequency updates, polling is simpler and sufficiently responsive.
  • Decoupling Enables Scale
    Separating agent logic, prompts, execution, and web serving improved testability and extensibility.

What’s Next for Quorum

  • Multi-Bill Campaigns – Simulate full legislative sessions with interdependent bills
  • Advanced Kairos Governance – On-chain voting for which bills get simulated
  • Token Incentives – Reward constructive public participation with reputation scores
  • Historical Data Integration – Train agents on real legislative speeches and voting records
  • Explainability Dashboard – Kairos-linked visualizations of bill evolution and rationale
  • Mobile Apps – Native clients for voting and debate participation
  • Simulation Analytics – Export data for civic education and policy research
  • Multi-Language Support – Adapt Quorum for legislatures worldwide

Built With

Share this project:

Updates