Added prompts and support files

Author: bcorfman

parsing/PDN.py

@@ -163,7 +163,7 @@ def _read_board_orientation(self, value):
             raise SyntaxError(f"Unknown {value} used in board_orientation tag.")
 
     def _start_move_list(self, _):
-        if self._black_player and self._white_player:
+        if self._black_player and self._white_player and self._black_player != "*" and self._white_player != "*":
             title = f"{self._event}: {self._black_player} vs. {self._white_player}"
         else:
             title = f"{self._event}"
@@ -281,9 +281,9 @@ def read_game(self, idx):
                         self._moves.append([move_list, annotation])
                     else:
                         raise RuntimeError(f"Cannot interpret item {item} in game.body")
-            # if no game description was in the file, add a basic one so the user has something to guide them.
+        # if no game description was in the file, add a basic one so the user has something to guide them.
         if not self._description:
-            if self._black_player and self._white_player:
+            if self._black_player and self._white_player and self._black_player != "*" and self._white_player != "*":
                 self._description += f"{self._event}: {self._black_player} vs. {self._white_player}"
             else:
                 self._description += f"{self._event}"

prompts_and_support_files/FEN_description.txt

@@ -0,0 +1,42 @@
+# FEN Description for American Checkers (8x8 Board)
+
+The Forsyth-Edwards Notation (FEN) represents a checkers position in a concise string format. For American Checkers, the FEN format follows this pattern:
+
+[TURN]:[COLOR1][PIECES]:[COLOR2][PIECES]
+
+Where:
+- [TURN] is either "W" (White's turn) or "B" (Black's turn)
+- [COLOR1] is always "W" for White pieces
+- [COLOR2] is always "B" for Black pieces
+- [PIECES] is a comma-separated list of piece positions, with kings prefixed by "K"
+
+## Format Rules:
+1. The FEN always begins with the turn indicator "W" or "B" followed by a colon
+2. White pieces are always listed first, then Black pieces
+3. Regular men are indicated by just their square number
+4. Kings are indicated by "K" followed immediately by their square number
+5. Multiple pieces of the same color are separated by commas
+6. The two color sections are separated by a colon
+7. No spaces are allowed in the FEN string
+8. Square numbers range from 1-32
+
+## Examples:
+
+Starting position (White to move):
+W:W21,22,23,24,25,26,27,28,29,30,31,32:B1,2,3,4,5,6,7,8,9,10,11,12
+
+White has two kings, Black has one king and one man (Black to move):
+B:WK10,K20:B5,K15
+
+White has one king, Black has three kings (White to move):
+W:WK23:BK7,K10,K15
+
+Two kings vs one king (Either to play):
+W:WK5,K10:BK20
+B:WK5,K10:BK20
+
+## Important Notes:
+1. When generating a FEN string from a diagram, first determine the turn from the accompanying instruction line ("Black to play", "White to play", or "Either to play").
+2. When the instruction says "Either to play", use the side specified first in the continuation text.
+3. In PDN files, the FEN tag must be formatted as: [FEN "W:W1,2:B3,4"] (including the quotes)
+4. Men and kings should be listed in ascending order by square number for readability (though this is not required by the standard)

prompts_and_support_files/PDN_generation.txt

