README changed

README.md

@@ -1,3 +1,15 @@
+---
+title: Connect Four AI with Explainability
+emoji: 🎮
+colorFrom: blue
+colorTo: red
+sdk: streamlit
+sdk_version: "1.28.1"
+app_file: app.py
+pinned: false
+license: cc-by-nc-sa-4.0
+---
+
 # 🎮 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.
@@ -43,9 +55,9 @@ A fully interpretable Connect Four game AI powered by **Minimax + Alpha-Beta Pru
 - Heuristic board evaluation (threats, board control)
 - Returns move score and algorithm statistics
 
-### 3. **Natural Language Explanations** (`llm_explanation.py` or `llm_explanation_hf.py`)
+### 3. **Natural Language Explanations** (`llm_explanation.py`)
 - Converts algorithm output to human-readable insights
-- Uses LLM (Ollama locally or HuggingFace API on Spaces)
+- Uses HuggingFace Inference API (Mistral-7B LLM)
 - Graceful fallback if API unavailable
 
 ### 4. **Interactive UI** (`app.py`)
@@ -56,97 +68,21 @@ A fully interpretable Connect Four game AI powered by **Minimax + Alpha-Beta Pru
 
 ---
 
-## 🚀 Quick Start (HuggingFace Spaces)
+## 🚀 Quick Start
 
 ### Prerequisites
 - HuggingFace account (free at https://huggingface.co)
 - HuggingFace API token (get it [here](https://huggingface.co/settings/tokens))
 
-### Deployment (10 minutes)
-
-1. **Create a new Space**
-   - Go to https://huggingface.co/spaces
-   - Click "Create new Space"
-   - Choose "Streamlit" as SDK
-   - Name it `connect-four-ai`
-
-2. **Add your HF Token as Secret**
-   - Go to Space Settings → Secrets and variables
-   - Add: `HF_TOKEN` = your token from step above
-   - Click Save
-
-3. **Upload Files**
-   - In Files tab, upload:
-     - `app.py`
-     - `connect_four_game.py`
-     - `minimax_ai.py`
-     - `llm_explanation.py`
-     - `requirements.txt`
-   - Create `.streamlit/` folder and upload `config.toml`
-
-4. **Wait for Build**
-   - Space will auto-deploy (1-2 minutes)
-   - Once ready, click the app URL to play!
-
-**That's it! Your AI is now live! 🎉**
-
----
-
-## 💻 Local Installation
-
-### Requirements
-- Python 3.9+
-- Ollama (for local LLM inference)
+### Setup (Already Running on Spaces!)
 
-### Steps
+This Space is ready to use! Just:
 
-1. **Clone or download this repository**
-   ```bash
-   git clone <your-repo-url>
-   cd connect-four-ai
-   ```
-
-2. **Install Ollama**
-   - Download from https://ollama.ai
-   - Run: `ollama pull phi3:latest` (or your preferred model)
-
-3. **Install Python dependencies**
-   ```bash
-   pip install -r requirements.txt
-   ```
-
-4. **Start Ollama** (in a separate terminal)
-   ```bash
-   ollama serve
-   ```
-
-5. **Run the app**
-   ```bash
-   streamlit run app.py
-   ```
-
-6. **Play!**
-   - App opens at `http://localhost:8501`
-   - Select a column and click Play
-   - Watch AI analyze and explain its moves
-
----
-
-## 📋 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 (local Ollama)
-├── llm_explanation_hf.py       # Move explanations (HF Spaces)
-├── requirements.txt            # Dependencies (local)
-├── requirements_hf.txt         # Dependencies (HF Spaces)
-├── .streamlit/
-│   └── config.toml             # Streamlit theme config
-└── README.md                   # This file
-```
+1. **Play!** Select a column (0-6) and click "Play"
+2. **Watch AI think** - See the AI analyze and make its move
+3. **Read explanations** - Understand why it chose that move
+4. **Adjust difficulty** - Use the sidebar slider to change AI strength (3-10)
+5. **New game** - Click "New Game" to restart
 
 ---
 
@@ -193,17 +129,7 @@ connect-four-ai/
 
 ## 🤖 LLM Explanations
 
-### Local Version (Ollama)
-- Uses Phi-3 or Llama model running on your machine
-- Fast (<1 second)
-- No rate limits
-- Privacy-focused (everything stays local)
-
-### HuggingFace Spaces Version
-- Uses Mistral-7B via HuggingFace Inference API
-- Slightly slower (2-5 seconds)
-- Free tier: ~1000 API calls/day
-- Graceful fallback if rate-limited
+This Space uses **HuggingFace Inference API** with **Mistral-7B** to generate explanations.
 
 ### What Explanations Include
 - **Strategic Insight**: Why this move is strong
@@ -211,84 +137,58 @@ connect-four-ai/
 - **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
-In `app.py`, modify the search depth slider or default:
-```python
-search_depth = st.sidebar.slider("AI Search Depth", 3, 10, 7)
-```
+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)
 
-### Change LLM Model
-In `llm_explanation_hf.py`:
-```python
-self.model = 'mistralai/Mistral-7B-Instruct-v0.3'  # Change this
-```
-Other options: `HuggingFaceH4/zephyr-7b-beta`, `meta-llama/Llama-2-7b-chat`, etc.
-
 ---
 
 ## 🔧 Troubleshooting
 
-### Local (Ollama) Version
-
-**"ollama: command not found"**
-- Install Ollama from https://ollama.ai
-- Make sure `ollama serve` is running in background
-
-**"Connection refused to localhost:11434"**
-- Start Ollama: `ollama serve`
-- Or pull model: `ollama pull phi3:latest`
+### "HuggingFace Token Not Found"
+- Contact Space owner to verify token is set
+- Token should be added to Spaces Secrets (HF_TOKEN)
 
-**Slow responses**
-- Reduce search depth (AI explores fewer moves)
-- Use smaller model: `ollama pull tinyllama:latest`
+### "Rate limit exceeded"
+- Wait 24 hours for limit reset (free tier)
+- Or upgrade to HF Pro for higher limits
 
-### HuggingFace Spaces Version
+### Slow responses
+- Reduce search depth using the sidebar slider
+- This makes AI think faster
 
-**"HuggingFace Token Not Found"**
-- Add `HF_TOKEN` to Spaces Secrets (Settings page)
-- Click Restart button on Space
-- Refresh browser
-
-**"Rate limit exceeded"**
-- Wait 24 hours (free tier resets daily)
-- Upgrade to HF Pro ($9/month)
-- Or use local Ollama instead
-
-**Build errors**
-- Verify all files uploaded to root directory
-- Check `requirements.txt` has correct packages
-- Click Restart button
+### App won't load
+- Refresh page
+- Clear browser cache
+- Try a different browser
 
 ---
 
 ## 📈 Performance
 
-### Local Performance
-- **Move Decision**: 300-800ms (depends on depth)
-- **Explanation**: <1 second (Phi-3 local)
-- **Total Response**: <1 second
-- **Uptime**: While your app is running
-
-### HuggingFace Spaces Performance
-- **Move Decision**: 300-800ms (identical algorithm)
-- **Explanation**: 2-5 seconds (HF API inference)
+### 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)
-- **Rate Limit**: ~1000 calls/day (free tier)
+- **Uptime**: 24/7 (always available on Spaces)
 
 ---
 
 ## 🎓 Learning Outcomes
 
-Playing with this project, you'll understand:
+Playing with this AI, you'll understand:
 
 ✅ **Classical AI Algorithms**
 - Minimax decision-making
@@ -300,12 +200,6 @@ Playing with this project, you'll understand:
 - Natural language generation for AI decisions
 - Bridging the gap between algorithms and humans
 
-✅ **Full-Stack Development**
-- Python backend (game logic)
-- Streamlit web UI
-- API integration (HF Spaces)
-- Cloud deployment
-
 ✅ **Game Theory Concepts**
 - Perfect information games
 - Heuristic evaluation functions
@@ -313,25 +207,19 @@ Playing with this project, you'll understand:
 
 ---
 
-## 🌐 Deployment Options
-
-### Option 1: Local (Recommended for Development)
-- **Setup**: 30 minutes (Ollama + dependencies)
-- **Speed**: Fast (<1 sec explanations)
-- **Cost**: Free
-- **Limit**: None
-- **Access**: Local only
-
-### Option 2: HuggingFace Spaces (Recommended for Sharing)
-- **Setup**: 10 minutes (token + upload)
-- **Speed**: Moderate (2-5 sec explanations)
-- **Cost**: Free tier (~1000 requests/day)
-- **Limit**: Free tier has daily limits
-- **Access**: Global via URL
+## 📁 File Structure
 
-### Option 3: Docker (Advanced)
-- Self-host with complete control
-- See `Dockerfile` (if provided)
+```
+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
+```
 
 ---
 
@@ -359,7 +247,7 @@ For details: https://creativecommons.org/licenses/by-nc-sa/4.0/
 - **Alpha-Beta Pruning**: Optimization technique (Knuth & Moore, 1970s)
 - **Streamlit**: Web UI framework (Streamlit Inc.)
 - **HuggingFace**: LLM inference & Spaces hosting
-- **Ollama**: Local LLM inference engine
+- **Mistral AI**: Language model provider
 
 ---
 
@@ -377,19 +265,11 @@ For details: https://creativecommons.org/licenses/by-nc-sa/4.0/
 ### Tools & Frameworks
 - Streamlit: https://streamlit.io
 - HuggingFace: https://huggingface.co
-- Ollama: https://ollama.ai
-
----
-
-## 🤝 Support & Contact
-
-- **Issues**: Check Troubleshooting section above
-- **Questions**: Refer to documentation files
-- **Feedback**: Suggestions welcome!
+- HuggingFace Spaces: https://huggingface.co/docs/hub/spaces
 
 ---
 
-## 🎉 Summary
+## 🎉 Have Fun!
 
 This project demonstrates:
 - ✅ Classical AI algorithms (Minimax, Alpha-Beta Pruning)
@@ -403,4 +283,5 @@ This project demonstrates:
 
 **Last Updated**: November 2025  
 **License**: CC BY-NC-SA 4.0  
-**Python Version**: 3.9+
+**Python Version**: 3.9+  
+**Framework**: Streamlit 1.28.1+