Insert human readable commentary

[Entze]

Lichess adds human readable comments after inaccuracies (dubious you called them), mistakes and blunders, and suggests alternative move-sequences. For example the following pgn got annotated like this:

[Result "1-0"]

1. e4 e5 2. Nf3 Nc6 3. Bb5 Nd4 4. Bc4 Nf6
5. c3 Nc6 6. d3 d5 7. Bb5 dxe4 8. Nxe5 Qd5
9. Bxc6+ bxc6 10. Bf4 Bd6 11. d4 Bg4 12. c4 Qa5+
13. Qd2 Qxd2+ 14. Nxd2 Nh5 15. g3 Rb8 16. f3 exf3
17. Ndxf3 Rxb2 18. O-O c5 19. Nxg4 Nxf4 20. gxf4 Bxf4
21. Rfe1+ Kd7 22. dxc5 f6 23. Red1+ Kc6 24. Rd5 h5
25. Nd4+ Kb7 26. c6+ Kc8 27. Nf2 Be3 28. Rf1 g5
29. h3 g4 30. hxg4 hxg4 31. Rf5 g3 32. Kg2 gxf2
33. Nb5 Rg8+ 34. Kf3 Bd4 35. Nxd4 Rg1 36. Rxf2 1-0

Annotated:

[Site "https://lichess.org/sugtc1iC"]
[Round "1"]
[Result "1-0"]
[Variant "Standard"]
[TimeControl "-"]
[ECO "C61"]
[Opening "Ruy Lopez: Bird Variation"]
[Termination "Normal"]
[Annotator "lichess.org"]

