How HN: AI-Powered Quiz Generator with SRS and One-Click Web Deployment

Instantly transform any text into interactive, shareable quizzes and a personal study deck. This application leverages the power of Google's Gemini AI for intelligent content parsing, Hugging Face Hub for persistent data storage, and Netlify for one-click deployment of your quizzes to the web.

🚀 Try the Live Demo
Deploy to Spaces

• 🤖 AI-Powered Parsing: Simply paste your raw questions and answers. The Gemini API intelligently structures it into a valid quiz format, even determining the correct answer if you forget to mark it.
• 🔁 Spaced Repetition System (SRS): Don't just take quizzes—learn from them. Every mistake you make is automatically converted into a flashcard and added to a personal review deck, using an SM-2 inspired algorithm to schedule future reviews.
• 🚀 Automatic Web Deployment: With a single click, your new quiz is deployed to a persistent, public website on Netlify, complete with a homepage listing all your quizzes.
• 🔐 Private & Persistent Storage: All your quiz data and SRS progress are stored securely and privately in a Hugging Face Dataset under your own account. You own your data.
• 🎮 Gamified Learning: Stay motivated with Experience Points (XP) and a Daily Streak tracker for completing quizzes and review sessions.
• Open & Self-Hosted: Designed to run on Hugging Face Spaces. Just provide your own API keys, and you're in full control.

You have three main options to use this application, from easiest to most advanced:

The quickest way to see the app in action. No setup is required. Note that data created in the public demo may be periodically cleared.

➡️ Click here to access the Live Demo

Create your own private copy of this application on Hugging Face. This is the best way to have your own persistent quiz library.

1. Click the Deploy to Spaces button.
2. Hugging Face will create a new Space under your account. Choose a name and select "Private" if you wish.
3. In your new Space's settings, go to Settings > Secrets.
4. Add the following as repository secrets:
   • GEMINI_API_KEY
   • HF_TOKEN (with write permissions)
   • NETLIFY_TOKEN
5. The Space will build, and you can launch the app. It will guide you through entering the remaining configuration (like your desired HF Dataset ID) in the sidebar.

Run the application on your own machine for development or offline use.

1. Prerequisites: Ensure you have Python 3.9+ installed.
2. Clone the repository:
   git clone https://github.com/Reqeique/SRS-AI-quiz-gen.git cd SRS-AI-quiz-gen
3. Install the dependencies:
   pip install -r requirements.txt
4. Run the Streamlit app:
   streamlit run quiz_generator.py
5. Configure in Sidebar: Open the app in your browser and enter all the required keys and configuration values in the sidebar.

1. Input: A user pastes raw text into the Streamlit interface.
2. AI Parsing: The text is sent to the Google Gemini API, which returns a structured JSON object for the quiz.
3. Persistent Storage: The new quiz JSON and the user's updated SRS deck (srs_deck.csv) are saved to a private Hugging Face Dataset.
4. Deployment: The app generates all necessary HTML files and deploys the entire quiz site to Netlify via their API.
5. Interaction: The user takes the quiz on the public Netlify site.
6. Feedback Loop: Upon completion, the quiz results (mistakes) are sent back to the Streamlit app to update the SRS deck.

• Frontend: Streamlit
• AI Model: Google Gemini
• Data Storage: Hugging Face Hub (Datasets)
• Web Hosting: Netlify
• Core Libraries: pandas, requests, huggingface-hub

This project is licensed under the MIT License - see the LICENSE file for details.