README.md

---
title: Legal Deed Reviewer
emoji: ⚖️
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 6.0.1
app_file: app.py
pinned: false
license: mit
short_description: AI-powered legal deed analysis
tags:
  - mcp
  - mcp-in-action-track-consumer
  - legal
  - document-analysis
  - gradio
  - ai
  - legal-tech
  - property
  - deed-analysis
---

# ⚖️ Legal Deed Reviewer

**AI-powered legal deed analysis using MCP (Model Context Protocol) servers**

Upload property deed documents to receive comprehensive risk assessments, clause-by-clause breakdowns, and plain-language explanations of legal issues.

Social media link: https://www.linkedin.com/posts/pial-ghosh-38bb45302_huggingface-ai-legaltech-share-7400767193354842112-1tG3
Demo video link: https://youtu.be/31b2ouvrZVY

## 🎯 Overview

Legal Deed Reviewer is an intelligent system that helps property buyers, landlords, lawyers, and mortgage teams understand the risks and implications in legal deed documents. Built for the **MCP-1st-Birthday Hackathon (Customer Applications category)**, this project demonstrates advanced MCP integration with multi-tool orchestration for legal document analysis.

### **What This Tool Does:**

✅ **Deed Classification** - Automatically identifies deed type (sale, mortgage, lease, gift, warranty, quitclaim)  
✅ **Metadata Extraction** - Extracts parties, property details, consideration, and jurisdiction  
✅ **Clause Breakdown** - Splits deeds into logical sections and clauses  
✅ **Risk Analysis** - Identifies legal risks with severity levels (LOW/MEDIUM/HIGH)  
✅ **Plain-Language Explanations** - Translates legal jargon into understandable language  
✅ **Actionable Recommendations** - Suggests next steps and areas requiring legal consultation

## 🚀 Quick Start

1. **Upload a PDF** - Click "Upload Deed (PDF)" and select your property deed document
2. **Click "Analyze Deed"** - The system will process your document takes 30 seconds or more(depends on document).
3. **Review Results** - Navigate through tabs:
   - **Overview**: Deed metadata and quick stats
   - **Clause Breakdown**: All identified clauses with categorization
   - **Risk Analysis**: Clause-by-clause risk assessment with explanations
   - **Extracted Text**: Full text from the deed
4. **Download Report** - Get a Markdown report for your records


## 🏗️ Architecture

### MCP Integration

This project uses **5 MCP tools** that work together to provide comprehensive deed analysis:

#### **1. PDF Text Extraction**
```python
extract_text_from_deed_pdf(pdf_path: str) -> JSON
```
- Direct text extraction from PDFs using PyMuPDF
- OCR fallback for scanned documents
- Returns full text + page-by-page breakdown

#### **2. Clause Splitting**
```python
split_deed_into_clauses(text: str) -> JSON
```
- Pattern-based clause detection
- Identifies common deed sections (WITNESSETH, WHEREAS, NOW THEREFORE)
- Categorizes clause types

#### **3. Deed Classification**
```python
classify_deed_type(deed_text: str) -> JSON
```
- LLM-powered deed type identification
- Extracts jurisdiction, parties, property details
- Structured JSON output

#### **4. Risk Analysis**
```python
analyze_deed_risks(clauses: str, classification: str) -> JSON
```
- Clause-by-clause risk assessment
- Categories: TITLE, WARRANTY, ENCUMBRANCE, EASEMENT, RESTRICTION
- Risk levels with explanations and recommendations

#### **5. Comprehensive Report Generation**
```python
generate_comprehensive_deed_report(pdf_path: str) -> JSON
```
- Orchestrates all tools in a pipeline
- Returns complete analysis report
- Single-command full analysis

### Tech Stack

- **MCP Framework**: Model Context Protocol for tool orchestration
- **Gradio 6**: Web interface
- **FastAPI**: REST API backend
- **Nebius Qwen2.5-VL-72B**: Vision model for OCR and LLM for legal analysis
- **PyMuPDF**: PDF processing

