{"path":"research/deliberation-io.md","content":"# Deliberation.io\n\n**Stanford Digital Economy Lab + MIT GOV/LAB collaborative deliberation platform.**\n\nResearched: March 27, 2026. Sources: GitHub repos, Stanford DEL project page, DC.gov press releases, Stanford Daily, source code analysis.\n\n## Overview\n\nDeliberation.io is an AI-facilitated civic deliberation platform designed for large-scale public engagement. It uses GPT-4 for two purposes: Socratic questioning of individual participants and steelman synthesis of collective opinions. The platform was deployed in Washington D.C. in July 2025 as the first U.S. city-level AI deliberation pilot.\n\n**Key distinction**: This is an **opinion polling platform with AI-mediated reflection**, not an argumentation platform. It has no concept of claims, evidence, logical relationships, or argument structure.\n\n## GitHub Repositories\n\n| Repo | Purpose | Stack |\n|------|---------|-------|\n| [itchytoo/deliberation.io](https://github.com/itchytoo/deliberation.io) | **Main application code** (89 commits, Python 92% / HTML 8%) | Firebase Cloud Functions, OpenAI |\n| [Jiaxin-Pei/deliberation.io](https://github.com/Jiaxin-Pei/deliberation.io) | Static landing page only (GitHub Pages) | HTML/CSS |\n| [Watts-Lab/deliberation-empirica](https://github.com/Watts-Lab/deliberation-empirica) | **Separate project** -- small-group video-call deliberation experiments on Empirica V2 (different team, different purpose) | 8 stars |\n\n## Architecture and Tech Stack\n\nFirebase-native serverless application:\n\n- **Frontend**: FlutterFlow (Dart/Flutter web app, no-code/low-code). Two app URLs revealed via CORS config: `deliberationio-yizum0.flutterflow.app` and `deliberationiobeta2.flutterflow.app`.\n- **Backend**: Python Firebase Cloud Functions (`firebase_functions` SDK). All business logic in `functions/fn_impl/` as HTTP-triggered cloud functions.\n- **Database**: Firestore (NoSQL document DB)\n- **Auth**: Firebase Auth with JWT token verification on every endpoint\n- **AI**: OpenAI GPT-4 via `openai==0.28` (pre-1.0 SDK). No streaming, no tool calling.\n- **Deployment**: Firebase Hosting + Cloud Functions, GitHub Actions CI/CD\n- **Other deps**: pandas, requests, matplotlib (analytics)\n\n### Cloud Function Modules\n\nFrom `main.py` imports:\n\n```python\nfrom fn_impl.home import *\nfrom fn_impl.createTopic import *\nfrom fn_impl.round1 import *\nfrom fn_impl.round2 import *\nfrom fn_impl.admin import *\nfrom fn_impl.socratic import *\nfrom fn_impl.steelman import *\nfrom fn_impl.pageNavigation import *\nfrom fn_impl.analytics import *\n```\n\n## Firestore Data Model\n\nCollections identified in the source code:\n\n| Collection | Structure | Purpose |\n|------------|-----------|---------|\n| `deliberations` | Top-level document per topic. Fields: `topicName`, `topic`, `isPlacebo`, `placeboPrompt`, `isSteelman`, `pushyLevel` | Deliberation configuration |\n| `deliberations/{id}/commentCollection` | Subcollection. Doc per user, field `comments: [string]` (array of comment versions) | User opinions (Round 1) |\n| `deliberations/{id}/votesCollection` | Subcollection. Doc per user | Topic-level votes |\n| `deliberations/{id}/socraticCollection` | Subcollection. Doc per user, field `socraticHistory: [{role, text}]` | Multi-turn Socratic dialogue history |\n| `deliberations/{id}/steelmanCommentCollection` | Subcollection. Doc per steelmanned opinion, field `comments: [string]` | GPT-4-synthesized steelman positions |\n| `users` | Doc per user. Fields: `createdDeliberations`, `participatedDeliberations`, `email`, `uid` | User profiles |\n\n## Deliberation Flow\n\n```\nHomepage -> Round 1 -> Socratic Dialogue -> Round 2\n```\n\n1. **Round 1**: Users see seed viewpoints (yes/no taglines + descriptions), write their own opinion, cast a topic-level vote.\n2. **Socratic Dialogue**: 1-on-1 AI conversation challenging the user's stated position (see below).\n3. **Round 2**: Users see other participants' comments (randomly sampled, up to 10, optionally steelmanned by GPT-4), and vote on each comment.\n\n**Note**: \"Face of the Crowd\" (preference distribution visualization) and \"Dynamic Deliberation\" (AI-generated follow-up questions for group discussion) are described in press materials but not present in the codebase -- likely in a separate repo or unreleased.\n\n## AI: Socratic Dialogue (`socratic.py`)\n\nGPT-4 conducts a 1-on-1 multi-turn conversation with each participant to deepen their examination of their beliefs.\n\n### Prompt Design\n\nThe full system prompt instructs GPT-4 to:\n\n- \"Deepen the user's examination of their beliefs on the topic at hand\"\n- Craft follow-up questions that \"probe deeply into the user's argument, aimed at revealing the underlying layers of thought, assumption, and belief\"\n- \"Compel them to engage in deeper reflection and explanation\"\n- Ask exactly **one probing question per turn** (explicitly constrained)\n\n### Pushiness Levels (1-3)\n\nConfigurable per-deliberation via `pushyLevel` field. Each level has a distinct tone:\n\n| Level | Style | Example (affordable housing) |\n|-------|-------|------------------------------|\n| 1 | Gentle, broad | \"What leads you to see affordable housing as a fundamental human right?\" |\n| 2 | Moderately challenging | \"Could investing heavily in affordable housing divert funds from other vital services?\" |\n| 3 | Highly provocative | \"Why should taxpayers fund housing for others, rather than promoting personal responsibility and letting the market regulate housing prices?\" |\n\nAdditional examples in the prompt cover climate change and UBI at all three levels.\n\n### Placebo Mode\n\nThe `isPlacebo` flag redirects Socratic dialogue to an unrelated topic (the `placeboPrompt` field) -- used for research control groups. When active, the AI asks probing questions about the placebo topic instead of the actual deliberation topic.\n\n### Implementation Details\n\nTwo versions exist: `getFullHistory` (hardcoded topic and level=1) and `getFullHistoryModular` (reads topic, pushiness level, and placebo config from Firestore). The modular version:\n\n- Reads deliberation config from Firestore to get topic name, pushiness level, and placebo flag\n- Constructs the full conversation history from stored roles/texts\n- Inserts the system prompt as the first message with all parameters filled\n- Calls `openai.ChatCompletion.create(model=\"gpt-4\", messages=messages)`\n- Stores the updated conversation history back to `socraticCollection`\n\nThe OpenAI API key is passed from the client in every request (`data['apikey']`) -- a notable security choice.\n\n## AI: Steelman Synthesis (`steelman.py`)\n\nAfter Round 1 comment collection, GPT-4 synthesizes all opinions into 3-7 \"fundamental opinions,\" each steelmanned into its strongest form.\n\n### Steelman Prompt\n\n```\nAs a moderator in a discussion, your role is to extract the most fundamental\nperspectives from users' diverse opinions on the topic: {topic}.\n\nYou must present at least 3 and no more than {MAX_K} fundamental opinions --\nthis is a strict upper limit, and the goal is to stay as close to 3 as possible.\nYour task is to refine each perspective into its strongest form, amalgamating\nsimilar yet slightly differing opinions into single, robust viewpoints. Ensure\nthat each selected opinion is steelmanned, providing a tight list of perspectives,\neach crafted in no more than 5 sentences and no less than 3, with clear and\nforceful justification.\n```\n\n- `MAX_K = 7` (hard cap on number of synthesized positions)\n- Output format: opinions separated by `###` delimiters (parsed by splitting on `###`)\n- Each steelmanned opinion is stored as a separate document in `steelmanCommentCollection`\n- Synthetic user accounts are created for each steelmanned opinion (with `@stanford.edu` email addresses)\n\n### Notable Prompt Engineering\n\nThe steelman prompt uses a dramatic threat for format compliance: \"If your output format differs AT ALL from the format I have specified above, I will lose billions of dollars and get a deathly illness, and you will be unemployed.\" -- a crude but effective technique for GPT-4 output formatting compliance (pre-structured outputs era).\n\n## D.C. Deployment (July 2025)\n\nWashington D.C. became the **first U.S. city** to use deliberation.io:\n\n- **Date**: July 15, 2025\n- **Event**: D.C. AI Public Listening Session (town hall on city government AI usage)\n- **Partners**: Bowser Administration, MIT GOV/LAB, Stanford Digital Economy Lab\n- **Co-organizer**: OCTO (Office of the Chief Technology Officer)\n- **Focus**: How the city government uses AI to serve residents\n- **Status**: Completion report with analysis was planned but results not yet published\n\nSources:\n- [DC.gov press release](https://octo.dc.gov/release/bowser-administration-announces-first-its-kind-ai-pilot-program-new-platform-mit-governance)\n- [Stanford Daily article](https://stanforddaily.com/2025/09/24/digital-economy-lab-launches-platform/)\n\n## Team\n\n| Person | Role |\n|--------|------|\n| **Alex \"Sandy\" Pentland** | MIT Media Lab, principal investigator |\n| **Lily Tsai** | MIT GOV/LAB, principal investigator |\n| **Jiaxin Pei** | Stanford DEL postdoc, NLP/AI lead |\n| **Jose Ramon Enriquez** | Stanford DEL postdoc, policy |\n| **Umar Patel** | Core developer |\n| **Alia Braley** | Team member |\n| **Lula/Nuole Chen** | Team member |\n| Chinmaya, Guinness | Code authors (per source comments) |\n\n## Key Papers\n\n- **\"Deliberation.io: Facilitating Democratic and Civil Engagement at Scale\"** -- Pei et al. Platform paper.\n- **\"Can AI Truly Represent Your Voice in Deliberations? A Comprehensive Study of Large-Scale Opinion Aggregation with LLMs\"** ([arXiv:2510.05154](https://arxiv.org/html/2510.05154)) -- Zhu, Yang, Bakker, Pentland, Pei. Introduces DeliberationJudge for evaluating LLM opinion aggregation.\n- **\"Benchmarking Overton Pluralism in LLMs\"** ([arXiv:2512.01351v2](https://arxiv.org/html/2512.01351v2)) -- Evaluates LLMs' ability to represent diverse viewpoints (ICLR 2026).\n\n## Comparison to Deliberus\n\n| Dimension | Deliberation.io | Deliberus Vision |\n|-----------|----------------|-----------------|\n| **Core model** | Opinion polling with AI facilitation | Argument mapping with formal structure |\n| **Ontology** | Opinions, comments, votes (flat text) | Claims, evidence, logical relationships (structured graph) |\n| **AI role** | Socratic questioner + opinion synthesizer | Claim extraction, logical validation, argument analysis |\n| **Argumentation theory** | None. No formal framework, no claim decomposition, no evidence linking, no logical structure | Dung's frameworks, ASPIC+, Walton's schemes, AIF |\n| **Data model** | Firestore documents: `{comments: [string], votes: {}}` | Knowledge graph with typed relationships |\n| **Scale approach** | Survey-style: collect opinions, aggregate with LLM | Structured: decompose arguments, connect evidence |\n| **Truth-seeking** | No argument quality assessment | Core design goal |\n| **Proven value** | LLMs can facilitate reflection and synthesize opinions at scale | (To be demonstrated) |\n\n### What Deliberus Can Learn\n\n**Borrow**:\n- The Socratic dialogue prompt is well-crafted -- particularly the pushiness levels (1-3) and the explicit \"one question per turn\" constraint. This pattern could inspire Deliberus's AI interaction layer.\n- The steelman synthesis approach demonstrates practical LLM-based opinion consolidation.\n- Placebo/control group support shows research rigor worth emulating.\n\n**Skip**:\n- The data model is too flat for structured argumentation (comments as string arrays, no structure).\n- No graph database, no argument structure, no formal logic.\n- Old OpenAI SDK (0.28), no streaming, no tool calling.\n- FlutterFlow (no-code) is inadequate for the rich interactive argument mapping UI that Deliberus needs.\n- No claim extraction, no evidence linking, no logical validation.\n\n### Positioning\n\nDeliberation.io is much closer to **Polis** (opinion clustering) than to argument mapping tools like Kialo or what Deliberus envisions. It proves that AI-mediated 1-on-1 reflection improves deliberation quality, but does not attempt to structure arguments, assess logical validity, or map relationships between claims. These are precisely the gaps Deliberus aims to fill.\n"}