albert-magarire/ZimKAG

Supervised NLP for risk and opportunity detection in bespoke construction contracts (MSc Quantity Surveying, University of Zimbabwe) # 🏗️ ZimKAG ### Supervised NLP for Risk & Opportunity Detection in Bespoke Construction Contracts **Development of a Supervised NLP Model to Assist in Identification of Risks and Opportunities in Bespoke Construction Contracts in Zimbabwe** *A Master of Quantity Surveying research project · University of Zimbabwe* --- ## 🎯 What is ZimKAG? **ZimKAG** is an end-to-end NLP system that helps quantity surveyors and contract administrators in Zimbabwe **read construction contracts faster and safer**. A contractor uploads a PDF / DOCX / TXT contract (JCT, NEC4, FIDIC or bespoke) and ZimKAG returns a clause-by-clause classification into: | Class | Meaning | |---|---| | 🚨 **High Risk** | Significantly favours the Employer; potential red flag | | 🟠 **Medium Risk** | Some imbalance; worth tightening in negotiation | | 🟡 **Low Risk** | Standard balanced provision | | ✅ **Opportunity** | Favours the Contractor — defend during negotiation | | ⚪ **Neutral** | Heading, definition or pure boilerplate | Each risky clause is paired with **knowledge-graph guidance** (Zimbabwe-specific: RBZ, RTGS/ZiG, ZIMRA, EMA, NSSA, OHSACT, Arbitration Act 7:15) and an **LLM-generated fairer rewrite**. --- ## ✨ Highlights - **10 000-clause labelled dataset** spanning JCT, NEC4, FIDIC and bespoke Zimbabwean contracts - **Fine-tuned Legal-BERT** (`nlpaueb/legal-bert-base-uncased`) for 5-class clause classification - **Hybrid pipeline** — Legal-BERT prediction → Knowledge-graph trigger matching → Semantic-similarity fallback → LLM rewrite - **Modern web app** — FastAPI backend with async job pipeline, single-page UI (Tailwind CDN + vanilla JS + Chart.js), dark mode, drag-drop, branded PDF report download - **📧 Gmail watcher** — companion background service that auto-detects construction contracts in your inbox and replies with a full risk analysis + PDF report (70+ keyword pre-filter, ≥3-hit threshold) - **Zimbabwe-aware knowledge graph** with 8 risk categories and fuzzy trigger m …