🔍 ClaimLens AI

Intelligent Claims Document Processing for US Commercial Property Insurance

ClaimLens AI is an agentic document-processing pipeline that reads insurance claim documents — FNOLs, proof-of-loss forms, repair estimates, damage photos, and more — then extracts structured data, generates per-document summaries, and writes comprehensive claim notes, all in a single run.

---

✨ Features

Capability	Description
Agentic Pipeline	LangGraph state-machine orchestrates Extract → Summarize → Claim Notes
Document Extraction	Parses PDFs, images, DOCX & plain text via the Datalab API
Strict Summaries	Per-document summaries grounded strictly in the source content
Claim Notes Generation	Full narrative claim notes synthesised across all documents
Schema-Driven	Typed extraction schemas for 8+ insurance document types
Graceful Fallbacks	Runs in placeholder mode when credentials are unavailable

---

📁 Project Structure

ClaimLens-AI/
├── main.py                         # Entry point - run the agent
├── requirements.txt                # Python dependencies
├── .env.template                   # Environment variable template
│
├── src/
│   ├── core/
│   │   ├── entities.py             # Pydantic domain models
│   │   ├── schemas.py              # Extraction schemas (FNOL, PoL, etc.)
│   │   └── exceptions.py           # Custom exception classes
│   │
│   ├── application/
│   │   ├── claims_graph.py         # LangGraph definition & ClaimsAgent API
│   │   ├── graph_state.py          # Graph state TypedDict
│   │   └── nodes/
│   │       ├── extract_documents.py    # Node - Datalab extraction
│   │       ├── summarize_documents.py  # Node - per-doc summaries (STRICT)
│   │       └── generate_claim_notes.py # Node - full claim notes (FULL)
│   │
│   └── infrastructure/
│       └── datalabs_client.py      # Datalab API client wrapper
│
└── sample_documents/               # Auto-generated sample claim files

---

🚀 Quick Start

1. Clone & install

git clone https://github.com/<your-username>/ClaimLens-AI.git
cd ClaimLens-AI

python -m venv .venv
.venv\Scripts\activate          # Windows
# source .venv/bin/activate     # macOS / Linux

pip install -r requirements.txt

2. Configure environment

copy .env.template .env         # Windows
# cp .env.template .env         # macOS / Linux

Open .env and fill in your credentials:

Variable	Required	Default	Description
AZURE_OPENAI_API_KEY	Yes	—	Azure OpenAI resource key
AZURE_OPENAI_ENDPOINT	Yes	—	Azure OpenAI endpoint URL
AZURE_OPENAI_API_VERSION	No	2024-02-15-preview	API version string
AZURE_OPENAI_DEPLOYMENT	No	gpt-4	Model deployment name
DATALAB_API_KEY	No	—	Datalab API key (for document extraction)
DATALAB_BASE_URL	No	https://api.datalab.to	Datalab API base URL
DATALAB_MAX_POLLS	No	300	Max polling attempts for async jobs
DATALAB_POLL_INTERVAL	No	2.0	Seconds between poll requests
LOG_LEVEL	No	INFO	Logging verbosity

3. Run

python main.py

On first run the agent creates sample documents in sample_documents/. Run again to process them through the full pipeline.

---

📄 Supported Document Types

Type	Extensions	Schema
FNOL (First Notice of Loss)	.pdf .txt .docx	FNOL_SCHEMA
Proof of Loss	.pdf .txt	PROOF_OF_LOSS_SCHEMA
Policy / Coverage	.pdf	COVERAGE_POLICY_SCHEMA
Claims Report	.pdf .txt	CLAIMS_REPORT_SCHEMA
Damage Photos	.jpg .png .jpeg	DAMAGE_PHOTO_SCHEMA
Repair Estimates	.pdf .xlsx	REPAIR_ESTIMATE_SCHEMA
Police / Fire Reports	.pdf	POLICE_FIRE_REPORT_SCHEMA
Business Inventory	.xlsx .pdf	BUSINESS_INVENTORY_SCHEMA

---

🧩 How It Works

  Documents ──> Extract (Datalab) ──> Summarize (STRICT) ──> Claim Notes (FULL) ──> Output

1. Extract — Documents are parsed via the Datalab API into structured markdown + extracted fields.
2. Summarize — Each document receives a grounded, schema-aware summary using Azure OpenAI.
3. Claim Notes — All summaries are synthesised into a single narrative with key findings and recommendations.

---

🧪 Usage Examples

Process with custom documents

import asyncio
from dotenv import load_dotenv
load_dotenv()

from src.application import ClaimsAgent
from src.core.entities import ClaimMetadata

async def run():
    agent = ClaimsAgent()

    result = await agent.process_claim(
        claim_number="MY-CLAIM-001",
        document_paths=["path/to/fnol.pdf", "path/to/estimate.pdf"],
        claim_metadata=ClaimMetadata(
            claim_number="MY-CLAIM-001",
            policy_number="POL-12345",
            insured_name="Acme Corp.",
            date_of_loss="2024-06-01",
            cause_of_loss="Fire Damage",
        ),
    )

    for s in result.document_summaries:
        print(f"{s.document_name} - {s.document_type.value}")
        print(f"  {s.summary[:200]}")

asyncio.run(run())

Extract only (no LLM needed)

docs = await agent.extract_only(
    claim_number="TEST-001",
    document_paths=["document.pdf"],
)
for doc in docs:
    print(doc.filename, doc.extracted_fields)

Summarize only (no claim notes)

summaries = await agent.summarize_only(
    claim_number="TEST-002",
    document_paths=["doc1.pdf", "doc2.pdf"],
)

---

📊 Output Structure

result.extracted_documents   # Raw Datalab extraction output
result.document_summaries    # Per-document summaries (STRICT mode)
result.claim_notes           # Full claim narrative    (FULL mode)
result.errors                # Any processing errors

---

🔧 Troubleshooting

Issue	Solution
AZURE_OPENAI_API_KEY not set	Ensure .env exists and contains valid credentials
datalab-sdk not found	Agent runs in placeholder mode - install SDK when available
No documents found	Add files to the sample_documents/ directory
Summarization failed	Verify Azure OpenAI quota and deployment name

---

📜 License

This project is provided as-is for internal / educational use.

---

Built with ❤️ using LangGraph, Azure OpenAI & Datalab