Implementation Guide: Analyze contracts to flag unusual clauses, missing provisions, or risk terms

# Network speed test from attorney workstation
speedtest-cli --simple

# Verify Microsoft 365 licensing via PowerShell
Connect-MgGraph -Scopes 'User.Read.All','Organization.Read.All'
Get-MgSubscribedSku | Select-Object SkuPartNumber, ConsumedUnits, PrepaidUnits

# Check Entra ID configuration
Get-MgOrganization | Select-Object DisplayName, VerifiedDomains

# Enumerate existing SharePoint sites (if using SharePoint as DMS)
Get-MgSite -Search '*' | Select-Object DisplayName, WebUrl

# FortiGate initial configuration via CLI (after factory reset)
config system interface
  edit port1
    set ip 192.168.1.1 255.255.255.0
    set allowaccess ping https ssh
  next
end

# Create address objects for AI vendor endpoints
config firewall address
  edit goheather-saas
    set type fqdn
    set fqdn app.goheather.com
  next
  edit azure-openai
    set type fqdn
    set fqdn *.openai.azure.com
  next
  edit legalsifter-saas
    set type fqdn
    set fqdn app.legalsifter.com
  next
end

# Create outbound policy allowing AI vendor traffic
config firewall policy
  edit 10
    set srcintf internal
    set dstintf wan1
    set srcaddr all
    set dstaddr goheather-saas azure-openai legalsifter-saas
    set action accept
    set schedule always
    set service HTTPS
    set utm-status enable
    set ssl-ssh-profile certificate-inspection
    set av-profile default
    set ips-sensor default
    set logtraffic all
  next
end

# Cisco Umbrella - deploy roaming client via Intune
# Upload the OrgInfo.json file and Umbrella MSI to Intune
# Create Win32 app deployment in Endpoint Manager
# Install command:
msiexec /i UmbrellaRoamingClient.msi /qn ORG_ID=<your_org_id> ORG_FINGERPRINT=<your_fingerprint>

# Synology NAS - create shared folder for contracts
# Via DSM web interface or SSH:
synoshare --add ContractArchive 'Contract Document Archive' /volume1/ContractArchive '' '' rw @administrators

# Login to Azure CLI
az login

# Set subscription context
az account set --subscription '<client-subscription-id>'

# Create resource group
az group create --name rg-legalai-prod --location eastus

# Create Azure OpenAI resource
az cognitiveservices account create \
  --name oai-legalai-prod \
  --resource-group rg-legalai-prod \
  --kind OpenAI \
  --sku S0 \
  --location eastus \
  --custom-domain oai-legalai-prod

# Deploy GPT-5.4 model
az cognitiveservices account deployment create \
  --name oai-legalai-prod \
  --resource-group rg-legalai-prod \
  --deployment-name gpt-5.4-contract-review \
  --model-name gpt-5.4 \
  --model-version 2024-08-06 \
  --model-format OpenAI \
  --sku-capacity 30 \
  --sku-name Standard

# Create storage account for contract documents
az storage account create \
  --name stlegalaidocs \
  --resource-group rg-legalai-prod \
  --location eastus \
  --sku Standard_LRS \
  --kind StorageV2 \
  --min-tls-version TLS1_2 \
  --allow-blob-public-access false

# Create blob container
az storage container create \
  --name contracts \
  --account-name stlegalaidocs \
  --auth-mode login

# Create PostgreSQL Flexible Server
az postgres flexible-server create \
  --name psql-legalai-prod \
  --resource-group rg-legalai-prod \
  --location eastus \
  --sku-name Standard_B1ms \
  --tier Burstable \
  --version 16 \
  --admin-user legalai_admin \
  --admin-password '<GENERATE-STRONG-PASSWORD>' \
  --storage-size 32

# Create the application database
az postgres flexible-server db create \
  --resource-group rg-legalai-prod \
  --server-name psql-legalai-prod \
  --database-name contractanalysis

# Create VM for orchestration server
az vm create \
  --resource-group rg-legalai-prod \
  --name vm-legalai-orch \
  --image Ubuntu2204 \
  --size Standard_D4s_v5 \
  --admin-username azureuser \
  --generate-ssh-keys \
  --public-ip-sku Standard \
  --nsg-rule SSH

# Create NSG rule to allow HTTPS inbound (for API access)
az network nsg rule create \
  --resource-group rg-legalai-prod \
  --nsg-name vm-legalai-orchNSG \
  --name AllowHTTPS \
  --priority 100 \
  --destination-port-ranges 443 \
  --protocol Tcp \
  --access Allow

# SSH into the orchestration VM
ssh azureuser@<vm-public-ip>

# Update system and install dependencies
sudo apt update && sudo apt upgrade -y
sudo apt install -y python3.11 python3.11-venv python3-pip nginx certbot python3-certbot-nginx postgresql-client

# Create application directory and virtual environment
sudo mkdir -p /opt/legalai
sudo chown azureuser:azureuser /opt/legalai
cd /opt/legalai
python3.11 -m venv venv
source venv/bin/activate

# Install Python packages
pip install --upgrade pip
pip install langchain langchain-openai langchain-community openai fastapi uvicorn psycopg2-binary python-multipart azure-storage-blob azure-identity pdfplumber python-docx tiktoken pydantic sqlalchemy alembic httpx tenacity structlog

# Create application directory structure
mkdir -p /opt/legalai/{app,playbooks,templates,logs}
touch /opt/legalai/app/__init__.py

# Create environment configuration file
cat > /opt/legalai/.env << 'EOF'
AZURE_OPENAI_ENDPOINT=https://oai-legalai-prod.openai.azure.com/
AZURE_OPENAI_API_KEY=<your-api-key>
AZURE_OPENAI_DEPLOYMENT=gpt-5.4-contract-review
AZURE_OPENAI_API_VERSION=2024-08-06
AZURE_STORAGE_ACCOUNT=stlegalaidocs
AZURE_STORAGE_CONTAINER=contracts
DATABASE_URL=postgresql://legalai_admin:<password>@psql-legalai-prod.postgres.database.azure.com:5432/contractanalysis
LOG_LEVEL=INFO
MAX_TOKENS_PER_REQUEST=128000
EOF
chmod 600 /opt/legalai/.env

# Create systemd service
sudo cat > /etc/systemd/system/legalai.service << 'EOF'
[Unit]
Description=Legal AI Contract Analysis Service
After=network.target

[Service]
Type=simple
User=azureuser
WorkingDirectory=/opt/legalai
Environment=PATH=/opt/legalai/venv/bin
EnvironmentFile=/opt/legalai/.env
ExecStart=/opt/legalai/venv/bin/uvicorn app.main:app --host 127.0.0.1 --port 8000 --workers 2
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable legalai

# Configure Nginx reverse proxy
sudo cat > /etc/nginx/sites-available/legalai << 'EOF'
server {
    listen 443 ssl;
    server_name legalai.<client-domain>.com;
    
    client_max_body_size 50M;
    
    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 300s;
    }
}
EOF

sudo ln -s /etc/nginx/sites-available/legalai /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

# Obtain TLS certificate
sudo certbot --nginx -d legalai.<client-domain>.com --non-interactive --agree-tos -m admin@<msp-domain>.com

