Open source · engine-grounded chess coach
Lucena
A Socratic chess coach that explains the positions you actually play. Lucena pairs a native SwiftUI macOS client with a Python backend, Stockfish and Maia analysis, and a strict calculate/interpret boundary: the language model can explain grounded facts, but it cannot calculate variations, change the board, or invent application state.
The product problem
Most chess software can tell you the best move. Lucena is built around the more useful question: what did this position demand, what changed after the move, and how do I recognize the pattern in a future game?
That turns a chess explanation into a systems problem. The product has to preserve board truth, distinguish a plan from a mechanism or a static state, and give the model enough grounded material to teach without letting it become the source of truth.
Calculate first, interpret second
The central seam is deliberate: deterministic systems calculate and mutate state; one bounded model generation interprets the resulting fact sheet. The language model never owns the board and never gets to smuggle a plausible-sounding variation into the product as fact.
- Board truth — legal moves, SAN at the product boundary, and deterministic state mutation stay in the application and backend layers.
- Engine grounding — Stockfish supplies calculation while Maia models human move tendencies, giving the coach both strength and human-plausibility signals.
- Structured coaching facts — tactics, plans, mechanisms, drills, and position-to-plan evidence are prepared before the model is asked to explain anything.
- Honest degradation — when the model is unavailable, deterministic facts remain useful instead of the system fabricating confidence.
A stateful native client
The macOS client is SwiftUI over a thin WebSocket and REST protocol. Versioned updates and reconnect-safe command handling keep the board and coaching state coherent while the backend owns the durable conversation loop, persistence, and provider-agnostic model adapter.
That split keeps the native surface responsive and inspectable without turning the client into a second chess engine or the backend into an opaque session blob.
Research as an engineering constraint
The project treats chess plans as measurable objects rather than attractive prose. Candidate detectors are tested against seeded-random baselines, engine lines, Maia rollouts, and external annotated games; negative results are preserved when a concept behaves more like a state or route than an actionable plan.
The product rule that emerged is simple: recommend a move only when the system can state what the move achieves. If there is no grounded why, stay Socratic instead of pretending there is one canonical answer.