seungchan1122/mk-document-classifier repository overview

⁠MK Document Classifier

A mortgage document classification and human-review console built for the MK Lending coding assignment.

The pipeline combines native PDF text extraction, selective OCR, explainable rule-based classification, and optional LLM validation to classify mortgage-document pages and group contiguous pages into document units.

⁠Features

• PDF page classification
  • URLA_1003
  • INCOME_DOC
  • CREDIT_REPORT
  • TITLE_REPORT
  • OTHER
• Native text extraction with selective Tesseract OCR
• Hybrid Rule + AI classification
• NVIDIA NIM (openai/gpt-oss-120b) support
• OpenAI provider support
• Human-review routing with explicit review reasons
• Multi-PDF and ZIP batch ingestion
• Safe ZIP handling
  • Path traversal protection
  • Symlink rejection
  • Nested archive rejection
  • File and archive size limits
• Korean / English Streamlit UI
• Canonical JSON / CSV / HTML exports
• Localized Korean / English CSV / HTML / PDF reports
• Streamlit container health check
• No raw task PDF, ZIP, .env, or API key included in the image

⁠Supported Platforms

Multi-architecture image support:

• linux/amd64
• linux/arm64

Available tags:

• latest
• 1.0.0

⁠Quick Start

Pull the image:

docker pull seungchan1122/mk-document-classifier:latest

⁠Rule-only mode

No external AI API is required.

docker run --rm \
  -p 8501:8501 \
  -e AI_PROVIDER=none \
  seungchan1122/mk-document-classifier:latest

Open:

http://localhost:8501

⁠Hybrid AI mode

Create a local .env file and provide it only at container runtime.

Example for NVIDIA NIM:

AI_PROVIDER=nvidia
NVIDIA_API_KEY=your_api_key
NVIDIA_BASE_URL=https://integrate.api.nvidia.com/v1
NVIDIA_MODEL=openai/gpt-oss-120b
ALLOW_PRIVATE_AI_UPLOAD=true

Run:

docker run --rm \
  -p 8501:8501 \
  --env-file .env \
  seungchan1122/mk-document-classifier:latest

⁠Processing Pipeline

PDF
 ↓
Native Text Extraction
 ↓
Selective OCR
 ↓
Weighted Rule Evidence
 ↓
Optional AI Validation
 ↓
Page Classification
 ↓
Human Review Routing
 ↓
Contiguous Document Groups

⁠Evaluation

On the provided package_01 Ground Truth:

The hybrid run improved 5 pages without introducing newly incorrect pages in this evaluation.

INCOME_DOC had only one Ground Truth sample and remained misclassified, so this project does not claim reliable generalized performance for that class.

package_02 has no official Ground Truth, so no accuracy claim is made for it.

⁠Human Review

Review routing is intentionally conservative.

A page may be flagged when:

• Model confidence is low
• The result is OTHER
• Model evidence is insufficient
• AI and rule classifications disagree
• Extracted text quality is insufficient
• OCR was required
• AI processing falls back to the rule result

The Streamlit Review Console groups review pages by package and provides sanitized review reasons and in-memory page previews.

⁠Data Handling

The Docker image does not contain the coding-test PDFs or ZIP archives.

Uploaded files are processed in temporary storage and are not persisted to the repository or Docker image.

External AI usage requires explicit opt-in:

ALLOW_PRIVATE_AI_UPLOAD=true

The original PDF or page image is not sent to the configured LLM provider. Only the extracted text required for classification is sent.

Persisted reports use sanitized output and do not store raw page text or free-form source evidence.

⁠Container Verification

Verified with:

• Python 3.12
• Tesseract OCR 5.5.0
• Korean Noto CJK fonts
• Korean PDF report rendering
• Streamlit /_stcore/health
• NVIDIA NIM runtime smoke test
• linux/amd64
• linux/arm64

⁠Health Check

http://localhost:8501/_stcore/health

⁠Image

seungchan1122/mk-document-classifier

Built as a reproducible Docker delivery layer around the same classification engine used by the CLI and Streamlit application.