Position Evaluator

Daily diagnostic log that classifies your personal decisions into formal chess concepts (Zugzwang, Fork, Zwischenzug, Prophylaxis, Gambit, Overextension, Tempo Loss) using Gemini structured output. Built for the DEV Weekend Challenge: Passion Edition.

Setup

python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

cp .env.example .env
# edit .env: add your GEMINI_API_KEY and MySQL credentials

mysql -u root -p < schema.sql

python app.py
# open http://127.0.0.1:5000

Running tests

# fast, no API calls, safe to run anytime — this is what CI runs on every push
pytest tests/ -k "not eval_set"

# slower, calls the real Gemini API, costs quota — run after editing the
# system prompt in gemini_client.py to check for prompt drift
pytest tests/ -k "eval_set"

.github/workflows/test.yml runs the deterministic tests on every push/PR to main. The Gemini eval-set tests are deliberately excluded from CI. They call a real, paid external API and aren't fully deterministic, so gating every commit on them would make CI flaky and cost money per push. Run those manually when you touch the prompt.

Known limitations

• Single-user only (DEFAULT_USER constant in app.py). No auth.
• Rate limiter in gemini_client.py is per-process, in-memory — not safe across multiple gunicorn workers. Fine for flask run / single-process demo.
• No pagination on /api/entries — fine at hackathon-demo data volumes.
• Exact google-genai exception attribute names (.code on APIError) should be double-checked against your installed SDK version before depending on them beyond this demo, verify with pip show google-genai.
• The duplicate-submit handling in db.insert_entry relies on MySQL/InnoDB allowing a SELECT to run after a caught IntegrityError within the same transaction, without needing an explicit rollback first (this differs from PostgreSQL, where a failed statement aborts the transaction until rolled back). This matches documented InnoDB behavior, but it was not possible to run a real MySQL instance in the sandbox this was built in, test the double-submit path yourself (submit the same text twice for the same day) before treating it as solid.
• True concurrent duplicate submits (two requests for the identical situation text landing at the same instant) have a narrow theoretical race window not fully closed here, irrelevant at single-user hackathon scale, called out for completeness rather than fixed.