agentic-govbot/README.md

Govbot

An agentic governance bot for democratic communities that interprets natural language constitutions and facilitates collective decision-making across social platforms.

Overview

Govbot is designed to:

• Read and interpret governance constitutions written in natural language
• Facilitate proposals, voting, and decision-making on social platforms
• Execute administrative actions based on constitutional rules
• Maintain an audit trail of all governance actions
• Support both local (Ollama) and cloud AI models
• Work across multiple platforms (Mastodon, Discord, Telegram, etc.)

Features

• Agentic Architecture: The bot dynamically interprets constitutional rules rather than hard-coding governance procedures
• RAG-based Constitutional Reasoning: Uses retrieval-augmented generation to understand and apply governance rules
• Platform-Agnostic: Same governance logic works across Mastodon, Discord, Telegram, Matrix, and more
• Reversible Actions: All actions are logged and can be reversed through constitutional processes
• Temporal Awareness: Handles multi-day governance processes with deadlines and reminders
• Supermajority Veto: Built-in safety mechanism allowing members to halt problematic actions
• Platform Skills: Can perform admin actions, moderation, and platform-specific governance

Supported Platforms

• ✅ Mastodon - Full implementation with streaming, admin, and moderation
• 🚧 Discord - Coming soon (see PLATFORMS.md for implementation guide)
• 🚧 Telegram - Coming soon
• 🚧 Matrix - Planned

Want to add a platform? See PLATFORMS.md for the implementation guide!

Architecture

┌─────────────────────────────────────────┐
│      Governance Core (Platform-Agnostic)│
│  - Constitutional Reasoning (RAG)       │
│  - AI Agent & Planning                  │
│  - Action Primitives                    │
│  - Temporal Scheduler                   │
└────────────────┬────────────────────────┘
                 │
         ┌───────▼───────┐
         │   Platform    │
         │   Adapter     │ ← Abstraction layer
         └───────┬───────┘
                 │
      ┌──────────┼──────────┐
      │          │          │
 ┌────▼────┐┌───▼────┐┌───▼────┐
 │Mastodon ││Discord ││Telegram│
 │ Adapter ││ Adapter││ Adapter│
 └─────────┘└────────┘└────────┘

Installation

# Install dependencies (using uv for faster installation)
uv pip install -e .

# For development
uv pip install -e ".[dev]"

Quick Start

1. Install Dependencies (above)

2. Configure (Credentials Required)

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

# Edit with your credentials
nano config/config.yaml

⚠️ IMPORTANT: config/config.yaml contains your secrets and is automatically ignored by git. Never commit this file.

Configure:

• Platform credentials (Mastodon access tokens, Discord bot tokens, etc.)
• AI model settings (Ollama local models or cloud API keys)
• Constitution path and database location

For detailed setup instructions:

• Mastodon: See MASTODON_SETUP.md
• Security: See SECURITY.md for credential management

3. Set AI API Keys (if using cloud models)

# For OpenAI
llm keys set openai

# For Anthropic Claude
llm keys set anthropic

These are stored securely in ~/.llm/keys.json (also gitignored)

Usage

# Run the bot
python -m src.govbot.bot

# Query the constitution
python -m src.govbot.governance.constitution "What are the rules for proposals?"

Constitution Format

Your constitution should be a markdown file that describes:

• Governance processes (proposals, voting, etc.)
• Decision-making thresholds
• Member rights and responsibilities
• Administrative procedures
• Safety mechanisms (veto, appeals, etc.)

See constitution.md for an example based on Social.coop's bylaws.

Documentation

• QUICKSTART.md - Get started quickly with CLI testing
• MASTODON_SETUP.md - Complete Mastodon deployment guide
• PLATFORMS.md - Guide for implementing new platform adapters
• SECURITY.md - Credential management and security best practices
• constitution.md - Example governance constitution

Security Note

Never commit these files (already in .gitignore):

• config/config.yaml - Contains your credentials
• govbot.db - Your governance database
• .env files - Environment variables
• *.token, *.key, *.secret files

See SECURITY.md for complete security guide.

Development Status

This is early-stage software. Current phase: Core infrastructure and agentic reasoning engine.

License

[To be determined]

Contributing

This project is in early development. Contributions and feedback welcome!

For platform developers: See PLATFORMS.md to add support for Discord, Telegram, Matrix, or other platforms.