games.battleship.models¶

Pydantic models for Battleship naval strategy game components.

This module defines comprehensive data models for the classic Battleship game, including ships, coordinates, attacks, board state, and strategic analysis. All models use Pydantic for validation with extensive documentation and examples.

The Battleship implementation supports classic naval combat gameplay with AI-powered strategic targeting, ship placement validation, and sophisticated probability-based attack algorithms.

Examples

Creating ship coordinates:

coordinates = Coordinates(row=3, col=5)
print(f"Targeting {coordinates}")  # Targeting (3, 5)

Placing a ship:

destroyer_placement = ShipPlacement(
    ship_type=ShipType.DESTROYER,
    coordinates=[
        Coordinates(row=2, col=3),
        Coordinates(row=2, col=4)
    ]
)

Executing an attack:

attack = MoveCommand(row=4, col=6)
outcome = board.receive_attack(attack.row, attack.col)
print(f"Attack result: {outcome}")

Classes¶

`Analysis`	Strategic analysis of the current Battleship game state.
`Coordinates`	Represents a coordinate position on the Battleship game board.
`GamePhase`	Current phase of the Battleship game.
`MoveCommand`	Represents an attack command targeting specific coordinates.
`MoveOutcome`	Result of an executed attack with detailed outcome information.
`MoveResult`	Possible outcomes of an attack in Battleship.
`PlayerBoard`	Represents a player's complete board state in Battleship.
`Ship`	Represents a naval vessel on the Battleship game board.
`ShipPlacement`	Represents a ship placement command for board setup.
`ShipPlacementWrapper`	Wrapper for complete fleet placement returned by LLM agents.
`ShipType`	Naval ship types in Battleship with varying sizes and strategic roles.

Module Contents¶

class games.battleship.models.Analysis(/, **data)¶

Bases: pydantic.BaseModel

Strategic analysis of the current Battleship game state.

Analysis provides AI-generated strategic assessment of board position, target priorities, and recommended actions. This enables sophisticated decision-making beyond simple random or pattern-based targeting.

The analysis system considers ship placement probabilities, hit patterns, remaining fleet composition, and strategic positioning for optimal play.

Parameters:: data (Any)

analysis¶

Detailed strategic assessment text.

Type:: str

priority_targets¶

High-value coordinates for next attacks.

Type:: Optional[List[Coordinates]]

Examples

Post-hit analysis:

analysis = Analysis(
    analysis="Hit detected at (5,3). Ship orientation unknown. Target adjacent squares to determine ship alignment and continue attack sequence.",
    priority_targets=[
        Coordinates(row=4, col=3),  # North
        Coordinates(row=6, col=3),  # South
        Coordinates(row=5, col=2),  # West
        Coordinates(row=5, col=4),  # East
    ]
)

Probability-based analysis:

analysis = Analysis(
    analysis="Three ships remaining: Carrier, Battleship, Submarine. Focus on areas with sufficient space for large ships. Avoid edges where only small ships can fit.",
    priority_targets=[
        Coordinates(row=2, col=4),
        Coordinates(row=3, col=6),
        Coordinates(row=7, col=2)
    ]
)

Cleanup analysis:

analysis = Analysis(
    analysis="Only Destroyer remains (2 squares). Search remaining unexplored areas systematically. Focus on edge positions and corners.",
    priority_targets=[
        Coordinates(row=0, col=8),
        Coordinates(row=9, col=1),
        Coordinates(row=8, col=9)
    ]
)

Note

Analysis quality directly impacts AI performance. Advanced analysis considers ship placement patterns, probability distributions, and optimal search strategies.

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_targets(targets)¶

Validate and normalize priority target list.

Parameters:: targets (list[Coordinates | dict] | None) – List of target coordinates (Coordinates objects or dicts).
Returns:: Validated target list.
Return type:: List[Coordinates]

class games.battleship.models.Coordinates(/, **data)¶

