BLACKSAND24/ai-smart-tutor-full

An a.i smart tutor tailored to help african students with limited resources # AI Smart Tutor — Full Adaptive Version (with Luganda & Swahili) This repository contains a Streamlit-based adaptive AI tutor optimized for low-bandwidth African classrooms. It includes: - English, Luganda, and Swahili offline question banks (Math, Python, African History). - Adaptive pacing, mastery tracking, and spaced repetition (SM-2 inspired). - Hints/scaffold system, language-aware sessions, and a Teacher dashboard. - Migration script to ensure DB schema and adaptive tables. - Offline-first behavior; OpenAI used only if API key is set for generating new questions. ## Quickstart (local) 1. Unzip the repo and `cd` into it. 2. Create a virtual environment and install requirements: ```bash python -m venv .venv # Windows: .venv\Scripts\activate # macOS/Linux: source .venv/bin/activate pip install -r requirements.txt ``` 3. (Optional) Set OpenAI API key for online generation: ```bash # Windows PowerShell $env:OPENAI_API_KEY = "sk-..." # macOS/Linux export OPENAI_API_KEY="sk-..." ``` 4. Run DB migration once (creates new tables): ```bash python migrate_db.py ``` 5. Start the Streamlit app: ```bash streamlit run app.py ``` 6. Open the local URL provided by Streamlit (usually localhost). ## Deployment (Streamlit Community Cloud or Render) - Create a GitHub repo and push this folder. - For Streamlit Cloud: connect the repo and set the start command to `streamlit run app.py`. - Add `OPENAI_API_KEY` as a secret in the hosting platform only if you want online generation. ## Where the adaptive pieces are - `adaptive.py` — Mastery model, SM-2-like review scheduling, selection logic. - `db.py` — Database helpers and schema. - `core.py` — Question generation & local bank loading. - `local_bank.json` — Offline bank with translations & hints. - `app.py` — Streamlit UI integrated with adaptive logic & teacher dashboard. - `migrate_db.py` — Migration script to ensure schema changes. ## Teacher workflow - Open Teacher Dashboard checkbox in the app. - Export sessio …