# 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!