AI_DEV_REFERENCE.py

"""
Bao la Kiswahili — AI Module Developer Reference

This file documents the public API that all AI/analysis/training/UI modules
must use. Read this before writing any module.

## Core Classes (bao.board)

### GameState
    - .board: BaoBoard  (4x8 grid of seed counts)
    - .hands: dict {SOUTH: int, NORTH: int} — seeds in hand (nemo)
    - .phase: str  'namua' | 'mtaji'
    - .turn: str   'south' | 'north'
    - .nyumba_status: dict {SOUTH: str, NORTH: str} — 'functional' | 'destroyed'
    - .captures: dict {SOUTH: int, NORTH: int} — total captured seeds
    - .move_count: int
    - .move_history: list[MoveResult]
    - .takasia_pits: dict {player: set of (row, col)}
    
    Methods:
    - .clone() -> GameState  (deep copy for search)
    - .is_nyumba(player, row, col) -> bool
    - .is_functional_nyumba(player, row, col) -> bool
    - .destroy_nyumba(player) -> None
    - .switch_turn() -> None

### BaoBoard
    - .grid: list[list[int]]  4 rows x 8 cols
    - .get(row, col) -> int
    - .set(row, col, value)
    - .add(row, col, amount=1)
    - .take_all(row, col) -> int  (removes and returns all seeds)
    - .is_empty(row, col) -> bool
    - .clone() -> BaoBoard
    - .total_seeds() -> int
    - .player_seeds(player) -> int  (both rows)
    - .inner_row_seeds(player) -> int

### Move
    - .move_type: str  'namua' | 'mtaji'
    - .player: str    'south' | 'north'
    - .col: int        (namua: inner row col; mtaji: pit col)
    - .row: int         (mtaji: pit row; namua: -1)
    - .direction: str   'cw' | 'ccw' (for non-capture sowing choice)
    - .is_capture: bool
    - .safari_choice: bool  (True = continue from nyumba)

### MoveResult
    - .move: Move
    - .player: str
    - .seeds_captured: int
    - .laps: int
    - .ended_in_nyumba: bool
    - .nyumba_destroyed: bool
    - .phase_after: str
    - .board_before: BaoBoard
    - .board_after: BaoBoard

## Engine Functions (bao.engine)

    - get_valid_moves(state, player) -> list[Move]
    - execute_move(state, move) -> MoveResult  (mutates state!)
    - check_game_over(state) -> str | None  (returns winner or None)
    - is_terminal(state) -> bool
    - winner(state) -> str | None
    - seed_difference(state, player) -> int
    - count_seeds(state, player) -> int  (board + hand)
    - is_marker(state, player, row, col) -> bool
    - has_capture_available(state, player) -> bool
    - has_mtaji_capture(state, player) -> bool
    - build_sow_path(player, direction, start_row, start_col, length) -> list[(row,col)]
    - get_board_display(state) -> str

## Config Constants (bao.config)

    SOUTH = 'south', NORTH = 'north'
    NAMUA = 'namua', MTAJI = 'mtaji'
    CCW = 'ccw', CW = 'cw'
    OPPONENT = {SOUTH: NORTH, NORTH: SOUTH}
    
    PLAYER_INNER_ROW = {SOUTH: 2, NORTH: 1}
    PLAYER_BACK_ROW = {SOUTH: 3, NORTH: 0}
    PLAYER_NYUMBA_COL = {SOUTH: 3, NORTH: 4}
    PLAYER_RIGHT_KICHWA = {SOUTH: 0, NORTH: 7}
    PLAYER_LEFT_KICHWA = {SOUTH: 7, NORTH: 0}
    
    Rows: 0=N-back, 1=N-inner, 2=S-inner, 3=S-back

## AI Base Class (bao.ai.base)

    class BaoAI(ABC):
        def __init__(self, name, **kwargs)
        @abstractmethod
        def select_move(self, state) -> Move | None
        def evaluate(self, state, player) -> float  (override this!)
        @property
        def name(self) -> str
        def reset(self) -> None
        def get_stats(self) -> dict

All AI modules MUST:
    1. Inherit from BaoAI
    2. Implement select_move(state) -> Move
    3. Call self.nodes_evaluated += 1 in search loops
    4. Accept **kwargs in __init__ and pass to super()
    5. Be importable without side effects

## Module File Conventions

    - Each module is one .py file in the appropriate package
    - File starts with a docstring describing the strategy
    - Classes use PascalCase, functions use snake_case
    - No external dependencies beyond Python stdlib + bao package
    - Each file is self-contained (imports from bao.* only)
    - Include a __all__ list
"""