@@ -0,0 +1,84 @@
+The PDN output for each diagram should be as follows:
+An Event tag is first in the file. It should be the name of the diagram, such as "Diagram 5".
+
+Next is the Date tag. If there is a date listed as part of the surrounding diagram text (such as "Edinburgh 1848, game 1" or "I got Willie Leeds with this move in the 1985 championship") then the date would go here in the value; otherwise, the value should just be an asterisk. All dates should be represented in MM/DD/YYYY format. If some of the date is unknown, then use question marks to represent the unknown portions, e.g., ??/??/1985
+
+The Round tag is next. Use an asterisk for this value.
+
+The Black tag is next. If the Black player has a name, it should be included here. For instance, if the surrounding diagram text said "Tinsley is Black; Chinook is White", then the value for Black would be "Tinsley". If no Black player is listed, then leave it as an empty string.
+
+The White tag is next. If the White player has a name, it should be included here. For instance, if the surrounding diagram text said "Tinsley is Black; Chinook is White", then the value for White would be "Chinook". If no White player is listed, then leave it as an empty string.
+
+The Site tag is next. Use an asterisk for this value.
+
+The Result tag is next. If Black wins, the result is 1-0; if White wins, the result is 0-1; if both players draw, the result is 1/2-1/2; if the game is still in-process, the result is an asterisk.
+
+The FEN tag is next. Use the procedure for generating the FEN for each diagram outlined in the attached FEN_description.txt file. Be sure to correctly identify all pieces and their positions.
+
+The BoardOrientation tag is next. Use "white_on_top" for this value.
+
+Next is one or more comment lines (each beginning with a % symbol and a space) that should contain the overall description of the diagram. Things to include in the comments:
+
+1. The title of the section that the diagram is in, if it applies to the diagram.
+2. The lesson title.
+3. Relevant context or descriptive information in the paragraphs related to the diagram, but not involving the actual checker moves or annotations in the game continuation.
+4. Make sure to directly reference the diagram by number in the description (e.g., "Diagram 5 shows...")
+5. Don't start descriptions with transition words like "However" that imply preceding content
+6. Don't refer to other diagrams in the descriptions
+7. Make each description self-contained with all relevant information
+8. Use clear, simple language (avoid phrases like "all-king endgame" in favor of clearer phrasing)
+
+After the descriptive comments, add a play instruction line as a comment (starting with % symbol) that describes whose turn it is to play and the expected outcome (e.g., "% Black to play, White wins" or "% White to play and draw").
+
+Next in the file is a GameBody, as defined in PDN_Grammar.txt. This is the PDN version of the move continuation text, listed in the text after its matching diagram. The move continuation text starts with the phrase "Continue: ..." or "Continue from Diagram N: ..." where N refers to the number of the diagram preceding. Include move numbers (1., 2., etc.) at the beginning of each pair of moves. One difference from the PDN grammar GameBody definition is that both Variations or COMMENTs will be in parentheses, and when translated to PDN, both the Variations and the COMMENTs should be in curly braces. Each move should be followed by a comment in curly braces containing the move notation and any variations or annotations given in the original text. The other difference from the PDN grammar in the move continuation text is that rather than ending with a WIN1, DRAW1 or LOSS1, the ending will say something like "Black wins.", "White wins." or "Drawn.". This should be translated to the appropriate WIN1, DRAW1 or LOSS1 when the PDN is created.
+
+Three examples of valid, generated PDNs based on the instructions above:
+
+Example 1 -
+[Event "Diagram 5"]
+[Date "*"]
+[Round "*"]
+[Black "Player 1"]
+[White "Player 2"]
+[Site "*"]
+[Result "*"]
+[FEN "W:WK23:BK31"]
+[BoardOrientation "white_on_top"]
+% Chapter 3: Simple Endgames
+% Lesson 3: 1 King v 1 King
+% Diagram 5 shows a position where Black is pinned on the side of the board and just two moves away from losing.
+% Black to play, White wins
+1. 31-27 {31-27 (Or 31-26 23-30)} 23-32 {23-32. White wins.} 0-1
+
+Example 2 - 
+[Event "Diagram 10"]
+[Date "*"]
+[Round "*"]
+[Black "Player 1"]
+[White "Player 2"]
+[Site "*"]
+[Result "*"]
+[FEN "W:WK5,WK6:BK15"]
+[BoardOrientation "white_on_top"]
+% Chapter 3: Simple Endgames
+% Lesson 4: 2 Kings v 1 King
+% In an open all-king situation where there is a material imbalance, the side with the king majority has a forced win at hand. In the case of 2 kings v 1, the strategy employed is as follows: the lone king strives to access one of the double-corners; the two kings pursue it there, force it out and pin it on the side of the board. Diagram 10 is representative.
+% White to play and win
+ 1. 5-9 {5-9} 2. 15-19 {15-19 (15-18 comes to the same thing, while 15-11 just hastens the end)} 6-10 {6-10} 3. 19-24 {19-24 (The same comments apply to 19-23 and 19-16)} 10-15 {10-15 (There is no need to memorize specific moves, just the general strategy)} 4. 24-28 {24-28 (Again, 24-27 is essentially the same; 24-20 loses quickly)} 15-19 {15-19} 5. 28-32 {28-32} 9-14 {9-14} 6. 32-28 {32-28} 14-18 {14-18} 7. 28-32 {28-32} 18-23 {18-23} 8. 32-28 {32-28} 23-27 {23-27} 9. 28-32 {28-32} 19-23 {19-23!} 10. 32-28 {32-28} 27-32 {27-32! (Entering the double-corner and forcing Black out)} 11. 28-24 {28-24} 32-28 {32-28} 12. 24-20 {24-20} 23-18 {23-18!} 13. 20-16 {20-16} 18-15 {18-15} 14. 16-20 {16-20} 15-11 {15-11! White wins.} 0-1
+
+Example 3 -
+[Event "Diagram 8"]
+[Date "*"]
+[Round "*"]
+[Black "Player 1"]
+[White "Player 2"]
+[Site "*"]
+[Result "1/2-1/2"]
+[FEN "W:WK5:BK12"]
+[BoardOrientation "white_on_top"]
+% Chapter 3: Simple Endgames
+% Lesson 3: 1 King v 1 King
+% In Diagram 8, White has the opposition, but it confers no advantage in the current setup. In a 1 king v 1 king situation, possession of the opposition means it's impossible to lose. This position requires Black to employ care to secure the draw.
+% Simple as it may be, before proceeding it's well worth playing through Diagram 8 several times, examining all the possible alternate moves, in order to firmly embed the underlying principles.
+% White to play, Black draws
+1. 5-9 {5-9}; 2. 12-16 {12-16!} 9-14 {9-14} 3. 16-19 {16-19 (16-20 is also okay, but both 16-11? and 16-12? lose)} 14-18 {14-18} 4. 19-24 {19-24!} 18-23 {18-23} 5. 24-28 {24-28!} 23-27 {23-27} 6. 28-32 {28-32} 27-23 {27-23 (Or 27-24 or 27-31) and drawn.} 1/2-1/2

