agentic-govbot/README.md

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

## Quick Start

### 1. Install Dependencies (above)

### 2. Configure (Credentials Required)

```bash
# Copy the template
cp config/config.example.yaml config/config.yaml

# Edit with your credentials
nano config/config.yaml
```

**⚠️ IMPORTANT**: `config/config.yaml` contains your secrets and is automatically ignored by git. 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)

```bash
# For OpenAI
llm keys set openai

# For Anthropic Claude
llm keys set anthropic
```

These are stored securely in `~/.llm/keys.json` (also gitignored)

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

## Documentation

- **[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
- **[constitution.md](constitution.md)** - Example governance constitution

## Security

⚠️ **Important**: Never commit `config/config.yaml` or other files containing credentials. All sensitive files are automatically protected by `.gitignore`.

**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.

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