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.

Key Concept: Govbot uses "process" as the central abstraction - a generic container for any governance activity (proposals, disputes, elections, etc.). Process types are not hard-coded; the LLM interprets your constitution to understand what types exist and how they work.

Features

• Pure LLM-Driven Governance: No hard-coded governance logic - the LLM interprets the constitution and makes all decisions
• Structured Memory System: Tracks governance processes, events, and decisions in a queryable format
• Complete Auditability: Every decision includes reasoning, constitutional citations, and calculation details
• Platform-Agnostic: Same governance logic works across Mastodon, Discord, Telegram, Matrix, and more
• Temporal Awareness: Handles multi-day governance processes with deadlines and reminders

Supported Platforms

• ✅ Mastodon - Full implementation with streaming, admin, and moderation
• ✅ Slack - Channel-scoped governance with Socket Mode
• 🚧 Discord - Coming soon (see PLATFORMS.md)
• 🚧 Telegram - Coming soon
• 🚧 Matrix - Planned

Quick Start

1. Install Dependencies

# Using uv (recommended, faster)
curl -LsSf https://astral.sh/uv/install.sh | sh
uv pip install -e .

# Or using pip
pip install -e .

2. Configure

cp config/config.example.yaml config/config.yaml
nano config/config.yaml  # Edit with your settings

⚠️ IMPORTANT: config/config.yaml contains secrets and is gitignored. Never commit this file.

Configure:

• Platform credentials (Mastodon access tokens, etc.) - See MASTODON_SETUP.md
• AI model (Ollama local models or cloud API keys)
• Constitution path and database location

For cloud models, set API keys:

llm keys set openai      # For OpenAI
llm keys set anthropic   # For Anthropic Claude

3. Run the Bot

# Activate virtual environment (REQUIRED)
source .venv/bin/activate

# Connect to Mastodon (or configured platform)
python -m src.govbot.bot

# Test locally without Mastodon
python -m src.govbot

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

Testing Locally

Test all governance features without connecting to a platform:

source .venv/bin/activate  # Activate virtual environment first
python -m src.govbot

Try these commands:

• constitution - View the constitution
• query What are the rules for creating a proposal? - Ask constitutional questions
• propose We should update the guidelines - Create a test proposal
• processes - Check active processes
• vote 1 agree - Vote on a process
• status 1 - Check process status
• actions - View recent actions

Architecture

The bot uses an LLM agent that:

1. Interprets natural language constitutions via RAG
2. Queries structured memory for governance state
3. Uses deterministic tools for calculations
4. Makes decisions with full reasoning trails
5. Works across any platform via adapters

User Request → Governance Agent (LLM) → Platform Action
               ↓
          Constitution (RAG)
          Memory System
          Audit Trail

For detailed architecture, see ARCHITECTURE.md and ARCHITECTURE_EXAMPLE.md

Constitution Format

Your constitution is a markdown file describing:

• Governance processes (proposals, voting, etc.)
• Decision-making thresholds and member rights
• Administrative procedures and safety mechanisms

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

Publishing Constitution

The bot can publish its constitution as a pinned Mastodon thread with automatic version control:

# Publish or update constitution
python scripts/publish_constitution.py --summary "What changed"

When updated, the bot:

• Adds a deprecation notice to the previous version
• Posts the new version as a thread
• Pins it to the bot's profile
• Maintains a public history of all versions

See CONSTITUTION_PUBLISHING.md for full documentation.

Documentation

Core

• ARCHITECTURE.md - System design and components
• ARCHITECTURE_EXAMPLE.md - Proposal lifecycle walkthrough
• constitution.md - Example governance constitution

Setup

• MASTODON_SETUP.md - Deploy to Mastodon
• SLACK_SETUP.md - Deploy to Slack
• PLATFORMS.md - Add new platform support
• SECURITY.md - Credential management

Templates

• templates/ - Governance models (petition, consensus, do-ocracy, jury, circles)

Contributing

Early-stage project. Contributions welcome!

To add platform support: See PLATFORMS.md

License

[To be determined]