| --- |
| 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](https://ollama.com) zijn geïnstalleerd. |
| Installeer en start het model lokaal: |
| ```bash |
| ollama run gemma:latest |
| ``` |
|
|
| ### 2. Virtuele Omgeving & Dependencies Installeren |
| ```bash |
| python3 -m venv .venv |
| source .venv/bin/activate |
| pip install -r requirements.txt |
| ``` |
|
|
| ### 3. Applicatie Starten |
| Start de Gradio server: |
| ```bash |
| 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: |
| ```bash |
| python3 shadowlist_app.py |
| ``` |
| En open vervolgens `http://127.0.0.1:7860` (of het aangegeven poortnummer in de terminal). |
|
|
