chessai.core.action

  1"""
  2The core actions that agents are allowed to take.
  3Default actions are provided, but custom actions can be easily created.
  4"""
  5
  6import re
  7import typing
  8
  9import edq.util.json
 10import edq.util.serial
 11
 12import chessai.core.coordinate
 13import chessai.core.piece
 14import chessai.core.types
 15
 16ACTION_PATTERN: re.Pattern = re.compile(r'^([a-z]+\d+)([a-z]+\d+)([a-zA-Z]?)$')
 17ACTION_KEY: str = 'actions'
 18
 19UCI_ACCEPT_DRAW_ACTION: str = 'Accept Draw'
 20UCI_FORFEIT_ACTION: str = 'Forfeit'
 21UCI_NULL_ACTION: str = '0000'
 22UCI_PROPOSE_DRAW_ACTION: str = 'Propose Draw'
 23UCI_REJECT_DRAW_ACTION: str = 'Reject Draw'
 24
 25class Action(edq.util.serial.DictConverter):
 26    """
 27    The base for all actions that an agent is allowed to take.
 28
 29    Actions are an immutable class, so do not change attributes after construction.
 30
 31    Actions are strings in the Chess UCI format
 32    (https://en.wikipedia.org/wiki/Universal_Chess_Interface).
 33    """
 34
 35    _type_order: typing.ClassVar[int]
 36    """
 37    The ordering of this action type.
 38    Child classes must choose a unique type number for their game.
 39    """
 40
 41    # This function is meant to be an abc.abstractmethod,
 42    # but for performance reasons it raises an error.
 43    def uci(self) -> str:
 44        """ Represent the agent action as a chess move in UCI format. """
 45
 46        raise NotImplementedError("Action.uci()")
 47
 48    # Comparing actions with non-action objects raises an error.
 49    def __lt__(self, other: object) -> bool:
 50        return bool(self._type_order < other._type_order)  # type: ignore[attr-defined]  # pylint: disable=no-member
 51
 52    # Comparing actions with non-action objects may raise an error.
 53    def __eq__(self, other: object) -> bool:
 54        return type(self) == type(other)
 55
 56    def __str__(self) -> str:
 57        return self.uci()
 58
 59    def __repr__(self) -> str:
 60        return self.uci()
 61
 62class NoneAction(Action):
 63    """ An action that signifies nothing happened. """
 64
 65    _type_order = 0
 66
 67    def uci(self) -> str:
 68        return UCI_NULL_ACTION
 69
 70class MoveAction(Action):
 71    """ Actions that move a piece from one coordinate to another. """
 72
 73    _type_order = 1
 74
 75    def __init__(self,
 76                 start_coordinate: chessai.core.coordinate.Coordinate,
 77                 end_coordinate: chessai.core.coordinate.Coordinate,
 78                 ) -> None:
 79        self.start_coordinate: chessai.core.coordinate.Coordinate = start_coordinate
 80        """ The starting coordinate for the action. """
 81
 82        self.end_coordinate: chessai.core.coordinate.Coordinate = end_coordinate
 83        """ The ending coordinate for the action. """
 84
 85    def uci(self) -> str:
 86        start = self.start_coordinate.uci()
 87        end = self.end_coordinate.uci()
 88
 89        return f"{start}{end}"
 90
 91    def __eq__(self, other: object) -> bool:
 92        if (type(self) != type(other)):
 93            return False
 94
 95        return (self.start_coordinate, self.end_coordinate) == (other.start_coordinate, other.end_coordinate) # type: ignore[attr-defined]  # pylint: disable=no-member
 96
 97    def __lt__(self, other: object) -> bool:
 98        if isinstance(other, MoveAction):
 99            return (self.start_coordinate, self.end_coordinate) < (other.start_coordinate, other.end_coordinate)