Bases: pydantic.BaseModel

Represents a coordinate position on the Battleship game board.

Coordinates use a standard (row, col) system with 0-based indexing for a 10x10 grid. This provides precise targeting for naval combat and supports conversion between different coordinate representations.

The coordinate system enables strategic analysis, pattern recognition, and systematic search algorithms for AI targeting systems.

Parameters:: data (Any)

row¶

Row index from 0-9 (top to bottom).

Type:: int

col¶

Column index from 0-9 (left to right).

Type:: int

Examples

Basic coordinate creation:

target = Coordinates(row=3, col=7)
print(f"Targeting {target}")  # Targeting (3, 7)

Coordinate arithmetic for search patterns:

center = Coordinates(row=5, col=5)
adjacent = [
    Coordinates(row=center.row-1, col=center.col),  # North
    Coordinates(row=center.row+1, col=center.col),  # South
    Coordinates(row=center.row, col=center.col-1),  # West
    Coordinates(row=center.row, col=center.col+1),  # East
]

Grid traversal:

all_coordinates = [
    Coordinates(row=r, col=c)
    for r in range(10) for c in range(10)
]

Note

Standard naval notation (A1, B2, etc.) can be converted to/from this coordinate system for human-readable game interfaces.

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.

to_tuple()¶

Convert coordinates to tuple representation.

Returns:: (row, col) tuple for easy comparison and hashing.
Return type:: Tuple[int, int]

Examples

>>> coord = Coordinates(row=3, col=5)
>>> coord.to_tuple()
(3, 5)
>>> coord_set = {coord.to_tuple() for coord in coordinates_list}

property is_corner: bool¶

Check if coordinate is in a corner of the board.

Returns:: True if coordinate is at (0,0), (0,9), (9,0), or (9,9).
Return type:: bool

Note

Corner positions have unique strategic properties for ship placement and targeting algorithms.

property is_edge: bool¶

Check if coordinate is on the edge of the board.

Returns:: True if coordinate is on any board edge.
Return type:: bool

Note

Edge positions limit ship placement options and affect AI search patterns.

class games.battleship.models.GamePhase¶

Bases: str, enum.Enum

Current phase of the Battleship game.

Game phases track progression from initial setup through active combat to completion. Phase tracking enables proper game flow and determines available actions at each stage.

SETUP¶: Initial ship placement phase.

PLAYING¶: Active combat phase with attacks and responses.

ENDED¶: Game completion with victory determined.

Examples

Game flow management:

phase = GamePhase.SETUP
while phase != GamePhase.ENDED:
    if phase == GamePhase.SETUP:
        # Handle ship placement
        phase = GamePhase.PLAYING
    elif phase == GamePhase.PLAYING:
        # Handle combat turns
        if game_over_condition():
            phase = GamePhase.ENDED

Note

Phase transitions are managed by the game controller and determine which operations are valid at any given time.

Initialize self. See help(type(self)) for accurate signature.

class games.battleship.models.MoveCommand(/, **data)¶

Bases: pydantic.BaseModel

Represents an attack command targeting specific coordinates.

Move commands encapsulate player targeting decisions and provide the interface between strategic AI and game execution. Commands include validation and conversion utilities for different coordinate systems.

The command structure supports both human input and AI-generated attacks with consistent validation and error handling.

Parameters:: data (Any)

row¶

Target row index (0-9).

Type:: int

col¶

Target column index (0-9).

Type:: int

Examples

Manual targeting:

attack = MoveCommand(row=5, col=7)
print(f"Attacking {attack}")  # Attacking (5, 7)

AI-generated attacks:

ai_targets = [
    MoveCommand(row=3, col=4),
    MoveCommand(row=3, col=5),
    MoveCommand(row=3, col=6)
]

Coordinate conversion:

attack = MoveCommand(row=2, col=8)
coords = attack.to_coordinates()  # Get Coordinates object

Note

