Upload README.md

README.md

@@ -10,56 +10,101 @@ app_file: app.py
 pinned: false
 ---
 
-# 🛡️ ClauseGuard — AI Contract Analysis
+# 🛡️ ClauseGuard — World's Best Open-Source Legal Contract Analysis
 
-**The world's most comprehensive open-source legal contract analysis tool.**
+**ClauseGuard** is the most comprehensive open-source AI-powered legal contract analysis tool. It analyzes contracts using state-of-the-art legal NLP models and provides actionable risk assessments.
 
-ClauseGuard automatically analyzes legal contracts using state-of-the-art NLP models fine-tuned on legal data.
+## ✨ Core Features
 
-## ✨ Features
+### Analysis Engine
+| Feature | Description |
+|---------|-------------|
+| **41 CUAD Clause Categories** | Full taxonomy: Document Name, Parties, Governing Law, Indemnification, Termination, Non-Compete, IP Ownership, Audit Rights, Force Majeure, and more |
+| **4-Tier Risk Scoring** | Critical 🔴 / High 🟠 / Medium 🟡 / Low 🟢 with visual risk matrix |
+| **Legal NER** | Extracts parties, dates, monetary values ($), jurisdictions, defined terms, and party roles |
+| **NLI Contradiction Detection** | Identifies conflicting clauses (e.g., uncapped + capped liability) and missing critical provisions |
+| **Obligation Tracker** | Categorizes action items: monetary 💰, compliance ⚖️, reporting 📊, delivery 📦, termination 🛑 |
+| **Compliance Checker** | Validates against GDPR, CCPA, SOX, HIPAA, and FINRA requirements |
+| **Contract Comparison** | Side-by-side diff between two contracts with alignment scoring |
 
