Skip to content

SETUP.md

Latest commit

 

History

History
173 lines (117 loc) · 3.76 KB

SETUP.md

File metadata and controls

173 lines (117 loc) · 3.76 KB

Setup Guide — AI Policy Town Hall Simulator

Exact commands to run from scratch on a fresh machine.

Prerequisites

Step-by-Step Setup

1. Clone the project

git clone <your-repo-url>
cd policy-town-hall

2. Create a virtual environment

python -m venv venv

Activate it:

# Windows (PowerShell)
venv\Scripts\Activate.ps1

# Windows (cmd)
venv\Scripts\activate.bat

# macOS / Linux
source venv/bin/activate

3. Install Python dependencies

pip install -r requirements.txt

4. Set up environment variables

# Windows
copy .env.example .env

# macOS/Linux
cp .env.example .env

Open .env in your editor. The defaults work with Ollama out of the box:

LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434
DEBATE_MODEL=qwen2.5:3b-instruct
SUMMARY_MODEL=qwen2.5:7b-instruct

5. Install and start Ollama

Download and install Ollama from ollama.com.

Pull the required models:

# Required — fast 3B model for debate turns
ollama pull qwen2.5:3b-instruct

# Recommended — higher-quality 7B model for report synthesis
ollama pull qwen2.5:7b-instruct

Verify Ollama is running:

ollama list

You should see qwen2.5:3b-instruct in the output.

6. Run the application

streamlit run ui/app.py

Open http://localhost:8501 in your browser.

7. Run the test suite (optional)

python -m pytest tests/test_debate.py -v

Google OAuth Setup (Optional)

Only needed if you want to save reports to Google Drive or send email summaries.

1. Create a Google Cloud Project

2. Enable APIs

  • Navigate to APIs & Services → Library
  • Enable Google Drive API
  • Enable Gmail API

3. Create OAuth Credentials

  • Go to APIs & Services → Credentials
  • Click Create Credentials → OAuth 2.0 Client ID
  • Application type: Desktop app
  • Download the JSON file
  • Save it as client_secret.json in the project root

4. Configure OAuth Consent Screen

  • Go to APIs & Services → OAuth consent screen
  • Select External
  • Add your email as a test user

5. Update .env

GOOGLE_OAUTH_CLIENT_SECRETS=client_secret.json
GOOGLE_OAUTH_TOKEN=token.json
GMAIL_RECIPIENT=your_email@gmail.com

6. First Run

On first launch with Drive/Gmail enabled, a browser window will open asking for Google authorization. After you approve, a token.json is created and reused automatically.

Troubleshooting

Problem Solution
ConnectionRefusedError on LLM call Make sure Ollama is running: ollama serve
Model not found Pull it: ollama pull qwen2.5:3b-instruct
Google Drive fails silently Check that client_secret.json exists and APIs are enabled
ModuleNotFoundError Activate your venv and run pip install -r requirements.txt
Streamlit import errors Run from project root: streamlit run ui/app.py
DuckDuckGo search returns empty Normal if rate-limited; debate continues without evidence

Quick Demo (3 minutes)

  1. Start the app: streamlit run ui/app.py
  2. Click the sample policy: "Should Ahmedabad implement a congestion tax on private vehicles?"
  3. Set rounds to 2 for speed
  4. Uncheck Drive/Gmail (unless configured)
  5. Click Start Debate
  6. Watch agents debate in real time
  7. Review the structured impact report
  8. Download the JSON report

Total time: ~2 minutes with qwen2.5:3b-instruct on CPU.