bitbully.agent_interface.Connect4Agent Class Reference

Inheritance diagram for bitbully.agent_interface.Connect4Agent:

Collaboration diagram for bitbully.agent_interface.Connect4Agent:

Public Member Functions
dict[int, int]	score_all_moves (self, Board board)
int	best_move (self, Board board)
int	score_move (self, Board board, int column, int first_guess=0)

Detailed Description

Minimal interface a Connect-4 agent must implement to work with ``GuiC4``.

This interface is intentionally aligned with the public ``BitBully`` API,
but excludes BitBully-specific engine features such as opening-book handling,
node counters, transposition tables, and specialized search entry points.

Required methods:
    - ``score_all_moves``: Provide integer evaluations for all *legal* moves.
    - ``best_move``: Select one legal move using BitBully-compatible
      tie-breaking semantics.

Notes on scoring:
    - Scores are integers where **larger values are better** for the side to move.
    - The absolute scale is agent-defined.
    - The GUI only relies on *relative ordering* and legality.

Example:
    Minimal agent compatible with the `Connect4Agent` protocol:

    ```python
    import random
    from bitbully import Board

    # Importing the Protocol is optional at runtime, but useful for:
    #  - static type checking (mypy / pyright)
    #  - documenting that this class satisfies the agent interface
    from bitbully.agent_protocols import Connect4Agent


    class RandomAgent:
        '''Agent that plays a random legal move.

        This class does NOT inherit from ``Connect4Agent``.
        It is compatible because it implements the required methods
        with matching signatures (structural typing).
        '''

        def score_all_moves(self, board: Board) -> dict[int, int]:
            # Only legal columns may appear in the result.
            # The GUI and other consumers rely on this contract.
            return {c: 0 for c in board.legal_moves()}

        def best_move(self, board: Board) -> int:
            # Consumers may call only ``best_move`` if they are
            # not interested in individual move scores.
            return random.choice(board.legal_moves())


    board = Board("332311")

    # The variable annotation enforces the protocol at type-check time.
    agent: Connect4Agent = RandomAgent()

    move = agent.best_move(board)
    board.play(move)
    ```

Definition at line 18 of file agent_interface.py.

Member Function Documentation

best_move()

int bitbully.agent_interface.Connect4Agent.best_move	(		self,
		Board	board )

Return the best legal move (column index) for the side to move.

Args:
    board (Board):
        Current Connect-4 board position.

Returns:
    int:
        Selected column index in the range ``0..6``.

Definition at line 95 of file agent_interface.py.

score_all_moves()

dict[int, int] bitbully.agent_interface.Connect4Agent.score_all_moves	(		self,
		Board	board )

Score all legal moves for the given board state.

Args:
    board (Board):
        Current Connect-4 board position.

Returns:
    dict[int, int]:
        Mapping ``{column: score}`` for all *legal* columns (0..6).
        Columns that are full or illegal **must not** appear in the mapping.

Notes:
    - Higher scores indicate better moves.
    - The returned dictionary may contain between 0 and 7 entries.

Definition at line 77 of file agent_interface.py.

score_move()

int bitbully.agent_interface.Connect4Agent.score_move	(		self,
		Board	board,
		int	column,
		int	first_guess = 0 )

Evaluate a single legal move for the given board state.

This method is optional and not required by the GUI, but can be useful
for agents that support fine-grained move evaluation.

Args:
    board (Board):
        Current Connect-4 board position.
    column (int):
        Column index (0..6) of the move to evaluate.
    first_guess (int):
        Optional initial guess for iterative or search-based agents.
        Implementations may safely ignore this parameter.

Returns:
    int:
        Evaluation score for the given move.

Definition at line 111 of file agent_interface.py.

---

The documentation for this class was generated from the following file:

• src/bitbully/agent_interface.py