# Connect to PostgreSQL
psql 'host=psql-legalai-prod.postgres.database.azure.com port=5432 dbname=contractanalysis user=legalai_admin sslmode=require'

# Execute schema creation
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

CREATE TABLE playbooks (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    name VARCHAR(255) NOT NULL,
    contract_type VARCHAR(100) NOT NULL,
    jurisdiction VARCHAR(100),
    version INTEGER DEFAULT 1,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    created_by VARCHAR(255) NOT NULL,
    is_active BOOLEAN DEFAULT TRUE
);

CREATE TABLE playbook_clauses (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    playbook_id UUID REFERENCES playbooks(id) ON DELETE CASCADE,
    clause_name VARCHAR(255) NOT NULL,
    clause_category VARCHAR(100) NOT NULL,
    standard_position TEXT NOT NULL,
    risk_level VARCHAR(20) DEFAULT 'medium' CHECK (risk_level IN ('low', 'medium', 'high', 'critical')),
    is_required BOOLEAN DEFAULT FALSE,
    sample_language TEXT,
    red_flag_patterns TEXT[],
    notes TEXT
);

CREATE TABLE contracts (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    filename VARCHAR(500) NOT NULL,
    file_hash VARCHAR(64) NOT NULL,
    blob_path VARCHAR(1000) NOT NULL,
    contract_type VARCHAR(100),
    parties TEXT[],
    effective_date DATE,
    uploaded_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    uploaded_by VARCHAR(255) NOT NULL,
    matter_id VARCHAR(100),
    clio_matter_id VARCHAR(100),
    status VARCHAR(50) DEFAULT 'pending' CHECK (status IN ('pending', 'analyzing', 'completed', 'error', 'reviewed'))
);

CREATE TABLE analysis_results (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    contract_id UUID REFERENCES contracts(id) ON DELETE CASCADE,
    playbook_id UUID REFERENCES playbooks(id),
    analysis_timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    overall_risk_score DECIMAL(3,1) CHECK (overall_risk_score BETWEEN 0 AND 10),
    summary TEXT NOT NULL,
    model_version VARCHAR(100) NOT NULL,
    token_usage_input INTEGER,
    token_usage_output INTEGER,
    processing_time_seconds DECIMAL(8,2),
    raw_response JSONB
);

CREATE TABLE flagged_items (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    analysis_id UUID REFERENCES analysis_results(id) ON DELETE CASCADE,
    item_type VARCHAR(50) NOT NULL CHECK (item_type IN ('unusual_clause', 'missing_provision', 'risk_term', 'deviation', 'ambiguity')),
    severity VARCHAR(20) NOT NULL CHECK (severity IN ('info', 'low', 'medium', 'high', 'critical')),
    clause_reference VARCHAR(255),
    original_text TEXT,
    description TEXT NOT NULL,
    recommendation TEXT,
    playbook_clause_id UUID REFERENCES playbook_clauses(id),
    attorney_reviewed BOOLEAN DEFAULT FALSE,
    attorney_action VARCHAR(50) CHECK (attorney_action IN (NULL, 'accepted', 'dismissed', 'modified')),
    attorney_notes TEXT,
    reviewed_at TIMESTAMP,
    reviewed_by VARCHAR(255)
);

CREATE TABLE audit_log (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    action VARCHAR(100) NOT NULL,
    user_id VARCHAR(255),
    contract_id UUID REFERENCES contracts(id),
    details JSONB,
    ip_address INET
);

CREATE INDEX idx_contracts_status ON contracts(status);
CREATE INDEX idx_contracts_matter ON contracts(clio_matter_id);
CREATE INDEX idx_flagged_severity ON flagged_items(severity);
CREATE INDEX idx_flagged_type ON flagged_items(item_type);
CREATE INDEX idx_audit_timestamp ON audit_log(timestamp);
CREATE INDEX idx_analysis_contract ON analysis_results(contract_id);

# 1. Register an application in Clio Developer Portal
# Navigate to https://app.clio.com/nc/#/settings/developer_applications
# Create new application:
#   Name: 'Legal AI Contract Analyzer'
#   URL: https://legalai.<client-domain>.com
#   Redirect URI: https://legalai.<client-domain>.com/auth/clio/callback
#   Scopes: matters:read, documents:read, documents:write, activities:write, contacts:read

# 2. Store Clio OAuth credentials in .env file on orchestration server
echo 'CLIO_CLIENT_ID=<your-clio-client-id>' >> /opt/legalai/.env
echo 'CLIO_CLIENT_SECRET=<your-clio-client-secret>' >> /opt/legalai/.env
echo 'CLIO_REDIRECT_URI=https://legalai.<client-domain>.com/auth/clio/callback' >> /opt/legalai/.env

# 3. Test Clio API connectivity
curl -X GET 'https://app.clio.com/api/v4/matters.json?limit=5' \
  -H 'Authorization: Bearer <test-access-token>' \
  -H 'Content-Type: application/json'

# 4. Verify document retrieval
curl -X GET 'https://app.clio.com/api/v4/documents.json?matter_id=<test-matter-id>' \
  -H 'Authorization: Bearer <test-access-token>' \
  -H 'Content-Type: application/json'

# Connect to the orchestration server
ssh azureuser@<vm-public-ip>
cd /opt/legalai
source venv/bin/activate

# Load playbook data using the management script
python -m app.management.load_playbook --file playbooks/nda_standard.json
python -m app.management.load_playbook --file playbooks/commercial_lease.json
python -m app.management.load_playbook --file playbooks/employment_agreement.json
python -m app.management.load_playbook --file playbooks/vendor_services.json
python -m app.management.load_playbook --file playbooks/msa_standard.json

# Verify playbooks loaded
python -m app.management.list_playbooks

# Expected output:
# ID | Name                        | Contract Type | Clauses | Active
# -- | --------------------------- | ------------- | ------- | ------
# 1  | Standard NDA Playbook        | NDA           | 18      | Yes
# 2  | Commercial Lease Playbook    | Lease         | 32      | Yes
# 3  | Employment Agreement Playbook| Employment    | 25      | Yes
# 4  | Vendor Services Playbook     | Services      | 22      | Yes
# 5  | Master Services Agreement    | MSA           | 28      | Yes

# SSH into orchestration server
ssh azureuser@<vm-public-ip>
cd /opt/legalai

# Clone or copy application files (see custom_ai_components for full source)
# The main application files should be placed as follows:
# /opt/legalai/app/main.py          - FastAPI application entry point
# /opt/legalai/app/analyzer.py      - Core LangChain contract analysis engine
# /opt/legalai/app/models.py         - SQLAlchemy ORM models
# /opt/legalai/app/schemas.py        - Pydantic request/response schemas
# /opt/legalai/app/clio_client.py    - Clio API integration
# /opt/legalai/app/document_loader.py - PDF/DOCX text extraction
# /opt/legalai/app/prompts/          - Prompt templates directory
# /opt/legalai/app/management/       - CLI management scripts

# Run database migrations
cd /opt/legalai
source venv/bin/activate
alembic upgrade head

# Start the service
sudo systemctl start legalai
sudo systemctl status legalai

