Modpol/agentic-govbot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add Slack platform adapter and comprehensive platform skills system

Browse Source 
Major Features:
- Implemented full Slack channel-bot adapter with Socket Mode
- Added 35+ Mastodon platform skills across 7 categories
- Created constitution publishing system for Mastodon

Slack Adapter (NEW):
- Full PlatformAdapter implementation (1071 lines)
- Socket Mode for real-time events
- 16 channel-scoped governance skills
- User group management as channel "roles"
- Channel access control and management
- Message pinning and moderation
- Platform limitations documentation
- Comprehensive setup guide (SLACK_SETUP.md)

Mastodon Platform Skills (ENHANCED):
- Account Moderation (9 skills): suspend, silence, disable, mark sensitive, delete status
- Account Management (4 skills): approve, reject, delete data, create account
- Report Management (4 skills): assign, unassign, resolve, reopen
- Federation Management (4 skills): block/unblock domains, allow/disallow federation
- Security Management (4 skills): block IP/email domains
- Constitution Management (2 skills): publish constitution, update profile
- Documented web-only limitations (role management requires tootctl)

Constitution Publishing:
- Publish constitution as pinned Mastodon thread
- Automatic deprecation of previous versions
- Version control with change summaries
- Thread splitting for long documents
- CLI tool: scripts/publish_constitution.py
- Documentation: CONSTITUTION_PUBLISHING.md

Configuration & Integration:
- Added SlackConfig model with bot_token, app_token, channel_id
- Updated PlatformConfig to support type: slack
- Added slack-sdk>=3.33.0 dependency
- Bot.py now routes to Slack adapter
- Updated example config with Slack section

Documentation:
- SLACK_SETUP.md: Complete Slack setup guide
- PLATFORM_SKILLS.md: All 35+ Mastodon skills documented
- CONSTITUTION_PUBLISHING.md: Constitution publishing guide
- Updated README.md: Merged QUICKSTART, added Slack to supported platforms
- Updated PLATFORMS.md: Slack marked as implemented with examples
- Updated .gitignore: Added instance-specific state files

Security:
- All sensitive files properly gitignored
- Instance-specific state (.constitution_post_id) excluded
- Credentials properly handled in config

Breaking Changes: None

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Nathan Schneider
2026-02-10 22:46:48 -07:00
parent a0785f09cf
commit 54beddb420
16 changed files with 3675 additions and 489 deletions
Download Patch File Download Diff File Expand all files Collapse all files

228
README.md
View File

@@ -2,184 +2,158 @@
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](PLATFORMS.md) for implementation guide)
- ✅ **Slack** - Channel-scoped governance with Socket Mode
- 🚧 **Discord** - Coming soon (see [PLATFORMS.md](PLATFORMS.md))
- 🚧 **Telegram** - Coming soon
- 🚧 **Matrix** - Planned
Want to add a platform? See [PLATFORMS.md](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](ARCHITECTURE.md).
## Installation
```bash
# 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)
### 1. Install Dependencies
```bash
# Copy the template
cp config/config.example.yaml config/config.yaml
# Using uv (recommended, faster)
curl -LsSf https://astral.sh/uv/install.sh | sh
uv pip install -e .
# Edit with your credentials
nano config/config.yaml
# Or using pip
pip install -e .
```
**⚠️ IMPORTANT**: `config/config.yaml` contains your secrets and is automatically ignored by git. Never commit this file.
### 2. Configure
```bash
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, 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](MASTODON_SETUP.md)
- **Security**: See [SECURITY.md](SECURITY.md) for credential management
### 3. Set AI API Keys (if using cloud models)
- **Platform credentials** (Mastodon access tokens, etc.) - See [MASTODON_SETUP.md](MASTODON_SETUP.md)
- **AI model** (Ollama local models or cloud API keys)
- **Constitution path** and database location
For cloud models, set API keys:
```bash
# For OpenAI
llm keys set openai
# For Anthropic Claude
llm keys set anthropic
llm keys set openai # For OpenAI
llm keys set anthropic # For Anthropic Claude
```
These are stored securely in `~/.llm/keys.json` (also gitignored)
## Usage
### 3. Run the Bot
```bash
# 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:
```bash
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](ARCHITECTURE.md) and [ARCHITECTURE_EXAMPLE.md](ARCHITECTURE_EXAMPLE.md)
## Constitution Format
Your constitution should be a markdown file that describes:
Your constitution is a markdown file describing:
- Governance processes (proposals, voting, etc.)
- Decision-making thresholds
- Member rights and responsibilities
- Administrative procedures
- Safety mechanisms (veto, appeals, 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:
```bash
# 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](CONSTITUTION_PUBLISHING.md) for full documentation.
## Documentation
### Core Documentation
- **[ARCHITECTURE.md](ARCHITECTURE.md)** - System architecture with LLM, memory, tools, and audit trail
- **[ARCHITECTURE_EXAMPLE.md](ARCHITECTURE_EXAMPLE.md)** - Complete walkthrough of a proposal lifecycle
- **[constitution.md](constitution.md)** - Example governance constitution
**Core**
- [ARCHITECTURE.md](ARCHITECTURE.md) - System design and components
- [ARCHITECTURE_EXAMPLE.md](ARCHITECTURE_EXAMPLE.md) - Proposal lifecycle walkthrough
- [constitution.md](constitution.md) - Example governance constitution
### Setup Guides
- **[QUICKSTART.md](QUICKSTART.md)** - Get started quickly with CLI testing
- **[MASTODON_SETUP.md](MASTODON_SETUP.md)** - Complete Mastodon deployment guide
- **[PLATFORMS.md](PLATFORMS.md)** - Guide for implementing new platform adapters
- **[SECURITY.md](SECURITY.md)** - Credential management and security best practices
**Setup**
- [MASTODON_SETUP.md](MASTODON_SETUP.md) - Deploy to Mastodon
- [SLACK_SETUP.md](SLACK_SETUP.md) - Deploy to Slack
- [PLATFORMS.md](PLATFORMS.md) - Add new platform support
- [SECURITY.md](SECURITY.md) - Credential management
### Templates
- **[templates/](templates/)** - Governance template library (petition, consensus, do-ocracy, jury, circles, dispute resolution)
**Templates**
- [templates/](templates/) - Governance models (petition, consensus, do-ocracy, jury, circles)
## Security
## Contributing
⚠️ **Important**: Never commit `config/config.yaml` or other files containing credentials. All sensitive files are automatically protected by `.gitignore`.
Early-stage project. Contributions welcome!
**See [SECURITY.md](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.
To add platform support: See [PLATFORMS.md](PLATFORMS.md)
## License
[To be determined]
## Contributing
This project is in early development. Contributions and feedback welcome!
**For platform developers**: See [PLATFORMS.md](PLATFORMS.md) to add support for Discord, Telegram, Matrix, or other platforms.