fbc37ecb8f
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>
108 lines
3.9 KiB
Markdown
108 lines
3.9 KiB
Markdown
# 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](PLATFORMS.md) for implementation guide)
|
|
- 🚧 **Telegram** - Coming soon
|
|
- 🚧 **Matrix** - Planned
|
|
|
|
Want to add a platform? See [PLATFORMS.md](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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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!
|