README.md

metadata

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

---

🚀 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

👉 Watch MatchWise in action

📴 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

📓 Field Notes: I also wrote a full build report about the design, challenges, small-model constraints, and lessons learned: Building MatchWise

🗃️ 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:

pip install -r requirements.txt

Run locally with:

python app.py

Made with ❤️ using Gradio, MiniCPM5-1B via llama.cpp, and Hugging Face CPU (Free Tier) Spaces 🤗

Created by tejasashinde for The Build Small Hackathon 2026.