Initial commit: Platform-agnostic governance bot

Govbot is an AI-powered governance bot that interprets natural language constitutions and facilitates collective decision-making across social platforms. Core features: - Agentic architecture with constitutional reasoning (RAG) - Platform-agnostic design (Mastodon, Discord, Telegram, etc.) - Action primitives for flexible governance processes - Temporal awareness for multi-day proposals and voting - Audit trail with constitutional citations - Reversible actions with supermajority veto - Works with local (Ollama) and cloud AI models Platform support: - Mastodon: Full implementation with streaming, moderation, and admin skills - Discord/Telegram: Platform abstraction ready for implementation Documentation: - README.md: Architecture and overview - QUICKSTART.md: Getting started guide - PLATFORMS.md: Platform implementation guide for developers - MASTODON_SETUP.md: Complete Mastodon deployment guide - constitution.md: Example governance constitution Technical stack: - Python 3.11+ - SQLAlchemy for state management - llm CLI for model abstraction - Mastodon.py for Mastodon integration - Pydantic for configuration validation Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-02-06 17:09:26 -07:00
commit fbc37ecb8f
27 changed files with 6004 additions and 0 deletions
--- a/MASTODON_SETUP.md
+++ b/MASTODON_SETUP.md
@@ -0,0 +1,420 @@
+# 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
+
+### Credentials
+
+- **Never commit** `config/config.yaml` to version control
+- 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!