games.tic_tac_toe.models

Comprehensive data models for strategic Tic Tac Toe gameplay and positional analysis.

This module provides sophisticated data models for the classic game of Tic Tac Toe, supporting both traditional gameplay and advanced strategic analysis. The models enable structured data handling throughout the game implementation and provide strong typing for LLM-based components and strategic decision-making systems.

The models support: - Complete move representation with coordinate validation - Strategic analysis with winning/blocking move detection - Fork opportunity identification for advanced play - Position evaluation from game theory perspective - Multi-level strategic recommendations - Perfect play analysis and minimax integration

Examples

Basic move representation:

move = TicTacToeMove(
    row=0,
    col=1,
    player="X"
)
print(str(move))  # Output: "X places at (0, 1)"

Strategic position analysis:

analysis = TicTacToeAnalysis(
    winning_moves=[{"row": 0, "col": 2}],
    blocking_moves=[{"row": 1, "col": 1}],
    fork_opportunities=[],
    center_available=False,
    corner_available=True,
    position_evaluation="winning",
    recommended_move={"row": 0, "col": 2},
    strategy="Win immediately by completing top row"
)

Fork creation analysis:

analysis = TicTacToeAnalysis(
    winning_moves=[],
    blocking_moves=[],
    fork_opportunities=[{"row": 0, "col": 0}, {"row": 2, "col": 2}],
    center_available=False,
    corner_available=True,
    position_evaluation="unclear",
    recommended_move={"row": 0, "col": 0},
    strategy="Create fork with two winning threats"
)

Note

All models use Pydantic for validation and support both JSON serialization and integration with LLM-based strategic analysis systems for perfect play.

Classes

TicTacToeAnalysis	Advanced strategic analysis model for Tic Tac Toe positions with game theory.
TicTacToeMove	Comprehensive representation of a Tic Tac Toe move with validation and game.

Module Contents

class games.tic_tac_toe.models.TicTacToeAnalysis(/, **data)

Bases: pydantic.BaseModel

Advanced strategic analysis model for Tic Tac Toe positions with game theory. insights.

This model provides comprehensive analysis of Tic Tac Toe positions using game theory principles, perfect play algorithms, and strategic heuristics. It supports both educational gameplay and competitive AI decision-making with detailed explanations of optimal strategies.

The analysis includes: - Immediate win detection and threat assessment - Defensive move identification to prevent losses - Fork creation and prevention strategies - Positional advantage evaluation (center, corners, edges) - Game-theoretic position classification - Perfect play recommendations with explanations - Educational insights for learning optimal strategy

Parameters:

data (Any)

winning_moves

Coordinates that win immediately. Each dict contains ‘row’ and ‘col’ keys for winning positions.

Type:

List[Dict[str, int]]

blocking_moves

Moves that must be played to prevent loss. Critical defensive moves to block opponent’s winning threats.

Type:

List[Dict[str, int]]

fork_opportunities

Moves creating multiple threats. Advanced positions that force opponent into defensive play.

Type:

List[Dict[str, int]]

center_available

Whether the center square (1,1) is unoccupied. Center control is crucial for optimal Tic Tac Toe strategy.

Type:

bool

corner_available

Whether any corner square is unoccupied. Corners are second-best positions after center.

Type:

bool

position_evaluation

Game-theoretic evaluation of position. Classifications: winning, losing, drawing, unclear.

Type:

Literal

recommended_move

Best move by perfect play. Computed using minimax algorithm with full game tree search.

Type:

Optional[Dict[str, int]]

strategy

Natural language explanation of optimal strategy. Educational description for understanding the position.

Type:

str

move_priority

Priority ranking of recommended move. 1=win, 2=block loss, 3=create fork, 4=block fork, 5=positional.

Type:

Optional[int]

optimal_outcome

Expected result with perfect play. Predicts game outcome assuming both players play optimally.

Type:

Optional[Literal]

Examples

Winning position analysis:

analysis = TicTacToeAnalysis(
    winning_moves=[{"row": 0, "col": 2}],
    blocking_moves=[],
    fork_opportunities=[],
    center_available=False,
    corner_available=False,
    position_evaluation="winning",
    recommended_move={"row": 0, "col": 2},
    strategy="Win immediately by completing the top row",
    move_priority=1,
    optimal_outcome="win"
)

Defensive position requiring blocking:

