Spaces:
Sleeping
Sleeping
| title: LearnCraft | |
| emoji: 🎓 | |
| colorFrom: blue | |
| colorTo: purple | |
| sdk: streamlit | |
| sdk_version: 1.32.0 | |
| app_file: app.py | |
| pinned: true | |
| license: mit | |
| short_description: Personalized AI Learning Platform | |
| tags: | |
| - education | |
| - learning | |
| - ai-tutor | |
| - quiz | |
| - flashcards | |
| - groq | |
| - llama | |
| - streamlit | |
| - gamification | |
| - study-tools | |
| # 🎓 LearnCraft — Personalized AI Learning Platform | |
| > Generate personalized study material, flashcards & quizzes tailored exactly to your level and learning goals — powered by **Groq LLaMA-3.3-70b**. | |
|  | |
|  | |
|  | |
|  | |
| --- | |
| ## 🌟 What is LearnCraft? | |
| LearnCraft is a fully AI-powered learning platform that generates **customized study content** based on your chosen topic and difficulty level. Whether you're a beginner learning Python or an advanced student studying Quantum Mechanics — LearnCraft adapts everything to you. | |
| ### How it works: | |
| 1. **Pick a topic** — anything from Calculus to Climate Change | |
| 2. **Choose your level** — Beginner, Intermediate, or Advanced | |
| 3. **Get personalized content** — notes, quizzes, flashcards and an AI tutor instantly | |
| 4. **Track your progress** — earn XP, unlock badges and monitor your scores | |
| --- | |
| ## ✨ Features | |
| | Feature | Description | | |
| |---|---| | |
| | 📚 **Study Content Generator** | AI-generated notes in 4 styles: Summary Notes, Detailed Explanation, Bullet Points, Concept Map | | |
| | 🃏 **Flashcard Studio** | Auto-generated flip-card decks (up to 20 cards) for any topic | | |
| | 🧩 **Quiz Engine** | MCQ, True/False, Fill-in-the-Blank, Short Answer — with optional timed mode | | |
| | 🤖 **AI Tutor Chat** | Multi-turn conversational AI tutor with topic context and full conversation memory | | |
| | 🏅 **Gamification** | XP points, 7 levels (Seedling → Genius), 15 badges, daily streak tracking | | |
| | 📄 **PDF Export** | Download study notes and quiz results as branded A4 PDFs | | |
| | 📊 **Progress Dashboard** | Score history chart, per-topic best scores, weak topic detection | | |
| | 📝 **Notes** | Save, search and delete personal notes during study sessions | | |
| --- | |
| ## 🚀 Running on Hugging Face Spaces | |
| This app runs directly on Hugging Face Spaces using the **Streamlit SDK**. | |
| ### ⚙️ Required Secret | |
| You must add your **Groq API key** as a Space secret for the app to work: | |
| 1. Go to your Space → **Settings** → **Repository secrets** | |
| 2. Add a new secret: | |
| - **Name:** `GROQ_API_KEY` | |
| - **Value:** your Groq API key from [console.groq.com](https://console.groq.com) | |
| > Get a free Groq API key at **https://console.groq.com** — it takes under a minute. | |
| ### 📂 Files required in your Space | |
| ``` | |
| app.py | |
| content_generator.py | |
| quiz_generator.py | |
| flashcard_generator.py | |
| tutor.py | |
| evaluation.py | |
| gamification.py | |
| pdf_export.py | |
| utils.py | |
| requirements.txt | |
| README.md | |
| ``` | |
| --- | |
| ## 🔑 API Key Configuration | |
| The app reads the Groq API key from the environment. Make sure each module uses: | |
| ```python | |
| import os | |
| GROQ_API_KEY = os.environ.get("GROQ_API_KEY", "") | |
| ``` | |
| > If you're running **locally**, set the variable in your terminal: | |
| > ```bash | |
| > export GROQ_API_KEY="gsk_your_key_here" # macOS/Linux | |
| > set GROQ_API_KEY=gsk_your_key_here # Windows | |
| > ``` | |
| --- | |
| ## 📦 Requirements | |
| ``` | |
| streamlit>=1.32.0 | |
| pandas>=2.0.0 | |
| groq>=0.4.0 | |
| reportlab>=4.0.0 | |
| plotly>=5.18.0 | |
| ``` | |
| --- | |
| ## 🗺️ App Pages | |
| | Page | Description | | |
| |---|---| | |
| | 🏠 **Home** | Hero banner, feature overview, quick-start buttons, recent activity feed | | |
| | 📚 **Study Content** | Generate AI study notes with key terms, summary and PDF export | | |
| | 🃏 **Flashcards** | Navigate AI-generated flip cards with progress bar and deck overview | | |
| | 🧩 **Take Quiz** | Timed quiz with instant results, XP awards and PDF download | | |
| | 🤖 **AI Tutor** | Chat with an AI tutor — quick-start prompts and topic context | | |
| | 🏅 **Achievements** | XP level hero card, badge gallery, streak and stats | | |
| | 📊 **My Progress** | Score history, per-topic performance table, weak topic alerts | | |
| | 📝 **My Notes** | Searchable saved notes from study sessions | | |
| --- | |
| ## 🏅 Gamification | |
| ### Earn XP for every learning action: | |
| | Action | XP | | |
| |---|---| | |
| | Study session | +10 XP | | |
| | Flashcard deck | +10 XP | | |
| | Complete a quiz | +20 XP | | |
| | Score ≥ 60% | +15 XP | | |
| | Score ≥ 80% | +30 XP | | |
| | Perfect score (100%) | +50 XP | | |
| ### 7 Levels: | |
| ``` | |
| 🌱 Seedling (0 XP) → 📖 Reader (50) → 🎓 Student (150) → 🔬 Scholar (300) | |
| → 🏆 Expert (500) → 🌟 Master (800) → 🚀 Genius (1200) | |
| ``` | |
| ### 15 Badges to unlock: | |
| | Badge | How to Earn | | |
| |---|---| | |
| | 🎯 First Quiz | Complete your first quiz | | |
| | 💯 Perfect Score | Score 100% on a quiz | | |
| | 🔥 3-Day Streak | Study 3 days in a row | | |
| | ⚡ Week Warrior | Study 7 days in a row | | |
| | 🗓️ Fortnight Hero | Study 14 days in a row | | |
| | 🗺️ Explorer | Study 5 different topics | | |
| | 🧠 Polymath | Study 10 different topics | | |
| | 🧩 Quiz Master | Complete 10 quizzes | | |
| | 🏅 Quiz Champion | Complete 25 quizzes | | |
| | 🎉 High Achiever | Score above 80% | | |
| | 🃏 Card Shark | Complete a flashcard deck | | |
| | 🔬 Scholar | Reach Scholar level (300 XP) | | |
| | 🏆 Expert | Reach Expert level (500 XP) | | |
| | 🌟 Master | Reach Master level (800 XP) | | |
| | 📝 Note Taker | Save your first note | | |
| --- | |
| ## 📐 Architecture | |
| ``` | |
| User (Browser) | |
| │ | |
| ▼ | |
| app.py (Streamlit — routing, session state, UI) | |
| │ | |
| ├── content_generator.py ──┐ | |
| ├── quiz_generator.py ├──► Groq API (LLaMA-3.3-70b) | |
| ├── flashcard_generator.py │ | |
| ├── tutor.py ───┘ | |
| │ | |
| ├── evaluation.py ── Quiz answer scoring | |
| ├── gamification.py ── XP / badges / streak | |
| ├── pdf_export.py ── ReportLab PDF generation | |
| └── utils.py ── JSON persistence | |
| (learning_progress.json, | |
| notes.json, | |
| gamification.json) | |
| ``` | |
| --- | |
| ## 💡 Topics You Can Study | |
| LearnCraft works with **any topic you type**, plus these built-in suggestions: | |
| `Photosynthesis` · `Machine Learning` · `World War II` · `Python Functions` · `Calculus` · `Climate Change` · `The French Revolution` · `DNA Replication` · `Object-Oriented Programming` · `The Solar System` · `Economics Supply & Demand` · `Quantum Mechanics` | |
| --- | |
| ## 🔒 Data & Privacy | |
| - All progress, notes and gamification data are stored in **local JSON files** within the Space | |
| - No user data is sent anywhere except to the **Groq API** for content generation | |
| - The Groq API is used solely for generating educational content | |
| - On Hugging Face Spaces, persistent storage resets when the Space restarts — data is session-local | |
| --- | |
| ## 🛠️ Local Development | |
| ```bash | |
| # 1. Clone the Space | |
| git clone https://huggingface.co/spaces/YOUR_USERNAME/learncraft | |
| cd learncraft | |
| # 2. Install dependencies | |
| pip install -r requirements.txt | |
| # 3. Set your API key | |
| export GROQ_API_KEY="gsk_your_key_here" | |
| # 4. Run | |
| streamlit run app.py | |
| ``` | |
| --- | |
| ## 📄 License | |
| MIT License — free to use, modify and distribute. | |
| --- | |
| <div align="center"> | |
| Built with ❤️ using <strong>Streamlit</strong> · <strong>Groq</strong> · <strong>ReportLab</strong> · <strong>Python</strong> | |
| <br><br> | |
| <em>🎓 LearnCraft — Learn smarter, not harder.</em> | |
| </div> | |