Final Repor Updated

.dockerignore

@@ -0,0 +1,21 @@
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+.Python
+env
+pip-log.txt
+pip-delete-this-directory.txt
+.tox
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.log
+.git
+.mypy_cache
+.pytest_cache
+.hypothesis
+.DS_Store

.gitignore

@@ -1,23 +1,10 @@
-# Model files (too large for GitHub)
-models/embeddings/model.safetensors
-models/legal-bert/model.safetensors
-models/
-
-# Sample data directories (very large)
-data/sample_data/
-basic_streamlit/
-
-# Database files
-*.db
-*.sqlite3
-*.sqlite
-basic_streamlit/legal_market_terms.db
-
-# Python
+# Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]
 *$py.class
 *.so
+
+# Distribution / packaging
 .Python
 build/
 develop-eggs/
@@ -31,83 +18,59 @@ parts/
 sdist/
 var/
 wheels/
-share/python-wheels/
 *.egg-info/
 .installed.cfg
 *.egg
-MANIFEST
 
 # Virtual environments
-env/
 venv/
-.venv/
-.env
+env/
 ENV/
 
-# IDE
+# IDEs
 .vscode/
 .idea/
 *.swp
 *.swo
-*~
 
 # OS
 .DS_Store
-.DS_Store?
-._*
-.Spotlight-V100
-.Trashes
-ehthumbs.db
 Thumbs.db
 
-# Jupyter
-.ipynb_checkpoints/
-
 # Logs
-*.log
 logs/
+*.log
+
+# Environment variables
+.env
+.env.local
+.env.dev
+.env.prod
+
+# Model downloads (if stored locally)
+models/
+cache/models/
+
+# Uploaded files (if stored temporarily)
+uploads/
 
 # Cache directories
 .cache/
-cache/
-
-# Streamlit
-.streamlit/
+__pycache__/
 
-# Temporary files
-*.tmp
-*.temp
+# Reports generated
+*.pdf
+reports/
 
-# Documentation
-_site/
-.sass-cache/
-.jekyll-cache/
+# Jupyter notebooks checkpoints
+.ipynb_checkpoints/
 
 # Coverage reports
-htmlcov/
 .coverage
-.coverage.*
- coverage.xml
-*.cover
-*.py,cover
-.hypothesis/
-.pytest_cache/
-
-# MyPy
-.mypy_cache/
-.dmypy.json
-dmypy.json
+htmlcov/
 
-# Pyre
-.pyre/
+# Environment-specific files
+.envrc
 
-# Environment variables
-.env
-.env.local
-.env.production
-
-# Large file types that might be generated
-*.pdf
-*.docx
-*.zip
-*.tar.gz
+# Special Case
+basic_streamlit/

Dockerfile

@@ -0,0 +1,80 @@
+# Use Python 3.11 for better performance and compatibility
+FROM python:3.11-slim
+
+# Set working directory
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    curl \
+    wget \
+    git \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements first for better caching
+COPY requirements.txt .
+
+# Install Python dependencies
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Download spaCy model
+RUN python -m spacy download en_core_web_sm
+
+# Install Ollama
+RUN curl -fsSL https://ollama.ai/install.sh | sh
+
+# Copy application code
+COPY . .
+
+# Create necessary directories
+RUN mkdir -p uploads cache logs cache/models models
+
+# Download pre-trained models in advance
+RUN python -c "
+from model_manager.model_loader import ModelLoader
+from config.settings import settings
+import logging
+
+# Configure basic logging
+logging.basicConfig(level=logging.INFO)
+
+try:
+    print('Pre-downloading AI models...')
+    loader = ModelLoader()
+    loader.ensure_models_downloaded()
+    print('All models downloaded successfully!')
+except Exception as e:
+    print(f'Model download warning: {e}')
+    print('Models will be downloaded on first use...')
+"
+
+# Start Ollama server and pull model in background
+RUN ollama serve &
+RUN sleep 10 && ollama pull llama3:8b &
+
+# Expose port (required for Hugging Face Spaces)
+EXPOSE 7860
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:7860/docs || exit 1
+
+# Start the application
+CMD ["sh", "-c", "
+    # Start Ollama server in background
+    echo 'Starting Ollama server...'
+    ollama serve &
+    
+    # Wait for Ollama to start
+    echo 'Waiting for Ollama to start...'
+    sleep 15
+    
+    # Ensure the model is pulled
+    echo 'Checking for Ollama model...'
+    ollama pull llama3:8b &
+    
+    # Start the FastAPI application
+    echo 'Starting AI Contract Risk Analyzer...'
+    uvicorn main:app --host 0.0.0.0 --port 7860 --reload
+"]

README.md

@@ -1,3 +1,14 @@
+---
+title: AI Contract Risk Analyzer
+emoji: 📝
+colorFrom: blue
+colorTo: purple
+sdk: docker
+app_file: Dockerfile
+pinned: false
+license: mit
+---
+
 <div align="center">
 
 # AI Contract Risk Analyzer 🤖⚖️
@@ -5,25 +16,33 @@
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![FastAPI](https://img.shields.io/badge/FastAPI-0.104+-green.svg)](https://fastapi.tiangolo.com/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Hugging Face Spaces](https://img.shields.io/badge/🤗-Hugging%20Face%20Spaces-blue)](https://huggingface.co/spaces)
+[![Transformers](https://img.shields.io/badge/🤗-Transformers-ffcc33)](https://huggingface.co/transformers/)
+[![PyTorch](https://img.shields.io/badge/PyTorch-2.1+-ee4c2c)](https://pytorch.org/)
+[![Legal-BERT](https://img.shields.io/badge/Legal--BERT-nlpaueb/legal--bert--base--uncased-orange)](https://huggingface.co/nlpaueb/legal-bert-base-uncased)
+[![Sentence-BERT](https://img.shields.io/badge/Sentence--BERT-all--MiniLM--L6--v2-lightgrey)](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2)
+[![Ollama](https://img.shields.io/badge/Ollama-llama3:8b-7c3aed)](https://ollama.ai/)
+[![Docker](https://img.shields.io/badge/Docker-Ready-2496ed)](https://docker.com/)
+[![spaCy](https://img.shields.io/badge/spaCy-3.7+-09a3d5)](https://spacy.io/)
 
 > **Democratizing Legal Intelligence Through AI**  
-> Comprehensive contract risk analysis using Legal-BERT, multi-model NLP, and LLM integration
+> Comprehensive contract risk analysis using an integrated pipeline with Legal-BERT, multi-model NLP, and LLM interpretation
 
 </div>
 
-
 ## 🎯 Overview
 
-The AI Contract Risk Analyzer is a production-grade legal document analysis platform that leverages state-of-the-art NLP and machine learning to provide instant, comprehensive contract risk assessment. Built with Legal-BERT for clause understanding, semantic embeddings for similarity matching, and LLM integration for natural language explanations.
+The AI Contract Risk Analyzer is a production-grade legal document analysis platform that leverages state-of-the-art NLP and machine learning to provide instant, comprehensive contract risk assessment. Built with a unified orchestration architecture, it integrates Legal-BERT for clause understanding, semantic embeddings for similarity matching, and LLMs for natural language explanations.
 
 ### Key Features
 
-- 📄 **Multi-Format Support**: PDF, DOCX document processing
-- 🔍 **12+ Contract Categories**: Employment, NDA, Lease, Service agreements, etc.
-- ⚡ **Sub-30s Analysis**: Real-time risk scoring and clause extraction
+- 📄 **Multi-Format Support**: PDF, DOCX, TXT document processing
+- 🔍 **9 Contract Categories**: Employment, NDA, Lease, Service agreements, etc.
+- ⚡ **Sub-60s Analysis**: Real-time risk scoring and clause extraction via pre-loaded models
 - 🔒 **Privacy-First**: Ephemeral processing, zero data retention
-- 🌐 **LLM Integration**: Ollama, OpenAI, Anthropic support
-- 📊 **Comprehensive Reports**: Executive summaries, negotiation points, market comparisons
+- 🌐 **LLM Integration**: Ollama (local), OpenAI, Anthropic support with fallback
+- 📊 **Comprehensive Reports**: Executive summaries, negotiation playbooks, market comparisons, and downloadable PDFs
+- 🔄 **Integrated Pipeline**: A single orchestrator (`PreloadedAnalysisService`) ensures consistent context propagation from classification through to final reporting
 
 ---
 
@@ -37,6 +56,7 @@ The AI Contract Risk Analyzer is a production-grade legal document analysis plat
 - [Configuration](#-configuration)
 - [Development](#-development)
 - [Performance](#-performance)
+- [Documentation & Blog](#-documentation--blog)
 - [License](#-license)
 
 ---
@@ -45,6 +65,8 @@ The AI Contract Risk Analyzer is a production-grade legal document analysis plat
 
 ### System Overview
 
+This diagram illustrates the core components and their interactions, highlighting the unified orchestration and the flow of context (specifically the `ContractType`) through the system.
+
 ```
 ┌─────────────────────────────────────────────────────────────┐
 │                      Client Layer                           │
@@ -109,113 +131,114 @@ The AI Contract Risk Analyzer is a production-grade legal document analysis plat
 └─────────────────────────────────────────────────────────────┘
 ```
 
-### Analysis Pipeline Flowchart
+
+### Integrated Analysis Pipeline Flowchart
 
 ```mermaid
 graph TB
-    Start[User Uploads Contract PDF/DOCX] --> Read[Document Reader]
+    Start[User Uploads Contract] --> Read[Document Reader]
     Read --> Validate{Contract Validator}
     Validate -->|Invalid| Error[Return Error]
     Validate -->|Valid| Classify[Contract Classifier]
     
-    Classify --> Extract[Clause Extractor]
+    Classify --> Extract[RiskClauseExtractor]
+    Extract --> Analyze[TermAnalyzer + ProtectionChecker]
+    Analyze --> Score[RiskAnalyzer]
+    Score --> Generate[Output Generators]
     
-    Extract --> Risk[Risk Analyzer]
-    Extract --> Terms[Term Analyzer]
-    Extract --> Protect[Protection Checker]
-    Extract --> Market[Market Comparator]
+    Generate --> Sum[SummaryGenerator]
+    Generate --> Interp[LLM Interpreter]
+    Generate --> Neg[Negotiation Engine]
+    Generate --> PDF[PDF Report Generator]
     
-    Risk --> Aggregate[Result Aggregator]
-    Terms --> Aggregate
-    Protect --> Aggregate
-    Market --> Aggregate
-    
-    Extract --> LLM[LLM Interpreter]
-    LLM --> Aggregate
-    
-    Risk --> Negotiate[Negotiation Engine]
-    Terms --> Negotiate
-    Protect --> Negotiate
-    Negotiate --> Aggregate
-    
-    Aggregate --> Report[Executive Summary]
-    Report --> End[JSON Response + PDF Report]
+    Sum --> End[JSON Response]
+    Interp --> End
+    Neg --> End
+    PDF --> End
     
     style Start fill:#e1f5e1
     style End fill:#e1f5e1
     style Error fill:#ffe1e1
     style Classify fill:#e1e5ff
     style Extract fill:#e1e5ff
-    style Risk fill:#ffe5e1
-    style LLM fill:#fff5e1
-    style Negotiate fill:#f5e1ff
+    style Score fill:#ffe5e1
+    style Generate fill:#fff5e1
 ```
 
 ### Component Diagram
 
 ```mermaid
 graph LR
-    subgraph "Frontend"
-        UI[HTML/CSS/JS]
+    subgraph "Client"
+        UI[Browser / API Client]
     end
-    
-    subgraph "Backend (FastAPI)"
-        API[REST API]
-        Jobs[Job Queue]
+
+    subgraph "FastAPI Backend"
+        API[FastAPI Server]
+        PAS[PreloadedAnalysisService]
     end
-    
-    subgraph "Services"
-        C[Classifier]
-        E[Extractor]
-        R[Risk]
-        T[Terms]
-        P[Protection]
-        L[LLM]
-        N[Negotiation]
-        M[Market]
+
+    subgraph "Core Services"
+        CC[Contract Classifier]
+        RCE[Risk Clause Extractor]
+        TA[Term Analyzer]
+        PC[Protection Checker]
+        RA[Comprehensive Risk Analyzer]
+        SG[Summary Generator]
+        LI[LLM Interpreter]
+        NE[Negotiation Engine]
+        PR[PDF Report Generator]
     end
-    
-    subgraph "Model Manager"
-        Reg[Registry]
-        Load[Loader]
-        Cache[Cache]
-        LLMMgr[LLM Manager]
+
+    subgraph "Model Management"
+        MM[Model Manager]
+        MR[Model Registry]
+        LM[LLM Manager]
     end
-    
+
     subgraph "AI Models"
-        BERT[Legal-BERT]
-        SBERT[Sentence-BERT]
-        Ollama[Ollama]
-        OpenAI[OpenAI]
-        Claude[Anthropic]
+        LB[Legal-BERT]
+        ST[Sentence-BERT]
+        OLM[Ollama]
+        OAI[OpenAI]
+        ANT[Anthropic]
     end
-    
-    UI -->|HTTP| API
-    API --> Jobs
-    Jobs --> C
-    C --> E
-    E --> R
-    E --> T
-    E --> P
-    E --> M
-    E --> L
-    L --> N
-    
-    C --> Reg
-    E --> Reg
-    R --> Reg
-    M --> Reg
-    L --> LLMMgr
-    N --> LLMMgr
-    
-    Reg --> Load
-    Load --> Cache
-    Cache --> BERT
-    Cache --> SBERT
-    
-    LLMMgr --> Ollama
-    LLMMgr --> OpenAI
-    LLMMgr --> Claude
+
+    UI --> API
+    API --> PAS
+    PAS --> CC
+    PAS --> RCE
+    PAS --> TA
+    PAS --> PC
+    PAS --> RA
+    PAS --> SG
+    PAS --> LI
+    PAS --> NE
+    PAS --> PR
+
+    CC -.-> RCE
+    RCE --> TA
+    RCE --> PC
+    TA --> RA
+    PC --> RA
+    RCE --> RA
+
+    RA --> SG
+    RA --> LI
+    RA --> NE
+    SG --> PR
+    LI --> PR
+    NE --> PR
+
+    PAS --> MM
+    MM --> MR
+    MM --> LM
+
+    MR --> LB
+    MR --> ST
+    LM --> OLM
+    LM --> OAI
+    LM --> ANT
 ```
 
 ---
@@ -232,11 +255,11 @@ Storage: 10GB for models
 GPU: Optional (3x speedup with NVIDIA GPU + CUDA 11.8+)
 ```
 
-### Option 1: Quick Install (Recommended)
+### Quick Install
 
 ```bash
 # Clone repository
-git clone https://github.com/yourusername/contract-guard-ai.git
+git clone https://github.com/satyaki-mitra/contract-guard-ai.git  
 cd contract-guard-ai
 
 # Create virtual environment
@@ -249,41 +272,10 @@ pip install -r requirements.txt
 # Download spaCy model (optional, for advanced text processing)
 python -m spacy download en_core_web_sm
 
-# Download AI models (automatic on first run, or manual)
+# Initialize models (on first run)
 python -c "from model_manager.model_loader import ModelLoader; ModelLoader()"
 ```
 
-### Option 2: Docker Installation
-
-```bash
-# Build Docker image
-docker build -t contract-analyzer .
-
-# Run container
-docker run -p 8000:8000 -v ./models:/app/models contract-analyzer
-
-# With GPU support
-docker run --gpus all -p 8000:8000 -v ./models:/app/models contract-analyzer
-```
-
-### Option 3: Development Setup
-
-```bash
-# Install in editable mode with dev dependencies
-pip install -e ".[dev]"
-
-# Install pre-commit hooks
-pre-commit install
-
-# Run tests
-pytest tests/
-
-# Run linting
-flake8 .
-black .
-mypy .
-```
-
 ---
 
 ## ⚡ Quick Start
@@ -291,7 +283,7 @@ mypy .
 ### 1. Start Required Services
 
 ```bash
-# Terminal 1: Start Ollama (for LLM features)
+# Start Ollama (for local LLM features)
 ollama serve
 
 # Pull LLM model
@@ -332,370 +324,13 @@ MIN_CONTRACT_LENGTH=300
 ### 3. Launch Application
 
 ```bash
-# Option A: Use launch script (starts API + Frontend)
-python launch.py
-
-# Option B: Start API only
+# Option A: Start API only
 python app.py
 
-# Option C: Use Uvicorn directly
+# Option B: Use Uvicorn directly
 uvicorn app:app --reload --host 0.0.0.0 --port 8000
 ```
 
-### 4. Access Services
-
-- **API**: http://localhost:8000
-- **Interactive Docs**: http://localhost:8000/api/docs
-- **Health Check**: http://localhost:8000/api/v1/health
-
-### 5. Analyze Your First Contract
-
-```bash
-# Using cURL
-curl -X POST "http://localhost:8000/api/v1/analyze" \
-  -F "file=@/path/to/contract.pdf" \
-  -F "max_clauses=15" \
-  -F "interpret_clauses=true" \
-  -F "llm_provider=ollama"
-
-# Response (job created)
-{
-  "job_id": "abc-123-def-456",
-  "status": "pending",
-  "progress": 0,
-  "message": "Analysis queued"
-}
-
-# Check status
-curl "http://localhost:8000/api/v1/jobs/abc-123-def-456"
-
-# Response (completed)
-{
-  "job_id": "abc-123-def-456",
-  "status": "completed",
-  "progress": 100,
-  "result": {
-    "overall_score": 78,
-    "risk_level": "HIGH",
-    "clauses": [...],
-    "unfavorable_terms": [...],
-    ...
-  }
-}
-```
-
----
-
-## 📚 API Documentation
-
-### Core Endpoints
-
-#### 1. Analyze Contract (Async)
-
-```http
-POST /api/v1/analyze
-Content-Type: multipart/form-data
-
-Parameters:
-  - file: File (required) - PDF or DOCX contract
-  - max_clauses: int (default: 15) - Max clauses to extract
-  - interpret_clauses: bool (default: true) - Generate plain-English explanations
-  - generate_negotiation_points: bool (default: true) - Create negotiation strategy
-  - compare_to_market: bool (default: true) - Compare to market standards
-  - llm_provider: str (default: "ollama") - LLM provider: ollama/openai/anthropic
-
-Response: 202 Accepted
-{
-  "job_id": "uuid",
-  "status": "pending",
-  "progress": 0,
-  "message": "Analysis queued",
-  "created_at": "ISO-8601 timestamp"
-}
-```
-
-#### 2. Get Job Status
-
-```http
-GET /api/v1/jobs/{job_id}
-
-Response: 200 OK
-{
-  "job_id": "uuid",
-  "status": "completed",  // pending/processing/completed/failed
-  "progress": 100,
-  "message": "Analysis complete",
-  "result": {
-    "analysis_id": "uuid",
-    "timestamp": "ISO-8601",
-    "classification": {...},
-    "clauses": [...],
-    "risk_analysis": {...},
-    "unfavorable_terms": [...],
-    "missing_protections": [...],
-    "clause_interpretations": [...],
-    "negotiation_points": [...],
-    "market_comparisons": [...],
-    "executive_summary": "text",
-    "metadata": {...}
-  }
-}
-```
-
-#### 3. Health Check
-
-```http
-GET /api/v1/health
-
-Response: 200 OK
-{
-  "status": "healthy",
-  "version": "1.0.0",
-  "timestamp": "ISO-8601",
-  "models_loaded": 2,
-  "gpu_available": true
-}
-```
-
-#### 4. Quick Validation
-
-```http
-POST /api/v1/validate
-Content-Type: multipart/form-data
-
-Parameters:
-  - file: File (required)
-
-Response: 200 OK
-{
-  "is_valid": true,
-  "validation_type": "high_confidence",
-  "message": "Strong contract indicators (score: 45)",
-  "scores": {
-    "total": 45,
-    "indicators": 30,
-    "structural": 15
-  },
-  "features": {
-    "has_signature_block": true,
-    "has_effective_date": true,
-    "has_party_identification": true
-  }
-}
-```
-
-#### 5. List Jobs
-
-```http
-GET /api/v1/jobs?limit=10
-
-Response: 200 OK
-[
-  {
-    "job_id": "uuid",
-    "status": "completed",
-    "created_at": "ISO-8601",
-    ...
-  },
-  ...
-]
-```
-
-#### 6. Delete Job
-
-```http
-DELETE /api/v1/jobs/{job_id}
-
-Response: 200 OK
-{
-  "message": "Job deleted successfully",
-  "job_id": "uuid"
-}
-```
-
-#### 7. Get Contract Categories
-
-```http
-GET /api/v1/categories
-
-Response: 200 OK
-[
-  "employment",
-  "consulting",
-  "nda",
-  "technology",
-  "intellectual_property",
-  "real_estate",
-  "financial",
-  "business",
-  "sales",
-  "service_agreement",
-  "vendor",
-  "agency"
-]
-```
-
-#### 8. Get Market Standards
-
-```http
-GET /api/v1/market-standards/{category}
-
-Response: 200 OK
-{
-  "reasonable": "Market-standard reasonable clause text...",
-  "standard": "Typical market standard clause text...",
-  "aggressive": "Aggressive/unfavorable clause text..."
-}
-```
-
-### Response Schemas
-
-<details>
-<summary><b>Complete Analysis Result Schema</b></summary>
-
-```json
-{
-  "analysis_id": "uuid",
-  "timestamp": "2025-01-15T10:30:00.000Z",
-  
-  "classification": {
-    "category": "employment",
-    "subcategory": "full_time",
-    "confidence": 0.89,
-    "reasoning": ["Strong keyword match", "Semantic similarity 0.87"],
-    "detected_keywords": ["employee", "salary", "benefits"],
-    "alternative_categories": [
-      {"category": "consulting", "confidence": 0.43}
-    ]
-  },
-  
-  "clauses": [
-    {
-      "text": "Employee shall not engage in competitive business...",
-      "reference": "Section 8.2",
-      "category": "non_compete",
-      "confidence": 0.92,
-      "start_pos": 5432,
-      "end_pos": 5680,
-      "extraction_method": "structural",
-      "risk_indicators": ["non-compete", "competitive"],
-      "subclauses": [],
-      "legal_bert_score": 0.88
-    }
-  ],
-  
-  "risk_analysis": {
-    "overall_score": 78,
-    "risk_level": "HIGH",
-    "category_scores": {
-      "restrictive_covenants": 85,
-      "termination_rights": 72,
-      "penalties_liability": 68
-    },
-    "risk_factors": ["restrictive_covenants"],
-    "detailed_findings": {
-      "restrictive_covenants": [
-        "Duration of 24 months is excessive"
-      ]
-    },
-    "benchmark_comparison": {
-      "non_compete_duration": "✗ Exceeds market standards"
-    },
-    "risk_breakdown": [
-      {
-        "category": "Restrictive Covenants",
-        "score": 85,
-        "summary": "Analysis of non-compete clauses",
-        "findings": ["Duration 24 months excessive"]
-      }
-    ]
-  },
-  
-  "unfavorable_terms": [
-    {
-      "term": "Non Compete Overly Broad",
-      "category": "non_compete",
-      "severity": "critical",
-      "explanation": "Restricts ability to earn living",
-      "clause_reference": "Section 8.2",
-      "suggested_fix": "Limit to 6-12 months, direct competitors only"
-    }
-  ],
-  
-  "missing_protections": [
-    {
-      "protection": "'For Cause' Definition",
-      "importance": "critical",
-      "explanation": "Termination grounds are ambiguous",
-      "recommendation": "Add clear 'for cause' definition",
-      "category": "termination",
-      "examples": ["For Cause means: gross negligence, breach..."]
-    }
-  ],
-  
-  "clause_interpretations": [
-    {
-      "clause_reference": "Section 8.2",
-      "original_text": "Employee shall not engage...",
-      "plain_english_summary": "Prevents working for competitors",
-      "key_points": [
-        "Restricts future employment",
-        "Duration and scope are key factors"
-      ],
-      "potential_risks": [
-        "Could prevent earning a living in your field",
-        "24-month duration is excessive"
-      ],
-      "favorability": "unfavorable",
-      "confidence": 0.85
-    }
-  ],
-  
-  "negotiation_points": [
-    {
-      "priority": 1,
-      "category": "non_compete",
-      "issue": "Non Compete Overly Broad",
-      "current_language": "Employee shall not engage in any competitive business for 24 months globally...",
-      "proposed_language": "Employee agrees not to work for direct competitors in software industry within 50 miles for 6 months...",
-      "rationale": "Current terms unreasonably restrict ability to earn living",
-      "fallback_position": "If 6 months refused, negotiate to 12 months maximum",
-      "estimated_difficulty": "hard"
-    }
-  ],
-  
-  "market_comparisons": [
-    {
-      "clause_category": "non_compete",
-      "user_clause": "Employee shall not engage in any competitive business for 24 months...",
-      "market_standard": "Employee shall not engage in competitive activities for 12 months within geographic area...",
-      "similarity_score": 0.68,
-      "assessment": "unfavorable",
-      "explanation": "More aggressive than market standards",
-      "recommendation": "Strongly recommend negotiating to align with market norms"
-    }
-  ],
-  
-  "executive_summary": "This employment contract has been analyzed and assigned an overall risk score of 78/100, classified as HIGH risk. SIGNIFICANT CONCERNS: This contract has several unfavorable terms that should be negotiated before execution...",
-  
-  "metadata": {
-    "text_length": 15432,
-    "word_count": 2876,
-    "num_clauses": 12,
-    "contract_type": "employment",
-    "options": {
-      "max_clauses": 15,
-      "interpret_clauses": true,
-      "generate_negotiation_points": true,
-      "compare_to_market": true,
-      "llm_provider": "ollama"
-    }
-  }
-}
-```
-
-</details>
-
 ---
 
 ## 🔧 Technical Details
@@ -767,7 +402,6 @@ contract-guard-ai/
 │   ├── protection_checker.py   # Missing protections checker
 │   ├── llm_interpreter.py      # LLM-powered clause interpretation
 │   ├── negotiation_engine.py   # Negotiation points generation
-│   └── market_comparator.py    # Market standards comparison
 │
 ├── utils/                      # Utility functions
 │   ├── __init__.py
@@ -794,6 +428,7 @@ contract-guard-ai/
 ├── uploads/                    # Temporary upload storage
 │
 └── docs/                       # Documentation
+   ├── API_DOCUMENTATION.md
    └── BLOGPOST.md
 ```
 
@@ -848,20 +483,6 @@ Where:
   score = raw model confidence
 ```
 
-### Performance Characteristics
-
-#### Latency Benchmarks
-
-| Operation | p50 | p95 | p99 |
-|-----------|-----|-----|-----|
-| Document Upload | 120ms | 250ms | 380ms |
-| Contract Classification | 180ms | 320ms | 450ms |
-| Clause Extraction | 2.1s | 4.8s | 7.2s |
-| Risk Analysis | 1.8s | 3.2s | 4.5s |
-| LLM Interpretation (10 clauses) | 8.5s | 15.2s | 22.1s |
-| **Full Pipeline** | **22.3s** | **38.7s** | **52.4s** |
-
-
 #### Memory Usage
 
 ```
@@ -874,325 +495,10 @@ Total (Peak): ~1.2GB
 
 ---
 
-## ⚙️ Configuration
-
-### Application Settings (config/settings.py)
-
-```python
-from pydantic_settings import BaseSettings
-
-class Settings(BaseSettings):
-    # Application
-    APP_NAME: str = "AI Contract Risk Analyzer"
-    APP_VERSION: str = "1.0.0"
-    HOST: str = "0.0.0.0"
-    PORT: int = 8000
-    RELOAD: bool = False  # Set to True for development
-    WORKERS: int = 4
-    LOG_LEVEL: str = "INFO"
-    
-    # CORS
-    CORS_ORIGINS: list = ["*"]
-    CORS_ALLOW_CREDENTIALS: bool = True
-    CORS_ALLOW_METHODS: list = ["*"]
-    CORS_ALLOW_HEADERS: list = ["*"]
-    
-    # File Upload
-    MAX_UPLOAD_SIZE: int = 10 * 1024 * 1024  # 10MB
-    ALLOWED_EXTENSIONS: list = [".pdf", ".docx"]
-    
-    # Analysis
-    MIN_CONTRACT_LENGTH: int = 300
-    MAX_CONTRACT_LENGTH: int = 500000
-    MAX_CLAUSES_TO_ANALYZE: int = 15
-    
-    # Ollama
-    OLLAMA_BASE_URL: str = "http://localhost:11434"
-    OLLAMA_MODEL: str = "llama3:8b"
-    OLLAMA_TIMEOUT: int = 120
-    
-    # OpenAI (optional)
-    OPENAI_API_KEY: str = ""
-    
-    # Anthropic (optional)
-    ANTHROPIC_API_KEY: str = ""
-    
-    # Cache
-    ENABLE_CACHE: bool = True
-    CACHE_TTL: int = 3600
-    
-    class Config:
-        env_file = ".env"
-```
-
-### Model Configuration (config/model_config.py)
-
-```python
-from pathlib import Path
-
-class ModelConfig:
-    BASE_DIR = Path(__file__).parent.parent
-    MODEL_DIR = BASE_DIR / "models"
-    CACHE_DIR = BASE_DIR / "cache" / "models"
-    
-    # Legal-BERT Configuration
-    LEGAL_BERT = {
-        "model_name": "nlpaueb/legal-bert-base-uncased",
-        "local_path": MODEL_DIR / "legal-bert",
-        "dimension": 768,
-        "max_length": 512
-    }
-    
-    # Sentence Transformer Configuration
-    EMBEDDING_MODEL = {
-        "model_name": "sentence-transformers/all-MiniLM-L6-v2",
-        "local_path": MODEL_DIR / "embeddings",
-        "dimension": 384,
-        "max_length": 256
-    }
-    
-    # LLM Configuration
-    LLM_CONFIG = {
-        "base_url": "http://localhost:11434",
-        "model": "llama3:8b",
-        "timeout": 120
-    }
-```
-
-### Risk Rules (config/risk_rules.py)
-
-```python
-from enum import Enum
-
-class ContractType(Enum):
-    EMPLOYMENT = "employment"
-    CONSULTING = "consulting"
-    NDA = "nda"
-    SOFTWARE = "software"
-    SERVICE = "service"
-    PARTNERSHIP = "partnership"
-    LEASE = "lease"
-    PURCHASE = "purchase"
-    GENERAL = "general"
-
-class RiskRules:
-    # Critical keywords (highest risk)
-    CRITICAL_KEYWORDS = {
-        'unlimited liability': 15,
-        'perpetual': 12,
-        'irrevocable': 12,
-        'forfeit': 10,
-        'liquidated damages': 10,
-        'wage withholding': 15,
-        'joint and several': 8
-    }
-    
-    # High-risk keywords
-    HIGH_RISK_KEYWORDS = {
-        'non-compete': 8,
-        'non-solicit': 7,
-        'penalty': 6,
-        'without cause': 7,
-        'sole discretion': 8,
-        'immediate termination': 7,
-        'at-will': 6
-    }
-    
-    # Risk thresholds
-    RISK_THRESHOLDS = {
-        "critical": 80,
-        "high": 60,
-        "medium": 40,
-        "low": 20
-    }
-    
-    # Contract type-specific weight adjustments
-    TYPE_WEIGHTS = {
-        ContractType.EMPLOYMENT: {
-            "restrictive_covenants": 1.3,
-            "termination_rights": 1.2,
-            "compensation_benefits": 1.1
-        },
-        ContractType.CONSULTING: {
-            "penalties_liability": 1.3,
-            "intellectual_property": 1.2
-        },
-        ContractType.NDA: {
-            "restrictive_covenants": 1.4
-        }
-    }
-```
-
----
-
-## 💻 Development
-
-### Setting Up Development Environment
-
-```bash
-# Clone repository
-git clone https://github.com/yourusername/contract-guard-ai.git
-cd contract-guard-ai
-
-# Create virtual environment
-python -m venv venv
-source venv/bin/activate  # Windows: venv\Scripts\activate
-
-# Install in editable mode with dev dependencies
-pip install -e ".[dev]"
-
-# Install pre-commit hooks
-pre-commit install
-
-# Copy environment template
-cp .env.example .env
-```
-
-### Running Tests
-
-```bash
-# Run all tests
-pytest
-
-# Run with coverage
-pytest --cov=. --cov-report=html
-
-# Run specific test file
-pytest tests/test_classifier.py
-
-# Run with verbose output
-pytest -v -s
-
-# Run only fast tests (skip slow integration tests)
-pytest -m "not slow"
-```
-
-### Code Quality
-
-```bash
-# Format code with Black
-black .
-
-# Sort imports
-isort .
-
-# Lint with Flake8
-flake8 .
-
-# Type checking with MyPy
-mypy .
-
-# All checks (pre-commit)
-pre-commit run --all-files
-```
-
-### Adding New Services
-
-1. **Create service file** in `services/`:
-```python
-# services/my_new_service.py
-from utils.logger import ContractAnalyzerLogger, log_info
-
-class MyNewService:
-    def __init__(self):
-        self.logger = ContractAnalyzerLogger.get_logger()
-        log_info("MyNewService initialized")
-    
-    @ContractAnalyzerLogger.log_execution_time("my_operation")
-    def my_operation(self, input_data):
-        """Your service logic here"""
-        log_info("Processing...", input_size=len(input_data))
-        result = self._process(input_data)
-        return result
-```
-
-2. **Register in services/__init__.py**:
-```python
-from .my_new_service import MyNewService
-
-__all__ = [
-    # ... existing services
-    'MyNewService'
-]
-```
-
-3. **Add tests** in `tests/`:
-```python
-# tests/test_my_new_service.py
-import pytest
-from services.my_new_service import MyNewService
-
-def test_my_operation():
-    service = MyNewService()
-    result = service.my_operation("test data")
-    assert result is not None
-```
-
-4. **Integrate in app.py**:
-```python
-# Add to service initialization
-services["my_new_service"] = MyNewService()
-
-# Use in analysis pipeline
-my_result = services["my_new_service"].my_operation(data)
-```
-
-### Debugging
-
-```bash
-# Run with debug logging
-LOG_LEVEL=DEBUG python app.py
-
-# Enable API debug mode
-uvicorn app:app --reload --log-level debug
-
-# Python debugger (pdb)
-import pdb; pdb.set_trace()
-
-# VS Code launch.json
-{
-  "version": "0.2.0",
-  "configurations": [
-    {
-      "name": "FastAPI",
-      "type": "python",
-      "request": "launch",
-      "module": "uvicorn",
-      "args": ["app:app", "--reload", "--port", "8000"],
-      "jinja": true
-    }
-  ]
-}
-```
-
 ## 📝 License
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
 
-```
-MIT License
-
-Copyright (c) 2025 AI Contract Risk Analyzer Contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-```
-
 ---
 
 ## 🙏 Acknowledgments
@@ -1225,19 +531,29 @@ SOFTWARE.
 | Model Management | ✅ Stable | 88% |
 | Services | ✅ Stable | 85% |
 | Documentation | ✅ Complete | 100% |
-| Tests | 🟡 In Progress | 67% |
-| Frontend | 🟡 Beta | N/A |
+| Frontend | ✅ Stable | 80%  |
+| Tests | 🟡 In Progress | 50% |
 
 ---
 
+## 📚 Documentation & Blog
+
+- For detailed technical documentation, including API endpoints, request/response schemas, and error handling, see the [API_DOCUMENTATION.md](docs/API_DOCUMENTATION.md) file.
+
+- To learn about the research behind the system and our vision for democratizing legal intelligence, read our full [BLOGPOST.md](docs/BLOGPOST.md) file.
+---
+
 <div align="center">
 
-**Made with ❤️ by the Contract Guard AI Team**
+**Made with ❤️ by the Itobuz Technologies Private Limited**
 
-[Website](https://contractguardai.com) • [Documentation](https://docs.contractguardai.com) • [Blog](https://blog.contractguardai.com)
+• [Documentation](docs/API_DOCUMENTATION.md) 
+• [Blog](docs/BLOGPOST.md)
 
 </div>
 
 ---
 
-*© 2025 AI Contract Risk Analyzer. Making legal intelligence accessible to everyone.*
+> *© 2025 AI Contract Risk Analyzer. Making legal intelligence accessible to everyone.*
+
+---

app.py

@@ -1,509 +1,816 @@
-"""
-FastAPI Application for AI Contract Risk Analyzer - UPDATED
-Complete integration with new services pipeline and frontend requirements
-"""
-import signal
+# app.py
+# DEPENDENCIES
 import os
+import sys
 import time
 import json
 import uuid
-from typing import Any, List, Dict, Optional
+import signal
+import uvicorn
+import numpy as np
+from typing import Any
+from typing import List
+from typing import Dict
 from pathlib import Path
+from fastapi import File
+from fastapi import Form
+from pydantic import Field
+from fastapi import FastAPI
+from fastapi import Request
+from typing import Optional
 from datetime import datetime
+from pydantic import BaseModel
+from fastapi import UploadFile
+from fastapi import HTTPException
+from fastapi.responses import Response
+from fastapi.responses import JSONResponse
+from fastapi.responses import FileResponse
 from contextlib import asynccontextmanager
-
-import uvicorn
-import numpy as np
-from fastapi import FastAPI, File, UploadFile, HTTPException, Form, Request
-from fastapi.responses import JSONResponse, FileResponse, Response
-from fastapi.middleware.cors import CORSMiddleware
 from fastapi.staticfiles import StaticFiles
-from pydantic import BaseModel, Field
-import sys
+from fastapi.middleware.cors import CORSMiddleware
 
 # Add parent directory to path
 sys.path.append(str(Path(__file__).parent))
 
-# Import all services - UPDATED WITH NEW SERVICES
+from utils.logger import log_info
+from utils.logger import log_error
 from config.settings import settings
 from config.risk_rules import ContractType
-from model_manager.model_loader import ModelLoader
-from model_manager.llm_manager import LLMManager, LLMProvider
-from utils.document_reader import DocumentReader
+from services.data_models import RiskScore
 from utils.validators import ContractValidator
 from utils.text_processor import TextProcessor
-from utils.logger import ContractAnalyzerLogger, log_info, log_error
-
-# UPDATED SERVICE IMPORTS
-from services.contract_classifier import ContractClassifier, ContractCategory
-from services.clause_extractor import ComprehensiveClauseExtractor, RiskClauseExtractor, ExtractedClause
-from services.risk_analyzer import RiskAnalyzer, RiskScore
-from services.term_analyzer import TermAnalyzer, UnfavorableTerm
-from services.protection_checker import ProtectionChecker, MissingProtection
-from services.llm_interpreter import LLMClauseInterpreter, ClauseInterpretation, RiskInterpretation
-from services.negotiation_engine import NegotiationEngine, NegotiationPlaybook, NegotiationPoint
+from services.data_models import SummaryContext 
+from utils.logger import ContractAnalyzerLogger
+from services.risk_analyzer import RiskAnalyzer
+from services.term_analyzer import TermAnalyzer
+from services.data_models import ExtractedClause
+from services.data_models import UnfavorableTerm
+from utils.document_reader import DocumentReader
+from model_manager.llm_manager import LLMManager
+from services.data_models import NegotiationPoint
+from services.data_models import ContractCategory
+from model_manager.llm_manager import LLMProvider
+from model_manager.model_loader import ModelLoader
+from services.data_models import MissingProtection
+from services.data_models import RiskInterpretation
+from services.data_models import NegotiationPlaybook
+from reporter.pdf_generator import PDFReportGenerator
+from services.data_models import ClauseInterpretation
+from reporter.pdf_generator import generate_pdf_report
 from services.summary_generator import SummaryGenerator
+from services.clause_extractor import RiskClauseExtractor
+from services.negotiation_engine import NegotiationEngine
+from services.llm_interpreter import LLMClauseInterpreter
+from services.protection_checker import ProtectionChecker
+from services.contract_classifier import ContractClassifier
+from services.clause_extractor import ComprehensiveClauseExtractor
 
-# Import PDF generator
-from reporter.pdf_generator import generate_pdf_report
 
 # ============================================================================
-# CUSTOM SERIALIZATION (UNCHANGED)
+# CUSTOM SERIALIZATION METHODS
 # ============================================================================
-
 class NumpyJSONEncoder(json.JSONEncoder):
     def default(self, obj: Any) -> Any:
         if isinstance(obj, (np.float32, np.float64)):
             return float(obj)
+        
         elif isinstance(obj, (np.int32, np.int64, np.int8, np.uint8)):
             return int(obj)
+        
         elif isinstance(obj, np.ndarray):
             return obj.tolist()
+        
         elif isinstance(obj, np.bool_):
             return bool(obj)
+        
         elif hasattr(obj, 'item'):
             return obj.item()
+        
         elif hasattr(obj, 'to_dict'):
             return obj.to_dict()
+        
         elif hasattr(obj, 'dict'):
             return obj.dict()
+        
         elif isinstance(obj, (set, tuple)):
             return list(obj)
+        
         return super().default(obj)
 
+
 class NumpyJSONResponse(JSONResponse):
     def render(self, content: Any) -> bytes:
-        return json.dumps(
-            content,
-            ensure_ascii=False,
-            allow_nan=False,
-            indent=None,
-            separators=(",", ":"),
-            cls=NumpyJSONEncoder,
-        ).encode("utf-8")
+        
+        return json.dumps(obj          = content,
+                          ensure_ascii = False,
+                          allow_nan    = False,
+                          indent       = None,
+                          separators   = (",", ":"),
+                          cls          = NumpyJSONEncoder,
+                         ).encode("utf-8")
+
 
 def convert_numpy_types(obj: Any) -> Any:
     if obj is None:
         return None
+    
     if isinstance(obj, dict):
         return {key: convert_numpy_types(value) for key, value in obj.items()}
+    
     elif isinstance(obj, (list, tuple, set)):
         return [convert_numpy_types(item) for item in obj]
+    
     elif isinstance(obj, (np.float32, np.float64)):
         return float(obj)
+    
     elif isinstance(obj, (np.int32, np.int64, np.int8, np.uint8)):
         return int(obj)
+    
     elif isinstance(obj, np.ndarray):
         return obj.tolist()
+    
     elif isinstance(obj, np.bool_):
         return bool(obj)
+    
     elif hasattr(obj, 'item'):
         return obj.item()
+    
     elif hasattr(obj, 'to_dict'):
         return convert_numpy_types(obj.to_dict())
+    
     elif hasattr(obj, 'dict'):
         return convert_numpy_types(obj.dict())
+    
     else:
         return obj
 
+
 def safe_serialize_response(data: Any) -> Any:
     return convert_numpy_types(data)
 
-# ============================================================================
-# PYDANTIC SCHEMAS - UPDATED FOR FRONTEND COMPATIBILITY
-# ============================================================================
 
+# PYDANTIC SCHEMAS 
 class SerializableBaseModel(BaseModel):
     def dict(self, *args, **kwargs) -> Dict[str, Any]:
         data = super().dict(*args, **kwargs)
         return convert_numpy_types(data)
+
     
     def json(self, *args, **kwargs) -> str:
         data = self.dict(*args, **kwargs)
-        return json.dumps(data, cls=NumpyJSONEncoder, *args, **kwargs)
+        return json.dumps(data, cls = NumpyJSONEncoder, *args, **kwargs)
+
 
 class HealthResponse(SerializableBaseModel):
-    status: str
-    version: str
-    timestamp: str
-    models_loaded: int
-    services_loaded: int
-    memory_usage_mb: float
+    status          : str
+    version         : str
+    timestamp       : str
+    models_loaded   : int
+    services_loaded : int
+    memory_usage_mb : float
+
 
 class AnalysisOptions(SerializableBaseModel):
-    max_clauses: int = Field(default=15, ge=5, le=30)
-    interpret_clauses: bool = Field(default=True)
-    generate_negotiation_points: bool = Field(default=True)
-    compare_to_market: bool = Field(default=False)  # Disabled for now
+    max_clauses                 : int  = Field(default = 50, ge = 5, le = 30)
+    interpret_clauses           : bool = Field(default = True)
+    generate_negotiation_points : bool = Field(default = True)
+    compare_to_market           : bool = Field(default = False)  # Disabled for now
+
 
 class AnalysisResult(SerializableBaseModel):
-    analysis_id: str
-    timestamp: str
-    classification: Dict[str, Any]
-    clauses: List[Dict[str, Any]]
-    risk_analysis: Dict[str, Any]
-    unfavorable_terms: List[Dict[str, Any]]
-    missing_protections: List[Dict[str, Any]]
-    clause_interpretations: Optional[List[Dict[str, Any]]] = None
-    negotiation_points: Optional[List[Dict[str, Any]]] = None
-    market_comparisons: Optional[List[Dict[str, Any]]] = None
-    executive_summary: str
-    metadata: Dict[str, Any]
-    pdf_available: bool = True
+    analysis_id            : str
+    timestamp              : str
+    classification         : Dict[str, Any]
+    clauses                : List[Dict[str, Any]]
+    risk_analysis          : Dict[str, Any]
+    unfavorable_terms      : List[Dict[str, Any]]
+    missing_protections    : List[Dict[str, Any]]
+    clause_interpretations : Optional[List[Dict[str, Any]]] = None
+    negotiation_points     : Optional[List[Dict[str, Any]]] = None
+    market_comparisons     : Optional[List[Dict[str, Any]]] = None
+    executive_summary      : str
+    metadata               : Dict[str, Any]
+    pdf_available          : bool                           = True
+
 
 class ErrorResponse(SerializableBaseModel):
-    error: str
-    detail: str
-    timestamp: str
+    error     : str
+    detail    : str
+    timestamp : str
+
 
 class FileValidationResponse(SerializableBaseModel):
-    valid: bool
-    message: str
-    confidence: Optional[float] = None
-    report: Optional[Dict[str, Any]] = None
+    valid      : bool
+    message    : str
+    confidence : Optional[float]          = None
+    report     : Optional[Dict[str, Any]] = None
 
-# ============================================================================
-# SERVICE INITIALIZATION WITH FULL PIPELINE INTEGRATION
-# ============================================================================
 
+# SERVICE INITIALIZATION WITH FULL PIPELINE INTEGRATION
 class PreloadedAnalysisService:
-    """Analysis service with complete pipeline integration"""
-    
+    """
+    Analysis service with complete pipeline integration
+    """
     def __init__(self):
-        self.model_loader = ModelLoader()
-        self.llm_manager = LLMManager()
-        self.services = {}
-        self.service_status = {}
+        self.model_loader    = ModelLoader()
+        self.llm_manager     = LLMManager() 
+        self.services        = dict()
+        self.service_status  = dict()
         self.memory_usage_mb = 0
+
         self._preload_all_services()
-    
+
+
     def _preload_all_services(self):
-        """Pre-load ALL services and models at initialization"""
+        """
+        Pre-load ALL services and models at initialization
+        """
         log_info("PRE-LOADING ALL AI MODELS AND SERVICES")
-        
         try:
             initial_memory = self._get_memory_usage()
-            
-            # 1. Pre-load Contract Classifier
+
+            # Pre-load Contract Classifier
             log_info("🔄 Pre-loading Contract Classifier...")
-            self.services["classifier"] = ContractClassifier(self.model_loader)
-            self.service_status["classifier"] = "loaded"
-            log_info("✅ Contract Classifier loaded")
+            try:
+                self.services["classifier"]       = ContractClassifier(self.model_loader)
+                self.service_status["classifier"] = "loaded"
+                log_info("✅ Contract Classifier loaded")
             
-            # 2. Pre-load Comprehensive Clause Extractor
+            except Exception as e:
+                log_error(f"Failed to load ContractClassifier: {repr(e)}")
+                raise
+
+            # Pre-load ComprehensiveClauseExtractor as base for RiskClauseExtractor
             log_info("🔄 Pre-loading Comprehensive Clause Extractor...")
-            self.services["clause_extractor"] = ComprehensiveClauseExtractor(self.model_loader)
-            self.service_status["clause_extractor"] = "loaded"
-            log_info("✅ Comprehensive Clause Extractor loaded")
+            try:
+                self.services["comprehensive_extractor"]       = ComprehensiveClauseExtractor(self.model_loader)
+                self.service_status["comprehensive_extractor"] = "loaded"
+
+                log_info("✅ Comprehensive Clause Extractor loaded")
             
-            # 3. Pre-load Risk Analyzer (Main Orchestrator)
+            except Exception as e:
+                log_error(f"Failed to load ComprehensiveClauseExtractor: {repr(e)}")
+                raise
+
+            # Initialize RiskClauseExtractor with default type (will be recreated per analysis)
+            log_info("🔄 Initializing Risk-Focused Clause Extractor...")
+            try:
+                self.services["clause_extractor"]       = RiskClauseExtractor(model_loader  = self.model_loader,
+                                                                              contract_type = ContractType.GENERAL,
+                                                                             )
+                self.service_status["clause_extractor"] = "loaded"
+
+                log_info("✅ Risk-Focused Clause Extractor initialized")
+
+            except Exception as e:
+                log_error(f"Failed to initialize RiskClauseExtractor: {repr(e)}")
+                raise
+
+            # Pre-load RiskAnalyzer
             log_info("🔄 Pre-loading Risk Analyzer...")
-            self.services["risk_analyzer"] = RiskAnalyzer(self.model_loader)
-            self.service_status["risk_analyzer"] = "loaded"
-            log_info("✅ Risk Analyzer loaded")
+            try:
+                # RiskAnalyzer orchestrates other services but doesn't need to initialize them separately
+                self.services["risk_analyzer"]       = RiskAnalyzer(self.model_loader)
+                self.service_status["risk_analyzer"] = "loaded"
+
+                log_info("✅ Comprehensive Risk Analyzer loaded")
             
-            # 4. Pre-load LLM Interpreter
+            except Exception as e:
+                log_error(f"Failed to load RiskAnalyzer: {repr(e)}")
+                raise
+
+            # Pre-load LLM Interpreter 
             log_info("🔄 Pre-loading LLM Interpreter...")
             try:
-                self.services["llm_interpreter"] = LLMClauseInterpreter(self.llm_manager)
+                self.services["llm_interpreter"]       = LLMClauseInterpreter(self.llm_manager)
                 self.service_status["llm_interpreter"] = "loaded"
+
                 log_info("✅ LLM Interpreter loaded")
+
             except Exception as e:
-                self.services["llm_interpreter"] = None
-                self.service_status["llm_interpreter"] = f"failed: {str(e)}"
+                self.services["llm_interpreter"]       = None
+                self.service_status["llm_interpreter"] = f"failed: {repr(e)}"
+
                 log_info("⚠️  LLM Interpreter not available")
-            
-            # 5. Pre-load Negotiation Engine
+
+            # Pre-load Negotiation Engine
             log_info("🔄 Pre-loading Negotiation Engine...")
             try:
-                self.services["negotiation_engine"] = NegotiationEngine(self.llm_manager)
+                # Initialize with LLM manager - ensure constructor args match
+                self.services["negotiation_engine"]       = NegotiationEngine(llm_manager      = self.llm_manager, 
+                                                                              default_provider = LLMProvider.OLLAMA,
+                                                                             )
                 self.service_status["negotiation_engine"] = "loaded"
+
                 log_info("✅ Negotiation Engine loaded")
+            
             except Exception as e:
-                self.services["negotiation_engine"] = None
-                self.service_status["negotiation_engine"] = f"failed: {str(e)}"
+                self.services["negotiation_engine"]       = None
+                self.service_status["negotiation_engine"] = f"failed: {repr(e)}"
+
                 log_info("⚠️  Negotiation Engine not available")
-            
-            # 6. Pre-load Summary Generator
+
+            # Pre-load Summary Generator
             log_info("🔄 Pre-loading Summary Generator...")
             try:
-                self.services["summary_generator"] = SummaryGenerator(self.llm_manager)
+                # Initialize with LLM manager
+                self.services["summary_generator"]       = SummaryGenerator(llm_manager = self.llm_manager)
                 self.service_status["summary_generator"] = "loaded"
+                
                 log_info("✅ Summary Generator loaded")
+            
             except Exception as e:
-                self.services["summary_generator"] = SummaryGenerator()
+                # Fallback if initialization fails
+                self.services["summary_generator"]       = SummaryGenerator()
                 self.service_status["summary_generator"] = "fallback_loaded"
+                
                 log_info("⚠️  Summary Generator using fallback mode")
+
+            # Pre-load Unfavorable Term Analyzer
+            log_info("🔄 Pre-loading Unfavorable Term Analyzer...")
+            try:
+                # Initialize with default contract type, will be updated per analysis
+                self.services["term_analyzer"]       = TermAnalyzer(contract_type = ContractType.GENERAL)
+                self.service_status["term_analyzer"] = "loaded"
+                
+                log_info("✅ Unfavorable Term Analyzer loaded")
+            
+            except Exception as e:
+                log_error(f"Failed to load TermAnalyzer: {repr(e)}")
+                raise
+
+            # Pre-load Missing Protection Checker
+            log_info("🔄 Pre-loading Missing Protection Checker...")
+            try:
+                # Initialize with default contract type, will be updated per analysis
+                self.services["protection_checker"]       = ProtectionChecker(contract_type = ContractType.GENERAL)
+                self.service_status["protection_checker"] = "loaded"
+                
+                log_info("✅ Protection Checker loaded")
             
+            except Exception as e:
+                log_error(f"Failed to load ProtectionChecker: {repr(e)}")
+                raise
+
             # Calculate memory usage
-            final_memory = self._get_memory_usage()
+            final_memory         = self._get_memory_usage()
             self.memory_usage_mb = final_memory - initial_memory
             
             log_info("🎉 ALL SERVICES PRE-LOADED SUCCESSFULLY!")
             log_info(f"📊 Memory Usage: {self.memory_usage_mb:.2f} MB")
             log_info(f"🔧 Services Loaded: {len(self.service_status)}")
-            
+
         except Exception as e:
             log_error(f"CRITICAL: Failed to pre-load services: {e}")
             raise
-    
+
+
     def _get_memory_usage(self) -> float:
-        """Get current memory usage in MB"""
+        """
+        Get current memory usage in MB
+        """
         try:
             import psutil
             process = psutil.Process()
             return process.memory_info().rss / 1024 / 1024
+       
         except ImportError:
             return 0.0
-    
+
+
+    def _create_fallback_negotiation_points(self, risk_score, unfavorable_terms, missing_protections):
+        """
+        Create basic negotiation points when engine fails
+        """
+        fallback_points = list()
+        # Add top unfavorable terms
+        for term in unfavorable_terms[:5]:
+            fallback_points.append({"priority"             : 1 if term.severity == "critical" else 2,
+                                    "category"             : term.category,
+                                    "issue"                : term.term,
+                                    "current_language"     : "See contract clause",
+                                    "proposed_language"    : term.suggested_fix or "Request balanced language",
+                                    "rationale"            : term.explanation,
+                                    "estimated_difficulty" : "medium"
+                                  })
+        # Add critical missing protections
+        for protection in [p for p in missing_protections if (p.importance == "critical")][:5]:
+            fallback_points.append({"priority"             : 1,
+                                    "category"             : protection.categories[0] if protection.categories else "general",
+                                    "issue"                : f"Add {protection.protection}",
+                                    "current_language"     : "[MISSING]",
+                                    "proposed_language"    : protection.suggested_language or protection.recommendation,
+                                    "rationale"            : protection.explanation,
+                                    "estimated_difficulty" : "medium"
+                                  })
+        return fallback_points
+
+
     def get_service_status(self) -> Dict[str, Any]:
-        """Get detailed service status"""
+        """
+        Get detailed service status
+        """
         model_stats = self.model_loader.get_registry_stats()
-        return {
-            "services": self.service_status,
-            "models": model_stats,
-            "memory_usage_mb": self.memory_usage_mb,
-            "total_services_loaded": len([s for s in self.service_status.values() if "loaded" in str(s)]),
-            "total_models_loaded": model_stats.get("loaded_models", 0)
-        }
-    
+        return {"services"              : self.service_status,
+                "models"                : model_stats,
+                "memory_usage_mb"       : self.memory_usage_mb,
+                "total_services_loaded" : len([s for s in self.service_status.values() if "loaded" in str(s)]),
+                "total_models_loaded"   : model_stats.get("loaded_models", 0),
+               }
+
+
     def analyze_contract(self, contract_text: str, options: AnalysisOptions) -> Dict[str, Any]:
-        """Complete contract analysis using full pipeline"""
+        """
+        Complete contract analysis using full pipeline
+        """
         try:
             log_info("Starting comprehensive contract analysis pipeline...")
-            
-            # Step 1: Classify contract
-            classification = self.services["classifier"].classify_contract(contract_text)
-            classification_dict = safe_serialize_response(classification.to_dict())
+
+            # Classify contract
+            classification                    = self.services["classifier"].classify_contract(contract_text)
+            classification_dict               = safe_serialize_response(classification.to_dict())
             log_info(f"Contract classified as: {classification.category}")
             
-            # Step 2: Extract clauses
-            clauses = self.services["clause_extractor"].extract_clauses(
-                contract_text, options.max_clauses
-            )
-            clauses_dict = [safe_serialize_response(clause.to_dict()) for clause in clauses]
-            log_info(f"Extracted {len(clauses)} clauses")
+            # Debug logging for classification
+            log_info(f"Classification details - Confidence: {classification.confidence:.3f}, "
+                     f"Subcategory: {classification.subcategory}, "
+                     f"Keywords found: {len(classification.detected_keywords)}",
+                    )
+
+            # Get ContractType enum for downstream services
+            contract_type_enum                = self._get_contract_type_enum(category_str = classification.category)
+
+            # Re-initialize RiskClauseExtractor with correct contract type: crucial for category mapping in risk analysis
+            if (hasattr(self.services["clause_extractor"], 'contract_type')):
+                self.services["clause_extractor"].contract_type    = contract_type_enum
+                self.services["clause_extractor"].category_weights = self.services["clause_extractor"].risk_rules.get_adjusted_weights(contract_type_enum)
+                
+                log_info(f"Updated RiskClauseExtractor for contract type: {contract_type_enum.value}")
             
-            # Step 3: Map to ContractType
-            contract_type = self._get_contract_type_enum(classification.category)
+            else:
+                # Fallback: create new instance if update not possible
+                self.services["clause_extractor"] = RiskClauseExtractor(model_loader  = self.model_loader,
+                                                                        contract_type = contract_type_enum,
+                                                                       )
+                log_info(f"Re-initialized RiskClauseExtractor for contract type: {contract_type_enum.value}")
+
+            # Extract Risk Focused clauses (outputs risk categories)
+            clauses      = list()
+            clauses_dict = list()
+            try:
+                # Try risk-focused extraction first
+                clauses = self.services["clause_extractor"].extract_risk_clauses(contract_text = contract_text,
+                                                                                 max_clauses   = options.max_clauses,
+                                                                                )
+                
+                log_info(f"Extracted {len(clauses)} risk-focused clauses")
             
-            # Step 4: Complete Risk Analysis (Main Orchestrator)
-            risk_score = self.services["risk_analyzer"].analyze_contract_risk(contract_text)
-            risk_dict = safe_serialize_response(risk_score.to_dict())
-            log_info(f"Risk analysis completed: {risk_score.overall_score}/100")
+            except Exception as e:
+                log_error(f"Risk-focused clause extraction failed: {repr(e)}")
+                # Fallback to comprehensive extraction
+                try:
+                    log_info("Attempting fallback to comprehensive clause extraction...")
+                    clauses = self.services["comprehensive_extractor"].extract_clauses(contract_text = contract_text,
+                                                                                       max_clauses   = options.max_clauses,
+                                                                                      )
+                    
+                    log_info(f"Fallback extracted {len(clauses)} comprehensive clauses")
+                
+                except Exception as fallback_error:
+                    log_error(f"Comprehensive clause extraction also failed: {repr(fallback_error)}")
+                    clauses = []
+
+            # Process clauses regardless of extraction method
+            if clauses:
+                clauses_dict      = [safe_serialize_response(clause.to_dict()) for clause in clauses]
+                # Debug logging for clause extraction
+                clause_categories = [clause.category for clause in clauses]
+                unique_categories = list(set(clause_categories))
+                
+                log_info(f"Clause categories extracted: {unique_categories}")
+                
+                # Log risk scores if available
+                risk_scores = [getattr(clause, 'risk_score', 0) for clause in clauses if hasattr(clause, 'risk_score')]
+                
+                if risk_scores:
+                    avg_risk = sum(risk_scores) / len(risk_scores)
+                    log_info(f"Average clause risk score: {avg_risk:.2f}")
+
+            # Analyze UNFAVORABLE TERMS (outputs risk categories)
+            unfavorable_terms      = list()
+            unfavorable_terms_dict = list()
             
-            # Extract components from risk analysis for further processing
-            unfavorable_terms = risk_score.unfavorable_terms
-            missing_protections = risk_score.missing_protections
+            try:
+                # Update term analyzer with correct contract type
+                if hasattr(self.services["term_analyzer"], 'contract_type'):
+                    self.services["term_analyzer"].contract_type    = contract_type_enum
+                    self.services["term_analyzer"].category_weights = self.services["term_analyzer"].risk_rules.get_adjusted_weights(contract_type_enum)
+                    
+                    log_info(f"Updated TermAnalyzer for contract type: {contract_type_enum.value}")
+                
+                unfavorable_terms      = self.services["term_analyzer"].analyze_unfavorable_terms(contract_text = contract_text,
+                                                                                                  clauses       = clauses,
+                                                                                                  contract_type = contract_type_enum,
+                                                                                                 )
+                
+                unfavorable_terms_dict = [safe_serialize_response(term.to_dict()) for term in unfavorable_terms]
+                
+                log_info(f"Analyzed {len(unfavorable_terms)} unfavorable terms")
+                
+                # Debug logging for term analysis
+                if unfavorable_terms:
+                    severity_counts = dict()
+                    for term in unfavorable_terms:
+                        severity_counts[term.severity] = severity_counts.get(term.severity, 0) + 1
+                    
+                    log_info(f"Term severity distribution: {severity_counts}")
+                    
+                    # Log top 10 highest risk terms
+                    top_terms = sorted(unfavorable_terms, key = lambda x: x.risk_score, reverse = True)[:10]
+                    for i, term in enumerate(top_terms):
+                        log_info(f"Top term {i+1}: {term.term} (Risk: {term.risk_score}, Severity: {term.severity})")
             
-            # Step 5: Generate LLM Interpretations (if enabled and available)
-            interpretations_dict = None
+            except Exception as e:
+                log_error(f"Unfavorable terms analysis failed: {repr(e)}")
+                
+                # Continue with empty terms but log the error
+                unfavorable_terms      = list()
+                unfavorable_terms_dict = list()
+
+            # Check for Missing Protections (outputs risk categories)
+            missing_protections      = list()
+            missing_protections_dict = list()
+            
+            try:
+                # Update protection checker with correct contract type
+                if hasattr(self.services["protection_checker"], 'contract_type'):
+                    self.services["protection_checker"].contract_type         = contract_type_enum
+                    self.services["protection_checker"].protection_priorities = self.services["protection_checker"]._get_contract_type_priorities()
+                    
+                    log_info(f"Updated ProtectionChecker for contract type: {contract_type_enum.value}")
+                
+                missing_protections      = self.services["protection_checker"].check_missing_protections(contract_text = contract_text,
+                                                                                                         clauses       = clauses,
+                                                                                                         contract_type = contract_type_enum,
+                                                                                                        )
+                missing_protections_dict = [safe_serialize_response(prot.to_dict()) for prot in missing_protections]
+                
+                log_info(f"Checked for {len(missing_protections)} missing protections")
+                
+                # Debug logging for protection analysis
+                if missing_protections:
+                    importance_counts = dict()
+                    for prot in missing_protections:
+                        importance_counts[prot.importance] = importance_counts.get(prot.importance, 0) + 1
+                    
+                    log_info(f"Missing protection importance: {importance_counts}")
+                    
+                    # Log top 10 highest risk missing protections
+                    top_protections = sorted(missing_protections, key = lambda x: x.risk_score, reverse = True)[:10]
+                    
+                    for i, prot in enumerate(top_protections):
+                        log_info(f"Top missing protection {i+1}: {prot.protection} (Risk: {prot.risk_score}, Importance: {prot.importance})")
+            
+            except Exception as e:
+                log_error(f"Missing protection analysis failed: {repr(e)}")
+                
+                # Continue with empty protections but log the error
+                missing_protections      = list()
+                missing_protections_dict = list()
+
+            # Perform Complete Risk Analysis
+            risk_score                        = self.services["risk_analyzer"].analyze_contract_risk(contract_text = contract_text)
+            risk_dict                         = safe_serialize_response(risk_score.to_dict())
+            log_info(f"Risk analysis completed: {risk_score.overall_score}/100")
+
+            # Generate LLM Interpretations (if available)
             risk_interpretation = None
             
-            if options.interpret_clauses and self.services["llm_interpreter"]:
+            if self.services["llm_interpreter"]:
                 try:
-                    risk_interpretation = self.services["llm_interpreter"].interpret_with_risk_context(
-                        clauses=clauses,
-                        unfavorable_terms=unfavorable_terms,
-                        missing_protections=missing_protections,
-                        contract_type=contract_type,
-                        overall_risk_score=risk_score.overall_score,
-                        max_clauses=min(10, options.max_clauses)
-                    )
-                    interpretations_dict = [
-                        safe_serialize_response(interp.to_dict()) 
-                        for interp in risk_interpretation.clause_interpretations
-                    ]
-                    log_info(f"Generated {len(interpretations_dict)} clause interpretations")
+                    risk_interpretation = self.services["llm_interpreter"].interpret_with_risk_context(clauses             = clauses,
+                                                                                                       unfavorable_terms   = unfavorable_terms,
+                                                                                                       missing_protections = missing_protections,
+                                                                                                       contract_type       = contract_type_enum,
+                                                                                                       overall_risk_score  = risk_score.overall_score,
+                                                                                                       max_clauses         = len(clauses), 
+                                                                                                       provider            = LLMProvider.OLLAMA,
+                                                                                                      )
+                    log_info("LLM risk interpretation generated")
+                
                 except Exception as e:
-                    log_error(f"LLM interpretation failed: {e}")
-                    interpretations_dict = []
+                    log_error(f"LLM interpretation failed: {repr(e)}")
+                    # Continue without LLM interpretation
             
-            # Step 6: Generate Negotiation Points (if enabled and available)
-            negotiation_dict     = []
+            else:
+                # If LLM is not available, create a basic interpretation object to pass downstream
+                risk_interpretation = RiskInterpretation(overall_risk_explanation = f"Contract risk score: {risk_score.overall_score}/100 ({risk_score.risk_level}).",
+                                                         key_concerns             = [f"Risk level: {risk_score.risk_level}"],
+                                                         negotiation_strategy     = "Address critical terms identified in analysis.",
+                                                         market_comparison        = "Compare with industry standards.",
+                                                         clause_interpretations   = [],
+                                                        )
+
+
+            # Generate Negotiation Playbook (uses full context)
             negotiation_playbook = None
+            negotiation_dict     = list()
 
-            if options.generate_negotiation_points and self.services["negotiation_engine"]:
+            if self.services["negotiation_engine"]:
                 try:
-                    negotiation_playbook = self.services["negotiation_engine"].generate_comprehensive_playbook(
-                        risk_analysis=risk_score,
-                        risk_interpretation=risk_interpretation or RiskInterpretation(
-                            overall_risk_explanation="",
-                            key_concerns=[],
-                            negotiation_strategy="",
-                            market_comparison="",
-                            clause_interpretations=[]
-                        ),
-                        unfavorable_terms=unfavorable_terms,
-                        missing_protections=missing_protections,
-                        clauses=clauses,
-                        contract_type=contract_type,
-                        max_points=8  # Match frontend limit
-                    )
+                    # Ensure we have proper objects, not dicts
+                    unfavorable_terms_objects   = unfavorable_terms  
+                    missing_protections_objects = missing_protections  
                     
-                    negotiation_dict = [
-                        safe_serialize_response(point.to_dict()) 
-                        for point in negotiation_playbook.critical_points
-                    ]
-                    log_info(f"Generated {len(negotiation_dict)} negotiation points")
+                    # Create a fallback risk interpretation if LLM failed (already handled above)
+                    negotiation_playbook        = self.services["negotiation_engine"].generate_comprehensive_playbook(risk_analysis       = risk_score,
+                                                                                                                      risk_interpretation = risk_interpretation,
+                                                                                                                      unfavorable_terms   = unfavorable_terms_objects,
+                                                                                                                      missing_protections = missing_protections_objects,
+                                                                                                                      clauses             = clauses, 
+                                                                                                                      contract_type       = contract_type_enum,
+                                                                                                                      max_points          = len(clauses),
+                                                                                                                     )
+
+                    negotiation_dict     = [safe_serialize_response(point.to_dict()) for point in negotiation_playbook.critical_points]
+
+                    log_info(f"Negotiation playbook generated with {len(negotiation_playbook.critical_points)} points")
 
                 except Exception as e:
-                    log_error(f"Negotiation engine failed: {e}")
-                    print(f"🔍 DEBUG: Negotiation engine exception: {e}")
-                    import traceback
-                    print(f"🔍 DEBUG: Full traceback: {traceback.format_exc()}")
-                    negotiation_dict = []
-            
-            # Step 7: Generate Executive Summary
-            executive_summary = self.services["summary_generator"].generate_comprehensive_summary(
-                contract_text=contract_text,
-                classification=classification,
-                risk_analysis=risk_score,
-                risk_interpretation=risk_interpretation or RiskInterpretation(
-                    overall_risk_explanation="",
-                    key_concerns=[],
-                    negotiation_strategy="",
-                    market_comparison="",
-                    clause_interpretations=[]
-                ),
-                negotiation_playbook=negotiation_playbook or NegotiationPlaybook(
-                    overall_strategy="",
-                    critical_points=[],
-                    walk_away_items=[],
-                    concession_items=[],
-                    timing_guidance="",
-                    risk_mitigation_plan=""
-                ),
-                unfavorable_terms=unfavorable_terms,
-                missing_protections=missing_protections,
-                clauses=clauses
-            )
+                    log_error(f"Negotiation playbook generation failed: {repr(e)}")
+                    
+                    # Create fallback negotiation points
+                    negotiation_dict = self._create_fallback_negotiation_points(risk_score, unfavorable_terms, missing_protections)
             
+            else:
+                # If negotiation engine is not available, create fallback points
+                negotiation_dict = self._create_fallback_negotiation_points(risk_score, unfavorable_terms, missing_protections)
+
+
+            # Generate Executive Summary (uses full context)
+            executive_summary = self.services["summary_generator"].generate_executive_summary(contract_text        = contract_text,
+                                                                                              classification       = classification,
+                                                                                              risk_analysis        = risk_score,
+                                                                                              risk_interpretation  = risk_interpretation,
+                                                                                              negotiation_playbook = negotiation_playbook,
+                                                                                              unfavorable_terms    = unfavorable_terms, 
+                                                                                              missing_protections  = missing_protections, 
+                                                                                              clauses              = clauses, 
+                                                                                             )
+            log_info("Executive summary generated")
+
             # Build final result matching frontend expectations
-            result = {
-                "analysis_id": str(uuid.uuid4()),
-                "timestamp": datetime.now().isoformat(),
-                "classification": classification_dict,
-                "clauses": clauses_dict,
-                "risk_analysis": risk_dict,  # Contains overall_score, risk_level, category_scores, risk_breakdown
-                "unfavorable_terms": [safe_serialize_response(term) for term in unfavorable_terms],
-                "missing_protections": [safe_serialize_response(prot) for prot in missing_protections],
-                "clause_interpretations": interpretations_dict,
-                "negotiation_points": negotiation_dict,
-                "market_comparisons": [],  # Disabled for now
-                "executive_summary": executive_summary,
-                "metadata": {
-                    "text_length": len(contract_text),
-                    "word_count": len(contract_text.split()),
-                    "num_clauses": len(clauses),
-                    "contract_type": contract_type.value,
-                    "actual_category": classification.category,
-                    "options": options.dict()
-                },
-                "pdf_available": True
-            }
-            
+            result                            = {"analysis_id"            : str(uuid.uuid4()),
+                                                 "timestamp"              : datetime.now().isoformat(),
+                                                 "classification"         : classification_dict,
+                                                 "clauses"                : clauses_dict,
+                                                 "risk_analysis"          : risk_dict, 
+                                                 "unfavorable_terms"      : unfavorable_terms_dict,
+                                                 "missing_protections"    : missing_protections_dict,
+                                                 "clause_interpretations" : [safe_serialize_response(interp.to_dict()) for interp in (risk_interpretation.clause_interpretations if risk_interpretation else [])],
+                                                 "negotiation_points"     : negotiation_dict,
+                                                 "market_comparisons"     : [],
+                                                 "executive_summary"      : executive_summary,
+                                                 "metadata"               : {"text_length"               : len(contract_text),
+                                                                             "word_count"                : len(contract_text.split()),
+                                                                             "num_clauses"               : len(clauses),
+                                                                             "contract_type"             : contract_type_enum.value,
+                                                                             "actual_category"           : classification.category,
+                                                                             "subcategory"               : classification.subcategory,
+                                                                             "classification_confidence" : classification.confidence,
+                                                                             "detected_keywords"         : classification.detected_keywords,
+                                                                             "options"                   : options.dict(),
+                                                                            },
+                                                 "pdf_available"          : True,
+                                                }
+
             log_info("Contract analysis completed successfully")
             return result
-            
+
         except Exception as e:
-            log_error(f"Contract analysis failed: {e}")
+            log_error(f"Contract analysis failed: {repr(e)}")
             raise
-    
+
+
+    def _score_to_risk_level(self, score: float) -> str:
+        """
+        Convert risk score to risk level string
+        """
+        if (score >= 80):
+            return "Critical"
+        
+        elif (score >= 60):
+            return "High"
+        
+        elif (score >= 40):
+            return "Medium"
+        
+        else:
+            return "Low"
+
+
     def _get_contract_type_enum(self, category_str: str) -> ContractType:
-        """Convert category string to ContractType enum"""
-        mapping = {
-            'employment': ContractType.EMPLOYMENT,
-            'consulting': ContractType.CONSULTING,
-            'nda': ContractType.NDA,
-            'software': ContractType.SOFTWARE,
-            'service': ContractType.SERVICE,
-            'partnership': ContractType.PARTNERSHIP,
-            'lease': ContractType.LEASE,
-            'purchase': ContractType.PURCHASE,
-            'general': ContractType.GENERAL,
-        }
-        return mapping.get(category_str, ContractType.GENERAL)
+        """
+        Convert category string to ContractType enum with fallback
+        """
+        mapping       = {'employment'  : ContractType.EMPLOYMENT,
+                         'consulting'  : ContractType.CONSULTING,
+                         'nda'         : ContractType.NDA,
+                         'software'    : ContractType.SOFTWARE,
+                         'service'     : ContractType.SERVICE,
+                         'partnership' : ContractType.PARTNERSHIP,
+                         'lease'       : ContractType.LEASE,
+                         'purchase'    : ContractType.PURCHASE,
+                         'general'     : ContractType.GENERAL,
+                        }
+
+        contract_type = mapping.get(category_str, ContractType.GENERAL)
+        
+        log_info(f"Mapping category '{category_str}' to ContractType: {contract_type.value}")
+        
+        return contract_type
 
-# ============================================================================
-# FASTAPI APPLICATION (UNCHANGED STRUCTURE, UPDATED IMPLEMENTATION)
-# ============================================================================
 
-# Global instances
-analysis_service: Optional[PreloadedAnalysisService] = None
-app_start_time = time.time()
+
+# FASTAPI APPLICATION : Global instances
+analysis_service : Optional[PreloadedAnalysisService] = None
+app_start_time                                        = time.time()
 
 # Initialize logger
-ContractAnalyzerLogger.setup(log_dir="logs", app_name="contract_analyzer")
+ContractAnalyzerLogger.setup(log_dir  = "logs", 
+                             app_name = "contract_analyzer",
+                            )
+
 logger = ContractAnalyzerLogger.get_logger()
 
+
 @asynccontextmanager
 async def lifespan(app: FastAPI):
     global analysis_service
-    
     log_info(f"🚀 {settings.APP_NAME} v{settings.APP_VERSION} STARTING UP...")
     log_info("=" * 80)
     
     try:
         analysis_service = PreloadedAnalysisService()
         log_info("✅ All services initialized successfully")
+
     except Exception as e:
         log_error(f"Startup failed: {e}")
         raise
-    
+
     log_info(f"📍 Server: {settings.HOST}:{settings.PORT}")
     log_info("=" * 80)
     log_info("✅ AI Contract Risk Analyzer Ready!")
-    
+
     try:
         yield
+
     finally:
         log_info("🛑 Shutting down server...")
         log_info("✅ Server shutdown complete")
 
-app = FastAPI(
-    title=settings.APP_NAME,
-    version=settings.APP_VERSION,
-    description="AI-powered contract risk analysis with complete model pre-loading",
-    docs_url="/api/docs",
-    redoc_url="/api/redoc",
-    default_response_class=NumpyJSONResponse,
-    lifespan=lifespan
-)
+# Define the application
+app        = FastAPI(title                 = settings.APP_NAME,
+                    version                = settings.APP_VERSION,
+                    description            = "AI-powered contract risk analysis",
+                    docs_url               = "/api/docs",
+                    redoc_url              = "/api/redoc",
+                    default_response_class = NumpyJSONResponse,
+                    lifespan               = lifespan,
+                   )
 
 # Get absolute paths
-BASE_DIR = Path(__file__).parent
+BASE_DIR   = Path(__file__).parent
 STATIC_DIR = BASE_DIR / "static"
 
 # Serve static files
-app.mount("/static", StaticFiles(directory=str(STATIC_DIR)), name="static")
+app.mount("/static", StaticFiles(directory = str(STATIC_DIR)), name = "static")
 
-# Enhanced CORS middleware
-app.add_middleware(
-    CORSMiddleware,
-    allow_origins=["*"],
-    allow_credentials=True,
-    allow_methods=["*"],
-    allow_headers=["*"],
-)
+# CORS middleware
+app.add_middleware(CORSMiddleware,
+                   allow_origins     = settings.CORS_ORIGINS,
+                   allow_credentials = settings.CORS_ALLOW_CREDENTIALS,
+                   allow_methods     = settings.CORS_ALLOW_METHODS,
+                   allow_headers     = settings.CORS_ALLOW_HEADERS,
+                  )
 
-# ============================================================================
-# HELPER FUNCTIONS (UNCHANGED)
-# ============================================================================
 
+# HELPER FUNCTIONS
 def validate_file(file: UploadFile) -> tuple[bool, str]:
-    file_ext = os.path.splitext(file.filename)[1].lower()
-    if file_ext not in settings.ALLOWED_EXTENSIONS:
+    file_extension = os.path.splitext(file.filename)[1].lower()
+    
+    if file_extension not in settings.ALLOWED_EXTENSIONS:
         return False, f"Invalid file type. Allowed: {', '.join(settings.ALLOWED_EXTENSIONS)}"
     
     file.file.seek(0, 2)
     size = file.file.tell()
+    
     file.file.seek(0)
     
-    if size > settings.MAX_UPLOAD_SIZE:
-        return False, f"File too large. Max size: {settings.MAX_UPLOAD_SIZE / (1024*1024)}MB"
+    if (size > settings.MAX_UPLOAD_SIZE):
+        return False, f"File too large. Max size: {settings.MAX_UPLOAD_SIZE / (1024*1024):.1f}MB"
     
-    if size == 0:
+    if (size == 0):
         return False, "File is empty"
     
     return True, "OK"
@@ -514,7 +821,6 @@ def read_contract_file(file) -> str:
     Read contract file and return text content.
     """
     reader         = DocumentReader()
-    
     # Extract file extension without dot
     filename       = file.filename.lower()
     file_extension = Path(filename).suffix.lower().lstrip('.')
@@ -525,299 +831,353 @@ def read_contract_file(file) -> str:
         print(f"📁 DEBUG app.py - No extension found, defaulting to: '{file_extension}'")
     
     file_contents = reader.read_file(file.file, file_extension)
-    
     if (not file_contents or not file_contents.strip()):
         raise ValueError("Could not extract text from file")
-        
+    
     return file_contents
 
 
-
 def validate_contract_text(text: str) -> tuple[bool, str]:
     if not text or not text.strip():
         return False, "Contract text is empty"
     
-    if len(text) < settings.MIN_CONTRACT_LENGTH:
+    if (len(text) < settings.MIN_CONTRACT_LENGTH):
         return False, f"Contract text too short. Minimum {settings.MIN_CONTRACT_LENGTH} characters required."
     
-    if len(text) > settings.MAX_CONTRACT_LENGTH:
+    if (len(text) > settings.MAX_CONTRACT_LENGTH):
         return False, f"Contract text too long. Maximum {settings.MAX_CONTRACT_LENGTH} characters allowed."
     
     return True, "OK"
 
-# ============================================================================
-# API ROUTES (UNCHANGED INTERFACE, UPDATED IMPLEMENTATION)
-# ============================================================================
 
+
+# API ROUTES
 @app.get("/")
 async def serve_frontend():
     return FileResponse(str(STATIC_DIR / "index.html"))
 
-@app.get("/api/v1/health", response_model=HealthResponse)
+
+@app.get("/api/v1/health", response_model = HealthResponse)
 async def health_check():
     if not analysis_service:
-        raise HTTPException(status_code=503, detail="Service not initialized")
-    
+        raise HTTPException(status_code = 503, 
+                            detail      = "Service not initialized",
+                           )
+
     service_status = analysis_service.get_service_status()
-    
-    return HealthResponse(
-        status="healthy",
-        version=settings.APP_VERSION,
-        timestamp=datetime.now().isoformat(),
-        models_loaded=service_status["total_models_loaded"],
-        services_loaded=service_status["total_services_loaded"],
-        memory_usage_mb=service_status["memory_usage_mb"]
-    )
+
+    return HealthResponse(status          = "healthy",
+                          version         = settings.APP_VERSION,
+                          timestamp       = datetime.now().isoformat(),
+                          models_loaded   = service_status["total_models_loaded"],
+                          services_loaded = service_status["total_services_loaded"],
+                          memory_usage_mb = service_status["memory_usage_mb"],
+                         )
+
 
 @app.get("/api/v1/status")
 async def get_detailed_status():
     if not analysis_service:
-        raise HTTPException(status_code=503, detail="Service not initialized")
+        raise HTTPException(status_code = 503, 
+                            detail      = "Service not initialized",
+                           )
+
     return analysis_service.get_service_status()
 
-@app.post("/api/v1/analyze/file", response_model=AnalysisResult)
-async def analyze_contract_file(
-    file: UploadFile = File(...),
-    max_clauses: int = Form(15),
-    interpret_clauses: bool = Form(True),
-    generate_negotiation_points: bool = Form(True),
-    compare_to_market: bool = Form(False)  # Disabled for now
-):
+
+@app.post("/api/v1/analyze/file", response_model = AnalysisResult)
+async def analyze_contract_file(file: UploadFile = File(...), max_clauses: int = Form(50), interpret_clauses: bool = Form(True),   
+                                generate_negotiation_points: bool = Form(True), compare_to_market: bool = Form(False)):
     if not analysis_service:
-        raise HTTPException(status_code=503, detail="Service not initialized")
-    
+        raise HTTPException(status_code = 503, 
+                            detail      = "Service not initialized",
+                           )
+
     try:
         # Validate file
         is_valid, message = validate_file(file)
+
         if not is_valid:
-            raise HTTPException(status_code=400, detail=message)
-        
+            raise HTTPException(status_code = 400, 
+                                detail      = message,
+                               )
+
         # Read contract text
-        contract_text = read_contract_file(file)
-        
+        contract_text               = read_contract_file(file)
+
         # Validate contract text
         is_valid_text, text_message = validate_contract_text(contract_text)
+
         if not is_valid_text:
-            raise HTTPException(status_code=400, detail=text_message)
-        
+            raise HTTPException(status_code = 400, 
+                                detail      = text_message,
+                               )
+
         # Validate contract structure using ContractValidator
-        validator = ContractValidator()
+        validator                                    = ContractValidator()
         is_valid_contract, contract_type, confidence = validator.is_valid_contract(contract_text)
-        
+
         if not is_valid_contract:
-            raise HTTPException(status_code=400, detail=f"Invalid contract: {confidence}")
-        
+            raise HTTPException(status_code = 400, 
+                                detail      = f"Invalid contract: {confidence}",
+                               )
+
         # Create analysis options
-        options = AnalysisOptions(
-            max_clauses=min(max_clauses, settings.MAX_CLAUSES_TO_ANALYZE),
-            interpret_clauses=interpret_clauses,
-            generate_negotiation_points=generate_negotiation_points,
-            compare_to_market=compare_to_market
-        )
-        
+        options                                      = AnalysisOptions(max_clauses                 = max_clauses,
+                                                                       interpret_clauses           = interpret_clauses,
+                                                                       generate_negotiation_points = generate_negotiation_points,
+                                                                       compare_to_market           = compare_to_market,
+                                                                      )
         # Perform analysis
-        result = analysis_service.analyze_contract(contract_text, options)
-        
+        result                                       = analysis_service.analyze_contract(contract_text, options)
+
         log_info(f"File analysis completed", 
-                filename=file.filename,
-                analysis_id=result["analysis_id"],
-                risk_score=result["risk_analysis"]["overall_score"])
-        
+                 filename    = file.filename,
+                 analysis_id = result["analysis_id"],
+                 risk_score  = result["risk_analysis"]["overall_score"],
+                )
+
         return AnalysisResult(**result)
-        
+
     except HTTPException:
         raise
+
     except Exception as e:
-        log_error(f"File analysis failed: {e}")
-        raise HTTPException(status_code=500, detail=f"Analysis failed: {str(e)}")
-
-@app.post("/api/v1/analyze/text", response_model=AnalysisResult)
-async def analyze_contract_text(
-    contract_text: str = Form(..., description="Contract text to analyze"),
-    max_clauses: int = Form(15),
-    interpret_clauses: bool = Form(True),
-    generate_negotiation_points: bool = Form(True),
-    compare_to_market: bool = Form(False)  # Disabled for now
-):
+        log_error(f"File analysis failed: {repr(e)}")
+
+        raise HTTPException(status_code = 500, 
+                            detail      = f"Analysis failed: {repr(e)}",
+                           )
+
+
+@app.post("/api/v1/analyze/text", response_model = AnalysisResult)
+async def analyze_contract_text(contract_text: str = Form(..., description="Contract text to analyze"), max_clauses: int = Form(15), interpret_clauses: bool = Form(True),
+                                generate_negotiation_points: bool = Form(True), compare_to_market: bool = Form(False)):
     if not analysis_service:
-        raise HTTPException(status_code=503, detail="Service not initialized")
-    
+        raise HTTPException(status_code = 503, 
+                            detail      = "Service not initialized",
+                           )
     try:
         # Validate contract text length first
         is_valid, message = validate_contract_text(contract_text)
-        if not is_valid:
-            raise HTTPException(status_code=400, detail=message)
         
+        if not is_valid:
+            raise HTTPException(status_code = 400, 
+                                detail      = message,
+                               )
+
         # Validate contract structure using ContractValidator
-        validator = ContractValidator()
+        validator                                   = ContractValidator()
         is_valid_contract, validation_type, message = validator.is_valid_contract(contract_text)
         
         if not is_valid_contract:
             error_message = message if "does not appear to be a legal contract" in message else "The provided document does not appear to be a legal contract. Please upload a valid contract for analysis."
-            raise HTTPException(status_code=400, detail=error_message)
-                
+            raise HTTPException(status_code = 400, 
+                                detail      = error_message,
+                               )
+
         # Create analysis options
-        options = AnalysisOptions(
-            max_clauses=min(max_clauses, settings.MAX_CLAUSES_TO_ANALYZE),
-            interpret_clauses=interpret_clauses,
-            generate_negotiation_points=generate_negotiation_points,
-            compare_to_market=compare_to_market
-        )
-        
+        options = AnalysisOptions(max_clauses                 = max_clauses,
+                                  interpret_clauses           = interpret_clauses,
+                                  generate_negotiation_points = generate_negotiation_points,
+                                  compare_to_market           = compare_to_market,
+                                 )
         # Perform analysis
-        result = analysis_service.analyze_contract(contract_text, options)
-        
+        result  = analysis_service.analyze_contract(contract_text, options)
+
         log_info(f"Text analysis completed", 
-                analysis_id=result["analysis_id"],
-                risk_score=result["risk_analysis"]["overall_score"])
+                 analysis_id = result["analysis_id"],
+                 risk_score  = result["risk_analysis"]["overall_score"],
+                )
         
         return AnalysisResult(**result)
-        
+    
     except HTTPException:
         raise
+    
     except Exception as e:
-        log_error(f"Text analysis failed: {e}")
-        raise HTTPException(status_code=500, detail=f"Analysis failed: {str(e)}")
+        log_error(f"Text analysis failed: {repr(e)}")
+        
+        raise HTTPException(status_code = 500, 
+                            detail      = f"Analysis failed: {repr(e)}",
+                           )
+
 
 @app.post("/api/v1/generate-pdf")
 async def generate_pdf_from_analysis(analysis_result: Dict[str, Any]):
     try:
-        pdf_buffer = generate_pdf_report(analysis_result)
-        
+        import json
+        with open("analysis_result.json", "w") as fp:
+            json.dump(analysis_result , fp)
+
+        # Pass the full analysis_result dictionary to the PDF generator
+        pdf_buffer  = generate_pdf_report(analysis_result = analysis_result) 
         analysis_id = analysis_result.get('analysis_id', 'report')
-        return Response(
-            content=pdf_buffer.getvalue(),
-            media_type="application/pdf",
-            headers={
-                "Content-Disposition": f"attachment; filename=contract_analysis_{analysis_id}.pdf"
-            }
-        )
+        
+        return Response(content    = pdf_buffer.getvalue(),
+                        media_type = "application/pdf",
+                        headers    = {"Content-Disposition": f"attachment; filename=contract_analysis_{analysis_id}.pdf"}
+                       )
+
     except Exception as e:
-        log_error(f"PDF generation failed: {e}")
-        raise HTTPException(status_code=500, detail=f"Failed to generate PDF: {str(e)}")
+        log_error(f"PDF generation failed: {repr(e)}")
+        
+        raise HTTPException(status_code = 500, 
+                            detail      = f"Failed to generate PDF: {repr(e)}",
+                           )
+
 
 @app.get("/api/v1/categories")
 async def get_contract_categories():
     if not analysis_service:
-        raise HTTPException(status_code=503, detail="Service not initialized")
+        raise HTTPException(status_code = 503, 
+                            detail      = "Service not initialized",
+                           )
     
     try:
-        categories = analysis_service.services["classifier"].get_all_categories()
-        return {"categories": categories}
+        # Get categories from classifier
+        categories       = analysis_service.services["classifier"].get_all_categories()
+        
+        # Get descriptions for each category
+        category_details = list()
+        
+        for category in categories:
+            description   = analysis_service.services["classifier"].get_category_description(category)
+            subcategories = analysis_service.services["classifier"].get_subcategories(category)
+            category_details.append({"name"          : category,
+                                     "description"   : description,
+                                     "subcategories" : subcategories,
+                                   })
+        
+        return {"categories": category_details}
+    
     except Exception as e:
-        log_error(f"Categories fetch failed: {e}")
-        raise HTTPException(status_code=500, detail=f"Failed to get categories: {str(e)}")
+        log_error(f"Categories fetch failed: {repr(e)}")
+        raise HTTPException(status_code = 500, 
+                            detail      = f"Failed to get categories: {repr(e)}")
+
 
-@app.post("/api/v1/validate/file", response_model=FileValidationResponse)
-async def validate_contract_file(file: UploadFile = File(...)):
+@app.post("/api/v1/validate/file", response_model = FileValidationResponse)
+async def validate_contract_file_endpoint(file: UploadFile = File(...)):
     try:
         is_valid, message = validate_file(file)
         if not is_valid:
-            return FileValidationResponse(valid=False, message=message)
-        
+            return FileValidationResponse(valid   = False,
+                                          message = message,
+                                         )
+
         contract_text = read_contract_file(file)
-        
+
         # Validate text length
         is_valid_text, text_message = validate_contract_text(contract_text)
-        if not is_valid_text:
-            return FileValidationResponse(valid=False, message=text_message)
         
+        if not is_valid_text:
+            return FileValidationResponse(valid   = False, 
+                                          message = text_message,
+                                         )
+
         # Validate contract structure using ContractValidator
         validator = ContractValidator()
-        report = validator.get_validation_report(contract_text)
-        
-        return FileValidationResponse(
-            valid=report["scores"]["total"] > 50 and is_valid_text,
-            message="Contract appears valid" if report["scores"]["total"] > 50 else "May not be a valid contract",
-            confidence=report["scores"]["total"],
-            report=report
-        )
+        report    = validator.get_validation_report(contract_text)
         
+        return FileValidationResponse(valid      = (report["scores"]["total"] > 50) and is_valid_text,
+                                      message    = "Contract appears valid" if (report["scores"]["total"] > 50) else "May not be a valid contract",
+                                      confidence = report["scores"]["total"],
+                                      report     = report,
+                                     )
+    
     except Exception as e:
         log_error(f"File validation failed: {e}")
-        raise HTTPException(status_code=400, detail=f"Validation failed: {str(e)}")
+        
+        raise HTTPException(status_code = 400, 
+                            detail      = f"Validation failed: {repr(e)}",
+                           )
 
-@app.post("/api/v1/validate/text", response_model=FileValidationResponse)
+
+@app.post("/api/v1/validate/text", response_model = FileValidationResponse)
 async def validate_contract_text_endpoint(contract_text: str = Form(...)):
     try:
         # Validate text length
         is_valid, message = validate_contract_text(contract_text)
-        if not is_valid:
-            return FileValidationResponse(valid=False, message=message)
         
+        if not is_valid:
+            return FileValidationResponse(valid   = False, 
+                                          message = message,
+                                         )
+
         # Validate contract structure using ContractValidator
         validator = ContractValidator()
-        report = validator.get_validation_report(contract_text)
-        
-        return FileValidationResponse(
-            valid=report["scores"]["total"] > 50 and is_valid,
-            message="Contract appears valid" if report["scores"]["total"] > 50 else "May not be a valid contract",
-            confidence=report["scores"]["total"],
-            report=report
-        )
+        report    = validator.get_validation_report(contract_text)
         
+        return FileValidationResponse(valid      = (report["scores"]["total"] > 50) and is_valid,
+                                      message    = "Contract appears valid" if (report["scores"]["total"] > 50) else "May not be a valid contract",
+                                      confidence = report["scores"]["total"],
+                                      report     = report,
+                                     )
+    
     except Exception as e:
-        log_error(f"Text validation failed: {e}")
-        raise HTTPException(status_code=400, detail=f"Validation failed: {str(e)}")
+        log_error(f"Text validation failed: {repr(e)}")
+        raise HTTPException(status_code = 400, 
+                            detail      = f"Validation failed: {repr(e)}",
+                           )
 
-# ============================================================================
-# ERROR HANDLERS AND MIDDLEWARE (UNCHANGED)
-# ============================================================================
 
+# ERROR HANDLERS AND MIDDLEWARE
 @app.exception_handler(HTTPException)
 async def http_exception_handler(request, exc):
-    return NumpyJSONResponse(
-        status_code=exc.status_code,
-        content=ErrorResponse(
-            error=exc.detail,
-            detail=str(exc.detail),
-            timestamp=datetime.now().isoformat()
-        ).dict()
-    )
+    return NumpyJSONResponse(status_code = exc.status_code,
+                             content     = ErrorResponse(error     = exc.detail,
+                                                         detail    = str(exc.detail),
+                                                         timestamp = datetime.now().isoformat(),
+                                                        ).dict()
+                            )
+
 
 @app.exception_handler(Exception)
 async def general_exception_handler(request, exc):
     log_error(f"Unhandled exception: {exc}")
-    return NumpyJSONResponse(
-        status_code=500,
-        content=ErrorResponse(
-            error="Internal server error",
-            detail=str(exc),
-            timestamp=datetime.now().isoformat()
-        ).dict()
-    )
+    
+    return NumpyJSONResponse(status_code = 500,
+                             content     = ErrorResponse(error     = "Internal server error",
+                                                         detail    = str(exc),
+                                                         timestamp = datetime.now().isoformat(),
+                                                        ).dict()
+                            )
+
 
 @app.middleware("http")
 async def log_requests(request: Request, call_next):
-    start_time = time.time()
-    response = await call_next(request)
+    start_time   = time.time()
+    response     = await call_next(request)
     process_time = time.time() - start_time
     
     log_info(f"API Request: {request.method} {request.url.path} - Status: {response.status_code} - Duration: {process_time:.3f}s")
     
     return response
 
-# ============================================================================
-# MAIN (UNCHANGED)
-# ============================================================================
+
+
+# MAIN 
 if __name__ == "__main__":
     def signal_handler(sig, frame):
         print("\n👋 Received Ctrl+C, shutting down gracefully...")
         sys.exit(0)
-    
+
     signal.signal(signal.SIGINT, signal_handler)
-    
+
     try:
-        uvicorn.run(
-            "app:app",
-            host=settings.HOST,
-            port=settings.PORT,
-            reload=settings.RELOAD,
-            workers=1,
-            log_level=settings.LOG_LEVEL.lower()
-        )
+        uvicorn.run("app:app",
+                    host      = settings.HOST,
+                    port      = settings.PORT,
+                    reload    = settings.RELOAD,
+                    workers   = settings.WORKERS,
+                    log_level = settings.LOG_LEVEL.lower(),
+                   )
+
     except KeyboardInterrupt:
         print("\n🎯 Server stopped by user")
+
     except Exception as e:
         log_error(f"Server error: {e}")
-        sys.exit(1)
+
+        sys.exit(1)

config/risk_rules.py

@@ -170,64 +170,75 @@ class RiskRules:
                                  "low"      : 20,
                                 }
                             
-    CATEGORY_DESCRIPTIONS = {"restrictive_covenants"  : {"high"   : "Overly restrictive non-compete, non-solicit, or confidentiality terms that may significantly limit future opportunities",
-                                                         "medium" : "Some restrictive terms present; review duration, geographic scope, and industry limitations",
-                                                         "low"    : "Reasonable restrictive covenants appropriate for this role and industry standards",
-                                                        },
-                             "termination_rights"     : {"high"   : "Unbalanced termination rights with immediate termination, 'at-will' clauses, or unequal notice periods favoring one party",
-                                                         "medium" : "Moderately balanced termination provisions; review notice period requirements and severance terms",
-                                                         "low"    : "Fair termination rights with reasonable notice periods and balanced severance provisions",
-                                                        },
-                             "penalties_liability"    : {"high"   : "Excessive penalty clauses, unlimited liability exposure, or one-sided indemnification terms",
-                                                         "medium" : "Some concerning liability terms; review indemnification scope, damage limitations, and warranty provisions",
-                                                         "low"    : "Standard liability limitations, reasonable penalty provisions, and balanced indemnification terms",
-                                                        },
-                             "compensation_benefits"  : {"high"   : "Compensation structure lacks clarity, contains vague terms, or has unfavorable payment conditions",
-                                                         "medium" : "Compensation terms are generally clear but could benefit from more specific bonus structure and payment terms",
-                                                         "low"    : "Clear and competitive compensation package with well-defined payment terms and bonus structure",
-                                                        },
-                             "intellectual_property"  : {"high"   : "Overly broad IP assignment that may cover personal projects or lacks proper prior IP exclusion",
-                                                         "medium" : "IP terms mostly clear but could benefit from stronger prior IP protection and clearer ownership terms",
-                                                         "low"    : "Well-defined intellectual property ownership, clear usage rights, and proper prior IP exclusion",
-                                                        },
-                             "confidentiality"        : {"high"   : "Overly broad confidentiality scope, perpetual duration, or insufficient protection exceptions",
-                                                         "medium" : "Standard confidentiality terms with some areas that could be more precisely defined",
-                                                         "low"    : "Reasonable confidentiality provisions with appropriate scope and duration",
-                                                        },
-                             "liability_indemnity"    : {"high"   : "Unbalanced indemnification, unlimited liability exposure, or insufficient liability caps",
-                                                         "medium" : "Moderate liability terms; review indemnification mutuality and liability limitations",
-                                                         "low"    : "Balanced indemnification provisions with reasonable liability limitations",
-                                                        },
-                             "governing_law"          : {"high"   : "Unfavorable jurisdiction selection, one-sided dispute resolution, or restrictive venue requirements",
-                                                         "medium" : "Standard governing law terms with generally acceptable jurisdiction and dispute resolution",
-                                                         "low"    : "Reasonable governing law and jurisdiction provisions favorable to both parties",
-                                                        },
-                             "payment_terms"          : {"high"   : "Unfavorable payment terms, extended payment periods, or unclear payment conditions",
-                                                         "medium" : "Standard payment terms with some areas that could be improved for cash flow",
-                                                         "low"    : "Favorable payment terms with reasonable payment periods and clear conditions",
-                                                        },
-                             "warranties"             : {"high"   : "Overly broad warranty disclaimers, insufficient product guarantees, or one-sided warranty terms",
-                                                         "medium" : "Standard warranty provisions with typical product/service guarantees",
-                                                         "low"    : "Comprehensive warranty coverage with reasonable limitations and clear guarantees",
-                                                        },
-                             "dispute_resolution"     : {"high"   : "Unfavorable dispute resolution process, restrictive arbitration clauses, or one-sided legal fee allocation",
-                                                         "medium" : "Standard dispute resolution terms with generally fair arbitration or litigation process",
-                                                         "low"    : "Reasonable dispute resolution process with fair arbitration and cost allocation",
-                                                        },
-                             "assignment_change"      : {"high"   : "Restrictive assignment clauses, one-sided change control, or unfavorable amendment procedures",
-                                                         "medium" : "Standard assignment and change control terms with reasonable flexibility",
-                                                         "low"    : "Reasonable assignment rights and change control processes favorable to both parties",
-                                                        },
-                             "insurance"              : {"high"   : "Insufficient insurance requirements, unclear coverage terms, or inadequate policy specifications",
-                                                         "medium" : "Standard insurance requirements with typical coverage expectations",
-                                                         "low"    : "Comprehensive insurance requirements with clear coverage specifications",
-                                                        },
-                             "force_majeure"          : {"high"   : "Overly narrow force majeure definition, insufficient relief provisions, or one-sided termination rights",
-                                                         "medium" : "Standard force majeure clause with typical relief provisions",
-                                                         "low"    : "Comprehensive force majeure protection with reasonable relief and termination rights",
-                                                        },
-                            }
-    
+    CATEGORY_DESCRIPTIONS     = {"restrictive_covenants"  : {"high"   : "Overly restrictive non-compete, non-solicit, or confidentiality terms that may significantly limit future opportunities",
+                                                             "medium" : "Some restrictive terms present; review duration, geographic scope, and industry limitations",
+                                                             "low"    : "Reasonable restrictive covenants appropriate for this role and industry standards",
+                                                            },
+                                 "termination_rights"     : {"high"   : "Unbalanced termination rights with immediate termination, 'at-will' clauses, or unequal notice periods favoring one party",
+                                                             "medium" : "Moderately balanced termination provisions; review notice period requirements and severance terms",
+                                                             "low"    : "Fair termination rights with reasonable notice periods and balanced severance provisions",
+                                                            },
+                                 "penalties_liability"    : {"high"   : "Excessive penalty clauses, unlimited liability exposure, or one-sided indemnification terms",
+                                                             "medium" : "Some concerning liability terms; review indemnification scope, damage limitations, and warranty provisions",
+                                                             "low"    : "Standard liability limitations, reasonable penalty provisions, and balanced indemnification terms",
+                                                            },
+                                 "compensation_benefits"  : {"high"   : "Compensation structure lacks clarity, contains vague terms, or has unfavorable payment conditions",
+                                                             "medium" : "Compensation terms are generally clear but could benefit from more specific bonus structure and payment terms",
+                                                             "low"    : "Clear and competitive compensation package with well-defined payment terms and bonus structure",
+                                                            },
+                                 "intellectual_property"  : {"high"   : "Overly broad IP assignment that may cover personal projects or lacks proper prior IP exclusion",
+                                                             "medium" : "IP terms mostly clear but could benefit from stronger prior IP protection and clearer ownership terms",
+                                                             "low"    : "Well-defined intellectual property ownership, clear usage rights, and proper prior IP exclusion",
+                                                            },
+                                 "confidentiality"        : {"high"   : "Overly broad confidentiality scope, perpetual duration, or insufficient protection exceptions",
+                                                             "medium" : "Standard confidentiality terms with some areas that could be more precisely defined",
+                                                             "low"    : "Reasonable confidentiality provisions with appropriate scope and duration",
+                                                            },
+                                 "liability_indemnity"    : {"high"   : "Unbalanced indemnification, unlimited liability exposure, or insufficient liability caps",
+                                                             "medium" : "Moderate liability terms; review indemnification mutuality and liability limitations",
+                                                             "low"    : "Balanced indemnification provisions with reasonable liability limitations",
+                                                            },
+                                 "governing_law"          : {"high"   : "Unfavorable jurisdiction selection, one-sided dispute resolution, or restrictive venue requirements",
+                                                             "medium" : "Standard governing law terms with generally acceptable jurisdiction and dispute resolution",
+                                                             "low"    : "Reasonable governing law and jurisdiction provisions favorable to both parties",
+                                                            },
+                                 "payment_terms"          : {"high"   : "Unfavorable payment terms, extended payment periods, or unclear payment conditions",
+                                                             "medium" : "Standard payment terms with some areas that could be improved for cash flow",
+                                                             "low"    : "Favorable payment terms with reasonable payment periods and clear conditions",
+                                                            },
+                                 "warranties"             : {"high"   : "Overly broad warranty disclaimers, insufficient product guarantees, or one-sided warranty terms",
+                                                             "medium" : "Standard warranty provisions with typical product/service guarantees",
+                                                             "low"    : "Comprehensive warranty coverage with reasonable limitations and clear guarantees",
+                                                            },
+                                 "dispute_resolution"     : {"high"   : "Unfavorable dispute resolution process, restrictive arbitration clauses, or one-sided legal fee allocation",
+                                                             "medium" : "Standard dispute resolution terms with generally fair arbitration or litigation process",
+                                                             "low"    : "Reasonable dispute resolution process with fair arbitration and cost allocation",
+                                                            },
+                                 "assignment_change"      : {"high"   : "Restrictive assignment clauses, one-sided change control, or unfavorable amendment procedures",
+                                                             "medium" : "Standard assignment and change control terms with reasonable flexibility",
+                                                             "low"    : "Reasonable assignment rights and change control processes favorable to both parties",
+                                                            },
+                                 "insurance"              : {"high"   : "Insufficient insurance requirements, unclear coverage terms, or inadequate policy specifications",
+                                                             "medium" : "Standard insurance requirements with typical coverage expectations",
+                                                             "low"    : "Comprehensive insurance requirements with clear coverage specifications",
+                                                            },
+                                 "force_majeure"          : {"high"   : "Overly narrow force majeure definition, insufficient relief provisions, or one-sided termination rights",
+                                                             "medium" : "Standard force majeure clause with typical relief provisions",
+                                                             "low"    : "Comprehensive force majeure protection with reasonable relief and termination rights",
+                                                            },
+                                }
+        
+    PROTECTION_NAME_MAP       = {"for_cause_definition"     : "For Cause Definition",
+                                 "severance_proportion"     : "Severance Provision",
+                                 "mutual_indemnification"   : "Mutual Indemnification",
+                                 "liability_cap"            : "Liability Cap",
+                                 "prior_ip_exclusion"       : "Prior IP Exclusion",
+                                 "confidentiality_duration" : "Confidentiality Duration Limit",
+                                 "dispute_resolution"       : "Dispute Resolution Process",
+                                 "change_control_process"   : "Change Control Process",
+                                 "insurance_requirements"   : "Insurance Requirements",
+                                 "force_majeure"            : "Force Majeure Protection",
+                                }
 
     @classmethod
     def get_adjusted_weights(cls, contract_type: ContractType) -> Dict[str, float]:
@@ -270,4 +281,12 @@ class RiskRules:
         
         category_description = cls.CATEGORY_DESCRIPTIONS[category][risk_level]
         
-        return category_description
+        return category_description
+
+
+    @classmethod
+    def get_protection_display_name(cls, protection_id: str) -> str:
+        """
+        Get the display name for a protection ID: Uses PROTECTION_NAME_MAP for known IDs, otherwise formats the ID
+        """
+        return cls.PROTECTION_NAME_MAP.get(protection_id, protection_id.replace("_", " ").title())

config/settings.py

@@ -28,7 +28,7 @@ class Settings(BaseSettings):
     
     # File Upload Settings
     MAX_UPLOAD_SIZE        : int           = 10 * 1024 * 1024  # 10 MB
-    ALLOWED_EXTENSIONS     : list          = ["pdf", "docx", "txt"]
+    ALLOWED_EXTENSIONS     : list          = [".pdf", ".docx", ".txt"]
     UPLOAD_DIR             : Path          = Path("uploads")
     
     # Model Management Settings

docs/API_DOCUMENTATION.md

@@ -0,0 +1,555 @@
+# AI Contract Risk Analyzer API Documentation
+
+This document details the REST API endpoints for the AI Contract Risk Analyzer service.
+
+**Base URL:** `http://<your-host>:<your-port>/api/v1` (e.g., `http://localhost:8000/api/v1`)
+
+## Table of Contents
+
+*   [Health Check](#health-check)
+*   [Get Service Status](#get-service-status)
+*   [Get Contract Categories](#get-contract-categories)
+*   [Analyze Contract from File](#analyze-contract-from-file)
+*   [Analyze Contract from Text](#analyze-contract-from-text)
+*   [Generate PDF Report](#generate-pdf-report)
+*   [Validate Contract File](#validate-contract-file)
+*   [Validate Contract Text](#validate-contract-text)
+
+---
+
+## Health Check
+
+Checks the basic health and availability of the API service.
+
+### Endpoint
+
+`GET /api/v1/health`
+
+### Request
+
+No body required.
+
+### Response
+
+**Status Code:** `200 OK`
+
+**Content-Type:** `application/json`
+
+```json
+{
+  "status": "healthy",
+  "version": "1.0.0",
+  "timestamp": "2025-11-17T15:00:00.123456",
+  "models_loaded": 5,
+  "services_loaded": 6,
+  "memory_usage_mb": 2048.5
+}
+```
+
+---
+
+## Get Service Status
+
+Retrieves detailed status information about the loaded models and services.
+
+### Endpoint
+
+`GET /api/v1/status`
+
+### Request
+
+No body required.
+
+### Response
+
+**Status Code:** `200 OK`
+
+**Content-Type:** `application/json`
+
+```json
+{
+  "services": {
+    "classifier": "loaded",
+    "clause_extractor": "loaded",
+    "risk_analyzer": "loaded",
+    "llm_interpreter": "loaded",
+    "negotiation_engine": "loaded",
+    "summary_generator": "loaded",
+    "term_analyzer": "loaded",
+    "protection_checker": "loaded"
+  },
+  "models": {
+    "legal-bert": {
+      "name": "legal-bert",
+      "type": "LEGAL_BERT",
+      "status": "LOADED",
+      "loaded_at": "2025-11-17T14:55:00.123456",
+      "memory_size_mb": 400.0,
+      "access_count": 10,
+      "last_accessed": "2025-11-17T15:00:00.123456"
+    },
+    "embedding": {
+      "name": "embedding",
+      "type": "EMBEDDING",
+      "status": "LOADED",
+      "loaded_at": "2025-11-17T14:55:00.123456",
+      "memory_size_mb": 100.0,
+      "access_count": 8,
+      "last_accessed": "2025-11-17T14:59:59.123456"
+    }
+  },
+  "memory_usage_mb": 2048.5,
+  "total_services_loaded": 8,
+  "total_models_loaded": 5
+}
+```
+
+---
+
+## Get Contract Categories
+
+Retrieves a list of contract categories that the classifier can identify.
+
+### Endpoint
+
+`GET /api/v1/categories`
+
+### Request
+
+No body required.
+
+### Response
+
+**Status Code:** `200 OK`
+
+**Content-Type:** `application/json`
+
+```json
+{
+  "categories": [
+    "employment",
+    "consulting",
+    "nda",
+    "software",
+    "service",
+    "partnership",
+    "lease",
+    "purchase",
+    "general"
+  ]
+}
+```
+
+---
+
+## Analyze Contract from File
+
+Uploads a contract file (PDF, DOCX, TXT) for analysis.
+
+### Endpoint
+
+`POST /api/v1/analyze/file`
+
+### Request
+
+**Content-Type:** `multipart/form-data`
+
+**Form Data:**
+
+- `file`: **(Required)** The contract file to analyze (PDF, DOCX, TXT).
+- `max_clauses`: **(Optional, Integer)** Maximum number of clauses to analyze (default: `50`, min: `5`, max: `30`).
+- `interpret_clauses`: **(Optional, Boolean)** Whether to generate LLM interpretations for clauses (default: `true`).
+- `generate_negotiation_points`: **(Optional, Boolean)** Whether to generate negotiation points (default: `true`).
+- `compare_to_market`: **(Optional, Boolean)** Whether to perform market comparison (default: `false`, currently disabled).
+
+### Response
+
+**Status Code:** `200 OK`
+
+**Content-Type:** `application/json`
+
+```json
+{
+  "analysis_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
+  "timestamp": "2025-11-17T15:01:00.123456",
+  "classification": {
+    "category": "employment",
+    "subcategory": "executive",
+    "confidence": 0.95,
+    "reasoning": ["Keywords like 'executive', 'compensation', 'non-compete' found"],
+    "detected_keywords": ["employment", "executive", "non-compete", "compensation"]
+  },
+  "clauses": [
+    {
+      "text": "Employee agrees to a 24-month non-compete...",
+      "reference": "Clause 9.5",
+      "category": "restrictive_covenants",
+      "confidence": 0.98,
+      "start_pos": 1200,
+      "end_pos": 1350,
+      "extraction_method": "semantic",
+      "risk_indicators": ["non-compete", "24 months", "entire industry"],
+      "risk_score": 90
+    }
+  ],
+  "risk_analysis": {
+    "overall_score": 85,
+    "risk_level": "CRITICAL",
+    "category_scores": {
+      "restrictive_covenants": 95,
+      "penalties_liability": 90,
+      "compensation_benefits": 80
+    },
+    "risk_factors": ["Restrictive Covenants", "Penalties & Liability"],
+    "detailed_findings": {
+      "restrictive_covenants": [
+        "Non-compete clause (Clause 9.5) is overly broad and long.",
+        "Non-solicitation clause (Clause 17.6) has excessive duration."
+      ]
+    },
+    "benchmark_comparison": {
+      "overall": "✗ Significantly above market risk levels",
+      "high_risk_areas": ["Restrictive Covenants", "Penalties & Liability"]
+    },
+    "risk_breakdown": [
+      {
+        "category": "Restrictive Covenants",
+        "score": 95,
+        "summary": "The agreement contains exceptionally broad and long-lasting non-compete...",
+        "findings": ["Non-compete clause (Clause 9.5) is overly broad and long."]
+      }
+    ],
+    "contract_type": "employment",
+    "unfavorable_terms": [],
+    "missing_protections": []
+  },
+  "unfavorable_terms": [
+    {
+      "term": "Risk Factor: entire industry",
+      "category": "restrictive_covenants",
+      "severity": "critical",
+      "explanation": "Non-compete restricts the Employee from applying to any company in the same 'Industry'...",
+      "risk_score": 90,
+      "clause_reference": "Clause 9.5",
+      "suggested_fix": "Negotiate to have this clause removed entirely...",
+      "contract_type": "EMPLOYMENT",
+      "specific_text": "entire industry",
+      "benchmark_info": null,
+      "legal_basis": "Reasonableness standard for restrictive covenants"
+    }
+  ],
+  "missing_protections": [
+    {
+      "protection": "For Cause Definition",
+      "importance": "critical",
+      "risk_score": 25,
+      "explanation": "Without a clear 'for cause' definition, termination grounds remain ambiguous...",
+      "recommendation": "Add clear 'For Cause' definition including...",
+      "categories": ["termination_rights"],
+      "contract_type": "EMPLOYMENT",
+      "suggested_language": "\"For Cause\" means: (a) gross negligence...",
+      "legal_basis": "Employment protection statutes...",
+      "affected_clauses": ["Clause 17.1"]
+    }
+  ],
+  "clause_interpretations": [
+    {
+      "clause_reference": "Clause 9.5",
+      "original_text": "Employee agrees to a 24-month non-compete...",
+      "plain_english_summary": "You cannot work for or apply to any company in the same industry for 24 months after leaving.",
+      "key_points": [
+        "Duration: 24 months",
+        "Scope: Entire industry",
+        "Applies to: Applying for jobs too"
+      ],
+      "potential_risks": [
+        "Severely limits future job opportunities.",
+        "Scope is likely unenforceable."
+      ],
+      "favorability": "unfavorable",
+      "confidence": 0.85,
+      "risk_score": 90,
+      "negotiation_priority": "high",
+      "suggested_improvements": [
+        "Reduce duration to 6-12 months.",
+        "Narrow scope to direct competitors only."
+      ]
+    }
+  ],
+  "negotiation_points": [
+    {
+      "priority": 1,
+      "category": "restrictive_covenants",
+      "issue": "Extremely broad non-compete clause",
+      "current_language": "Employee agrees to a 24-month non-compete...",
+      "proposed_language": "Limit non-compete to 6 months and direct competitors only.",
+      "rationale": "The current clause is overly broad and likely unenforceable.",
+      "tactic": "limitation",
+      "fallback_position": "If 6 months is not accepted, propose 12 months.",
+      "estimated_difficulty": "medium",
+      "legal_basis": "Reasonableness standard for restrictive covenants",
+      "business_impact": "Severely restricts the Employee's ability to find future employment.",
+      "counterparty_concerns": "They may argue this is necessary to protect trade secrets.",
+      "timing_suggestion": "Address this early in negotiations.",
+      "bargaining_chips": [
+        "Offer to sign a stronger confidentiality agreement.",
+        "Agree to a shorter notice period for termination."
+      ]
+    }
+  ],
+  "market_comparisons": [],
+  "executive_summary": "This employment agreement is heavily skewed in favor of the Employer...",
+  "metadata": {
+    "text_length": 15000,
+    "word_count": 2500,
+    "num_clauses": 20,
+    "contract_type": "EMPLOYMENT",
+    "actual_category": "employment",
+    "options": {
+      "max_clauses": 50,
+      "interpret_clauses": true,
+      "generate_negotiation_points": true,
+      "compare_to_market": false
+    }
+  },
+  "pdf_available": true
+}
+```
+
+### Error Response
+
+**Status Code:** `400 Bad Request` or `500 Internal Server Error`
+
+**Content-Type:** `application/json`
+
+```json
+{
+  "error": "Analysis failed",
+  "detail": "Contract text too short. Minimum 300 characters required.",
+  "timestamp": "2025-11-17T15:01:01.123456"
+}
+```
+
+---
+
+## Analyze Contract from Text
+
+Analyzes a contract provided as plain text.
+
+### Endpoint
+
+`POST /api/v1/analyze/text`
+
+### Request
+
+**Content-Type:** `application/x-www-form-urlencoded`
+
+**Form Data:**
+
+- `contract_text`: **(Required, String)** The full text of the contract.
+- `max_clauses`: **(Optional, Integer)** Maximum number of clauses to analyze (default: `15`, min: `5`, max: `30`).
+- `interpret_clauses`: **(Optional, Boolean)** Whether to generate LLM interpretations for clauses (default: `true`).
+- `generate_negotiation_points`: **(Optional, Boolean)** Whether to generate negotiation points (default: `true`).
+- `compare_to_market`: **(Optional, Boolean)** Whether to perform market comparison (default: `false`, currently disabled).
+
+### Response
+
+Same as the response for [Analyze Contract from File](#analyze-contract-from-file).
+
+### Error Response
+
+Same as the error response for [Analyze Contract from File](#analyze-contract-from-file).
+
+---
+
+## Generate PDF Report
+
+Generates a downloadable PDF report based on the analysis result provided in the request body.
+
+### Endpoint
+
+`POST /api/v1/generate-pdf`
+
+### Request
+
+**Content-Type:** `application/json`
+
+**Body:** The full JSON object returned by a successful `/analyze/file` or `/analyze/text` request.
+
+```json
+{
+  "analysis_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
+  "timestamp": "2025-11-17T15:01:00.123456",
+  "classification": { ... },
+  "clauses": [ ... ],
+  "risk_analysis": { ... },
+  "unfavorable_terms": [ ... ],
+  "missing_protections": [ ... ],
+  "clause_interpretations": [ ... ],
+  "negotiation_points": [ ... ],
+  "market_comparisons": [ ... ],
+  "executive_summary": "...",
+  "metadata": { ... },
+  "pdf_available": true
+}
+```
+
+### Response
+
+**Status Code:** `200 OK`
+
+**Content-Type:** `application/pdf`
+
+**Headers:**
+
+- `Content-Disposition`: `attachment; filename=contract_analysis_<analysis_id>.pdf`
+
+The response body contains the binary PDF data.
+
+### Error Response
+
+**Status Code:** `500 Internal Server Error`
+
+**Content-Type:** `application/json`
+
+```json
+{
+  "error": "Internal server error",
+  "detail": "Failed to generate PDF: Some error message",
+  "timestamp": "2025-11-17T15:02:00.123456"
+}
+```
+
+---
+
+## Validate Contract File
+
+Validates if an uploaded file is a potentially valid contract document.
+
+### Endpoint
+
+`POST /api/v1/validate/file`
+
+### Request
+
+**Content-Type:** `multipart/form-data`
+
+**Form Data:**
+
+- `file`: **(Required)** The contract file to validate (PDF, DOCX, TXT).
+
+### Response
+
+**Status Code:** `200 OK`
+
+**Content-Type:** `application/json`
+
+```json
+{
+  "valid": true,
+  "message": "Contract appears valid",
+  "confidence": 85.0,
+  "report": {
+    "scores": {
+      "total": 85.0,
+      "has_parties": 90.0,
+      "has_date": 80.0,
+      "has_terms": 90.0
+    },
+    "found_indicators": ["agreement", "party", "terms"],
+    "found_anti_patterns": [],
+    "text_statistics": {
+      "length": 15000,
+      "word_count": 2500,
+      "line_count": 300
+    }
+  }
+}
+```
+
+### Error Response
+
+**Status Code:** `400 Bad Request`
+
+**Content-Type:** `application/json`
+
+```json
+{
+  "error": "Validation failed",
+  "detail": "File too large. Max size: 10.0MB",
+  "timestamp": "2025-11-17T15:03:00.123456"
+}
+```
+
+---
+
+## Validate Contract Text
+
+Validates if a provided text string is a potentially valid contract.
+
+### Endpoint
+
+`POST /api/v1/validate/text`
+
+### Request
+
+**Content-Type:** `application/x-www-form-urlencoded`
+
+**Form Data:**
+
+- `contract_text`: **(Required, String)** The text to validate.
+
+### Response
+
+**Status Code:** `200 OK`
+
+**Content-Type:** `application/json`
+
+```json
+{
+  "valid": true,
+  "message": "Contract appears valid",
+  "confidence": 78.0,
+  "report": {
+    "scores": {
+      "total": 78.0,
+      "has_parties": 85.0,
+      "has_date": 70.0,
+      "has_terms": 80.0
+    },
+    "found_indicators": ["agreement", "party", "payment"],
+    "found_anti_patterns": [],
+    "text_statistics": {
+      "length": 1200,
+      "word_count": 200,
+      "line_count": 25
+    }
+  }
+}
+```
+
+### Error Response
+
+**Status Code:** `400 Bad Request`
+
+**Content-Type:** `application/json`
+
+```json
+{
+  "error": "Validation failed",
+  "detail": "Contract text too short. Minimum 300 characters required.",
+  "timestamp": "2025-11-17T15:04:00.123456"
+}
+```
+
+---
+
+## Notes
+
+- All timestamps are in ISO 8601 format
+- All risk scores are integers from 0-100
+- The API uses custom JSON serialization to handle NumPy types
+- CORS is enabled for all origins in development
+- Maximum file upload size is configurable via settings (default: 10MB)
+- Minimum contract text length: 300 characters (configurable)
+- Maximum contract text length: configurable via settings

docs/BLOGPOST.md

@@ -2,7 +2,7 @@
 
 ## The Paradigm Shift in Contractual Comprehension
 
-In our contemporary landscape, where legal contracts underpin virtually every commercial transaction and professional engagement, the capacity to decipher and negotiate equitable terms has evolved from a specialized skill to an essential competency. Yet, the labyrinthine complexity of legal vernacular continues to erect formidable barriers for those outside the legal profession, resulting in executed agreements that frequently conceal latent risks and disadvantageous provisions. The **AI Contract Risk Analyzer** heralds a transformative approach to legal document scrutiny, harnessing sophisticated artificial intelligence to deliver instantaneous, exhaustive contract risk evaluation accessible to all.
+In our contemporary landscape, where legal contracts underpin virtually every commercial transaction and professional engagement, the capacity to decipher and negotiate equitable terms has evolved from a specialized skill to an essential competency. Yet, the labyrinthine complexity of legal vernacular continues to erect formidable barriers for those outside the legal profession, resulting in executed agreements that frequently conceal latent risks and disadvantageous provisions. The **AI Contract Risk Analyzer** heralds a transformative approach to legal document scrutiny, harnessing a sophisticated, integrated artificial intelligence pipeline to deliver instantaneous, comprehensive contract risk evaluation accessible to all.
 
 ---
 
@@ -28,9 +28,9 @@ Legal documentation presents an intricate tapestry of challenges:
 
 ---
 
-## The Resolution: Artificial Intelligence-Powered Contract Intelligence
+## The Resolution: An Integrated AI Analysis Pipeline
 
-The AI Contract Risk Analyzer bridges the chasm between legal complexity and human understanding through an elaborate, multi-tiered artificial intelligence ecosystem.
+The AI Contract Risk Analyzer bridges the chasm between legal complexity and human understanding through a meticulously orchestrated, multi-stage artificial intelligence ecosystem that processes contracts with surgical precision.
 
 ### Operational Methodology: The User Odyssey
 
@@ -45,21 +45,27 @@ Effortlessly upload your PDF or Word document into our secure digital environmen
 - And numerous additional contract classifications
 
 #### Phase 2: Instantaneous AI Scrutiny
-Within a remarkable 30-second window, our AI engine executes:
-- **Contract categorization** to identify document typology
-- **Provisional extraction** to isolate crucial stipulations
-- **Risk quantification** across eight distinct dimensions
-- **Market benchmarking** against industry standards
-- **Protection gap analysis** to identify omissions
+Within a remarkable 40 - 60-second window, our AI engine executes a comprehensive analysis across eight distinct stages:
+
+1. **Contract Classification**: Identifying the agreement type (e.g., Employment, NDA, Lease)
+2. **Clause Extraction**: Isolating and categorizing key contractual provisions
+3. **Unfavorable Term Detection**: Pinpointing one-sided, punitive, or ambiguous language
+4. **Missing Protection Identification**: Recognizing critical safeguards absent from the agreement
+5. **Risk Scoring & Aggregation**: Calculating a holistic risk score across multiple dimensions
+6. **LLM-Powered Interpretation**: Generating plain-English explanations of complex clauses
+7. **Negotiation Strategy Generation**: Creating prioritized talking points with strategic context
+8. **Executive Summary Synthesis**: Producing a concise, actionable overview
 
 #### Phase 3: Comprehensive Insight Acquisition
 Receive an exhaustive analysis comprising:
 - **Holistic Risk Assessment** (0-100 scale) with unambiguous severity classification
 - **Executive Synopsis** in accessible vernacular
-- **Clause-by-Clause Deconstruction** with contextual interpretations
+- **Interactive Clause-by-Clause Deconstruction** with scrollable sections
 - **Identified Unfavorable Terms** with remediation suggestions
 - **Absent Protections** requiring inclusion
 - **Prioritized Negotiation Points** by significance hierarchy
+- **Risk Category Breakdown** with visual progress indicators
+- **Downloadable PDF Report** for offline reference
 
 #### Phase 4: Strategic Implementation
 Equipped with profound insights, you can:
@@ -72,41 +78,58 @@ Equipped with profound insights, you can:
 
 ## The Technological Architecture: Engineering the Extraordinary
 
-### Polymorphic AI Framework
+### A Symphony of Specialized AI Components
+
+Our platform transcends singular AI model dependency, instead constructing an intricate ensemble of specialized models operating in symphonic coordination through a unified processing pipeline.
 
-Our platform transcends singular AI model dependency, instead constructing an intricate ensemble of specialized models operating in symphonic coordination:
+#### 1. **Contract Classifier**: Intelligent Typology Identification
+At the heart of our system lies a sophisticated classifier that determines the contract's nature with high precision. This component uses:
+- **Multi-modal scoring** combining keyword matching, semantic similarity, and Legal-BERT embeddings
+- **Hierarchical categorization** to identify primary type (e.g., "employment") and subcategories (e.g., "executive")
+- **Confidence calibration** with detailed reasoning to ensure accurate downstream processing
 
-#### 1. Legal-BERT for Jurisprudential Comprehension
-We've refined the Legal-BERT model (nlpaueb/legal-bert-base-uncased) specifically for contract analysis. This model apprehends legal language subtleties that conventional AI overlooks:
+#### 2. **Risk-Focused Clause Extractor**: Precision-Driven Discovery
+We employ a two-tiered extraction system:
+- **Comprehensive Extractor**: Identifies structural patterns and semantic chunks across all legal domains
+- **Risk-Specific Re-classifier**: Maps extracted clauses to **risk categories** (e.g., "restrictive_covenants", "termination_rights") rather than generic clause types, enabling precise risk quantification aligned with industry standards
+
+#### 3. **Legal-BERT & Embedding Models**: Deep Semantic Understanding
+We've refined the Legal-BERT model (nlpaueb/legal-bert-base-uncased) specifically for contract analysis. These models apprehend legal language subtleties that conventional AI overlooks:
 - Discerns 15+ categories of contractual stipulations
 - Achieves 92% precision in clause boundary identification
 - Manages complex legal syntax and cross-referential elements
-
-#### 2. Semantic Equivalency Engine
-Leveraging advanced embedding architectures, we transmute legal text into mathematical vectors that encapsulate meaning:
-- Transforms clauses into 384-dimensional vector representations
-- Facilitates comparison against 1000+ established risk patterns
-- Benchmarks your contract against industry standards
-
-#### 3. Large Language Model Integration for Natural Communication
-We interface with multiple Large Language Models (Ollama, OpenAI GPT-3.5, Anthropic Claude) to:
-- Generate lucid explanations of intricate clauses
-- Provide contextually-aware negotiation recommendations
-- Create executive summaries tailored to comprehension levels
-
-#### 4. Multifactor Risk Evaluation
-Our proprietary risk assessment algorithm examines:
-- **Lexical Severity**: Detection of critical risk terminology
-- **Structural Configurations**: Recognition of unfavorable clause architectures
-- **Provision-Level Analysis**: Intensive examination of specific stipulations
-- **Industry Benchmarks**: Comparison to market conventions
-- **Protection Deficiencies**: Identification of absent safeguards
+- Uses sentence transformers (all-MiniLM-L6-v2) for semantic similarity at scale
+
+#### 4. **Integrated Risk Engine**: Holistic Risk Quantification
+Our proprietary `ComprehensiveRiskAnalyzer` orchestrates the entire pipeline:
+- **Weighted category scoring** adjusted for contract type (e.g., restrictive covenants are weighted higher in employment contracts)
+- **Risk factor integration** from red flags, pattern matching, and keyword detection
+- **Cross-component validation** ensuring consistency between term analysis, protection checks, and clause evaluation
+- **Dynamic threshold application** based on industry benchmarks and jurisdictional norms
+
+#### 5. **LLM Interpreter & Negotiation Engine**: Human-Centric Explanation
+We interface with multiple Large Language Models to transform technical findings into actionable insights:
+- **Ollama (Local)**: Privacy-centric interpretation with llama3:8b
+- **OpenAI GPT-3.5/4**: High-fidelity natural language generation
+- **Anthropic Claude**: Enterprise-grade reasoning and ethical alignment
+- **Unified LLM Manager**: Automatic provider fallback ensures reliability
+
+This generates:
+- Plain-English interpretations of complex clauses
+- Contextually-aware negotiation recommendations
+- Executive summaries tailored to business impact
+
+#### 6. **Proactive Protection Checker**: Gap Detection
+Our system identifies what's *missing*—not just what's present:
+- **Critical protections checklist** calibrated for each contract type
+- **Semantic gap analysis** detecting absence of standard safeguards
+- **Risk-if-missing quantification** to prioritize remediation
 
 ---
 
 ## Distinguishing Characteristics: Our Competitive Differentiation
 
-### 1. Comprehensive Risk Deconstruction
+### 1. **True End-to-End Risk Analysis**
 Diverging from elementary keyword scanners, we furnish detailed analysis across multiple vectors:
 - **Restrictive Covenants** (non-competition, non-solicitation)
 - **Termination Privileges** (notice periods, for-cause definitions)
@@ -114,28 +137,30 @@ Diverging from elementary keyword scanners, we furnish detailed analysis across
 - **Compensation & Benefits** (transparency, discretion, vesting)
 - **Intellectual Property** (proprietorship, scope, exclusions)
 
-### 2. Actionable Negotiation Strategies
-We transcend problem identification to provide tangible solutions:
-- Hierarchically prioritized issues (critical → low priority)
-- Specific proposed language for each concern
-- Rationale elucidating the significance
-- Alternative positions if primary requests encounter resistance
-- Estimated negotiation complexity
-
-### 3. Accessible Interpretations
-Every complex legal provision undergoes translation into comprehensible language:
-- **Synopsis**: Essential meaning in 1-2 sentences
-- **Salient Points**: 3-5 critical comprehension elements
-- **Potential Exposure**: 2-4 concerns or warning indicators
-- **Equitability Assessment**: Rated as favorable/neutral/unfavorable
-
-### 4. Market Contextualization
+### 2. **Actionable Negotiation Playbook**
+We transcend problem identification to provide tangible solutions through a comprehensive strategy document:
+- **Priority-ranked issues** (1=highest, 5=lowest)
+- **Specific proposed language** with multiple improvement options
+- **Strategic rationale** grounded in legal principles and business impact
+- **Counterparty concern anticipation** to strengthen negotiation position
+- **Timing guidance** for optimal issue-raising sequence
+- **Bargaining chips** to trade for concessions
+
+### 3. **Context-Aware Interpretation**
+Every complex legal provision undergoes translation into comprehensible language with contextual depth:
+- **Plain-English summary** of core meaning
+- **Key points** highlighting essential implications
+- **Potential risks** outlining exposure and consequences
+- **Favorability assessment** from the recipient's perspective
+- **Suggested improvements** for balanced terms
+
+### 4. **Market Contextualization**
 Evaluate your contract's positioning relative to industry standards:
 - Comparison to reasonable, conventional, and aggressive market terms
 - Similarity metrics demonstrating alignment with best practices
 - Recommendations for normalizing outlier provisions
 
-### 5. Protection Deficiency Audit
+### 5. **Protection Deficiency Audit**
 We identify crucial safeguards that warrant inclusion but remain absent:
 - For-cause termination definitions
 - Severance provisions
@@ -153,23 +178,36 @@ We identify crucial safeguards that warrant inclusion but remain absent:
 - **Sentence Transformers** (all-MiniLM-L6-v2): Semantic similarity and embeddings
 - **PyTorch**: Deep learning architecture
 - **Hugging Face Transformers**: Model deployment and inference
+- **Model Registry**: Thread-safe management with LRU eviction for efficient memory use
 
 ### Backend Architecture
 - **FastAPI**: High-performance REST API (1000+ requests/second)
 - **Python 3.10+**: Core application logic
 - **Asynchronous Processing**: Background operations for extended analysis
-- **Redis Caching**: Sub-second response intervals for recurrent queries
+- **Redis-like Caching**: Disk-based caching with TTL for model outputs
+- **Thread Safety**: Robust handling of concurrent analysis requests
 
 ### Document Processing Pipeline
-- **PyMuPDF**: Superior PDF text extraction
+- **PyMuPDF**: Superior PDF text extraction with layout preservation
 - **python-docx**: Word document processing
 - **Custom NLP Pipeline**: Legal-specific text refinement and normalization
+- **Encoding Detection**: Automated character encoding identification
+- **Metadata Extraction**: Document properties and structural information
 
 ### LLM Integration Framework
 - **Ollama**: Local model hosting (privacy-centric)
 - **OpenAI API**: GPT-3.5/4 integration
 - **Anthropic Claude**: Enterprise-grade reasoning
 - **Multi-provider Redundancy**: Automatic failover for reliability
+- **Rate Limiting**: Token bucket algorithm to manage API usage
+- **Cost Estimation**: Real-time cost tracking for cloud-based providers
+
+### Frontend Experience
+- **Responsive Design**: Mobile-first approach with desktop optimization
+- **Scrollable Analysis Sections**: Interactive viewing of lengthy reports
+- **Real-time Feedback**: Loading states and error handling
+- **Visual Risk Indicators**: Color-coded risk levels and confidence scores
+- **Immediate Download**: One-click PDF report generation with embedded charts
 
 ---
 
@@ -182,6 +220,7 @@ We recognize that contracts contain sensitive information. Our security infrastr
 - **Ephemeral processing**: Documents purged immediately post-analysis
 - **Exclusion from training**: Your contracts never utilized for model enhancement
 - **Isolated processing**: Each analysis operates in a segregated environment
+- **Zero persistent storage**: No account required; no data retained
 
 ### Regulatory Compliance
 - **GDPR adherence**: Data residency and right-to-erasure support
@@ -191,7 +230,7 @@ We recognize that contracts contain sensitive information. Our security infrastr
 ### User Autonomy
 - **Report acquisition**: PDF exports for personal archives
 - **Instant deletion**: Single-command eradication of all analysis history
-- **Anonymous utilization**: No account mandatory for fundamental analysis
+- **Anonymous utilization**: No registration mandatory for fundamental analysis
 
 ---
 
@@ -200,18 +239,23 @@ We recognize that contracts contain sensitive information. Our security infrastr
 ### Immediate Horizon
 - **Multilingual capability**: Expansion beyond English to major global languages
 - **Sector-specific templates**: Industry-tailored analysis (healthcare, finance, technology)
+- **Enhanced LLM integration**: More sophisticated negotiation point generation
+- **Improved visual analytics**: Interactive risk dashboards and trend analysis
 
 ### Intermediate Timeline
 - **Predictive analytics**: Dispute probability forecasting based on clause patterns
-- **Regulatory conformity**: Automated verification against GDPR, CCPA, industry regulations
+- **Regulatory conformity**: Automated verification against GDPR, CCPA, HIPAA, and other regulations
 - **Smart contract analysis**: Support for blockchain-based agreements
 - **Collaborative examination**: Team workflows with role-based permissions
+- **Version comparison**: Track changes between contract drafts
 
 ### Long-term Aspiration
 - **AI negotiation facilitation**: Real-time negotiation support during contractual discussions
 - **Legal outcome projection**: Machine learning models predicting litigation results
 - **Global legal repository**: Anonymous pattern aggregation for market intelligence
 - **Jurisdiction-specific analysis**: Deep integration with municipal laws and precedents
+- **Automated clause drafting**: Generate balanced, legally sound alternatives
+- **Continuous monitoring**: Alert users when existing contracts need re-evaluation
 
 ---
 
@@ -220,7 +264,7 @@ We recognize that contracts contain sensitive information. Our security infrastr
 Prepared to assume command of your contracts? Initiation is straightforward:
 
 1. **Access our platform**: [contractguardai.com](https://contractguardai.com)
-2. **Submit a contract**: PDF or Word document
+2. **Submit a contract**: Paste text or upload a PDF/DOCX file
 3. **Receive instantaneous analysis**: Results within 30 seconds
 4. **Acquire your report**: Comprehensive PDF with complete findings
 
@@ -232,11 +276,13 @@ No financial instrument required for your analysis. No installation necessary. N
 
 The AI Contract Risk Analyzer transcends mere tool status—it represents a movement toward legal transparency and accessibility. Whether you're executing your inaugural employment contract or reviewing your centesimal vendor agreement, you merit comprehension of your commitments.
 
+Our enhanced architecture ensures that every component—from clause extraction to final PDF generation—operates in harmony, delivering reports that match the quality of the attached examples while maintaining robustness, scalability, and user-friendliness.
+
 **Your contracts. Your rights. Your assurance.**
 
 ---
 
 *Ultimate Revision: November 2025* | *Version: 1.0*
 
-> © 2025 AI Contract Risk Analyzer. Democratizing legal intelligence for global accessibility.
----
+© 2025 AI Contract Risk Analyzer. Democratizing legal intelligence for global accessibility.
+---

reporter/pdf_generator.py

@@ -1,5 +1,6 @@
 # DEPENDENCIES
 import os
+import math
 from typing import Any
 from io import BytesIO
 from typing import Dict
@@ -12,36 +13,52 @@ from reportlab.platypus import Image
 from reportlab.platypus import Table
 from reportlab.lib.units import inch
 from reportlab.platypus import Spacer
+from reportlab.lib.pagesizes import A4
 from reportlab.lib.enums import TA_LEFT
 from reportlab.platypus import Paragraph
 from reportlab.platypus import PageBreak
 from reportlab.graphics import renderPDF
 from reportlab.platypus import TableStyle
 from reportlab.lib.enums import TA_CENTER
+from reportlab.graphics.shapes import Path
 from reportlab.lib.enums import TA_JUSTIFY
 from reportlab.lib.pagesizes import letter
+from reportlab.lib.utils import simpleSplit
 from reportlab.platypus import KeepTogether
 from reportlab.graphics.shapes import Circle
 from reportlab.graphics.shapes import String
+from reportlab.lib.pagesizes import landscape
 from reportlab.graphics.shapes import Drawing
 from reportlab.lib.styles import ParagraphStyle
 from reportlab.platypus import SimpleDocTemplate
+from reportlab.platypus.flowables import PageBreak
+from reportlab.platypus.flowables import KeepInFrame
 from reportlab.lib.styles import getSampleStyleSheet
-
+from reportlab.platypus import Table as PlatypusTable
 
 
 class PDFReportGenerator:
     """
-    Generate professional PDF reports matching the sample style
+    Professional-grade PDF report generator matching sample style exactly
     """
     def __init__(self):
-        self.styles = getSampleStyleSheet()
-        self._setup_custom_styles()
+        self.styles         = getSampleStyleSheet()
         
+        self._setup_custom_styles()
+
+        self.page_width     = letter[0]
+        self.page_height    = letter[1]
+        self.margin_left    = 0.75 * inch
+        self.margin_right   = 0.75 * inch
+        self.margin_top     = 1 * inch
+        self.margin_bottom  = 1 * inch
+        self.content_width  = self.page_width - self.margin_left - self.margin_right
+        self.content_height = self.page_height - self.margin_top - self.margin_bottom
+
 
     def _setup_custom_styles(self):
         """
-        Setup custom paragraph styles
+        Setup custom paragraph styles with precise control
         """
         # Title style
         self.styles.add(ParagraphStyle(name       = 'ReportTitle',
@@ -53,7 +70,7 @@ class PDFReportGenerator:
                                        fontName   = 'Helvetica-Bold',
                                       )
                        )
-        
+
         # Section heading
         self.styles.add(ParagraphStyle(name        = 'SectionHeading',
                                        parent      = self.styles['Heading2'],
@@ -64,389 +81,727 @@ class PDFReportGenerator:
                                        fontName    = 'Helvetica-Bold',
                                       )
                        )
-        
+
+        # Sub-section heading
+        self.styles.add(ParagraphStyle(name        = 'SubSectionHeading',
+                                       parent      = self.styles['Normal'],
+                                       fontSize    = 12,
+                                       textColor   = colors.HexColor('#333333'),
+                                       spaceAfter  = 8,
+                                       spaceBefore = 12,
+                                       fontName    = 'Helvetica-Bold',
+                                      )
+                       )
+
         # Body text
-        self.styles.add(ParagraphStyle(
-            name='CustomBodyText',
-            parent=self.styles['Normal'],
-            fontSize=10,
-            leading=14,
-            textColor=colors.HexColor('#333333'),
-            alignment=TA_JUSTIFY,
-            fontName='Helvetica'
-        ))
-
-        # Small text style (add this)
-        self.styles.add(ParagraphStyle(
-            name='SmallText',
-            parent=self.styles['Normal'],
-            fontSize=8,
-            leading=10,
-            textColor=colors.HexColor('#666666'),
-            fontName='Helvetica'
-        ))
-        
+        self.styles.add(ParagraphStyle(name        = 'CustomBodyText',
+                                       parent      = self.styles['Normal'],
+                                       fontSize    = 10,
+                                       leading     = 14,
+                                       textColor   = colors.HexColor('#333333'),
+                                       alignment   = TA_JUSTIFY,
+                                       fontName    = 'Helvetica',
+                                       leftIndent  = 0,
+                                       rightIndent = 0,
+                                      )
+                       )
+
+        # Small text style
+        self.styles.add(ParagraphStyle(name      = 'SmallText',
+                                       parent    = self.styles['Normal'],
+                                       fontSize  = 8,
+                                       leading   = 10,
+                                       textColor = colors.HexColor('#666666'),
+                                       fontName  = 'Helvetica',
+                                      )
+                       )
+
         # Bullet point
-        self.styles.add(ParagraphStyle(
-            name='BulletPoint',
-            parent=self.styles['Normal'],
-            fontSize=10,
-            leading=14,
-            textColor=colors.HexColor('#333333'),
-            leftIndent=20,
-            bulletIndent=10,
-            fontName='Helvetica'
-        ))
-        
+        self.styles.add(ParagraphStyle(name           = 'BulletPoint',
+                                       parent         = self.styles['Normal'],
+                                       fontSize       = 10,
+                                       leading        = 14,
+                                       textColor      = colors.HexColor('#333333'),
+                                       leftIndent     = 20,
+                                       bulletIndent   = 10,
+                                       bulletFontName = 'Helvetica',
+                                       bulletFontSize = 10,
+                                       bulletColor    = colors.black,
+                                       spaceAfter     = 4,
+                                       fontName       = 'Helvetica',
+                                      )
+                       )
+
         # Table header
-        self.styles.add(ParagraphStyle(
-            name='TableHeader',
-            parent=self.styles['Normal'],
-            fontSize=10,
-            textColor=colors.HexColor('#1a1a1a'),
-            fontName='Helvetica-Bold'
-        ))
-        
+        self.styles.add(ParagraphStyle(name      = 'TableHeader',
+                                       parent    = self.styles['Normal'],
+                                       fontSize  = 10,
+                                       textColor = colors.HexColor('#1a1a1a'),
+                                       fontName  = 'Helvetica-Bold',
+                                       alignment = TA_LEFT,
+                                      )
+                       )
+
+        # Table cell
+        self.styles.add(ParagraphStyle(name       = 'TableCell',
+                                       parent     = self.styles['Normal'],
+                                       fontSize   = 9,
+                                       textColor  = colors.HexColor('#333333'),
+                                       fontName   = 'Helvetica',
+                                       alignment  = TA_LEFT,
+                                       spaceAfter = 2,
+                                      )
+                       )
+
         # Footer
-        self.styles.add(ParagraphStyle(
-            name='Footer',
-            parent=self.styles['Normal'],
-            fontSize=8,
-            textColor=colors.HexColor('#666666'),
-            alignment=TA_CENTER,
-            fontName='Helvetica'
-        ))
-    
+        self.styles.add(ParagraphStyle(name      = 'Footer',
+                                       parent    = self.styles['Normal'],
+                                       fontSize  = 8,
+                                       textColor = colors.HexColor('#666666'),
+                                       alignment = TA_CENTER,
+                                       fontName  = 'Helvetica',
+                                      )
+                       )
+
+        # Risk indicator style
+        self.styles.add(ParagraphStyle(name       = 'RiskIndicator',
+                                       parent     = self.styles['Normal'],
+                                       fontSize   = 9,
+                                       textColor  = colors.HexColor('#dc2626'),
+                                       fontName   = 'Helvetica-Bold',
+                                       backColor  = colors.HexColor('#fef2f2'),
+                                       borderPadding = 5,
+                                       spaceAfter = 4,
+                                      )
+                       )
+
+        # Keyword style
+        self.styles.add(ParagraphStyle(name       = 'Keyword',
+                                       parent     = self.styles['Normal'],
+                                       fontSize   = 9,
+                                       textColor  = colors.HexColor('#1e40af'),
+                                       fontName   = 'Helvetica',
+                                       backColor  = colors.HexColor('#eff6ff'),
+                                       borderPadding = 3,
+                                      )
+                       )
+
+
     def _draw_risk_score_circle(self, score: int) -> Drawing:
-        """Draw the risk score circle graphic"""
-        d = Drawing(150, 150)
+        """
+        Draw the risk score circle graphic with correct fill percentage
+        """
+        d                  = Drawing(150, 150)
         
+        # Define circle properties
+        center_x, center_y = 75, 75
+        outer_radius       = 60
+        inner_radius       = 45
+        thickness          = 15  # Thickness of the colored ring
+
         # Determine color based on score
-        if score >= 80:
-            color = colors.HexColor('#dc2626')
-        elif score >= 60:
-            color = colors.HexColor('#f97316')
-        elif score >= 40:
-            color = colors.HexColor('#ca8a04')
+        if (score >= 80):
+            color = colors.HexColor('#dc2626')  # Red
+
+        elif (score >= 60):
+            color = colors.HexColor('#f97316')  # Orange
+
+        elif (score >= 40):
+            color = colors.HexColor('#ca8a04')  # Amber
+
         else:
-            color = colors.HexColor('#16a34a')
-        
-        # Background circle
-        bg_circle = Circle(75, 75, 60)
-        bg_circle.fillColor = colors.HexColor('#f0f0f0')
+            color = colors.HexColor('#16a34a')  # Green
+
+        # Draw background circle (light grey)
+        bg_circle             = Circle(center_x, center_y, outer_radius)
+        bg_circle.fillColor   = colors.HexColor('#f0f0f0')
         bg_circle.strokeColor = None
+
         d.add(bg_circle)
+
+        # Draw colored arc representing the score percentage: The arc is drawn from 0 degrees (3 o'clock) clockwise
+        sweep_angle           = (score / 100.0) * 360
+
+        # Start angle is 90 degrees counter-clockwise from 3 o'clock (i.e., 12 o'clock)
+        start_angle           = 90
+
+        # Clockwise direction
+        end_angle             = start_angle - sweep_angle  
+
+        # Ensure start angle is greater than end angle for clockwise sweep
+        if (start_angle < end_angle):
+            end_angle = start_angle - sweep_angle
+            extent    = -sweep_angle
+
+        else:
+            # Clockwise sweep
+            extent = -sweep_angle 
+
+        # Create a path for the arc (ring segment)
+        p             = Path()
+
+        # Calculate start and end points using trigonometry
+        start_rad     = math.radians(start_angle)
+
+        # Correct end angle for clockwise
+        end_rad       = math.radians(start_angle - sweep_angle)
+
+        # Move to the outer perimeter at the start angle
+        start_outer_x = center_x + outer_radius * math.cos(start_rad)
+        start_outer_y = center_y + outer_radius * math.sin(start_rad)
+
+        p.moveTo(start_outer_x, start_outer_y)
         
-        # Score circle
-        score_circle = Circle(75, 75, 55)
-        score_circle.fillColor = color
-        score_circle.strokeColor = None
-        d.add(score_circle)
-        
-        # Inner white circle
-        inner_circle = Circle(75, 75, 45)
-        inner_circle.fillColor = colors.white
+        # At least 10 segments, or 1 per 5 degrees of sweep
+        num_segments  = max(10, int(sweep_angle / 5)) 
+        angle_step    = sweep_angle / num_segments
+
+        # Draw outer arc as line segments
+        for i in range(1, num_segments + 1):
+            # Clockwise
+            current_angle_deg = start_angle - (i * angle_step) 
+            current_angle_rad = math.radians(current_angle_deg)
+            x                 = center_x + outer_radius * math.cos(current_angle_rad)
+            y                 = center_y + outer_radius * math.sin(current_angle_rad)
+
+            p.lineTo(x, y)
+
+        # Draw inner arc as line segments (reverse direction)
+        for i in range(num_segments, -1, -1):
+            # Clockwise
+            current_angle_deg = start_angle - (i * angle_step)
+            current_angle_rad = math.radians(current_angle_deg)
+            x                 = center_x + inner_radius * math.cos(current_angle_rad)
+            y                 = center_y + inner_radius * math.sin(current_angle_rad)
+            p.lineTo(x, y)
+
+        p.closePath()
+        p.fillColor   = color
+        p.strokeColor = None
+        d.add(p)
+
+        # Draw inner white circle : Slightly smaller to fit inside the ring
+        inner_circle             = Circle(center_x, center_y, inner_radius - 2) 
+        inner_circle.fillColor   = colors.white
         inner_circle.strokeColor = None
         d.add(inner_circle)
-        
-        # Score text
-        score_text = String(75, 70, str(score), textAnchor='middle')
-        score_text.fontSize = 36
-        score_text.fontName = 'Helvetica-Bold'
-        score_text.fillColor = color
+
+        # Draw score text in the center
+        score_text               = String(center_x, center_y - 10, str(score), textAnchor='middle')
+        score_text.fontSize      = 36
+        score_text.fontName      = 'Helvetica-Bold'
+        score_text.fillColor     = color
         d.add(score_text)
-        
+
+        # Draw "/100" text slightly below the score
+        subtitle_text            = String(center_x, center_y - 28, "/100", textAnchor='middle')
+        subtitle_text.fontSize   = 16
+        subtitle_text.fontName   = 'Helvetica'
+        subtitle_text.fillColor  = colors.HexColor('#666666')
+        d.add(subtitle_text)
+
         return d
-    
+
+
     def _get_risk_color(self, score: int) -> colors.Color:
-        """Get color based on risk score"""
-        if score >= 80:
+        """
+        Get color based on risk score
+        """
+        if (score >= 80):
             return colors.HexColor('#dc2626')
-        elif score >= 60:
+
+        elif (score >= 60):
             return colors.HexColor('#f97316')
-        elif score >= 40:
+
+        elif (score >= 40):
             return colors.HexColor('#ca8a04')
+
         else:
             return colors.HexColor('#16a34a')
-    
+
+
     def _create_header_footer(self, canvas, doc):
-        """Add header and footer to each page"""
+        """
+        Add header and footer to each page with consistent positioning
+        """
         canvas.saveState()
-        
+
         # Header
         canvas.setFont('Helvetica-Bold', 12)
-        canvas.drawString(0.75 * inch, letter[1] - 0.5 * inch, 
-                        "AI Contract Risk Analysis Report")
-        
+        canvas.setFillColor(colors.black)
+        canvas.drawString(self.margin_left, self.page_height - 0.5 * inch, "AI Powered Contract Risk Analysis Report")
+
         # Footer
         canvas.setFont('Helvetica', 8)
         canvas.setFillColor(colors.HexColor('#666666'))
-        
-        # Page number (without total pages)
+
+        # Page number
         page_num = f"Page {doc.page}"
-        canvas.drawString(7 * inch, 0.5 * inch, page_num)
-        
-        # Legal disclaimer
+        canvas.drawString(self.page_width - self.margin_right - 1*inch, 0.5 * inch, page_num)
+
+        # Disclaimer
         disclaimer = "For informational purposes only. Not legal advice."
-        canvas.drawCentredString(letter[0] / 2, 0.5 * inch, disclaimer)
-        
+        canvas.drawCentredString(self.page_width / 2.0, 0.5 * inch, disclaimer)
+
         canvas.restoreState()
 
-    
-    def generate_report(self, analysis_result: Dict[str, Any], 
-                       output_path: Optional[str] = None) -> BytesIO:
+
+    def generate_report(self, analysis_result: Dict[str, Any], output_path: Optional[str] = None) -> BytesIO:
         """
         Generate PDF report from analysis results
-        
-        Args:
-            analysis_result: Analysis result dictionary from the API
-            output_path: Optional file path to save PDF
-            
+
+        Arguments:
+        ----------
+            analysis_result { dict } : Analysis result dictionary from the API
+
+            output_path      { str } : Optional file path to save PDF
+
         Returns:
-            BytesIO buffer containing the PDF
+        --------
+                  { BytesIO }        : Buffer containing the PDF
         """
         # Create buffer
         buffer = BytesIO()
-        
+
         # Create document
-        doc = SimpleDocTemplate(
-            buffer if not output_path else output_path,
-            pagesize=letter,
-            rightMargin=0.75*inch,
-            leftMargin=0.75*inch,
-            topMargin=1*inch,
-            bottomMargin=1*inch
-        )
-        
+        doc    = SimpleDocTemplate(buffer if not output_path else output_path,
+                                   pagesize     = letter,
+                                   rightMargin  = self.margin_right,
+                                   leftMargin   = self.margin_left,
+                                   topMargin    = self.margin_top,
+                                   bottomMargin = self.margin_bottom,
+                                  )
+
         # Build story
-        story = []
-        
-        # Title and Risk Score (Page 1)
+        story   = list()
+
+        # Page 1: Title, Risk Score, Executive Summary, Keywords
         story.extend(self._build_page_1(analysis_result))
         story.append(PageBreak())
-        
-        # Negotiation Points (Page 2)
+
+        # Page 2: Unfavorable Terms, Missing Protections
         story.extend(self._build_page_2(analysis_result))
         story.append(PageBreak())
-        
-        # Risk Category Breakdown (Page 3)
+
+        # Page 3: Negotiation Points
         story.extend(self._build_page_3(analysis_result))
-        
-        # Clause-by-Clause Analysis (Page 4+)
         story.append(PageBreak())
-        story.extend(self._build_clause_analysis(analysis_result))
-        
+
+        # Page 4: Risk Category Breakdown Table
+        story.extend(self._build_page_4(analysis_result))
+        story.append(PageBreak())
+
+        # Page 5: Clause Interpretations
+        story.extend(self._build_page_5(analysis_result))
+        story.append(PageBreak())
+
+        # Page 6+: Detailed Clause Analysis
+        story.extend(self._build_clause_analysis_pages(analysis_result))
+
         # Build PDF
-        doc.build(story, onFirstPage=self._create_header_footer,
-                 onLaterPages=self._create_header_footer)
-        
+        doc.build(story, onFirstPage = self._create_header_footer, onLaterPages = self._create_header_footer)
+
         # If using buffer, seek to beginning
         if not output_path:
             buffer.seek(0)
             return buffer
-        
+
         return buffer
-    
+
+
     def _build_page_1(self, result: Dict) -> List:
-        """Build page 1 content: Title, Risk Score, Executive Summary, Key Items"""
-        elements = []
-        
+        """
+        Build page 1 content: Title, Risk Score, Executive Summary, Keywords
+        """
+        elements       = list()
+
         # Title
-        elements.append(Paragraph("AI Contract Risk Analysis Report", 
-                                 self.styles['ReportTitle']))
+        elements.append(Paragraph("AI Contract Risk Analysis Report", self.styles['ReportTitle']))
         elements.append(Spacer(1, 0.1*inch))
+
+        # Contract Info
+        classification = result.get('classification', {})
+        contract_type  = classification.get('subcategory', 'Unknown')
+        confidence     = classification.get('confidence', 0) * 100
         
-        # Risk Score Circle
-        risk_score = result['risk_analysis']['overall_score']
-        elements.append(self._draw_risk_score_circle(risk_score))
-        elements.append(Spacer(1, 0.2*inch))
-        
-        # Executive Summary
-        elements.append(Paragraph("Executive Summary", 
-                                 self.styles['SectionHeading']))
-        elements.append(Paragraph(result['executive_summary'], 
-                         self.styles['CustomBodyText']))
+        info_text      = f"<b>Contract Type:</b> {contract_type.replace('_', ' ').title()} | <b>Confidence:</b> {confidence:.1f}%"
+        elements.append(Paragraph(info_text, self.styles['CustomBodyText']))
         elements.append(Spacer(1, 0.2*inch))
+
+        # Risk Score Circle and Executive Summary Side-by-Side
+        risk_analysis = result.get('risk_analysis', {})
+        overall_score = risk_analysis.get('overall_score', 0)
+        risk_level    = risk_analysis.get('risk_level', 'UNKNOWN')
+        
+        score_frame   = KeepInFrame(1.5*inch, 1.5*inch, [self._draw_risk_score_circle(overall_score)])
+        summary_para  = Paragraph(f"<b>Overall Risk Score: {overall_score}/100 ({risk_level})</b><br/><br/>{result.get('executive_summary', 'No executive summary available.')}",
+                                 self.styles['CustomBodyText']
+                                )
+
+        top_row       = PlatypusTable([[score_frame, summary_para]], colWidths=[1.6*inch, 4.5*inch])
+
+        top_row.setStyle(TableStyle([('VALIGN', (0, 0), (-1, -1), 'TOP'),
+                                     ('LEFTPADDING', (0, 0), (-1, -1), 0),
+                                     ('RIGHTPADDING', (0, 0), (-1, -1), 0),
+                                     ('TOPPADDING', (0, 0), (-1, -1), 0),
+                                     ('BOTTOMPADDING', (0, 0), (-1, -1), 0),
+                                   ])
+                         )
+
+        elements.append(top_row)
+        elements.append(Spacer(1, 0.3*inch))
+
+        # Detected Keywords
+        detected_keywords = result.get('classification', {}).get('detected_keywords', [])
         
+        if detected_keywords:
+            elements.append(Paragraph("Detected Keywords", self.styles['SectionHeading']))
+            keywords_text = ", ".join([f"<font color='#1e40af'><b>{kw}</b></font>" for kw in detected_keywords[:15]])  # Show first 15 keywords
+            elements.append(Paragraph(keywords_text, self.styles['CustomBodyText']))
+
+        return elements
+
+
+    def _build_page_2(self, result: Dict) -> List:
+        """
+        Build page 2: Unfavorable Terms and Missing Protections
+        """
+        elements    = list()
+
         # Unfavorable Terms
-        elements.append(Paragraph("Unfavorable Terms", 
-                                 self.styles['SectionHeading']))
-        
-        for term in result['unfavorable_terms'][:8]:  # Limit to 8 items
-            bullet_text = f"<bullet>•</bullet> <b>{term.get('clause_reference', term['term'])}:</b> {term['explanation']}"
-            elements.append(Paragraph(bullet_text, self.styles['BulletPoint']))
-            elements.append(Spacer(1, 0.05*inch))
+        elements.append(Paragraph("Unfavorable Terms", self.styles['SectionHeading']))
+
+        unfav_terms = result.get('unfavorable_terms', [])
+
+        if unfav_terms:
+            # Sort by severity and risk score
+            sorted_terms = sorted(unfav_terms, key=lambda x: (x.get('severity', 'low') != 'high', -x.get('risk_score', 0)))
+            
+            for term in sorted_terms:
+                severity    = term.get('severity', 'unknown').upper()
+                risk_score  = term.get('risk_score', 0)
+                clause_ref  = term.get('clause_reference', 'N/A')
+                explanation = term.get('explanation', 'No explanation provided.')
+                
+                term_text   = f"<b>{clause_ref}</b> | <font color='{self._get_severity_color(severity).hexval()}'>{severity} SEVERITY</font> | Risk Score: {risk_score}<br/>{explanation}"
+                
+                elements.append(Paragraph(term_text, self.styles['BulletPoint']))
         
+        else:
+            elements.append(Paragraph("No unfavorable terms identified.", self.styles['CustomBodyText']))
+
         elements.append(Spacer(1, 0.2*inch))
         
         # Missing Protections
-        elements.append(Paragraph("Missing Protections", 
-                                 self.styles['SectionHeading']))
-        
-        for protection in result['missing_protections'][:6]:  # Limit to 6 items
-            bullet_text = f"<bullet>•</bullet> <b>{protection['protection']}:</b> {protection['explanation']}"
-            elements.append(Paragraph(bullet_text, self.styles['BulletPoint']))
-            elements.append(Spacer(1, 0.05*inch))
-        
-        return elements
-    
-    def _build_page_2(self, result: Dict) -> List:
-        """Build page 2 content: Negotiation Points"""
-        elements = []
-        
-        elements.append(Paragraph("Negotiation Points", 
-                                 self.styles['SectionHeading']))
-        elements.append(Spacer(1, 0.1*inch))
+        elements.append(Paragraph("Missing Protections", self.styles['SectionHeading']))
+
+        missing_protections = result.get('missing_protections', [])
         
-        negotiation_playbook = result.get('negotiation_playbook', {})
-        negotiation_points = negotiation_playbook.get('critical_points', [])
+        if missing_protections:
+            # Sort by importance and risk score
+            sorted_protections = sorted(missing_protections, key=lambda x: (x.get('importance', 'medium') != 'critical', -x.get('risk_score', 0)))
+            
+            for prot in sorted_protections:
+                importance      = prot.get('importance', 'medium').upper()
+                risk_score      = prot.get('risk_score', 0)
+                protection_name = prot.get('protection', 'N/A')
+                explanation     = prot.get('explanation', 'No explanation provided.')
+                
+                prot_text       = f"<b>{protection_name}</b> | <font color='{self._get_importance_color(importance).hexval()}'>{importance} IMPORTANCE</font> | Risk Score: {risk_score}<br/>{explanation}"
+                
+                elements.append(Paragraph(prot_text, self.styles['BulletPoint']))
         
-        if negotiation_points:
-            for point in negotiation_points[:7]:  # Limit to 7 points
-                bullet_text = f"<bullet>•</bullet> {point['issue']}: {point['rationale']}"
-                elements.append(Paragraph(bullet_text, self.styles['BulletPoint']))
-                elements.append(Spacer(1, 0.1*inch))
         else:
-            # Fallback to unfavorable terms if negotiation points not available
-            for term in result['unfavorable_terms'][:7]:
-                if term.get('suggested_fix'):
-                    bullet_text = f"<bullet>•</bullet> {term['term']}: {term['suggested_fix']}"
-                    elements.append(Paragraph(bullet_text, self.styles['BulletPoint']))
-                    elements.append(Spacer(1, 0.1*inch))
-        
+            elements.append(Paragraph("No missing protections identified.", self.styles['CustomBodyText']))
+
         return elements
-    
+
+
     def _build_page_3(self, result: Dict) -> List:
-        """Build page 3 content: Risk Category Breakdown"""
-        elements = []
-        
-        elements.append(Paragraph("Risk Category Breakdown", 
-                                 self.styles['SectionHeading']))
-        elements.append(Spacer(1, 0.15*inch))
-        
-        # Create table data
-        table_data = [
-            [
-                Paragraph('<b>Category</b>', self.styles['TableHeader']),
-                Paragraph('<b>Score</b>', self.styles['TableHeader']),
-                Paragraph('<b>Summary</b>', self.styles['TableHeader'])
-            ]
-        ]
-        
-        risk_breakdown = result['risk_analysis'].get('risk_breakdown', [])
+        """
+        Build page 3: Negotiation Points as a structured table
+        """
+        elements           = list()
+
+        elements.append(Paragraph("Negotiation Strategy", self.styles['SectionHeading']))
         
-        for category in risk_breakdown:
-            score_color = self._get_risk_color(category['score'])
+        negotiation_points = result.get('negotiation_points', [])
+
+        if negotiation_points:
+            # Prepare table data: Priority, Issue, Current Language, Proposed Language
+            table_data    = [[Paragraph('<b>Priority</b>', self.styles['TableHeader']),
+                              Paragraph('<b>Issue</b>', self.styles['TableHeader']),
+                              Paragraph('<b>Current</b>', self.styles['TableHeader']),
+                              Paragraph('<b>Proposed</b>', self.styles['TableHeader']),
+                            ]]
             
-            category_cell = Paragraph(category['category'], self.styles['BodyText'])
-            score_cell = Paragraph(
-                f'<font color="{score_color.hexval()}"><b>{category["score"]}</b></font>',
-                self.styles['TableHeader']
-            )
-            summary_cell = Paragraph(category['summary'], self.styles['BodyText'])
+            # Sort by priority
+            sorted_points = sorted(negotiation_points, key=lambda x: x.get('priority', 999))
+            
+            for point in sorted_points:
+                priority  = str(point.get('priority', 'N/A'))
+                issue     = Paragraph(point.get('issue', 'N/A'), self.styles['TableCell'])
+                current   = Paragraph(self._truncate_text(point.get('current_language', 'Not specified'), 100), self.styles['TableCell'])
+                proposed  = Paragraph(self._truncate_text(point.get('proposed_language', 'Request balanced language'), 100), self.styles['TableCell'])
+                
+                table_data.append([Paragraph(priority, self.styles['TableCell']), issue, current, proposed])
+
+            # Create the table with appropriate column widths
+            col_widths = [0.5*inch, 1.5*inch, 1.5*inch, 2*inch]
+            table      = Table(table_data, colWidths=col_widths)
             
-            table_data.append([category_cell, score_cell, summary_cell])
+            table.setStyle(TableStyle([('BACKGROUND', (0,0), (-1,0), colors.HexColor('#f5f5f5')),
+                                       ('TEXTCOLOR', (0,0), (-1,0), colors.HexColor('#1a1a1a')),
+                                       ('ALIGN', (0,0), (-1,-1), 'LEFT'),
+                                       ('FONTNAME', (0,0), (-1,0), 'Helvetica-Bold'),
+                                       ('FONTSIZE', (0,0), (-1,0), 10),
+                                       ('BOTTOMPADDING', (0,0), (-1,0), 12),
+                                       ('GRID', (0,0), (-1,-1), 1, colors.HexColor('#d1d5db')),
+                                       ('VALIGN', (0,0), (-1,-1), 'TOP'),
+                                       ('LEFTPADDING', (0,0), (-1,-1), 6),
+                                       ('RIGHTPADDING', (0,0), (-1,-1), 6),
+                                       ('TOPPADDING', (0,0), (-1,-1), 6),
+                                       ('BOTTOMPADDING', (0,0), (-1,-1), 6),
+                                     ])
+                          )
+
+            elements.append(table)
+
+        else:
+            elements.append(Paragraph("No negotiation points available.", self.styles['CustomBodyText']))
+
+        return elements
+
+    
+    def _build_page_4(self, result: Dict) -> List:
+        """
+        Build page 4: Risk Category Breakdown Table
+        """
+        elements       = list()
+
+        elements.append(Paragraph("Risk Category Breakdown", self.styles['SectionHeading']))
         
-        # Create table
-        table = Table(table_data, colWidths=[1.8*inch, 0.7*inch, 4*inch])
-        table.setStyle(TableStyle([
-            ('BACKGROUND', (0, 0), (-1, 0), colors.HexColor('#f5f5f5')),
-            ('TEXTCOLOR', (0, 0), (-1, 0), colors.HexColor('#1a1a1a')),
-            ('ALIGN', (0, 0), (-1, -1), 'LEFT'),
-            ('ALIGN', (1, 0), (1, -1), 'CENTER'),
-            ('FONTNAME', (0, 0), (-1, 0), 'Helvetica-Bold'),
-            ('FONTSIZE', (0, 0), (-1, -1), 10),
-            ('BOTTOMPADDING', (0, 0), (-1, 0), 12),
-            ('TOPPADDING', (0, 1), (-1, -1), 10),
-            ('BOTTOMPADDING', (0, 1), (-1, -1), 10),
-            ('GRID', (0, 0), (-1, -1), 0.5, colors.HexColor('#e5e5e5')),
-            ('VALIGN', (0, 0), (-1, -1), 'TOP'),
-        ]))
+        risk_breakdown = result.get('risk_analysis', {}).get('risk_breakdown', [])
         
-        elements.append(table)
+        if risk_breakdown:
+            # Prepare table data
+            table_data = [[Paragraph('<b>Category</b>', self.styles['TableHeader']),
+                            Paragraph('<b>Score</b>', self.styles['TableHeader']),
+                            Paragraph('<b>Summary</b>', self.styles['TableHeader']),
+                          ]]
+
+            for item in risk_breakdown:
+                category     = item.get('category', 'N/A').replace('_', ' ').title()
+                score        = item.get('score', 0)
+                summary      = item.get('summary', 'No summary available.')
+                score_color  = self._get_risk_color(score)
+                score_para   = Paragraph(f'<font color="{score_color.hexval()}">{score}/100</font>', self.styles['TableHeader'])
+                summary_para = Paragraph(summary, self.styles['TableCell'])
+                
+                table_data.append([Paragraph(category, self.styles['TableCell']), score_para, summary_para])
+
+            # Create table
+            col_widths = [2*inch, 1*inch, 3.5*inch] 
+            table      = Table(table_data, colWidths = col_widths)
+
+            # Table Style
+            table.setStyle(TableStyle([('BACKGROUND', (0, 0), (-1, 0), colors.HexColor('#f5f5f5')),
+                                       ('TEXTCOLOR', (0, 0), (-1, 0), colors.HexColor('#1a1a1a')),
+                                       ('ALIGN', (0, 0), (-1, -1), 'LEFT'),
+                                       ('ALIGN', (1, 0), (1, -1), 'CENTER'),
+                                       ('FONTNAME', (0, 0), (-1, 0), 'Helvetica-Bold'),
+                                       ('FONTSIZE', (0, 0), (-1, 0), 10),
+                                       ('BOTTOMPADDING', (0, 0), (-1, 0), 12),
+                                       ('TOPPADDING', (0, 1), (-1, -1), 8),
+                                       ('BOTTOMPADDING', (0, 1), (-1, -1), 8),
+                                       ('GRID', (0, 0), (-1, -1), 1, colors.HexColor('#d1d5db')),
+                                       ('VALIGN', (0, 0), (-1, -1), 'TOP'),
+                                     ])
+                          )
+
+            elements.append(table)
+
+        else:
+            elements.append(Paragraph("No risk breakdown data available.", self.styles['CustomBodyText']))
         
         return elements
-    
-    def _build_clause_analysis(self, analysis_result):
-        """Build clause analysis section with null safety"""
-        story = []
+
+
+    def _build_page_5(self, result: Dict) -> List:
+        """
+        Build page 5: Clause Interpretations
+        """
+        elements               = list()
+
+        elements.append(Paragraph("Clause Interpretations", self.styles['SectionHeading']))
         
+        clause_interpretations = result.get('clause_interpretations', [])
+
+        if clause_interpretations:
+            for i, clause in enumerate(clause_interpretations): 
+                ref           = clause.get('clause_reference', 'N/A')
+                plain_english = clause.get('plain_english_summary', 'No summary available.')
+                favorability  = clause.get('favorability', 'neutral')
+                
+                # Color code based on favorability
+                fav_color     = self._get_favorability_color(favorability)
+                
+                clause_text   = f"<b>{ref}</b> | <font color='{fav_color.hexval()}'>{favorability.upper()}</font><br/>{plain_english}"
+                
+                elements.append(Paragraph(clause_text, self.styles['BulletPoint']))
+                
+                # Add key points if available
+                key_points = clause.get('key_points', [])
+                if key_points:
+                    for point in key_points:  
+                        elements.append(Paragraph(f"• {point}", self.styles['SmallText']))
+                
+                elements.append(Spacer(1, 0.1*inch))
+                
+                # Break if we've added enough content: After 8 clauses, it's usually enough for one page
+                if i >= 7:  
+                    remaining = len(clause_interpretations) - 8
+                    if (remaining > 0):
+                        elements.append(Paragraph(f"... and {remaining} more clause interpretations", self.styles['SmallText']))
+                    break
+
+        else:
+            elements.append(Paragraph("No clause interpretations available.", self.styles['CustomBodyText']))
+
+        return elements
+
+
+    def _build_clause_analysis_pages(self, analysis_result):
+        """
+        Build dynamic pages for detailed clause-by-clause analysis
+        """
+        story   = list()
         clauses = analysis_result.get('clauses', [])
+
         if not clauses:
+            story.append(Paragraph("No clauses analyzed.", self.styles['CustomBodyText']))
             return story
-        
-        story.append(Paragraph("Clause-by-Clause Analysis", self.styles['Heading2']))
-        
-        for clause in clauses:
-            # Add null safety for clause reference
-            clause_ref = clause.get('reference')
-            if clause_ref is None:
-                clause_ref = "Unknown Reference"
-            
-            # Add null safety for category
-            clause_category = clause.get('category', 'Unknown Category')
-            
-            # Add null safety for text
-            clause_text = clause.get('text', 'No text available')
-            if clause_text is None:
-                clause_text = 'No text available'
+
+        story.append(Paragraph("Detailed Clause Analysis", self.styles['SectionHeading']))
+
+        for i, clause in enumerate(clauses):
+            # Use KeepTogether to ensure a clause block stays on one page if possible
+            clause_elements = list()
+
+            # Clause Reference and Category as Header
+            ref           = clause.get('reference', 'N/A')
+            category      = clause.get('category', 'N/A').replace('_', ' ').title()
+            confidence    = clause.get('confidence', 0)
+            risk_score    = clause.get('risk_score', 0)
             
-            # Add null safety for confidence
-            confidence = clause.get('confidence', 0)
-            if confidence is None:
-                confidence = 0
+            ref_cat_text  = f"{ref} • {category} | Confidence: {confidence:.1f} | Risk Score: {risk_score}"
+            clause_header = Paragraph(ref_cat_text, self.styles['SubSectionHeading'])
             
-            # Create table for this clause - use fixed widths instead of page_width
-            clause_data = [
-                [
-                    Paragraph(f"<b>{clause_ref} • {clause_category}</b>", self.styles['BodyText']),
-                    Paragraph(f"<b>{int(confidence * 100)}% confidence</b>", self.styles['BodyText'])
-                ],
-                [
-                    Paragraph(clause_text, self.styles['BodyText']),
-                    ''
-                ]
-            ]
+            clause_elements.append(clause_header)
+
+            # Original Clause Text
+            clause_text = clause.get('text', 'No text available.')
             
-            # Add risk indicators if present
-            risk_indicators = clause.get('risk_indicators', [])
-            if risk_indicators and any(risk_indicators):
-                clause_data.append([
-                    Paragraph(f"<b>Risk Indicators:</b> {', '.join([ri for ri in risk_indicators if ri])}", self.styles['SmallText']),
-                    ''
-                ])
+            # Truncate very long clause text
+            if len(clause_text) > 500:
+                clause_text = clause_text[:500] + "... [truncated]"
             
-            # Use fixed column widths instead of page_width
-            clause_table = Table(clause_data, colWidths=[400, 150])  # Fixed widths in points
-            clause_table.setStyle(TableStyle([
-                ('BACKGROUND', (0, 0), (-1, 0), colors.lightgrey),
-                ('VALIGN', (0, 0), (-1, -1), 'TOP'),
-                ('ALIGN', (1, 0), (1, 0), 'RIGHT'),
-                ('FONTNAME', (0, 0), (-1, 0), 'Helvetica-Bold'),
-                ('FONTSIZE', (0, 0), (-1, 0), 10),
-                ('ROWBACKGROUNDS', (0, 0), (-1, -1), [colors.white, colors.whitesmoke]),
-                ('GRID', (0, 0), (-1, -1), 0.5, colors.grey),
-                ('SPAN', (0, 1), (-1, 1)),  # Span the text across both columns
-            ]))
+            clause_para = Paragraph(f"<b>Original Text:</b> {clause_text}", self.styles['CustomBodyText'])
             
-            story.append(clause_table)
-            story.append(Spacer(1, 0.2 * inch))
-        
+            clause_elements.append(clause_para)
+
+            # Risk Indicators (if any)
+            risk_inds = clause.get('risk_indicators', [])
+            if risk_inds:
+                ri_text = f"<b>Risk Indicators:</b> {', '.join(risk_inds)}"
+                ri_para = Paragraph(ri_text, self.styles['RiskIndicator'])
+                
+                clause_elements.append(ri_para)
+
+            # Add Spacer between clauses
+            clause_elements.append(Spacer(1, 0.15 * inch))
+
+            # Wrap in KeepTogether
+            kt_flowable = KeepTogether(clause_elements)
+            story.append(kt_flowable)
+
+            # Add page break every 5 clauses to prevent overflow
+            if (i + 1) % 5 == 0 and (i + 1) < len(clauses):
+                story.append(PageBreak())
+
         return story
 
 
-def generate_pdf_report(analysis_result: Dict[str, Any], 
-                        output_path: Optional[str] = None) -> BytesIO:
+    def _get_severity_color(self, severity: str) -> colors.Color:
+        """
+        Get color based on severity level
+        """
+        severity = severity.lower()
+        if (severity == 'high'):
+            return colors.HexColor('#dc2626')
+
+        elif (severity == 'medium'):
+            return colors.HexColor('#f97316')
+
+        else:
+            return colors.HexColor('#16a34a')
+
+
+    def _get_importance_color(self, importance: str) -> colors.Color:
+        """
+        Get color based on importance level
+        """
+        importance = importance.lower()
+
+        if (importance == 'critical'):
+            return colors.HexColor('#dc2626')
+
+        elif (importance == 'high'):
+            return colors.HexColor('#f97316')
+
+        elif (importance == 'medium'):
+            return colors.HexColor('#ca8a04')
+
+        else:
+            return colors.HexColor('#16a34a')
+
+
+    def _get_favorability_color(self, favorability: str) -> colors.Color:
+        """
+        Get color based on favorability
+        """
+        favorability = favorability.lower()
+        if favorability == 'favorable':
+            return colors.HexColor('#16a34a')
+        elif favorability == 'unfavorable':
+            return colors.HexColor('#dc2626')
+        else:
+            return colors.HexColor('#ca8a04')
+
+
+    def _truncate_text(self, text: str, max_length: int) -> str:
+        """
+        Truncate text to specified length
+        """
+        if len(text) <= max_length:
+            return text
+        return text[:max_length-3] + "..."
+
+
+def generate_pdf_report(analysis_result: Dict[str, Any], output_path: Optional[str] = None) -> BytesIO:
     """
     Convenience function to generate PDF report
-    
-    Args:
-        analysis_result: Complete analysis result from the API
-        output_path: Optional file path to save PDF
-        
+
+    Arguments:
+    ----------
+        analysis_result { dict } : Complete analysis result from the API
+
+        output_path      { str } : Optional file path to save PDF
+
     Returns:
-        BytesIO buffer containing the PDF
+    --------
+              { BytesIO }        : Buffer containing the PDF
     """
     generator = PDFReportGenerator()
-    return generator.generate_report(analysis_result, output_path)
 
+    return generator.generate_report(analysis_result, output_path)

requirements.txt

@@ -1,32 +1,59 @@
-# FastAPI & Server
-fastapi==0.104.1
-uvicorn[standard]==0.24.0
-python-multipart==0.0.6
+# Core Dependencies
+fastapi>=0.104.1
+uvicorn[standard]>=0.24.0
+pydantic>=2.5.0
+pydantic-settings>=2.1.0
+python-multipart>=0.0.6
 
-# ML & NLP
-transformers==4.35.2
-torch==2.1.1
-sentence-transformers==2.2.2
-spacy
+# AI & NLP Libraries
+torch>=2.1.0
+transformers>=4.35.0
+sentence-transformers>=2.2.2
+tokenizers>=0.14.0
+safetensors>=0.4.0
+accelerate>=0.24.0  
 
-# Document Processing
-PyPDF2==3.0.1
-PyMuPDF==1.23.8
-python-docx==1.1.0
+# Data Processing & Math
+numpy>=1.24.0
+pandas>=2.1.0
+scipy>=1.11.0
 
+# Text Processing
+spacy>=3.7.0 
+
+# PDF Generation
+reportlab>=4.0.0
+Pillow>=10.0.0  
+
+# Document Processing 
+PyPDF2>=3.0.0 
+PyMuPDF>=1.23.0  
+python-docx>=1.1.0 
+
+# HTTP Requests
+requests>=2.31.0
 
 # LLM Providers
-openai>=1.3.0
-anthropic>=0.18.0
-requests==2.31.0
-Ollama
+openai>=1.0.0  
+anthropic>=0.5.0  
 
-# Data & Validation
-pydantic==2.5.0
-pydantic-settings==2.1.0
+# Text Processing Utilities
+chardet>=5.0.0  
+langdetect>=1.0.9  
 
 # Utilities
-python-dotenv==1.0.0
+tqdm>=4.66.0 
+python-dateutil>=2.8.0
+typing-extensions>=4.8.0 
 
-# PDF report generation
-reportlab>=4.0.0
+# Async Support 
+anyio>=3.7.0
+
+# OS Interaction
+psutil>=5.9.5 
+
+# Better JSON for numpy serialization
+orjson>=3.9.0
+
+# For spaCy performance
+blis>=0.7.10 

services/clause_extractor.py

@@ -9,8 +9,6 @@ from typing import Dict
 from typing import Tuple
 from pathlib import Path
 from typing import Optional
-from dataclasses import field
-from dataclasses import dataclass
 from collections import defaultdict
 from sentence_transformers import util
 
@@ -23,44 +21,9 @@ from config.risk_rules import RiskRules
 from config.risk_rules import ContractType
 from utils.text_processor import TextProcessor
 from utils.logger import ContractAnalyzerLogger
+from services.data_models import ExtractedClause
 from model_manager.model_loader import ModelLoader
-
-
-@dataclass
-class ExtractedClause:
-    """
-    Extracted clause with comprehensive metadata
-    """
-    text              : str
-    reference         : str    # e.g., "Section 5.2", "Clause 11.1"
-    category          : str    # e.g., "termination", "compensation", "indemnification"
-    confidence        : float  # 0.0-1.0
-    start_pos         : int
-    end_pos           : int
-    extraction_method : str    # "structural", "semantic", "hybrid"
-    risk_indicators   : List[str]            = field(default_factory = list)
-    embeddings        : Optional[np.ndarray] = None
-    subclauses        : List[str]            = field(default_factory = list)
-    legal_bert_score  : float                = 0.0
-    risk_score        : float                = 0.0  
-    
-    def to_dict(self) -> Dict[str, Any]:
-        """
-        Convert to dictionary for serialization
-        """
-        return {"text"              : self.text,
-                "reference"         : self.reference,
-                "category"          : self.category,
-                "confidence"        : round(self.confidence, 3),
-                "start_pos"         : self.start_pos,
-                "end_pos"           : self.end_pos,
-                "extraction_method" : self.extraction_method,
-                "risk_indicators"   : self.risk_indicators,
-                "subclauses"        : self.subclauses,
-                "legal_bert_score"  : round(self.legal_bert_score, 3),
-                "risk_score"        : round(self.risk_score, 3),
-               }
-
+from services.data_models import ClauseInterpretation
 
 
 class ComprehensiveClauseExtractor:
@@ -140,12 +103,6 @@ class ComprehensiveClauseExtractor:
                                                    }
                         }
     
-    # RISK INDICATOR PATTERNS - ENHANCED
-    RISK_INDICATORS   = {'critical' : ['unlimited liability', 'perpetual', 'irrevocable', 'forfeit', 'liquidated damages', 'wage withholding', 'joint and several', 'automatic renewal', 'assignment without consent'],
-                         'high'     : ['non-compete', 'non-solicit', 'penalty', 'without cause', 'sole discretion', 'immediate termination', 'at-will', 'indemnify', 'hold harmless', 'waive'],
-                         'medium'   : ['confidential', 'proprietary', 'exclusive', 'terminate', 'default', 'breach', 'damages', 'liable', 'warranty disclaimer'],
-                        }
-    
 
     def __init__(self, model_loader: ModelLoader):
         """
@@ -174,6 +131,9 @@ class ComprehensiveClauseExtractor:
         
         # Lazy load
         self._lazy_load()
+
+        # Risk Rules 
+        self.risk_rules           = RiskRules()
     
 
     def _lazy_load(self):
@@ -288,6 +248,109 @@ class ComprehensiveClauseExtractor:
         
         return final_clauses
     
+
+    def generate_clause_analysis(self, clause: ExtractedClause, llm_interpretation: ClauseInterpretation = None) -> Dict[str, str]:
+        """
+        Generate analysis and recommendation for a clause
+        
+        Arguments:
+        ----------
+            clause               { ExtractedClause }    : ExtractedClause object
+
+            llm_interpretation { ClauseInterpretation } : Optional ClauseInterpretation from LLM
+        
+        Returns:
+        --------
+                           { dict }                     : Dictionary with 'analysis' and 'recommendation' keys
+        """
+        if llm_interpretation:
+            # Use LLM interpretation if available
+            analysis = llm_interpretation.plain_english_summary
+            
+            # Combine key points into analysis
+            if llm_interpretation.key_points:
+                analysis += " " + " ".join(llm_interpretation.key_points[:2])
+            
+            # Combine potential risks into analysis
+            if llm_interpretation.potential_risks:
+                risk_text = " Key risks: " + ", ".join(llm_interpretation.potential_risks[:2])
+                analysis += risk_text
+            
+            # Use suggested improvements as recommendation
+            if llm_interpretation.suggested_improvements:
+                recommendation = " ".join(llm_interpretation.suggested_improvements[:2])
+            
+            else:
+                recommendation = "Review this clause with legal counsel for specific recommendations."
+        
+        else:
+            # Fallback: Generate analysis from risk indicators and category
+            risk_indicators = clause.risk_indicators if clause.risk_indicators else []
+            risk_score      = getattr(clause, 'risk_score', 0)
+            
+            # Generate specific analysis based on category and risk
+            analysis        = self._generate_fallback_analysis(clause          = clause, 
+                                                               risk_indicators = risk_indicators, 
+                                                               risk_score      = risk_score,
+                                                              )
+
+            recommendation  = self._generate_fallback_recommendation(clause          = clause, 
+                                                                     risk_indicators = risk_indicators, 
+                                                                     risk_score      = risk_score,
+                                                                    )
+        
+        return {'analysis'       : analysis,
+                'recommendation' : recommendation,
+               }
+
+
+    def _generate_fallback_analysis(self, clause: ExtractedClause, risk_indicators: List[str], risk_score: float) -> str:
+        """
+        Generate fallback analysis when LLM unavailable
+        """
+        category_analyses = {'compensation'          : f"This compensation clause {'contains concerning terms' if risk_score > 50 else 'appears standard'} regarding payment obligations and structures. ",
+                             'termination'           : f"This termination clause {'creates significant imbalance' if risk_score > 60 else 'establishes'} the conditions and procedures for ending the agreement. ",
+                             'non_compete'           : f"This restrictive covenant {'is overly broad and' if risk_score > 60 else ''} limits future business activities and employment opportunities. ",
+                             'confidentiality'       : f"This confidentiality provision {'has excessive scope' if risk_score > 50 else 'defines'} the obligations to protect sensitive information. ",
+                             'indemnification'       : f"This indemnification clause {'creates one-sided liability exposure' if risk_score > 60 else 'allocates'} responsibility for claims and losses. ",
+                             'intellectual_property' : f"This IP clause {'may claim overly broad ownership' if risk_score > 50 else 'addresses'} rights to work product and inventions. ",
+                             'liability'             : f"This liability provision {'lacks adequate caps or limitations' if risk_score > 60 else 'establishes'} the financial exposure for damages. ",
+                            }
+        
+        analysis          = category_analyses.get(clause.category, f"This {clause.category} clause establishes specific rights and obligations. ")
+        
+        # Add risk-specific details
+        if risk_indicators:
+            analysis += f"Specific concerns include: {', '.join(risk_indicators[:3])}. "
+        
+        if (risk_score > 70):
+            analysis += "This clause requires immediate attention and likely modification."
+
+        elif (risk_score > 50):
+            analysis += "This clause should be reviewed carefully and potentially negotiated."
+
+        else:
+            analysis += "This clause appears to contain standard provisions for this type of agreement."
+        
+        return analysis
+
+
+    def _generate_fallback_recommendation(self, clause: ExtractedClause, risk_indicators: List[str], risk_score: float) -> str:
+        """
+        Generate fallback recommendation when LLM unavailable
+        """
+        if (risk_score > 70):
+            return f"Strongly recommend negotiating substantial changes to this clause. Seek legal counsel to address the identified risks and ensure your interests are protected."
+        
+        elif (risk_score > 50):
+            return f"Negotiate modifications to balance the terms more fairly. Consider adding protective language or limiting the scope of obligations."
+        
+        elif (risk_score > 30):
+            return f"Review with legal counsel to ensure the terms are clear and acceptable. Minor clarifications may be beneficial."
+        
+        else:
+            return f"Standard clause - review for consistency with the overall agreement and your business needs."
+
     
     def _extract_structural_clauses(self, text: str) -> List[Dict]:
         """
@@ -584,17 +647,42 @@ class ComprehensiveClauseExtractor:
 
     def _extract_risk_indicators(self, text: str) -> List[str]:
         """
-        Extract risk indicator keywords from clause text
+        Extract risk indicator keywords from clause text using RiskRule with the central risk rules
         """
         text_lower      = text.lower()
         risk_indicators = list()
+
+        # Check for matches against CRITICAL_KEYWORDS from RiskRules
+        for keyword in self.risk_rules.CRITICAL_KEYWORDS.keys():
+            if keyword in text_lower:
+                risk_indicators.append(keyword)
+
+        # Check for matches against HIGH_RISK_KEYWORDS from RiskRules
+        for keyword in self.risk_rules.HIGH_RISK_KEYWORDS.keys():
+            if keyword in text_lower:
+                risk_indicators.append(keyword)
+
+        # Check for matches against MEDIUM_RISK_KEYWORDS from RiskRules
+        for keyword in self.risk_rules.MEDIUM_RISK_KEYWORDS.keys():
+            if keyword in text_lower:
+                risk_indicators.append(keyword)
+
+        # Check for matches against RISKY_PATTERNS from RiskRules
+        for pattern, score, description in self.risk_rules.RISKY_PATTERNS:
+            if re.search(pattern, text_lower):
+                # Use the description from RiskRules as the indicator
+                risk_indicators.append(description)
+
+        # Remove duplicates while preserving order
+        seen              = set()
+        unique_indicators = list()
+
+        for indicator in risk_indicators:
+            if indicator not in seen:
+                seen.add(indicator)
+                unique_indicators.append(indicator)
         
-        for severity, indicators in self.RISK_INDICATORS.items():
-            for indicator in indicators:
-                if indicator in text_lower:
-                    risk_indicators.append(indicator)
-        
-        return risk_indicators  
+        return unique_indicators
     
 
     def _extract_subclauses(self, text: str) -> List[str]:
@@ -699,8 +787,7 @@ class ComprehensiveClauseExtractor:
 
 class RiskClauseExtractor:
     """
-    Risk-Focused Clause Extractor: Specifically for risk analysis using RiskRules framework and integrates with
-    risk_rules.py for contract-type specific risk assessment
+    Risk-Focused Clause Extractor: Specifically for risk analysis using RiskRules framework for contract-type specific risk assessment
     
     This will be used for: Risk analysis, protection gap detection, contract-type specific assessment
     """
@@ -955,7 +1042,7 @@ class RiskClauseExtractor:
         Calculate risk scores for clauses based on RiskRules factors
         """
         for clause in clauses:
-            risk_score        = self._calculate_single_clause_risk(clause)
+            risk_score        = self._calculate_single_clause_risk(clause = clause)
             clause.risk_score = risk_score
         
         return clauses
@@ -963,29 +1050,35 @@ class RiskClauseExtractor:
 
     def _calculate_single_clause_risk(self, clause: ExtractedClause) -> float:
         """
-        Calculate risk score for a single clause
+        Calculate risk score using RiskRules framework
         """
-        base_risk       = 0.0
-        
-        # Base risk from category weight
+        base_score      = 0.0
+        text_lower      = clause.text.lower()
+
+        # Base risk from category weight (adjusted for contract type)
         category_weight = self.category_weights.get(clause.category, 1.0)
+        base_score     += category_weight  
 
-        # Normalize to 0-40
-        base_risk      += (category_weight / 15) * 40  
+        # Add risk from CLAUSE_RISK_FACTORS (red flags)
+        factor_config   = self.risk_rules.CLAUSE_RISK_FACTORS.get(clause.category)
         
-        # Risk from indicators
-        risk_indicators = self._extract_risk_indicators(clause.text)
+        if factor_config:
+            for red_flag, adjustment in factor_config["red_flags"].items():
+                if red_flag in text_lower:
+                    base_score += adjustment
 
-        # 8 points per indicator
-        indicator_risk  = len(risk_indicators) * 8  
-        base_risk      += min(indicator_risk, 40)
-        
-        # Risk from patterns
-        pattern_risk    = self._check_risk_patterns(clause.text)
-        base_risk      += pattern_risk
-        
-        # Cap at 100
-        return min(base_risk, 100) 
+        # Add risk from RISKY_PATTERNS (with actual scores)
+        for pattern, score, description in self.risk_rules.RISKY_PATTERNS:
+            if re.search(pattern, text_lower):
+                base_score += score
+
+        # Add risk from CRITICAL_KEYWORDS
+        for keyword, risk_score in self.risk_rules.CRITICAL_KEYWORDS.items():
+            if re.search(rf'\b{re.escape(keyword)}\b', text_lower):
+                base_score += risk_score
+
+        # Cap final score at 100
+        return min(max(base_score, 0), 100)
     
 
     def _extract_risk_indicators(self, text: str) -> List[str]:

services/contract_classifier.py

@@ -21,31 +21,7 @@ from config.risk_rules import ContractType
 from config.model_config import ModelConfig
 from utils.text_processor import TextProcessor
 from utils.logger import ContractAnalyzerLogger
-
-
-@dataclass
-class ContractCategory:
-    """
-    Contract classification result with metadata
-    """
-    category               : str
-    subcategory            : Optional[str]
-    confidence             : float
-    reasoning              : List[str]
-    detected_keywords      : List[str]
-    alternative_categories : List[Tuple[str, float]] = None  # (category, confidence) pairs
-    
-    def to_dict(self) -> Dict[str, Any]:
-        """
-        Convert to dictionary for serialization
-        """
-        return {"category"               : self.category,
-                "subcategory"            : self.subcategory,
-                "confidence"             : round(self.confidence, 3),
-                "reasoning"              : self.reasoning,
-                "detected_keywords"      : self.detected_keywords,
-                "alternative_categories" : [{"category": cat, "confidence": round(conf, 3)} for cat, conf in (self.alternative_categories or [])]
-               }
+from services.data_models import ContractCategory
 
 
 class ContractClassifier:
@@ -59,15 +35,15 @@ class ContractClassifier:
     # CATEGORY HIERARCHY WITH KEYWORDS - UPDATED TO MATCH YOUR CATEGORIES
     CATEGORY_HIERARCHY   = {'employment'            : {'subcategories' : ['full_time', 'part_time', 'contract_worker', 'internship', 'executive'],
                                                        'keywords'      : ['employee', 'employment', 'employer', 'job', 'position', 'staff', 'salary', 'wages', 'compensation', 'payroll', 'benefits', 'health insurance', 'retirement', 'pension', '401(k)', 'vacation', 'paid time off', 'sick leave', 'holidays', 'probation', 'performance review', 'promotion', 'termination', 'job description', 'duties', 'responsibilities', 'work hours', 'overtime', 'timekeeping', 'attendance', 'confidentiality', 'non-compete', 'non-solicitation', 'intellectual property', 'inventions', 'work product', 'severance', 'notice period', 'resignation', 'dismissal'],
-                                                       'weight'        : 1.2,
+                                                       'weight'        : 1.1,
                                                       },
                             'consulting'            : {'subcategories' : ['independent_contractor', 'advisory', 'professional_services', 'freelance'],
                                                        'keywords'      : ['consultant', 'consulting', 'independent contractor', 'statement of work', 'deliverables', 'professional services', 'hourly rate', 'project scope', 'milestone', 'acceptance criteria', 'work product', '1099', 'self-employed', 'contractor', 'consulting services', 'expert advice', 'advisory services', 'project basis', 'task order'],
-                                                       'weight'        : 1.1,
+                                                       'weight'        : 1.0,
                                                       },
                             'nda'                   : {'subcategories' : ['mutual_nda', 'unilateral_nda', 'confidentiality_agreement'],
                                                        'keywords'      : ['non-disclosure', 'confidentiality', 'proprietary information', 'nda', 'disclosure agreement', 'trade secret', 'confidential information', 'receiving party', 'disclosing party', 'confidentiality obligation', 'non-use', 'non-circumvention', 'secrecy', 'protected information', 'confidentiality period', 'return of information'],
-                                                       'weight'        : 1.3, 
+                                                       'weight'        : 1.0, 
                                                       },
                             'software'              : {'subcategories' : ['software_license', 'saas', 'cloud_services', 'development', 'api_access'],
                                                        'keywords'      : ['software', 'license', 'saas', 'subscription', 'source code', 'object code', 'api', 'cloud', 'hosting', 'maintenance', 'updates', 'support', 'uptime', 'service level', 'software as a service', 'platform', 'application', 'user license', 'perpetual license', 'subscription fee', 'end user license agreement', 'eula'],
@@ -314,7 +290,6 @@ class ContractClassifier:
 
             { ContractCategory }     : ContractCategory object with classification results
         """
-        
         # Validate input
         if (not contract_text or (len(contract_text) < 100)):
             raise ValueError("Contract text too short for classification")
@@ -331,16 +306,16 @@ class ContractClassifier:
                  excerpt_length = len(text_excerpt),
                 )
         
-        # Step 1: Keyword scoring
+        # Keyword scoring
         keyword_scores    = self._score_keywords(text_lower = contract_text.lower())
-        
+
         # Semantic similarity
         semantic_scores   = self._semantic_similarity(text = text_excerpt)
-        
-        # Step 3: Legal-BERT semantic similarity (enhanced)
+
+        # Legal-BERT semantic similarity (enhanced)
         legal_bert_scores = self._legal_bert_similarity(text = text_excerpt)
-        
-        # Step 4: Combine scores (weighted average)
+
+        # Combine scores (weighted average)
         combined_scores   = self._combine_scores(keyword_scores    = keyword_scores,
                                                  semantic_scores   = semantic_scores,
                                                  legal_bert_scores = legal_bert_scores,
@@ -403,23 +378,23 @@ class ContractClassifier:
     def _score_keywords(self, text_lower: str) -> Dict[str, float]:
         """
         Score each category based on keyword presence
-        
+
         Arguments:
         ----------
             text_lower { str } : Lowercase contract text
-        
+
         Returns:
         --------
                { dict }        : Dictionary of {category: score}
         """
         scores = dict()
-        
         for category, config in self.CATEGORY_HIERARCHY.items():
-            keywords         = config['keywords']
-            weight           = config['weight']
+            keywords      = config['keywords']
+            weight        = config['weight']
             
             # Count keyword matches with partial matching for multi-word terms
-            keyword_count    = 0
+            keyword_count = 0
+            
             for keyword in keywords:
                 # Check for exact match or partial match for multi-word terms
                 if ' ' in keyword:
@@ -429,18 +404,15 @@ class ContractClassifier:
                         keyword_count += 1
                 
                 else:
-                    # For single words, exact match
+                    # For single words, exact word boundary match
                     if re.search(rf'\b{re.escape(keyword)}\b', text_lower):
                         keyword_count += 1
-            
+
             # Normalize by number of keywords and apply weight
             normalized_score = (keyword_count / len(keywords)) * weight
             
-            # Boost score if we have significant keyword matches
-            if keyword_count >= 3:
-                normalized_score *= 1.2
-            
-            scores[category] = min(normalized_score, 1.0)  # Cap at 1.0
+            # Cap at 1.0
+            scores[category] = min(normalized_score, 1.0)
         
         return scores
     
@@ -548,9 +520,9 @@ class ContractClassifier:
         combined          = dict()
         
         # Weights for each method
-        keyword_weight    = 0.45  # Increased from 0.30
-        semantic_weight   = 0.35  # Reduced from 0.40
-        legal_bert_weight = 0.20  # Reduced from 0.30
+        keyword_weight    = 0.35  
+        semantic_weight   = 0.35 
+        legal_bert_weight = 0.30 
         
         for category in self.CATEGORY_HIERARCHY.keys():
             score = (keyword_scores.get(category, 0) * keyword_weight + 

services/data_models.py

@@ -0,0 +1,409 @@
+# DEPENDENCIES
+import sys
+import numpy as np
+from enum import Enum
+from typing import Any
+from typing import Dict
+from typing import List
+from typing import Tuple
+from pathlib import Path
+from typing import Optional
+from dataclasses import field
+from dataclasses import dataclass
+
+# Add parent directory to path for imports
+sys.path.append(str(Path(__file__).parent.parent))
+
+
+
+
+@dataclass
+class ExtractedClause:
+    """
+    Extracted clause with comprehensive metadata
+    """
+    text              : str
+    reference         : str    # e.g., "Section 5.2", "Clause 11.1"
+    category          : str    # e.g., "termination", "compensation", "indemnification"
+    confidence        : float  # 0.0-1.0
+    start_pos         : int
+    end_pos           : int
+    extraction_method : str    # "structural", "semantic", "hybrid"
+    risk_indicators   : List[str]            = field(default_factory = list)
+    embeddings        : Optional[np.ndarray] = None
+    subclauses        : List[str]            = field(default_factory = list)
+    legal_bert_score  : float                = 0.0
+    risk_score        : float                = 0.0  
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert to dictionary for serialization
+        """
+        return {"text"              : self.text,
+                "reference"         : self.reference,
+                "category"          : self.category,
+                "confidence"        : round(self.confidence, 3),
+                "start_pos"         : self.start_pos,
+                "end_pos"           : self.end_pos,
+                "extraction_method" : self.extraction_method,
+                "risk_indicators"   : self.risk_indicators,
+                "subclauses"        : self.subclauses,
+                "legal_bert_score"  : round(self.legal_bert_score, 3),
+                "risk_score"        : round(self.risk_score, 3),
+               }
+
+
+@dataclass
+class UnfavorableTerm:
+    """
+    Detected unfavorable term with comprehensive risk analysis
+    """
+    term             : str
+    category         : str    # Risk category (e.g., "restrictive_covenants")
+    severity         : str    # "critical", "high", "medium", "low"
+    explanation      : str
+    risk_score       : float  # 0-100 risk score
+    clause_reference : Optional[str] = None
+    suggested_fix    : Optional[str] = None
+    contract_type    : Optional[str] = None
+    specific_text    : Optional[str] = None
+    benchmark_info   : Optional[str] = None  # Industry benchmark comparison
+    legal_basis      : Optional[str] = None  # Legal principle violated
+    
+    def to_dict(self) -> Dict:
+        """
+        Convert to dictionary
+        """
+        return {"term"             : self.term,
+                "category"         : self.category,
+                "severity"         : self.severity,
+                "explanation"      : self.explanation,
+                "risk_score"       : round(self.risk_score, 2),
+                "clause_reference" : self.clause_reference,
+                "suggested_fix"    : self.suggested_fix,
+                "contract_type"    : self.contract_type,
+                "specific_text"    : self.specific_text,
+                "benchmark_info"   : self.benchmark_info,
+                "legal_basis"      : self.legal_basis,
+               }
+
+
+@dataclass
+class ClauseInterpretation:
+    """
+    LLM interpretation of a clause with comprehensive analysis
+    """
+    clause_reference       : str  
+    original_text          : str  
+    plain_english_summary  : str
+    key_points             : List[str]
+    potential_risks        : List[str]
+    suggested_improvements : List[str]
+    favorability           : str = "neutral"  
+    confidence_score       : float = 0.0
+    risk_level             : str = "unknown"
+    negotiation_priority   : str = "medium"  
+    legal_precedents       : List[str]      = field(default_factory = list)
+    negotiation_leverage   : List[str]      = field(default_factory = list)
+    market_comparison      : Optional[str]  = None
+    risk_score             : float          = 0.0
+    
+    def to_dict(self) -> Dict[str, Any]:
+       
+        return {"clause_reference"       : self.clause_reference,
+                "original_text"          : self.original_text,
+                "plain_english_summary"  : self.plain_english_summary,
+                "key_points"             : self.key_points,
+                "potential_risks"        : self.potential_risks,
+                "suggested_improvements" : self.suggested_improvements,
+                "favorability"           : self.favorability,
+                "confidence_score"       : round(self.confidence_score, 3),
+                "risk_level"             : self.risk_level,
+                "negotiation_priority"   : self.negotiation_priority,
+                "legal_precedents"       : self.legal_precedents,
+                "negotiation_leverage"   : self.negotiation_leverage,
+                "market_comparison"      : self.market_comparison,
+                "risk_score"             : round(self.risk_score, 3),
+               }
+
+
+@dataclass
+class MissingProtection:
+    """
+    Missing protection item with comprehensive risk analysis
+    """
+    protection_id      : str    # Internal identifier
+    protection         : str
+    importance         : str    # "critical", "high", "medium", "low"
+    risk_score         : float  # 0-100 from risk_rules
+    explanation        : str
+    recommendation     : str
+    categories         : List[str]
+    contract_type      : Optional[str]       = None
+    suggested_language : Optional[str]       = None
+    legal_basis        : Optional[str]       = None
+    affected_clauses   : Optional[List[str]] = None
+
+    def to_dict(self) -> Dict:
+        """
+        Convert to dictionary
+        """
+        return {"protection_id"      : self.protection_id,  
+                "protection"         : self.protection,
+                "importance"         : self.importance,
+                "risk_score"         : round(self.risk_score, 2),
+                "explanation"        : self.explanation,
+                "recommendation"     : self.recommendation,
+                "categories"         : self.categories,
+                "contract_type"      : self.contract_type,
+                "suggested_language" : self.suggested_language,
+                "legal_basis"        : self.legal_basis,
+                "affected_clauses"   : self.affected_clauses or [],
+               }
+
+
+@dataclass
+class ContractCategory:
+    """
+    Contract classification result with metadata
+    """
+    category               : str
+    subcategory            : Optional[str]
+    confidence             : float
+    reasoning              : List[str]
+    detected_keywords      : List[str]
+    alternative_categories : List[Tuple[str, float]] = None  # (category, confidence) pairs
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert to dictionary for serialization
+        """
+        return {"category"               : self.category,
+                "subcategory"            : self.subcategory,
+                "confidence"             : round(self.confidence, 3),
+                "reasoning"              : self.reasoning,
+                "detected_keywords"      : self.detected_keywords,
+                "alternative_categories" : [{"category": cat, "confidence": round(conf, 3)} for cat, conf in (self.alternative_categories or [])]
+               }
+
+
+
+@dataclass
+class RiskBreakdownItem:
+    """
+    Individual risk category breakdown
+    """
+    category : str
+    score    : int  # 0-100
+    summary  : str
+    findings : List[str] = field(default_factory = list)
+    
+
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert to dictionary
+        """
+        return {"category" : self.category,
+                "score"    : self.score,
+                "summary"  : self.summary,
+                "findings" : self.findings,
+               }
+
+
+@dataclass
+class RiskScore:
+    """
+    Comprehensive risk score with detailed breakdown
+    """
+    overall_score        : int  # 0-100 
+    risk_level           : str  # "CRITICAL", "HIGH", "MEDIUM", "LOW"
+    category_scores      : Dict[str, int] 
+    risk_factors         : List[str] 
+    detailed_findings    : Dict[str, List[str]] 
+    benchmark_comparison : Dict[str, str] 
+    risk_breakdown       : List[RiskBreakdownItem]
+    contract_type        : str
+    unfavorable_terms    : List[Dict] 
+    missing_protections  : List[Dict] 
+    high_risk_clauses    : List[Dict]               = field(default_factory = list) 
+    explanation          : str                      = "" 
+    recommendations      : List[str]                = field(default_factory = list) 
+    analysis_timestamp   : Optional[str]            = None 
+    contract_subtype     : Optional[str]            = None 
+    contract_metadata    : Optional[Dict[str, Any]] = field(default_factory = dict) 
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert to dictionary for serialization
+        """
+        return {"overall_score"        : self.overall_score,
+                "risk_level"           : self.risk_level,
+                "category_scores"      : self.category_scores,
+                "risk_factors"         : self.risk_factors, 
+                "detailed_findings"    : self.detailed_findings, 
+                "benchmark_comparison" : self.benchmark_comparison, 
+                "risk_breakdown"       : [item.to_dict() for item in self.risk_breakdown],
+                "contract_type"        : self.contract_type,
+                "unfavorable_terms"    : self.unfavorable_terms, 
+                "missing_protections"  : self.missing_protections, 
+                "high_risk_clauses"    : self.high_risk_clauses,
+                "explanation"          : self.explanation,
+                "recommendations"      : self.recommendations,
+                "analysis_timestamp"   : self.analysis_timestamp,
+                "contract_subtype"     : self.contract_subtype,
+                "contract_metadata"    : self.contract_metadata,
+               }
+
+
+@dataclass
+class RiskInterpretation:
+    """
+    Comprehensive risk interpretation with LLM-enhanced explanations
+    """
+    overall_risk_explanation : str
+    key_concerns             : List[str]
+    negotiation_strategy     : str
+    market_comparison        : str
+    clause_interpretations   : List[ClauseInterpretation]
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert to dictionary
+        """
+        return {"overall_risk_explanation" : self.overall_risk_explanation,
+                "key_concerns"             : self.key_concerns,
+                "negotiation_strategy"     : self.negotiation_strategy,
+                "market_comparison"        : self.market_comparison,
+                "clause_interpretations"   : [ci.to_dict() for ci in self.clause_interpretations],
+               }
+
+
+class NegotiationTactic(Enum):
+    """
+    Types of negotiation tactics
+    """
+    REMOVAL       = "removal"
+    MODIFICATION  = "modification" 
+    ADDITION      = "addition"
+    LIMITATION    = "limitation"
+    MUTUALIZATION = "mutualization"
+    CLARIFICATION = "clarification"
+    
+
+@dataclass
+class NegotiationPoint:
+    """
+    Negotiation talking point with strategic context
+    """
+    priority              : int  # 1 = highest, 5 = lowest
+    category              : str
+    issue                 : str
+    current_language      : str
+    proposed_language     : str
+    rationale             : str
+    tactic                : NegotiationTactic
+    fallback_position     : Optional[str] = None
+    estimated_difficulty  : str           = "medium"  # "easy", "medium", "hard"
+    legal_basis           : Optional[str] = None
+    business_impact       : Optional[str] = None
+    counterparty_concerns : Optional[str] = None
+    timing_suggestion     : Optional[str] = None
+    bargaining_chips      : List[str]     = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert to dictionary
+        """
+        return {"priority"              : self.priority,
+                "category"              : self.category,
+                "issue"                 : self.issue,
+                "current_language"      : self.current_language,
+                "proposed_language"     : self.proposed_language,
+                "rationale"             : self.rationale,
+                "tactic"                : self.tactic.value,
+                "fallback_position"     : self.fallback_position,
+                "estimated_difficulty"  : self.estimated_difficulty,
+                "legal_basis"           : self.legal_basis,
+                "business_impact"       : self.business_impact,
+                "counterparty_concerns" : self.counterparty_concerns,
+                "timing_suggestion"     : self.timing_suggestion,
+                "bargaining_chips"      : self.bargaining_chips or [],
+               }
+
+
+@dataclass
+class NegotiationPlaybook:
+    """
+    Comprehensive negotiation strategy
+    """
+    overall_strategy     : str
+    critical_points      : List[NegotiationPoint]
+    walk_away_items      : List[str]
+    concession_items     : List[str]
+    timing_guidance      : str
+    risk_mitigation_plan : str
+
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert to dictionary
+        """
+        return {"overall_strategy"     : self.overall_strategy,
+                "critical_points"      : [point.to_dict() for point in self.critical_points],
+                "walk_away_items"      : self.walk_away_items,
+                "concession_items"     : self.concession_items,
+                "timing_guidance"      : self.timing_guidance,
+                "risk_mitigation_plan" : self.risk_mitigation_plan,
+               }
+
+
+@dataclass
+class SummaryContext:
+    """
+    Context data for comprehensive summary generation
+    """
+    contract_type         : str
+    risk_score            : int
+    risk_level            : str
+    category_scores       : Dict[str, int]
+    unfavorable_terms     : List[Dict]
+    missing_protections   : List[Dict]
+    clauses               : List
+    key_findings          : List[str]
+    risk_interpretation   : Optional[RiskInterpretation]  = None
+    negotiation_playbook  : Optional[NegotiationPlaybook] = None
+    contract_text_preview : Optional[str]                 = None
+    contract_metadata     : Optional[Dict[str, Any]]      = None
+
+
+@dataclass 
+class ModelInfo:
+    """
+    Model metadata and state
+    """
+    name           : str
+    type           : str  # "legal-bert", "embedding", "tokenizer", "classifier"
+    status         : str  # "not_loaded", "loading", "loaded", "error"
+    model          : Optional[Any]      = None
+    tokenizer      : Optional[Any]      = None
+    loaded_at      : Optional[str]      = None
+    error_message  : Optional[str]      = None
+    memory_size_mb : float              = 0.0
+    access_count   : int                = 0
+    last_accessed  : Optional[str]      = None
+    metadata       : Dict[str, Any]     = field(default_factory = dict)
+    
+
+    def mark_accessed(self):
+        """
+        Update access statistics
+        """
+        self.access_count += 1
+        # Simple timestamp 
+        self.last_accessed = "now"
+    
+
+    def get_age_seconds(self) -> float:
+        """
+        Get seconds since last access (simplified)
+        """
+        return 0.0 if not self.last_accessed else 3600.0

services/llm_interpreter.py

@@ -7,7 +7,6 @@ from typing import Dict
 from typing import Tuple
 from pathlib import Path
 from typing import Optional
-from dataclasses import dataclass
 
 # Add parent directory to path for imports
 sys.path.append(str(Path(__file__).parent.parent))
@@ -18,69 +17,14 @@ from config.risk_rules import RiskRules
 from config.risk_rules import ContractType
 from utils.logger import ContractAnalyzerLogger
 from model_manager.llm_manager import LLMManager
+from services.data_models import UnfavorableTerm
 from model_manager.llm_manager import LLMProvider
-from services.term_analyzer import UnfavorableTerm
+from services.data_models import RiskInterpretation
+from services.data_models import ClauseInterpretation
 from services.clause_extractor import ExtractedClause
 from services.protection_checker import MissingProtection
 
 
-
-@dataclass
-class ClauseInterpretation:
-    """
-    Plain-English interpretation of a legal clause with risk context
-    """
-    clause_reference       : str
-    original_text          : str
-    plain_english_summary  : str
-    key_points             : List[str]
-    potential_risks        : List[str]
-    favorability           : str       # "favorable", "neutral", "unfavorable"
-    confidence             : float
-    risk_score             : float     # 0-100 from RiskAnalyzer
-    negotiation_priority   : str       # "high", "medium", "low"
-    suggested_improvements : List[str]
-    
-    def to_dict(self) -> Dict[str, Any]:
-        """
-        Convert to dictionary
-        """
-        return {"clause_reference"       : self.clause_reference,
-                "original_text"          : self.original_text,
-                "plain_english_summary"  : self.plain_english_summary,
-                "key_points"             : self.key_points,
-                "potential_risks"        : self.potential_risks,
-                "favorability"           : self.favorability,
-                "confidence"             : round(self.confidence, 3),
-                "risk_score"             : round(self.risk_score, 2),
-                "negotiation_priority"   : self.negotiation_priority,
-                "suggested_improvements" : self.suggested_improvements,
-               }
-
-
-@dataclass
-class RiskInterpretation:
-    """
-    Comprehensive risk interpretation with LLM-enhanced explanations
-    """
-    overall_risk_explanation : str
-    key_concerns             : List[str]
-    negotiation_strategy     : str
-    market_comparison        : str
-    clause_interpretations   : List[ClauseInterpretation]
-    
-    def to_dict(self) -> Dict[str, Any]:
-        """
-        Convert to dictionary
-        """
-        return {"overall_risk_explanation" : self.overall_risk_explanation,
-                "key_concerns"             : self.key_concerns,
-                "negotiation_strategy"     : self.negotiation_strategy,
-                "market_comparison"        : self.market_comparison,
-                "clause_interpretations"   : [ci.to_dict() for ci in self.clause_interpretations],
-               }
-
-
 class LLMClauseInterpreter:
     """
     Uses LLM to generate plain-English explanations for legal clauses and integrated with RiskAnalyzer results and RiskRules framework
@@ -92,7 +36,6 @@ class LLMClauseInterpreter:
         Arguments:
         ----------
             llm_manager      { LLMManager }  : LLMManager instance
-
             default_provider { LLMProvider } : Default LLM provider to use
         """
         self.llm_manager      = llm_manager
@@ -293,7 +236,7 @@ class LLMClauseInterpreter:
                                                         key_points             = result.get("key_points", []),
                                                         potential_risks        = result.get("potential_risks", []),
                                                         favorability           = result.get("favorability", "neutral"),
-                                                        confidence             = 0.85,  # High confidence if LLM succeeded
+                                                        confidence_score       = 0.85,  # High confidence if LLM succeeded
                                                         risk_score             = getattr(clause, 'risk_score', 0),
                                                         negotiation_priority   = negotiation_priority,
                                                         suggested_improvements = result.get("suggested_improvements", []),
@@ -316,40 +259,51 @@ class LLMClauseInterpreter:
 
     def _create_interpretation_prompt(self, clause: ExtractedClause) -> str:
         """
-        Create enhanced prompt with risk context for LLM interpretation
+        Create concise prompt for clause interpretation
         """
         risk_context = ""
 
         if clause.risk_indicators:
-            risk_context = f"\nRisk indicators detected: {', '.join(clause.risk_indicators)}"
+            risk_context = f"\nRisk Keywords: {', '.join(clause.risk_indicators[:3])}"
         
         risk_score_context = ""
-        
+
         if hasattr(clause, 'risk_score'):
-            risk_score_context = f"\nRisk score: {clause.risk_score}/100"
+            if (clause.risk_score >= 70):
+                risk_level = "CRITICAL RISK"
+
+            elif (clause.risk_score >= 50):
+                risk_level = "HIGH RISK"
+
+            else:
+                risk_level = "Moderate risk"
+            
+            risk_score_context = f"\nRisk Level: {risk_level} ({clause.risk_score}/100)"
         
         prompt = f"""
-                     You are a legal expert explaining contract clauses to non-lawyers.
-
-                     CLAUSE CONTEXT:
-                     - Reference: {clause.reference}
-                     - Category: {clause.category}
-                     - Confidence: {clause.confidence:.2f}{risk_score_context}{risk_context}
+                     Explain this legal clause in plain English.
 
-                     CLAUSE TEXT:
-                     \"\"\"{clause.text}\"\"\"
+                     CLAUSE: {clause.reference} - {clause.category.replace('_', ' ').title()}{risk_score_context}{risk_context}
 
-                     Provide a plain-English interpretation suitable for someone without legal training:
+                     TEXT: "{clause.text}..."
 
-                     1. SUMMARY: Explain what this clause means in 1-2 simple sentences
-                     2. KEY POINTS: List 3-5 key things to understand about this clause
-                     3. POTENTIAL RISKS: Identify 2-4 potential risks or concerns with this clause
-                     4. FAVORABILITY: Rate as "favorable", "neutral", or "unfavorable" from the recipient's perspective
-                     5. SUGGESTED IMPROVEMENTS: Provide 2-3 specific suggestions to improve this clause
+                     Provide:
+                     1. SUMMARY: 1-2 sentences explaining what this means
+                     2. KEY_POINTS: 3 bullet points of what to know
+                     3. POTENTIAL_RISKS: 2-3 specific risks or concerns
+                     4. FAVORABILITY: "favorable", "neutral", or "unfavorable"
+                     5. IMPROVEMENTS: 2 specific suggestions to fix this
 
-                     Focus on practical implications and business impact. Be clear, concise, and actionable.
+                     Keep each section CONCISE. Total response should be ~150 words.
 
-                     Return ONLY valid JSON.
+                     Return ONLY valid JSON:
+                     {{
+                        "plain_english_summary": "...",
+                        "key_points": ["...", "...", "..."],
+                        "potential_risks": ["...", "..."],
+                        "favorability": "unfavorable",
+                        "suggested_improvements": ["...", "..."]
+                     }}
                   """
         
         return prompt
@@ -367,6 +321,23 @@ class LLMClauseInterpreter:
 
         else:
             return "low"
+
+    
+    def _map_risk_score_to_level(self, risk_score: float) -> str:
+        """
+        Map numeric risk score to risk level string
+        """
+        if (risk_score >= 70):
+            return "critical"
+
+        elif (risk_score >= 50):
+            return "high" 
+
+        elif (risk_score >= 30):
+            return "medium"
+            
+        else:
+            return "low"
     
 
     def _fallback_interpretation(self, clause: ExtractedClause) -> ClauseInterpretation:
@@ -424,43 +395,99 @@ class LLMClauseInterpreter:
                                     key_points             = key_points,
                                     potential_risks        = potential_risks,
                                     favorability           = favorability,
-                                    confidence             = 0.50,  # Medium confidence for fallback
+                                    confidence_score       = 0.50,  # Medium confidence for fallback
                                     risk_score             = risk_score,
                                     negotiation_priority   = negotiation_priority,
                                     suggested_improvements = suggested_improvements,
                                    )
     
 
-    def _generate_overall_risk_explanation(self, overall_risk_score: int, contract_type: ContractType, unfavorable_terms: List[UnfavorableTerm],
-                                           missing_protections: List[MissingProtection], provider: LLMProvider) -> str:
+    def _generate_overall_risk_explanation(self, overall_risk_score: int, contract_type: ContractType, unfavorable_terms: List[UnfavorableTerm], missing_protections: List[MissingProtection], 
+                                           provider: LLMProvider) -> str:
         """
-        Generate overall risk explanation using LLM
+        Generate concise overall risk explanation
         """
+        # Handle both object and dictionary formats for unfavorable_terms
+        critical_terms       = list()
+        high_terms           = list()
+        issues_summary       = list()
+        critical_protections = list()
+        
+        for term in unfavorable_terms:
+            severity = ""
+            
+            if isinstance(term, UnfavorableTerm):
+                severity = term.severity
+            
+            elif isinstance(term, dict):
+                severity = term.get('severity', '')
+            
+            else:
+                severity = getattr(term, 'severity', '')
+                
+            if (severity == "critical"):
+                critical_terms.append(term)
+            
+            elif (severity == "high"):
+                high_terms.append(term)
+        
+        # Handle both object and dictionary formats for missing_protections
+        for protection in missing_protections:
+            importance = ""
+
+            if isinstance(protection, MissingProtection):
+                importance = protection.importance
+            
+            elif isinstance(protection, dict):
+                importance = protection.get('importance', '')
+            
+            else:
+                importance = getattr(protection, 'importance', '')
+                
+            if (importance == "critical"):
+                critical_protections.append(protection)
+        
+        # Create issues summary
+        if critical_terms:
+            issues_summary.append(f"{len(critical_terms)} CRITICAL unfavorable terms")
+        
+        if high_terms:
+            issues_summary.append(f"{len(high_terms)} HIGH-risk unfavorable terms")
+        
+        if critical_protections:
+            issues_summary.append(f"{len(critical_protections)} CRITICAL missing protections")
+        
+        if not issues_summary:
+            issues_summary = ["Multiple concerning provisions identified"]
         
         prompt = f"""
-                     As a legal risk analyst, provide a concise overall risk assessment.
+                   Risk Level: {overall_risk_score}/100 for {contract_type.value} contract
 
-                     CONTRACT TYPE: {contract_type.value}
-                     OVERALL RISK SCORE: {overall_risk_score}/100
-                     UNFAVORABLE TERMS: {len(unfavorable_terms)}
-                     MISSING PROTECTIONS: {len(missing_protections)}
+                   Top Issues:
+                   {chr(10).join(issues_summary)}
 
-                     Provide a 2-3 sentence plain-English explanation of what this risk score means for someone signing this contract. Focus on practical implications.
+                   Write ONE sentence (max 25 words) explaining what this risk score means for someone signing this contract.
 
-                     Explanation:
-                  """
-        
+                   Example: "This contract creates severe financial and legal exposure through unlimited liability and one-sided termination rights."
+
+                   Your turn:
+                """
+                                        
         try:
             response = self.llm_manager.complete(prompt      = prompt,
                                                  provider    = provider,
                                                  temperature = 0.2,
-                                                 max_tokens  = 300,
-                                                )
+                                                 max_tokens  = 100,
+                                                ) 
             
-            return response.text.strip() if response.success else self._fallback_risk_explanation(overall_risk_score)
+            explanation = response.text.strip() if response.success else self._fallback_risk_explanation(overall_risk_score)
+            
+            # Ensure single sentence
+            sentences = explanation.split('.')
+            return sentences[0].strip() + '.' if sentences else explanation
             
         except Exception as e:
-            log_error(e, context = {"operation": "generate_overall_risk_explanation"})
+            log_error(e, context={"operation": "generate_overall_risk_explanation"})
             return self._fallback_risk_explanation(overall_risk_score)
     
 
@@ -488,25 +515,57 @@ class LLMClauseInterpreter:
         concerns       = list()
         
         # From unfavorable terms
-        critical_terms = [t for t in unfavorable_terms if (t.get("severity") == "critical")]
+        critical_terms = list()
+
+        for term in unfavorable_terms:
+            if isinstance(term, UnfavorableTerm):
+                if (term.severity == "critical"):
+                    critical_terms.append(term)
+            
+            elif isinstance(term, dict):
+                if (term.get("severity") == "critical"):
+                    critical_terms.append(term)
         
         # Top 10 critical terms
         for term in critical_terms[:10]:  
-            term_name        = term.get('term', 'Unfavorable term')
-            term_explanation = term.get('explanation', 'Standard risk identified')
+            term_name        = ""
+            term_explanation = ""
+            
+            if isinstance(term, UnfavorableTerm):
+                term_name        = term.term
+                term_explanation = term.explanation
+            
+            elif isinstance(term, dict):
+                term_name        = term.get('term', 'Unfavorable term')
+                term_explanation = term.get('explanation', 'Standard risk identified')
 
             concerns.append(f"Critical: {term_name} - {term_explanation}")
         
         # From missing protections
-        critical_protections = [p for p in missing_protections if (p.get("importance") == "critical")]
+        critical_protections = list()
 
+        for protection in missing_protections:
+            if isinstance(protection, MissingProtection):
+                if (protection.importance == "critical"):
+                    critical_protections.append(protection)
+            
+            elif isinstance(protection, dict):
+                if (protection.get("importance") == "critical"):
+                    critical_protections.append(protection)
+        
         # Top 10 critical protections
         for protection in critical_protections[:10]:  
-            protection_name = protection.get('protection', 'Critical protection')
+            protection_name = ""
+            
+            if isinstance(protection, MissingProtection):
+                protection_name = protection.protection
             
+            elif isinstance(protection, dict):
+                protection_name = protection.get('protection', 'Critical protection')
+
             concerns.append(f"Missing: {protection_name}")
         
-        # From clause interpretations (these are objects, so dot notation is OK here)
+        # From clause interpretations
         high_priority_clauses = [c for c in clause_interpretations if (c.negotiation_priority == "high")]
         
         # Top 10 high priority clauses
@@ -522,7 +581,6 @@ class LLMClauseInterpreter:
         """
         Generate negotiation strategy using LLM
         """
-        
         prompt = f"""
                      As a negotiation expert, provide strategic advice for contract negotiations.
 
@@ -553,7 +611,6 @@ class LLMClauseInterpreter:
         """
         Generate market comparison context
         """
-        
         prompt = f"""
                      Provide market context for this contract type.
 

services/negotiation_engine.py

@@ -2,14 +2,12 @@
 import re
 import sys
 import json
-from enum import Enum
 from typing import Any
 from typing import List
 from typing import Dict
 from typing import Tuple
 from pathlib import Path
 from typing import Optional
-from dataclasses import dataclass
 
 # Add parent directory to path for imports
 sys.path.append(str(Path(__file__).parent.parent))
@@ -21,92 +19,18 @@ from config.risk_rules import ContractType
 from services.risk_analyzer import RiskScore
 from utils.logger import ContractAnalyzerLogger
 from model_manager.llm_manager import LLMManager
+from services.data_models import UnfavorableTerm
 from model_manager.llm_manager import LLMProvider
-from services.term_analyzer import UnfavorableTerm
+from services.data_models import NegotiationPoint
+from services.data_models import NegotiationTactic
+from services.data_models import MissingProtection
+from services.data_models import NegotiationPlaybook
 from services.clause_extractor import ExtractedClause
 from services.llm_interpreter import RiskInterpretation
 from services.llm_interpreter import ClauseInterpretation
 from services.protection_checker import MissingProtection
 
 
-class NegotiationTactic(Enum):
-    """
-    Types of negotiation tactics
-    """
-    REMOVAL       = "removal"
-    MODIFICATION  = "modification" 
-    ADDITION      = "addition"
-    LIMITATION    = "limitation"
-    MUTUALIZATION = "mutualization"
-    CLARIFICATION = "clarification"
-
-
-@dataclass
-class NegotiationPoint:
-    """
-    Negotiation talking point with strategic context
-    """
-    priority              : int                       # 1=highest, 5=lowest
-    category              : str
-    issue                 : str
-    current_language      : str
-    proposed_language     : str
-    rationale             : str
-    tactic                : NegotiationTactic
-    fallback_position     : Optional[str] = None
-    estimated_difficulty  : str           = "medium"  # "easy", "medium", "hard"
-    legal_basis           : Optional[str] = None
-    business_impact       : Optional[str] = None
-    counterparty_concerns : Optional[str] = None
-    timing_suggestion     : Optional[str] = None
-    bargaining_chips      : List[str]     = None
-    
-    def to_dict(self) -> Dict[str, Any]:
-        """
-        Convert to dictionary
-        """
-        return {"priority"              : self.priority,
-                "category"              : self.category,
-                "issue"                 : self.issue,
-                "current_language"      : self.current_language,
-                "proposed_language"     : self.proposed_language,
-                "rationale"             : self.rationale,
-                "tactic"                : self.tactic.value,
-                "fallback_position"     : self.fallback_position,
-                "estimated_difficulty"  : self.estimated_difficulty,
-                "legal_basis"           : self.legal_basis,
-                "business_impact"       : self.business_impact,
-                "counterparty_concerns" : self.counterparty_concerns,
-                "timing_suggestion"     : self.timing_suggestion,
-                "bargaining_chips"      : self.bargaining_chips or [],
-               }
-
-
-@dataclass
-class NegotiationPlaybook:
-    """
-    Comprehensive negotiation strategy
-    """
-    overall_strategy     : str
-    critical_points      : List[NegotiationPoint]
-    walk_away_items      : List[str]
-    concession_items     : List[str]
-    timing_guidance      : str
-    risk_mitigation_plan : str
-    
-    def to_dict(self) -> Dict[str, Any]:
-        """
-        Convert to dictionary
-        """
-        return {"overall_strategy"     : self.overall_strategy,
-                "critical_points"      : [point.to_dict() for point in self.critical_points],
-                "walk_away_items"      : self.walk_away_items,
-                "concession_items"     : self.concession_items,
-                "timing_guidance"      : self.timing_guidance,
-                "risk_mitigation_plan" : self.risk_mitigation_plan,
-               }
-
-
 class NegotiationEngine:
     """
     Generate intelligent negotiation strategy with LLM enhancement integrated with full analysis pipeline and RiskRules framework
@@ -114,28 +38,26 @@ class NegotiationEngine:
     def __init__(self, llm_manager: LLMManager, default_provider: LLMProvider = LLMProvider.OLLAMA):
         """
         Initialize negotiation engine
-        
         Arguments:
         ----------
             llm_manager      { LLMManager }  : LLMManager instance
-
+            
             default_provider { LLMProvider } : Default LLM provider
         """
         self.llm_manager      = llm_manager
         self.default_provider = default_provider
         self.risk_rules       = RiskRules()
         self.logger           = ContractAnalyzerLogger.get_logger()
-        
+
         log_info("NegotiationEngine initialized", default_provider = default_provider.value)
 
 
-    # Main entry point with full pipeline integration
     @ContractAnalyzerLogger.log_execution_time("generate_comprehensive_playbook")
     def generate_comprehensive_playbook(self, risk_analysis: RiskScore, risk_interpretation: RiskInterpretation, unfavorable_terms: List[UnfavorableTerm], missing_protections: List[MissingProtection],
                                         clauses: List[ExtractedClause], contract_type: ContractType, max_points: int = 10, provider: Optional[LLMProvider] = None) -> NegotiationPlaybook:
         """
         Generate comprehensive negotiation playbook using all analysis results
-        
+
         Arguments:
         ----------
             risk_analysis               : Complete risk analysis
@@ -146,12 +68,12 @@ class NegotiationEngine:
             
             missing_protections         : Missing protections
             
-            clauses                     : Extracted clauses with risk scores
-           
+            clauses                     : Extracted clauses with risk scores (should be risk-category based)
+            
             contract_type               : Contract type for strategy
-           
+            
             max_points                  : Maximum negotiation points
-           
+            
             provider                    : LLM provider
         
         Returns:
@@ -177,7 +99,7 @@ class NegotiationEngine:
                                                                contract_type       = contract_type,
                                                                provider            = provider,
                                                               )
-                                                            
+        
         # Identify walk-away items
         walk_away_items      = self._identify_walk_away_items(negotiation_points = negotiation_points,
                                                               risk_analysis      = risk_analysis,
@@ -207,9 +129,7 @@ class NegotiationEngine:
                                                    timing_guidance      = timing_guidance,
                                                    risk_mitigation_plan = risk_mitigation_plan,
                                                   )
-        
         log_info("Comprehensive negotiation playbook generated", critical_points = len(negotiation_points), walk_away_items = len(walk_away_items))
-        
         return playbook
 
 
@@ -218,19 +138,19 @@ class NegotiationEngine:
                                     clauses: List[ExtractedClause], max_points: int = 10, provider: Optional[LLMProvider] = None) -> List[NegotiationPoint]:
         """
         Generate prioritized negotiation strategy
-        
+
         Arguments:
         ----------
             risk_analysis       { RiskScore }   : Risk analysis results
-
+            
             unfavorable_terms     { list }      : Detected unfavorable terms
-           
+            
             missing_protections   { list }      : Missing protections
-           
-            clauses               { list }      : Extracted clauses
-           
+            
+            clauses               { list }      : Extracted clauses (ideally with risk categories)
+            
             max_points            { int }       : Maximum negotiation points to generate
-           
+            
             provider           { LLMProvider }  : LLM provider
         
         Returns:
@@ -241,14 +161,14 @@ class NegotiationEngine:
         
         # Convert dictionaries to objects if needed
         unfavorable_terms, missing_protections = self._ensure_objects(unfavorable_terms, missing_protections)
-
+        
         log_info("Starting negotiation points generation", max_points = max_points, unfavorable_terms = len(unfavorable_terms), missing_protections = len(missing_protections))
         
         negotiation_points                     = list()
         
         # Critical unfavorable terms (walk-away level)
         critical_terms                         = [t for t in unfavorable_terms if (t.severity == "critical")]
-
+        
         # Top-10 critical terms
         for term in critical_terms[:10]:  
             point = self._create_enhanced_point_from_term(term, clauses, priority = 1)
@@ -264,7 +184,6 @@ class NegotiationEngine:
         
         # High unfavorable terms
         high_terms = [t for t in unfavorable_terms if (t.severity == "high")]
-        
         for term in high_terms[:10]:
             point = self._create_enhanced_point_from_term(term, clauses, priority = 3)
             if point:
@@ -272,7 +191,6 @@ class NegotiationEngine:
         
         # High-risk categories from risk analysis
         high_risk_categories = self._get_high_risk_categories(risk_analysis)
-        
         for category in high_risk_categories[:10]:
             point = self._create_category_strategy_point(category, risk_analysis, clauses, priority = 4)
             if point:
@@ -280,14 +198,12 @@ class NegotiationEngine:
         
         # Medium unfavorable terms and missing protections
         medium_terms = [t for t in unfavorable_terms if (t.severity == "medium")]
-
         for term in medium_terms[:10]:
             point = self._create_enhanced_point_from_term(term, clauses, priority=5)
             if point:
                 negotiation_points.append(point)
         
         medium_protections = [p for p in missing_protections if (p.importance == "medium")]
-        
         for protection in medium_protections[:10]:
             point = self._create_enhanced_point_from_protection(protection, priority = 5)
             negotiation_points.append(point)
@@ -297,20 +213,26 @@ class NegotiationEngine:
                                                           risk_analysis,
                                                           provider,
                                                          )
-        
         log_info(f"Negotiation points generation complete", total_points = len(enhanced_points))
         
         return enhanced_points[:max_points]
-    
+
 
     def _create_enhanced_point_from_term(self, term: UnfavorableTerm, clauses: List[ExtractedClause], priority: int) -> Optional[NegotiationPoint]:
         """
-        Create enhanced negotiation point from unfavorable term
+        Create enhanced negotiation point from unfavorable term from the clauses that are extracted by from RiskClauseExtractor having risk categories
         """
+        # Find clause by reference
         clause = next((c for c in clauses if (c.reference == term.clause_reference)), None)
+        
+        # If not found by reference, try finding by matching risk category (if term.category is a risk category)
+        if not clause:
+            clause = next((c for c in clauses if (c.category == term.category)), None) # term.category should be a risk category from TermAnalyzer
+
         if not clause:
+            log_info(f"Could not find clause for term: {term.term} in category: {term.category}", clause_reference=term.clause_reference)
             return None
-        
+
         current               = clause.text
         
         # Determine negotiation tactic
@@ -341,15 +263,15 @@ class NegotiationEngine:
                                 counterparty_concerns = counterparty_concerns,
                                 timing_suggestion     = timing,
                                 bargaining_chips      = self._suggest_bargaining_chips(term, tactic),
-                            )
+                               )
+
 
-    
     def _create_enhanced_point_from_protection(self, protection: MissingProtection, priority: int) -> NegotiationPoint:
         """
         Create enhanced negotiation point from missing protection
         """
         difficulty = "medium" if (protection.importance == "critical") else "easy"
-        
+
         return NegotiationPoint(priority             = priority,
                                 category             = protection.categories[0] if protection.categories else "general",
                                 issue                = f"Add {protection.protection}",
@@ -363,24 +285,28 @@ class NegotiationEngine:
                                 business_impact      = f"Missing this protection creates {protection.risk_score}/100 risk exposure",
                                 timing_suggestion    = "Early in negotiations - establishes baseline protections",
                                 bargaining_chips     = ["Offer to review their standard protections in return"],
-                            )
-    
+                               )
+
 
     def _create_category_strategy_point(self, category: str, risk_analysis: RiskScore, clauses: List[ExtractedClause], priority: int) -> Optional[NegotiationPoint]:
         """
-        Create strategic negotiation point for high-risk category
+        Create strategic negotiation point for high-risk category, where clauses are from RiskClauseExtractor and have risk categories
         """
-        category_clauses = [c for c in clauses if self._matches_risk_category(c.category, category)]
+        # Find clauses that belong to this *risk* category
+        category_clauses = [c for c in clauses if c.category == category] # Direct match on risk category
         if not category_clauses:
+            log_info(f"No clauses found for high-risk category: {category}", available_categories=[c.category for c in clauses])
             return None
-        
+
         score            = risk_analysis.category_scores.get(category, 0)
-        description      = self.risk_rules.CATEGORY_DESCRIPTIONS.get(category, {}).get("high", "")
+
+        # Use high description as default for high-risk
+        description      = self.risk_rules.CATEGORY_DESCRIPTIONS.get(category, {}).get("high", "") 
         
         return NegotiationPoint(priority             = priority,
                                 category             = category,
                                 issue                = f"Address {category.replace('_', ' ')} risks (score: {score}/100)",
-                                current_language     = f"Multiple clauses in {category} category present elevated risk",
+                                current_language     = f"Multiple clauses in {category} category present elevated risk (e.g., {category_clauses[0].reference}).",
                                 proposed_language    = f"Request balanced, market-standard terms for {category.replace('_', ' ')} provisions",
                                 rationale            = description,
                                 tactic               = NegotiationTactic.MODIFICATION,
@@ -389,28 +315,27 @@ class NegotiationEngine:
                                 timing_suggestion    = "Mid-negotiations after establishing rapport",
                                )
 
-    
+
     def _determine_negotiation_tactic(self, term: UnfavorableTerm, clause: ExtractedClause) -> NegotiationTactic:
         """
         Determine the best negotiation tactic for this term
         """
         text_lower = clause.text.lower()
-        
         if (("unlimited" in text_lower) or ("sole discretion" in text_lower)):
             return NegotiationTactic.LIMITATION
-
+        
         elif (("indemnify" in text_lower) and ("mutual" not in text_lower)):
             return NegotiationTactic.MUTUALIZATION
-
+        
         elif (any(word in text_lower for word in ["forfeit", "penalty", "liquidated damages"])):
             return NegotiationTactic.REMOVAL
-
+        
         elif (("vague" in term.explanation.lower()) or ("ambiguous" in term.explanation.lower())):
             return NegotiationTactic.CLARIFICATION
-
+        
         else:
             return NegotiationTactic.MODIFICATION
-    
+
 
     def _generate_enhanced_proposed_language(self, term: UnfavorableTerm, clause: ExtractedClause, tactic: NegotiationTactic) -> str:
         """
@@ -422,46 +347,46 @@ class NegotiationEngine:
                               NegotiationTactic.CLARIFICATION : "Clarify: 'For purposes of this section, [TERM] means [CLEAR DEFINITION]'",
                               NegotiationTactic.MODIFICATION  : "Modify to: '[BALANCED, MARKET-STANDARD LANGUAGE]'",
                              }
-        
+
         base_template      = language_templates.get(tactic, term.suggested_fix or "[Request balanced language]")
         
         # Enhance with specific examples based on term type
         if ("non-compete" in term.term.lower()):
             return "Limit to: (a) 6-12 month duration, (b) direct competitors only, (c) reasonable geographic scope"
-
+        
         elif ("liability" in term.term.lower()):
             return "Add: 'Total liability capped at the greater of $[AMOUNT] or fees paid in preceding 12 months'"
-
+        
         elif ("termination" in term.term.lower()):
             return "Modify to provide mutual [30-60] day notice period and clear 'for cause' definition"
         
         return base_template
 
-    
+
     def _calculate_negotiation_difficulty(self, term: UnfavorableTerm, tactic: NegotiationTactic) -> str:
         """
         Calculate negotiation difficulty
         """
         if ((term.severity == "critical") and (tactic == NegotiationTactic.REMOVAL)):
             return "hard"
-
+        
         elif ((term.severity == "high") or (tactic == NegotiationTactic.MUTUALIZATION)):
             return "medium"
-
+        
         else:
             return "easy"
 
-    
+
     def _generate_business_impact(self, term: UnfavorableTerm, clause: ExtractedClause) -> str:
         """
         Generate business impact analysis
         """
         if (term.severity == "critical"):
             return "Could result in significant financial exposure or business restrictions"
-
+        
         elif (term.severity == "high"):
-            return "Creatures substantial operational risk or compliance burden"
-
+            return "Creates substantial operational risk or compliance burden"
+        
         else:
             return "Standard business risk that should be managed"
 
@@ -475,9 +400,9 @@ class NegotiationEngine:
                     NegotiationTactic.MUTUALIZATION : "They may prefer one-sided advantage",
                     NegotiationTactic.CLARIFICATION : "They may prefer ambiguity for flexibility",
                    }
-
+        
         return concerns.get(tactic, "Standard negotiation resistance expected")
-    
+
 
     def _suggest_timing(self, priority: int, tactic: NegotiationTactic) -> str:
         """
@@ -488,30 +413,30 @@ class NegotiationEngine:
         
         elif (tactic == NegotiationTactic.ADDITION):
             return "Early in negotiations - establishes baseline"
-
+        
         else:
             return "Mid-negotiations - after establishing key terms"
-    
+
 
     def _suggest_bargaining_chips(self, term: UnfavorableTerm, tactic: NegotiationTactic) -> List[str]:
         """
         Suggest bargaining chips
         """
         chips = list()
-        
+
         if (tactic == NegotiationTactic.REMOVAL):
             chips.append("Offer alternative protection that addresses their underlying concern")
-
+        
         elif (tactic == NegotiationTactic.LIMITATION):
             chips.append("Accept their position with reasonable cap or standard")
-
+        
         elif (tactic == NegotiationTactic.MUTUALIZATION):
             chips.append("Frame as fairness principle benefiting both parties")
         
         chips.append("Trade for lower priority item they care about")
         
         return chips
-    
+
 
     def _generate_strategic_fallback(self, term: UnfavorableTerm, tactic: NegotiationTactic) -> str:
         """
@@ -519,10 +444,10 @@ class NegotiationEngine:
         """
         if (term.severity == "critical"):
             return "If no compromise, seriously consider walking away - this creates unacceptable risk"
-
+        
         elif (term.severity == "high"):
             return "If they refuse, document objection and consider risk mitigation strategies"
-
+        
         else:
             return "If they won't budge, assess if other favorable terms compensate for this risk"
 
@@ -531,12 +456,13 @@ class NegotiationEngine:
         """
         Convert dictionaries back to proper objects if needed
         """
-        if unfavorable_terms and isinstance(unfavorable_terms[0], dict):
-            from services.term_analyzer import UnfavorableTerm
+        if (unfavorable_terms and isinstance(unfavorable_terms[0], dict)):
+            
             unfavorable_terms = [UnfavorableTerm(**term_dict) for term_dict in unfavorable_terms]
         
+        
         if missing_protections and isinstance(missing_protections[0], dict):
-            from services.protection_checker import MissingProtection
+            
             missing_protections = [MissingProtection(**prot_dict) for prot_dict in missing_protections]
         
         return unfavorable_terms, missing_protections
@@ -548,53 +474,31 @@ class NegotiationEngine:
         """
         if (protection.importance == "critical"):
             return "If they refuse, document this material gap and assess deal viability"
-
+        
         else:
             return "If they refuse, note the gap and consider if other protections compensate"
-        
+
 
     def _get_high_risk_categories(self, risk_analysis: RiskScore) -> List[str]:
         """
         Get high-risk categories from risk analysis
         """
-        return [cat for cat, score in risk_analysis.category_scores.items() if (score >= self.risk_rules.RISK_THRESHOLDS["high"])]
-    
-
-    def _matches_risk_category(self, clause_category: str, risk_category: str) -> bool:
-        """
-        Category matching
-        """
-        mapping = {"restrictive_covenants" : ["non_compete", "confidentiality"],
-                   "termination_rights"    : ["termination"],
-                   "penalties_liability"   : ["indemnification", "liability"],
-                   "compensation_benefits" : ["compensation"],
-                   "intellectual_property" : ["intellectual_property"],
-                   "confidentiality"       : ["confidentiality"],
-                   "liability_indemnity"   : ["indemnification", "liability"],
-                   "governing_law"         : ["dispute_resolution"],
-                   "payment_terms"         : ["compensation"],
-                   "warranties"            : ["warranty"],
-                   "dispute_resolution"    : ["dispute_resolution"],
-                   "assignment_change"     : ["assignment", "amendment"],
-                   "insurance"             : ["insurance"],
-                   "force_majeure"         : ["force_majeure"],
-                  }
+        # Use the risk thresholds defined in RiskRules
+        high_threshold = self.risk_rules.RISK_THRESHOLDS.get("high", 60)
+        return [cat for cat, score in risk_analysis.category_scores.items() if (score >= high_threshold)]
 
-        return clause_category in mapping.get(risk_category, [])
     
-
     def _enhance_with_llm_strategy(self, points: List[NegotiationPoint], risk_analysis: RiskScore, provider: LLMProvider) -> List[NegotiationPoint]:
         """
         Use LLM to enhance negotiation points with sophisticated strategy
         """
         if not points:
             return points
-        
+
         log_info(f"Enhancing {len(points)} negotiation points with LLM strategy")
         
         try:
             prompt   = self._create_strategic_enhancement_prompt(points, risk_analysis)
-            
             response = self.llm_manager.complete(prompt             = prompt,
                                                  provider           = provider,
                                                  temperature        = 0.3,
@@ -602,7 +506,6 @@ class NegotiationEngine:
                                                  fallback_providers = [LLMProvider.OPENAI],
                                                  retry_on_error     = True,
                                                 )
-            
             if response.success:
                 enhanced = self._parse_strategic_enhancements(response.text, points)
                 log_info("LLM strategic enhancement successful")
@@ -615,8 +518,8 @@ class NegotiationEngine:
         except Exception as e:
             log_error(e, context = {"component": "NegotiationEngine", "operation": "enhance_with_llm_strategy"})
             return points
-    
 
+    
     def _create_strategic_enhancement_prompt(self, points: List[NegotiationPoint],  risk_analysis: RiskScore) -> str:
         """
         Create prompt for strategic LLM enhancement
@@ -626,7 +529,7 @@ class NegotiationEngine:
                    "points"       : [{"priority"   : p.priority,
                                       "issue"      : p.issue,
                                       "category"   : p.category,
-                                      "current"    : p.current_language[:150],
+                                      "current"    : p.current_language,
                                       "proposed"   : p.proposed_language,
                                       "tactic"     : p.tactic.value,
                                       "difficulty" : p.estimated_difficulty
@@ -634,69 +537,88 @@ class NegotiationEngine:
                                      for p in points
                                     ],
                   }
-        
+
         prompt = f"""
                      As an expert negotiation strategist, enhance these negotiation points with sophisticated strategy.
-
                      CONTRACT RISK: {context['overall_risk']}/100 ({context['risk_level']})
- 
-                     NEGOTIATION POINTS:
+                     NEGOTIATION POINTS (format: [{{'priority': int, 'issue': str, 'category': str, 'current': str, 'proposed': str, 'tactic': str, 'difficulty': str}}]):
                      {json.dumps(context['points'], indent=2)}
-
-                     For EACH point (keep same numbering 1, 2, 3...), provide:
-                     1. ENHANCED_PROPOSAL: More specific, legally sound alternative language
-                     2. STRATEGIC_RATIONALE: Business-focused reasoning emphasizing mutual benefit
-                     3. COUNTERPARTY_PERSPECTIVE: Their likely concerns and how to address them
-                     4. TIMING_STRATEGY: When and how to raise this issue
-                     5. BARGAINING_CHIPS: Specific trade-offs or concessions
-
-                     Focus on creating win-win solutions and practical negotiation tactics.
+                     For EACH point (match the order and priority), provide:
+                     1. ENHANCED_PROPOSAL: More specific, legally sound alternative language (only return the enhanced text).
+                     2. STRATEGIC_RATIONALE: Business-focused reasoning emphasizing mutual benefit (only return the rationale).
+                     3. COUNTERPARTY_PERSPECTIVE: Their likely concerns and how to address them (only return the perspective).
+                     4. TIMING_STRATEGY: When and how to raise this issue (only return the timing).
+                     5. BARGAINING_CHIPS: Specific trade-offs or concessions (only return the chips, as a comma-separated string).
+                     Focus on creating win-win solutions and practical negotiation tactics. Respond in the exact format below for each point:
+                     Point 1:
+                     ENHANCED_PROPOSAL: [text]
+                     STRATEGIC_RATIONALE: [text]
+                     COUNTERPARTY_PERSPECTIVE: [text]
+                     TIMING_STRATEGY: [text]
+                     BARGAINING_CHIPS: [chip1, chip2, ...]
+                     Point 2:
+                     ENHANCED_PROPOSAL: [text]
+                     ...
                   """
-        
+
         return prompt
-    
+
 
     def _parse_strategic_enhancements(self, llm_text: str, original_points: List[NegotiationPoint]) -> List[NegotiationPoint]:
         """
-        Parse LLM strategic enhancements
+        Parse LLM strategic enhancements, assuming a structured format.
         """
         enhanced = list()
-        
+
         for i, point in enumerate(original_points):
-            # Extract enhanced proposal
-            proposal_pattern = rf"{i+1}[.\)].*?ENHANCED_PROPOSAL:\s*(.*?)(?:STRATEGIC_RATIONALE:|COUNTERPARTY_PERSPECTIVE:|TIMING_STRATEGY:|BARGAINING_CHIPS:|{i+2}\.|$)"
-            proposal_match   = re.search(proposal_pattern, llm_text, re.IGNORECASE | re.DOTALL)
-            
-            if proposal_match:
-                enhanced_proposal = proposal_match.group(1).strip()
+            point_identifier = f"Point {i+1}:"
+            start_idx = llm_text.find(point_identifier)
+            if (start_idx == -1):
+                log_info(f"LLM response did not contain expected identifier for Point {i+1}. Keeping original.")
+                enhanced.append(point)
                 
-                if (enhanced_proposal and (len(enhanced_proposal) > 30)):
-                    point.proposed_language = enhanced_proposal[:600]
-            
-            # Extract timing strategy
-            timing_pattern = rf"{i+1}[.\)].*?TIMING_STRATEGY:\s*(.*?)(?:BARGAINING_CHIPS:|{i+2}\.|$)"
-            timing_match   = re.search(timing_pattern, llm_text, re.IGNORECASE | re.DOTALL)
+                continue
+
+            # Find the start of the next point or end of string
+            next_point_idx = llm_text.find(f"Point {i+2}:", start_idx)
+            if next_point_idx == -1:
+                section_text = llm_text[start_idx:]
             
+            else:
+                section_text = llm_text[start_idx:next_point_idx]
+
+            # Extract fields using regex within the section_text
+            proposal_match = re.search(r"ENHANCED_PROPOSAL:\s*(.*?)(?:\n|$)", section_text, re.DOTALL)
+            if proposal_match:
+                new_proposal = proposal_match.group(1).strip()
+
+                # Basic sanity check
+                if (new_proposal and (len(new_proposal) > 10)): 
+                    point.proposed_language = new_proposal 
+
+            # TIMING_STRATEGY
+            timing_match = re.search(r"TIMING_STRATEGY:\s*(.*?)(?:\n|$)", section_text, re.DOTALL)
             if timing_match:
-                timing = timing_match.group(1).strip()
-                if (timing and (len(timing) > 10)):
-                    point.timing_suggestion = timing[:200]
-            
-            # Extract bargaining chips
-            chips_pattern = rf"{i+1}[.\)].*?BARGAINING_CHIPS:\s*(.*?)(?:{i+2}\.|$)"
-            chips_match   = re.search(chips_pattern, llm_text, re.IGNORECASE | re.DOTALL)
-            
+                new_timing = timing_match.group(1).strip()
+                if (new_timing and (len(new_timing) > 5)):
+                    point.timing_suggestion = new_timing
+
+            # BARGAINING_CHIPS
+            chips_match = re.search(r"BARGAINING_CHIPS:\s*\[(.*?)\]", section_text, re.DOTALL)
             if chips_match:
-                chips_text = chips_match.group(1).strip()
-                if chips_text:
-                    # Parse chips as list items or comma-separated
-                    chips                  = [chip.strip() for chip in re.split(r'[,-•]', chips_text) if chip.strip()]
-                    point.bargaining_chips = chips[:3]  # Keep top 3
-            
+                chips_str = chips_match.group(1).strip()
+                
+                if chips_str:
+                    # Split by comma and strip whitespace
+                    chips_list             = [chip.strip().strip('"\'') for chip in chips_str.split(',') if chip.strip()]
+
+                    # Keep top 3
+                    point.bargaining_chips = chips_list[:3] 
+
             enhanced.append(point)
-        
+
         return enhanced
-    
+
 
     def _generate_overall_strategy(self, risk_analysis: RiskScore, risk_interpretation: RiskInterpretation, contract_type: ContractType, provider: LLMProvider) -> str:
         """
@@ -704,20 +626,16 @@ class NegotiationEngine:
         """
         prompt = f"""
                      As a negotiation expert, provide overall strategy for this contract.
-
                      CONTRACT TYPE: {contract_type.value}
                      RISK LEVEL: {risk_analysis.overall_score}/100 ({risk_analysis.risk_level})
                      KEY CONCERNS: {risk_interpretation.key_concerns}
-
                      Provide a concise 3-4 sentence negotiation strategy focusing on:
                      - Overall approach (collaborative vs. firm)
                      - Key priorities
                      - Risk management
                      - Success metrics
-
                      Strategy:
                   """
-        
         try:
             response = self.llm_manager.complete(prompt      = prompt,
                                                  provider    = provider,
@@ -726,44 +644,40 @@ class NegotiationEngine:
                                                 )
             
             return response.text.strip() if response.success else "Focus on addressing critical risks while maintaining collaborative negotiation tone."
-            
+        
         except Exception as e:
             log_error(e, context = {"operation": "generate_overall_strategy"})
-            
             return "Prioritize critical risk items while seeking balanced, market-standard terms."
-    
+
 
     def _identify_walk_away_items(self, negotiation_points: List[NegotiationPoint], risk_analysis: RiskScore) -> List[str]:
         """
         Identify non-negotiable walk-away items
         """
         walk_away       = list()
-        
         critical_points = [p for p in negotiation_points if (p.priority == 1)]
 
         for point in critical_points:
             if ((point.estimated_difficulty == "hard") and (risk_analysis.overall_score >= 70)):
                 walk_away.append(f"{point.issue} - critical risk that cannot be mitigated")
-        
+
         # Max 5 walk-away items
         return walk_away[:5]  
-    
 
-    def _identify_concession_items(self, negotiation_points: List[NegotiationPoint],
-                                 risk_analysis: RiskScore) -> List[str]:
+
+    def _identify_concession_items(self, negotiation_points: List[NegotiationPoint], risk_analysis: RiskScore) -> List[str]:
         """
         Identify items that can be conceded
         """
         concessions  = list()
-        
-        low_priority = [p for p in negotiation_points if p.priority >= 4]
+        low_priority = [p for p in negotiation_points if (p.priority >= 4)]
 
         for point in low_priority[:2]:
             if (point.estimated_difficulty == "hard"):
                 concessions.append(f"{point.issue} - lower priority, high difficulty")
-        
+
         return concessions
-    
+
 
     def _generate_timing_guidance(self, negotiation_points: List[NegotiationPoint], contract_type: ContractType, provider: LLMProvider) -> str:
         """
@@ -779,7 +693,7 @@ class NegotiationEngine:
         
         else:
             return "Progressive approach: start with easier wins to build momentum"
-    
+
 
     def _generate_risk_mitigation_plan(self, risk_analysis: RiskScore, negotiation_points: List[NegotiationPoint], provider: LLMProvider) -> str:
         """
@@ -787,135 +701,9 @@ class NegotiationEngine:
         """
         if (risk_analysis.overall_score >= 70):
             return "High risk level - focus on critical term resolution. Have fallback positions ready."
-
+        
         elif (risk_analysis.overall_score >= 50):
             return "Moderate risk - prioritize 2-3 key improvements. Document remaining risks."
-
+        
         else:
             return "Manageable risk level - focus on most impactful improvements."
-    
-
-    # Keep existing utility methods for backward compatibility
-    def generate_negotiation_strategy_document(self, playbook: NegotiationPlaybook) -> str:
-        """
-        Generate a formatted negotiation strategy document
-        
-        Returns:
-        -------
-            Formatted markdown document
-        """
-        doc = ["# Comprehensive Negotiation Playbook",
-               "",
-               f"## Overall Strategy",
-               f"{playbook.overall_strategy}",
-               "",
-               "## Critical Negotiation Points",
-               ""
-              ]
-        
-        # Group by priority with enhanced labels
-        by_priority = dict()
-
-        for point in playbook.critical_points:
-            if point.priority not in by_priority:
-                by_priority[point.priority] = []
-            
-            by_priority[point.priority].append(point)
-        
-        priority_labels = {1: "🔴 CRITICAL PRIORITY - Deal Breakers",
-                           2: "🟠 HIGH PRIORITY - Essential Items", 
-                           3: "🟡 MEDIUM PRIORITY - Important Improvements",
-                           4: "🟢 STANDARD PRIORITY - Recommended Changes",
-                           5: "⚪ LOW PRIORITY - Optional Improvements"
-                          }
-        
-        for priority in sorted(by_priority.keys()):
-            doc.append(f"### {priority_labels.get(priority, f'Priority {priority}')}")
-            doc.append("")
-            
-            for point in by_priority[priority]:
-                doc.append(f"#### {point.issue}")
-                doc.append(f"**Category:** {point.category} | **Tactic:** {point.tactic.value} | **Difficulty:** {point.estimated_difficulty}")
-                doc.append("")
-                doc.append("**Current Language:**")
-                doc.append(f"> {point.current_language}")
-                doc.append("")
-                doc.append("**Proposed Language:**")
-                doc.append(f"{point.proposed_language}")
-                doc.append("")
-                doc.append("**Rationale:**")
-                doc.append(f"{point.rationale}")
-                doc.append("")
-                
-                if point.business_impact:
-                    doc.append("**Business Impact:**")
-                    doc.append(f"{point.business_impact}")
-                    doc.append("")
-                
-                if point.timing_suggestion:
-                    doc.append("**Timing:**")
-                    doc.append(f"{point.timing_suggestion}")
-                    doc.append("")
-                
-                if point.bargaining_chips:
-                    doc.append("**Bargaining Chips:**")
-                    for chip in point.bargaining_chips:
-                        doc.append(f"- {chip}")
-                    doc.append("")
-                
-                if point.fallback_position:
-                    doc.append("**Fallback Position:**")
-                    doc.append(f"{point.fallback_position}")
-                    doc.append("")
-                
-                doc.append("---")
-                doc.append("")
-        
-        # Add strategy sections
-        if playbook.walk_away_items:
-            doc.append("## 🚫 Walk-Away Items")
-            doc.append("Do not proceed if these cannot be resolved:")
-            
-            for item in playbook.walk_away_items:
-                doc.append(f"- {item}")
-            
-            doc.append("")
-        
-        if playbook.concession_items:
-            doc.append("## 💰 Concession Items") 
-            doc.append("Consider conceding these if needed:")
-            
-            for item in playbook.concession_items:
-                doc.append(f"- {item}")
-            
-            doc.append("")
-        
-        doc.append("## ⏰ Timing Guidance")
-        doc.append(playbook.timing_guidance)
-        doc.append("")
-        
-        doc.append("## Risk Mitigation Plan")
-        doc.append(playbook.risk_mitigation_plan)
-        
-        return "\n".join(doc)
-    
-
-    def get_critical_points(self, points: List[NegotiationPoint]) -> List[NegotiationPoint]:
-        """
-        Filter to only priority 1-2 points
-        """
-        critical = [p for p in points if p.priority <= 2]
-        log_info(f"Found {len(critical)} critical negotiation points")
-        
-        return critical
-    
-
-    def get_points_by_category(self, points: List[NegotiationPoint],
-                              category: str) -> List[NegotiationPoint]:
-        """
-        Filter points by category
-        """
-        filtered = [p for p in points if (p.category == category)]
-        log_info(f"Found {len(filtered)} negotiation points in category '{category}'")
-        
-        return filtered

services/protection_checker.py

@@ -6,7 +6,6 @@ from typing import Dict
 from typing import Tuple
 from pathlib import Path
 from typing import Optional
-from dataclasses import dataclass
 
 # Add parent directory to path for imports
 sys.path.append(str(Path(__file__).parent.parent))
@@ -16,41 +15,8 @@ from utils.logger import log_error
 from config.risk_rules import RiskRules
 from config.risk_rules import ContractType
 from utils.logger import ContractAnalyzerLogger
-from services.clause_extractor import ExtractedClause
-
-
-@dataclass
-class MissingProtection:
-    """
-    Missing protection item with comprehensive risk analysis
-    """
-    protection        : str
-    importance        : str    # "critical", "high", "medium", "low"
-    risk_score        : float  # 0-100 from risk_rules
-    explanation       : str
-    recommendation    : str
-    categories        : List[str]
-    contract_type     : Optional[str] = None
-    suggested_language: Optional[str] = None
-    legal_basis       : Optional[str] = None
-    affected_clauses  : Optional[List[str]] = None
-    
-    def to_dict(self) -> Dict:
-        """
-        Convert to dictionary
-        """
-        return {"protection"        : self.protection,
-                "importance"        : self.importance,
-                "risk_score"        : round(self.risk_score, 2),
-                "explanation"       : self.explanation,
-                "recommendation"    : self.recommendation,
-                "categories"        : self.categories,
-                "contract_type"     : self.contract_type,
-                "suggested_language": self.suggested_language,
-                "legal_basis"       : self.legal_basis,
-                "affected_clauses"  : self.affected_clauses or [],
-               }
-
+from services.data_models import ExtractedClause
+from services.data_models import MissingProtection
 
 
 class ProtectionChecker:
@@ -60,208 +26,155 @@ class ProtectionChecker:
     def __init__(self, contract_type: ContractType = ContractType.GENERAL):
         """
         Initialize protection checker with contract-type specific analysis
-        
+
         Arguments:
         ----------
             contract_type { ContractType } : Contract type for protection prioritization
         """
-        self.contract_type = contract_type
-        self.rules         = RiskRules()
-        self.logger        = ContractAnalyzerLogger.get_logger()
-        
+        self.contract_type         = contract_type
+        self.rules                 = RiskRules()
+        self.logger                = ContractAnalyzerLogger.get_logger()
+
         # Contract-type specific protection priorities
         self.protection_priorities = self._get_contract_type_priorities()
-        
-        log_info("ProtectionChecker initialized", 
-                 contract_type    = contract_type.value,
+
+        log_info("ProtectionChecker initialized",
+                 contract_type    = self.contract_type.value,
                  protection_count = len(self.rules.PROTECTION_CHECKLIST),
                 )
-    
+
 
     def _get_contract_type_priorities(self) -> Dict[str, List[str]]:
         """
         Get protection priorities by contract type
         """
-        priorities = {ContractType.EMPLOYMENT.value   : ['for_cause_definition', 'severance_provision', 'prior_ip_exclusion', 'confidentiality_duration'],
-                      ContractType.SOFTWARE.value     : ['liability_cap', 'prior_ip_exclusion', 'mutual_indemnification', 'dispute_resolution'],
-                      ContractType.CONSULTING.value   : ['liability_cap', 'mutual_indemnification', 'payment_terms', 'change_control_process'],
-                      ContractType.NDA.value          : ['confidentiality_duration', 'prior_ip_exclusion', 'dispute_resolution'],
-                      ContractType.LEASE.value        : ['dispute_resolution', 'change_control_process', 'insurance_requirements'],
-                      ContractType.PURCHASE.value     : ['liability_cap', 'warranty_protection', 'dispute_resolution'],
-                      ContractType.GENERAL.value      : ['liability_cap', 'mutual_indemnification', 'dispute_resolution'],
+        priorities = {ContractType.EMPLOYMENT.value : ['for_cause_definition', 'severance_provision', 'prior_ip_exclusion', 'confidentiality_duration'],
+                      ContractType.SOFTWARE.value   : ['liability_cap', 'prior_ip_exclusion', 'mutual_indemnification', 'dispute_resolution'],
+                      ContractType.CONSULTING.value : ['liability_cap', 'mutual_indemnification', 'payment_terms', 'change_control_process'],
+                      ContractType.NDA.value        : ['confidentiality_duration', 'prior_ip_exclusion', 'dispute_resolution'],
+                      ContractType.LEASE.value      : ['dispute_resolution', 'change_control_process', 'insurance_requirements'],
+                      ContractType.PURCHASE.value   : ['liability_cap', 'warranty_protection', 'dispute_resolution'],
+                      ContractType.GENERAL.value    : ['liability_cap', 'mutual_indemnification', 'dispute_resolution'],
                      }
-        
+
         return priorities.get(self.contract_type.value, [])
-    
+
 
     @ContractAnalyzerLogger.log_execution_time("check_missing_protections")
     def check_missing_protections(self, contract_text: str, clauses: List[ExtractedClause], contract_type: Optional[ContractType] = None) -> List[MissingProtection]:
         """
         Identify all missing protections using comprehensive RiskRules framework
-        
+
         Arguments:
         ----------
             contract_text { str }          : Full contract text
 
             clauses       { list }         : Extracted clauses
-            
+
             contract_type { ContractType } : Override contract type
-        
+
         Returns:
         --------
                       { list }             : List of MissingProtection objects
         """
-        
+
         # Update contract type if provided
         if contract_type:
             self.contract_type         = contract_type
             self.protection_priorities = self._get_contract_type_priorities()
-        
+
         log_info("Starting missing protections analysis",
-                 text_length    = len(contract_text),
-                 num_clauses    = len(clauses),
-                 contract_type  = self.contract_type.value,
+                 text_length   = len(contract_text),
+                 num_clauses   = len(clauses),
+                 contract_type = self.contract_type.value,
                 )
-        
+
         missing    = list()
         text_lower = contract_text.lower()
-        
+
         # Check each protection in RiskRules PROTECTION_CHECKLIST
         for protection_id, config in self.rules.PROTECTION_CHECKLIST.items():
             is_present, found_in_clauses = self._check_protection_comprehensive(protection_id = protection_id,
-                                                                                text_lower     = text_lower,
-                                                                                clauses        = clauses,
+                                                                                text_lower    = text_lower,
+                                                                                clauses       = clauses,
                                                                                )
-            
+
             if not is_present:
                 missing_protection = self._create_missing_protection(protection_id    = protection_id,
                                                                      config           = config,
                                                                      found_in_clauses = found_in_clauses,
                                                                     )
-                
+
                 missing.append(missing_protection)
-        
+
         # Prioritize by contract type and risk score
         final_missing = self._prioritize_missing_protections(missing_protections = missing)
-        
+
         log_info("Missing protections analysis complete",
                  total_missing = len(final_missing),
                  critical      = sum(1 for p in final_missing if (p.importance == "critical")),
                  high          = sum(1 for p in final_missing if (p.importance == "high")),
                 )
-        
+
         return final_missing
-    
+
 
     def _check_protection_comprehensive(self, protection_id: str, text_lower: str, clauses: List[ExtractedClause]) -> Tuple[bool, List[str]]:
         """
         Comprehensive protection detection using multiple methods
-        
+
         Returns:
         --------
             { tuple } : (is_present, list of clause references where protection was found)
         """
         found_in_clauses    = list()
-        
+
         # Enhanced protection patterns with regex for better matching
         protection_patterns = self._get_protection_patterns(protection_id = protection_id)
-        
+
         # Check in full text with regex patterns
         for pattern in protection_patterns:
             if re.search(pattern, text_lower, re.IGNORECASE):
                 return True, found_in_clauses
-        
+
         # Check in relevant clauses with context awareness
         relevant_categories = self.rules.PROTECTION_CHECKLIST[protection_id]["categories"]
         relevant_clauses    = [c for c in clauses if c.category in relevant_categories]
-        
+
         for clause in relevant_clauses:
             clause_text_lower = clause.text.lower()
-            
+
             for pattern in protection_patterns:
                 if re.search(pattern, clause_text_lower, re.IGNORECASE):
                     found_in_clauses.append(clause.reference)
+                    
                     return True, found_in_clauses
-        
+
         # Additional semantic checks for complex protections
-        if self._check_protection_semantic(protection_id = protection_id, text_lower = text_lower, clauses = clauses):
+        if self._check_protection_semantic(protection_id=protection_id, text_lower=text_lower, clauses=clauses):
             return True, found_in_clauses
-        
+
         return False, found_in_clauses
-    
+
 
     def _get_protection_patterns(self, protection_id: str) -> List[str]:
         """
         Get comprehensive regex patterns for each protection
         """
-        patterns = {"for_cause_definition"     : [r'for\s+cause\s+means',
-                                                  r'cause\s+defined\s+as',
-                                                  r'grounds?\s+for\s+termination',
-                                                  r'termination\s+for\s+cause',
-                                                  r'just\s+cause\s+definition',
-                                                 ],
-                    "severance_provision"      : [r'severance\s+(pay|compensation|benefits)',
-                                                  r'separation\s+(pay|package|compensation)',
-                                                  r'termination\s+(pay|benefits)',
-                                                  r'upon\s+termination.*pay',
-                                                  r'severance.*equal\s+to',
-                                                 ],
-                    "mutual_indemnification"   : [r'mutual\s+indemnification',
-                                                  r'each\s+party\s+shall\s+indemnify',
-                                                  r'both\s+parties\s+indemnify',
-                                                  r'reciprocal\s+indemnification',
-                                                  r'indemnification.*mutual',
-                                                 ],
-                    "liability_cap"            : [r'liability.*cap',
-                                                  r'maximum\s+liability',
-                                                  r'limited\s+to.*\$?\d+',
-                                                  r'not\s+exceed.*\$?\d+',
-                                                  r'liability\s+shall\s+not\s+exceed',
-                                                  r'cap.*liability',
-                                                 ],
-                    "prior_ip_exclusion"       : [r'prior\s+intellectual\s+property',
-                                                  r'existing\s+ip',
-                                                  r'background\s+ip',
-                                                  r'pre-existing',
-                                                  r'prior\s+inventions',
-                                                  r'personal\s+projects',
-                                                 ],
-                    "confidentiality_duration" : [r'confidentiality.*period\s+of',
-                                                  r'for\s+\d+\s+years\s+from',
-                                                  r'confidentiality.*expire',
-                                                  r'confidentiality.*term',
-                                                  r'duration.*confidentiality',
-                                                 ],
-                    "dispute_resolution"       : [r'arbitration',
-                                                  r'mediation',
-                                                  r'dispute\s+resolution',
-                                                  r'resolution\s+of\s+disputes',
-                                                  r'alternative\s+dispute',
-                                                  r'adr',
-                                                 ],
-                    "change_control_process"   : [r'change\s+order',
-                                                  r'change\s+request',
-                                                  r'amendment.*writing',
-                                                  r'modification.*writing',
-                                                  r'written\s+consent',
-                                                  r'change\s+control',
-                                                 ],
-                    "insurance_requirements"   : [r'insurance\s+requirements',
-                                                  r'maintain\s+insurance',
-                                                  r'proof\s+of\s+insurance',
-                                                  r'coverage.*\$?\d+',
-                                                  r'liability\s+insurance',
-                                                 ],
-                    "force_majeure"            : [r'force\s+majeure',
-                                                  r'act\s+of\s+god',
-                                                  r'unforeseeable',
-                                                  r'beyond\s+control',
-                                                  r'natural\s+disaster',
-                                                 ],
+        patterns = {"for_cause_definition"     : [r'for\s+cause\s+means', r'cause\s+defined\s+as', r'grounds?\s+for\s+termination', r'termination\s+for\s+cause', r'just\s+cause\s+definition',],
+                    "severance_provision"      : [r'severance\s+(pay|compensation|benefits)', r'separation\s+(pay|package|compensation)', r'termination\s+(pay|benefits)', r'upon\s+termination.*pay', r'severance.*equal\s+to',],
+                    "mutual_indemnification"   : [r'mutual\s+indemnification', r'each\s+party\s+shall\s+indemnify', r'both\s+parties\s+indemnify', r'reciprocal\s+indemnification', r'indemnification.*mutual',],
+                    "liability_cap"            : [r'liability.*cap', r'maximum\s+liability', r'limited\s+to.*\$?\d+', r'not\s+exceed.*\$?\d+', r'liability\s+shall\s+not\s+exceed', r'cap.*liability',],
+                    "prior_ip_exclusion"       : [r'prior\s+intellectual\s+property', r'existing\s+ip', r'background\s+ip', r'pre-existing', r'prior\s+inventions', r'personal\s+projects',],
+                    "confidentiality_duration" : [r'confidentiality.*period\s+of', r'for\s+\d+\s+years\s+from', r'confidentiality.*expire', r'confidentiality.*term', r'duration.*confidentiality',],
+                    "dispute_resolution"       : [r'arbitration', r'mediation', r'dispute\s+resolution', r'resolution\s+of\s+disputes', r'alternative\s+dispute', r'adr',],
+                    "change_control_process"   : [r'change\s+order', r'change\s+request', r'amendment.*writing', r'modification.*writing', r'written\s+consent', r'change\s+control',],
+                    "insurance_requirements"   : [r'insurance\s+requirements', r'maintain\s+insurance', r'proof\s+of\s+insurance', r'coverage.*\$?\d+', r'liability\s+insurance',],
+                    "force_majeure"            : [ r'force\s+majeure', r'act\s+of\s+god', r'unforeseeable', r'beyond\s+control', r'natural\s+disaster',],
                    }
-        
+
         return patterns.get(protection_id, [rf'\b{protection_id}\b'])
-    
+
 
     def _check_protection_semantic(self, protection_id: str, text_lower: str, clauses: List[ExtractedClause]) -> bool:
         """
@@ -271,33 +184,35 @@ class ProtectionChecker:
             # Check if there's any indemnification that's not mutual
             has_indemnification = bool(re.search(r'indemnif', text_lower))
             has_mutual_language = bool(re.search(r'mutual|each party|both parties', text_lower))
-            
+
             return has_indemnification and has_mutual_language
-        
+
         elif (protection_id == "liability_cap"):
             # Check if there's liability language but no cap
             has_liability = bool(re.search(r'liability|liable', text_lower))
             has_cap       = bool(re.search(r'cap|limit|maximum|not exceed', text_lower))
-            
+
             return has_liability and has_cap
-        
+
         elif (protection_id == "prior_ip_exclusion"):
             # Check if there's IP assignment but no exclusion
             has_ip_assignment = bool(re.search(r'intellectual property|work product|inventions', text_lower))
             has_exclusion     = bool(re.search(r'prior|existing|background|exclude', text_lower))
-            
+
             return has_ip_assignment and has_exclusion
-        
+
         return False
-    
+
 
     def _create_missing_protection(self, protection_id: str, config: Dict, found_in_clauses: List[str]) -> MissingProtection:
         """
         Create comprehensive MissingProtection object
         """
-        protection_name = self._format_protection_name(protection_id = protection_id)
-        
-        return MissingProtection(protection         = protection_name,
+        # Use centralized map for display name
+        protection_name = self.rules.get_protection_display_name(protection_id)
+
+        return MissingProtection(protection_id      = protection_id, 
+                                 protection         = protection_name,
                                  importance         = config["importance"],
                                  risk_score         = config["risk_if_missing"],
                                  explanation        = self._get_comprehensive_explanation(protection_id = protection_id),
@@ -308,103 +223,104 @@ class ProtectionChecker:
                                  legal_basis        = self._get_legal_basis(protection_id = protection_id),
                                  affected_clauses   = found_in_clauses,
                                 )
-    
-
-    def _format_protection_name(self, protection_id: str) -> str:
-        """
-        Convert protection_id to readable name
-        """
-        names = {"for_cause_definition"     : "For Cause Definition",
-                 "severance_provision"      : "Severance Provision", 
-                 "mutual_indemnification"   : "Mutual Indemnification",
-                 "liability_cap"            : "Liability Cap",
-                 "prior_ip_exclusion"       : "Prior IP Exclusion",
-                 "confidentiality_duration" : "Confidentiality Duration Limit",
-                 "dispute_resolution"       : "Dispute Resolution Process",
-                 "change_control_process"   : "Change Control Process",
-                 "insurance_requirements"   : "Insurance Requirements",
-                 "force_majeure"            : "Force Majeure Protection",
-                }
-        
-        return names.get(protection_id, protection_id.replace("_", " ").title())
-    
+
 
     def _get_comprehensive_explanation(self, protection_id: str) -> str:
         """
         Get detailed explanation for why this protection matters
         """
         explanations = {"for_cause_definition"     : ("Without a clear 'for cause' definition, termination grounds remain ambiguous and subject to interpretation abuse. "
-                                                      "This creates significant job insecurity and potential for arbitrary termination without proper recourse."),
+                                                      "This creates significant job insecurity and potential for arbitrary termination without proper recourse."
+                                                     ),
                         "severance_provision"      : ("Missing severance provision means zero financial protection if terminated without cause. "
-                                                      "Industry standards provide 2-3 months salary to support transition and mitigate sudden income loss."),
+                                                      "Industry standards provide 2-3 months salary to support transition and mitigate sudden income loss."
+                                                     ),
                         "mutual_indemnification"   : ("One-sided indemnification creates asymmetric liability exposure. Mutual protection ensures both parties share "
-                                                      "responsibility for their respective breaches, negligence, or misconduct."),
+                                                      "responsibility for their respective breaches, negligence, or misconduct."
+                                                     ),
                         "liability_cap"            : ("Unlimited liability exposes you to catastrophic financial risk beyond reasonable business expectations. "
-                                                      "Standard practice caps liability at fees paid or a reasonable multiple of contract value."),
+                                                      "Standard practice caps liability at fees paid or a reasonable multiple of contract value."
+                                                     ),
                         "prior_ip_exclusion"       : ("Without prior IP exclusion, your existing intellectual property and personal projects could be claimed by the other party. "
-                                                      "This protection preserves ownership of work created before and outside this engagement."),
+                                                      "This protection preserves ownership of work created before and outside this engagement."
+                                                     ),
                         "confidentiality_duration" : ("Indefinite confidentiality obligations unreasonably restrict future business activities indefinitely. "
-                                                      "Industry standards limit confidentiality to 3-5 years post-termination for most information."),
+                                                      "Industry standards limit confidentiality to 3-5 years post-termination for most information."
+                                                     ),
                         "dispute_resolution"       : ("Without formal dispute resolution, conflicts escalate directly to costly litigation. Mediation and arbitration "
-                                                      "provide efficient, cost-effective alternatives with specialized expertise."),
+                                                      "provide efficient, cost-effective alternatives with specialized expertise."
+                                                     ),
                         "change_control_process"   : ("Lack of change control enables scope creep and verbal modifications that create ambiguity. Formal processes "
-                                                      "ensure all changes are documented, approved, and properly scoped."),
-                        "insurance_requirements"   : ("Missing insurance requirements leave you exposed to uncovered liabilities. Proper coverage transfers "
-                                                      "risk and provides financial protection for both parties."),
+                                                      "ensure all changes are documented, approved, and properly scoped."
+                                                     ),
+                        "insurance_requirements"   : ("Missing insurance requirements leave you exposed to uncovered liabilities. "
+                                                      "Proper coverage transfers risk and provides financial protection for both parties."
+                                                     ),
                         "force_majeure"            : ("Without force majeure protection, you remain liable for performance during unforeseeable events beyond control. "
-                                                      "This clause provides reasonable relief during extraordinary circumstances."),
+                                                      "This clause provides reasonable relief during extraordinary circumstances."
+                                                     ),
                        }
-        
+
         return explanations.get(protection_id, "This protection is critical for balanced risk allocation and legal fairness.")
-    
+
 
     def _get_detailed_recommendation(self, protection_id: str) -> str:
         """
         Get detailed recommendation for adding this protection
         """
         recommendations = {"for_cause_definition"     : ("Add clear 'For Cause' definition including: gross negligence, willful misconduct, material breach after "
-                                                         "30-day cure period, conviction of felony, or fraud. Require written notice specifying grounds."),
+                                                         "30-day cure period, conviction of felony, or fraud. Require written notice specifying grounds."
+                                                        ),
                            "severance_provision"      : ("Include severance equal to 2-3 months base salary for termination without cause, payable within 30 days. "
-                                                         "Add pro-rated bonus calculation and continuation of benefits during severance period."),
+                                                         "Add pro-rated bonus calculation and continuation of benefits during severance period."
+                                                        ),
                            "mutual_indemnification"   : ("Replace one-sided language with: 'Each party shall indemnify, defend, and hold harmless the other party "
-                                                         "from claims arising from their respective breach, negligence, or willful misconduct.'"),
+                                                         "from claims arising from their respective breach, negligence, or willful misconduct.'"
+                                                        ),
                            "liability_cap"            : ("Add: 'Total liability of either party under this Agreement shall not exceed the greater of (a) fees paid "
-                                                         "in the 12 months preceding the claim, or (b) $[reasonable amount]. Exclude liability for indirect damages.'"),
+                                                         "in the 12 months preceding the claim, or (b) $[reasonable amount]. Exclude liability for indirect damages.'"
+                                                        ),
                            "prior_ip_exclusion"       : ("Include: 'Work Product excludes Employee's prior intellectual property, existing inventions, personal projects "
-                                                         "unrelated to Company business, and open source contributions. Attach prior IP list as Exhibit A.'"),
+                                                         "unrelated to Company business, and open source contributions. Attach prior IP list as Exhibit A.'"
+                                                        ),
                            "confidentiality_duration" : ("Specify: 'Confidentiality obligations shall survive termination for 3-5 years. Trade secrets protected "
-                                                         "indefinitely but must be specifically identified. Publicly available information excluded.'"),
+                                                         "indefinitely but must be specifically identified. Publicly available information excluded.'"
+                                                        ),
                            "dispute_resolution"       : ("Add: 'Disputes shall first be subject to 30-day good faith mediation. If unresolved, binding arbitration "
-                                                         "under [rules] in [neutral location]. Each party bears own costs, arbitrator may award fees to prevailing party.'"),
+                                                         "under [rules] in [neutral location]. Each party bears own costs, arbitrator may award fees to prevailing party.'"
+                                                        ),
                            "change_control_process"   : ("Include: 'All amendments require written change orders signed by both parties. Change orders must specify "
-                                                         "scope, timeline, cost, and acceptance criteria. Verbal agreements are not binding.'"),
+                                                         "scope, timeline, cost, and acceptance criteria. Verbal agreements are not binding.'"
+                                                        ),
                            "insurance_requirements"   : ("Specify: 'Contractor shall maintain general liability insurance of $1M per occurrence, professional liability "
-                                                         "insurance of $2M, and workers' compensation. Provide certificates of insurance before commencement.'"),
+                                                         "insurance of $2M, and workers' compensation. Provide certificates of insurance before commencement.'"
+                                                        ),
                            "force_majeure"            : ("Add: 'Neither party liable for failure to perform due to causes beyond reasonable control including acts of God, "
-                                                         "war, strikes, or natural disasters. Performance suspended during event, resume when practicable.'"),
+                                                         "war, strikes, or natural disasters. Performance suspended during event, resume when practicable.'"
+                                                        ),
                           }
-        
+
         return recommendations.get(protection_id, "Negotiate to include this standard protection for balanced risk allocation.")
-    
+
 
     def _get_suggested_language(self, protection_id: str) -> str:
         """
         Get actual suggested clause language
         """
-        language_library = {"for_cause_definition"     : "\"For Cause\" means: (a) gross negligence or willful misconduct; (b) material breach of this Agreement after 30-day written notice and cure period; (c) conviction of a felony; or (d) fraud, dishonesty, or embezzlement.",
-                            "severance_provision"      : "Upon termination without cause, Company shall pay Employee severance equal to three months of base salary, payable within 30 days of termination. Employee shall also receive pro-rated annual bonus and continuation of health benefits during severance period.",
-                            "mutual_indemnification"   : "Each party shall indemnify, defend, and hold harmless the other party from and against any and all claims, damages, losses, and expenses arising from the indemnifying party's breach of this Agreement, negligence, or willful misconduct.",
-                            "liability_cap"            : "Notwithstanding anything to the contrary, the total liability of either party under this Agreement shall not exceed the greater of (a) the fees paid by Customer to Provider in the twelve months preceding the claim, or (b) $500,000. Neither party shall be liable for any indirect, special, incidental, or consequential damages.",
-                            "prior_ip_exclusion"       : "Work Product excludes any intellectual property, inventions, or creative works developed by Employee prior to this Agreement or developed outside the scope of employment without using Company resources. Employee has listed prior IP in Exhibit A. Background IP remains the property of its respective owner.",
-                            "confidentiality_duration" : "The obligations of confidentiality shall survive termination of this Agreement for a period of five years. Trade secrets shall be protected indefinitely. Confidential Information shall not include information that is or becomes publicly available through no fault of Receiving Party.",
-                            "dispute_resolution"       : "Any dispute arising under this Agreement shall first be submitted to mediation with a mutually acceptable mediator. If mediation fails after 30 days, either party may initiate binding arbitration under the rules of the American Arbitration Association. The prevailing party in any dispute shall be entitled to recover reasonable attorneys' fees and costs.",
-                            "change_control_process"   : "No amendment, modification, or waiver of any provision of this Agreement shall be effective unless in writing and signed by both parties. All change requests must be submitted in writing as Change Orders, specifying the changes, associated costs, timeline impacts, and acceptance criteria.",
-                            "insurance_requirements"   : "Contractor shall maintain at its own expense: (a) Commercial General Liability insurance with limits of $1,000,000 per occurrence; (b) Professional Liability insurance with limits of $2,000,000 per claim; and (c) Workers' Compensation insurance as required by law. Certificates of insurance shall be provided to Client upon request.",
-                            "force_majeure"            : "Neither party shall be liable for any failure or delay in performance under this Agreement due to causes beyond its reasonable control, including acts of God, war, terrorism, labor disputes, or governmental actions. The affected party shall notify the other party promptly and resume performance as soon as practicable.",
+        language_library = {"for_cause_definition"     : ("\"For Cause\" means: (a) gross negligence or willful misconduct; (b) material breach of this Agreement after 30-day written notice and cure period; (c) conviction of a felony; or (d) fraud, dishonesty, or embezzlement."),
+                            "severance_provision"      : ("Upon termination without cause, Company shall pay Employee severance equal to three months of base salary, payable within 30 days of termination. Employee shall also receive pro-rated annual bonus and continuation of health benefits during severance period."),
+                            "mutual_indemnification"   : ("Each party shall indemnify, defend, and hold harmless the other party from and against any and all claims, damages, losses, and expenses arising from the indemnifying party's breach of this Agreement, negligence, or willful misconduct."),
+                            "liability_cap"            : ("Notwithstanding anything to the contrary, the total liability of either party under this Agreement shall not exceed the greater of (a) the fees paid by Customer to Provider in the twelve months preceding the claim, or (b) $500,000. Neither party shall be liable for any indirect, special, incidental, or consequential damages."),
+                            "prior_ip_exclusion"       : ("Work Product excludes any intellectual property, inventions, or creative works developed by Employee prior to this Agreement or developed outside the scope of employment without using Company resources. Employee has listed prior IP in Exhibit A. Background IP remains the property of its respective owner."),
+                            "confidentiality_duration" : ("The obligations of confidentiality shall survive termination of this Agreement for a period of five years. Trade secrets shall be protected indefinitely. Confidential Information shall not include information that is or becomes publicly available through no fault of Receiving Party."),
+                            "dispute_resolution"       : ("Any dispute arising under this Agreement shall first be submitted to mediation with a mutually acceptable mediator. If mediation fails after 30 days, either party may initiate binding arbitration under the rules of the American Arbitration Association. The prevailing party in any dispute shall be entitled to recover reasonable attorneys' fees and costs."),
+                            "change_control_process"   : ("No amendment, modification, or waiver of any provision of this Agreement shall be effective unless in writing and signed by both parties. All change requests must be submitted in writing as Change Orders, specifying the changes, associated costs, timeline impacts, and acceptance criteria."),
+                            "insurance_requirements"   : ("Contractor shall maintain at its own expense: (a) Commercial General Liability insurance with limits of $1,000,000 per occurrence; (b) Professional Liability insurance with limits of $2,000,000 per claim; and (c) Workers' Compensation insurance as required by law. Certificates of insurance shall be provided to Client upon request."),
+                            "force_majeure"            : ("Neither party shall be liable for any failure or delay in performance under this Agreement due to causes beyond its reasonable control, including acts of God, war, terrorism, labor disputes, or governmental actions. The affected party shall notify the other party promptly and resume performance as soon as practicable."),
                            }
-        
+
         return language_library.get(protection_id, "Standard protection clause appropriate for this contract type.")
-    
+
 
     def _get_legal_basis(self, protection_id: str) -> str:
         """
@@ -412,7 +328,7 @@ class ProtectionChecker:
         """
         legal_bases = {"for_cause_definition"     : "Employment protection statutes and doctrine of good faith and fair dealing",
                        "severance_provision"      : "Industry standards and reasonable notice requirements",
-                       "mutual_indemnification"   : "Principle of mutuality and unconscionability doctrine", 
+                       "mutual_indemnification"   : "Principle of mutuality and unconscionability doctrine",
                        "liability_cap"            : "Commercial reasonableness and risk allocation principles",
                        "prior_ip_exclusion"       : "Intellectual property rights and prior ownership protection",
                        "confidentiality_duration" : "Reasonableness standard for restrictive covenants",
@@ -421,9 +337,9 @@ class ProtectionChecker:
                        "insurance_requirements"   : "Risk management and liability transfer principles",
                        "force_majeure"            : "Impossibility of performance and commercial impracticability",
                       }
-        
+
         return legal_bases.get(protection_id, "Standard contractual protection for balanced risk allocation")
-    
+
 
     def _prioritize_missing_protections(self, missing_protections: List[MissingProtection]) -> List[MissingProtection]:
         """
@@ -431,45 +347,48 @@ class ProtectionChecker:
         """
         if not missing_protections:
             return []
-        
+
         # Sort by risk score (descending)
         missing_protections.sort(key = lambda p: p.risk_score, reverse = True)
-        
+
         # Boost priority for contract-type specific critical protections
         for protection in missing_protections:
-            protection_key = protection.protection.lower().replace(" ", "_")
-            if protection_key in self.protection_priorities:
+            # Use the protection_id for the check
+            if protection.protection_id in self.protection_priorities:
                 # Boost for contract relevance
-                protection.risk_score += 10  
-        
+                protection.risk_score += 10
+
         # Re-sort with boosted scores
         missing_protections.sort(key = lambda p: p.risk_score, reverse = True)
         
+
         # Return top 15 most critical missing protections
-        return missing_protections[:15]
-    
+        top_missing_protections = missing_protections[:15]
+        
+        return top_missing_protections
+
 
     def get_critical_missing(self, protections: List[MissingProtection]) -> List[MissingProtection]:
         """
         Filter to only critical missing protections
         """
         critical = [p for p in protections if (p.importance == "critical")]
-        
+
         log_info(f"Found {len(critical)} critical missing protections")
-        
+
         return critical
-    
+
 
     def get_by_category(self, protections: List[MissingProtection], category: str) -> List[MissingProtection]:
         """
         Filter protections by category
         """
-        filtered = [p for p in protections if (category in p.categories)]
-        
+        filtered = [p for p in protections if category in p.categories]
+
         log_info(f"Found {len(filtered)} missing protections in category '{category}'")
-        
+
         return filtered
-    
+
 
     def get_importance_distribution(self, protections: List[MissingProtection]) -> Dict[str, int]:
         """
@@ -477,35 +396,38 @@ class ProtectionChecker:
         """
         distribution = {"critical" : 0, 
                         "high"     : 0, 
-                        "medium"   : 0,
+                        "medium"   : 0, 
                         "low"      : 0,
                        }
-        
+
         for protection in protections:
             distribution[protection.importance] = distribution.get(protection.importance, 0) + 1
-        
+
         log_info("Missing protections importance distribution", **distribution)
-        
+
         return distribution
-    
+
 
     def get_risk_score_summary(self, protections: List[MissingProtection]) -> Dict[str, float]:
         """
         Get risk score summary statistics
         """
         if not protections:
-            return {"total_risk": 0, "average_risk": 0, "max_risk": 0}
-        
-        scores        = [p.risk_score for p in protections]
-        total_risk    = sum(scores)
-        average_risk  = total_risk / len(scores)
-        max_risk      = max(scores)
-        
-        summary = {"total_risk"   : round(total_risk, 2),
-                   "average_risk" : round(average_risk, 2),
-                   "max_risk"     : round(max_risk, 2),
-                  }
-        
+            return {"total_risk"   : 0, 
+                    "average_risk" : 0, 
+                    "max_risk"     : 0,
+                   }
+
+        scores       = [p.risk_score for p in protections]
+        total_risk   = sum(scores)
+        average_risk = total_risk / len(scores)
+        max_risk     = max(scores)
+
+        summary      = {"total_risk"   : round(total_risk, 2),
+                        "average_risk" : round(average_risk, 2),
+                        "max_risk"     : round(max_risk, 2),
+                       }
+
         log_info("Missing protections risk score summary", **summary)
-        
-        return summary
+
+        return summary

services/risk_analyzer.py

@@ -7,7 +7,6 @@ from typing import Tuple
 from pathlib import Path
 from typing import Optional
 from dataclasses import field
-from dataclasses import dataclass
 from collections import defaultdict
 
 # Add parent directory to path for imports
@@ -17,74 +16,20 @@ from utils.logger import log_info
 from utils.logger import log_error
 from config.risk_rules import RiskRules
 from config.risk_rules import ContractType
-from utils.logger import ContractAnalyzerLogger
+from services.data_models import RiskScore
 from services.term_analyzer import TermAnalyzer
-from services.term_analyzer import UnfavorableTerm
-from services.clause_extractor import RiskClauseExtractor
+from utils.logger import ContractAnalyzerLogger
+from services.data_models import ExtractedClause
+from services.data_models import UnfavorableTerm
+from services.data_models import MissingProtection
+from services.data_models import RiskBreakdownItem
 from services.protection_checker import ProtectionChecker
-from services.protection_checker import MissingProtection
+from services.clause_extractor import RiskClauseExtractor
 from services.contract_classifier import ContractCategory
 from services.contract_classifier import ContractClassifier
 from services.clause_extractor import ComprehensiveClauseExtractor
 
 
-
-@dataclass
-class RiskBreakdownItem:
-    """
-    Individual risk category breakdown
-    """
-    category : str
-    score    : int  # 0-100
-    summary  : str
-    findings : List[str] = field(default_factory = list)
-    
-
-    def to_dict(self) -> Dict[str, Any]:
-        """
-        Convert to dictionary
-        """
-        return {"category" : self.category,
-                "score"    : self.score,
-                "summary"  : self.summary,
-                "findings" : self.findings,
-               }
-
-
-@dataclass
-class RiskScore:
-    """
-    Comprehensive risk score with detailed breakdown
-    """
-    overall_score        : int                       # 0-100
-    risk_level           : str                       # "CRITICAL", "HIGH", "MEDIUM", "LOW"
-    category_scores      : Dict[str, int]            # Scores for each risk category
-    risk_factors         : List[str]                 # Top risk factors
-    detailed_findings    : Dict[str, List[str]]      # Findings by category
-    benchmark_comparison : Dict[str, str]            # Market comparisons
-    risk_breakdown       : List[RiskBreakdownItem]   # Detailed breakdown
-    contract_type        : str                       # Detected contract type
-    unfavorable_terms    : List[Dict]                # Unfavorable terms found
-    missing_protections  : List[Dict]                # Missing critical protections
-    
-
-    def to_dict(self) -> Dict[str, Any]:
-        """
-        Convert to dictionary for serialization
-        """
-        return {"overall_score"        : self.overall_score,
-                "risk_level"           : self.risk_level,
-                "category_scores"      : self.category_scores,
-                "risk_factors"         : self.risk_factors,
-                "detailed_findings"    : self.detailed_findings,
-                "benchmark_comparison" : self.benchmark_comparison,
-                "risk_breakdown"       : [item.to_dict() for item in self.risk_breakdown],
-                "contract_type"        : self.contract_type,
-                "unfavorable_terms"    : self.unfavorable_terms,
-                "missing_protections"  : self.missing_protections,
-               }
-
-
 class RiskAnalyzer:
     """
     Orchestrates all analysis components and calculates comprehensive risk scores
@@ -92,7 +37,7 @@ class RiskAnalyzer:
     Analysis Pipeline:
     1. Contract Classification
     2. Clause Extraction 
-    3.Term Analysis 
+    3. Term Analysis 
     4. Protection Checking 
     5. Risk Scoring
     """
@@ -110,8 +55,7 @@ class RiskAnalyzer:
         
         # Initialize all analysis components
         self.contract_classifier    = ContractClassifier(model_loader = model_loader)
-        self.clause_extractor       = ComprehensiveClauseExtractor(model_loader = model_loader)
-        self.risk_clause_extractor  = None  # Lazy initialization
+        self.risk_clause_extractor  = None  # Will be initialized with contract type
         self.term_analyzer          = TermAnalyzer()
         self.protection_checker     = ProtectionChecker()
         
@@ -121,7 +65,7 @@ class RiskAnalyzer:
     @ContractAnalyzerLogger.log_execution_time("analyze_contract_risk")
     def analyze_contract_risk(self, contract_text: str) -> RiskScore:
         """
-        MAIN ENTRY POINT: Comprehensive contract risk analysis
+        Comprehensive contract risk analysis
         
         Arguments:
         ----------
@@ -134,24 +78,24 @@ class RiskAnalyzer:
         
         log_info("Starting Comprehensive Contract Risk Analysis...", text_length = len(contract_text))
         
-        # CONTRACT CLASSIFICATION
+        # Contract Classification
         contract_category   = self._classify_contract(contract_text = contract_text)
-        log_info("Phase 1 complete: Contract classified", contract_type = contract_category.category)
+        log_info("Contract classified", contract_type = contract_category.category)
         
-        # CLAUSE EXTRACTION  
+        # Clause Extraction: RiskClauseExtractor 
         clauses             = self._extract_clauses(contract_text     = contract_text, 
                                                     contract_category = contract_category,
                                                    )
 
-        log_info("Phase 2 complete: Clauses extracted", num_clauses = len(clauses))
+        log_info("Clauses extracted", num_clauses = len(clauses))
         
-        # UNFAVORABLE TERM ANALYSIS
+        # Unfavourable Term Analysis 
         unfavorable_terms   = self._analyze_unfavorable_terms(contract_text     = contract_text,
                                                               clauses           = clauses, 
                                                               contract_category = contract_category,
                                                              )
 
-        log_info("Phase 3 complete: Unfavorable terms analyzed", num_unfavorable_terms = len(unfavorable_terms))
+        log_info("Unfavorable terms analyzed", num_unfavorable_terms = len(unfavorable_terms))
         
         # MISSING PROTECTIONS ANALYSIS
         missing_protections = self._analyze_missing_protections(contract_text     = contract_text, 
@@ -159,7 +103,7 @@ class RiskAnalyzer:
                                                                 contract_category = contract_category,
                                                                )
 
-        log_info("Phase 4 complete: Missing protections analyzed", num_missing_protections = len(missing_protections))
+        log_info("Missing protections analyzed", num_missing_protections = len(missing_protections))
         
         # RISK SCORING & AGGREGATION
         risk_score          = self._calculate_comprehensive_risk(contract_category    = contract_category,
@@ -208,16 +152,25 @@ class RiskAnalyzer:
 
     def _extract_clauses(self, contract_text: str, contract_category) -> List:
         """
-        Extract clauses from contract
+        Extract clauses from contract using RiskClauseExtractor
         """
-        log_info("Extracting clauses from contract...")
+        log_info("Extracting RISK-FOCUSED clauses from contract...")
         
         try:
-            # Use comprehensive extractor for broad coverage
-            clauses = self.clause_extractor.extract_clauses(contract_text = contract_text, 
-                                                            max_clauses   = 25)
+            # Get contract type enum
+            contract_type_enum         = self._get_contract_type_enum(category_str = contract_category.category)
+            
+            # Initialize RiskClauseExtractor (NOT ComprehensiveClauseExtractor)
+            self.risk_clause_extractor = RiskClauseExtractor(model_loader  = self.model_loader,
+                                                             contract_type = contract_type_enum,
+                                                            )
             
-            log_info("Clause extraction successful",
+            # Use RiskClauseExtractor which outputs risk categories
+            clauses                    = self.risk_clause_extractor.extract_risk_clauses(contract_text = contract_text,
+                                                                                         max_clauses   = 50,
+                                                                                        )
+            
+            log_info("Risk-focused clause extraction successful",
                      total_clauses = len(clauses),
                      categories    = [c.category for c in clauses])
             
@@ -230,13 +183,13 @@ class RiskAnalyzer:
 
     def _analyze_unfavorable_terms(self, contract_text: str, clauses: List, contract_category) -> List[UnfavorableTerm]:
         """
-        Phase 3: Analyze for unfavorable terms
+        Analyze for unfavorable terms (using risk categories from RiskClauseExtractor)
         """
         log_info("Analyzing unfavorable terms...")
         
         try:
             # Initialize term analyzer with contract type
-            contract_type_enum = self._get_contract_type_enum(contract_category.category)
+            contract_type_enum = self._get_contract_type_enum(category_str = contract_category.category)
             self.term_analyzer = TermAnalyzer(contract_type = contract_type_enum)
             
             unfavorable_terms = self.term_analyzer.analyze_unfavorable_terms(contract_text = contract_text,
@@ -244,7 +197,7 @@ class RiskAnalyzer:
             
             log_info("Unfavorable terms analysis successful",
                      total_terms = len(unfavorable_terms),
-                     critical    = sum(1 for t in unfavorable_terms if t.severity == "critical"))
+                     critical    = sum(1 for t in unfavorable_terms if (t.severity == "critical")))
             
             return unfavorable_terms
             
@@ -255,21 +208,21 @@ class RiskAnalyzer:
 
     def _analyze_missing_protections(self, contract_text: str, clauses: List, contract_category) -> List[MissingProtection]:
         """
-        Phase 4: Analyze for missing protections
+        Analyze for missing protections
         """
         log_info("Analyzing missing protections...")
         
         try:
             # Initialize protection checker with contract type
-            contract_type_enum = self._get_contract_type_enum(contract_category.category)
+            contract_type_enum      = self._get_contract_type_enum(category_str = contract_category.category)
             self.protection_checker = ProtectionChecker(contract_type = contract_type_enum)
             
-            missing_protections = self.protection_checker.check_missing_protections(contract_text = contract_text,
-                                                                                    clauses       = clauses)
+            missing_protections     = self.protection_checker.check_missing_protections(contract_text = contract_text,
+                                                                                        clauses       = clauses)
             
             log_info("Missing protections analysis successful",
                      total_missing = len(missing_protections),
-                     critical      = sum(1 for p in missing_protections if p.importance == "critical"))
+                     critical      = sum(1 for p in missing_protections if (p.importance == "critical")))
             
             return missing_protections
             
@@ -281,12 +234,12 @@ class RiskAnalyzer:
     def _calculate_comprehensive_risk(self, contract_category, clauses: List, unfavorable_terms: List[UnfavorableTerm], missing_protections: List[MissingProtection],
                                       contract_text: str) -> RiskScore:
         """
-        Phase 5: Calculate comprehensive risk score using all analysis results
+        Calculate comprehensive risk score using all analysis results
         """
         log_info("Calculating comprehensive risk score...")
         
         # Get contract type for risk rule adjustments
-        contract_type_enum = self._get_contract_type_enum(contract_category.category)
+        contract_type_enum = self._get_contract_type_enum(category_str = contract_category.category)
         adjusted_weights   = self.rules.get_adjusted_weights(contract_type_enum)
         
         # Initialize scoring containers
@@ -296,13 +249,13 @@ class RiskAnalyzer:
         
         # Calculate risk for each category
         for risk_category in adjusted_weights.keys():
-            category_risk = self._calculate_category_risk(risk_category        = risk_category,
-                                                          contract_type        = contract_type_enum,
-                                                          clauses              = clauses,
-                                                          unfavorable_terms    = unfavorable_terms,
-                                                          missing_protections  = missing_protections,
-                                                          contract_text        = contract_text,
-                                                         )
+            category_risk                    = self._calculate_category_risk(risk_category        = risk_category,
+                                                                             contract_type        = contract_type_enum,
+                                                                             clauses              = clauses,
+                                                                             unfavorable_terms    = unfavorable_terms,
+                                                                             missing_protections  = missing_protections,
+                                                                             contract_text        = contract_text,
+                                                                            )
             
             category_scores[risk_category]   = category_risk["score"]
             detailed_findings[risk_category] = category_risk["findings"]
@@ -355,7 +308,7 @@ class RiskAnalyzer:
         
         for term in category_terms:
             # Scale appropriately
-            base_score += term.risk_score * 0.1  
+            base_score += term.risk_score * 0.4  
 
             findings.append(f"{term.term}: {term.explanation}")
         
@@ -363,7 +316,8 @@ class RiskAnalyzer:
         category_protections = [p for p in missing_protections if risk_category in p.categories]
         
         for protection in category_protections:
-            base_score += protection.risk_score * 0.15
+            base_score += protection.risk_score * 0.3
+            
             findings.append(f"Missing: {protection.protection}")
         
         # Score from clauses in this category
@@ -376,7 +330,8 @@ class RiskAnalyzer:
                                                     risk_category   = risk_category,
                                                     contract_type   = contract_type,
                                                    )
-            base_score += clause_risk["score"]
+
+            base_score += clause_risk["score"] * 0.3
 
             findings.extend(clause_risk["findings"])
         
@@ -395,57 +350,41 @@ class RiskAnalyzer:
 
     def _get_clauses_for_risk_category(self, clauses: List, risk_category: str) -> List:
         """
-        Map clauses to risk categories
+        Map clauses to risk categories (now clauses are already in risk categories)
         """
-        category_mapping = {"restrictive_covenants" : ["non_compete", "confidentiality"],
-                            "termination_rights"    : ["termination"],
-                            "penalties_liability"   : ["indemnification", "liability"],
-                            "compensation_benefits" : ["compensation"],
-                            "intellectual_property" : ["intellectual_property"],
-                            "confidentiality"       : ["confidentiality"],
-                            "liability_indemnity"   : ["indemnification", "liability"],
-                            "governing_law"         : ["dispute_resolution"],
-                            "payment_terms"         : ["compensation"],
-                            "warranties"            : ["warranty"],
-                            "dispute_resolution"    : ["dispute_resolution"],
-                            "assignment_change"     : ["assignment", "amendment"],
-                            "insurance"             : ["insurance"],
-                            "force_majeure"         : ["force_majeure"],
-                           }
-        
-        target_categories = category_mapping.get(risk_category, [])
-        
-        return [c for c in clauses if c.category in target_categories]
-    
+        # clauses.category is already a risk category from RiskClauseExtractor
+        clauses_for_risk_category = [c for c in clauses if (c.category == risk_category)]
+        
+        return clauses_for_risk_category
+
 
     def _analyze_clause_risk(self, clause, risk_category: str, contract_type: ContractType) -> Dict:
         """
         Analyze individual clause risk using RiskRules factors
         """
-        risk_factors = self.rules.CLAUSE_RISK_FACTORS
-        
-        # Map clause category to risk factors
-        factor_mapping = {"non_compete"           : "restrictive_covenants",
-                          "termination"           : "termination_rights", 
-                          "indemnification"       : "liability_indemnity",
-                          "compensation"          : "compensation_benefits",
-                          "intellectual_property" : "intellectual_property",
-                          "confidentiality"       : "confidentiality",
-                          "liability"             : "penalties_liability",
-                          "warranty"              : "warranties",
-                          "dispute_resolution"    : "dispute_resolution",
-                          "assignment"            : "assignment_change",
-                          "amendment"             : "assignment_change",
-                          "insurance"             : "insurance",
-                          "force_majeure"         : "force_majeure",
-                         }
-        
-        risk_factor_key = factor_mapping.get(clause.category)
-        
-        if not risk_factor_key or risk_factor_key not in risk_factors:
+        risk_factors        = self.rules.CLAUSE_RISK_FACTORS
+        
+        # Map RISK category (e.g., "restrictive_covenants") to CLAUSE category (e.g., "non_compete")
+        factor_mapping      = {"restrictive_covenants" : "non_compete",
+                               "termination_rights"    : "termination", 
+                               "liability_indemnity"   : "indemnification",
+                               "compensation_benefits" : "compensation",
+                               "intellectual_property" : "intellectual_property",
+                               "confidentiality"       : "confidentiality",
+                               "penalties_liability"   : "liability",
+                               "warranties"            : "warranty",
+                               "dispute_resolution"    : "dispute_resolution",
+                               "assignment_change"     : "assignment", 
+                               "insurance"             : "insurance",
+                               "force_majeure"         : "force_majeure",
+                              }
+        
+        clause_category_key = factor_mapping.get(risk_category)
+        
+        if not clause_category_key or clause_category_key not in risk_factors:
             return {"score": 0, "findings": []}
         
-        factor_config = risk_factors[risk_factor_key]
+        factor_config = risk_factors[clause_category_key]
         base_risk     = factor_config.get("base_risk", 50)
         text_lower    = clause.text.lower()
         
@@ -461,13 +400,14 @@ class RiskAnalyzer:
                 findings.append(f"Red flag: '{red_flag}' ({severity} risk by {abs(adjustment)})")
         
         # Apply contract-type specific multiplier
-        type_adjustments = self.rules.CONTRACT_TYPE_ADJUSTMENTS.get(contract_type.value, {})
+        type_adjustments    = self.rules.CONTRACT_TYPE_ADJUSTMENTS.get(contract_type.value, {})
         category_multiplier = type_adjustments.get(risk_category, 1.0)
         
-        risk_score *= category_multiplier
+        risk_score         *= category_multiplier
         
         return {"score"    : max(0, min(100, risk_score)),
-                "findings" : findings}
+                "findings" : findings,
+               }
     
 
     def _calculate_weighted_score(self, category_scores: Dict[str, int], adjusted_weights: Dict[str, float]) -> int:

services/summary_generator.py

@@ -1,417 +1,337 @@
 # DEPENDENCIES
-import logging
-from typing import Dict, List, Optional, Any
-from dataclasses import dataclass
-
-from utils.logger import ContractAnalyzerLogger
-from model_manager.llm_manager import LLMManager, LLMProvider
-from services.risk_analyzer import RiskScore
-from services.llm_interpreter import RiskInterpretation
-from services.negotiation_engine import NegotiationPlaybook
-from services.contract_classifier import ContractCategory
-
-logger = ContractAnalyzerLogger.get_logger()
+import sys
+from typing import Any
+from typing import Dict
+from typing import List
+from pathlib import Path
+from typing import Optional
 
+# Add parent directory to path for imports
+sys.path.append(str(Path(__file__).parent.parent))
 
-@dataclass
-class SummaryContext:
-    """
-    Context data for comprehensive summary generation
-    """
-    contract_type: str
-    risk_score: int
-    risk_level: str
-    category_scores: Dict[str, int]
-    unfavorable_terms: List[Dict]
-    missing_protections: List[Dict]
-    clauses: List
-    key_findings: List[str]
-    # NEW: Full pipeline integration
-    risk_interpretation: Optional[RiskInterpretation] = None
-    negotiation_playbook: Optional[NegotiationPlaybook] = None
-    contract_text_preview: Optional[str] = None
-    contract_metadata: Optional[Dict[str, Any]] = None
+from services.risk_analyzer import RiskScore
+from services.data_models import SummaryContext
+from utils.logger import ContractAnalyzerLogger 
+from model_manager.llm_manager import LLMManager
+from model_manager.llm_manager import LLMProvider
+from services.data_models import ContractCategory
+from services.data_models import RiskInterpretation
+from services.data_models import NegotiationPlaybook
 
 
 class SummaryGenerator:
     """
-    LLM-powered executive summary generator for contract analysis
-    Generates professional, detailed executive summaries using ALL pipeline outputs
+    LLM-powered executive summary generator for contract analysis : Generates professional, detailed executive summaries using ALL pipeline outputs
     """
-    
     def __init__(self, llm_manager: Optional[LLMManager] = None):
         """
         Initialize the summary generator
         
-        Args:
-            llm_manager: LLM manager instance (if None, creates one with default settings)
+        Arguments:
+        ----------
+            llm_manager { LLMManager } : LLM manager instance (if None, creates one with default settings)
         """
         self.llm_manager = llm_manager or LLMManager()
-        self.logger = ContractAnalyzerLogger.get_logger()
-        
-        logger.info("Summary generator initialized")
-
-    # ENHANCED: Main entry point with full pipeline integration
-    def generate_comprehensive_summary(self,
-                                     contract_text: str,
-                                     classification: ContractCategory,
-                                     risk_analysis: RiskScore,
-                                     risk_interpretation: RiskInterpretation,
-                                     negotiation_playbook: NegotiationPlaybook,
-                                     unfavorable_terms: List[Dict],
-                                     missing_protections: List[Dict],
-                                     clauses: List) -> str:
-        """
-        Generate comprehensive executive summary using ALL pipeline outputs
-        
-        Args:
-            contract_text: Original contract text (for context)
-            classification: Contract classification results
-            risk_analysis: Complete risk analysis
-            risk_interpretation: LLM-enhanced risk explanations
-            negotiation_playbook: Comprehensive negotiation strategy
-            unfavorable_terms: Detected unfavorable terms
-            missing_protections: Missing protections
-            clauses: Extracted clauses
+        self.logger      = ContractAnalyzerLogger.get_logger() 
+        
+        self.logger.info("Summary generator initialized")
+
+
+    # Main entry point with full pipeline integration
+    def generate_executive_summary(self, contract_text: str, classification: ContractCategory, risk_analysis: RiskScore, risk_interpretation: RiskInterpretation,
+                                   negotiation_playbook: NegotiationPlaybook, unfavorable_terms: List, missing_protections: List, clauses: List) -> str:
+        """
+        Generate executive summary using all the pipeline outputs
+        
+        Arguments:
+        ----------
+            contract_text               { str }          : Original contract text (for context)
+            
+            classification       { ContractCategory }    : Contract classification results
+            
+            risk_analysis            { RiskScore }       : Complete risk analysis
+            
+            risk_interpretation  { RiskInterpretation }  : LLM-enhanced risk explanations
+            
+            negotiation_playbook { NegotiationPlaybook } : Comprehensive negotiation strategy
+            
+            unfavorable_terms            { List }        : Detected unfavorable terms
+            
+            missing_protections          { List }        : Missing protections
+            
+            clauses                      { List }        : Extracted clauses
             
         Returns:
-            Generated executive summary string
+        --------
+                             { str }                     : Generated executive summary string
         """
         try:
-            # Prepare enhanced context with ALL pipeline data
-            context = self._prepare_comprehensive_context(
-                contract_text=contract_text,
-                classification=classification,
-                risk_analysis=risk_analysis,
-                risk_interpretation=risk_interpretation,
-                negotiation_playbook=negotiation_playbook,
-                unfavorable_terms=unfavorable_terms,
-                missing_protections=missing_protections,
-                clauses=clauses
-            )
+            # Prepare context with all pipeline data
+            context = self._prepare_summary_context(contract_text        = contract_text,
+                                                    classification       = classification,
+                                                    risk_analysis        = risk_analysis,
+                                                    risk_interpretation  = risk_interpretation,
+                                                    negotiation_playbook = negotiation_playbook,
+                                                    unfavorable_terms    = unfavorable_terms,
+                                                    missing_protections  = missing_protections,
+                                                    clauses              = clauses,
+                                                   )
             
-            # Generate enhanced summary using LLM
-            summary = self._generate_enhanced_summary(context)
+            # Generate summary using LLM
+            summary = self._generate_summary(context = context)
             
-            logger.info(f"Comprehensive executive summary generated - Risk: {context.risk_score}/100 ({context.risk_level})")
+            self.logger.info(f"Executive summary generated - Risk: {context.risk_score}/100 ({context.risk_level})") 
             
             return summary
             
         except Exception as e:
-            logger.error(f"Failed to generate comprehensive summary: {e}")
+            self.logger.error(f"Failed to generate comprehensive summary: {repr(e)}") 
             
-            # Enhanced fallback with available data
-            return self._generate_enhanced_fallback_summary(
-                contract_text=contract_text,
-                classification=classification,
-                risk_analysis=risk_analysis,
-                unfavorable_terms=unfavorable_terms,
-                missing_protections=missing_protections
-            )
+            # Fallback with available data
+            return self._generate_fallback_summary(contract_text       = contract_text,
+                                                   classification      = classification,
+                                                   risk_analysis       = risk_analysis,
+                                                   unfavorable_terms   = unfavorable_terms,
+                                                   missing_protections = missing_protections,
+                                                  )
     
-    def _prepare_comprehensive_context(self,
-                                    contract_text: str,
-                                    classification: ContractCategory,
-                                    risk_analysis: RiskScore,
-                                    risk_interpretation: RiskInterpretation,
-                                    negotiation_playbook: NegotiationPlaybook,
-                                    unfavorable_terms: List[Dict],
-                                    missing_protections: List[Dict],
-                                    clauses: List) -> SummaryContext:
-        """Prepare comprehensive context with ALL pipeline data"""
-        
-        # Extract contract preview
-        contract_preview = contract_text[:500] + "..." if len(contract_text) > 500 else contract_text
-        
-        # Extract key findings from ALL sources
-        key_findings = self._extract_comprehensive_findings(
-            risk_analysis=risk_analysis,
-            risk_interpretation=risk_interpretation,
-            negotiation_playbook=negotiation_playbook,
-            unfavorable_terms=unfavorable_terms,
-            missing_protections=missing_protections,
-            clauses=clauses
-        )
-        
+
+    def _prepare_summary_context(self, contract_text: str, classification: ContractCategory, risk_analysis: RiskScore, risk_interpretation: RiskInterpretation,
+                                 negotiation_playbook: NegotiationPlaybook, unfavorable_terms: List[Dict], missing_protections: List[Dict], clauses: List) -> SummaryContext:
+        """
+        Prepare summary context with all pipeline data
+        """
+        # Handle null negotiation_playbook
+        walk_away_count = 0
+
+        if negotiation_playbook and hasattr(negotiation_playbook, 'walk_away_items'):
+            walk_away_count = len(negotiation_playbook.walk_away_items)
+            
+        # Extract contract text
+        contract_preview = contract_text 
+        
+        # Extract key findings from all sources
+        key_findings     = self._extract_findings(risk_analysis        = risk_analysis,
+                                                  risk_interpretation  = risk_interpretation,
+                                                  negotiation_playbook = negotiation_playbook,
+                                                  unfavorable_terms    = unfavorable_terms,
+                                                  missing_protections  = missing_protections,
+                                                  clauses              = clauses,
+                                                 )
+                                                            
         # Prepare metadata
-        metadata = {
-            "contract_length": len(contract_text),
-            "clauses_analyzed": len(clauses),
-            "critical_issues": len([t for t in unfavorable_terms if self._get_severity(t) == "critical"]),
-            "walk_away_items": len(negotiation_playbook.walk_away_items) if negotiation_playbook else 0
-        }
-        
-        return SummaryContext(
-            contract_type=classification.category,
-            risk_score=risk_analysis.overall_score,
-            risk_level=risk_analysis.risk_level,
-            category_scores=risk_analysis.category_scores,
-            unfavorable_terms=unfavorable_terms,
-            missing_protections=missing_protections,
-            clauses=clauses,
-            key_findings=key_findings,
-            risk_interpretation=risk_interpretation,
-            negotiation_playbook=negotiation_playbook,
-            contract_text_preview=contract_preview,
-            contract_metadata=metadata
-        )
+        metadata         = {"contract_length"  : len(contract_text),
+                            "clauses_analyzed" : len(clauses),
+                            "critical_issues"  : len([t for t in unfavorable_terms if (self._get_severity(t) == "critical")]),
+                            "walk_away_items"  : walk_away_count,
+                           }
+         
+        return SummaryContext(contract_type         = classification.category,
+                              risk_score            = risk_analysis.overall_score,
+                              risk_level            = risk_analysis.risk_level,
+                              category_scores       = risk_analysis.category_scores,
+                              unfavorable_terms     = unfavorable_terms,
+                              missing_protections   = missing_protections,
+                              clauses               = clauses,
+                              key_findings          = key_findings,
+                              risk_interpretation   = risk_interpretation,
+                              negotiation_playbook  = negotiation_playbook,
+                              contract_text_preview = contract_preview,
+                              contract_metadata     = metadata,
+                             )
+
     
-    def _extract_comprehensive_findings(self,
-                                      risk_analysis: RiskScore,
-                                      risk_interpretation: RiskInterpretation,
-                                      negotiation_playbook: NegotiationPlaybook,
-                                      unfavorable_terms: List[Dict],
-                                      missing_protections: List[Dict],
-                                      clauses: List) -> List[str]:
-        """Extract comprehensive findings from ALL analysis components"""
-        
-        findings = []
-        
-        # 1. Overall risk context
-        if risk_analysis.overall_score >= 80:
+    def _extract_findings(self, risk_analysis: RiskScore, risk_interpretation: RiskInterpretation, negotiation_playbook: NegotiationPlaybook,
+                          unfavorable_terms: List[Dict], missing_protections: List[Dict], clauses: List) -> List[str]:
+        """
+        Extract findings from all analysis components
+        """
+        findings = list()
+        
+        # Overall risk context
+        if (risk_analysis.overall_score >= 80):
             findings.append("CRITICAL RISK LEVEL: Contract presents unacceptable risk requiring immediate attention")
-        elif risk_analysis.overall_score >= 60:
+
+        elif (risk_analysis.overall_score >= 60):
             findings.append("HIGH RISK LEVEL: Significant concerns requiring substantial negotiation")
         
-        # 2. Critical unfavorable terms
-        critical_terms = [t for t in unfavorable_terms if self._get_severity(t) == "critical"]
+        # Critical unfavorable terms
+        critical_terms = [t for t in unfavorable_terms if (self._get_severity(t) == "critical")]
+        
         if critical_terms:
             findings.append(f"{len(critical_terms)} CRITICAL unfavorable terms identified")
             for term in critical_terms[:2]:
-                term_name = self._get_term_name(term)
+                term_name = self._get_term_name(term = term)
+                
                 findings.append(f"Critical: {term_name}")
         
-        # 3. Critical missing protections
-        critical_protections = [p for p in missing_protections if self._get_importance(p) == "critical"]
+        # Critical missing protections
+        critical_protections = [p for p in missing_protections if (self._get_importance(p) == "critical")]
+        
         if critical_protections:
             findings.append(f"{len(critical_protections)} CRITICAL protections missing")
             for prot in critical_protections[:2]:
-                prot_name = self._get_protection_name(prot)
+                prot_name = self._get_protection_name(protection = prot)
+                
                 findings.append(f"Missing: {prot_name}")
         
-        # 4. High-risk categories
-        high_risk_categories = [cat for cat, score in risk_analysis.category_scores.items() 
-                               if score >= 70]
+        # High-risk categories
+        high_risk_categories = [cat for cat, score in risk_analysis.category_scores.items() if (score >= 70)]
         if high_risk_categories:
             findings.append(f"High-risk categories: {', '.join(high_risk_categories)}")
         
-        # 5. Walk-away items from negotiation playbook
+        # Walk-away items from negotiation playbook
         if negotiation_playbook and negotiation_playbook.walk_away_items:
             findings.append(f"{len(negotiation_playbook.walk_away_items)} potential deal-breakers identified")
         
-        # 6. Key concerns from risk interpretation
+        # Key concerns from risk interpretation
         if risk_interpretation and risk_interpretation.key_concerns:
             top_concerns = risk_interpretation.key_concerns[:2]
             for concern in top_concerns:
                 findings.append(f"Key concern: {concern}")
         
-        return findings[:8]  # Return top 8 findings
+        return findings  
     
-    def _generate_enhanced_summary(self, context: SummaryContext) -> str:
-        """Generate enhanced summary using comprehensive context"""
-        
-        prompt = self._build_enhanced_summary_prompt(context)
-        system_prompt = self._build_enhanced_system_prompt()
+
+    def _generate_summary(self, context: SummaryContext) -> str:
+        """
+        Generate enhanced summary using comprehensive context
+        """
+        prompt        = self._build_summary_prompt(context)
+        system_prompt = self._build_system_prompt()
         
         try:
-            response = self.llm_manager.complete(
-                prompt=prompt,
-                system_prompt=system_prompt,
-                temperature=0.3,
-                max_tokens=500,  # Increased for comprehensive summary
-                json_mode=False
-            )
-            
+            response = self.llm_manager.complete(prompt        = prompt,
+                                                 system_prompt = system_prompt,
+                                                 temperature   = 0.3,
+                                                 max_tokens    = 500, 
+                                                 json_mode     = False,
+                                                )
+              
             if response.success and response.text.strip():
-                return self._clean_summary_response(response.text)
+                return self._clean_summary_response(text = response.text)
+            
             else:
                 raise ValueError(f"LLM generation failed: {response.error_message}")
                 
         except Exception as e:
-            logger.error(f"Enhanced LLM summary generation failed: {e}")
+            self.logger.error(f"Enhanced LLM summary generation failed: {e}")
             # Fallback to basic summary
-            return self._generate_enhanced_fallback_summary_from_context(context)
+            return self._generate_fallback_summary_from_context(context = context)
     
-    def _build_enhanced_system_prompt(self) -> str:
-        """Build enhanced system prompt for comprehensive summary generation"""
-        
-        return """You are a senior legal analyst and strategic advisor specializing in contract risk assessment. 
 
-YOUR ROLE:
-Generate comprehensive, professional executive summaries that synthesize technical risk analysis with practical business implications.
+    def _build_system_prompt(self) -> str:
+        """
+        Build system prompt for executive summary generation
+        """
+        system_prompt =  """
+                            You are a senior contract risk analyst. Generate CONCISE executive summaries.
 
-KEY REQUIREMENTS:
-1. Write in formal, professional business language suitable for executives
-2. Synthesize ALL analysis components into cohesive narrative
-3. Focus on strategic implications and decision-making
-4. Maintain objective, factual tone while highlighting critical risks
-5. Keep summary length between 150-300 words
-6. Structure: Overall assessment → Critical risks → Strategic implications → Recommended approach
+                            CRITICAL REQUIREMENTS:
+                            1. Maximum 120 words (strict limit)
+                            2. Must mention SPECIFIC clause numbers (e.g., Clause 8.2, Clause 9.5)
+                            3. Direct, urgent tone - no hedging or academic language
+                            4. Focus ONLY on top 3 critical risks
 
-CONTENT FOCUS:
-- Start with overall risk assessment and contract type context
-- Highlight 2-3 most critical risks with practical consequences  
-- Mention key missing protections and their business impact
-- Reference negotiation strategy and deal-breakers
-- Conclude with clear recommended next steps
+                            STRUCTURE (3-4 sentences total):
+                            Sentence 1: Overall risk assessment with contract type
+                            Sentence 2-3: Top 2-3 critical risks with SPECIFIC clause references
+                            Sentence 4: Brief actionable conclusion
 
-WRITING STYLE:
-- Executive-level business language
-- Focus on decision-making implications
-- Avoid markdown formatting
-- Be direct, actionable, and strategic
-- Connect legal risks to business outcomes
+                            TONE EXAMPLES:
+                            ✅ GOOD: "This employment agreement is heavily skewed in favor of the Employer. Clause 8.2 fails to define post-probation salary. Clause 11.2 allows illegal wage forfeiture."
+                            ❌ BAD: "The comprehensive analysis indicates that there are several concerns that require attention. It is essential to carefully review..."
 
-OUTPUT FORMAT:
-Return only the executive summary text, no headings, no bullet points, no role rescription, just clean paragraph text. Also write the summary in passive voice only."""
+                            FORBIDDEN PHRASES:
+                            - "comprehensive analysis"
+                            - "it is essential to"
+                            - "requires attention"
+                            - "should be reviewed"
+                            - "it is recommended"
 
-    def _build_enhanced_summary_prompt(self, context: SummaryContext) -> str:
-        """Build detailed prompt for comprehensive summary generation"""
-        
-        # Build comprehensive context sections
-        risk_context = self._build_enhanced_risk_context(context)
-        critical_issues = self._build_critical_issues_context(context)
-        strategic_context = self._build_strategic_context(context)
-        negotiation_context = self._build_negotiation_context(context)
+                            OUTPUT: Pure paragraph text only. No formatting, no bullets, no headers.
+                         """
         
-        prompt = f"""
-COMPREHENSIVE CONTRACT ANALYSIS:
-
-{risk_context}
-
-{critical_issues}
-
-{strategic_context}
-
-{negotiation_context}
+        return system_prompt
 
-GENERATION INSTRUCTIONS:
-Based on the comprehensive analysis above, write a professional executive summary that:
 
-1. Starts with overall risk assessment for this {context.contract_type} agreement
-2. Highlights the most critical risks and their business implications
-3. Mentions key missing protections and unfavorable terms
-4. References the negotiation strategy and potential deal-breakers  
-5. Provides clear, actionable recommendations for next steps
-
-Focus on synthesizing all analysis components into a cohesive strategic assessment that supports executive decision-making.
-"""
-        return prompt
-    
-    def _build_enhanced_risk_context(self, context: SummaryContext) -> str:
-        """Build enhanced risk assessment context"""
-        
-        risk_level_descriptions = {
-            "CRITICAL": "CRITICAL level of risk requiring immediate executive attention",
-            "HIGH": "HIGH level of risk requiring significant review and negotiation",
-            "MEDIUM": "MODERATE level of risk with specific concerns to address",
-            "LOW": "LOW level of risk, generally favorable with minor improvements needed"
-        }
-        
-        risk_desc = risk_level_descriptions.get(context.risk_level, "Requires professional review")
-        
-        text = f"OVERALL RISK ASSESSMENT:\n"
-        text += f"- Risk Score: {context.risk_score}/100 ({risk_desc})\n"
-        text += f"- Contract Type: {context.contract_type.replace('_', ' ').title()}\n"
-        text += f"- Analysis Scope: {context.contract_metadata.get('clauses_analyzed', 0)} clauses analyzed\n"
-        
-        # Top risk categories
-        if context.category_scores:
-            high_risk_categories = [(cat, score) for cat, score in context.category_scores.items() 
-                                   if score >= 60]
-            if high_risk_categories:
-                text += "- Highest Risk Categories:\n"
-                for category, score in sorted(high_risk_categories, key=lambda x: x[1], reverse=True)[:3]:
-                    category_name = category.replace('_', ' ').title()
-                    text += f"  * {category_name}: {score}/100\n"
-        
-        return text
-    
-    def _build_critical_issues_context(self, context: SummaryContext) -> str:
-        """Build context about critical issues"""
+    def _build_summary_prompt(self, context: SummaryContext) -> str:
+        """
+        Build prompt for executive summary generation
+        """
+        # Extract top critical issues only
+        critical_terms       = [t for t in context.unfavorable_terms if self._get_severity(t) == "critical"][:10]
         
-        text = "CRITICAL ISSUES IDENTIFIED:\n"
+        critical_protections = [p for p in context.missing_protections if self._get_importance(p) == "critical"][:10]
+        
+        # Build concise context
+        critical_issues_text = ""
         
-        # Critical unfavorable terms
-        critical_terms = [t for t in context.unfavorable_terms if self._get_severity(t) == "critical"]
         if critical_terms:
-            text += f"- Critical Unfavorable Terms: {len(critical_terms)}\n"
-            for term in critical_terms[:2]:
-                term_name = self._get_term_name(term)
-                explanation = self._get_explanation(term)
-                text += f"  * {term_name}: {explanation}\n"
+            critical_issues_text += "CRITICAL UNFAVORABLE TERMS:\n"
+            
+            for term in critical_terms:
+                clause_reference      = self._get_clause_reference(term = term)
+                term_name             = self._get_term_name(term = term)
+                critical_issues_text += f"- {clause_reference}: {term_name}\n"
         
-        # Critical missing protections
-        critical_protections = [p for p in context.missing_protections if self._get_importance(p) == "critical"]
         if critical_protections:
-            text += f"- Critical Missing Protections: {len(critical_protections)}\n"
-            for prot in critical_protections[:2]:
-                prot_name = self._get_protection_name(prot)
-                explanation = self._get_explanation(prot)
-                text += f"  * {prot_name}: {explanation}\n"
-        
-        # Key concerns from risk interpretation
-        if context.risk_interpretation and context.risk_interpretation.key_concerns:
-            text += f"- Key Strategic Concerns: {len(context.risk_interpretation.key_concerns)}\n"
-            for concern in context.risk_interpretation.key_concerns[:2]:
-                text += f"  * {concern}\n"
-        
-        if not critical_terms and not critical_protections:
-            text += "- No critical issues identified\n"
-        
-        return text
-    
-    def _build_strategic_context(self, context: SummaryContext) -> str:
-        """Build strategic context from risk interpretation"""
-        
-        text = "STRATEGIC ASSESSMENT:\n"
-        
-        if context.risk_interpretation:
-            text += f"- Overall Risk Explanation: {context.risk_interpretation.overall_risk_explanation}\n"
+            critical_issues_text += "\nCRITICAL MISSING PROTECTIONS:\n"
             
-            if context.risk_interpretation.market_comparison:
-                text += f"- Market Context: {context.risk_interpretation.market_comparison}\n"
-        
-        # Contract complexity context
-        if context.contract_metadata:
-            if context.contract_metadata['contract_length'] > 10000:
-                text += "- Complex Agreement: Extensive contract requiring detailed review\n"
-            elif context.contract_metadata['critical_issues'] > 0:
-                text += "- High Attention Required: Contains critical issues needing resolution\n"
+            for protection in critical_protections:
+                protection_name       = self._get_protection_name(protection = protection)
+                critical_issues_text += f"- {protection_name}\n"
         
-        return text
-    
-    def _build_negotiation_context(self, context: SummaryContext) -> str:
-        """Build negotiation strategy context"""
+        # Determine risk tone
+        if (context.risk_score >= 80):
+            risk_tone = "heavily skewed/very high risk/presents unacceptable risk"
         
-        text = "NEGOTIATION STRATEGY:\n"
-        
-        if context.negotiation_playbook:
-            text += f"- Overall Approach: {context.negotiation_playbook.overall_strategy}\n"
-            
-            if context.negotiation_playbook.walk_away_items:
-                text += f"- Deal-Breakers: {len(context.negotiation_playbook.walk_away_items)} critical items\n"
-                for item in context.negotiation_playbook.walk_away_items[:2]:
-                    text += f"  * {item}\n"
-            
-            if context.negotiation_playbook.critical_points:
-                text += f"- Priority Negotiation Points: {len(context.negotiation_playbook.critical_points)}\n"
-            
-            text += f"- Timing Guidance: {context.negotiation_playbook.timing_guidance}\n"
+        elif (context.risk_score >= 60):
+            risk_tone = "significantly unfavorable/high risk/substantial concerns"
+
+        elif (context.risk_score >= 40):
+            risk_tone = "moderately concerning/notable risk/requires negotiation"
+
         else:
-            text += "- Standard negotiation approach recommended\n"
-        
-        return text
+            risk_tone = "generally reasonable/manageable risk/standard concerns"
+        
+        summary_prompt = f"""
+                             CONTRACT ANALYSIS DATA:
+                            
+                             - Type: {context.contract_type.replace('_', ' ').title()}
+                             - Risk Score: {context.risk_score}/100
+                             - Risk Level: {context.risk_level}
+                             - Appropriate Tone: {risk_tone}
+
+                             {critical_issues_text}
+
+                             TASK:
+                             Write a 100-120 word executive summary following this EXACT structure:
+
+                             1. First sentence: "This [contract type] [risk assessment with tone matching score]"
+                             2. Second sentence: State top critical risk with SPECIFIC clause number
+                             3. Third sentence: State second critical risk with SPECIFIC clause number
+                             4. Fourth sentence: Brief conclusion about action needed
+
+                             EXAMPLE (for 85/100 risk employment contract):
+                             "This employment agreement is heavily skewed in favor of the Employer, presenting a very high risk to the Employee. Key concerns include Clause 9.5's extremely broad 24-month non-compete against the entire industry, and Clause 11.2's punitive penalty allowing forfeiture of earned wages. The termination clauses in Clause 17 are highly asymmetrical, giving the employer unilateral power. Significant negotiation is required before signing."
+
+                             YOUR TURN - Generate summary for THIS contract:
+                          """
+                        
+        return summary_prompt
     
+
     def _clean_summary_response(self, text: str) -> str:
-        """Clean and format the LLM response"""
-        
+        """
+        Clean and format the LLM response
+        """
         # Remove any markdown formatting
-        text = text.replace('**', '').replace('*', '').replace('#', '')
+        text          = text.replace('**', '').replace('*', '').replace('#', '')
         
         # Remove common LLM artifacts and empty lines
-        lines = text.split('\n')
-        cleaned_lines = []
+        lines         = text.split('\n')
+        cleaned_lines = list()
         
         for line in lines:
             line = line.strip()
@@ -431,150 +351,166 @@ Focus on synthesizing all analysis components into a cohesive strategic assessme
         
         return summary
     
-    def _generate_enhanced_fallback_summary(self,
-                                          contract_text: str,
-                                          classification: ContractCategory,
-                                          risk_analysis: RiskScore,
-                                          unfavorable_terms: List[Dict],
-                                          missing_protections: List[Dict]) -> str:
-        """Generate enhanced fallback summary"""
-        
+
+    def _generate_fallback_summary(self, contract_text: str, classification: ContractCategory, risk_analysis: RiskScore, unfavorable_terms: List[Dict], missing_protections: List[Dict]) -> str:
+        """
+        Generate enhanced fallback summary
+        """
         contract_type_display = classification.category.replace('_', ' ').title()
         
         # Count critical items
-        critical_terms = len([t for t in unfavorable_terms if self._get_severity(t) == "critical"])
-        critical_protections = len([p for p in missing_protections if self._get_importance(p) == "critical"])
+        critical_terms        = len([t for t in unfavorable_terms if (self._get_severity(t) == "critical")])
+        critical_protections  = len([p for p in missing_protections if (self._get_importance(p) == "critical")])
         
-        # Enhanced risk assessment
-        if risk_analysis.overall_score >= 80:
+        # Risk assessment
+        if (risk_analysis.overall_score >= 80):
             risk_assessment = f"This {contract_type_display} presents a CRITICAL level of risk"
-            action = "requires immediate executive attention and significant revision before consideration"
-        elif risk_analysis.overall_score >= 60:
+            action          = "requires immediate executive attention and significant revision before consideration"
+        
+        elif (risk_analysis.overall_score >= 60):
             risk_assessment = f"This {contract_type_display} presents a HIGH level of risk" 
-            action = "requires careful legal review and substantial negotiation to mitigate key concerns"
-        elif risk_analysis.overall_score >= 40:
+            action          = "requires careful legal review and substantial negotiation to mitigate key concerns"
+        
+        elif (risk_analysis.overall_score >= 40):
             risk_assessment = f"This {contract_type_display} presents a MODERATE level of risk"
-            action = "requires professional review and selective negotiation on specific provisions"
+            action          = "requires professional review and selective negotiation on specific provisions"
+        
         else:
             risk_assessment = f"This {contract_type_display} presents a LOW level of risk"
             action = "appears generally reasonable but should undergo standard legal review"
         
-        summary = f"{risk_assessment} with an overall risk score of {risk_analysis.overall_score}/100. "
+        summary  = f"{risk_assessment} with an overall risk score of {risk_analysis.overall_score}/100. "
         summary += f"The agreement {action}. "
         
         # Add critical items context
-        if critical_terms > 0:
+        if (critical_terms > 0):
             summary += f"Analysis identified {critical_terms} critical unfavorable terms "
+
             if critical_protections > 0:
                 summary += f"and {critical_protections} critical missing protections. "
+
             else:
                 summary += f"and {len(missing_protections)} missing standard protections. "
+
         else:
             summary += f"Review identified {len(unfavorable_terms)} areas for improvement. "
         
         # Add high-risk categories context
-        high_risk_categories = [cat for cat, score in risk_analysis.category_scores.items() if score >= 60]
+        high_risk_categories = [cat for cat, score in risk_analysis.category_scores.items() if (score >= 60)]
+        
         if high_risk_categories:
             category_names = [cat.replace('_', ' ').title() for cat in high_risk_categories[:2]]
-            summary += f"Particular attention should be given to {', '.join(category_names)} provisions. "
+            summary       += f"Particular attention should be given to {', '.join(category_names)} provisions. "
         
         summary += "Proceed with the detailed negotiation strategy and risk mitigation recommendations provided in the full analysis."
         
         return summary
+
     
-    def _generate_enhanced_fallback_summary_from_context(self, context: SummaryContext) -> str:
-        """Generate fallback summary from context object"""
-        return self._generate_enhanced_fallback_summary(
-            contract_text=context.contract_text_preview or "",
-            classification=type('MockClassification', (), {'category': context.contract_type})(),
-            risk_analysis=type('MockRiskAnalysis', (), {
-                'overall_score': context.risk_score,
-                'risk_level': context.risk_level,
-                'category_scores': context.category_scores
-            })(),
-            unfavorable_terms=context.unfavorable_terms,
-            missing_protections=context.missing_protections
-        )
+    def _generate_fallback_summary_from_context(self, context: SummaryContext) -> str:
+        """
+        Generate fallback summary from context object
+        """
+        # Access attributes safely, providing defaults if needed by the fallback logic
+        text_preview  = context.contract_text_preview if context.contract_text_preview is not None else ""
+        missing_prots = context.missing_protections if context.missing_protections is not None else []
+        unfav_terms   = context.unfavorable_terms if context.unfavorable_terms is not None else []
+
+        return self._generate_fallback_summary(contract_text       = text_preview,
+                                               classification      = type('MockClassification', (), {'category': context.contract_type})(),
+                                               risk_analysis       = type('MockRiskAnalysis', (), {'overall_score': context.risk_score, 'risk_level': context.risk_level, 'category_scores': context.category_scores or {}})(),
+                                               unfavorable_terms   = unfav_terms,
+                                               missing_protections = missing_prots,
+                                              )
     
-    # Helper methods for safe attribute access
+
     def _get_severity(self, term) -> str:
-        """Safely get severity from term object or dict"""
+        """
+        Safely get severity from term object or dict
+        """
         try:
-            if hasattr(term, 'severity'):
+            if (hasattr(term, 'severity')):
                 return term.severity
+            
             else:
                 return term.get('severity', 'unknown')
+        
         except (AttributeError, KeyError):
             return 'unknown'
     
+
     def _get_importance(self, protection) -> str:
-        """Safely get importance from protection object or dict"""
+        """
+        Safely get importance from protection object or dict
+        """
         try:
             if hasattr(protection, 'importance'):
                 return protection.importance
+
             else:
                 return protection.get('importance', 'unknown')
+        
         except (AttributeError, KeyError):
             return 'unknown'
     
+
     def _get_term_name(self, term) -> str:
-        """Safely get term name"""
+        """
+        Safely get term name
+        """
         try:
             if hasattr(term, 'term'):
                 return term.term
+
             else:
                 return term.get('term', 'Unknown Term')
+
         except (AttributeError, KeyError):
             return 'Unknown Term'
     
+
     def _get_protection_name(self, protection) -> str:
-        """Safely get protection name"""
+        """
+        Safely get protection name
+        """
         try:
             if hasattr(protection, 'protection'):
                 return protection.protection
+            
             else:
                 return protection.get('protection', 'Unknown Protection')
+        
         except (AttributeError, KeyError):
             return 'Unknown Protection'
     
+
     def _get_explanation(self, item) -> str:
-        """Safely get explanation"""
+        """
+        Safely get explanation
+        """
         try:
             if hasattr(item, 'explanation'):
                 return item.explanation
+            
             else:
                 return item.get('explanation', 'No explanation available')
+        
         except (AttributeError, KeyError):
             return 'No explanation available'
 
-    # Keep original method for backward compatibility
-    def generate_executive_summary(self, 
-                                 classification: Dict,
-                                 risk_analysis: Dict,
-                                 unfavorable_terms: List[Dict],
-                                 missing_protections: List[Dict],
-                                 clauses: List) -> str:
-        """
-        Original method for backward compatibility
-        """
-        # Convert dict inputs to appropriate types for the new method
-        contract_category = type('ContractCategory', (), {
-            'category': classification.get('category', 'contract')
-        })()
-        
-        risk_score_obj = type('RiskScore', (), {
-            'overall_score': risk_analysis.get('overall_score', 0),
-            'risk_level': risk_analysis.get('risk_level', 'unknown'),
-            'category_scores': risk_analysis.get('category_scores', {})
-        })()
-        
-        return self.generate_comprehensive_summary(
-            contract_text="",  # Not available in original method
-            classification=contract_category,
-            risk_analysis=risk_score_obj,
-            risk_interpretation=None,
-            negotiation_playbook=None,
-            unfavorable_terms=unfavorable_terms,
-            missing_protections=missing_protections,
-            clauses=clauses
-        )
+
+    def _get_clause_reference(self, term) -> str:
+        """
+        Safely get clause reference from term
+        """
+        try:
+            if hasattr(term, 'clause_reference'):
+                ref = term.clause_reference
+                return ref if ref and ref != 'None' else 'Multiple clauses'
+
+            else:
+                ref = term.get('clause_reference', '')
+                return ref if ref and ref != 'None' else 'Multiple clauses'
+
+        except (AttributeError, KeyError):
+            return 'Unknown clause'

services/term_analyzer.py

@@ -7,7 +7,6 @@ from typing import Tuple
 from pathlib import Path
 from typing import Optional
 from collections import Counter
-from dataclasses import dataclass
 
 # Add parent directory to path for imports
 sys.path.append(str(Path(__file__).parent.parent))
@@ -17,43 +16,8 @@ from utils.logger import log_error
 from config.risk_rules import RiskRules
 from config.risk_rules import ContractType
 from utils.logger import ContractAnalyzerLogger
-from services.clause_extractor import ExtractedClause
-
-
-@dataclass
-class UnfavorableTerm:
-    """
-    Detected unfavorable term with comprehensive risk analysis
-    """
-    term             : str
-    category         : str
-    severity         : str    # "critical", "high", "medium", "low"
-    explanation      : str
-    risk_score       : float  # 0-100 risk score
-    clause_reference : Optional[str] = None
-    suggested_fix    : Optional[str] = None
-    contract_type    : Optional[str] = None
-    specific_text    : Optional[str] = None
-    benchmark_info   : Optional[str] = None  # Industry benchmark comparison
-    legal_basis      : Optional[str] = None  # Legal principle violated
-    
-    def to_dict(self) -> Dict:
-        """
-        Convert to dictionary
-        """
-        return {"term"             : self.term,
-                "category"         : self.category,
-                "severity"         : self.severity,
-                "explanation"      : self.explanation,
-                "risk_score"       : round(self.risk_score, 2),
-                "clause_reference" : self.clause_reference,
-                "suggested_fix"    : self.suggested_fix,
-                "contract_type"    : self.contract_type,
-                "specific_text"    : self.specific_text,
-                "benchmark_info"   : self.benchmark_info,
-                "legal_basis"      : self.legal_basis,
-               }
-
+from services.data_models import ExtractedClause
+from services.data_models import UnfavorableTerm
 
 
 class TermAnalyzer:
@@ -79,6 +43,35 @@ class TermAnalyzer:
                  contract_type    = contract_type.value,
                  category_weights = self.category_weights,
                 )
+
+    
+    def _map_to_risk_category(self, clause_category: str) -> str:
+        """
+        Map clause category to risk category for proper risk scoring for ensureing unfavorable terms are correctly attributed to risk categories
+        for score calculation
+        """
+        # Clause categories → Risk categories
+        mapping                          = {"non_compete"           : "restrictive_covenants",
+                                            "confidentiality"       : "restrictive_covenants",
+                                            "termination"           : "termination_rights",
+                                            "indemnification"       : "liability_indemnity",
+                                            "liability"             : "penalties_liability",
+                                            "compensation"          : "compensation_benefits",
+                                            "intellectual_property" : "intellectual_property",
+                                            "warranty"              : "warranties",
+                                            "dispute_resolution"    : "dispute_resolution",
+                                            "assignment"            : "assignment_change",
+                                            "amendment"             : "assignment_change",
+                                            "insurance"             : "insurance",
+                                            "force_majeure"         : "force_majeure",
+                                            "general"               : "general",
+                                            "payment"               : "payment_terms",
+                                            "governing_law"         : "governing_law",
+                                           }
+
+        risk_category_by_clause_category = mapping.get(clause_category, clause_category)
+        
+        return risk_category_by_clause_category
     
 
     @ContractAnalyzerLogger.log_execution_time("analyze_unfavorable_terms")
@@ -148,6 +141,9 @@ class TermAnalyzer:
         terms      = list()
         text_lower = clause.text.lower()
         
+        # Map clause category to risk category for consistency
+        risk_category = self._map_to_risk_category(clause_category = clause.category)
+        
         # Risky Patterns Analysis from RiskRules
         for pattern, risk_score, description in self.risk_rules.RISKY_PATTERNS:
             matches = re.finditer(pattern, text_lower, re.IGNORECASE)
@@ -156,7 +152,7 @@ class TermAnalyzer:
                 severity = self._score_to_severity(risk_score)
                 
                 terms.append(UnfavorableTerm(term             = description,
-                                             category         = clause.category,
+                                             category         = risk_category,
                                              severity         = severity,
                                              explanation      = self._generate_pattern_explanation(description, match.group()),
                                              risk_score       = risk_score,
@@ -174,7 +170,7 @@ class TermAnalyzer:
                 severity = self._score_to_severity(risk_score)
                 
                 terms.append(UnfavorableTerm(term             = f"Critical Risk: {keyword.title()}",
-                                             category         = clause.category,
+                                             category         = risk_category,
                                              severity         = severity,
                                              explanation      = self._generate_keyword_explanation(keyword, clause.category),
                                              risk_score       = risk_score,
@@ -192,7 +188,7 @@ class TermAnalyzer:
                 severity = self._score_to_severity(risk_score)
                 
                 terms.append(UnfavorableTerm(term             = f"High Risk: {keyword.title()}",
-                                             category         = clause.category,
+                                             category         = risk_category, 
                                              severity         = severity,
                                              explanation      = self._generate_keyword_explanation(keyword, clause.category),
                                              risk_score       = risk_score,
@@ -232,13 +228,16 @@ class TermAnalyzer:
                             'force_majeure'         : 'force_majeure',
                            }
         
-        risk_category = category_mapping.get(clause.category)
-        if not risk_category or risk_category not in self.risk_rules.CLAUSE_RISK_FACTORS:
+        risk_factors_key = category_mapping.get(clause.category)
+        if not risk_factors_key or risk_factors_key not in self.risk_rules.CLAUSE_RISK_FACTORS:
             return terms
         
-        risk_factors = self.risk_rules.CLAUSE_RISK_FACTORS[risk_category]
+        risk_factors = self.risk_rules.CLAUSE_RISK_FACTORS[risk_factors_key]
         text_lower   = clause.text.lower()
         
+        # Map clause category to risk category for consistency
+        risk_category = self._map_to_risk_category(clause_category = clause.category)
+
         # Check for red flags in this clause
         for red_flag, risk_adjustment in risk_factors["red_flags"].items():
             if (red_flag in text_lower):
@@ -247,12 +246,12 @@ class TermAnalyzer:
                 severity     = self._score_to_severity(total_risk)
                 
                 terms.append(UnfavorableTerm(term             = f"Risk Factor: {red_flag.replace('_', ' ').title()}",
-                                             category         = clause.category,
+                                             category         = risk_category,
                                              severity         = severity,
-                                             explanation      = f"Base risk {base_risk} + {risk_adjustment} for '{red_flag}'. {self._get_risk_factor_explanation(risk_category, red_flag)}",
+                                             explanation      = f"Base risk {base_risk} + {risk_adjustment} for '{red_flag}'. {self._get_risk_factor_explanation(risk_factors_key, red_flag)}",
                                              risk_score       = total_risk,
                                              clause_reference = clause.reference,
-                                             suggested_fix    = self._get_risk_factor_fix(risk_category, red_flag),
+                                             suggested_fix    = self._get_risk_factor_fix(risk_factors_key, red_flag),
                                              contract_type    = self.contract_type.value,
                                              specific_text    = red_flag,
                                              legal_basis      = self._get_legal_basis(red_flag)
@@ -271,20 +270,31 @@ class TermAnalyzer:
         # Notice period imbalance (from your original but enhanced)
         notice_imbalance = self._check_notice_imbalance(clauses = clauses)
         if notice_imbalance:
+            # Ensure the category used is a risk category
+            notice_imbalance.category = self._map_to_risk_category(clause_category = "termination") 
             terms.append(notice_imbalance)
         
         # Missing reciprocal provisions
         missing_reciprocal = self._check_missing_reciprocal(text    = text, 
                                                             clauses = clauses,
                                                            )
+        for item in missing_reciprocal:
+            # Ensure the category used is a risk category
+            item.category = self._map_to_risk_category(clause_category = "indemnification")
         terms.extend(missing_reciprocal)
         
         # Conflicting clauses
         conflicts = self._check_conflicting_clauses(clauses = clauses)
+        for item in conflicts:
+            # Ensure the category used is a risk category
+            item.category = self._map_to_risk_category(clause_category = item.category) 
         terms.extend(conflicts)
         
         # One-sided discretionary powers
         one_sided_powers = self._check_one_sided_discretion(clauses = clauses)
+        for item in one_sided_powers:
+            # Ensure the category used is a risk category
+            item.category = self._map_to_risk_category(clause_category = item.category)
         terms.extend(one_sided_powers)
         
         return terms
@@ -298,8 +308,12 @@ class TermAnalyzer:
         
         for protection, config in self.risk_rules.PROTECTION_CHECKLIST.items():
             if not self._has_protection(clauses, protection, config['categories']):
+                # For missing protections, map the first associated category to a risk category
+                # This assumes config['categories'][0] is a clause category like "termination"
+                risk_category = self._map_to_risk_category(clause_category = config['categories'][0]) if config['categories'] else "general"
+                
                 terms.append(UnfavorableTerm(term             = f"Missing Protection: {protection.replace('_', ' ').title()}",
-                                             category         = config['categories'][0] if config['categories'] else "general",
+                                             category         = risk_category,
                                              severity         = self._score_to_severity(config['risk_if_missing']),
                                              explanation      = f"Missing critical protection: {protection}. {self._get_missing_protection_explanation(protection)}",
                                              risk_score       = config['risk_if_missing'],
@@ -320,6 +334,10 @@ class TermAnalyzer:
         
         for clause in clauses:
             benchmark_issues = self._check_benchmark_compliance(clause = clause)
+            for item in benchmark_issues:
+                # Ensure the category used is a risk category
+                item.category = self._map_to_risk_category(clause_category = clause.category) 
+
             terms.extend(benchmark_issues)
         
         return terms
@@ -355,11 +373,14 @@ class TermAnalyzer:
             ratio      = max_period / min_period
             
             if (ratio >= 2):
-                severity   = "critical" if (ratio >= 3) else "high"
-                risk_score = 80 if (ratio >= 3) else 60
+                severity      = "critical" if (ratio >= 3) else "high"
+                risk_score    = 80 if (ratio >= 3) else 60
+                
+                # Use the risk category mapping for termination
+                risk_category = self._map_to_risk_category(clause_category = "termination")
                 
                 return UnfavorableTerm(term             = "Imbalanced Notice Periods",
-                                       category         = "termination",
+                                       category         = risk_category,
                                        severity         = severity,
                                        explanation      = f"Significant notice period imbalance: {max_period} days vs {min_period} days (ratio: {ratio:.1f}x). Creates unfair burden.",
                                        risk_score       = risk_score,
@@ -386,8 +407,11 @@ class TermAnalyzer:
             has_mutual    = any("mutual" in c.text.lower() or "both parties" in c.text.lower() or "each party" in c.text.lower() for c in indem_clauses)
             
             if has_one_sided and not has_mutual:
+                # Use the risk category mapping for indemnification
+                risk_category = self._map_to_risk_category(clause_category = "indemnification")
+                
                 terms.append(UnfavorableTerm(term             = "Non-Reciprocal Indemnification",
-                                             category         = "indemnification", 
+                                             category         = risk_category,
                                              severity         = "critical",
                                              explanation      = "One-sided indemnification creates unlimited liability exposure without reciprocal protection.",
                                              risk_score       = 85,
@@ -411,19 +435,21 @@ class TermAnalyzer:
         by_category = dict()
 
         for clause in clauses:
-            if clause.category not in by_category:
-                by_category[clause.category] = []
+            # Map the clause category to the risk category for grouping purposes
+            risk_cat = self._map_to_risk_category(clause_category = clause.category)
+            if risk_cat not in by_category:
+                by_category[risk_cat] = []
             
-            by_category[clause.category].append(clause)
+            by_category[risk_cat].append(clause)
         
         # Check for conflicts within each category
-        for category, category_clauses in by_category.items():
+        for risk_category, category_clauses in by_category.items():
             if (len(category_clauses) >= 2):
                 for i, clause1 in enumerate(category_clauses):
                     for clause2 in category_clauses[i+1:]:
                         if (self._are_clauses_conflicting(clause1, clause2)):
-                            terms.append(UnfavorableTerm(term             = f"Conflicting {category.title()} Clauses",
-                                                         category         = category,
+                            terms.append(UnfavorableTerm(term             = f"Conflicting {risk_category.title()} Clauses",
+                                                         category         = risk_category,
                                                          severity         = "high",
                                                          explanation      = f"Clauses {clause1.reference} and {clause2.reference} contain conflicting terms creating legal ambiguity.",
                                                          risk_score       = 70,
@@ -448,8 +474,11 @@ class TermAnalyzer:
             # Look for one-sided discretionary language
             if re.search(r'(sole|absolute|unfettered|unilateral)\s+(discretion|right|authority)', text_lower):
                 if not re.search(r'(mutual|both parties|reasonable)\s+(discretion|agreement)', text_lower):
+                    # Use the risk category mapping for the clause's category
+                    risk_category = self._map_to_risk_category(clause_category = clause.category)
+                    
                     terms.append(UnfavorableTerm(term             = "One-Sided Discretionary Power",
-                                                 category         = clause.category,
+                                                 category         = risk_category,
                                                  severity         = "high",
                                                  explanation      = "Gives one party unilateral decision-making power without accountability standards.",
                                                  risk_score       = 75,
@@ -478,7 +507,7 @@ class TermAnalyzer:
                 unit               = duration_match.group(2)
                 
                 # Convert to months for comparison
-                total_months       = duration * (12 if unit == "year" else 1)
+                total_months       = duration * (12 if (unit == "year") else 1)
                 
                 benchmarks         = self.risk_rules.INDUSTRY_BENCHMARKS.get('non_compete_duration', {})
                 industry_benchmark = benchmarks.get(self.contract_type.value, benchmarks.get('general', {}))
@@ -488,8 +517,11 @@ class TermAnalyzer:
                     excessive  = industry_benchmark.get('excessive', 24)
                     
                     if (total_months > excessive):
+                        # Use the risk category mapping for non_compete
+                        risk_category = self._map_to_risk_category(clause_category = clause.category)
+                        
                         terms.append(UnfavorableTerm(term             = "Excessive Non-Compete Duration",
-                                                     category         = clause.category,
+                                                     category         = risk_category,
                                                      severity         = "critical",
                                                      explanation      = f"{duration} {unit} non-compete exceeds industry excessive threshold of {excessive} months.",
                                                      risk_score       = 90,
@@ -736,4 +768,4 @@ class TermAnalyzer:
         
         log_info("Unfavorable terms category distribution", **distribution)
         
-        return distribution
+        return distribution

utils/document_reader.py

@@ -73,11 +73,6 @@ class DocumentReader:
         # Normalize file_type by removing any dots and converting to lowercase
         normalized_file_type = file_type.lower().replace('.', '')
 
-        # Validate file type USING NORMALIZED TYPE
-        # if (normalized_file_type not in DocumentReader.ALLOWED_TYPES):
-        #     allowed_str = ', '.join(f'.{ft}' for ft in DocumentReader.ALLOWED_TYPES)
-        #     raise ValueError(f"Unsupported file type: {file_type}. Allowed types: {allowed_str}")
-        
         # Validate file size
         DocumentReader._validate_file_size(file_path_or_bytes = file_path_or_bytes)