haive.games.mancala.models

Comprehensive data models for the Mancala (Kalah) board game.

This module defines the complete set of data structures for the traditional Mancala game, providing models for move validation, strategic analysis, and game state representation. The implementation follows standard Kalah rules with 6 pits per player and seed redistribution mechanics.

Mancala is a classic strategy game involving: - Two players with 6 pits each plus one store (mancala) - Seed sowing mechanics with capture rules - Strategic pit selection for optimal play - Turn continuation and capture bonus rules

Key Models:

MancalaMove: Represents a player’s pit selection MancalaAnalysis: Strategic evaluation for AI decision-making

Examples

Making moves:

from haive.games.mancala.models import MancalaMove

# Select pit 2 for player 1
move = MancalaMove(pit_index=2, player="player1")

# Strategic center play
center_move = MancalaMove(pit_index=3, player="player2")

Strategic analysis:

from haive.games.mancala.models import MancalaAnalysis

analysis = MancalaAnalysis(
    captures_possible=[2, 4],
    free_turns_available=[1, 3],
    pit_values=[4, 3, 2, 5, 1, 6],
    strategy="Focus on pit 3 for free turn opportunity"
)

The models support AI strategy development with comprehensive validation and integration with the Mancala game engine.

Classes

MancalaAnalysis	Analysis of a Mancala position.
MancalaMove	Represents a move in Mancala.

Module Contents

class haive.games.mancala.models.MancalaAnalysis(/, **data)

Bases: pydantic.BaseModel

Analysis of a Mancala position.

This class defines the structure of an analysis for a Mancala position, which includes the overall position evaluation, advantage level, stone distribution, pit recommendations, strategic focus, key tactics, and reasoning.

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.

Parameters:

data (Any)

class haive.games.mancala.models.MancalaMove(/, **data)

Bases: pydantic.BaseModel

Represents a move in Mancala.

This class defines the structure of a move in Mancala, which includes the pit index to sow from and the player making the move.

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.

Parameters:

data (Any)

classmethod validate_pit_index(v, info)

Validate that the pit index is valid for the player.

Parameters:

• v (int) – The pit index to validate.

• info (pydantic.ValidationInfo) – Validation info containing other field values.

Returns:

The validated pit index.

Raises:

ValueError – If pit index is out of valid range.

Return type:

int