prompts_and_support_files/PDN_grammar.txt

@@ -0,0 +1,143 @@
+PDN Grammars
+This section defines some PDN grammars. First a PDN 3.0 grammar is given, with some additional restrictions. The goal of these restrictions is to make PDN easier to parse, and thus to make it easier for programmers to support PDN 3.0. Also some explanations are given. Finally, a much more liberal reading grammar is given that can be used when reading existing PDN files. The grammars that are given in this section can not be parsed using a simple LL(1) parser. See the PDN Implementation section for some examples of LL(1) grammars.
+
+PDN 3.0 Grammar
+// Game independent productions
+PdnFile          : Game (GameSeparator Game)* GameSeparator?
+GameSeparator    : ASTERISK
+Game             : (GameHeader GameBody?) | GameBody
+GameHeader       : PdnTag+
+GameBody         : (GameMove | Variation | COMMENT | SETUP | NAG)+
+PdnTag           : LBRACKET IDENTIFIER STRING RBRACKET
+GameMove         : MOVENUMBER? Move MOVESTRENGTH?
+Variation        : LPAREN GameBody RPAREN
+
+// Game dependent productions
+Move             : NormalMove | CaptureMove
+NormalMove       : Square MOVESEPARATOR Square
+CaptureMove      : Square (CAPTURESEPARATOR Square)+
+Square           : ALPHASQUARE | NUMSQUARE
+
+// Tokens
+MOVENUMBER       : "[0-9]+\.(\.\.)?"
+MOVESEPARATOR    : "-"
+CAPTURESEPARATOR : "x"
+ALPHASQUARE      : "[a-h][1-8]"
+NUMSQUARE        : "[1-9][0-9]?"
+MOVESTRENGTH     : "([\!\?]+)|(\([\!\?]+\))"
+NAG              : "\$[0-9]+"
+LPAREN           : "\("
+RPAREN           : "\)"
+LBRACKET         : "\["
+RBRACKET         : "\]"
+ASTERISK         : "\*"
+SETUP            : "\/[^\/]*\/"
+STRING           : "\"([^\"]|\\\")*\""
+COMMENT          : "\{[^}]*\}"
+IDENTIFIER       : "[A-Z][a-zA-Z0-9_]*"
+Besides the usual white space characters (spaces, tabs and line endings), also line comments starting with a % are allowed. For example
+
+% Board game: International Draughts 10x10
+[Date "2012.02.01"]
+1. 32-28 19-23
+PDN 3.0 Restrictions
+When writing PDN, the following restrictions should be applied:
+
+Spaces are not allowed in the notation of a move. For example, 1 - 7 is not allowed.
+
+Spaces are not allowed between a move notation and it’s move strength indicator. For example, 32-28 ! is not allowed.
+
+The symbol * is not allowed as a move strength indicator. Use the $7 numeric annotation glyph instead. See the PDN parsing issues section for an explanation.
+
+Only the symbol * is allowed as a game separator.
+
+Squares of moves may not have leading zeroes. For example 01-07 is not allowed.
+
+Moves must be written in the format (Alpha numeric, Numeric or SAN) as it is specified in the Notation attribute of the GameType tag. See also section GameType tag.
+
+Capture moves must be written using the capture separator corresponding to the GameType, as it is specified in the table in section GameType tag.
+
+Ambiguous moves must be written in long notation, i.e. they must contain the full capture sequence. All other moves should use regular notation, i.e. only a begin and an end square.
+
+Explanation: sometimes the regular notation of a move is ambiguous. For example in the position below the notation 47x36 does not specify exactly which black pieces were captured.
+
+_images/diagram1.png
+To resolve this, 47x38x24x13x36 or 47x38x20x9x36 must be chosen.
+
+Disambiguated capture sequences have to specify a complete sequence of intermediate squares along the path of the capture. If there is a change in direction, an intermediate square is the square where a turn in direction was made. If there was not a change in direction, the intermediate square is the square immediately behind a captured piece. There is no intermediate square behind the last captured piece, but otherwise leaving out an intermediate square that is not necessary for the disambiguation is forbidden.
+
+For example, in the above diagram 47x24x36 is not allowed, even though it uniquely determines the move. Also 47x33x24x13x36 is not allowed, since 33 is not immediately behind a captured piece.
+
+N.B. The first five restrictions are enforced by the grammar. Other restrictions have to be checked after parsing.
+
+Explanation
+The grammar is given in EBNF format. In the productions the symbol ? stands for 0 or 1 repetitions, * stands for 0 or more repetitions, and + stands for 1 or more repetitions. Tokens are given between double quotes and should be interpreted as regular expressions.
+
+Strings can have embedded double quotes ", by using the escape sequence \". For example "An embedded \" quote!".
+
+Comments are placed between braces. For example { Start of the game } 33-28 18-22 39-33? { This is a classical mistake }.
+
+In existing PDN files games are usually terminated with a result. It can be one of the chess results 1-0, 1/2-1/2, 0-1, one of the results of international draughts 2-0, 1-1, 0-2, or a double forfeit 0-0. Finally the * can be used as a terminator.
+
+A game can not be empty.
+
+Both numeric moves 32-28 and alpha-numeric moves a3-b4 are allowed.
+
+In alpha-numeric moves the separator may be omitted, so a3b4 is allowed.
+
+A move number is a number followed by either one dot or three dots, for example 1. 32-28 or 23... 20-25. The three dots denotes that it is a black move.
+
+Moves can be annotated using a move strength indicator right after their notation, for example 10-15! or 29-23(?).
+
+Moves can also be annotated using numeric annotation glyphs (NAGs). For example $1 has the same meaning as the move strength indicator !.
+
+Comments, variations and NAGs may appear anywhere in the game, in any order. This is less restrictive than in [Nemesis],
+
+Variations are placed between parentheses. They can be nested arbitrarily, for example: 32-28 19-23 (18-23 38-32 (37-32? 23-29! { Black wins }) 12-18) 28x19 14x23.
+
+PDN Reading Grammar
+// Game independent productions
+PdnFile          : Game (GameSeparator Game)* GameSeparator?
+GameSeparator    : ASTERISK | Result
+Game             : (GameHeader GameBody?) | GameBody
+GameHeader       : PdnTag+
+GameBody         : (GameMove | Variation | COMMENT | SETUP | NAG)+
+PdnTag           : LBRACKET IDENTIFIER STRING RBRACKET
+GameMove         : MOVENUMBER? Move MOVESTRENGTH?
+Variation        : LPAREN GameBody RPAREN
+
+// Game dependent productions
+Move             : NormalMove | CaptureMove | ELLIPSES
+NormalMove       : Square MOVESEPARATOR Square
+CaptureMove      : Square (CAPTURESEPARATOR Square)+
+Square           : ALPHASQUARE | NUMSQUARE
+Result           : Result1 | Result2 | DOUBLEFORFEIT
+Result1          : WIN1 | DRAW1 | LOSS1
+Result2          : WIN2 | DRAW2 | LOSS2
+
+// Tokens
+WIN1             : "1-0"
+DRAW1            : "1\/2-1\/2"
+LOSS1            : "0-1"
+WIN2             : "2-0"
+DRAW2            : "1-1"
+LOSS2            : "0-2"
+DOUBLEFORFEIT    : "0-0"                          
+ELLIPSES         : "\.\.\."
+MOVENUMBER       : "[0-9]+\.(\.\.)?"
+MOVESEPARATOR    : "-"
+CAPTURESEPARATOR : "[x:]"
+ALPHASQUARE      : "[a-h][1-8]"
+NUMSQUARE        : "([1-9][0-9]?)|(0[1-9])"
+MOVESTRENGTH     : "([\!\?]+)|(\([\!\?]+\))"
+NAG              : "\$[0-9]+"
+LPAREN           : "\("
+RPAREN           : "\)"
+LBRACKET         : "\["
+RBRACKET         : "\]"
+ASTERISK         : "\*"
+SETUP            : "\/[^\/]*\/"
+STRING           : "\"([^\"]|\\\")*\""
+COMMENT          : "\{[^}]*\}"
+IDENTIFIER       : "[A-Z][a-zA-Z0-9_]*"
+When reading PDN, one must take into account that captures can can contain the full capture sequence, also in the case of non-ambiguous moves. This is for backward compatibility.