analysis = TicTacToeAnalysis(
    winning_moves=[],
    blocking_moves=[{"row": 1, "col": 1}],
    fork_opportunities=[],
    center_available=True,
    corner_available=True,
    position_evaluation="losing",
    recommended_move={"row": 1, "col": 1},
    strategy="Must block opponent's winning threat in center",
    move_priority=2,
    optimal_outcome="draw"
)

Fork creation opportunity:

analysis = TicTacToeAnalysis(
    winning_moves=[],
    blocking_moves=[],
    fork_opportunities=[{"row": 0, "col": 0}, {"row": 2, "col": 2}],
    center_available=False,
    corner_available=True,
    position_evaluation="unclear",
    recommended_move={"row": 0, "col": 0},
    strategy="Create fork with two winning threats - opponent cannot block both",
    move_priority=3,
    optimal_outcome="win"
)

Opening position analysis:

analysis = TicTacToeAnalysis(
    winning_moves=[],
    blocking_moves=[],
    fork_opportunities=[],
    center_available=True,
    corner_available=True,
    position_evaluation="unclear",
    recommended_move={"row": 1, "col": 1},
    strategy="Control center for maximum strategic flexibility",
    move_priority=5,
    optimal_outcome="draw"
)

Note

This model provides the foundation for perfect Tic Tac Toe play. With optimal strategy, the game always ends in a draw.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

classmethod validate_move_coordinates(v)

Validate that all move coordinates are within bounds.

Parameters:

v (List[Dict[str, int]]) – List of move coordinates to validate.

Returns:

Validated move coordinates.

Return type:

List[Dict[str, int]]

Raises:

ValueError – If coordinates are out of bounds.

property has_immediate_threat: bool

Check if there’s an immediate win or loss threat.

Returns:

True if winning or blocking moves exist.

Return type:

bool

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property move_count: dict[str, int]

Count available moves by category.

Returns:

Counts of different move types.

Return type:

Dict[str, int]

property threat_level: str

Assess the urgency level of the position.

Returns:

Threat level classification.

Return type:

str

class games.tic_tac_toe.models.TicTacToeMove(/, **data)

Bases: pydantic.BaseModel

Comprehensive representation of a Tic Tac Toe move with validation and game. context.

This model provides complete representation of moves in Tic Tac Toe, supporting both basic gameplay and advanced strategic analysis. It includes coordinate validation, player identification, and integration with game state management for perfect play algorithms and educational systems.

The model supports: - Coordinate validation for 3x3 grid constraints - Player symbol enforcement (X or O) - Move notation generation for game records - Integration with minimax and alpha-beta pruning - Educational move explanations - Tournament play recording standards

Parameters:

data (Any)

row

Row index (0-2) where the player places their symbol. Uses 0-based indexing with 0=top, 1=middle, 2=bottom.

Type:

int

col

Column index (0-2) where the player places their symbol. Uses 0-based indexing with 0=left, 1=center, 2=right.

Type:

int

player

The symbol representing the player. ‘X’ traditionally plays first, ‘O’ plays second.

Type:

Literal[‘X’, ‘O’]

Examples

Basic move creation:

move = TicTacToeMove(row=1, col=1, player="X")
print(str(move))  # Output: "X places at (1, 1)"
# This represents X playing in the center square

Corner move for strategic play:

corner_move = TicTacToeMove(row=0, col=0, player="X")
# Opening corner move - classic strategic opening

Blocking move example:

block = TicTacToeMove(row=2, col=2, player="O")
# O blocks X's potential diagonal win

Educational notation:

move = TicTacToeMove(row=0, col=2, player="X")
# Top-right corner: strategic for controlling diagonals

Note

Moves are validated to ensure coordinates are within the 3x3 grid. The string representation provides human-readable move descriptions.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

property board_position: str

Get human-readable board position name.

Returns:

Position name like ‘center’, ‘top-left corner’, etc.

Return type:

str

property is_center: bool

Check if this move is the center position.

Returns:

True if the move is in the center (most valuable position).

Return type:

bool

property is_corner: bool

Check if this move is a corner position.

Returns:

True if the move is in a corner (strategic positions).

Return type:

bool

property is_edge: bool

Check if this move is an edge (non-corner, non-center) position.

Returns:

True if the move is on an edge (weakest positions).

Return type:

bool