CoolFace
Apppublic

ShubhanshuBansod/connect-four-ai

sourceHugging Facecc-by-nc-sa-4.0updated 11mo agoView on Hugging Face
0likes
App README

🎮 Connect Four AI with Explainability

A fully interpretable Connect Four game AI powered by Minimax + Alpha-Beta Pruning with LLM-generated natural language explanations. Play against an intelligent opponent that explains its strategic decisions in real-time.

🌟 Features

✅ Intelligent AI Opponent

  • —Minimax algorithm with alpha-beta pruning
  • —Adjustable difficulty (depth 3-10)
  • —Real-time algorithm statistics (nodes explored, pruning efficiency)

✅ Explainability Layer

  • —LLM-powered move explanations in natural language
  • —Strategic threat analysis
  • —Human-friendly decision insights
  • —No technical jargon—easy to understand

✅ Interactive Web Interface

  • —Play directly in your browser
  • —Real-time board updates
  • —Game controls (New Game, Undo)
  • —Mobile-friendly design

✅ Educational Value

  • —Learn classical game theory (Minimax, Alpha-Beta Pruning)
  • —Understand neuro-symbolic AI (classical algorithms + LLM)
  • —See interpretable AI in action

🎯 How It Works

1. Game Logic (connect_four_game.py)

  • —6×7 board state management
  • —Move validation and winner detection
  • —Threat analysis (3-in-a-row, center control)

2. AI Decision Making (minimax_ai.py)

  • —Minimax algorithm explores possible moves
  • —Alpha-beta pruning eliminates unnecessary branches
  • —Heuristic board evaluation (threats, board control)
  • —Returns move score and algorithm statistics

3. Natural Language Explanations (llm_explanation.py)

  • —Converts algorithm output to human-readable insights
  • —Uses HuggingFace Inference API (Mistral-7B LLM)
  • —Graceful fallback if API unavailable

4. Interactive UI (app.py)

  • —Built with Streamlit
  • —Real-time game state display
  • —Move selection dropdown
  • —Algorithm statistics & explanations

🚀 Quick Start