prompts_and_support_files/checkerboard_interpretation.txt

@@ -0,0 +1,78 @@
+Each diagram in the attached PDF represents a checkers board state using a structured text format. Diagrams are labeled "Diagram N" or "Diagram N:", where N is a number between 1 and 128.
+
+Each diagram consists of the following key components:
+1. Diagram Label
+A label starting with "Diagram N" or "Diagram N:", where N is a number.
+This may be followed by optional descriptive text and one or more newlines.
+
+2. Checkerboard Representation
+Begins with the border line:
+QRRRRRRRRS
+
+Ends with the border line:
+VWWWWWWWWX
+
+Contains rows prefixed with "T" or "U", which are border characters and must be ignored.
+
+Each row consists of:
+Dark, non-playable squares → Represented by "E" (IGNORE THESE COMPLETELY).
+Playable squares (either occupied or empty) are defined by a letter-number pair.
+
+Piece Representation:
+"A" → Black man
+"B" → White man
+"C" → Black king
+"D" → White king
+" " (space) → Open playable square
+
+Square Number Encoding:
+1-9 → "1" through "9"
+10-19 → "!" replaces the leading 1 (e.g., "!0" = 10, "!1" = 11, etc.)
+20-29 → "@" replaces the leading 2 (e.g., "@0" = 20, "@1" = 21, etc.)
+30-32 → "#" replaces the leading 3 (e.g., "#0" = 30, "#1" = 31, "#2" = 32)
+
+3. Play Instruction
+After the checkerboard, a single line starts with "Black to play", "White to play" or "Either to play". 
+
+The following rigorous steps must be followed every time:
+Step 1: Extract the Diagram
+Locate "Diagram N" or "Diagram N:" to identify the start of the diagram.
+Extract everything from "QRRRRRRRRS" (inclusive) to "VWWWWWWWWX" (inclusive).
+Extract the single play instruction line directly below the diagram.
+
+Step 2: Process the Board
+Ignore "T" and "U" (border characters).
+Ignore all "E" characters (non-playable dark squares).
+Read only letter-number pairs and map them to the correct square numbers.
+Do not infer or assume; each piece must be explicitly listed in the extracted text.
+
+Step 3: List All Pieces
+Black Men (A) → List all numbered squares
+White Men (B) → List all numbered squares
+Black Kings (C) → List all numbered squares
+White Kings (D) → List all numbered squares
+
+Confirm each square number using the exact encoding rules.
+
+Example: Interpreting Diagram 86
+
+Extracted board text:
+QRRRRRRRRS
+TE 1E 2E 3E 4U
+TA5EB6E 7E 8EU
+TEB9E !0E !1E !2U
+T !3EB!4EC!5E !6EU
+TE !7E !8E !9E @0U
+T @1E @2E @3E @4EU
+TE @5EC@6E @7E @8U
+T @9E #0E #1E #2EU
+VWWWWWWWWX
+
+Play instruction: "White to play"
+
+Final Interpretation
+Type of Piece	Square Numbers
+Black Men (A)	5
+White Men (B)	6, 9, 14
+Black Kings (C)	15, 26
+White Kings (D)	(None)