# Govbot Architecture

**Current State**: Pure LLM-driven governance with structured memory and strong auditability

## Design Principles

1. **No Hard-Coded Governance Logic**: Constitution defines ALL governance rules in natural language
2. **LLM as Interpreter**: Agent interprets constitution and makes all governance decisions
3. **Structured Memory**: Explicit memory system tracks state and enables LLM reasoning
4. **Tools for Correctness**: LLM uses tools for calculations (not reasoning about math)
5. **Auditability First**: Every decision logged with reasoning and constitutional citation
6. **Human-Readable**: All state and decisions must be inspectable by humans

## Central Concept: Process

The core abstraction in Govbot is the **process** - a generic container for any governance activity that unfolds over time.

**Process Types** (examples, not exhaustive):
- **Proposals**: Seeking decisions on policy, rules, actions
- **Disputes**: Conflict resolution, mediation, arbitration
- **Elections**: Selecting people for roles or responsibilities
- **Discussions**: Facilitated conversations without a specific decision goal
- **Do-ocracy**: Tracking autonomous actions taken by members
- **Reviews**: Evaluating past decisions, actions, or outcomes
- **Juries**: Random selection and deliberation processes
- **Any activity defined in your constitution**

**Why "Process" not "Proposal"?**
- ✅ Generic - doesn't assume voting or decisions
- ✅ Flexible - works for conversations, actions, selections, etc.
- ✅ Temporal - captures activities that unfold over time
- ✅ Minimalist - one concept covers all governance activities

The LLM interprets your constitution to understand what types of processes exist and how they work. No process types are hard-coded.

## Architecture Overview

```
┌─────────────────────────────────────────────┐
│           Governance Request                │
│     (Natural Language from User)            │
└─────────────────┬───────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────┐
│         Governance Agent (LLM)              │
│  • Interprets request                       │
│  • Consults constitution (RAG)              │
│  • Queries memory for context               │
│  • Uses tools for calculations              │
│  • Makes governance decisions               │
│  • Updates memory with reasoning            │
└─────────────────┬───────────────────────────┘
                  │
        ┌─────────┼─────────┐
        │         │         │
        ▼         ▼         ▼
┌─────────┐  ┌────────┐  ┌──────────┐
│ Memory  │  │ Tools  │  │ Audit    │
│ System  │  │        │  │ Trail    │
│         │  │        │  │          │
│ Tracks  │  │ Math   │  │ Explains │
│ State   │  │ Dates  │  │ Decisions│
│ Context │  │ Random │  │ Cites    │
└─────────┘  └────────┘  └──────────┘
```

## Core Components

### 1. Governance Agent (LLM-Driven)

**Role**: Interprets constitution and makes all governance decisions

**Responsibilities**:
- Parse user requests to understand intent
- Query constitution for relevant rules (using RAG)
- Query memory for current state
- Reason about what action to take
- Use tools for deterministic operations
- Update memory with decisions
- Generate audit trail

**Key Feature**: Agent does NOT execute hard-coded logic. Instead:
- Reads constitution to understand rules
- Uses tools to calculate/verify
- Decides based on interpretation

**Implementation**: `src/govbot/agent_refactored.py`

### 2. Structured Memory System

**Role**: Persistent state that LLM can query and update

**What It Tracks**:
- **Processes**: Active governance processes (proposals, disputes, etc.)
- **Events**: Timeline of all governance events
- **Decisions**: Bot decisions with reasoning
- **Participants**: Who's involved in what
- **Context**: Historical information for precedent

**Key Features**:
- **Queryable**: LLM can search memory by criteria
- **Structured**: Not just raw text, but typed records
- **Temporal**: Tracks history and changes over time
- **Human-Readable**: Can be inspected and understood
- **Versioned**: Changes tracked for audit

**Memory Schema**:
```python
ProcessMemory:
    id: str
    type: str  # "proposal", "dispute", "election", etc.
    status: str  # "active", "completed", "cancelled"
    created_at: datetime
    created_by: str
    deadline: Optional[datetime]
    constitution_basis: List[str]  # Article/section citations
    state: Dict[str, Any]  # Flexible process-specific state
    events: List[Event]  # History of what happened
    decisions: List[Decision]  # Bot decisions about this process

Event:
    timestamp: datetime
    actor: str
    event_type: str  # "vote_cast", "proposal_submitted", etc.
    data: Dict[str, Any]
    context: str  # Human description

Decision:
    timestamp: datetime
    decision_type: str  # "threshold_met", "deadline_reached", etc.
    reasoning: str  # LLM's reasoning
    constitution_citations: List[str]
    calculation_used: Optional[str]  # If tool was used
    result: Any
```

