https://github.com/cyberytti/tictactoe_ai
Play classic Tic-Tac-Toe against an intelligent AI opponent in your terminal.
https://github.com/cyberytti/tictactoe_ai
cli cli-app gaming gaming-bot groq langchain langchain-python pydantic python3 tictactoe tictactoe-python
Last synced: about 1 month ago
JSON representation
Play classic Tic-Tac-Toe against an intelligent AI opponent in your terminal.
- Host: GitHub
- URL: https://github.com/cyberytti/tictactoe_ai
- Owner: cyberytti
- License: apache-2.0
- Created: 2025-04-07T16:06:43.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-04-07T16:18:38.000Z (about 1 year ago)
- Last Synced: 2025-04-10T01:02:59.800Z (about 1 year ago)
- Topics: cli, cli-app, gaming, gaming-bot, groq, langchain, langchain-python, pydantic, python3, tictactoe, tictactoe-python
- Language: Python
- Homepage:
- Size: 32.2 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Tic-Tac-Toe AI 🤖
Play the classic game of Tic-Tac-Toe against an intelligent AI opponent powered by a Large Language Model (LLM) via the Groq API! This AI doesn't just make a move; it analyzes the board and provides its reasoning. 🤔
## ✨ Features
* **Classic Tic-Tac-Toe Gameplay:** Standard 3x3 grid rules.
* **Human vs. AI:** Play as 'X' against the AI 'O'.
* **LLM-Powered AI:** Utilizes Groq's fast inference API with the `qwen-2.5-32b` model for strategic decision-making.
* **AI Reasoning:** The AI explains *why* it chose a specific move, offering insights into its strategy. 🧠
* **Randomized Start:** Either the Human ('X') or the AI ('O') can start the game randomly.
* **Clear CLI:** Simple and intuitive command-line interface.
* **Input Validation:** Prevents invalid moves by the human player.
* **Win/Tie Detection:** Automatically detects and announces game outcomes. 🏆🤝
## 🛠️ Tech Stack
* **Python 🐍:** Core programming language.
* **Langchain (`langchain_groq`) 🦜🔗:** Framework for interacting with the LLM.
* **Groq API ⚡:** Provides fast LLM inference capabilities.
* **Pydantic 🤖:** Used for defining the structured output format expected from the LLM.
## ⚙️ Setup & Installation
1. **Clone the Repository:**
```bash
git clone https://github.com/cyberytti/tictactoe_AI
cd tictactoe_AI
```
2. **Install Dependencies:**
Make sure you have Python 3 installed. Then, install the required packages:
```bash
pip install requirements.txt
```
*(Note: `groq` might be needed directly or as a dependency of `langchain_groq`)*
3. **Configure API Key 🔑:**
* Sign up and get an API key from [GroqCloud](https://console.groq.com/keys).
* Open the file `tictactoe_AI/player.py`.
* Find the line: `API_KEY="enter your Groq api-key"`
* Replace `"enter your Groq api-key"` with your actual Groq API key.
## ▶️ How to Play
1. **Run the Game:**
Navigate to the project's root directory (`tictactoe_AI`) in your terminal and run:
```bash
python tictactoe_game.py
```
2. **Follow Prompts:**
* The game will display the numbered board layout (1-9).
* It will announce whether you ('X') or the Computer ('O') starts.
* When it's your turn, enter the number (1-9) corresponding to the empty square where you want to place your 'X'.
* When it's the AI's turn, it will pause briefly to think, then print the position it chose and its detailed reasoning.
* The game board updates after each move.
3. **Game End:**
The game continues until a player gets three in a row (horizontally, vertically, or diagonally) or the board is full (resulting in a tie). The outcome will be announced. 🎉
## 💡 How the AI Works
The AI's logic resides in `player.py`:
1. **Board Analysis:** The current state of the Tic-Tac-Toe board is formatted.
2. **Available Moves:** Empty squares are identified as potential moves.
3. **Prompt Engineering:** A detailed system prompt is constructed and sent to the Groq LLM. This prompt instructs the AI on the rules of Tic-Tac-Toe, its objective ('O'), winning/blocking strategies, and the desired output format (move number and reasoning).
4. **LLM Interaction:** The `ChatGroq` client (using Langchain) sends the prompt and current game state to the specified LLM (`qwen-2.5-32b`).
5. **Structured Output:** The LLM is asked to return its response in a specific JSON structure (defined using Pydantic), containing the chosen `move` (1-9) and the `reasoning`.
6. **Move Execution:** The game script receives the AI's move and reasoning, updates the board, and displays the information to the user.
7. **Fallback:** Basic error handling is included. If the LLM call fails, the AI defaults to picking the first available move.
## 🤝 Contributing
Contributions are welcome! If you have suggestions for improvements or find any bugs, please feel free to open an issue or submit a pull request.
## 📄 License
This project is licensed under the Apache License 2.0. You can find the full license text here: [LICENSE](https://github.com/cyberytti/tictactoe_AI/blob/main/LICENSE)
---
Enjoy playing against the AI!