AILED — Psyche & Personality System for Chess Engines

Architecture-agnostic middleware that gives any chess engine an emotional state.

A continuous psyche score (ψ ∈ [−100, +100]) tracks position quality move-by-move and drives a five-stage audio-inspired signal chain that reshapes the engine's move probability distribution — without any search, tree traversal, or model retraining.

Works as a drop-in layer on top of any move predictor that outputs logits or probabilities: Maia2, Stockfish NNUE policy heads, or your own transformer.

This module is a partial release accompanying the research paper: "Ailed: A Psyche-Driven Chess Engine with Dynamic Emotional Modulation"

What It Does

Psyche System

The PsycheCalculator evaluates the board position after every move across five factors:

These are combined, tanh-compressed to [−100, +100], and blended into the running psyche state with configurable reactivity, phase-awareness (opening/middlegame/endgame), sacrifice dampening, and daily decay toward neutral.

Game Phase Detection

Phase is detected per move and controls reactivity scaling (opening = dampened, middlegame = baseline, endgame = strongly dampened / freeze-biased by default, all configurable via PsycheConfig):

Endgame takes priority. The opening threshold prevents damped reactivity from masking rapid early collapses — gambits, sacrifices, or early trades that lose 6+ points of material (≈ two minor pieces) exit opening phase immediately, even before move 15. Both thresholds are configurable via PsycheConfig:

from ailed.psyche.config import PsycheConfig

config = PsycheConfig(
    opening_move_limit=15,               # fullmove limit for opening phase
    opening_material_loss_threshold=6,   # points lost to exit opening early (default: 6)
    endgame_material_threshold=13,       # total material to enter endgame
)

from ailed.psyche import PsycheCalculator
import chess

calc = PsycheCalculator()          # default config
board = chess.Board()
psyche = 0.0                       # neutral at game start

board.push_san("e4")
psyche = calc.update_psyche(psyche, board)
print(f"ψ = {psyche:.1f}")        # e.g. ψ = 3.2

EQ Signal Chain

MoveSelector applies a full audio-inspired signal chain to the move probability distribution:

Softmax → Noise gate → Dynamics → Sort + EQ bands → Saturation → Renormalize → Sample

1. Noise gate — silences moves below probability threshold
2. Dynamics — compressor/expander on probability spread
3. EQ bands — moves sorted into 5 quality bands, each with gain multiplier
4. Saturation — soft-clips dominant moves
5. Renormalize — produces valid distribution

All five parameters interpolate across N psyche anchors. At ψ = −70 (stressed) behavior differs dramatically from ψ = +70 (overconfident).

from ailed.uci.move_selector import MoveSelector
from ailed.uci.eq_curve import PRESETS
import torch, chess

selector = MoveSelector(curve=PRESETS["human"])
board = chess.Board()
legal_moves = list(board.legal_moves)
logits = torch.randn(len(legal_moves))

move = selector.select_move(
    legal_moves=legal_moves,
    move_logits=logits,
    base_confidence=0.8,
    psyche=-40.0,
)

Six Built-in Personalities

Installation

Requires Python 3.11+.

pip install chess pydantic torch
git clone https://github.com/chrnx-dev/ailed-chess
cd ailed-chess
pip install -e .

Reproduce Core Checks

Run the package tests exactly as used for release readiness:

pytest -q

Minimal sanity check of psyche + selector behavior:

python - <<'PY'
import chess
import torch
from ailed.psyche import PsycheCalculator
from ailed.uci.move_selector import MoveSelector

board = chess.Board()
board.push_san("e4")

calc = PsycheCalculator()
psi = calc.update_psyche(0.0, board)

selector = MoveSelector()
legal = list(board.legal_moves)
logits = torch.randn(len(legal))
move = selector.select_move(legal_moves=legal, move_logits=logits, base_confidence=0.8, psyche=psi)

print(f"psyche={psi:.2f}, selected={move.uci()}")
PY

Architecture Agnosticism

Works on top of any move predictor that outputs logits or probabilities:

• Maia2 (convert probability dict to log-probs)
• Stockfish NNUE policy head
• Your custom transformer
• Any neural network with move output

The paper demonstrates this across two engines of vastly different scale (60K-game model vs 169M-game Maia2), showing consistent behavioral signatures from psyche regardless of base model.

What Is NOT Included

This repository contains only the psyche and personality modules.

Full AILED system (released with paper) includes:

• Move predictor (23.5M param transformer)
• Training pipeline
• Lichess bot deployment
• Web dashboard
• Nightly study loop
• Terminal UI

Community

AI-generated contributions are welcome. Contributors are responsible for understanding and testing their code. Changes to critical paths (psyche math, phase detection, EQ signal chain) may require human validation before merge — see CONTRIBUTING.md for details.

Citation

Please cite both:

• the software release (preferred via GitHub citation tools / CITATION.cff)
• the arXiv paper once public

@misc{ailed2026,
  title={Ailed: A Psyche-Driven Chess Engine with Dynamic Emotional Modulation},
  author={Resendez Prado, Diego Armando},
  year={2026},
  eprint={TBD},
  archivePrefix={arXiv},
  primaryClass={cs.AI}
}

License

Apache 2.0 — see LICENSE.