**Important**: The `type` field in ProcessMemory is completely flexible - it's not an enum or predefined list. The LLM reads your constitution to understand what process types exist and uses the same terminology. If your constitution mentions "lazy consensus", "sortition", or "restorative circle", those become valid process types. The system doesn't need to know about them in advance.

**Implementation**: `src/govbot/memory.py`

### 3. LLM Tools (Generic Primitives)

**Role**: Deterministic operations the LLM can use

**Why Tools?**
- LLMs are unreliable at arithmetic
- Need deterministic, verifiable results
- Separates "what to do" (LLM) from "how to do it" (tool)

**Available Tools**:
- `calculate(expression, variables)` - Evaluate mathematical expressions safely
- `get_datetime()` - Current time
- `datetime_add(dt, days, hours)` - Date calculations
- `is_past_deadline(deadline)` - Check if deadline passed
- `random_select(items, count)` - Random selection for juries
- `tally(items, key)` - Count votes
- `filter_items(items, criteria)` - Filter data
- `percentage(num, denom)` - Calculate percentages

**Before** (hard-coded):
```python
def check_threshold(counts, "simple_majority") → bool
def check_threshold(counts, "3x_majority") → bool
```

**After** (generic):
```python
def calculate(expression: str, variables: Dict) → Any
# LLM provides: "agree > disagree", {"agree": 10, "disagree": 3}
```

**Implementation**: `src/govbot/tools.py`

### 4. Audit Trail System

**Role**: Human-readable explanation of all decisions

**What It Captures**:
- **Decision**: What was decided
- **Reasoning**: Why (in natural language)
- **Constitutional Basis**: Which articles/sections
- **Calculations**: What math was done
- **Precedent**: Related past decisions
- **Participants**: Who was involved
- **Timeline**: When things happened

**Audit Output Example**:
```markdown
# GOVERNANCE DECISION AUDIT TRAIL

**Decision**: Proposal #23 has passed
**Timestamp**: 2026-02-15 18:00:00 UTC
**Process**: standard_proposal (ID: prop_23)

## Constitutional Basis
- Article 3, Section 3.1: "Standard Proposals address routine governance matters"
- Article 3, Section 3.1: "Passage threshold: More Agree than Disagree votes"

## Calculation
Expression: agree > disagree
Variables: {"agree": 12, "disagree": 3, "abstain": 2, "block": 0}
Result: 12 > 3 = True

## Reasoning
The proposal reached its deadline of Feb 15, 2026 at 18:00 UTC.
According to the constitution, this is a standard proposal requiring
more agree votes than disagree votes. The vote tally shows 12 agree
and 3 disagree, which satisfies the threshold. Therefore, the proposal passes.

## Related Precedent
- Proposal #18 (passed with similar threshold)
- Proposal #21 (failed with 8 agree, 10 disagree)

## Next Actions
- Announce result to community
- Log outcome in governance record
- Execute authorized actions (if any)
```

**Implementation**: `src/govbot/audit.py`

### 5. Constitutional Reasoning (RAG)

**Role**: Retrieval-augmented generation for querying the constitution

**How It Works**:
- Constitution chunked into semantic sections
- Vector embeddings enable similarity search
- LLM retrieves relevant constitutional passages
- Provides context for decision-making

**Implementation**: `src/govbot/governance/constitution.py`

## Complete Workflow Example

See [ARCHITECTURE_EXAMPLE.md](ARCHITECTURE_EXAMPLE.md) for a detailed walkthrough of a complete process lifecycle.

### High-Level Flow (Example: Proposal Process)

This example uses a proposal to illustrate the flow, but the same pattern works for any process type (disputes, elections, discussions, etc.):

```
1. User initiates process (in this case, submitting a proposal)
2. Agent queries constitution: "What rules apply to this process?"
   → Constitution: Standard proposals need 6 days, more agree than disagree
3. Agent queries memory: "What active processes exist?"
   → Memory: 2 active processes currently
4. Agent updates memory:
   - Create process record (type: "proposal")
   - Log "process_initiated" event
   - Calculate deadline using datetime tool
   - Store decision: "Created process based on Article 3.1"
5. Agent announces to user with reasoning
6. [Time passes, users interact with the process]
7. Agent checks deadlines (scheduled task)
8. Agent queries memory: "What processes have reached deadline?"
   → Memory: Process #23 deadline was Feb 15
9. Agent queries memory: "What interactions occurred in process #23?"
   → Memory: 12 agree, 3 disagree, 2 abstain
10. Agent queries constitution: "What's the completion criteria?"
    → Constitution: "More agree than disagree"
11. Agent uses calculate tool: "agree > disagree", {agree: 12, disagree: 3}
    → Tool: True
12. Agent updates memory:
    - Store decision with reasoning
    - Log "process_completed" event
    - Update process status to "completed"
13. Agent generates audit trail
14. Agent announces result with full explanation
```