Prerequisites

  • —HuggingFace account (free at https://huggingface.co)
  • —HuggingFace API token (get it here)

Setup (Already Running on Spaces!)

This Space is ready to use! Just:

  1. 1.Play! Select a column (0-6) and click "Play"
  2. 2.Watch AI think - See the AI analyze and make its move
  3. 3.Read explanations - Understand why it chose that move
  4. 4.Adjust difficulty - Use the sidebar slider to change AI strength (3-10)
  5. 5.New game - Click "New Game" to restart

🎮 How to Play

  1. 1.Select a Column: Choose where to drop your piece (0-6, left to right)
  2. 2.AI Responds: AI analyzes and plays its move
  3. 3.See Explanations: Read why AI chose that move
  4. 4.Repeat: Continue until someone wins or board is full
  5. 5.Adjust Difficulty: Use the slider to change AI strength (3-10)

Game Rules

  • —Standard Connect Four: 6 rows × 7 columns
  • —First to get 4 pieces in a row (horizontal, vertical, or diagonal) wins
  • —If board fills with no winner = Draw

📊 Understanding the Algorithm

Minimax Algorithm

  • —Explores all possible moves (up to search depth)
  • —Assigns scores: +1000 for wins, -1000 for losses, 0 for neutral
  • —AI chooses move with highest score

Alpha-Beta Pruning

  • —Eliminates unnecessary branches during search
  • —Typically reduces nodes explored by 80-90%
  • —Makes deep searches feasible in real-time

Heuristics

  • —Threat Detection: 3-in-a-row patterns
  • —Center Control: Pieces in center are valuable
  • —Piece Count: More pieces = better position

Statistics Displayed

  • —Nodes Explored: Total positions analyzed
  • —Nodes Pruned: Branches eliminated by alpha-beta
  • —Pruning Efficiency: % of branches skipped
  • —Search Depth: Moves ahead analyzed
  • —Response Time: How long AI took to decide

🤖 LLM Explanations

This Space uses HuggingFace Inference API with Mistral-7B to generate explanations.

What Explanations Include

  • —Strategic Insight: Why this move is strong
  • —Threat Analysis: What patterns it creates/blocks
  • —Board Evaluation: How good the position is
  • —Human Language: No technical jargon

Rate Limiting

  • —Free tier: ~1000 API calls/day (~100-200 game moves)
  • —If limit hit: Automatic fallback explanations (game still works!)
  • —Reset: Resets every 24 hours

⚙️ Configuration

Adjust AI Difficulty

Use the sidebar slider:

  • —3-4: Easy (quick decisions, basic strategy)
  • —5-6: Medium (balanced thinking, ~400ms)
  • —7-8: Hard (deep analysis, ~800ms)
  • —9-10: Very Hard (exhaustive search, 1-2 seconds)

🔧 Troubleshooting

"HuggingFace Token Not Found"

  • —Contact Space owner to verify token is set
  • —Token should be added to Spaces Secrets (HF_TOKEN)

"Rate limit exceeded"

  • —Wait 24 hours for limit reset (free tier)
  • —Or upgrade to HF Pro for higher limits

Slow responses

  • —Reduce search depth using the sidebar slider
  • —This makes AI think faster

App won't load

  • —Refresh page
  • —Clear browser cache
  • —Try a different browser

📈 Performance

Response Times

  • —Move Decision: 300-800ms (depends on difficulty)
  • —Explanation: 2-5 seconds (HuggingFace API)
  • —Total Response: 3-6 seconds
  • —Uptime: 24/7 (always available on Spaces)

🎓 Learning Outcomes

Playing with this AI, you'll understand:

✅ Classical AI Algorithms

  • —Minimax decision-making
  • —Alpha-beta pruning optimization
  • —Game tree search strategies

✅ Modern AI Explainability

  • —Neuro-symbolic AI (classical + LLM)
  • —Natural language generation for AI decisions
  • —Bridging the gap between algorithms and humans

✅ Game Theory Concepts

  • —Perfect information games
  • —Heuristic evaluation functions
  • —Strategic thinking and threat detection

📁 File Structure

connect-four-ai/
├── app.py                    # Streamlit UI (main entry point)
├── connect_four_game.py      # Game engine & logic
├── minimax_ai.py             # AI decision-making algorithm
├── llm_explanation.py        # Move explanations (HF API)
├── requirements.txt          # Dependencies
├── .streamlit/
│   └── config.toml           # Streamlit theme config
└── README.md                 # This file

📝 License

This project is licensed under CC BY-NC-SA 4.0 (Creative Commons Attribution-NonCommercial-ShareAlike 4.0)

You are free to:

  • —✅ Use this project for educational purposes
  • —✅ Modify and adapt the code
  • —✅ Share derivatives under same license

With conditions:

  • —⚠️ Give credit to original author
  • —⚠️ Do not use commercially (without permission)
  • —⚠️ Share modifications under same CC BY-NC-SA 4.0 license

For details: https://creativecommons.org/licenses/by-nc-sa/4.0/

🙌 Credits & Acknowledgments

  • —Minimax Algorithm: Classical computer science (Shannon, 1950s)
  • —Alpha-Beta Pruning: Optimization technique (Knuth & Moore, 1970s)
  • —Streamlit: Web UI framework (Streamlit Inc.)
  • —HuggingFace: LLM inference & Spaces hosting
  • —Mistral AI: Language model provider

📚 References & Further Reading

Algorithms

  • —Minimax: https://en.wikipedia.org/wiki/Minimax
  • —Alpha-Beta Pruning: https://en.wikipedia.org/wiki/Alpha%E2%80%93beta_pruning
  • —Game Theory: https://en.wikipedia.org/wiki/Combinatorialgametheory

AI Explainability

  • —Neuro-Symbolic AI: https://arxiv.org/abs/2106.08561
  • —Interpretable ML: https://christophm.github.io/interpretable-ml-book/

Tools & Frameworks

  • —Streamlit: https://streamlit.io
  • —HuggingFace: https://huggingface.co
  • —HuggingFace Spaces: https://huggingface.co/docs/hub/spaces

🎉 Have Fun!

This project demonstrates:

  • —✅ Classical AI algorithms (Minimax, Alpha-Beta Pruning)
  • —✅ Modern AI interpretability (LLM explanations)
  • —✅ Full-stack web development (Python + Streamlit)
  • —✅ Cloud deployment (HuggingFace Spaces)

Start playing and learning today! 🚀

Last Updated: November 2025 License: CC BY-NC-SA 4.0 Python Version: 3.9+ Framework: Streamlit 1.28.1+