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 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)
- 🚧 **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)

```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

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

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

### Templates
- **[templates/](templates/)** - Governance template library (petition, consensus, do-ocracy, jury, circles, dispute resolution)

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