100
101        return bool(self._type_order < other._type_order)  # type: ignore[attr-defined]  # pylint: disable=no-member
102
103class PromotionAction(MoveAction):
104    """ Actions that move a piece and promote it to another piece type. """
105
106    _type_order = 2
107
108    def __init__(self,
109                 start_coordinate: chessai.core.coordinate.Coordinate,
110                 end_coordinate: chessai.core.coordinate.Coordinate,
111                 promotion: chessai.core.piece.Piece,
112                 ) -> None:
113        super().__init__(start_coordinate, end_coordinate)
114
115        self.promotion: chessai.core.piece.Piece = promotion
116        """ The piece to promote to, or None if this is not a promotion move. """
117
118    def uci(self) -> str:
119        movement_uci = super().uci()
120        promotion = self.promotion.symbol()
121
122        return f"{movement_uci}{promotion}"
123
124    def __eq__(self, other: object) -> bool:
125        if (not isinstance(other, PromotionAction)):
126            return False
127
128        return (self.start_coordinate, self.end_coordinate, self.promotion) == (other.start_coordinate, other.end_coordinate, other.promotion)
129
130    def __lt__(self, other: object) -> bool:
131        if isinstance(other, PromotionAction):
132            return (self.start_coordinate, self.end_coordinate, self.promotion) < (other.start_coordinate, other.end_coordinate, other.promotion)
133
134        return bool(self._type_order < other._type_order)  # type: ignore[attr-defined]  # pylint: disable=no-member
135
136class MetaAction(Action):
137    """
138    Meta actions for inter-agent communication regarding non-standard actions.
139
140    Meta actions include handling draws and forfeits.
141    """
142
143    def uci(self) -> str:
144        raise NotImplementedError("MetaAction.uci()")
145
146class ProposeDrawAction(MetaAction):
147    """ A meta action signaling the agent is offering a draw. """
148
149    _type_order = 3
150
151    def uci(self) -> str:
152        return UCI_PROPOSE_DRAW_ACTION
153
154class AcceptDrawAction(MetaAction):
155    """ A meta action responding to a draw proposal with an acceptance. """
156
157    _type_order = 4
158
159    def uci(self) -> str:
160        return UCI_ACCEPT_DRAW_ACTION
161
162class RejectDrawAction(MetaAction):
163    """ A meta action responding to a draw proposal with a rejection. """
164
165    _type_order = 5
166
167    def uci(self) -> str:
168        return UCI_REJECT_DRAW_ACTION
169
170class ForfeitAction(MetaAction):
171    """ A meta action signaling the agent is forfeiting the game. """
172
173    _type_order = 6
174
175    def uci(self) -> str:
176        return UCI_FORFEIT_ACTION
177
178def from_uci(uci: str) -> Action:
179    """
180    Parse a UCI string into the appropriate Action.
181    """
182
183    if (uci == UCI_NULL_ACTION):
184        return NoneAction()
185
186    if (uci == UCI_PROPOSE_DRAW_ACTION):
187        return ProposeDrawAction()
188
189    if (uci == UCI_ACCEPT_DRAW_ACTION):
190        return AcceptDrawAction()
191
192    if (uci == UCI_REJECT_DRAW_ACTION):
193        return RejectDrawAction()
194
195    if (uci == UCI_FORFEIT_ACTION):
196        return ForfeitAction()
197
198    match = ACTION_PATTERN.fullmatch(uci)
199    if (match is None):
200        raise ValueError("An action must be a pair of coordinates with an optional promotion piece:"
201                        + f" '{ACTION_PATTERN.pattern}', got: '{uci}'.")
202
203    start_coordinate = chessai.core.coordinate.Coordinate.from_uci(match.group(1))
204    end_coordinate = chessai.core.coordinate.Coordinate.from_uci(match.group(2))
205
206    tail = match.group(3)
207    if (len(tail) == 1):
208        if (tail not in chessai.core.piece.get_registered_piece_symbols()):
209            raise ValueError(f"Unknown promotion piece symbol '{tail}' in UCI string: '{uci}'.")
210
211        promotion = chessai.core.piece.get_registered_piece(tail)
212        return PromotionAction(start_coordinate, end_coordinate, promotion)
213
214    return MoveAction(start_coordinate, end_coordinate)
215
216def process_raw_action_list(raw_action_list: str | dict[str, typing.Any]) -> list[list[Action]]:
217    """ Convert raw move lines, from the CLI, into cleaned move lines. """
218
219    if (isinstance(raw_action_list, dict)):
220        raw_action_list = str(raw_action_list.get(ACTION_KEY, None))
221
222    parsed_move_lines = edq.util.json.loads(raw_action_list)
223
224    clean_move_lines: list[list[Action]] = []
225
226    for line in parsed_move_lines:
227        move_line = []
228        for uci in line:
229            move_line.append(from_uci(uci))
230
231        clean_move_lines.append(move_line)
232
233    return clean_move_lines