# 🎯 AI Prompt Engineering Game
[](https://badge.fury.io/py/ai-prompt-game)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/surajsahani/ai-prompt-game)
**Learn AI prompt engineering through reverse engineering!** 🎮
An educational CLI game where students see a target image and must craft prompts to recreate it using AI image generation. Perfect for learning prompt engineering, visual analysis, and AI communication skills.
**✅ Cross-Platform Compatible**: Works seamlessly on Windows, macOS, and Linux (Ubuntu/Debian)
## 🚀 Quick Start
### Install
```bash
pip install ai-prompt-game
```
### Play
```bash
ai-prompt-game
```
That's it! The game will guide you through setup and start your first challenge.
## 🎮 How It Works
1. **See a target image** (beautiful sunset, ocean waves, etc.)
2. **Write a prompt** describing what you see
3. **AI generates an image** based on your prompt
4. **Get scored** on how well it matches the target
5. **Improve and try again** until you master it!
### Example Game Flow
```
🎯 Target: Mountain Sunset
[Shows beautiful sunset image]
[Attempt #1] Your prompt: landscape
📊 Score: 23.4% - "Too generic! Describe the colors and lighting."
[Attempt #2] Your prompt: sunset over mountains
📊 Score: 67.8% - "Better! Add more details about the dramatic sky."
[Attempt #3] Your prompt: golden sunset over mountain peaks with dramatic clouds
📊 Score: 89.1% - "Excellent! Almost perfect!"
🎉 You're learning prompt engineering!
```
## ✨ Features
- **🎯 Multiple Challenges**: Mountain sunsets, ocean waves, forests, beaches, aurora
- **🤖 Real AI Generation**: Uses Pollinations.ai (free) or your own models
- **📊 Smart Scoring**: 4-metric similarity analysis (structure, colors, edges, composition)
- **🎓 Educational Feedback**: Learn what makes prompts effective
- **📈 Progress Tracking**: See your improvement over time
- **🖼️ Visual Display**: See target and generated images side-by-side
- **🌍 Works Offline**: After setup, only AI generation needs internet
- **🖥️ Cross-Platform**: Native support for Windows, macOS, and Linux
## 🛠️ Installation Options
### Option 1: Simple Install (Recommended)
```bash
pip install ai-prompt-game
ai-prompt-game --setup # Download challenge images
ai-prompt-game # Start playing!
```
### Option 2: Development Install
```bash
git clone https://github.com/surajsahani/ai-prompt-game.git
cd ai-prompt-game
pip install -e .
ai-prompt-game --setup
```
### Option 3: With Advanced AI Models
```bash
# For local Hugging Face models
pip install ai-prompt-game[huggingface]
# For Replicate API
pip install ai-prompt-game[replicate]
```
## 🖥️ Platform-Specific Setup
### Windows
```cmd
# Install via pip (works in Command Prompt or PowerShell)
pip install ai-prompt-game
ai-prompt-game
# If you encounter OpenCV issues:
pip install opencv-python-headless
```
### Ubuntu/Linux
```bash
# Standard installation
pip install ai-prompt-game
# If you need system OpenCV dependencies:
sudo apt-get update
sudo apt-get install python3-opencv libopencv-dev
# Then install the game
pip install ai-prompt-game
ai-prompt-game
```
### macOS
```bash
# Standard installation works out of the box
pip install ai-prompt-game
ai-prompt-game
```
**Note**: All platforms use the same commands once installed. The game automatically detects your operating system and adapts accordingly.
## 🖼️ Visual Features
The game includes **visual display mode** that shows images side-by-side:
- **Target Image**: The image you're trying to recreate
- **Generated Image**: Your AI-generated result
- **Real-time Comparison**: See both images with similarity scores
- **Automatic Saving**: All images saved to `~/.ai-prompt-game/generated/`
### Visual Mode Commands
```bash
ai-prompt-game # Full visual mode (default)
ai-prompt-game --no-visual # Text-only mode
```
**Visual mode requires**: `matplotlib` (automatically installed with the package)
## 🎯 Game Commands
```bash
ai-prompt-game # Start interactive game with visual display
ai-prompt-game --setup # Setup game files and targets
ai-prompt-game --list-targets # Show available challenges
ai-prompt-game --target sunset # Play specific challenge
ai-prompt-game --quick # Quick 5-minute game
ai-prompt-game --stats # Show your progress
ai-prompt-game --no-visual # Text-only mode (no image display)
```
### In-Game Commands
- `progress` - Show current game progress
- `target` - Show target image info again
- `help` - Show help and tips
- `quit` - Exit game
## 🎓 Educational Value
Perfect for learning:
- **Prompt Engineering**: How to communicate effectively with AI
- **Visual Analysis**: Breaking down images into describable components
- **Iterative Improvement**: Learning from feedback and refining
- **AI Understanding**: How image generation actually works
### For Educators
- **Measurable Learning**: Quantified skill improvement
- **Engaging Format**: Students love the game approach
- **Scalable**: Works for 1 or 1000 students
- **Progress Tracking**: Built-in analytics and statistics
## 🤖 AI Models Supported
| Model | Cost | Quality | Setup |
|-------|------|---------|-------|
| **Pollinations.ai** | Free | High | None (default) |
| **Hugging Face** | Free | Very High | Local GPU recommended |
| **Replicate** | Pay-per-use | Highest | API key required |
### Using Different Models
```bash
# Use Pollinations.ai (default, free)
ai-prompt-game --model pollinations
# Use local Hugging Face model
ai-prompt-game --model huggingface
# Use Replicate API
ai-prompt-game --model replicate
```
## 📊 Scoring System
The game uses an advanced multi-metric scoring system:
### **🤖 LLaVA AI-Enhanced Scoring (Optional)**
- **LLaVA Semantic (25%)**: AI-powered semantic understanding of image similarity
- **Structure (20%)**: Layout and composition matching
- **Colors (20%)**: Color distribution and palette
- **Edges (20%)**: Shape and boundary detection
- **Dominant Colors (15%)**: Key color matching
### **🔧 Traditional Scoring (Fallback)**
- **Structure (30%)**: Layout and composition matching
- **Colors (25%)**: Color distribution and palette
- **Edges (25%)**: Shape and boundary detection
- **Dominant Colors (20%)**: Key color matching
**Combined Score**: Weighted average of all metrics (0-100%)
### **🚀 Enable LLaVA Enhancement**
```bash
# Install LLaVA dependencies (large download ~13GB)
pip install transformers torch torchvision
# Use LLaVA-enhanced scoring (default)
ai-prompt-game
# Disable LLaVA (traditional metrics only)
ai-prompt-game --no-llava
```
**LLaVA Benefits:**
- 🧠 Semantic understanding (not just pixel comparison)
- 🎯 Better scoring for artistic and stylistic matches
- 💬 AI explanations of what matches/differs
- 🎨 Understands context, mood, and composition
## 🎯 Challenge Targets
- **🌅 Mountain Sunset** (Medium) - Golden hour over peaks
- **🌊 Ocean Waves** (Hard) - Powerful waves on rocky shore
- **🌲 Misty Forest** (Medium) - Peaceful forest path with mist
- **🏖️ Tropical Beach** (Easy) - Crystal clear water and white sand
- **🌌 Northern Lights** (Hard) - Aurora borealis over snow
## 📈 Example Learning Progression
```
Session 1: "landscape" → 15.6% → "Be more specific!"
Session 2: "sunset mountains" → 42.3% → "Add color details!"
Session 3: "golden sunset over mountain peaks" → 68.7% → "Great progress!"
Session 4: "golden sunset over mountain peaks with dramatic clouds" → 89.1% → "Almost perfect!"
Session 5: "golden sunset over mountain peaks with dramatic orange clouds and lake reflection" → 96.7% → "MASTERY!"
🎓 Result: Student learned effective prompt engineering!
```
## 🔧 Advanced Usage
### Custom Targets
```python
from ai_prompt_game import PromptGame
game = PromptGame()
game.add_custom_target("my_image.jpg", "My Custom Challenge")
```
### API Integration
```python
from ai_prompt_game import ImageGenerator, ImageComparison
generator = ImageGenerator("pollinations")
comparator = ImageComparison()
# Generate image
image = generator.generate("sunset over mountains")
# Compare with target
scores = comparator.compare(image, target_image)
print(f"Similarity: {scores['combined']:.3f}")
```
## 🤝 Contributing
We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
### Development Setup
```bash
git clone https://github.com/surajsahani/ai-prompt-game.git
cd ai-prompt-game
pip install -e .[dev]
pytest # Run tests
```
## 📄 License
MIT License - see [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- **Pollinations.ai** for free, high-quality image generation
- **Unsplash** for beautiful target images
- **OpenCV** for image processing capabilities
- **Education community** for inspiration and feedback
## 🆘 Support
- **Issues**: [GitHub Issues](https://github.com/surajsahani/ai-prompt-game/issues)
- **Discussions**: [GitHub Discussions](https://github.com/surajsahani/ai-prompt-game/discussions)
- **Email**: surajkumarsahani1997@gmail.com
---
**Made with ❤️ for AI education**
*"Making AI education engaging, measurable, and fun - one prompt at a time!"*
Raw data
{
"_id": null,
"home_page": "https://github.com/surajsahani/ai-prompt-game",
"name": "ai-prompt-game",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "ai, education, prompt-engineering, machine-learning, game, cli",
"author": "Suraj Sahani",
"author_email": "Suraj Sahani <surajkumarsahani1997@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/52/cd/befbbcd31d011ad868405845b5b484e36837f68b10f9e8087abb41fb45fd/ai_prompt_game-1.1.0.tar.gz",
"platform": null,
"description": "# \ud83c\udfaf AI Prompt Engineering Game\n\n[](https://badge.fury.io/py/ai-prompt-game)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/surajsahani/ai-prompt-game)\n\n**Learn AI prompt engineering through reverse engineering!** \ud83c\udfae\n\nAn educational CLI game where students see a target image and must craft prompts to recreate it using AI image generation. Perfect for learning prompt engineering, visual analysis, and AI communication skills.\n\n**\u2705 Cross-Platform Compatible**: Works seamlessly on Windows, macOS, and Linux (Ubuntu/Debian)\n\n## \ud83d\ude80 Quick Start\n\n### Install\n```bash\npip install ai-prompt-game\n```\n\n### Play\n```bash\nai-prompt-game\n```\n\nThat's it! The game will guide you through setup and start your first challenge.\n\n## \ud83c\udfae How It Works\n\n1. **See a target image** (beautiful sunset, ocean waves, etc.)\n2. **Write a prompt** describing what you see\n3. **AI generates an image** based on your prompt\n4. **Get scored** on how well it matches the target\n5. **Improve and try again** until you master it!\n\n### Example Game Flow\n```\n\ud83c\udfaf Target: Mountain Sunset\n[Shows beautiful sunset image]\n\n[Attempt #1] Your prompt: landscape\n\ud83d\udcca Score: 23.4% - \"Too generic! Describe the colors and lighting.\"\n\n[Attempt #2] Your prompt: sunset over mountains \n\ud83d\udcca Score: 67.8% - \"Better! Add more details about the dramatic sky.\"\n\n[Attempt #3] Your prompt: golden sunset over mountain peaks with dramatic clouds\n\ud83d\udcca Score: 89.1% - \"Excellent! Almost perfect!\"\n\n\ud83c\udf89 You're learning prompt engineering!\n```\n\n## \u2728 Features\n\n- **\ud83c\udfaf Multiple Challenges**: Mountain sunsets, ocean waves, forests, beaches, aurora\n- **\ud83e\udd16 Real AI Generation**: Uses Pollinations.ai (free) or your own models\n- **\ud83d\udcca Smart Scoring**: 4-metric similarity analysis (structure, colors, edges, composition)\n- **\ud83c\udf93 Educational Feedback**: Learn what makes prompts effective\n- **\ud83d\udcc8 Progress Tracking**: See your improvement over time\n- **\ud83d\uddbc\ufe0f Visual Display**: See target and generated images side-by-side\n- **\ud83c\udf0d Works Offline**: After setup, only AI generation needs internet\n- **\ud83d\udda5\ufe0f Cross-Platform**: Native support for Windows, macOS, and Linux\n\n## \ud83d\udee0\ufe0f Installation Options\n\n### Option 1: Simple Install (Recommended)\n```bash\npip install ai-prompt-game\nai-prompt-game --setup # Download challenge images\nai-prompt-game # Start playing!\n```\n\n### Option 2: Development Install\n```bash\ngit clone https://github.com/surajsahani/ai-prompt-game.git\ncd ai-prompt-game\npip install -e .\nai-prompt-game --setup\n```\n\n### Option 3: With Advanced AI Models\n```bash\n# For local Hugging Face models\npip install ai-prompt-game[huggingface]\n\n# For Replicate API\npip install ai-prompt-game[replicate]\n```\n\n## \ud83d\udda5\ufe0f Platform-Specific Setup\n\n### Windows\n```cmd\n# Install via pip (works in Command Prompt or PowerShell)\npip install ai-prompt-game\nai-prompt-game\n\n# If you encounter OpenCV issues:\npip install opencv-python-headless\n```\n\n### Ubuntu/Linux\n```bash\n# Standard installation\npip install ai-prompt-game\n\n# If you need system OpenCV dependencies:\nsudo apt-get update\nsudo apt-get install python3-opencv libopencv-dev\n\n# Then install the game\npip install ai-prompt-game\nai-prompt-game\n```\n\n### macOS\n```bash\n# Standard installation works out of the box\npip install ai-prompt-game\nai-prompt-game\n```\n\n**Note**: All platforms use the same commands once installed. The game automatically detects your operating system and adapts accordingly.\n\n## \ud83d\uddbc\ufe0f Visual Features\n\nThe game includes **visual display mode** that shows images side-by-side:\n\n- **Target Image**: The image you're trying to recreate\n- **Generated Image**: Your AI-generated result \n- **Real-time Comparison**: See both images with similarity scores\n- **Automatic Saving**: All images saved to `~/.ai-prompt-game/generated/`\n\n### Visual Mode Commands\n```bash\nai-prompt-game # Full visual mode (default)\nai-prompt-game --no-visual # Text-only mode\n```\n\n**Visual mode requires**: `matplotlib` (automatically installed with the package)\n\n## \ud83c\udfaf Game Commands\n\n```bash\nai-prompt-game # Start interactive game with visual display\nai-prompt-game --setup # Setup game files and targets\nai-prompt-game --list-targets # Show available challenges\nai-prompt-game --target sunset # Play specific challenge\nai-prompt-game --quick # Quick 5-minute game\nai-prompt-game --stats # Show your progress\nai-prompt-game --no-visual # Text-only mode (no image display)\n```\n\n### In-Game Commands\n- `progress` - Show current game progress\n- `target` - Show target image info again \n- `help` - Show help and tips\n- `quit` - Exit game\n\n## \ud83c\udf93 Educational Value\n\nPerfect for learning:\n- **Prompt Engineering**: How to communicate effectively with AI\n- **Visual Analysis**: Breaking down images into describable components\n- **Iterative Improvement**: Learning from feedback and refining\n- **AI Understanding**: How image generation actually works\n\n### For Educators\n- **Measurable Learning**: Quantified skill improvement\n- **Engaging Format**: Students love the game approach\n- **Scalable**: Works for 1 or 1000 students\n- **Progress Tracking**: Built-in analytics and statistics\n\n## \ud83e\udd16 AI Models Supported\n\n| Model | Cost | Quality | Setup |\n|-------|------|---------|-------|\n| **Pollinations.ai** | Free | High | None (default) |\n| **Hugging Face** | Free | Very High | Local GPU recommended |\n| **Replicate** | Pay-per-use | Highest | API key required |\n\n### Using Different Models\n```bash\n# Use Pollinations.ai (default, free)\nai-prompt-game --model pollinations\n\n# Use local Hugging Face model\nai-prompt-game --model huggingface\n\n# Use Replicate API\nai-prompt-game --model replicate\n```\n\n## \ud83d\udcca Scoring System\n\nThe game uses an advanced multi-metric scoring system:\n\n### **\ud83e\udd16 LLaVA AI-Enhanced Scoring (Optional)**\n- **LLaVA Semantic (25%)**: AI-powered semantic understanding of image similarity\n- **Structure (20%)**: Layout and composition matching\n- **Colors (20%)**: Color distribution and palette\n- **Edges (20%)**: Shape and boundary detection \n- **Dominant Colors (15%)**: Key color matching\n\n### **\ud83d\udd27 Traditional Scoring (Fallback)**\n- **Structure (30%)**: Layout and composition matching\n- **Colors (25%)**: Color distribution and palette\n- **Edges (25%)**: Shape and boundary detection \n- **Dominant Colors (20%)**: Key color matching\n\n**Combined Score**: Weighted average of all metrics (0-100%)\n\n### **\ud83d\ude80 Enable LLaVA Enhancement**\n```bash\n# Install LLaVA dependencies (large download ~13GB)\npip install transformers torch torchvision\n\n# Use LLaVA-enhanced scoring (default)\nai-prompt-game\n\n# Disable LLaVA (traditional metrics only)\nai-prompt-game --no-llava\n```\n\n**LLaVA Benefits:**\n- \ud83e\udde0 Semantic understanding (not just pixel comparison)\n- \ud83c\udfaf Better scoring for artistic and stylistic matches\n- \ud83d\udcac AI explanations of what matches/differs\n- \ud83c\udfa8 Understands context, mood, and composition\n\n## \ud83c\udfaf Challenge Targets\n\n- **\ud83c\udf05 Mountain Sunset** (Medium) - Golden hour over peaks\n- **\ud83c\udf0a Ocean Waves** (Hard) - Powerful waves on rocky shore\n- **\ud83c\udf32 Misty Forest** (Medium) - Peaceful forest path with mist\n- **\ud83c\udfd6\ufe0f Tropical Beach** (Easy) - Crystal clear water and white sand\n- **\ud83c\udf0c Northern Lights** (Hard) - Aurora borealis over snow\n\n## \ud83d\udcc8 Example Learning Progression\n\n```\nSession 1: \"landscape\" \u2192 15.6% \u2192 \"Be more specific!\"\nSession 2: \"sunset mountains\" \u2192 42.3% \u2192 \"Add color details!\" \nSession 3: \"golden sunset over mountain peaks\" \u2192 68.7% \u2192 \"Great progress!\"\nSession 4: \"golden sunset over mountain peaks with dramatic clouds\" \u2192 89.1% \u2192 \"Almost perfect!\"\nSession 5: \"golden sunset over mountain peaks with dramatic orange clouds and lake reflection\" \u2192 96.7% \u2192 \"MASTERY!\"\n\n\ud83c\udf93 Result: Student learned effective prompt engineering!\n```\n\n## \ud83d\udd27 Advanced Usage\n\n### Custom Targets\n```python\nfrom ai_prompt_game import PromptGame\n\ngame = PromptGame()\ngame.add_custom_target(\"my_image.jpg\", \"My Custom Challenge\")\n```\n\n### API Integration\n```python\nfrom ai_prompt_game import ImageGenerator, ImageComparison\n\ngenerator = ImageGenerator(\"pollinations\")\ncomparator = ImageComparison()\n\n# Generate image\nimage = generator.generate(\"sunset over mountains\")\n\n# Compare with target\nscores = comparator.compare(image, target_image)\nprint(f\"Similarity: {scores['combined']:.3f}\")\n```\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n### Development Setup\n```bash\ngit clone https://github.com/surajsahani/ai-prompt-game.git\ncd ai-prompt-game\npip install -e .[dev]\npytest # Run tests\n```\n\n## \ud83d\udcc4 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4f Acknowledgments\n\n- **Pollinations.ai** for free, high-quality image generation\n- **Unsplash** for beautiful target images\n- **OpenCV** for image processing capabilities\n- **Education community** for inspiration and feedback\n\n## \ud83c\udd98 Support\n\n- **Issues**: [GitHub Issues](https://github.com/surajsahani/ai-prompt-game/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/surajsahani/ai-prompt-game/discussions)\n- **Email**: surajkumarsahani1997@gmail.com\n\n---\n\n**Made with \u2764\ufe0f for AI education**\n\n*\"Making AI education engaging, measurable, and fun - one prompt at a time!\"*\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "AI-powered reverse prompt engineering educational game",
"version": "1.1.0",
"project_urls": {
"Documentation": "https://github.com/surajsahani/ai-prompt-game#readme",
"Homepage": "https://github.com/surajsahani/ai-prompt-game",
"Issues": "https://github.com/surajsahani/ai-prompt-game/issues",
"Repository": "https://github.com/surajsahani/ai-prompt-game"
},
"split_keywords": [
"ai",
" education",
" prompt-engineering",
" machine-learning",
" game",
" cli"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "73a066895983f3f3f8dae61763ea22bb0b00edf73d5da621c24e394dce6c6a95",
"md5": "6c5a05e9297a6e4c152254c0f9ab3835",
"sha256": "9b77a2ca595399a8b46aa5cfac5aa32cc7903369afca583c759d02b100774386"
},
"downloads": -1,
"filename": "ai_prompt_game-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6c5a05e9297a6e4c152254c0f9ab3835",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 22213,
"upload_time": "2025-08-18T09:35:51",
"upload_time_iso_8601": "2025-08-18T09:35:51.558034Z",
"url": "https://files.pythonhosted.org/packages/73/a0/66895983f3f3f8dae61763ea22bb0b00edf73d5da621c24e394dce6c6a95/ai_prompt_game-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "52cdbefbbcd31d011ad868405845b5b484e36837f68b10f9e8087abb41fb45fd",
"md5": "d66ac9ff1e4f8280e3c9a45c97024ad4",
"sha256": "956ab25bc1165d2104956e78ee1441258ffa2b02686579dba685763c078cbc90"
},
"downloads": -1,
"filename": "ai_prompt_game-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "d66ac9ff1e4f8280e3c9a45c97024ad4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 24347,
"upload_time": "2025-08-18T09:35:53",
"upload_time_iso_8601": "2025-08-18T09:35:53.077805Z",
"url": "https://files.pythonhosted.org/packages/52/cd/befbbcd31d011ad868405845b5b484e36837f68b10f9e8087abb41fb45fd/ai_prompt_game-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-18 09:35:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "surajsahani",
"github_project": "ai-prompt-game",
"github_not_found": true,
"lcname": "ai-prompt-game"
}
JSON