1. e4 e5 2. Nf3 Nc6 3. Bb5 Nd4 { C61 Ruy Lopez: Bird Variation } 4. Bc4 Nf6 5. c3 Nc6?! { (0.08 → 0.97) Inaccuracy. Best move was Nxf3+. } (5... Nxf3+ 6. Qxf3 c6 7. O-O d5 8. exd5 cxd5 9. Bb5+ Bd7 10. Bxd7+) 
6. d3?! { (0.97 → 0.45) Inaccuracy. Best move was Ng5. } (6. Ng5 d5 7. exd5 Nxd5 8. d4 Be6 9. O-O Be7 10. Nxe6 fxe6) 6... d5?! { (0.45 → 1.08) Inaccuracy. Best move was Be7. } (6... Be7 7. O-O O-O 8. Re1 d6 9. b4 a6 10. a4 d5 11. exd5) 7. Bb5? { (1.08 → -0.73) Mistake. Best move was exd5. } (7. exd5 Nxd5 8. Qb3 Na5 9. Qa4+ Nc6 10. Nxe5 Qe7 11. Bxd5 Qxe5+ 12. Qe4 Bd6 13. d4 Qxe4+) 7... dxe4 8. Nxe5 Qd5 9. Bxc6+ bxc6 10. Bf4 Bd6 
11. d4 Bg4? { (-0.89 → 0.53) Mistake. Best move was Ba6. } (11... Ba6) 12. c4? { (0.53 → -1.02) Mistake. Best move was Nxg4. } (12. Nxg4 Bxf4 13. Nxf6+ gxf6 14. O-O f5 15. Qe2 O-O 16. Nd2 c5 17. Nb3 cxd4 18. Nxd4 c5) 12... Qa5+? { (-1.02 → 0.60) Mistake. Best move was Bxd1. } (12... Bxd1 13. cxd5 Nxd5 14. Bd2 f6 15. Nc3 Nxc3 16. Bxc3 Ba4 17. b3 Bb5 18. Nc4 Kf7 19. O-O) 13. Qd2?! { (0.60 → -0.02) Inaccuracy. Best move was Bd2. } (13. Bd2 Bxd1 14. Bxa5 Bc2 15. Nxc6 Kd7 16. Na3 Bd3 17. Nb4 Bxb4+ 18. Bxb4 c6 19. Bc3 Rhe8) 13... Qxd2+ 14. Nxd2 Nh5? { (0.04 → 1.07) Mistake. Best move was O-O. } (14... O-O 15. O-O Rfe8 16. Rae1 Bf5 17. c5 Bxe5 18. Bxe5 Nd5 19. Nc4 f6 20. Bg3 Rac8 21. Ne3) 
15. g3? { (1.07 → -0.11) Mistake. Best move was Be3. } (15. Be3 Be6) 15... Rb8? { (-0.11 → 2.74) Mistake. Best move was Nxf4. } (15... Nxf4 16. Nxg4 f5 17. Ne3 Nd3+ 18. Ke2 O-O 19. f3 c5 20. fxe4 cxd4 21. Nxf5 Nxb2 22. Nxd6) 
16. f3?? { (2.74 → -0.35) Blunder. Best move was Nxg4. } (16. Nxg4 Nxf4 17. gxf4 Rxb2 18. f5 O-O 19. Nxe4 Re8 20. f3 Bf4 21. Ne5 Bxe5 22. dxe5 Rxe5) 16... exf3? { (-0.35 → 1.93) Mistake. Best move was Nxf4. } (16... Nxf4 17. Nxg4 Ne6 18. fxe4 Nxd4 19. O-O-O O-O 20. Rhf1 Rfe8 21. Nf2 a5 22. Nd3 a4 23. Kb1) 
17. Ndxf3?? { (1.93 → -1.90) Blunder. Best move was Nxg4. } (17. Nxg4 Nxf4 18. gxf4 Rxb2 19. Nxf3 f6 20. O-O Kd7 21. Nf2 Rb4 22. Rfc1 Bxf4 23. Rc3 Ra4) 17... Rxb2?? { (-1.90 → 1.51) Blunder. Best move was Bxf3. } (17... Bxf3 18. Nxf3 Nxf4 19. gxf4 Rxb2 20. Ne5 Bxe5 21. dxe5 Ke7 22. O-O g6 23. Rab1 Rhb8 24. Rxb2) 
18. O-O? { (1.51 → -0.58) Mistake. Best move was Nxg4. } (18. Nxg4 Bxf4 19. gxf4 O-O 20. Nge5 Nxf4 21. O-O c5 22. Nd7 Re8 23. Nxc5 Ree2 24. Kh1 f6) 
18... c5?? { (-0.58 → 2.51) Blunder. Best move was Bxf3. } (18... Bxf3 19. Rxf3 Nxf4 20. gxf4 Bxe5 21. fxe5 Rf8 22. Rh3 h6 23. Rg3 Rd2 24. Rxg7 Rxd4 25. Re1) 19. Nxg4?! { (2.51 → 1.92) Inaccuracy. Best move was Bc1. } (19. Bc1 Rb4 20. Nxg4 O-O 21. dxc5 Bxc5+ 22. Be3 Bd6 23. Nd2 f5 24. Nf2 Ra4 25. Nd3 Re8) 19... Nxf4 20. gxf4 Bxf4? { (2.02 → 4.21) Mistake. Best move was O-O. } (20... O-O 21. Nge5) 21. Rfe1+? { (4.21 → 2.62) Mistake. Best move was Rae1+. } (21. Rae1+) 21... Kd7?! { (2.62 → 3.48) Inaccuracy. Best move was Kf8. } (21... Kf8) 22. dxc5?! { (3.48 → 2.92) Inaccuracy. Best move was Re4. } (22. Re4) 22... f6?! { (2.92 → 3.69) Inaccuracy. Best move was Kc8. } (22... Kc8 23. Re7 h5 24. Nge5 Be3+ 25. Kh1 Bxc5 
26. Rxf7 Bd6 27. Rxg7 Re8 28. Rg5 Bxe5 29. Nxe5) 
23. Red1+? { (3.69 → 2.45) Mistake. Best move was Re4. } (23. Re4 g5) 23... Kc6 24. Rd5? { (2.65 → 1.42) Mistake. Best move was Nd4+. } (24. Nd4+ Kd7 25. Rab1 Rxb1 26. Rxb1 h5 27. Nf2 Re8 28. Kg2 Be5 29. c6+ Kd6 30. Ne4+ Ke7) 24... h5 25. Nd4+ Kb7 26. c6+ Kc8? { (1.52 → 2.71) Mistake. Best move was Kb6. } (26... Kb6) 27. Nf2? { (2.71 → 1.41) Mistake. Best move was Rf1. } (27. Rf1 Bd6 28. Nf2 Rd8 29. Ne6 Re8 30. Rxh5 g6 31. Rh6 Rxa2 32. c5 Be7 33. Rxg6 Re2) 
27... Be3 28. Rf1 g5?? { (1.44 → 4.67) Blunder. Best move was g6. } (28... g6 29. Rd7 Re8 30. Nb5 Bb6 31. Nd4 Rxa2 32. Rd1 Bxd4 33. R1xd4 Ra1+ 34. Kg2 Ra6 35. Rg7) 29. h3? { (4.67 → 1.74) Mistake. Best move was Nf5. } (29. Nf5 Bxf2+ 30. Rxf2 Rb1+ 31. Kg2 Kb8 32. Ne7 h4 33. Rd7 f5 34. Rxf5 a6 35. Rxg5 h3+) 
29... g4? { (1.74 → 4.30) Mistake. Best move was Rd8. } (29... Rd8 30. Nf5 Rxd5 31. cxd5 Bc5 32. a4 Kd8 33. Kg2 Bb6 34. a5 Bxa5 35. Ng7 Ke7 36. Kf3) 
30. hxg4? { (4.30 → 2.67) Mistake. Best move was Nf5. } (30. Nf5 Re2 31. Nxe3 Rxe3 32. Rb1 a6 33. Ra5 Rhe8 34. hxg4 Re1+ 35. Rxe1 Rxe1+ 36. Kg2 h4) 30... hxg4?! { (2.67 → 3.55) Inaccuracy. Best move was Bxd4. } (30... Bxd4 31. Rxd4 Rb6 32. Ne4 Rxc6 33. Nxf6 hxg4 34. Rxg4 Rd6 35. Rf2 Rf8 36. Ne4 Rd1+ 37. Kg2) 31. Rf5?? { (3.55 → -5.45) Blunder. Best move was Nf5. } (31. Nf5) 31... g3 32. Kg2 gxf2?? { (-4.71 → -0.80) Blunder. Best move was Bxf2. } (32... Bxf2 33. Ne6 Rg8 34. Rb5 Rc2 35. Kf3 g2 36. Rfb1 Rg3+ 37. Ke4 Bb6 38. c5 Re2+ 39. Kf4) 
33. Nb5? { (-0.80 → -3.54) Mistake. Best move was Rd5. } (33. Rd5 Bxd4 34. Rxd4 Rxa2 35. Rf4 Rg8+ 36. Kf3 Rf8 37. Rxf2 Ra6 38. Ke3 Rxc6 39. Kd4 Kd7) 33... Rg8+? { (-3.54 → -2.28) Mistake. Best move was Rc2. } (33... Rc2 34. Kf3 Re8 35. Rxf6 a6 36. Na3 Rxa2 37. Nb1 Rc2 38. Rg6 Rxc4 39. Kg2 a5 40. Rg3) 34. Kf3 Bd4?? { (-1.89 → 3.90) Blunder. Best move was Re8. } (34... Re8) 35. Nxd4 Rg1?? { (3.29 → 6.55) Blunder. Best move was Rd8. } (35... Rd8 36. Rf4) 36. Rxf2 { Black resigns. } 1-0

