L5 Persona Spec

Design doc reference: section 7 (Digital Staff Training & Promotion)

Purpose

The persona subsystem manages human and digital staff within the lab. Digital members progress through a training pipeline (Intern -> Analyst -> Specialist) based on benchmark performance. Each member has a SOUL.md (identity) and MEMORY.md (accumulated experience) managed via the Tier A memory backend.

Corrections are logged when mistakes are found, and promotion gates enforce minimum competency thresholds before role advancement.

Roles

Defined in MemberRole enum (core/schemas.py):

Role	Type	Description
pi	Human	Principal Investigator
postdoc	Human	Postdoctoral researcher
graduate	Human	Graduate student
undergraduate	Human	Undergraduate student
technician	Human	Lab technician
digital_intern	Digital	Entry-level digital staff
digital_analyst	Digital	Mid-level digital staff
digital_specialist	Digital	Senior digital staff

Pydantic Schemas

All models live in src/labclaw/persona/schemas.py.

MemberProfile

class MemberProfile(BaseModel):
    member_id: str               # uuid4
    name: str
    role: MemberRole
    is_digital: bool
    expertise: list[str]
    created_at: datetime
    promoted_at: datetime | None

BenchmarkResult

class BenchmarkResult(BaseModel):
    member_id: str
    task_type: str
    score: float                 # 0.0 - 1.0
    completed_at: datetime
    details: dict[str, Any]

CorrectionEntry

class CorrectionEntry(BaseModel):
    member_id: str
    category: str
    detail: str
    corrected_by: str
    timestamp: datetime

PromotionGate

class PromotionGate(BaseModel):
    from_role: MemberRole
    to_role: MemberRole
    min_benchmarks: int
    min_avg_score: float
    requires_approval: bool

Promotion Ladder

From	To	Min Benchmarks	Min Avg Score	Requires Approval
digital_intern	digital_analyst	10	0.70	No
digital_analyst	digital_specialist	25	0.85	Yes

Public Interface -- PersonaManager

class PersonaManager:
    def create_member(name: str, role: MemberRole, is_digital: bool) -> MemberProfile
    def get_member(member_id: str) -> MemberProfile
    def record_benchmark(member_id: str, task_type: str, score: float, details: dict | None) -> BenchmarkResult
    def record_correction(member_id: str, category: str, detail: str, corrected_by: str) -> CorrectionEntry
    def check_promotion(member_id: str) -> PromotionGate | None
    def promote(member_id: str, approver: str | None = None) -> MemberProfile
    def demote(member_id: str) -> MemberProfile

Constraints

• promote() / demote() only change digital member roles along the ladder.
• If the matched PromotionGate.requires_approval is True, promote() requires a non-empty approver.
• Human members cannot be demoted below their actual role.
• check_promotion() returns the matching PromotionGate if the member meets all criteria, or None if not eligible.
• demote() raises ValueError for human members or members already at digital_intern.

Events

Event Name	Payload	Emitted When
persona.member.created	member_id, name, role	create_member()
persona.benchmark.recorded	member_id, task_type, score	record_benchmark()
persona.correction.recorded	member_id, category, corrected_by	record_correction()
persona.member.promoted	member_id, from_role, to_role	promote()
persona.member.demoted	member_id, from_role, to_role	demote()

Storage

• In-memory dicts for MVP (no SQLite persistence yet).
• Future: persist via Tier A markdown files and Tier B knowledge graph.