Configuration Guide¶

Complete reference for all Duckling configuration options.

Environment Variables¶

Create a .env file in the backend directory:

# Flask Configuration
FLASK_ENV=development          # development | production | testing
SECRET_KEY=your-secret-key     # Required for production
DEBUG=True                     # Enable debug mode

# File Handling
MAX_CONTENT_LENGTH=104857600   # Max upload size in bytes (100MB default)

# Database (optional - defaults to SQLite)
DATABASE_URL=sqlite:///history.db

Production Environment¶

FLASK_ENV=production
SECRET_KEY=your-very-secure-random-key-here
DEBUG=False
MAX_CONTENT_LENGTH=209715200   # 200MB for production

OCR Settings¶

OCR (Optical Character Recognition) extracts text from images and scanned documents.

Configuration Options¶

OCR Backends¶

{
  "ocr": {
    "backend": "easyocr",
    "use_gpu": true,
    "language": "en"
  }
}

{
  "ocr": {
    "backend": "tesseract",
    "language": "eng"
  }
}

{
  "ocr": {
    "backend": "ocrmac",
    "language": "en"
  }
}

{
  "ocr": {
    "backend": "rapidocr",
    "language": "en"
  }
}

Supported Languages¶

Table Settings¶

Configure how tables are detected and extracted from documents.

Configuration Options¶

Detection Modes¶

{
  "tables": {
    "enabled": true,
    "mode": "accurate",
    "do_cell_matching": true
  }
}

{
  "tables": {
    "enabled": true,
    "mode": "fast",
    "do_cell_matching": false
  }
}

Image Settings¶

Configure image extraction and processing.

Configuration Options¶

Example Configurations¶

{
  "images": {
    "extract": true,
    "classify": true,
    "generate_page_images": true,
    "generate_picture_images": true,
    "generate_table_images": true,
    "images_scale": 2.0
  }
}

{
  "images": {
    "extract": false,
    "classify": false,
    "generate_page_images": false,
    "generate_picture_images": false,
    "generate_table_images": false
  }
}

Performance Settings¶

Optimize processing speed and resource usage.

Configuration Options¶

Device Options¶

Example Configurations¶

{
  "performance": {
    "device": "cuda",
    "num_threads": 8,
    "document_timeout": null
  }
}

{
  "performance": {
    "device": "cpu",
    "num_threads": 2,
    "document_timeout": 60
  }
}

{
  "performance": {
    "device": "mps",
    "num_threads": 4,
    "document_timeout": null
  }
}

Chunking Settings¶

Configure document chunking for RAG applications.

Configuration Options¶

Example Configurations¶

{
  "chunking": {
    "enabled": true,
    "max_tokens": 512,
    "merge_peers": true
  }
}

{
  "chunking": {
    "enabled": true,
    "max_tokens": 2048,
    "merge_peers": false
  }
}

Output Settings¶

Configure default output format.

Complete Configuration Example¶

{
  "ocr": {
    "enabled": true,
    "backend": "easyocr",
    "language": "en",
    "force_full_page_ocr": false,
    "use_gpu": false,
    "confidence_threshold": 0.5,
    "bitmap_area_threshold": 0.05
  },
  "tables": {
    "enabled": true,
    "structure_extraction": true,
    "mode": "accurate",
    "do_cell_matching": true
  },
  "images": {
    "extract": true,
    "classify": true,
    "generate_page_images": false,
    "generate_picture_images": true,
    "generate_table_images": true,
    "images_scale": 1.0
  },
  "performance": {
    "device": "auto",
    "num_threads": 4,
    "document_timeout": null
  },
  "chunking": {
    "enabled": false,
    "max_tokens": 512,
    "merge_peers": true
  },
  "output": {
    "default_format": "markdown"
  }
}

Configuration via API¶

Get Current Settings¶

curl http://localhost:5001/api/settings

Update Settings¶

curl -X PUT http://localhost:5001/api/settings \
  -H "Content-Type: application/json" \
  -d '{
    "ocr": {"backend": "tesseract"},
    "performance": {"num_threads": 8}
  }'

Reset to Defaults¶

curl -X POST http://localhost:5001/api/settings/reset

Troubleshooting¶

OCR Not Working¶

1. EasyOCR initialization error: Switch to ocrmac (macOS) or tesseract
2. GPU errors: Set use_gpu: false
3. Low confidence results: Lower confidence_threshold

Slow Processing¶

1. Reduce images_scale to 0.5
2. Use mode: "fast" for tables
3. Disable generate_page_images
4. Increase num_threads

Memory Issues¶

1. Enable document_timeout (e.g., 120 seconds)
2. Process fewer files in batch
3. Reduce images_scale
4. Disable chunking if not needed