CertiExtract

Certificate Data Extraction Agentic Pipeline

An AI-powered multi-agent pipeline that extracts structured data from certificate images and PDFs. Built with LangGraph for orchestration, DeepSeek v4 for intelligent text analysis, and Pytesseract for OCR.

---

Features

• Multi-agent architecture — 9-node LangGraph pipeline with conditional edges
• Layout-aware extraction — classifies certificates before extraction for prompt optimization
• OCR + LLM hybrid — Pytesseract OCR as primary text extraction, DeepSeek v4 for intelligent field parsing
• Cross-verification — OCR text is cross-checked against LLM extraction for hallucination detection
• Confidence scoring — weighted multi-signal confidence with automatic review flagging
• Idempotent processing — SHA-256 content hashing prevents reprocessing
• Batch support — process entire folders with progress tracking
• Structured output — CSV + formatted Excel export

---

Quick Start

Prerequisites

1. Python 3.11+
2. Tesseract OCR — installed on your system (download)
3. DeepSeek API key — get one from DeepSeek

Installation

cd CertiExtract
pip install -r requirements.txt

Configuration

Edit .env with your API key:

DEEPSEEK_API_KEY=your_key_here
DEEPSEEK_MODEL=deepseek-v4-flash

If Tesseract is not on your PATH, set:

TESSERACT_CMD=C:\path\to\tesseract.exe

Usage

Single Certificate

python run_pipeline.py --file path/to/certificate.png

Force reprocessing of an already-processed file:

python run_pipeline.py --file path/to/certificate.png --force

Batch Processing

python scripts/batch_run.py --folder data/input/

Export to Excel

python scripts/export_to_excel.py

---

Pipeline Architecture

START → load_document → preprocess → detect_photo → classify_layout
→ extract_fields → verify_ocr → normalize → validate
→ (retry if needed) → aggregate → END

See architecture.md for the full flow diagram and state documentation.

---

Output

Results are saved to:

• data/output/master_table.csv — machine-readable
• data/output/master_table.xlsx — formatted with conditional highlighting

Extracted Fields

Field	Description
name	Certificate recipient name
achievement	Title/degree/certification
organization	Primary issuing organization
co_organizations	Additional organizations
date_issued	ISO 8601 date
certificate_id	Serial number / ID
signatory	Signatory name(s)
grade_or_score	Grade/score if present
overall_confidence	Extraction confidence (0–1)
needs_review	Manual review flag

---

Testing

# Run all tests
pytest tests/ -v

# Run specific test suites
pytest tests/test_normalization_agent.py -v    # No API calls
pytest tests/test_validation_agent.py -v       # No API calls
pytest tests/test_extraction_agent.py -v       # Mocked API
pytest tests/test_pipeline_e2e.py -v -m e2e    # Full pipeline (mocked)

---

Project Structure

CertiExtract/
├── agents/          # LangGraph agent node implementations
├── data/            # Input/output/samples directories
├── prompts/         # LLM prompt templates
├── scripts/         # Batch processing & export utilities
├── tests/           # Test suites with fixtures
├── utils/           # Schema, config, logging, hashing
├── vision/          # Image loading, preprocessing, face detection
├── run_pipeline.py  # Single-file entry point
└── requirements.txt

---

Design Decisions

See design_decision.md for rationale behind architectural choices.

Changelog

See changes_logs.md for a running log of changes.