Spaces:
Running
Running
| title: Match Wise | |
| emoji: 🃏 | |
| colorFrom: purple | |
| colorTo: pink | |
| sdk: gradio | |
| sdk_version: 6.17.3 | |
| python_version: '3.12' | |
| app_file: app.py | |
| pinned: true | |
| short_description: AI-Powered Educational Memory Game with Llama.cpp | |
| hf_oauth: true | |
| tags: | |
| - track:wood | |
| - sponsor:openbmb | |
| - achievement:offgrid | |
| - achievement:offbrand | |
| - achievement:llama | |
| - achievement:sharing | |
| - achievement:fieldnotes | |
| - matchWise | |
| - gradio | |
| - minicpm5-1b | |
| thumbnail: >- | |
| https://cdn-uploads.huggingface.co/production/uploads/683d69c43015d6c975e276c1/f9OyOJSr8M08WCArixzvb.png | |
| # 🃏 MatchWise | |
| **AI-Powered Educational Memory Game with Adaptive Challenge Levels using MiniCPM5 llm via Llama.cpp** | |
| [](https://huggingface.co/build-small-hackathon) | |
|  | |
| --- | |
| ### 🚀 Purpose | |
| MatchWise attempts to make memory training more playful and educational by combining emoji card matching, AI-generated learning themes, session-wise performance tracking, and challenge levels that unlock when the player performs well. | |
| The game starts simple, then gradually moves the player from **Easy** toward **Challenge Me** using a performance meter based on level completion, matching accuracy, and gameplay progress. | |
| Instead of using fixed handcrafted stages, MatchWise keeps generating fresh memory boards and learning themes with LLM, so players can continue progressing through an endless learning loop. | |
| --- | |
| ### ✨ Key Features of MatchWise | |
| * 🎴 Emoji-based memory card matching game | |
| * 🤖 Infinite AI-generated levels with fresh themes and card sets | |
| * 🧠 Performance Meter that moves from **Easy** to **Challenge Me** | |
| * ⚡ Challenge levels unlocked through strong gameplay performance | |
| * ❤️ 5-life system to begin with | |
| * 💡 Peek system to help players during difficult boards | |
| * 🏆 Persistent leaderboard support using SQLite storage | |
| * 🎮 Interactive Gradio UI with polished game-style visuals | |
| --- | |
| ### 👨⚖️ Hackathon Tracks & Judging Notes | |
| 👉 [Social Media Post](https://x.com/tejasashinde/status/2066230745228886325) | |
| 👉 [Watch MatchWise in action](https://youtu.be/Wlb0md_pMDg) | |
| 📴 Off the Grid / Local-first: No cloud AI APIs are used. The game runs locally through MiniCPM5-1B-GGUF inside the Space. | |
| 🎨 Off-Brand / Custom UI: MatchWise uses a custom game-style frontend with handcrafted HTML, CSS, and JavaScript instead of the default Gradio look. | |
| 🦙 Llama Champion: The model runs through the llama.cpp runtime using llama-server. | |
| 📡 Sharing is Caring / Open Trace: I've shared the Codex agent trace artifacts on the Hub so the community can explore my development process and build on top of it: [MatchWise Open Trace](https://huggingface.co/datasets/build-small-hackathon/MatchWise-agent-trace) | |
| 📓 Field Notes: I also wrote a full build report about the design, challenges, small-model constraints, and lessons learned: [Building MatchWise](https://huggingface.co/blog/build-small-hackathon/building-match-wise) | |
| 🗃️ Collection: https://huggingface.co/collections/build-small-hackathon/matchwise | |
| --- | |
| ### 🧠 Models Dataset and APIs Used | |
| * **LLM:** openbmb/MiniCPM5-1B-GGUF model running locally through llama.cpp | |
| * **Model File:** MiniCPM5-1B-Q4_K_M.gguf | |
| * **Inference Runtime:** llama.cpp `llama-server` | |
| * **Game Content:** AI-generated level titles, educational messages, challenge content, learning simple facts | |
| * **Leaderboard Storage:** SQLite database stored in HuggingFace Bucket capturing HF username and high scores | |
| * **UI Framework:** Gradio with custom HTML, CSS, and JavaScript game logic | |
| --- | |
| ### 🛠️ Core Functionality Overview | |
| 1. Start the MatchWise game from the landing screen | |
| 2. Memorize the emoji cards during the preview timer | |
| 3. Flip cards and match identical emoji pairs | |
| 4. Earn score, peeks, and performance progress through clean gameplay | |
| 5. Move the Performance Meter from **Easy** toward **Challenge Me** | |
| 6. Unlock AI-generated challenge levels when performance is high enough | |
| 7. Continue playing while protecting your lives and improving your high score | |
| 8. Save and compare scores using the leaderboard | |
| --- | |
| ### 🧪 Install dependencies after clonning with: | |
| ```bash | |
| pip install -r requirements.txt | |
| ```` | |
| Run locally with: | |
| ```bash | |
| python app.py | |
| ``` | |
| Made with ❤️ using Gradio, MiniCPM5-1B via llama.cpp, and Hugging Face CPU (Free Tier) Spaces 🤗 | |
| Created by [tejasashinde](https://huggingface.co/tejasashinde) for [The Build Small Hackathon](https://huggingface.co/build-small-hackathon) 2026. |