Personas

Persona lifecycle for consensus-tools — packs, deterministic reputation updates, and respawn with learning.

Overview

@consensus-tools/personas provides the persona lifecycle for consensus-tools: built-in persona packs, a deterministic reputation update engine, and persona respawn when a reviewer's accuracy degrades.

Installation

pnpm add @consensus-tools/personas

Quick start

import { getPersonasByPack, getEvalPersonas, PERSONA_PACKS } from "@consensus-tools/personas";

// Get governance personas (PersonaConfig[])
const voters = getPersonasByPack("governance");

// Get evaluation personas with systemPrompt + evaluationFocus (EvalPersonaConfig[])
const evalPersonas = getEvalPersonas("default", 3);

// List available pack names
console.log(PERSONA_PACKS); // ["default", "skill-review", "governance"]

Persona packs

Three built-in packs of personas ready to use:

Pack	Count	Focus
`default`	3	Security analyst, compliance officer, operations engineer
`skill-review`	5	Specialists for SKILL.md evaluation (doc-architect, api-accuracy, agent-usability, completeness-auditor, style-guardian)
`governance`	5	Lifecycle personas for consensus voting (with reputation)

API reference

Reputation updates

Deterministic reputation engine. Aligned voters gain reputation, misaligned voters lose it, with a confidence penalty boost for high-confidence wrong votes.

import { updateReputation, DEFAULT_RULESET } from "@consensus-tools/personas";

const votes = [
  { persona_id: "security-analyst", vote: "NO", confidence: 0.9 },
  { persona_id: "compliance-officer", vote: "YES", confidence: 0.7 },
];

const result = updateReputation(votes, "BLOCK", voters, DEFAULT_RULESET);
// result.changes: ReputationChange[] — per-persona delta and new reputation

Default ruleset:

Parameter	Value	Effect
`rewardAligned`	+0.02	Aligned with final decision
`penalizeMisaligned`	-0.03	Disagreed with final decision
`highConfidencePenaltyBoost`	-0.02	Extra penalty for confident wrong votes
`minRep`	0.05	Floor — personas are never fully silenced
`maxRep`	0.95	Ceiling

Persona respawn

When a persona's reputation drops too low, analyze its mistakes and create a successor:

import { buildLearningSummary, mutatePersona } from "@consensus-tools/personas";

// Analyze past decisions to find mistake patterns
const learning = buildLearningSummary("security-analyst", decisionHistory);
// learning: { source_decisions: number, mistake_patterns: string[] }

// Create a successor persona informed by learning
const successor = mutatePersona(originalPersona, learning);
// successor: PersonaConfig with updated bias/non_negotiables

ℹ

Automatic respawn in universal

@consensus-tools/universal calls these functions automatically when a persona's reputation drops below respawnThreshold (default 0.15). You only need this package directly if you're managing the persona lifecycle yourself.

Exports reference

Export	Kind	Description
`getPersonasByPack(pack)`	Function	Get lifecycle personas by pack name
`getEvalPersonas(pack, count?)`	Function	Get evaluation personas with prompt fields
`PERSONA_PACKS`	Const	List of available pack names
`updateReputation(votes, truth, voters, ruleset)`	Function	Deterministic reputation update engine
`DEFAULT_RULESET`	Const	Default reputation update rules
`buildLearningSummary(id, history)`	Function	Analyze past decisions for mistake patterns
`mutatePersona(persona, learning)`	Function	Create successor persona from learning
`PersonaConfig`	Type	Base persona (id, name, role, reputation?, bias?)
`EvalPersonaConfig`	Type	Evaluation persona (extends PersonaConfig with systemPrompt, evaluationFocus)
`PersonaSet`	Type	Set of personas with metadata and lineage
`ReputationRuleset`	Type	Configurable reputation update rules
`ReputationChange`	Type	One persona's reputation delta
`ReputationDeltaResult`	Type	Full reputation update result
`LearningSummary`	Type	Learning analysis from decision history
`RespawnResult`	Type	Result of a persona respawn operation

universal -- uses personas for LLM mode deliberation and automatic respawn
evals -- ReputationTracker wraps this engine for A/B eval workflows

Previous←evals Nextstorage→