agentic-govbot/QUICKSTART.md

Govbot Quick Start Guide

This guide will help you get Govbot up and running.

Prerequisites

• Python 3.11 or higher
• llm CLI tool installed (pip install llm)
• Ollama installed with a model (e.g., ollama pull llama3.2) OR API keys for cloud models

Installation

1. Install Dependencies

Using uv (faster, recommended):

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv pip install -e .

Using regular pip:

pip install -e .

2. Configure the Bot

# Copy example config
cp config/config.example.yaml config/config.yaml

# Edit with your credentials and settings
nano config/config.yaml

⚠️ IMPORTANT - Security Notice:

• config/config.yaml contains your secrets (API tokens, passwords)
• This file is automatically gitignored - it will NEVER be committed
• Never share this file or commit it to version control
• See SECURITY.md for complete security guidance

For local models with Ollama:

ai:
  default_model: llama3.2  # or whatever model you have

For cloud models:

ai:
  default_model: gpt-4  # or claude-3-sonnet, etc.

Make sure the llm CLI is configured for your chosen model:

# Test llm
llm "Hello, how are you?"

# Configure for cloud models if needed
llm keys set openai  # for OpenAI
llm keys set anthropic  # for Anthropic Claude

3. Initialize the Database

The database will be created automatically on first run, but you can verify:

python -c "from src.govbot.db.models import init_db; init_db('govbot.db'); print('Database initialized!')"

Testing Without Mastodon

The CLI allows you to test all governance features without connecting to Mastodon:

# Run the interactive CLI
python -m src.govbot

Try these commands:

# View the constitution
constitution

# Ask a constitutional question
query What are the rules for creating a proposal?

# Create a test proposal
propose We should update the moderation guidelines

# Check active processes
processes

# Vote on a process (use the ID from processes command)
vote 1 agree

# Check process status
status 1

# View recent actions
actions

Testing the Constitutional Reasoner

You can test the constitutional reasoning engine directly:

python -m src.govbot.governance.constitution "What voting thresholds are required for different proposal types?"

Understanding the Architecture

Component Overview

1. Constitution (constitution.md): The governance rules in natural language
2. Database (govbot.db): SQLite database storing all governance state
3. AI Agent (src/govbot/agent.py): Interprets requests and orchestrates actions
4. Primitives (src/govbot/governance/primitives.py): Low-level governance operations
5. Constitutional Reasoner (src/govbot/governance/constitution.py): RAG system for understanding the constitution
6. Scheduler (src/govbot/scheduler.py): Background tasks for deadlines and reminders

How It Works

User Request
    ↓
AI Agent parses intent
    ↓
Queries Constitution (RAG)
    ↓
Plans primitive actions
    ↓
Executes with audit logging
    ↓
Returns response

Example: Creating a Proposal

Let's walk through what happens when you create a proposal:

$ python -m src.govbot
@testuser> propose We should add weekly community meetings

The bot will:

1. Parse your intent (creating a proposal)
2. Query the constitution about proposal rules
3. Determine this is a standard proposal (6 days, simple majority)
4. Create a governance process in the database
5. Schedule a reminder for the deadline
6. Respond with the proposal details and how to vote

You can then vote:

@testuser> vote 1 agree

And check status:

@testuser> status 1

The scheduler (running in background) will automatically close the proposal after 6 days and count votes.

Next Steps

Customizing the Constitution

Edit constitution.md to match your community's governance needs. The AI will adapt to whatever you write!

Key things to include:

• Proposal types and their requirements
• Voting thresholds
• Member rights and responsibilities
• Administrative procedures
• Safety mechanisms (veto, appeals)

Connecting to Mastodon

To connect to a real Mastodon instance, you'll need to:

1. Create a bot account on your instance
2. Register an application to get OAuth credentials
3. Update config/config.yaml with your Mastodon settings
4. Implement the Mastodon streaming listener (currently a stub in bot.py)

See MASTODON.md for detailed instructions (coming soon).

Adding Custom Governance Skills

You can extend the bot with custom Mastodon-specific actions:

1. Add new primitives in src/govbot/governance/primitives.py
2. Update the agent's planning logic in src/govbot/agent.py
3. Update the constitution to reference new capabilities

Running in Production

For production deployment:

1. Set up proper logging (see config.yaml)
2. Use a systemd service or supervisor to keep it running
3. Set up monitoring for the database and process queue
4. Consider running on a dedicated server or container
5. Implement backup procedures for the database

Troubleshooting

"Could not parse request" error

• Check that llm CLI is working: llm "test"
• Verify your model is installed: ollama list or check API keys
• Try a simpler request to test

"Constitution not found" error

• Make sure constitution.md exists in the root directory
• Check the path in config/config.yaml

Database errors

• Delete govbot.db and let it reinitialize
• Check file permissions

Model not responding

• Test llm directly: llm -m llama3.2 "hello"
• Check Ollama is running: ollama list
• For cloud models, verify API keys: llm keys list

Getting Help

• Check the README.md for architecture details
• Review the constitution examples
• Look at the code - it's designed to be readable!
• Open an issue if you find bugs

Philosophy

Govbot is designed around a few key principles:

1. Agentic, not procedural: The bot interprets natural language constitutions rather than hard-coding governance procedures
2. Transparent: All actions are logged with constitutional reasoning
3. Reversible: The community can override bot decisions
4. Flexible: Works with any constitution you write
5. Democratic: Enables collective governance within social platforms

Have fun governing! 🏛️