# Verify the API is running
curl -s https://legalai.<client-domain>.com/health | python3 -m json.tool
# Expected: {"status": "healthy", "database": "connected", "openai": "connected"}

# Run a test analysis
curl -X POST https://legalai.<client-domain>.com/api/v1/analyze \
  -H 'Authorization: Bearer <test-token>' \
  -F 'file=@/opt/legalai/test_contracts/sample_nda.pdf' \
  -F 'contract_type=NDA' \
  -F 'playbook_id=1'

# Register Azure AD app for SharePoint access
az ad app create \
  --display-name 'LegalAI-SharePoint-Connector' \
  --sign-in-audience AzureADMyOrg \
  --required-resource-accesses @sharepoint-permissions.json

# Grant admin consent
az ad app permission admin-consent --id <app-id>

# Create SharePoint document library structure
# Via SharePoint admin or PnP PowerShell:
Install-Module PnP.PowerShell -Force
Connect-PnPOnline -Url 'https://<tenant>.sharepoint.com/sites/contracts' -Interactive

# Create the contracts library with metadata columns
Add-PnPField -List 'Contracts' -DisplayName 'AI Analysis Status' -InternalName 'AIStatus' -Type Choice -Choices 'Pending','Analyzing','Completed','Error'
Add-PnPField -List 'Contracts' -DisplayName 'Risk Score' -InternalName 'RiskScore' -Type Number
Add-PnPField -List 'Contracts' -DisplayName 'Flagged Items' -InternalName 'FlaggedItems' -Type Number
Add-PnPField -List 'Contracts' -DisplayName 'Contract Type' -InternalName 'ContractType' -Type Choice -Choices 'NDA','Lease','Employment','Services','MSA','Other'
Add-PnPField -List 'Contracts' -DisplayName 'Analysis Report' -InternalName 'AnalysisReport' -Type URL

# Create Power Automate flow to trigger analysis
# Flow: When a file is created in SharePoint 'Contracts for Review' folder
# -> HTTP POST to https://legalai.<client-domain>.com/api/v1/analyze/sharepoint
# -> With file URL, metadata, and user context
# (Configure this in Power Automate web UI - see notes)

# Register the LegalAI application in Entra ID
az ad app create \
  --display-name 'Legal AI Contract Analyzer' \
  --web-redirect-uris 'https://legalai.<client-domain>.com/auth/callback' \
  --enable-id-token-issuance true

# Define app roles
az ad app update --id <app-id> --app-roles '[
  {
    "allowedMemberTypes": ["User"],
    "description": "Attorney - can upload contracts, view analysis, provide feedback",
    "displayName": "Attorney",
    "isEnabled": true,
    "value": "Attorney"
  },
  {
    "allowedMemberTypes": ["User"],
    "description": "Partner - full access including playbook management and reporting",
    "displayName": "Partner",
    "isEnabled": true,
    "value": "Partner"
  },
  {
    "allowedMemberTypes": ["User"],
    "description": "Staff - read-only access to completed analyses",
    "displayName": "Staff",
    "isEnabled": true,
    "value": "Staff"
  }
]'

# Add Entra ID configuration to application .env
echo 'AZURE_AD_TENANT_ID=<tenant-id>' >> /opt/legalai/.env
echo 'AZURE_AD_CLIENT_ID=<app-client-id>' >> /opt/legalai/.env
echo 'AZURE_AD_CLIENT_SECRET=<app-client-secret>' >> /opt/legalai/.env

# Restart the application to pick up new config
sudo systemctl restart legalai

# Upload test contracts in batch
cd /opt/legalai
source venv/bin/activate

# Run batch analysis on test corpus
python -m app.management.batch_analyze \
  --input-dir /opt/legalai/test_contracts/ \
  --playbook-auto-detect \
  --output-report /opt/legalai/test_results/batch_report.json

# Generate accuracy report comparing AI output to attorney annotations
python -m app.management.accuracy_report \
  --ai-results /opt/legalai/test_results/batch_report.json \
  --attorney-annotations /opt/legalai/test_contracts/attorney_annotations.json \
  --output /opt/legalai/test_results/accuracy_report.html

# /opt/legalai/app/analyzer.py

import json
import hashlib
import time
from typing import Optional
from datetime import datetime

from langchain_openai import AzureChatOpenAI
from langchain.prompts import ChatPromptTemplate
from langchain.output_parsers import PydanticOutputParser
from pydantic import BaseModel, Field
from sqlalchemy.orm import Session
import structlog

logger = structlog.get_logger()

# --- Output Schema ---
class FlaggedItem(BaseModel):
    item_type: str = Field(description="One of: unusual_clause, missing_provision, risk_term, deviation, ambiguity")
    severity: str = Field(description="One of: info, low, medium, high, critical")
    clause_reference: str = Field(description="Section/clause number or heading where the issue was found")
    original_text: str = Field(description="The exact text from the contract that triggered this flag")
    description: str = Field(description="Clear explanation of why this item was flagged")
    recommendation: str = Field(description="Specific recommended action for the reviewing attorney")

class ContractAnalysisResult(BaseModel):
    contract_type: str = Field(description="Identified contract type")
    parties: list[str] = Field(description="Names of all parties to the contract")
    effective_date: Optional[str] = Field(description="Contract effective date if found")
    overall_risk_score: float = Field(description="Overall risk score from 0.0 (low risk) to 10.0 (extreme risk)")
    executive_summary: str = Field(description="2-3 paragraph summary of the contract and key findings")
    flagged_items: list[FlaggedItem] = Field(description="All flagged issues found in the contract")
    missing_provisions: list[str] = Field(description="Standard provisions expected for this contract type that are missing")
    positive_observations: list[str] = Field(description="Clauses that are well-drafted or favorable to the client")

