Implement LLM-driven governance architecture with structured memory

This commit completes the transition to a pure LLM-driven agentic
governance system with no hard-coded governance logic.

Core Architecture Changes:
- Add structured memory system (memory.py) for tracking governance processes
- Add LLM tools (tools.py) for deterministic operations (math, dates, random)
- Add audit trail system (audit.py) for human-readable decision explanations
- Add LLM-driven agent (agent_refactored.py) that interprets constitution

Documentation:
- Add ARCHITECTURE.md describing process-centric design
- Add ARCHITECTURE_EXAMPLE.md with complete workflow walkthrough
- Update README.md to reflect current LLM-driven architecture
- Simplify constitution.md to benevolent dictator model for testing

Templates:
- Add 8 governance templates (petition, consensus, do-ocracy, jury, etc.)
- Add 8 dispute resolution templates
- All templates work with generic process-based architecture

Key Design Principles:
- "Process" is central abstraction (not "proposal")
- No hard-coded process types or thresholds
- LLM interprets constitution to understand governance rules
- Tools ensure correctness for calculations
- Complete auditability with reasoning and citations

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Nathan Schneider
2026-02-08 14:24:23 -07:00
parent 5fe22060e1
commit bda868cb45
26 changed files with 8683 additions and 187 deletions

View File

@@ -6,21 +6,25 @@ An agentic governance bot for democratic communities that interprets natural lan
Govbot is designed to:
- Read and interpret governance constitutions written in natural language
- Facilitate proposals, voting, and decision-making on social platforms
- 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 actions
- 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
- **Agentic Architecture**: The bot dynamically interprets constitutional rules rather than hard-coding governance procedures
- **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
- **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
@@ -35,26 +39,43 @@ Want to add a platform? See [PLATFORMS.md](PLATFORMS.md) for the implementation
```
┌─────────────────────────────────────────┐
│ Governance Core (Platform-Agnostic)
- Constitutional Reasoning (RAG)
│ - AI Agent & Planning │
│ - Action Primitives │
│ - Temporal Scheduler │
Governance Request
(Natural Language from User)
└────────────────┬────────────────────────┘
┌───────▼───────┐
│ Platform │
│ Adapter │ ← Abstraction layer
└───────┬───────┘
┌─────────────────────────────────────────┐
Governance Agent (LLM) │
• Interprets constitution (RAG) │
│ • Queries structured memory │
│ • Uses tools for calculations │
│ • Makes decisions with reasoning │
│ • Generates audit trails │
└────────────────┬────────────────────────┘
─────────┼─────────
┌────▼────┐┌───▼────┐┌───▼────┐
│Mastodon ││Discord ││Telegram│
Adapter ││ Adapter││ Adapter
└─────────┘└────────┘└────────┘
┌─────────┼─────────┐
│ │ │
▼ ▼ ▼
┌────────┐ ┌──────┐ ┌───────┐
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
@@ -125,11 +146,19 @@ 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
- **[constitution.md](constitution.md)** - Example governance constitution
### Templates
- **[templates/](templates/)** - Governance template library (petition, consensus, do-ocracy, jury, circles, dispute resolution)
## Security