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]"

Configuration

1. Copy config/config.example.yaml to config/config.yaml
2. Edit with your settings:
   • Mastodon instance URL and credentials
   • AI model preferences (local/cloud)
   • Path to your constitution file

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.

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!