# --- Analysis Engine ---
class ContractAnalyzer:
    def __init__(self, db_session: Session):
        self.db = db_session
        self.llm = AzureChatOpenAI(
            azure_deployment="gpt-5.4-contract-review",
            api_version="2024-08-06",
            temperature=0.1,  # Low temperature for consistent, precise analysis
            max_tokens=8000,
        )
        self.parser = PydanticOutputParser(pydantic_object=ContractAnalysisResult)

    def _load_playbook(self, playbook_id: str) -> dict:
        """Load playbook and its clauses from the database."""
        from app.models import Playbook, PlaybookClause
        playbook = self.db.query(Playbook).filter(Playbook.id == playbook_id, Playbook.is_active == True).first()
        if not playbook:
            raise ValueError(f"Playbook {playbook_id} not found or inactive")
        clauses = self.db.query(PlaybookClause).filter(PlaybookClause.playbook_id == playbook_id).all()
        return {
            "name": playbook.name,
            "contract_type": playbook.contract_type,
            "jurisdiction": playbook.jurisdiction,
            "clauses": [
                {
                    "name": c.clause_name,
                    "category": c.clause_category,
                    "standard_position": c.standard_position,
                    "risk_level": c.risk_level,
                    "is_required": c.is_required,
                    "sample_language": c.sample_language,
                    "red_flag_patterns": c.red_flag_patterns or []
                }
                for c in clauses
            ]
        }

    def _build_analysis_prompt(self, contract_text: str, playbook: dict) -> ChatPromptTemplate:
        """Build the multi-part analysis prompt."""
        system_template = """You are an expert legal contract analyst AI assistant working for a law firm. Your role is to perform thorough contract review by comparing the provided contract against the firm's legal playbook.

You must:
1. Identify ALL clauses in the contract and compare each against the playbook's standard positions
2. Flag any clause that deviates from the firm's standard position, noting the severity of deviation
3. Identify any REQUIRED clauses from the playbook that are MISSING from the contract
4. Flag risk terms including but not limited to: unlimited liability, unilateral termination rights, automatic renewal without notice, broad indemnification, non-mutual obligations, overly broad non-compete/non-solicit, unfavorable governing law, waiver of jury trial, limitation on consequential damages exclusion, assignment without consent
5. Identify ambiguous language that could be interpreted adversely
6. Note any unusual or non-standard clauses not typically found in this type of contract
7. Assess an overall risk score from 0.0 to 10.0

IMPORTANT GUIDELINES:
- Be thorough: it is better to over-flag than to miss a genuine risk
- Be specific: always cite the exact contract language and section references
- Be actionable: every flagged item must include a concrete recommendation
- Be objective: note both risks and favorable provisions
- Severity scale: 'critical' = potential significant financial/legal exposure; 'high' = material deviation requiring negotiation; 'medium' = notable deviation worth discussing; 'low' = minor deviation, likely acceptable; 'info' = observation, no action needed
- This analysis will be reviewed by a licensed attorney who makes all final decisions

{format_instructions}"""

        human_template = """## LEGAL PLAYBOOK: {playbook_name}
Contract Type: {contract_type}
Jurisdiction: {jurisdiction}

### Standard Positions and Required Clauses:
{playbook_clauses}

---

## CONTRACT TO ANALYZE:
{contract_text}

---

Perform a comprehensive analysis of this contract against the playbook above. Identify all flagged items, missing provisions, and risk terms. Provide your analysis in the specified JSON format."""

        playbook_clauses_text = ""
        for clause in playbook["clauses"]:
            required_marker = " [REQUIRED]" if clause["is_required"] else ""
            red_flags = ""
            if clause["red_flag_patterns"]:
                red_flags = f"\n    Red flags: {', '.join(clause['red_flag_patterns'])}"
            playbook_clauses_text += f"""\n- **{clause['name']}** ({clause['category']}) - Risk Level: {clause['risk_level']}{required_marker}
    Standard Position: {clause['standard_position']}{red_flags}\n"""

        prompt = ChatPromptTemplate.from_messages([
            ("system", system_template),
            ("human", human_template)
        ])
        return prompt, {
            "format_instructions": self.parser.get_format_instructions(),
            "playbook_name": playbook["name"],
            "contract_type": playbook["contract_type"],
            "jurisdiction": playbook.get("jurisdiction", "Not specified"),
            "playbook_clauses": playbook_clauses_text,
            "contract_text": contract_text
        }

    async def analyze_contract(
        self,
        contract_text: str,
        playbook_id: str,
        contract_id: str,
        uploaded_by: str
    ) -> ContractAnalysisResult:
        """Execute the full contract analysis pipeline."""
        start_time = time.time()
        logger.info("contract_analysis_started", contract_id=contract_id, playbook_id=playbook_id)

        # Load playbook
        playbook = self._load_playbook(playbook_id)

        # Build prompt
        prompt, variables = self._build_analysis_prompt(contract_text, playbook)

        # Execute LLM analysis
        chain = prompt | self.llm | self.parser
        result = await chain.ainvoke(variables)

        processing_time = time.time() - start_time
        logger.info(
            "contract_analysis_completed",
            contract_id=contract_id,
            risk_score=result.overall_risk_score,
            flagged_count=len(result.flagged_items),
            missing_count=len(result.missing_provisions),
            processing_seconds=round(processing_time, 2)
        )

        # Persist results to database
        from app.models import AnalysisResult, FlaggedItemDB, AuditLog
        analysis_record = AnalysisResult(
            contract_id=contract_id,
            playbook_id=playbook_id,
            overall_risk_score=result.overall_risk_score,
            summary=result.executive_summary,
            model_version="gpt-5.4",
            processing_time_seconds=round(processing_time, 2),
            raw_response=result.model_dump()
        )
        self.db.add(analysis_record)
        self.db.flush()

        for item in result.flagged_items:
            flagged_record = FlaggedItemDB(
                analysis_id=analysis_record.id,
                item_type=item.item_type,
                severity=item.severity,
                clause_reference=item.clause_reference,
                original_text=item.original_text,
                description=item.description,
                recommendation=item.recommendation
            )
            self.db.add(flagged_record)

        # Audit log
        audit_entry = AuditLog(
            action="contract_analyzed",
            user_id=uploaded_by,
            contract_id=contract_id,
            details={
                "playbook_id": playbook_id,
                "risk_score": result.overall_risk_score,
                "flagged_items": len(result.flagged_items),
                "processing_seconds": round(processing_time, 2)
            }
        )
        self.db.add(audit_entry)
        self.db.commit()

        return result

# /opt/legalai/app/classifier.py

from langchain_openai import AzureChatOpenAI
from langchain.prompts import ChatPromptTemplate
from pydantic import BaseModel, Field
from langchain.output_parsers import PydanticOutputParser
from sqlalchemy.orm import Session

class ClassificationResult(BaseModel):
    contract_type: str = Field(description="The identified contract type. One of: NDA, Lease, Employment, Services, MSA, Purchase, License, Partnership, Consulting, Settlement, Other")
    confidence: float = Field(description="Confidence score from 0.0 to 1.0")
    parties: list[str] = Field(description="Names of all parties identified in the contract")
    effective_date: str | None = Field(description="Contract effective date if found, in YYYY-MM-DD format")
    jurisdiction: str | None = Field(description="Governing law jurisdiction if specified")
    reasoning: str = Field(description="Brief explanation of why this classification was chosen")

class ContractClassifier:
    SUPPORTED_TYPES = ['NDA', 'Lease', 'Employment', 'Services', 'MSA', 'Purchase', 'License', 'Partnership', 'Consulting', 'Settlement', 'Other']

    def __init__(self):
        # Use a cheaper, faster model for classification
        self.llm = AzureChatOpenAI(
            azure_deployment="gpt-5.4-contract-review",
            api_version="2024-08-06",
            temperature=0.0,
            max_tokens=500,
        )
        self.parser = PydanticOutputParser(pydantic_object=ClassificationResult)

    async def classify(self, contract_text: str) -> ClassificationResult:
        """Classify a contract and extract key metadata."""
        # Only send first 3000 chars for classification (cost optimization)
        text_sample = contract_text[:3000]

        prompt = ChatPromptTemplate.from_messages([
            ("system", """You are a legal document classifier. Analyze the provided contract text and identify:
1. The type of contract
2. All named parties
3. The effective date
4. The governing law jurisdiction

Supported contract types: {supported_types}

{format_instructions}"""),
            ("human", "Classify this contract:\n\n{text}")
        ])

        chain = prompt | self.llm | self.parser
        result = await chain.ainvoke({
            "supported_types": ", ".join(self.SUPPORTED_TYPES),
            "format_instructions": self.parser.get_format_instructions(),
            "text": text_sample
        })
        return result

    def match_playbook(self, classification: ClassificationResult, db: Session) -> str | None:
        """Match the classified contract type to the best available playbook."""
        from app.models import Playbook

        # Try exact match first
        playbook = db.query(Playbook).filter(
            Playbook.contract_type == classification.contract_type,
            Playbook.is_active == True
        )

        # If jurisdiction is known, prefer jurisdiction-specific playbook
        if classification.jurisdiction:
            jurisdiction_match = playbook.filter(
                Playbook.jurisdiction == classification.jurisdiction
            ).first()
            if jurisdiction_match:
                return str(jurisdiction_match.id)

        # Fall back to general playbook for this type
        general_match = playbook.filter(
            Playbook.jurisdiction.is_(None) | (Playbook.jurisdiction == '')
        ).first()
        if general_match:
            return str(general_match.id)

        # If no match, use the first active playbook of this type
        any_match = playbook.first()
        return str(any_match.id) if any_match else None

