Chessmate

Self-hosted chess tutor that blends relational data (PostgreSQL) with vector search (Qdrant) to answer natural-language questions about ~4k annotated games. OCaml powers ingestion, hybrid retrieval, and CLI tooling.

Requirements

• PostgreSQL client (psql) available on the PATH for running migrations and database writes.
• curl (used by the embedding worker to call the OpenAI API).

Features

• Hybrid search: combine OpenAI FEN embeddings with keyword filters for precise tactics or opening questions.
• Structured metadata: Postgres schema stores games, players, positions, and annotations with ECO tags and ratings.
• CLI-first UX: chessmate ingest for PGN ingestion, chessmate query to explore positions via natural language.
• Extensible architecture: modular OCaml library (core/storage/embedding/query) plus an embedding worker scaffold for background vector sync.
• PGN → FEN tooling: dune exec pgn_to_fen -- <game.pgn> prints the FEN after every half-move for quick analysis.

Getting Started

1. Clone and enter the repository.
2. Create an opam switch and install dependencies:

   opam switch create . 5.1.0
   opam install . --deps-only --with-test

3. Launch backing services (Postgres, Qdrant) via Docker:

   docker-compose up -d postgres qdrant

4. Build and run tests:

   dune build
   dune test

5. Try the CLI stubs and worker loop:

   dune exec chessmate -- ingest fixtures/sample.pgn
   dune exec chessmate -- query "Find games with a queenside majority attack"
   OPENAI_API_KEY=dummy DATABASE_URL=postgres://... dune exec embedding_worker
   dune exec pgn_to_fen -- test/fixtures/sample_game.pgn

Repository Structure

lib/            # Core OCaml libraries (core, storage, embedding, query, cli)
bin/            # CLI entry points
scripts/        # Database migrations (`migrate.sh`, `migrations/`, seeds)
services/       # Long-running services (e.g., embedding_worker)
docs/           # Architecture, developer, ops, and planning docs
test/           # Alcotest suites
data/           # Bind-mounted volumes for Postgres and Qdrant

Documentation

• Implementation Plan
• Architecture Overview
• Developer Handbook
• Operations Playbook
• Collaboration Guidelines

Contributing

PRs welcome! See Collaboration Guidelines for coding standards, testing expectations, and PR checklist. Please open an issue before large changes and include dune build && dune test output in your PR template.

License

Distributed under the MIT License.