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