Move commands validate target coordinates are within the 10x10 game board but don’t check for previous attacks (handled by board state).

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.

to_coordinates()¶

Convert move command to Coordinates object.

Returns:: Equivalent coordinate representation.
Return type:: Coordinates

Examples

>>> move = MoveCommand(row=3, col=5)
>>> coords = move.to_coordinates()
>>> coords.row, coords.col
(3, 5)

class games.battleship.models.MoveOutcome(/, **data)¶

Bases: pydantic.BaseModel

Result of an executed attack with detailed outcome information.

Move outcomes provide complete information about attack results, including coordinates, hit status, and ship destruction details. This information drives AI learning and strategic adjustment.

The outcome model supports game state tracking, statistical analysis, and strategic decision-making for future moves.

Parameters:: data (Any)

row¶

Attacked row coordinate.

Type:: int

col¶

Attacked column coordinate.

Type:: int

result¶

Type of outcome (hit, miss, sunk, invalid).

Type:: MoveResult

sunk_ship¶

Type of ship destroyed, if any.

Type:: Optional[ShipType]

Examples

Successful hit outcome:

outcome = MoveOutcome(
    row=3, col=5,
    result=MoveResult.HIT
)

Ship destruction outcome:

outcome = MoveOutcome(
    row=7, col=2,
    result=MoveResult.SUNK,
    sunk_ship=ShipType.DESTROYER
)

Miss outcome:

outcome = MoveOutcome(
    row=1, col=9,
    result=MoveResult.MISS
)

Note

Sunk ship information enables AI to eliminate search areas and adjust targeting priorities for remaining fleet.

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.

validate_sunk_ship_consistency()¶

Validate sunk ship is only specified for SUNK results.

Returns:: Validated outcome.
Return type:: MoveOutcome
Raises:: ValueError – If sunk_ship is specified for non-SUNK results.

class games.battleship.models.MoveResult¶

Bases: str, enum.Enum

Possible outcomes of an attack in Battleship.

Attack results determine game flow, strategic information, and AI decision-making. Each result type provides different levels of information about the target area and ship status.

The result system enables sophisticated AI targeting that can learn from attack outcomes and adjust strategy accordingly.

HIT¶: Attack successfully damaged a ship.

MISS¶: Attack struck empty water.

SUNK¶: Attack destroyed the last undamaged section of a ship.

INVALID¶: Attack targeted previously attacked coordinates.

Examples

Processing attack results:

if result == MoveResult.HIT:
    print("Ship damaged! Continue attacking nearby.")
elif result == MoveResult.SUNK:
    print("Ship destroyed! Search for remaining fleet.")
elif result == MoveResult.MISS:
    print("Miss. Try different area.")
elif result == MoveResult.INVALID:
    print("Already attacked this position.")

AI strategy adjustment:

if result in [MoveResult.HIT, MoveResult.SUNK]:
    # Add adjacent coordinates to high-priority target list
    priority_targets.extend(get_adjacent_coordinates(attack_coords))

Note

Results guide AI targeting algorithms, with hits triggering focused searching and sunk ships enabling area elimination.

Initialize self. See help(type(self)) for accurate signature.

class games.battleship.models.PlayerBoard(/, **data)¶

Bases: pydantic.BaseModel

Represents a player’s complete board state in Battleship.

The player board manages all game state for one player, including ship placement, attack tracking, and game status. This model provides the core game logic for move validation, damage assessment, and victory determination.

The board state enables AI analysis, strategic planning, and game progression tracking with comprehensive rule enforcement.

Parameters:: data (Any)

ships¶

All ships placed on this player’s board.

Type:: List[Ship]

hits¶

Successful enemy attacks against this board.

Type:: List[Coordinates]

misses¶

Failed enemy attacks against this board.

Type:: List[Coordinates]

attacks¶

All attacks made by this player.

Type:: List[Coordinates]

successful_hits¶