## 📊 Sample Output

### Deed Classification
```json
{
  "deed_type": "warranty",
  "jurisdiction": {
    "country": "United States",
    "state_province": "Illinois"
  },
  "key_parties": {
    "grantor": "Michael Austin Carter and wife Laura Jean Carter",
    "grantee": "Husband and wife Address: 7421 Meadowbrook Drive"
  },
  "consideration_amount": "$250,000.00"
}
```

### Risk Analysis Example
```
RISK LEVEL: MEDIUM
CATEGORY: ENCUMBRANCE

EXPLANATION: The deed includes several exceptions and reservations that could 
affect the property's value and usability, including unpaid real estate taxes 
and existing easements.

RECOMMENDATION: Conduct a thorough title search to understand the full extent 
of encumbrances and consult with a real estate attorney to assess their impact.
```

## 🎓 Use Cases

### For Property Buyers
- Understand risks before closing
- Identify unusual clauses
- Know what questions to ask your lawyer

### For Real Estate Lawyers
- Quick first-pass review
- Standardized risk assessment
- Time-saving for routine deeds

### For Mortgage Teams
- Automated security deed screening
- Risk flagging for approval workflow
- Compliance checking

### For Landlords
- Lease deed analysis
- Easement and restriction identification
- Future resale impact assessment

## ⚠️ Legal Disclaimer

**IMPORTANT:** This tool provides analysis for informational purposes only and **does not constitute legal advice**. 

- Always consult with a qualified attorney licensed in your jurisdiction
- Legal requirements vary by location
- This tool cannot replace professional legal counsel
- Use this as a starting point for discussion with your lawyer

## 🔧 How It Works

### Multi-Step Reasoning Pipeline

The system uses intelligent multi-step reasoning:

1. **📄 Text Extraction** - Extracts text from PDF (direct or OCR)
2. **🔍 Classification** - Identifies deed type and jurisdiction
3. **✂️ Clause Segmentation** - Breaks document into logical sections
4. **⚖️ Risk Scoring** - Analyzes each clause for legal issues
5. **📝 Report Generation** - Compiles comprehensive analysis

### MCP Tool Orchestration

All tools are MCP-compliant and can be called individually or chained:

## 🏆 MCP-1st-Birthday Hackathon

This project was built for the **MCP-1st-Birthday Hackathon** for the **Customer Applications category** **mcp-in-action-track-consumer**.

### Why This Project Uses MCP

1. **Modularity** - Each legal analysis function is a separate MCP tool
2. **Composability** - Tools can be chained for complex workflows
3. **Reusability** - MCP tools work standalone or in pipelines
4. **Extensibility** - Easy to add new analysis tools (RAG, jurisdiction-specific logic)
5. **Interoperability** - Standard MCP interface for all tools

### Future Enhancements

- **RAG System**: Vector database with model clauses and legal precedents
- **Multi-Jurisdiction Support**: Country-specific risk assessments
- **Clause Comparison**: Visual diff against standard templates
- **Advanced Risk Scoring**: ML-based risk prediction
- **Multi-MCP Architecture**: Separate servers for PDF, RAG, and LLM

## 👥 Team
**Team Name:** Legal AI Team
- **Mahfuzur** - [@Nehlr1](https://huggingface.co/Nehlr1) - Sr. AI/ML enginner
- **Pial** - [@Pial2233](https://huggingface.co/Pial2233)- Jr.AI/ML enginner
- **Takib** - [@Takib25](https://huggingface.co/Takib25) - Jr. AI/ML enginner
- **Sojib** -[@SaikotSojib](https://huggingface.co/SaikotSojib)- Jr. AI/ML enginner

## 🔗 Links
- **Hugging Face Space**: This Space!
- **MCP Documentation**: [Model Context Protocol](https://modelcontextprotocol.io/)

## 📄 License

MIT License - See LICENSE file for details

---

**Made with ⚖️ for the MCP-1st-Birthday Hackathon**

*Empowering users to understand legal documents through AI*