README.md

metadata

title: BreinDump
emoji: 🧠
colorFrom: indigo
colorTo: blue
sdk: gradio
sdk_version: 4.44.0
app_file: app.py
pinned: false

Docenten Assistent (Slimme Lesobservaties & LVS Rapportage)

Dit project is ingediend voor de Backyard AI track van de Build Small Hackathon. Het lost een belangrijk en tijdrovend probleem op voor docenten: het snel en ongestructureerd vastleggen van observaties tijdens of vlak na een les, om deze vervolgens automatisch te structureren per leerling en om te zetten in bruikbare rapportages en constructieve feedback.

---

👥 Deelnemers / Participants

• Hugging Face Gebruikersnaam: Jeroen-Kolom

---

🎓 Hoe het werkt (Gebruikerservaring)

1. Typ of spreek je gedachten in: Docenten kunnen snel en informeel hun observaties invoeren (bijv. "tijdens de les nederlands heeft johan voor veel onrust gezorgd, hij was te laat en wilde zijn pet niet afzetten. dirk had veel moeite met de aangeboden lesstof heike ging erg goed").
2. AI Structurering: De AI herkent automatisch de namen van leerlingen uit de tekst (zelfs in ongestructureerde zinnen zonder hoofdletters of interpunctie) en groepeert de observaties netjes per leerling in het dashboard.
3. LVS Rapportage: Met één druk op de knop genereert de AI een neutrale, objectieve en professionele tekst die direct gebruikt kan worden in het Leerlingvolgsysteem (LVS).
4. Tips & Tops: Genereer constructieve feedback voor de leerling (Tops: wat ging er goed, Tips: wat kan beter).
5. Data Exporteren: Exporteer het volledige dagrapport als een prachtig opgemaakt Markdown-bestand (.md) of download alle ruwe data als JSON. Beide exports bevatten automatisch de huidige datum in de bestandsnaam.
6. Persistentie: Alle gegevens worden lokaal opgeslagen in docent_observations.json zodat er nooit observaties verloren gaan.

---

Technologieën & Modellen (32B of kleiner)

• Frontend/Dashboard: Gradio 6 (Premium Light Mode met Glassmorphism)
• LLM Structurering & Generatie: Gemma 9B via Ollama (lokaal) met een automatische cloud-fallback naar Qwen 2.5 7B via de Hugging Face Serverless Inference API (voor frictieloze en snelle deployment op gratis Hugging Face Spaces CPU-only).
• Spraakherkenning: OpenAI Whisper-base (lokaal) om spraakobservaties om te zetten in tekst.

---

Lokale Installatie & Opstarten

1. Vereisten

Zorg ervoor dat Python 3.10+ en Ollama zijn geïnstalleerd. Installeer en start het model lokaal:

ollama run gemma:latest

2. Virtuele Omgeving & Dependencies Installeren

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

3. Applicatie Starten

Start de Gradio server:

python3 app.py

Open vervolgens http://127.0.0.1:7860 in je browser om de app te gebruiken.

---

Deployment naar Hugging Face Spaces

Om dit project op Hugging Face Spaces te deployen onder de criteria (modellen onder 32B):

1. Maak een nieuwe Space aan: Kies voor de Gradio SDK en gebruik de standaard CPU-only resource (gratis).
2. Kopieer de bestanden: Upload app.py, requirements.txt en packages.txt naar de Space. (packages.txt zorgt ervoor dat Hugging Face automatisch ffmpeg installeert).
3. Voeg je Hugging Face Token toe:
   • Ga naar de Settings van je Space.
   • Voeg een Repository Secret toe genaamd HF_TOKEN met je Hugging Face API User Access Token.
4. De Space zal automatisch opstarten en de LLM-functionaliteiten via de gratis, snelle Serverless API aanroepen, waardoor het perfect draait op een gratis CPU Space!

---

🕒 Alternatieve App: ShadowList (Taken Assistent)

Het oorspronkelijke project ShadowList (een spraakgestuurde schaduw-takenlijst) is nog steeds beschikbaar in de repository. Je kunt deze lokaal opstarten met:

python3 shadowlist_app.py

En open vervolgens http://127.0.0.1:7860 (of het aangegeven poortnummer in de terminal).