Successful attacks made by this player.

Type:: List[Coordinates]

failed_attacks¶

Failed attacks made by this player.

Type:: List[Coordinates]

sunk_ships¶

Ships destroyed on this board.

Type:: List[ShipType]

Examples

Setting up a player board:

board = PlayerBoard()

# Place ships
destroyer_placement = ShipPlacement(
    ship_type=ShipType.DESTROYER,
    coordinates=[Coordinates(row=3, col=4), Coordinates(row=3, col=5)]
)
board.place_ship(destroyer_placement)

Processing an attack:

outcome = board.receive_attack(3, 4)
if outcome.result == MoveResult.HIT:
    print("Ship damaged!")

Checking game status:

if board.all_ships_sunk():
    print("Game over! All ships destroyed.")

Note

Board state is mutable and updates as the game progresses. Each attack modifies the appropriate tracking lists.

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.

all_ships_sunk()¶

Check if all ships on the board have been destroyed.

Returns:: True if all ships are sunk, False otherwise.
Return type:: bool

Examples

>>> board = PlayerBoard()
>>> # ... game progression ...
>>> if board.all_ships_sunk():
...     print("Game over!")

get_occupied_positions()¶

Get all board positions occupied by ships.

Returns:: List of (row, col) coordinates.
Return type:: List[Tuple[int, int]]

Examples

>>> board = PlayerBoard()
>>> # ... place ships ...
>>> occupied = board.get_occupied_positions()
>>> print(f"Ships occupy {len(occupied)} squares")

is_valid_placement(placement)¶

Check if a ship placement is valid on this board.

Parameters:: placement (ShipPlacement) – Proposed ship placement.
Returns:: True if placement is valid, False otherwise.
Return type:: bool

Examples

>>> board = PlayerBoard()
>>> placement = ShipPlacement(ship_type=ShipType.DESTROYER, coordinates=[...])
>>> if board.is_valid_placement(placement):
...     board.place_ship(placement)

place_ship(placement)¶

Place a ship on the board if placement is valid.

Parameters:: placement (ShipPlacement) – Ship placement to execute.
Returns:: True if ship was successfully placed, False otherwise.
Return type:: bool

Examples

>>> board = PlayerBoard()
>>> placement = ShipPlacement(ship_type=ShipType.CRUISER, coordinates=[...])
>>> success = board.place_ship(placement)
>>> print(f"Placement {'successful' if success else 'failed'}")

receive_attack(row, col)¶

Process an attack against this board.

Parameters:

row (int) – Target row coordinate.
col (int) – Target column coordinate.

Returns:

Result of the attack with detailed information.

Return type:

MoveOutcome

Examples

>>> board = PlayerBoard()
>>> # ... place ships ...
>>> outcome = board.receive_attack(3, 4)
>>> print(f"Attack result: {outcome.result}")

property damage_taken: int¶

Calculate total damage (hits) received.

Returns:: Number of ship squares that have been hit.
Return type:: int

property ships_remaining: int¶

Count ships that are still afloat.

Returns:: Number of ships not yet sunk.
Return type:: int

property total_ship_squares: int¶

Calculate total squares occupied by all ships.

Returns:: Total ship squares on the board.
Return type:: int

class games.battleship.models.Ship(/, **data)¶

Bases: pydantic.BaseModel

Represents a naval vessel on the Battleship game board.

Ships are the primary game entities, each with a specific type, size, position, and damage state. Ship management includes placement validation, hit tracking, and sunk status determination.

The ship model supports sophisticated damage tracking and strategic analysis for AI decision-making, including damage assessment and targeting priority calculations.

Parameters:: data (Any)

ship_type¶

The class of naval vessel.

Type:: ShipType

size¶

Number of grid squares occupied by the ship.

Type:: int

coordinates¶

All positions occupied by the ship.

Type:: List[Coordinates]

hits¶

Number of successful attacks against this ship.

