agentic-govbot/MASTODON_SETUP.md

# Mastodon Setup Guide

This guide walks through setting up Govbot on a Mastodon instance.

## Prerequisites

- A Mastodon instance (existing or test)
- Admin access to the instance (for creating bot account and getting credentials)
- Python 3.11+ installed
- Ollama (for local models) or API keys for cloud models

## Step 1: Create Bot Account

### On Your Mastodon Instance

1. **Create a new account** for the bot:
   - Go to your Mastodon instance
   - Sign up for a new account (e.g., `govbot@yourinstance.social`)
   - Verify the email address
   - Complete the profile (add avatar, bio explaining it's a governance bot)

2. **Note the bot's username** (you'll need this for configuration)

## Step 2: Register Application

### Get OAuth Credentials

1. **Navigate to Settings** while logged in as the bot account
2. Go to: **Settings → Development → New Application**

3. **Configure the application**:
   - **Application name**: Govbot
   - **Application website**: Your instance URL or governance documentation
   - **Redirect URI**: `urn:ietf:wg:oauth:2.0:oob` (for command-line auth)

4. **Scopes needed**:
   - `read` - Read account info and notifications
   - `read:statuses` - Read statuses
   - `write` - Post statuses
   - `write:statuses` - Create statuses
   - `admin:read` - Read admin data (if bot will have admin powers)
   - `admin:write` - Perform admin actions (if bot will manage instance)

5. **Click "Submit"**

6. **Save credentials**:
   - Client key (client_id)
   - Client secret (client_secret)
   - Access token (you may need to generate this)

### Generate Access Token

If the application page doesn't show an access token:

```python
# Run this Python script to generate an access token
from mastodon import Mastodon

Mastodon.create_app(
    'Govbot',
    api_base_url='https://your-instance.social',
    to_file='govbot_clientcred.secret'
)

mastodon = Mastodon(
    client_id='govbot_clientcred.secret',
    api_base_url='https://your-instance.social'
)

# Log in (will prompt for username and password)
mastodon.log_in(
    'your_bot@email.com',
    'your_bot_password',
    to_file='govbot_usercred.secret'
)

# The access token is now in govbot_usercred.secret
with open('govbot_usercred.secret') as f:
    access_token = f.read().strip()
    print(f"Access token: {access_token}")
```

## Step 3: Configure Govbot

### Update Configuration File

1. **Copy the example config**:
   ```bash
   cp config/config.example.yaml config/config.yaml
   ```

2. **Edit `config/config.yaml`**:
   ```yaml
   platform:
     type: mastodon

     mastodon:
       instance_url: https://your-instance.social
       client_id: YOUR_CLIENT_ID_HERE
       client_secret: YOUR_CLIENT_SECRET_HERE
       access_token: YOUR_ACCESS_TOKEN_HERE
       bot_username: govbot  # Your bot's username

   ai:
     # For local models:
     default_model: llama3.2

     # For cloud models:
     # default_model: gpt-4
     # (Make sure to configure llm CLI with: llm keys set openai)

   governance:
     constitution_path: constitution.md
     db_path: govbot.db
     default_veto_threshold: 0.67
     enable_auto_execution: true
     require_confirmation_for:
       - admin_action
       - moderation

   debug: false
   log_level: INFO
   ```

3. **Test LLM configuration**:
   ```bash
   # Test that llm works
   llm "Hello, test message"

   # If using local models, verify Ollama is running
   ollama list
   ```

## Step 4: Initialize Database

```bash
# Create the database
python -c "from src.govbot.db.models import init_db; init_db('govbot.db'); print('Database initialized!')"
```

## Step 5: Test with CLI

Before connecting to Mastodon, test the bot logic:

```bash
# Run the CLI
python -m src.govbot

# Try these commands:
query What are the rules for proposals?
propose We should have weekly community meetings
processes
exit
```

## Step 6: Run the Bot

```bash
# Start the bot
python -m src.govbot.bot

# You should see:
# INFO - Connecting to Mastodon instance: https://your-instance.social
# INFO - Connected as @govbot (ID: ...)
# INFO - Started listening for messages
# INFO - Bot is running. Press Ctrl+C to stop.
```

## Step 7: Test on Mastodon

### Basic Test

1. From another account on your instance, post:
   ```
   @govbot help
   ```

2. The bot should respond with information about how to use it

### Create a Proposal

```
@govbot I propose we add a weekly community meeting on Fridays
```

The bot should:
- Acknowledge the proposal
- Cite constitutional authority
- Explain voting period and threshold
- Provide instructions for voting

### Vote on Proposal

Reply to the proposal thread:
```
@govbot agree
```

### Check Status

