54beddb420
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>
160 lines
5.0 KiB
Markdown
160 lines
5.0 KiB
Markdown
# 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](PLATFORMS.md))
|
|
- 🚧 **Telegram** - Coming soon
|
|
- 🚧 **Matrix** - Planned
|
|
|
|
## Quick Start
|
|
|
|
### 1. Install Dependencies
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```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, 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
|
|
llm keys set openai # For OpenAI
|
|
llm keys set anthropic # For Anthropic Claude
|
|
```
|
|
|
|
### 3. Run the Bot
|
|
|
|
```bash
|
|
# 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 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:
|
|
|
|
```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**
|
|
- [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**
|
|
- [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 models (petition, consensus, do-ocracy, jury, circles)
|
|
|
|
## Contributing
|
|
|
|
Early-stage project. Contributions welcome!
|
|
|
|
To add platform support: See [PLATFORMS.md](PLATFORMS.md)
|
|
|
|
## License
|
|
|
|
[To be determined]
|