# /opt/legalai/app/workflows.py

import hashlib
from datetime import datetime
from typing import Optional

import pdfplumber
from docx import Document as DocxDocument
from azure.storage.blob import BlobServiceClient
from azure.identity import DefaultAzureCredential
from sqlalchemy.orm import Session
import structlog

from app.analyzer import ContractAnalyzer, ContractAnalysisResult
from app.classifier import ContractClassifier
from app.models import Contract, AuditLog
from app.clio_client import ClioClient

logger = structlog.get_logger()

class ContractReviewWorkflow:
    def __init__(self, db: Session):
        self.db = db
        self.classifier = ContractClassifier()
        self.analyzer = ContractAnalyzer(db)
        self.clio = ClioClient()

    def _extract_text(self, file_bytes: bytes, filename: str) -> str:
        """Extract text from PDF or DOCX files."""
        if filename.lower().endswith('.pdf'):
            import io
            text_parts = []
            with pdfplumber.open(io.BytesIO(file_bytes)) as pdf:
                for page in pdf.pages:
                    page_text = page.extract_text()
                    if page_text:
                        text_parts.append(page_text)
            full_text = "\n\n".join(text_parts)
            if len(full_text.strip()) < 100:
                logger.warning("pdf_low_text_extraction", filename=filename, chars=len(full_text))
                # May be a scanned PDF - would need OCR (Azure Document Intelligence)
                raise ValueError("PDF appears to be scanned/image-based. OCR processing required. Please upload a text-based PDF or DOCX.")
            return full_text
        elif filename.lower().endswith('.docx'):
            import io
            doc = DocxDocument(io.BytesIO(file_bytes))
            return "\n\n".join([para.text for para in doc.paragraphs if para.text.strip()])
        else:
            raise ValueError(f"Unsupported file type: {filename}. Please upload PDF or DOCX.")

    def _upload_to_blob(self, file_bytes: bytes, filename: str, contract_id: str) -> str:
        """Upload contract to Azure Blob Storage for archival."""
        import os
        blob_service = BlobServiceClient(
            account_url=f"https://{os.environ['AZURE_STORAGE_ACCOUNT']}.blob.core.windows.net",
            credential=DefaultAzureCredential()
        )
        container_client = blob_service.get_container_client(os.environ['AZURE_STORAGE_CONTAINER'])
        blob_path = f"{datetime.utcnow().strftime('%Y/%m')}/{contract_id}/{filename}"
        container_client.upload_blob(name=blob_path, data=file_bytes, overwrite=True)
        return blob_path

    async def execute(
        self,
        file_bytes: bytes,
        filename: str,
        uploaded_by: str,
        playbook_id: Optional[str] = None,
        contract_type: Optional[str] = None,
        clio_matter_id: Optional[str] = None
    ) -> dict:
        """Execute the complete contract review workflow."""

        # Step 1: Create contract record
        file_hash = hashlib.sha256(file_bytes).hexdigest()
        contract = Contract(
            filename=filename,
            file_hash=file_hash,
            blob_path="pending",
            uploaded_by=uploaded_by,
            clio_matter_id=clio_matter_id,
            status="analyzing"
        )
        self.db.add(contract)
        self.db.flush()
        contract_id = str(contract.id)

        logger.info("workflow_started", contract_id=contract_id, filename=filename)

        try:
            # Step 2: Extract text
            contract_text = self._extract_text(file_bytes, filename)
            logger.info("text_extracted", contract_id=contract_id, chars=len(contract_text))

            # Step 3: Upload to blob storage
            blob_path = self._upload_to_blob(file_bytes, filename, contract_id)
            contract.blob_path = blob_path

            # Step 4: Classify contract (if type not specified)
            if not playbook_id:
                classification = await self.classifier.classify(contract_text)
                contract.contract_type = classification.contract_type
                contract.parties = classification.parties
                if classification.effective_date:
                    try:
                        contract.effective_date = datetime.strptime(classification.effective_date, '%Y-%m-%d').date()
                    except ValueError:
                        pass

                # Step 5: Match playbook
                playbook_id = self.classifier.match_playbook(classification, self.db)
                if not playbook_id:
                    logger.warning("no_playbook_match", contract_type=classification.contract_type)
                    # Use a generic/default playbook
                    from app.models import Playbook
                    default = self.db.query(Playbook).filter(Playbook.contract_type == 'Other', Playbook.is_active == True).first()
                    if default:
                        playbook_id = str(default.id)
                    else:
                        raise ValueError(f"No playbook found for contract type: {classification.contract_type}")

            elif contract_type:
                contract.contract_type = contract_type

            # Step 6: Run AI analysis
            result = await self.analyzer.analyze_contract(
                contract_text=contract_text,
                playbook_id=playbook_id,
                contract_id=contract_id,
                uploaded_by=uploaded_by
            )

            # Step 7: Update contract status
            contract.status = "completed"
            self.db.commit()

            # Step 8: Link to Clio matter (if provided)
            if clio_matter_id:
                try:
                    await self.clio.create_note(
                        matter_id=clio_matter_id,
                        subject=f"AI Contract Analysis: {filename}",
                        body=self._format_clio_note(result)
                    )
                    logger.info("clio_note_created", matter_id=clio_matter_id)
                except Exception as e:
                    logger.error("clio_integration_error", error=str(e))

            # Step 9: Send notification for high-risk contracts
            if result.overall_risk_score >= 7.0:
                logger.warning(
                    "high_risk_contract_detected",
                    contract_id=contract_id,
                    risk_score=result.overall_risk_score,
                    critical_items=len([i for i in result.flagged_items if i.severity == 'critical'])
                )
                # TODO: Implement email/Teams notification for high-risk contracts

            return {
                "contract_id": contract_id,
                "status": "completed",
                "risk_score": result.overall_risk_score,
                "flagged_items_count": len(result.flagged_items),
                "missing_provisions_count": len(result.missing_provisions),
                "analysis": result.model_dump()
            }

        except Exception as e:
            contract.status = "error"
            self.db.add(AuditLog(
                action="analysis_error",
                user_id=uploaded_by,
                contract_id=contract_id,
                details={"error": str(e)}
            ))
            self.db.commit()
            logger.error("workflow_error", contract_id=contract_id, error=str(e))
            raise

    def _format_clio_note(self, result: ContractAnalysisResult) -> str:
        """Format analysis results as a readable note for Clio."""
        lines = [
            f"## AI Contract Analysis Report",
            f"**Overall Risk Score: {result.overall_risk_score}/10**",
            f"",
            f"### Executive Summary",
            result.executive_summary,
            f"",
            f"### Flagged Items ({len(result.flagged_items)} total)",
        ]
        for item in sorted(result.flagged_items, key=lambda x: ['critical','high','medium','low','info'].index(x.severity)):
            lines.append(f"- **[{item.severity.upper()}]** {item.clause_reference}: {item.description}")
        if result.missing_provisions:
            lines.append(f"\n### Missing Provisions")
            for provision in result.missing_provisions:
                lines.append(f"- {provision}")
        lines.append(f"\n---")
        lines.append(f"*This analysis was generated by AI and must be reviewed by a licensed attorney before any action is taken. See ABA Formal Opinion 512.*")
        return "\n".join(lines)

