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):
```bash
# 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:
```bash
pip install -e .
```

### 2. Configure the Bot

```bash
# 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](SECURITY.md) for complete security guidance

For local models with Ollama:
```yaml
ai:
  default_model: llama3.2  # or whatever model you have
```

For cloud models:
```yaml
ai:
  default_model: gpt-4  # or claude-3-sonnet, etc.
```

Make sure the `llm` CLI is configured for your chosen model:
```bash
# 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:

```bash
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:

```bash
# 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:

```bash
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:

```bash
$ 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](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](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! 🏛️