[ddugovic]

Thankfully such new annotations would comply with the PGN specification and therefore robust PGN parsers should tolerate them if we choose to create them. Otherwise we'd be stuck using Numeric Annotation Glyphs:

8.2.3.8: SAN move suffix annotations

Import format PGN allows for the use of traditional suffix annotations for
moves.  There are exactly six such annotations available: "!", "?", "!!", "!?",
"?!", and "??".  At most one such suffix annotation may appear per move, and if
present, it is always the last part of the move symbol.

[rpdelaney]

Using human-readable symbols rather than NAGs is proposed in #15 so we should discuss that there.

As for the other commentary added by lichess, e.g. 'Inaccuracy. Best move was Ng5.' and so on, I have mixed feelings about this. For starters, I don't intend just to mimic lichess. So there would have to be some independent, free-standing reason to do what they are doing also here. In this case I don't see what that reason is.

All the information added by this extra lichess commentary is at least implied in the annotations already produced by chess-annotator. You know your move was a mistake because it got an annotation; you know how big of a mistake it was based on the NAG and the difference in the computer's evaluation for the played move vs the best move; and you know what the best move was from the engine PV that is added as a variation.

So I don't see what this would improve, or who would be helped by this. The output format we have now is concise and information-dense. How would the user experience be improved by saying the same thing in more ways?

[Entze]