{
  "name": "Standard NDA Playbook",
  "contract_type": "NDA",
  "jurisdiction": "New York",
  "version": 1,
  "clauses": [
    {
      "clause_name": "Definition of Confidential Information",
      "clause_category": "definitions",
      "standard_position": "Confidential information should be broadly defined to include all non-public information disclosed by either party, whether written, oral, or visual. Should include carve-outs for information that is: (a) publicly known, (b) already known to the recipient, (c) independently developed, or (d) received from a third party without restriction.",
      "risk_level": "high",
      "is_required": true,
      "sample_language": "'Confidential Information' means any and all non-public information, whether in written, oral, electronic, or other form, disclosed by the Disclosing Party to the Receiving Party...",
      "red_flag_patterns": [
        "excludes oral disclosures",
        "requires written marking as sole condition",
        "one-way definition favoring only one party",
        "no standard exceptions listed"
      ]
    },
    {
      "clause_name": "Non-Disclosure Obligations",
      "clause_category": "obligations",
      "standard_position": "Mutual obligations preferred. Receiving party must protect confidential information using at least the same degree of care it uses for its own confidential information, but no less than reasonable care. Must restrict access to need-to-know employees and advisors.",
      "risk_level": "high",
      "is_required": true,
      "sample_language": null,
      "red_flag_patterns": [
        "no standard of care specified",
        "unrestricted sharing with affiliates",
        "unilateral obligations only"
      ]
    },
    {
      "clause_name": "Term and Duration",
      "clause_category": "term",
      "standard_position": "Agreement term of 2-3 years. Confidentiality obligations should survive for 3-5 years after termination. Trade secrets should be protected indefinitely.",
      "risk_level": "medium",
      "is_required": true,
      "sample_language": null,
      "red_flag_patterns": [
        "perpetual obligations with no end date",
        "survival period less than 2 years",
        "no trade secret exception"
      ]
    },
    {
      "clause_name": "Permitted Disclosures",
      "clause_category": "exceptions",
      "standard_position": "Must include exceptions for legally compelled disclosures (subpoena, court order, regulatory request). Should require prompt notice to the disclosing party before such disclosure when legally permissible.",
      "risk_level": "high",
      "is_required": true,
      "sample_language": null,
      "red_flag_patterns": [
        "no exception for legal compulsion",
        "no notice requirement before compelled disclosure",
        "overly broad permitted disclosure categories"
      ]
    },
    {
      "clause_name": "Return or Destruction of Information",
      "clause_category": "termination",
      "standard_position": "Upon termination or request, receiving party must return or destroy all confidential information and certify destruction in writing. Should allow retention of copies required by law or internal compliance policies.",
      "risk_level": "medium",
      "is_required": true,
      "sample_language": null,
      "red_flag_patterns": [
        "no return/destruction obligation",
        "no certification requirement",
        "no compliance retention exception"
      ]
    },
    {
      "clause_name": "Remedies",
      "clause_category": "remedies",
      "standard_position": "Should acknowledge that breach may cause irreparable harm and that injunctive relief may be sought without proving actual damages. Should not waive right to other remedies.",
      "risk_level": "medium",
      "is_required": false,
      "sample_language": null,
      "red_flag_patterns": [
        "liquidated damages with cap below potential exposure",
        "waiver of injunctive relief",
        "limitation on consequential damages"
      ]
    },
    {
      "clause_name": "Non-Solicitation / Non-Compete",
      "clause_category": "restrictive_covenants",
      "standard_position": "Non-solicitation of employees may be acceptable for 12-24 months. Non-compete clauses should generally be avoided in NDAs. If present, must be narrowly tailored in scope, geography, and duration.",
      "risk_level": "high",
      "is_required": false,
      "sample_language": null,
      "red_flag_patterns": [
        "broad non-compete in an NDA",
        "non-solicitation exceeding 24 months",
        "no geographic limitation on non-compete",
        "non-compete without consideration"
      ]
    },
    {
      "clause_name": "Governing Law and Dispute Resolution",
      "clause_category": "dispute_resolution",
      "standard_position": "Governing law should be the firm client's home jurisdiction (New York). Federal and state courts in New York County preferred. Mandatory arbitration acceptable if with a recognized institution (AAA, JAMS).",
      "risk_level": "medium",
      "is_required": true,
      "sample_language": null,
      "red_flag_patterns": [
        "foreign governing law",
        "mandatory arbitration in unfavorable jurisdiction",
        "waiver of jury trial without reciprocity",
        "loser-pays attorney fee provision"
      ]
    },
    {
      "clause_name": "Assignment",
      "clause_category": "general",
      "standard_position": "Neither party should be able to assign rights or obligations without the other's prior written consent, except in connection with a merger, acquisition, or sale of substantially all assets.",
      "risk_level": "low",
      "is_required": false,
      "sample_language": null,
      "red_flag_patterns": [
        "unilateral assignment right",
        "assignment to affiliates without consent",
        "no assignment clause at all"
      ]
    },
    {
      "clause_name": "No License or IP Transfer",
      "clause_category": "ip",
      "standard_position": "Should explicitly state that no license to intellectual property is granted by disclosure of confidential information. Ownership of all IP remains with the disclosing party.",
      "risk_level": "high",
      "is_required": true,
      "sample_language": "Nothing in this Agreement shall be construed as granting any rights, by license or otherwise, to any Confidential Information...",
      "red_flag_patterns": [
        "no IP reservation clause",
        "implied license language",
        "work product ownership assigned to recipient"
      ]
    }
  ]
}

# /opt/legalai/app/management/load_playbook.py

import json
import sys
import argparse
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker
import os

sys.path.insert(0, '/opt/legalai')
from app.models import Playbook, PlaybookClause

