[DomHudson]

Summary

Adds a way to get Maia3's log-probability of given moves in given positions, both from Python and from the command line.

• maia3.scoring.Maia3Scorer: loads a model the same way maia3-uci does (built-in aliases, Hugging Face download, or a local checkpoint). It featurizes positions or whole PGN games and returns batched log-probabilities, with illegal moves masked out.
  • Maia3Scorer.from_pretrained("maia3-5m"), or Maia3Scorer(cfg) with a config from maia3.uci.parse_args.
  • featurize_position(board, moves, self_elo, oppo_elo) takes history from the board's move stack; featurize_game(game, white_elo, black_elo) featurizes every ply of a game.
  • An illegal move raises ValueError; it is not silently scored as -inf.
• maia3-score: scores the moves of PGN games to JSONL or CSV, writing one row per move (game, ply, fen, move, played, self_elo, oppo_elo, logp).
  • --moves all scores every legal move, not just the played one.
  • Elos come from the PGN headers and can be overridden.
  • Model options are passed through unchanged to maia3-uci's option parser.

Defaults that differ from maia3-uci

Both can be switched, and both are documented in the README.

Setting	Scoring default	Matches maia3-uci's default with
History	Real previous positions (as --use-uci-history)	--no-use-history / use_history=False
Precision	fp32	--use-amp / use_amp=True (CUDA only)

Without matching settings, scores won't exactly match the policy that maia3-uci reports for the same position. That's why the README calls this out.

Testing

tests/test_scoring.py uses a small randomly initialized model, so it needs no download. It checks that:

• legal-move probabilities sum to 1;
• results match Maia3UCIEngine's policy in both history modes, which also covers the black-side mirroring;
• scoring a game and scoring its positions one by one agree;
• batch size doesn't change results;
• empty move lists, illegal moves, the row output, and a full CLI run on a saved checkpoint behave correctly.

Also checked by hand with the released 5M model, through both the CLI and the README's Python example. The mixed-precision test needs CUDA and was skipped in CPU-only runs.

Install the test dependency with pip install -e .[test] and run pytest tests.