mbuguakevvz/lenslink

End-to-end data engineering pipeline tracking glasses adherence and beneficiary sentiment across community eyewear outreach programs in Kenya. Built with Python, DuckDB, TextBlob, and Streamlit. # 👓 LensLink — Adherence & Sentiment Pipeline for Community Eyewear Programs ## 🌍 Overview LensLink is an end-to-end data engineering pipeline that tracks **glasses adherence** and **beneficiary sentiment** across community eyewear outreach programs in Kenya. Over 800 million people globally need glasses but don't have them. Free eyewear programs distribute glasses — but rarely follow up to know if they're actually being used. LensLink solves that data gap. --- ## 🏗️ Architecture--- ## 📊 Key Metrics Tracked - **Adherence Rate** — % of beneficiaries still wearing glasses at weeks 4, 12, 24 - **Cohort Retention Curves** — by program and age group - **Dropout Risk Profiles** — reason, timing, demographics - **Sentiment Score** — TextBlob polarity on free-text feedback - **Theme Detection** — stigma, comfort, loss, breakage, gratitude, improvement - **Program Health Scorecard** — 🟢 Healthy / 🟡 At Risk / 🔴 Critical --- ## 🗂️ Project Structure--- ## ⚙️ Setup & Run ```bash # 1. Clone the repo git clone github.com cd lenslink # 2. Create virtual environment python -m venv venv venv\Scripts\Activate.ps1 # Windows PowerShell # 3. Install dependencies pip install -r requirements.txt # 4. Generate synthetic data python data/generate_data.py # 5. Run ingestion python ingestion/ingest.py # 6. Run transformations python transforms/transform.py python transforms/cohort_analysis.py # 7. Run sentiment pipeline python sentiment/sentiment_pipeline.py # 8. Launch dashboard streamlit run dashboard/app.py ``` --- ## 🔍 Sample Insights (from synthetic data) | Program | Avg Adherence | Sentiment | Status | |---|---|---|---| | Meru Outreach | 81.6% | 60.8% positive | 🟢 Healthy | | Nairobi Vision Drive | 76.8% | 65.9% positive | 🟡 At Risk | | Nakuru EyeCare | 75.1% | 63.6% positive | 🟡 At Risk | | Kisumu Sight Camp | 72.1% | 55.3% positive | 🟡 At Risk | **Top dropout reasons:** Unknown · Discomfort · Social Stigma · Broke Glass …