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:
71
README.md
71
README.md
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user