Mcdizzo/Chaguo

This is a project that connects students to university programs based off of their final grade results. It shows the students what programs they qualify for and in what university in Tanzania. # Soma — Tanzania University Admissions (Phase 1) A web app that helps Form Six students in Tanzania see which undergraduate programs they may qualify for, using admission data from the TCU guidebook. Students enter A-Level subjects and grades; the app matches them against program minimum points and shows requirements from the official guidebook. ## Features - **Student matcher** — Enter principal/subsidiary subjects and grades; get a ranked list of programs you meet on points. - **Results search** — Filter matches by university name or program name. - **Guidebook pipeline** — Download the latest TCU undergraduate PDF, extract programs with Groq, and store them in SQLite. - **Resumable extraction** — Skips universities already loaded; adds missing universities from the guidebook automatically. ## Requirements - Python 3.10+ - Groq API key (for guidebook extraction) ## Setup ```bash git clone cd project_uni python3 -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -r requirements.txt ``` Create a `.env` file in the project root: ```env GROQ_API_KEY=your_key_here ``` The database file lives at `tz_admissions/admissions.db`. It is created or updated when you run the extraction pipeline. You can ship a pre-populated database or build it yourself (see below). ## Run the web app From the project root: ```bash python app/app.py ``` Open 127.0.0.1 in your browser. ## Guidebook pipeline (optional) Use this to refresh data from TCU when a new guidebook is published. **1. Download the latest PDF** (and run extraction unless you pass `--no-extract`): ```bash python tz_admissions/pipeline/update_guidebook.py ``` Options: - `--force` — Re-download even if the local file looks up to date. - `--no-extract` — Download only; do not call the extractor. **2. Extract programs only** (e.g. if you already have the PDF): ```bash python tz_admissions/pipeline/extract_requirements.py ``` Or point at a specific file: …