-### Core Analysis
-- **41 CUAD Clause Categories** — Detects and classifies clauses across the full [CUAD](https://huggingface.co/datasets/theatticusproject/cuad-qa) taxonomy (Document Name, Parties, Governing Law, Indemnification, Termination, Non-Compete, IP Ownership, etc.)
-- **4-Tier Risk Scoring** — Critical / High / Medium / Low with visual risk matrix
-- **Legal NER** — Extracts parties, dates, monetary values, jurisdictions, defined terms
-- **NLI Contradiction Detection** — Identifies conflicting clauses and missing critical provisions
-- **PDF / DOCX / TXT Support** — Upload any contract format
+### Document Support
+- **PDF** parsing via `pdfplumber`
+- **DOCX/DOC** parsing via `python-docx`
+- **TXT / Markdown** direct text input
 
 ### UI/UX
-- **3-Panel Professional Layout** — Sidebar upload + Main analysis + Summary dashboard
-- **Document Viewer** — Text with inline entity highlights
-- **Clause Cards** — Expandable cards with risk badges and descriptions
-- **Export Reports** — JSON (structured data) and CSV (tabular) downloads
-- **Color-Coded Risk Badges** — Visual indicators for quick triage
-
-## 🧠 Models Used
-
-| Component | Model |
-|-----------|-------|
-| Clause Classification | `Mokshith31/legalbert-contract-clause-classification` (LoRA on `nlpaueb/legal-bert-base-uncased`) |
-| Fallback Detection | Regex patterns covering 15+ clause types |
+- **3-Panel Professional Layout** — Upload sidebar + Main analysis + Summary dashboard
+- **Document Viewer** — Inline entity highlights (colored annotations)
+- **Clause Cards** — Expandable risk-badged cards with confidence scores
+- **Export Reports** — JSON (structured) and CSV (tabular) downloads
+- **Color-Coded Risk Badges** — Instant visual triage
+
+## 🧠 Models & Architecture
+
+| Component | Technology |
+|-----------|------------|
+| Clause Classification | `Mokshith31/legalbert-contract-clause-classification` — LoRA adapter on `nlpaueb/legal-bert-base-uncased`, fine-tuned on CUAD 41-class taxonomy |
 | NER | Rule-based with 7 entity types (dates, money, parties, jurisdictions, defined terms) |
-| NLI | Heuristic contradiction detection across 5 conflict patterns |
+| NLI | Heuristic contradiction detection with 5 conflict patterns + missing-clause detection |
+| Compliance | Regulatory keyword matching across GDPR, CCPA, SOX, HIPAA, FINRA |
+| Comparison | SequenceMatcher-based clause alignment with risk delta analysis |
+| Obligations | Regex pattern matching across 5 obligation categories |
+
+## 📊 Risk Scoring Methodology
+
+Risk scores combine clause detection with weighted severity:
+- **CRITICAL**: 40 pts (Uncapped Liability, Arbitration, IP Assignment, etc.)
+- **HIGH**: 20 pts (Non-Compete, Exclusivity, Unilateral Change, etc.)
+- **MEDIUM**: 10 pts (Governing Law, Jurisdiction, etc.)
+- **LOW**: 3 pts (Document Name, Dates, etc.)
 
-## 📚 Datasets
+Final score normalized to 0-100 with letter grades:
+- A (0-14): Low risk
+- B (15-29): Moderate risk
+- C (30-49): Elevated risk
+- D (50-69): High risk
+- F (70+): Critical risk
+
+## 📚 Datasets & Research
 
 - [CUAD](https://huggingface.co/datasets/theatticusproject/cuad-qa) — 510 contracts, 13K annotations, 41 clause categories
 - [LegalBench](https://huggingface.co/datasets/nguha/legalbench) — 322 legal reasoning tasks
 - [LexGLUE](https://huggingface.co/datasets/coastalcph/lex_glue) — Unfair Terms of Service classification
+- Paper: [CUAD: An Expert-Annotated NLP Dataset for Legal Contract Review](https://arxiv.org/abs/2103.06268) (Hendrycks et al., 2021)
 
 ## 🚀 Usage
 
-1. Upload a contract (PDF, DOCX, or TXT) or paste text directly
+1. **Upload** a contract (PDF, DOCX, or TXT) or paste text directly
 2. Click **Analyze Contract**
-3. View results across tabs: Document, Clauses, Entities, Contradictions
-4. Download JSON/CSV reports
+3. View results across tabs:
+   - **Document**: Full text with inline entity highlights
+   - **Clauses**: Detected clauses with risk badges
+   - **Entities**: Extracted parties, dates, money, jurisdictions
+   - **Contradictions**: Conflicting clauses and missing provisions
+   - **Obligations**: Action items categorized by type
+   - **Compliance**: Regulatory framework checks
+4. **Export** JSON/CSV reports
+
+## 🔀 Compare Contracts
+
+Switch to the **Compare Contracts** tab to:
+- Upload or paste two contracts side-by-side
+- See clause-level diffs (added, removed, modified)
+- Get an alignment score and risk delta
+- View raw JSON comparison data
 
 ## ⚠️ Disclaimer
 
-*Not legal advice. ClauseGuard is an AI-powered analysis tool for informational purposes only. Always consult a qualified attorney for legal decisions.*
+*Not legal advice. ClauseGuard is an AI-powered analysis tool for informational purposes only. Always consult a qualified attorney for legal decisions. The tool may miss nuances and should be used as a preliminary screening aid, not a substitute for professional legal review.*
 
 ## 🔗 Links
 
-- [Space](https://huggingface.co/spaces/gaurv007/ClauseGuard)
-- [CUAD Paper](https://arxiv.org/abs/2103.06268)
-- [LegalBench](https://huggingface.co/datasets/nguha/legalbench)
+- [ClauseGuard Space](https://huggingface.co/spaces/gaurv007/ClauseGuard)
+- [Clause Classifier Model](https://huggingface.co/Mokshith31/legalbert-contract-clause-classification)
+- [Legal-BERT Base](https://huggingface.co/nlpaueb/legal-bert-base-uncased)
+- [CUAD Dataset](https://huggingface.co/datasets/theatticusproject/cuad-qa)
+- [CUAD Paper (arXiv:2103.06268)](https://arxiv.org/abs/2103.06268)
+
+---
+
+*Built with ❤️ using Gradio, Hugging Face Transformers, and Legal-BERT. Open source and free for all.*