How guilhermekotchergenko/connect-4-ai works
Project Type and Purpose
• This is a standalone Python application plus a companion Jupyter notebook for running experiments.
• It implements a Connect Four game engine, multiple AI agents (ID3, ensemble bagging, MCTS, parallel MCTS), a terminal‐based UI, data logging, model training, and visualization (Graphviz + matplotlib).
High-Level Components
a. User Interfaces
• Terminal CLI (main.py in “Nanahira Connect 4!”)
• Jupyter Notebook (connect_four.ipynb)
b. Core Game Engine
• State representation (board.py, constants.py)
• Rule enforcement & win detection
c. AI Agents
• Random baseline
• ID3 Decision Tree (ai_id3.py + train logic)
• Bagging Ensemble (ensemble builder, majority vote)
• Monte-Carlo Tree Search (ai_mcts.py, parallel via multiprocessing)
d. Orchestration & Menus
• Menu modules (menu.py, MenuAISelection.py, *ConfigMenu.py) for steering game mode and AI selection
e. Persistence & Data
• CSV logs: datasets/match_log.csv & Nanahira/match_log.csv
• Model snapshots: *.pkl + *.hash under Nanahira
f. Visualization & Reporting
• Graphviz exports (images/*.dot → .png via external graphviz)
• Matplotlib plots (images/)
g. External Dependencies
• Graphviz system install
• Python libraries (listed in requirements.txt)
• Multiprocessing for parallel MCTS
Relationships and Data Flows
• User (CLI or Notebook) → invokes Orchestration layer → Game Engine.
• Game Engine → calls selected AI Agent to compute next move.
• After each game: Orchestration → appends flattened game history to datasets/<match_log>.
• Triggering a tree‐based AI → reads full CSV log → retrains model → writes *.pkl + *.hash.
• Optional: Notebook → batch runs multiple match-ups → writes performance logs → generates plots.
• Visualization modules invoke Graphviz CLI to render .dot files into .png.
Architectural Patterns & Design Principles
• Modular separation: UI (menus) vs. core engine vs. AI plugins vs. persistence vs. visualization.
• Pluggable AI components behind a common “Agent” interface in HandleAivsAI.py / HandlePvaiId3.py.
• Self-play training loop: closed‐loop feedback for model re‐training.
• Concurrency: MCTS parallel rollouts via Python’s multiprocessing module.
Essential Elements Checklist
[ ] Call out external Graphviz and multiprocessing