Spaces:

Pier-Jean
/

docling-studio

Running

App Files Files Community

docling-studio / README.md

Pier-Jean

Upload README.md with huggingface_hub

9f742a3 verified about 2 months ago

preview code

raw

history blame contribute delete

9.66 kB

metadata

title: Docling Studio
emoji: 📄
colorFrom: yellow
colorTo: blue
sdk: docker
app_port: 3000
pinned: false

Docling Studio

A visual document analysis studio powered by Docling. Upload a PDF, configure the extraction pipeline, and visualize the results — text, tables, images, formulas, bounding boxes — all from your browser.

Features

Home page with quick upload and recent documents
PDF viewer with page navigation, bounding box overlay, and resizable results panel
Configurable Docling pipeline — OCR, table extraction, code/formula enrichment, picture classification & description, image generation
Bounding box visualization — color-coded element overlay directly on the PDF
Per-page results — right panel syncs with the current PDF page
Markdown & HTML export of extracted content
Document management — upload, list, delete
Analysis history — re-visit and open past analyses
Dark / Light theme and FR / EN localization

Architecture

┌────────────┐         ┌──────────────────────┐
│  Frontend  │────────▶│   Document Parser    │
│  Vue 3     │  /api/* │ FastAPI + Docling    │
│  port 3000 │         │ SQLite + file storage│
└────────────┘         │   port 8000          │
                       └──────────────────────┘

Service	Stack	Role
frontend	Vue 3, TypeScript, Vite, Pinia	UI, PDF viewer, results display
document-parser	FastAPI, Docling, SQLite, pdf2image	REST API, document parsing, storage

Backend structure (clean architecture)

document-parser/
├── main.py                   # FastAPI app, CORS, lifespan
├── domain/                   # Pure domain — no HTTP, no DB
│   ├── models.py             # Document, AnalysisJob dataclasses
│   ├── ports.py              # Abstract protocols (converter, chunker)
│   └── value_objects.py      # ConversionResult, PageDetail, ChunkResult
├── api/                      # HTTP layer (FastAPI routers)
│   ├── schemas.py            # Pydantic DTOs (camelCase serialization)
│   ├── documents.py          # /api/documents endpoints
│   └── analyses.py           # /api/analyses endpoints
├── persistence/              # Data layer (SQLite via aiosqlite)
│   ├── database.py           # Connection management, schema init
│   ├── document_repo.py      # Document CRUD
│   └── analysis_repo.py      # AnalysisJob CRUD
├── services/                 # Use case orchestration
│   ├── document_service.py   # Upload, delete, preview
│   └── analysis_service.py   # Async Docling processing
└── tests/                    # 199 tests (pytest)

Frontend structure (feature-based)

frontend/src/
├── app/                      # App shell, router, global styles
├── pages/                    # Route-level pages
│   ├── HomePage.vue          # Landing page with upload & stats
│   ├── StudioPage.vue        # PDF viewer + config + results
│   ├── DocumentsPage.vue     # Document management
│   ├── HistoryPage.vue       # Past analyses
│   └── SettingsPage.vue      # Theme, language, API URL
├── features/                 # Feature modules
│   ├── analysis/             # Analysis store, API, bbox, UI components
│   ├── document/             # Document store, API, upload, list
│   ├── history/              # History store, API, navigation
│   └── settings/             # Settings store
└── shared/                   # Shared utilities (types, i18n, http, format)

Quick Start

Docling Studio ships two Docker image variants:

Variant	Image tag	Size	Description
remote	`latest-remote`	~270 MB	Lightweight — delegates to an external Docling Serve instance
local	`latest-local`	~1.9 GB	Full — runs Docling in-process, CPU-only (downloads ML models on first run)

Docker — remote mode (fastest)

docker run -p 3000:3000 \
  -e DOCLING_SERVE_URL=http://your-docling-serve:5001 \
  ghcr.io/scub-france/docling-studio:latest-remote

Docker — local mode (self-contained)

docker run -p 3000:3000 ghcr.io/scub-france/docling-studio:latest-local

Note: The first analysis takes longer as Docling downloads its ML models (~400 MB). Subsequent runs are fast.

Open http://localhost:3000

Docker Compose (for development)

git clone https://github.com/scub-france/Docling-Studio.git
cd Docling-Studio

# Local mode (default)
docker compose up --build

# Remote mode
CONVERSION_MODE=remote DOCLING_SERVE_URL=http://your-docling-serve:5001 docker compose up --build

Local Development

Backend (Python 3.12+):

cd document-parser
python -m venv .venv && source .venv/bin/activate

# Remote mode (lightweight)
pip install -r requirements.txt

# Local mode (with Docling)
pip install -r requirements-local.txt

uvicorn main:app --reload --port 8000

Frontend (Node 20+):

cd frontend
npm install
npm run dev

Running Tests

# Backend (199 tests)
cd document-parser
pip install pytest pytest-asyncio httpx
pytest tests/ -v

# Frontend (129 tests)
cd frontend
npm run test:run

Pipeline Options

These options map directly to Docling's PdfPipelineOptions. See the Docling documentation for details on each feature.

Option	Default	Description
`do_ocr`	`true`	OCR for scanned pages and embedded images
`do_table_structure`	`true`	Table detection and row/column reconstruction
`table_mode`	`accurate`	`accurate` (TableFormer) or `fast`
`do_code_enrichment`	`false`	Specialized OCR for code blocks
`do_formula_enrichment`	`false`	Math formula recognition (LaTeX output)
`do_picture_classification`	`false`	Classify images by type (chart, photo, diagram…)
`do_picture_description`	`false`	Generate image descriptions via VLM
`generate_picture_images`	`false`	Extract detected images as separate files
`generate_page_images`	`false`	Rasterize each page as an image
`images_scale`	`1.0`	Scale factor for generated images (0.1–10)

Configuration

All configuration is done via environment variables. See .env.example.

Variable	Default	Description
`CONVERSION_ENGINE`	`local`	`local` (in-process Docling) or `remote` (Docling Serve)
`DOCLING_SERVE_URL`	`http://localhost:5001`	Docling Serve endpoint (remote mode only)
`DOCLING_SERVE_API_KEY`	—	API key for Docling Serve (optional)
`CORS_ORIGINS`	`http://localhost:3000,...`	CORS allowed origins (comma-separated)
`UPLOAD_DIR`	`./uploads`	File storage directory
`DB_PATH`	`./data/docling_studio.db`	SQLite database path
`CONVERSION_TIMEOUT`	`600`	Max seconds for a single Docling conversion

CI / Release

GitHub Actions pipelines (see .github/workflows/):

Workflow	Trigger	What it does
CI	push to `main`, pull requests	Lint + type check + Backend tests + Frontend tests + build
Release	push tag `v*`	Build & push two multi-arch Docker images (`remote` + `local`) to `ghcr.io`
Docs	push to `main` (docs changes)	Build & deploy MkDocs to GitHub Pages

We follow Semantic Versioning with a simplified Git Flow. See CONTRIBUTING.md for the full release process.

Performance & System Requirements

Document type	Pages	Approx. time (CPU)
Simple report	5–10	~30s–1 min
Research paper	10–30	~1–2 min
Large document	100+	~2–5 min

Docker Desktop settings

	Remote image	Local image
Image size	~270 MB	~1.9 GB
Memory	2 GB	6 GB (recommended 8 GB+)
CPUs	2	4 (recommended 8+)

Platform support

All Docker images are multi-arch (linux/amd64 + linux/arm64). No GPU required.

Tech Stack

Frontend: Vue 3, TypeScript, Vite, Pinia, DOMPurify
Backend: FastAPI, Docling 2.x, SQLite (aiosqlite), pdf2image
CI: GitHub Actions
Infra: Docker Compose + Nginx

Contributing

Contributions are welcome! Please open an issue first to discuss what you'd like to change.

License

MIT — Pier-Jean Malandrino