```
@govbot status 1
```

## Granting Admin Powers (Optional)

If you want the bot to perform instance administration:

### 1. Grant Moderator/Admin Role

In Mastodon admin interface:
- Go to Moderation → Accounts
- Find the bot account
- Assign Moderator or Admin role

### 2. Update Constitution

Make sure your constitution specifies when and how admin powers can be used:

```markdown
## Admin Powers

The bot may perform administrative actions only when:
1. Authorized by constitutional amendment process
2. Approved by supermajority vote
3. Within scope of delegated authority

Admin actions include:
- Updating instance rules
- Moderating content
- Managing user accounts
- Changing instance settings
```

### 3. Test Admin Skills

```
@govbot What admin actions can you perform?
```

## Troubleshooting

### Bot Not Receiving Mentions

**Check**:
- Bot account access token is valid
- `read` scope is enabled
- Bot is following the mentioning account (or has appropriate visibility settings)
- Bot is actually running (check logs)

**Test manually**:
```python
from mastodon import Mastodon

client = Mastodon(
    access_token='YOUR_TOKEN',
    api_base_url='https://your-instance.social'
)

# Check notifications
notifications = client.notifications()
print(notifications)
```

### Bot Can't Post

**Check**:
- `write:statuses` scope is enabled
- Access token is valid
- Instance isn't rate limiting the bot
- Bot account isn't silenced/suspended

### Connection Errors

**Check**:
- Instance URL is correct (include `https://`)
- Instance is accessible from bot's network
- Firewall isn't blocking connection
- Instance isn't experiencing downtime

### LLM Errors

**For local models**:
```bash
# Check Ollama is running
ollama list
ollama ps

# Test the model
llm -m llama3.2 "test"
```

**For cloud models**:
```bash
# Check API keys
llm keys list

# Test the model
llm -m gpt-4 "test"
```

### Database Errors

**Reset database**:
```bash
# Backup first!
cp govbot.db govbot.db.backup

# Delete and reinitialize
rm govbot.db
python -c "from src.govbot.db.models import init_db; init_db('govbot.db')"
```

## Security Considerations

**📖 See [SECURITY.md](SECURITY.md) for the complete security guide.**

### Credentials

- **Never commit** `config/config.yaml` to version control (it's in `.gitignore`)
- **Never commit** `*_clientcred.secret` or `*_usercred.secret` files (also gitignored)
- Store credentials securely
- Use environment variables for production:
  ```bash
  export GOVBOT_PLATFORM__MASTODON__ACCESS_TOKEN="your_token"
  ```
- Rotate tokens periodically

### Access Control

- Don't grant unnecessary scopes
- Use separate accounts for testing vs. production
- Monitor bot actions through audit log
- Set up alerts for suspicious activity

### Rate Limiting

The bot respects Mastodon's rate limits. If you see rate limit errors:
- Reduce frequency of checks in scheduler
- Implement exponential backoff
- Consider caching frequently accessed data

## Production Deployment

### Systemd Service

Create `/etc/systemd/system/govbot.service`:

```ini
[Unit]
Description=Govbot Governance Bot
After=network.target

[Service]
Type=simple
User=govbot
WorkingDirectory=/home/govbot/agentic-govbot
ExecStart=/usr/bin/python3 -m src.govbot.bot
Restart=always
RestartSec=10

Environment="GOVBOT_LOG_LEVEL=INFO"

[Install]
WantedBy=multi-user.target
```

Enable and start:
```bash
sudo systemctl enable govbot
sudo systemctl start govbot
sudo systemctl status govbot

# View logs
sudo journalctl -u govbot -f
```

### Docker Deployment

Create `Dockerfile`:
```dockerfile
FROM python:3.11-slim

WORKDIR /app
COPY . .

RUN pip install -e .

CMD ["python", "-m", "src.govbot.bot"]
```

Build and run:
```bash
docker build -t govbot .
docker run -v $(pwd)/config:/app/config -v $(pwd)/govbot.db:/app/govbot.db govbot
```

### Monitoring

- Set up log aggregation (e.g., Loki, Elasticsearch)
- Monitor database size
- Track API usage and rate limits
- Alert on error rates
- Monitor governance activity

## Next Steps

- Customize the constitution for your community
- Test governance workflows
- Gather community feedback
- Iterate on processes
- Document your instance's governance

## Getting Help

- Check [QUICKSTART.md](QUICKSTART.md) for general usage
- Review [PLATFORMS.md](PLATFORMS.md) for platform details
- See [README.md](README.md) for architecture overview
- Open an issue on GitHub for bugs or questions

---

**Important**: This is governance infrastructure. Test thoroughly before deploying to a production community!