def load_playbook(filepath: str):
    engine = create_engine(os.environ['DATABASE_URL'])
    Session = sessionmaker(bind=engine)
    session = Session()

    with open(filepath, 'r') as f:
        data = json.load(f)

    # Check if playbook already exists
    existing = session.query(Playbook).filter(
        Playbook.name == data['name'],
        Playbook.contract_type == data['contract_type']
    ).first()

    if existing:
        print(f"Playbook '{data['name']}' already exists (ID: {existing.id}). Updating...")
        existing.jurisdiction = data.get('jurisdiction')
        existing.version = data.get('version', existing.version + 1)
        existing.updated_at = __import__('datetime').datetime.utcnow()
        # Delete existing clauses and reload
        session.query(PlaybookClause).filter(PlaybookClause.playbook_id == existing.id).delete()
        playbook_id = existing.id
    else:
        playbook = Playbook(
            name=data['name'],
            contract_type=data['contract_type'],
            jurisdiction=data.get('jurisdiction'),
            version=data.get('version', 1),
            created_by='system'
        )
        session.add(playbook)
        session.flush()
        playbook_id = playbook.id
        print(f"Created new playbook '{data['name']}' (ID: {playbook_id})")

    # Load clauses
    for clause_data in data['clauses']:
        clause = PlaybookClause(
            playbook_id=playbook_id,
            clause_name=clause_data['clause_name'],
            clause_category=clause_data['clause_category'],
            standard_position=clause_data['standard_position'],
            risk_level=clause_data.get('risk_level', 'medium'),
            is_required=clause_data.get('is_required', False),
            sample_language=clause_data.get('sample_language'),
            red_flag_patterns=clause_data.get('red_flag_patterns', []),
            notes=clause_data.get('notes')
        )
        session.add(clause)

    session.commit()
    print(f"Loaded {len(data['clauses'])} clauses for playbook '{data['name']}'")
    session.close()

if __name__ == '__main__':
    parser = argparse.ArgumentParser(description='Load a legal playbook into the database')
    parser.add_argument('--file', required=True, help='Path to playbook JSON file')
    args = parser.parse_args()
    load_playbook(args.file)

# /opt/legalai/app/main.py

import os
from contextlib import asynccontextmanager
from fastapi import FastAPI, UploadFile, File, Form, Depends, HTTPException, Request
from fastapi.middleware.cors import CORSMiddleware
from fastapi.responses import JSONResponse
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker, Session
from typing import Optional
import structlog
import msal
import jwt
from datetime import datetime

from app.workflows import ContractReviewWorkflow
from app.models import Contract, AnalysisResult, FlaggedItemDB, AuditLog

logger = structlog.get_logger()

# Database setup
engine = create_engine(os.environ['DATABASE_URL'], pool_pre_ping=True, pool_size=10)
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)

def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

# JWT Token validation for Entra ID
TENANT_ID = os.environ.get('AZURE_AD_TENANT_ID')
CLIENT_ID = os.environ.get('AZURE_AD_CLIENT_ID')
JWKS_URL = f"https://login.microsoftonline.com/{TENANT_ID}/discovery/v2.0/keys"

async def get_current_user(request: Request) -> dict:
    auth_header = request.headers.get('Authorization')
    if not auth_header or not auth_header.startswith('Bearer '):
        raise HTTPException(status_code=401, detail="Missing or invalid authorization header")
    token = auth_header.split(' ')[1]
    try:
        # In production, cache the JWKS keys
        import httpx
        async with httpx.AsyncClient() as client:
            resp = await client.get(JWKS_URL)
            jwks = resp.json()
        
        unverified_header = jwt.get_unverified_header(token)
        rsa_key = None
        for key in jwks['keys']:
            if key['kid'] == unverified_header['kid']:
                rsa_key = jwt.algorithms.RSAAlgorithm.from_jwk(key)
                break
        if not rsa_key:
            raise HTTPException(status_code=401, detail="Unable to find appropriate key")
        
        payload = jwt.decode(
            token, rsa_key, algorithms=['RS256'],
            audience=CLIENT_ID,
            issuer=f"https://login.microsoftonline.com/{TENANT_ID}/v2.0"
        )
        return {
            'user_id': payload.get('preferred_username', payload.get('sub')),
            'name': payload.get('name'),
            'roles': payload.get('roles', []),
        }
    except jwt.ExpiredSignatureError:
        raise HTTPException(status_code=401, detail="Token expired")
    except jwt.InvalidTokenError as e:
        raise HTTPException(status_code=401, detail=f"Invalid token: {str(e)}")

def require_role(required_roles: list[str]):
    async def role_checker(user: dict = Depends(get_current_user)):
        if not any(role in user.get('roles', []) for role in required_roles):
            raise HTTPException(status_code=403, detail="Insufficient permissions")
        return user
    return role_checker

# FastAPI app
app = FastAPI(
    title="Legal AI Contract Analyzer",
    description="AI-powered contract review for legal services",
    version="1.0.0"
)

