Skip to main content

Chess Opening Assistant for the French Chess Federation

Chess opening assistant logo

Context. The French Chess Federation (FFE) trains young competitive players, for whom opening study is the most structured part of early progress. The brief asked for a conversational assistant covering that ground: given a board position, surface the moves master play actually supports, and fall back on engine evaluation when theory runs out. I built the proof of concept end to end as sole engineer between May and June 2026, backend, retrieval layer, frontend and packaging.

Problem. The specification described the behaviour as a conditional pipeline: query the Lichess Opening Explorer for a given FEN, and if it returns nothing, call Stockfish. Implemented literally, that is an if/else with a language model attached to the end of it. The routing decision lives in Python, which has two consequences. Any question the branch did not anticipate has nowhere to go: the history of an opening, a request for a video tutorial, a question about chess in general. And the system cannot recover from a situation its author did not foresee, because recovery is exactly what the branch encodes. For a product whose users are children asking open questions, that ceiling is low and it is reached immediately.

Constraints. The audience set the register: French throughout, French algebraic notation, a coaching tone that pushes the player to think rather than handing over answers. The four knowledge sources are heterogeneous, an HTTP API with rate limits, a local engine binary, a vector store, and a quota-bounded Google API, so failure handling could not be uniform. The stack had to run on a developer machine with 8 GB of available RAM, which put Milvus and a multilingual embedding model in direct competition for memory. And the deviation from the specified architecture had to be defended on its merits, not adopted because it was more interesting: it was documented and reviewed before implementation, not after.

Approach. I replaced the conditional pipeline with a ReAct agent built on LangGraph, in which the language model selects its own tools according to the question and the current position, with no routing logic in Python at all. Four tools are exposed: get_opening_moves over the Lichess masters database, get_position_evaluation over Stockfish at depth 15, search_chess_knowledge over a Milvus RAG built from ten curated Wikichess articles with BGE-M3 multilingual embeddings and an HNSW cosine index, and find_videos over YouTube Data v3. Three decisions carry the architecture. Tools return structured JSON rather than pre-formatted prose, so the model owns the phrasing and the data layer stays reusable. Tool docstrings are written as routing instructions rather than passive documentation, since they are the only thing the model has to discriminate between two sources that both answer questions about a position. And the masters-only fallback is deliberately not coded: rather than querying a broader Lichess database when the masters base returns nothing, the tool returns the empty result and the model is left to notice it. Around that core sit the parts that are not novel but decide whether the thing runs: Pydantic FEN validation on both position tools, a bounded ReAct loop at a recursion limit of 10, an error contract separating runtime tool failures from missing configuration, FastAPI endpoints with MongoDB logging of every interaction, an Angular front end with a synchronised board, and Docker Compose orchestration with health checks and conditional startup.

Diagram of the ReAct agent loop

Result. I evaluated the agent by scenario rather than by metric, with nine documented cases across two milestones, each recording the expected tool sequence against the observed one. The decisive case is a rare Sicilian line absent from the masters database. The model calls Lichess, receives opening: null and an empty move list, states that the position is not in the masters database, then calls Stockfish on its own initiative, which returns an evaluation of +4.39 and the move cxd4. No branch in Python produced that fallback: the model connected an empty result from one tool to the use case described in another tool's docstring. That is the behaviour the specified architecture could not have exhibited, and it is the reason the deviation was worth defending. With all four tools connected, arbitration held across every scenario tested, including two that were not designed to succeed: an ambiguous request to learn the Sicilian, where the agent chose to combine theory retrieval and video search rather than pick one, and an out-of-scope question about the weather, where it called no tool and redirected the user. The project also produced a feasibility study for a separate MCP server indexing video tutorials by board position, costed at 8 to 12 person-days of build and 10 to 30 dollars a month of operation, with a make-or-buy comparison on the vision component and a roadmap ordered by dependency rather than by appeal.

Limits. The hard-coded routing I removed from Python partly reappeared in the system prompt, which instructs the agent to pass any supplied FEN to both position tools. Two tests confirm it works and it contradicts the architecture it sits inside. I logged it as an open point rather than correcting it, and it is the first thing I would change. The agent does not filter tool output: asked for a single video tutorial it relayed the three the tool returns by default, since the constraint was expressed to the model and enforced nowhere. On an open middlegame question it called both position tools in parallel where the engine alone would have answered, which is defensible but wasteful. More broadly, the evaluation establishes that arbitration works on the cases tested, not how often it works: nine scenarios, one evaluator, no repeated runs, and a temperature of zero that suppresses variance rather than measuring it. Retrieval quality was never assessed independently of the agent, and the knowledge base is ten articles. There is no CI pipeline and deployment is a manual compose command. Finally, no young player from the federation ever used the system: its pedagogical value is asserted by the system prompt and remains unmeasured.

Repository. https://github.com/Jojo4911/chess-ai-agent

← Back to Projects