This is of course a question of preference. I find that the NAGs alone (even with the suggested additions of #15) are more for computer parsing than human interpretation.
I find { 4. Ng5 Blunder: Best move was } (4. Ng3) to be much more meaningful than 4. Ng5 $4 (4. Ng3).
The move suggestions are very helpful to immediately understand why this move was a blunder or mistake, etc..

I would suggest therefore an (or multiple) argument(s) which allows the user to granulate which kind of annotation they would like.

For example:
--commentary -c for Blunder, etc
--move-suggestions -m for move suggestions
--NAGs -n annotate NAGs
--traditional-annotation -t turns on ? ?! etc (particularly with #15 in mind)
--all-annotations -a turns on all of the above

[rpdelaney]

This might hinge somewhat on what you expect the PGN format to achieve in a more general sense. To me, PGN is a specification for structuring data about chess games in a machine readable way. It's my expectation that users will be piping the output into a PGN reader of some kind and consuming it that way. Making the output from chess-annotator human readable in the terminal has not been a goal for this project.

With that in mind...

I find { 4. Ng5 Blunder: Best move was } (4. Ng3) to be much more meaningful than 4. Ng5 $4 (4. Ng3).

Put that way, I agree with you -- mostly because a NAG obfuscates the content of the annotation. But in a PGN reader, the difference is not so clear at all. If we do implement #15 then this problem would be fully eliminated in my eyes. (I'm not even sure it's actually a problem as it is, though.)

The move suggestions are very helpful to immediately understand why this move was a blunder or mistake

I agree. But I don't understand how it is more helpful than just looking at the engine variation. It's right there, and can be read just as easily as the human-readable comment.

I would suggest therefore an (or multiple) argument(s) which allows the user to granulate which kind of annotation they would like.

This would be an ideal solution, yes. But it would also add a non-negligible amount of complexity and maintenance overhead. I'll be thinking about this more, but right now I'm doubting that the payoff would be worth it.

[ddugovic]

I fully agree, PGN is meant to be machine-readable (and convenient to type by hand if necessary).

But in a PGN reader, the difference is not so clear at all.

I agree, most (all?) PGN readers lack this obvious (but costly to localize) feature. Until that changes, English (or other language) prose in PGN is of obvious benefit (and other annotations, less so).

[rpdelaney]

I agree, most (all?) PGN readers lack this obvious (but costly to localize) feature. Until that changes, English (or other language) prose in PGN is of obvious benefit (and other annotations, less so).

I'm not sure I understand - it sounds like you said you agree with me, and then you go on to say that prose comments are an obvious benefit?

[ddugovic]

I'm just saying... because ChessBase and others don't translate ! and ? symbols into prose, for amateur chess players (< 1800 FIDE) it's easier to context-switch between the text viewer and the board viewer if there's prose separating/spacing the moves/variations. Yes, the text viewer typically highlights the "last move" text, but prose helps frame "these are alternative moves" and provides English (or other) context which is more easily remembered than !? or ?! etc.

[rpdelaney]

For fun, here's the same game annotated by python-chess-annotator:

[Event "?"]
[Site "https://lichess.org/sugtc1iC"]
[Date "????.??.??"]
[Round "1"]
[White "?"]
[Black "?"]
[Result "1-0"]
[Variant "Standard"]
[TimeControl "-"]
[ECO "C61"]
[Opening "Ruy Lopez: Bird Variation"]
[Termination "Normal"]
[Annotator "Stockfish 8 64 POPCNT"]
[WhiteACPL "95"]
[BlackACPL "117"]

{ Stockfish 8 64 POPCNT } 1. e4 e5 2. Nf3 Nc6 3. Bb5 Nd4 { C61 Ruy Lopez: Bird Variation } 
4. Bc4 Nf6 5. c3 Nc6 $6 { 1.27 } ( 5... Nxf3+ 6. Qxf3 { 0.02/23 } ) 6. d3 d5 7. Bb5 $2 { -0.49 } 
( 7. exd5 Nxd5 8. Qb3 Na5 9. Qa4+ Nc6 10. Nxe5 Qe7 11. Bxd5 Qxe5+ { 1.10/26 } ) 7... dxe4 
8. Nxe5 Qd5 9. Bxc6+ bxc6 10. Bf4 Bd6 11. d4 Bg4 $2 { 0.58 } ( 11... Ba6 { -0.93/21 } ) 
12. c4 $2 { -0.99 } ( 12. Nxg4 Bxf4 13. Nxf6+ gxf6 14. Qe2 f5 15. Na3 O-O 16. Nc4 Bd6 
{ 0.58/25 } ) 12... Qa5+ $2 { 0.83 } ( 12... Bxd1 13. cxd5 Nxd5 14. Bd2 Ba4 15. Nc3 Nxc3 
16. Bxc3 f6 17. b3 { -0.96/25 } ) 13. Qd2 Qxd2+ 14. Nxd2 Nh5 $6 { 1.07 } ( 14... O-O { 0.18/23 } ) 
15. g3 $6 { -0.25 } ( 15. Be3 { 1.05/23 } ) 15... Rb8 $2 { 2.21 } ( 15... Nxf4 { -0.41/24 } ) 16. f3 $2 { 
-0.12 } ( 16. Nxg4 Nxf4 { 2.50/24 } ) 16... exf3 $2 { 2.01 } ( 16... Nxf4 17. Nxg4 { -0.02/22 } ) 17. 
Ndxf3 $4 { -1.68 } ( 17. Nxg4 Bxf4 { 2.25/23 } ) 17... Rxb2 $4 { 1.27 } ( 17... Bxf3 18. Nxf3 Nxf4 19. 
gxf4 Rxb2 20. O-O Bxf4 21. Rae1+ Kd8 22. Rf2 { -1.91/24 } ) 18. O-O $2 { -0.73 } ( 18. Nxg4 Bxf4 
{ 1.39/25 } ) 18... c5 $4 { 2.63 } ( 18... Bxf3 19. Rxf3 Nxf4 20. gxf4 f6 21. Nd3 Rd2 22. c5 Bf8 23. 
Re1+ { -0.88/26 } ) 19. Nxg4 Nxf4 20. gxf4 Bxf4 $2 { 4.14 } ( 20... O-O 21. Nge5 { 1.68/24 } ) 21. 
Rfe1+ Kd7 22. dxc5 f6 23. Red1+ Kc6 24. Rd5 $6 { 1.53 } ( 24. Nd4+ Kd7 { 2.59/22 } ) 24... h5 25. 
Nd4+ Kb7 26. c6+ Kc8 $6 { 2.57 } ( 26... Kb6 27. Nf2 { 1.38/24 } ) 27. Nf2 $6 { 1.37 } ( 27. Rf1 { 
2.87/22 } ) 27... Be3 28. Rf1 g5 $4 { 4.68 } ( 28... g6 29. Rd7 Re8 30. Nb5 Bb6 31. c5 Rxb5 32. 
cxb6 Rg5+ 33. Kh1 { 1.45/26 } ) 29. h3 $2 { 1.58 } ( 29. Nf5 Bb6 { 4.57/24 } ) 29... g4 $2 { 4.12 } ( 
29... Rd8 30. Rxd8+ Kxd8 31. Ne6+ Ke7 32. Nxc7 Kd6 33. Nd5 Bd4 34. c7 { 1.62/26 } ) 30. hxg4 
hxg4 31. Rf5 $4 { -5.14 } ( 31. Nf5 Bg5 32. Nxg4 Kb8 33. Rf2 Rb4 34. Nge3 Rb6 35. Rc5 a6 
{ 3.62/24 } ) 31... g3 32. Kg2 gxf2 $4 { -1.01 } ( 32... Bxf2 33. R5xf2 gxf2 34. a3 Rh4 35. Nf5 Rxc4 
36. Ne7+ Kd8 37. Nd5 { -5.29/26 } ) 33. Nb5 $4 { -3.81 } ( 33. Rd5 Bxd4 34. Rxd4 Rb6 35. Rxf2 
Rxc6 36. Kf3 Re6 37. Kg4 Rh6 { -0.73/26 } ) 33... Rg8+ 34. Kf3 Bd4 $4 { 4.35 } ( 34... Re8 35. 
Nc3 { -2.34/25 } ) 35. Nxd4 Rg1 $4 { 8.25 } ( 35... Rd8 36. Rd5 { 3.91/27 } ) 36. Rxf2 1-0

[rpdelaney]

Alright, at this point I'm not inclined to alter the way we present engine commentary in this app. If you are able to get the human-readable symbols added to python-chess, please re-open #15 and I'll likely add that in. Thanks for the input regardless.