Create README.md

README.md

@@ -0,0 +1,176 @@
+---
+license: apache-2.0
+library_name: docling
+pipeline_tag: image-to-text
+tags:
+  - docling
+  - table-structure-recognition
+  - document-conversion
+  - tables
+  - pdf
+  - preview
+---
+
+# TableFormerV2
+
+> [!WARNING]
+> **Preview model.** TableFormerV2 is a preview release. Its weights, outputs, and
+> integration options can change in future releases without notice. The default
+> table structure model in Docling is still
+> [TableFormer V1](https://huggingface.co/docling-project/docling-models).
+
+TableFormerV2 is a table structure recognition model for
+[Docling](https://github.com/docling-project/docling). It takes an image of a
+table and predicts its structure as an
+[OTSL](https://arxiv.org/abs/2305.03393) token sequence, together with a
+bounding box for each cell. Docling then maps the cells back to the text of the
+document to build a `TableItem` in the `DoclingDocument`.
+
+## Model details
+
+| | |
+|---|---|
+| **Developed by** | IBM Research, for the Docling project |
+| **Model type** | Image-to-sequence (table structure + cell boxes) |
+| **Parameters** | ~52M (FP32) |
+| **Input** | Table crop, resized to 448×448 |
+| **Output** | OTSL structure tokens and one bounding box per cell |
+| **License** | Apache-2.0 |
+| **Status** | Preview |
+
+### Architecture
+
+- **Image encoder:** EfficientNetV2-S backbone with Squeeze-and-Excitation.
+- **Spatial mixer:** depthwise separable convolutions (no self-attention in the
+  encoder).
+- **Structure decoder:** cache-aware Transformer decoder with cross-attention to
+  the image features.
+- **Bounding-box head:** multi-layer attention decoder that predicts one box per
+  cell.
+
+The design is lightweight. It targets fast CPU inference and GPU batch
+inference.
+
+The model implementation is in
+[`docling-ibm-models`](https://github.com/docling-project/docling-ibm-models)
+(`docling_ibm_models.tableformer_v2`).
+
+## Usage with Docling
+
+Install Docling:
+
+```bash
+pip install docling
+```
+
+Docling downloads the weights from this repository automatically the first time
+you use the model. To download them before you run a conversion (for example,
+for offline use), run:
+
+```bash
+docling-tools models download tableformerv2
+```
+
+### Option 1: Use the preset
+
+The fastest way to enable TableFormerV2 is to select it by name.
+
+**CLI:**
+
+```bash
+docling report.pdf --table-structure-engine docling_tableformer_v2
+```
+
+**Docling Serve / Service Client:** set the `tableformer_v2` preset.
+
+```python
+from docling.datamodel.service.options import ConvertDocumentsOptions
+from docling.service_client import DoclingServiceClient
+
+options = ConvertDocumentsOptions(table_structure_preset="tableformer_v2")
+
+with DoclingServiceClient(url="http://localhost:5001") as client:
+    result = client.convert(source="report.pdf", options=options)
+    print(result.document.export_to_markdown())
+```
+
+### Option 2: Set the full pipeline options
+
+Use the Python SDK when you need full control over the pipeline. Set
+`table_structure_options` to `TableStructureV2Options`:
+
+```python
+from docling.datamodel.accelerator_options import AcceleratorOptions
+from docling.datamodel.base_models import InputFormat
+from docling.datamodel.pipeline_options import (
+    PdfPipelineOptions,
+    TableStructureV2Options,
+)
+from docling.document_converter import DocumentConverter, PdfFormatOption
+
+pipeline_options = PdfPipelineOptions(
+    do_table_structure=True,
+    table_structure_options=TableStructureV2Options(
+        # True:  match the predicted cells to the text cells of the PDF.
+        # False: use the cells predicted by the model and ignore the PDF cells.
+        do_cell_matching=True,
+    ),
+    accelerator_options=AcceleratorOptions(device="auto", num_threads=8),
+)
+
+converter = DocumentConverter(
+    format_options={
+        InputFormat.PDF: PdfFormatOption(pipeline_options=pipeline_options),
+    }
+)
+
+result = converter.convert("report.pdf")
+
+for table in result.document.tables:
+    print(table.export_to_dataframe())
+```
+
+To load pre-downloaded weights, set `artifacts_path` on the pipeline options:
+
+```python
+pipeline_options = PdfPipelineOptions(
+    artifacts_path="/path/to/models",  # contains docling-project--TableFormerV2/
+    table_structure_options=TableStructureV2Options(),
+)
+```
+
+### Options
+
+| Option | Default | Description |
+|---|---|---|
+| `do_cell_matching` | `True` | Match the predicted cells to the PDF text cells. Set to `False` if PDF cells span more than one column, because this can break the table output. |
+
+## Limitations
+
+- This is a **preview** model. Quality and behavior can change between
+  releases.
+- On Apple Silicon, the model runs on CPU. Docling does not use MPS for this
+  model.
+- The model sees only the table crop. Errors in the layout model (missed or
+  wrongly cropped tables) propagate to the table structure.
+
+## License
+
+This model is released under the
+[Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0).
+
+## Citation
+
+If you use TableFormerV2, please cite Docling:
+
+```bibtex
+@misc{Docling,
+  author = {Docling Team},
+  title = {Docling: An Efficient Open-Source Toolkit for AI-driven Document Conversion},
+  url = {https://arxiv.org/abs/2501.17887},
+  eprint = {2501.17887},
+  archivePrefix = {arXiv},
+  doi = {10.48550/arXiv.2501.17887},
+  year = {2025}
+}
+```