docs/phase_4_evolution.md

Phase 4.3 — Agent evolution

Characters evolve after each match. Same character for everyone (global drift), bounded per match, clamped to identity. Elo is already handled by Phase 4.0b; this phase handles the human-like learning layer on top.

Scope

Five channels, in priority order:

1. Stylistic drift — aggression, risk_tolerance, patience, trash_talk sliders shift a small amount based on match outcome + opponent quality.
2. Opening-book evolution — per-opening score updated by a simple EMA of (opening_played · result_signal). Over time a character favours openings that won and drifts away from openings that lost.
3. Trap memory — pattern-specific counters ("fell for scholar's mate vs. @alice"). Probability of falling again drops but never zeros — humans still slip.
4. Tone drift — confidence/tilt baselines shift over streaks. Not a slider; a bias the Soul sees in its mood state.
5. Hard clamps — a Viktor who loses 50 games in a row can't turn into a pacifist. Sliders cannot drift more than ±2 from base; opening-book weights cannot flip sign on their basis openings.

Invariants

• Private matches skip the whole evolution step (per Phase 4.0b memory). Set once: if match.is_private: return.
• Global, not per-player. One evolution state row per character. Per-player memory (who bullied whom) stays in OpponentProfile and character memories.
• Per-match deltas are small. A single match can only move a slider by ≤ 1 step, a tone baseline by ≤ 0.05, an opening EMA by ≤ 0.1.
• Identity clamps bound cumulative drift. Character's base sliders are the anchor. Cumulative drift is capped at ±2 slider steps from base. The character can change — slowly — but can't become unrecognisable.
• Cadence: every match. Kept batch-friendly so we can flip to "every N matches" later without rewriting the pipeline.

Data model

character_evolution_state — one row per character, lazy-created on first post-match run.

column	type	notes
character_id (PK)	String(36) FK	one row per character
slider_drift	JSON	{aggression, risk_tolerance, patience, trash_talk} — signed deltas from base; bounded [-2, +2]
opening_scores	JSON	{"<opening_label>": float} — EMA-updated result signal in [-1, +1]
trap_memory	JSON	list of {"pattern": str, "fell_for": int, "avoided": int, "last_seen_at": iso}
tone_drift	JSON	{"confidence_baseline": float, "tilt_baseline": float} in [-0.3, +0.3]
matches_processed	int	counter
last_updated_at	datetime
last_match_id	str nullable	for idempotency check — skip if we've already processed this match

Migration 0012_character_evolution_state.

Drift math

Let win_value: +1 on a win (character POV), -1 on loss, 0 on draw. Let opponent_strength: player_elo_at_start / character_elo_at_start (centered around 1.0). Strong opponents amplify drift; weak opponents attenuate it.

signal        = win_value * clamp(opponent_strength, 0.3, 2.0)

Slider drift. Each match picks at most ONE slider to nudge, selected by which one would have helped most given the outcome:

• Lost, played cautiously (avg ACPL < 30) → nudge aggression +0.5.
• Lost, played recklessly (avg ACPL > 80) → nudge patience +0.5.
• Won, opponent higher-rated → nudge confidence in tone (not a slider).
• On tilt (recent loss streak ≥ 3) → nudge trash_talk slightly up or down toward the character's base depending on direction-of-drift.

new_drift = clamp(old_drift + delta, -2.0, +2.0)

Cap: at most one slider updated per match. Delta magnitude ≤ 0.5.

Opening-book EMA. For each opening the character played in the match:

score'       = 0.9 * score_prev  +  0.1 * signal

Only applied to openings in character.opening_preferences or to openings whose score has been built up over ≥ 3 matches.

Trap memory. A "trap" is a sharp loss in ≤ 15 plies, or a loss to a named mating pattern detectable by the analysis step. Detection is cheap: reuse MatchAnalysis.critical_moments — the first critical moment in the first 12 plies with swing ≥ 400cp is tagged as a trap and fed into trap_memory.

if detected_trap(pattern):
    entry = trap_memory[pattern] or new(entry)
    if character_fell: entry.fell_for += 1
    else:              entry.avoided += 1
    entry.last_seen_at = now

A learning Memory row is generated the FIRST time a pattern is seen (narrative: "Last time an opponent tried X, I stepped right into it ..."). Subsequent hits only bump the counter — no new memory row per match (prevents the Subconscious from drowning in redundant copies).

Tone drift. EMA toward current streak:

confidence_baseline'  = 0.95 * confidence_prev + 0.05 * clamp(win_streak / 5, -0.3, +0.3)
tilt_baseline'        = 0.95 * tilt_prev       + 0.05 * clamp(-loss_streak / 5, -0.3, +0.3)

Applied every match. Fed to the Soul as an additive nudge on the initial MoodState before each turn.

Pipeline

Added as a new step after elo_ratchet, before memory_generation in app/post_match/processor.py. That way generated memories can reference newly-detected traps.

engine_analysis → feature_extraction → elo_ratchet
  → evolution                ← NEW
  → memory_generation → narrative_summary

Contract: apply_evolution(session, match, analysis) — raises on programmer errors, swallows LLM errors (shouldn't invoke LLM anyway — the hook is pure data). Idempotent via last_match_id guard.

Integration with Subconscious

• Learned memories from trap memory use a new MemoryType.LEARNING scope. They enter the normal vector-retrieval flow; the Subconscious doesn't need changes.
• Tone drift is read at Soul call time — _build_soul_input adds tone_drift to the mood parameter before passing to the Soul. No Soul-side changes needed.
• Slider drift is read whenever the Director builds the engine config and whenever the style prompt is rendered. Effective slider = character.slider + drift.

Private-match exclusion

At entry: if match.is_private: return — no state read, no state write, no memory generation of learned entries. Logged at INFO so a demo can grep evolution.log to verify the guardrail is working.

Testing

• Unit tests per math function (slider delta selection, opening EMA step, trap detection, tone EMA, clamps).
• Integration test — simulate a 50-match burst against a fixed opponent profile and assert cumulative drift stays in bounds.
• Private-match test — confirm apply_evolution is a no-op on match.is_private = True.
• Idempotency test — re-running the pipeline on the same match doesn't double-apply drift.

What this phase does NOT do

• Does not build a multi-player personality model (global only).
• Does not feed PvP matches into evolution (only PvE — characters are PvE only; PvP is player-vs-player).
• Does not build a UI for viewing a character's drift. Phase 4.5 polish pass adds a read-only "this character has learned…" panel on the detail page if there's time.