**Key Point**: The same flow works for any process type. The constitution defines what "initiating", "interacting", and "completing" mean for each process type.

## Key Architecture Differences

| Aspect | Traditional (Hard-Coded) | Current (Agentic) |
|--------|--------------------------|-------------------|
| **Governance Rules** | In Python code | In constitution (natural language) |
| **Thresholds** | 4 fixed types | Any expression interpretable by LLM |
| **State Storage** | Database records | Structured memory |
| **Decision Making** | if/else logic | LLM reasoning with tools |
| **Flexibility** | Requires code changes | Constitution changes only |
| **Auditability** | Code + logs | Natural language reasoning |
| **Process Types** | Pre-defined | Any process type in constitution |
| **Calculations** | Python code | LLM + calculator tool |

## Benefits

### 1. Flexibility
No code changes needed for new governance models. Just update the constitution in natural language to define new process types.

**Example**:
```markdown
## Lazy Consensus Process
Proposals pass unless blocked by 2+ members within 7 days.

## Restorative Circle Process
When harm occurs, affected parties meet with a facilitator to discuss
impact and agree on repairs. Process completes when all parties signal readiness.

## Sortition Selection Process
For jury roles, randomly select 5-7 members from those who opt in.
```

The LLM interprets these rules and handles each process type correctly using the generic tools. No code changes needed.

### 2. Auditability
Every decision includes:
- Natural language reasoning
- Constitutional citations
- Calculation details
- Related precedent

Non-programmers can understand exactly what happened and why.

### 3. Template Support
Works with diverse governance templates:
- ✅ Petition (simple voting)
- ✅ Consensus (blocks, concern resolution)
- ✅ Do-ocracy (authority through action)
- ✅ Jury (random selection, deliberation)
- ✅ Circles (lazy consensus, domains)
- ✅ All 8 dispute resolution processes

The same code handles all templates by interpreting their constitutional rules.

### 4. Transparency
Community members can:
- Read audit trails in plain language
- Verify constitutional citations
- Inspect calculation details
- Review precedent
- Understand bot reasoning

### 5. Community Governance
Communities can amend their governance processes through the governance process itself, without requiring developer involvement.

## File Structure

```
src/govbot/
├── memory.py              # Structured memory system
├── tools.py               # LLM tools for calculations
├── audit.py               # Audit trail generation
├── agent_refactored.py    # LLM-driven agent (current)
├── governance/
│   ├── primitives.py      # Generic platform actions
│   └── constitution.py    # RAG system
└── db/
    ├── models.py          # Database models
    └── queries.py         # Database queries
```

## Considerations

### LLM Reliability
**Challenge**: LLMs can make mistakes or interpret rules inconsistently

**Mitigations**:
- Use tools for all math (not LLM reasoning)
- Require constitutional citations
- Store decisions as precedent
- Enable community review and appeals
- Validate critical decisions

### Cost and Latency
**Challenge**: More LLM calls than hard-coded approach

**Mitigations**:
- Cache constitutional interpretations
- Use faster models for routine tasks
- Batch deadline checks
- Optimize prompts

### Context Window Limits
**Challenge**: Memory can grow large over time

**Mitigations**:
- Hierarchical memory (summary → detail)
- Relevance filtering
- Only include relevant precedent
- Summarize completed processes

## Testing

See implementation files for unit tests:
- `tests/test_memory.py` - Memory operations
- `tests/test_tools.py` - Tool correctness
- `tests/test_audit.py` - Audit generation
- `tests/test_agent.py` - End-to-end workflows

## Success Criteria

✅ **Zero hard-coded governance logic**: No if/else for proposal types, thresholds, etc.

✅ **Constitution is source of truth**: All rules come from constitution text

✅ **LLM makes all decisions**: Agent interprets and decides, not executes programmed routines

✅ **Memory is queryable**: Can ask "what proposals are active?" and get answer

✅ **Audit trail is complete**: Every decision has reasoning + citations

✅ **Human-readable**: Non-programmers can understand what happened and why

✅ **Handles diverse templates**: Works with consensus, do-ocracy, jury, etc.

## Next Steps

Current implementation status:
- ✅ Memory system complete
- ✅ Tools system complete
- ✅ Audit system complete
- 🚧 LLM agent integration in progress
- ⏳ Production deployment pending testing

For implementation details and complete examples, see:
- [ARCHITECTURE_EXAMPLE.md](ARCHITECTURE_EXAMPLE.md) - Complete proposal lifecycle walkthrough
- [constitution.md](constitution.md) - Example governance constitution
- [templates/](templates/) - Governance template examples