Type:: int

Examples

Creating a horizontal destroyer:

destroyer = Ship(
    ship_type=ShipType.DESTROYER,
    size=2,
    coordinates=[
        Coordinates(row=3, col=4),
        Coordinates(row=3, col=5)
    ]
)

Vertical aircraft carrier placement:

carrier = Ship(
    ship_type=ShipType.CARRIER,
    size=5,
    coordinates=[
        Coordinates(row=2, col=1),
        Coordinates(row=3, col=1),
        Coordinates(row=4, col=1),
        Coordinates(row=5, col=1),
        Coordinates(row=6, col=1)
    ]
)

Damage tracking:

ship.hits = 2
if ship.is_sunk:
    print(f"{ship.ship_type} has been destroyed!")

Note

Ship coordinates must form a straight line (horizontal or vertical) and be contiguous. Size must match the ship type’s expected size.

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.

get_occupied_positions()¶

Get all board positions occupied by this ship.

Returns:: List of (row, col) tuples.
Return type:: List[Tuple[int, int]]

Examples

>>> ship = Ship(coordinates=[Coordinates(row=3, col=4), Coordinates(row=3, col=5)])
>>> ship.get_occupied_positions()
[(3, 4), (3, 5)]

validate_ship_consistency()¶

Validate ship size, coordinates, and type consistency.

Returns:: Validated ship instance.
Return type:: Ship
Raises:: ValueError – If ship configuration is invalid.

classmethod validate_size_matches_type(v, info)¶

Validate ship size matches the expected size for its type.

Parameters:

v (int) – Ship size to validate.
info – Validation context with other field values.

Returns:

Validated size.

Return type:

int

Raises:

ValueError – If size doesn’t match expected size for ship type.

property damage_percentage: float¶

Calculate percentage of ship that has been damaged.

Returns:: Damage percentage from 0.0 (undamaged) to 1.0 (sunk).
Return type:: float

Examples

>>> ship = Ship(ship_type=ShipType.CRUISER, size=3, hits=2)
>>> ship.damage_percentage
0.6666666666666666

property is_sunk: bool¶

Check if the ship has been completely destroyed.

Returns:: True if hits equal or exceed ship size.
Return type:: bool

Examples

>>> destroyer = Ship(ship_type=ShipType.DESTROYER, size=2, hits=2)
>>> destroyer.is_sunk
True
>>> carrier = Ship(ship_type=ShipType.CARRIER, size=5, hits=3)
>>> carrier.is_sunk
False

property orientation: str¶

Determine ship orientation on the board.

Returns:: “horizontal”, “vertical”, or “single” for single-square ships.
Return type:: str

Note

Orientation affects targeting strategies and probability calculations.

class games.battleship.models.ShipPlacement(/, **data)¶

Bases: pydantic.BaseModel

Represents a ship placement command for board setup.

Ship placement defines where a naval vessel will be positioned on the game board. This model handles validation of placement rules including size requirements, orientation constraints, and overlap prevention.

The placement system supports both manual positioning and AI-generated ship layouts with comprehensive validation for rule compliance.

Parameters:: data (Any)

ship_type¶

The type of ship being placed.

Type:: ShipType

coordinates¶

All positions the ship will occupy.

Type:: List[Coordinates]

Examples

Horizontal battleship placement:

battleship_placement = ShipPlacement(
    ship_type=ShipType.BATTLESHIP,
    coordinates=[
        Coordinates(row=5, col=2),
        Coordinates(row=5, col=3),
        Coordinates(row=5, col=4),
        Coordinates(row=5, col=5)
    ]
)

Vertical submarine placement:

submarine_placement = ShipPlacement(
    ship_type=ShipType.SUBMARINE,
    coordinates=[
        Coordinates(row=1, col=8),
        Coordinates(row=2, col=8),
        Coordinates(row=3, col=8)
    ]
)

Compact destroyer placement:

