How nanonets/docstrange works
Project Type and Purpose
• Type: A Python-based, full-stack library + CLI + optional self-hosted Web UI for document conversion and extraction.
• Purpose: Ingest PDFs, images, Office docs, and URLs → run OCR + layout detection → convert to Markdown, JSON, CSV, HTML → deliver via CLI, Python API, Web UI, or cloud API.
File Structure
• Core Library: docstrange/
• cli.py → CLI entry point
• web_app.py, static/, templates/ → Flask-based Web UI
• config.py, exceptions.py, result.py, utils/ → shared utilities
• Pipeline: docstrange/pipeline/
• layout_detector, ocr_service, model_downloader, nanonets_processor, neural_document_processor
• Processors: docstrange/processors/
• Format-specific processors: PDF, image, Excel, DOCX, PPTX, HTML, TXT, URL, Cloud, GPU
• Services: docstrange/services/
• auth_service.py, ollama_service.py → cloud authentication, local LLM service
• MCP Server Module: mcp_server_module/
• server.py, __main__.py → Claude Desktop integration microservice
• Scripts & Examples: scripts/, examples/, plus tests in tests/
Key Insights from README
• Dual processing modes: Cloud API vs. Local CPU/GPU
• Multi-stage pipeline: Ingestion → Layout Detection → OCR → Formatting/Cleaning → (Optional) Structured Extraction
• Interfaces: Python API, CLI, Local Web UI, MCP Server for Claude Desktop
a. User Interfaces
• CLI (cli.py)
• Python Library (DocumentExtractor API)
• Web UI (Flask app: web_app.py + static + templates)
• MCP Server (mcp_server_module/server.py)
b. Core Pipeline
• Ingestion Layer → dispatches file by type to appropriate processors/ module
• OCR & Layout Detection (ocr_service, layout_detector)
• Model Management (model_downloader, GPU utils)
• Processors (PDF, image, DOCX, PPTX, XLSX, HTML, TXT, URL, cell)
• Structured Extraction (LLM via ollama_service or cloud model)
c. Services & External Dependencies
• Cloud API (NanoNets, Claude, optionally other OCR providers)
• Ollama local LLM
d. Output Layer
• ConversionResult methods: .extract_markdown(), .extract_data(), .extract_html(), .extract_csv(), .extract_text()
Relationships & Data Flows
1. User invokes CLI or Web UI or Python API.
2. The front-end component calls into DocumentExtractor.
3. DocumentExtractor loads config → chooses cloud or local mode.
4. File is passed to Ingestion, which picks the right processor.
5. Processor calls into OCR Service and Layout Detector.
6. Cleaned text flows to Formatter (Markdown/HTML) or Structured Extractor (LLM).
7. Output is returned to user interface or written to file.
8. Optionally, for Claude Desktop, MCP Server runs independently to handle token-aware chunking.
Architectural Patterns & Principles
• Modular Pipeline: clear separation of ingestion, processing, and formatting
• Strategy Pattern: different processors/ selected at runtime based on input type
• Adapter/Facade: DocumentExtractor as a single façade to hide pipeline complexity
• Client-Server: Web UI and MCP server run as server processes
• Dependency Injection: configurable OCR, LLM, GPU vs. CPU modes