chess-result-analyzer-ollama 0.1.0

OCR and optional Ollama-assisted chess result analyzer

Chess Result Analyzer Ollama

OCR-first chess screenshot analysis with an optional Ollama vision fallback.

Features

• Chess.com mobile and desktop result parsing
• Support for alternative score/result banners like 0-1, 1-0, Black Won, and Game Aborted
• Importable Python API
• Desktop GUI uploader
• Optional Ollama vision refinement for harder screenshots
• Works with local Ollama or hosted Ollama using OLLAMA_API_KEY

Install

pip install chess-result-analyzer-ollama

You also need the native Tesseract executable installed on your machine.

Python Usage

from chess_result_analyzer import OllamaSettings, analyze_chess_result

result = analyze_chess_result(
    "result.png",
    username="isco-olad",
    ollama=OllamaSettings(
        model="gemma3:4b",
        base_url="http://127.0.0.1:11434",
        mode="fallback",
    ),
)

print(result["winner"], result["winner_color"])

Hosted Ollama

For local Ollama, no API key is needed.

For hosted Ollama, set environment variables:

export OLLAMA_BASE_URL="https://ollama.com"
export OLLAMA_API_KEY="your-key"

Then:

import os

from chess_result_analyzer import OllamaSettings, analyze_chess_result

result = analyze_chess_result(
    "result.png",
    ollama=OllamaSettings(
        model="gemma3:4b",
        base_url="https://ollama.com",
        mode="fallback",
        api_key=os.getenv("OLLAMA_API_KEY"),
    ),
)

When api_key is omitted, the CLI and GUI read OLLAMA_API_KEY from the environment.

CLI

chess-analyze --image result.png --username isco-olad
chess-analyze --image result.png --use-ollama --ollama-model gemma3:4b
chess-analyze-gui