destroyer_placement = ShipPlacement(
    ship_type=ShipType.DESTROYER,
    coordinates=[
        Coordinates(row=9, col=0),
        Coordinates(row=9, col=1)
    ]
)

Note

Placement validation ensures ships don’t overlap, stay within board boundaries, and maintain proper size and orientation.

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_coordinates(coords)¶

Validate and normalize coordinate list.

Parameters:: coords (list[Coordinates | dict]) – List of coordinates (Coordinates objects or dicts).
Returns:: Validated coordinate list.
Return type:: List[Coordinates]
Raises:: ValueError – If coordinates are invalid format.

validate_placement_rules()¶

Validate ship placement follows game rules.

Returns:: Validated placement.
Return type:: ShipPlacement
Raises:: ValueError – If placement violates game rules.

class games.battleship.models.ShipPlacementWrapper(/, **data)¶

Bases: pydantic.BaseModel

Wrapper for complete fleet placement returned by LLM agents.

This model validates that a complete, legal fleet has been specified with all required ship types and no duplicates or overlaps. Used for AI-generated ship arrangements and setup validation.

The wrapper ensures fleet completeness and provides structured error reporting for invalid configurations during automated setup.

Parameters:: data (Any)

placements¶

Complete list of ship placements for one fleet.

Type:: List[ShipPlacement]

Examples

Complete fleet setup:

fleet = ShipPlacementWrapper(
    placements=[
        ShipPlacement(ship_type=ShipType.CARRIER, coordinates=[...]),
        ShipPlacement(ship_type=ShipType.BATTLESHIP, coordinates=[...]),
        ShipPlacement(ship_type=ShipType.CRUISER, coordinates=[...]),
        ShipPlacement(ship_type=ShipType.SUBMARINE, coordinates=[...]),
        ShipPlacement(ship_type=ShipType.DESTROYER, coordinates=[...])
    ]
)

Fleet validation:

try:
    fleet = ShipPlacementWrapper(placements=ai_generated_placements)
    print("Fleet configuration is valid")
except ValueError as e:
    print(f"Invalid fleet: {e}")

Note

This wrapper enforces that exactly one ship of each type is included in the fleet, preventing duplicate or missing ships.

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.

validate_complete_fleet()¶

Validate fleet contains exactly one ship of each type.

Returns:: Validated fleet.
Return type:: ShipPlacementWrapper
Raises:: ValueError – If fleet is incomplete or has duplicates.

class games.battleship.models.ShipType¶

Bases: str, enum.Enum

Naval ship types in Battleship with varying sizes and strategic roles.

Each ship type represents a different class of naval vessel with unique characteristics. Ship variety adds strategic depth through different target profiles and placement considerations.

The traditional Battleship fleet composition balances large, valuable targets (carriers, battleships) with smaller, harder-to-find vessels (destroyers, submarines).

CARRIER¶: Largest ship, primary strategic target (5 squares).

BATTLESHIP¶: Heavy combat vessel, major threat (4 squares).

CRUISER¶: Balanced warship, versatile platform (3 squares).

SUBMARINE¶: Stealth vessel, hard to detect (3 squares).

DESTROYER¶: Fast escort ship, smallest target (2 squares).

Examples

Fleet composition analysis:

fleet = [ShipType.CARRIER, ShipType.BATTLESHIP, ShipType.CRUISER,
        ShipType.SUBMARINE, ShipType.DESTROYER]
total_squares = sum(SHIP_SIZES[ship] for ship in fleet)  # 17 squares

Strategic targeting priority:

high_value_targets = [ShipType.CARRIER, ShipType.BATTLESHIP]
stealth_targets = [ShipType.SUBMARINE]
quick_targets = [ShipType.DESTROYER]

Note

Ship types follow traditional naval classifications and provide different strategic value in terms of size, placement difficulty, and target priority for AI decision-making.

Initialize self. See help(type(self)) for accurate signature.