app.add_middleware(
    CORSMiddleware,
    allow_origins=[f"https://<client-domain>.sharepoint.com", "https://localhost:3000"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

@app.get("/health")
async def health_check(db: Session = Depends(get_db)):
    try:
        db.execute("SELECT 1")
        db_status = "connected"
    except Exception:
        db_status = "disconnected"
    return {"status": "healthy", "database": db_status, "timestamp": datetime.utcnow().isoformat()}

@app.post("/api/v1/analyze")
async def analyze_contract(
    file: UploadFile = File(...),
    contract_type: Optional[str] = Form(None),
    playbook_id: Optional[str] = Form(None),
    clio_matter_id: Optional[str] = Form(None),
    user: dict = Depends(require_role(['Attorney', 'Partner'])),
    db: Session = Depends(get_db)
):
    """Upload and analyze a contract document."""
    if not file.filename.lower().endswith(('.pdf', '.docx')):
        raise HTTPException(status_code=400, detail="Only PDF and DOCX files are supported")
    
    file_bytes = await file.read()
    if len(file_bytes) > 50 * 1024 * 1024:  # 50MB limit
        raise HTTPException(status_code=400, detail="File size exceeds 50MB limit")

    workflow = ContractReviewWorkflow(db)
    result = await workflow.execute(
        file_bytes=file_bytes,
        filename=file.filename,
        uploaded_by=user['user_id'],
        playbook_id=playbook_id,
        contract_type=contract_type,
        clio_matter_id=clio_matter_id
    )
    return JSONResponse(content=result)

@app.get("/api/v1/contracts")
async def list_contracts(
    status: Optional[str] = None,
    limit: int = 50,
    offset: int = 0,
    user: dict = Depends(require_role(['Attorney', 'Partner', 'Staff'])),
    db: Session = Depends(get_db)
):
    """List analyzed contracts with optional status filter."""
    query = db.query(Contract).order_by(Contract.uploaded_at.desc())
    if status:
        query = query.filter(Contract.status == status)
    contracts = query.offset(offset).limit(limit).all()
    return [{"id": str(c.id), "filename": c.filename, "contract_type": c.contract_type,
             "status": c.status, "uploaded_at": c.uploaded_at.isoformat(), "clio_matter_id": c.clio_matter_id}
            for c in contracts]

@app.get("/api/v1/contracts/{contract_id}/analysis")
async def get_analysis(
    contract_id: str,
    user: dict = Depends(require_role(['Attorney', 'Partner', 'Staff'])),
    db: Session = Depends(get_db)
):
    """Get the full analysis results for a contract."""
    analysis = db.query(AnalysisResult).filter(
        AnalysisResult.contract_id == contract_id
    ).order_by(AnalysisResult.analysis_timestamp.desc()).first()
    if not analysis:
        raise HTTPException(status_code=404, detail="Analysis not found")
    flagged = db.query(FlaggedItemDB).filter(FlaggedItemDB.analysis_id == analysis.id).all()
    return {
        "contract_id": contract_id,
        "analysis_id": str(analysis.id),
        "risk_score": float(analysis.overall_risk_score),
        "summary": analysis.summary,
        "model_version": analysis.model_version,
        "analyzed_at": analysis.analysis_timestamp.isoformat(),
        "flagged_items": [
            {"id": str(f.id), "type": f.item_type, "severity": f.severity,
             "clause_reference": f.clause_reference, "original_text": f.original_text,
             "description": f.description, "recommendation": f.recommendation,
             "attorney_reviewed": f.attorney_reviewed, "attorney_action": f.attorney_action}
            for f in flagged
        ]
    }

@app.put("/api/v1/flagged-items/{item_id}/review")
async def review_flagged_item(
    item_id: str,
    action: str = Form(...),  # accepted, dismissed, modified
    notes: Optional[str] = Form(None),
    user: dict = Depends(require_role(['Attorney', 'Partner'])),
    db: Session = Depends(get_db)
):
    """Record attorney review decision on a flagged item."""
    item = db.query(FlaggedItemDB).filter(FlaggedItemDB.id == item_id).first()
    if not item:
        raise HTTPException(status_code=404, detail="Flagged item not found")
    if action not in ('accepted', 'dismissed', 'modified'):
        raise HTTPException(status_code=400, detail="Action must be: accepted, dismissed, or modified")
    item.attorney_reviewed = True
    item.attorney_action = action
    item.attorney_notes = notes
    item.reviewed_at = datetime.utcnow()
    item.reviewed_by = user['user_id']
    db.add(AuditLog(
        action="flagged_item_reviewed",
        user_id=user['user_id'],
        contract_id=item.analysis.contract_id if item.analysis else None,
        details={"item_id": item_id, "action": action, "notes": notes}
    ))
    db.commit()
    return {"status": "updated", "item_id": item_id, "action": action}

@app.get("/api/v1/analytics/summary")
async def analytics_summary(
    user: dict = Depends(require_role(['Partner'])),
    db: Session = Depends(get_db)
):
    """Dashboard analytics for partners - review volumes, risk distribution, accuracy metrics."""
    from sqlalchemy import func
    total_contracts = db.query(func.count(Contract.id)).filter(Contract.status == 'completed').scalar()
    avg_risk = db.query(func.avg(AnalysisResult.overall_risk_score)).scalar()
    flagged_by_severity = db.query(
        FlaggedItemDB.severity, func.count(FlaggedItemDB.id)
    ).group_by(FlaggedItemDB.severity).all()
    reviewed_items = db.query(func.count(FlaggedItemDB.id)).filter(FlaggedItemDB.attorney_reviewed == True).scalar()
    dismissed_items = db.query(func.count(FlaggedItemDB.id)).filter(FlaggedItemDB.attorney_action == 'dismissed').scalar()
    false_positive_rate = (dismissed_items / reviewed_items * 100) if reviewed_items > 0 else 0
    return {
        "total_contracts_analyzed": total_contracts,
        "average_risk_score": round(float(avg_risk or 0), 1),
        "flagged_by_severity": {s: c for s, c in flagged_by_severity},
        "attorney_review_stats": {
            "total_reviewed": reviewed_items,
            "dismissed_as_false_positive": dismissed_items,
            "false_positive_rate_pct": round(false_positive_rate, 1)
        }
    }

# /opt/legalai/app/clio_client.py

import os
import httpx
from datetime import datetime
from typing import Optional
import structlog

logger = structlog.get_logger()

class ClioClient:
    BASE_URL = "https://app.clio.com/api/v4"

    def __init__(self):
        self.client_id = os.environ.get('CLIO_CLIENT_ID')
        self.client_secret = os.environ.get('CLIO_CLIENT_SECRET')
        self.redirect_uri = os.environ.get('CLIO_REDIRECT_URI')
        self._access_token = None
        self._refresh_token = os.environ.get('CLIO_REFRESH_TOKEN')  # Set after initial OAuth flow

    async def _ensure_token(self):
        """Refresh the access token if needed."""
        if self._access_token:
            return
        if not self._refresh_token:
            logger.warning("clio_no_refresh_token", msg="Clio integration not authenticated. Run OAuth flow first.")
            return
        async with httpx.AsyncClient() as client:
            resp = await client.post("https://app.clio.com/oauth/token", data={
                "grant_type": "refresh_token",
                "refresh_token": self._refresh_token,
                "client_id": self.client_id,
                "client_secret": self.client_secret,
            })
            if resp.status_code == 200:
                data = resp.json()
                self._access_token = data['access_token']
                self._refresh_token = data.get('refresh_token', self._refresh_token)
                # Persist new refresh token
                # In production, store in Azure Key Vault
                logger.info("clio_token_refreshed")
            else:
                logger.error("clio_token_refresh_failed", status=resp.status_code, body=resp.text)

    async def _request(self, method: str, path: str, **kwargs) -> dict:
        await self._ensure_token()
        if not self._access_token:
            raise ConnectionError("Clio authentication not available")
        async with httpx.AsyncClient() as client:
            resp = await client.request(
                method,
                f"{self.BASE_URL}{path}",
                headers={
                    "Authorization": f"Bearer {self._access_token}",
                    "Content-Type": "application/json"
                },
                **kwargs
            )
            if resp.status_code == 401:
                self._access_token = None
                await self._ensure_token()
                resp = await client.request(
                    method, f"{self.BASE_URL}{path}",
                    headers={"Authorization": f"Bearer {self._access_token}", "Content-Type": "application/json"},
                    **kwargs
                )
            resp.raise_for_status()
            return resp.json()

    async def get_matter(self, matter_id: str) -> dict:
        """Retrieve a matter from Clio."""
        result = await self._request("GET", f"/matters/{matter_id}.json", params={"fields": "id,display_number,description,client,status"})
        return result.get('data', {})

    async def create_note(self, matter_id: str, subject: str, body: str) -> dict:
        """Create an activity note on a Clio matter with analysis results."""
        payload = {
            "data": {
                "subject": subject,
                "body": body,
                "type": "Note",
                "matter": {"id": int(matter_id)},
                "date": datetime.utcnow().strftime("%Y-%m-%d")
            }
        }
        result = await self._request("POST", "/activities.json", json=payload)
        return result.get('data', {})

    async def create_time_entry(self, matter_id: str, description: str, duration_seconds: int, user_id: Optional[str] = None) -> dict:
        """Log a time entry for AI-assisted contract review. Marked as non-billable by default per ABA Rule 1.5."""
        payload = {
            "data": {
                "type": "TimeEntry",
                "quantity": duration_seconds,
                "note": f"[AI-Assisted Review] {description}",
                "matter": {"id": int(matter_id)},
                "date": datetime.utcnow().strftime("%Y-%m-%d"),
                "non_billable": True  # AI processing time is non-billable per ABA guidance
            }
        }
        if user_id:
            payload["data"]["user"] = {"id": int(user_id)}
        result = await self._request("POST", "/activities.json", json=payload)
        return result.get('data', {})