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 any governance process defined in your constitution (proposals, disputes, elections, discussions, etc.)
• Execute administrative actions based on constitutional rules
• Maintain an audit trail of all governance activities
• Support both local (Ollama) and cloud AI models
• Work across multiple platforms (Mastodon, Discord, Telegram, etc.)

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
• LLM Tools for Correctness: Deterministic tools for math, dates, and random selection ensure reliability
• Complete Auditability: Every decision includes reasoning, constitutional citations, and calculation details
• RAG-based Constitutional Reasoning: Uses retrieval-augmented generation to understand and apply governance rules
• Template Flexibility: Works with diverse governance models (petition, consensus, do-ocracy, jury, circles)
• 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

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 Request              │
│    (Natural Language from User)         │
└────────────────┬────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────┐
│       Governance Agent (LLM)            │
│  • Interprets constitution (RAG)        │
│  • Queries structured memory            │
│  • Uses tools for calculations          │
│  • Makes decisions with reasoning       │
│  • Generates audit trails               │
└────────────────┬────────────────────────┘
                 │
       ┌─────────┼─────────┐
       │         │         │
       ▼         ▼         ▼
  ┌────────┐ ┌──────┐ ┌───────┐
  │ Memory │ │Tools │ │ Audit │
  │ System │ │      │ │ Trail │
  └────┬───┘ └──────┘ └───────┘
       │
       ▼
┌──────────────────────────────┐
│   Platform Adapter Layer     │
└──────────┬───────────────────┘
           │
  ┌────────┼────────┐
  │        │        │
┌─▼──┐  ┌─▼──┐  ┌─▼──┐
│Mast││Disc││Tele│
│odon││ord ││gram│
└────┘  └────┘  └────┘

For detailed architecture documentation, see ARCHITECTURE.md.

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

Core Documentation

• ARCHITECTURE.md - System architecture with LLM, memory, tools, and audit trail
• ARCHITECTURE_EXAMPLE.md - Complete walkthrough of a proposal lifecycle
• constitution.md - Example governance constitution

Setup Guides

• 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

Templates

• templates/ - Governance template library (petition, consensus, do-ocracy, jury, circles, dispute resolution)

Security

⚠️ Important: Never commit config/config.yaml or other files containing credentials. All sensitive files are automatically protected by .gitignore.

See SECURITY.md for:

• Complete list of protected files
• Where to store credentials
• Best practices for development and production
• What to do if secrets are accidentally committed

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.