Skip to content

About

๐Ÿค– A browser-based Connect Four game featuring an Minimax AI opponent with Alpha-Beta pruning, plus a LLM powered AI coach to explain game strategy! ๐Ÿ‘พ Built with Python, Flask, and OpenAI.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

ย 

History

1 Commit

Folders and files

NameName
Last commit message
Last commit date
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

๐Ÿค– Connect Four AI ๐Ÿ‘พ

A browser based Connect Four game where the AI opponent thinks before it makes a move!

Note: While this project was primarily vibe-coded, all code was manually typed, reviewed, and adjusted as needed by myself.

Python 3.12 Flask 3.1 OpenAI API


๐Ÿค” How does it work?

I built this project to develop my Python skills and learn how to create a game where I can play against an AI opponent that uses actual logic before acting.

It's the classic Connect Four game where pieces are dropped into a column, and the first player to get four in a row wins. The twist is that you're playing against a computer opponent that looks several moves into the future** before it decides where to go. It isn't guessing and it isn't following a script. It plays out possible pathways, scores them, and picks the one that works out best for it.

On top of that, there's an optional AI coach that explains why the computer made each move in plain English.


๐ŸŽฎ How to play ๐ŸŽฒ

๐Ÿซก Pick a difficulty: Easy, Medium, or Hard.
๐Ÿ“ Click any column to drop your red piece.
๐Ÿค– The AI answers with a yellow piece a split second later.
๐Ÿ“– Read the panel under the board to see how many positions the AI checked and why it chose that column.
๐Ÿซถ๐Ÿป Click Ask the AI coach if you want a friendlier explanation.

๐Ÿง  How the AI thinks ๐Ÿง

Imagine you're about to make a move. A good player doesn't just ask "what looks good right now?" They ask:

"If I go here, what's the smartest thing my opponent could do back? And what would I do after that?"

That's exactly what my AI opponenet does. It uses an algorithm called minimax:

  • On its own turn, it picks the move with the highest score.
  • On your turn, it assumes you'll pick the move that's worst for it.

Assuming you'll always play perfectly might sound pessimistic, but it's what makes the AI hard to trick. It never walks into a trap hoping you won't notice.

There are way too many possibilities for wining a game, so it only looks a few moves ahead and then makes an educated guess based off the current board status. The computer is programed to view winning the game in tiers it can understand. It views the rewards as shown below:

Pattern on the boardWhat the AI thinks about it
Four in a row๐Ÿ† A win. Nothing beats this.
Three in a row with an open space๐Ÿ‘ One move away from winning
Two in a row with room to grow๐Ÿ™‚ A decent start
Pieces in the middle column๐Ÿ“ The center is part of the most winning lines
You having three in a row๐Ÿšจ Danger! Block it โ€” and this matters slightly more than building its own threat

I also added a speed trick called alpha-beta pruning. If the AI already knows a move is good, it stops wasting time on moves that clearly can't beat it. The final choice is exactly the same, it just gets there much faster.


๐Ÿ“Š Difficulty levels

Level How far ahead it looks Positions it checks What it feels like
๐ŸŸข Easy 1 move ~8 Makes random moves. Very beatable.
๐ŸŸก Medium 4 moves ~500 Blocks your obvious threats and sets up its own.
๐Ÿ”ด Hard 6 moves ~3,000 Very tough, the computer views you as a threat.

๐Ÿ—บ๏ธ How the pieces fit ๐Ÿงฉ

flowchart TD
    A["๐Ÿ–ฑ๏ธ You click a column<br/>(game.js)"] -->|"POST /api/move"| B["๐ŸŒ Flask server<br/>(app.py)"]
    B --> C["๐Ÿ“ Rules engine<br/>(game/board.py)"]
    B --> D["๐Ÿง  Minimax AI<br/>(game/ai.py)"]
    D --> C
    B --> E["๐Ÿ’ฌ Coach<br/>(game/coach.py)"]
    E -.->|"only if an API key is set"| F["โœจ OpenAI API"]
    B -->|"JSON"| A
Loading

I kept each part in its own file with its own job:

FileIts one job
game/board.pyThe rules. Is this move legal? Did someone win?
game/ai.pyThe brain. Which column should the computer play?
game/coach.pyThe explainer. Why did it play that?
app.pyThe messenger between the browser and the game.
templates/ and static/What you see and click on.

The rules file (board.py) doesn't know a website exists at all. This means that the game logic can be tested without starting a server, and I could reuse it for a totally different version of the game later.


๐Ÿš€ Run it yourself! ๐ŸŽฏ

The quickest way is GitHub Codespaces: click the green Code button above โ†’ Codespaces โ†’ Create codespace on main. Everything installs itself.

To run it on your own computer instead:

git clone <repository URL>
python -m venv .venv
source .venv/bin/activate        
pip install -r requirements.txt
python app.py

Then open http://localhost:5000 in your browser.

๐Ÿ’ก In Codespaces, localhost won't work from your own browser. Go to the Ports tab at the bottom of VS Code and click the ๐ŸŒ globe icon next to port 5000.


๐Ÿ“š Words I had to learn while building this (click to open)
TermWhat it means in plain English
MinimaxPick your best move while assuming your opponent always picks their best move back.
Alpha-beta pruningSkip checking moves that can't possibly change the final decision.
HeuristicAn educated guess used when calculating the perfect answer would take too long.
PlyOne move by one player. "Looking 4 plies ahead" means my move, your move, my move, your move.
RecursionA function that calls itself to solve a smaller version of the same problem.
FlaskA Python tool that turns functions into web pages and web addresses.
API routeA web address the browser sends data to, like /api/move.
SessionA small, signed piece of data that remembers your game between clicks, so you can't cheat by editing it.
Environment variableA setting stored outside the code. It's how secrets like API keys stay out of GitHub.

Results ๐Ÿšฉ

Results Screen

Thank you for stopping by!

About

๐Ÿค– A browser-based Connect Four game featuring an Minimax AI opponent with Alpha-Beta pruning, plus a LLM powered AI coach to explain game strategy! ๐Ÿ‘พ Built with Python, Flask, and OpenAI.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages