Update CITATION.cff with correct repository link; enhance README files with architecture details, training data, recognition examples, and evaluation metrics for the Ukrainian OCR/ICR model.

CITATION.cff

@@ -6,7 +6,7 @@ license: Apache-2.0
 authors:
   - family-names: "Sielikhov"
     given-names: "Volodymyr"
-repository-code: "https://huggingface.co/YOUR_USER/YOUR_MODEL"
+repository-code: "https://huggingface.co/Valerii02/ukr-htr-convtext"
 preferred-citation:
   type: article
   title: "HTR-ConvText: Leveraging Convolution and Textual Information for Handwritten Text Recognition"

README.md

@@ -13,6 +13,10 @@ tags:
 - pytorch
 - onnx
 pipeline_tag: image-to-text
+base_model: DAIR-Group/HTR-ConvText
+metrics:
+- cer
+- wer
 ---
 
 # Ukrainian OCR / ICR (HTR-ConvText)
@@ -24,7 +28,16 @@ Ukrainian translation: [README.uk.md](README.uk.md).
 
 This repository packages a Ukrainian OCR/ICR model for handwritten and partially printed text with a Hugging Face-native API (`AutoModel` + `AutoProcessor`).
 
-The architecture is adapted from the HTR-ConvText line of work and prepared for production-style inference:
+**Architecture:** HTR-ConvText — hybrid CNN + Vision Transformer with ResNet-18 + MobileViT (MVP) backbone, hierarchical ConvText encoder (U-Net-like down/upsampling), CTC decoding. Input: 64×3072 px (height × max width), 151-character vocabulary (Ukrainian + symbols).
+
+**Training data:**
+- [ukrainian-handwriting-synth](https://github.com/ValeriiSielikhov/ukrainian-handwriting-synth) — synthetic handwritten lines
+- [Ukrainian Handwritten Text](https://www.kaggle.com/datasets/annyhnatiuk/ukrainian-handwritten-text) — ~37k segmented lines
+- **Total:** 1,696,499 samples (Train 90% / Val 5% / Test 5%)
+
+**Training:** 500k iterations, batch 16 + grad accum 4, SAM optimizer, EMA (decay 0.9999), TCM warmup 40k iters, scan simulation and detector-error augmentations. Hardware: NVIDIA B200 (180GB VRAM), Beyond.pl / Run:ai.
+
+The packaged release includes:
 - deterministic preprocessing in a custom processor,
 - CTC greedy decoding in the processor,
 - checkpoint conversion from original `.pth` format to HF artifacts,
@@ -66,6 +79,15 @@ text = processor.batch_decode(logits)[0]
 print(text)
 ```
 
+## Recognition Examples
+
+| Example | Image | GT | Prediction | CER | WER |
+|---------|-------|----|------------|-----|-----|
+| 1 | ![example_1](images/example_1.png) | Департаменту патрульної поліції | Департаменту нагрульної поліції | 0.065 | 0.33 |
+| 2 | ![example_2](images/example_2.png) | за порушення правил дорожнього руху | за порушення правил дорожнього Дуку | 0.057 | 0.20 |
+
+*Real-world inference on scanned Ukrainian documents. GT = ground truth, CER/WER per sample.*
+
 ## Repository Files
 
 - `configuration_htr.py`: HF config class.
@@ -119,11 +141,14 @@ Recommended acceptance thresholds:
 - CER delta abs <= `0.005`
 - WER delta abs <= `0.01`
 
-## Evaluation (Fill With Your Final Numbers)
+## Evaluation
 
 | Split | CER | WER | Notes |
 |---|---:|---:|---|
-| test | TODO | TODO | Replace with measured values |
+| test (84,826) | — | — | Held-out from training split; add metrics after eval |
+| real-world (124) | 0.176 | 0.440 | Scanned docs, handwritten + printed (`images/`) |
+
+*Real-world metrics use micro-averaging and `format_string_for_wer` normalization. The 124-image set is from production-like scans; the held-out test split (84,826) can be evaluated with your pipeline.*
 
 ## Limitations
 
@@ -149,4 +174,19 @@ Apache-2.0. See `LICENSE`.
 
 ## Citation
 
-If you use this model, cite both upstream HTR-ConvText and this packaged release (see `CITATION.cff`).
+If you use this model, cite both upstream HTR-ConvText and this packaged release.
+
+**Upstream (HTR-ConvText):**
+```bibtex
+@misc{truc2025htrconvtext,
+  title={HTR-ConvText: Leveraging Convolution and Textual Information for Handwritten Text Recognition},
+  author={Pham Thach Thanh Truc and Dang Hoai Nam and Huynh Tong Dang Khoa and Vo Nguyen Le Duy},
+  year={2025},
+  eprint={2512.05021},
+  archivePrefix={arXiv},
+  primaryClass={cs.CV},
+  url={https://arxiv.org/abs/2512.05021},
+}
+```
+
+**This model:** See `CITATION.cff` for full attribution.

README.uk.md

@@ -6,6 +6,15 @@
 
 Цей репозиторій пакує українську OCR/ICR модель для рукописного та частково друкованого тексту у форматі, зручному для Hugging Face (`AutoModel` + `AutoProcessor`).
 
+**Архітектура:** HTR-ConvText — гібрид CNN + Vision Transformer (ResNet-18 + MobileViT), CTC декодування. Вхід: 64×3072 px, 151 символ.
+
+**Дані для тренування:**
+- [ukrainian-handwriting-synth](https://github.com/ValeriiSielikhov/ukrainian-handwriting-synth) — синтетичний рукопис
+- [Ukrainian Handwritten Text](https://www.kaggle.com/datasets/annyhnatiuk/ukrainian-handwritten-text) — ~37k рядків
+- **Всього:** 1,696,499 зразків (Train 90% / Val 5% / Test 5%)
+
+**Тренування:** 500k ітерацій, SAM, EMA, scan simulation, detector-error аугментації. NVIDIA B200 (180GB VRAM).
+
 Репозиторій включає:
 - кастомний HF `Processor` з PIL-препроцесінгом,
 - CTC greedy decode,
@@ -36,6 +45,15 @@ text = processor.batch_decode(logits)[0]
 print(text)
 ```
 
+## Приклади розпізнавання
+
+| Приклад | Зображення | GT | Prediction | CER | WER |
+|---------|------------|----|------------|-----|-----|
+| 1 | ![example_1](images/example_1.png) | Департаменту патрульної поліції | Департаменту нагрульної поліції | 0.065 | 0.33 |
+| 2 | ![example_2](images/example_2.png) | за порушення правил дорожнього руху | за порушення правил дорожнього Дуку | 0.057 | 0.20 |
+
+*Інференс на реальних сканах українських документів. GT = еталонний текст.*
+
 ## Конвертація чекпойнта в HF формат
 
 ```bash
@@ -71,6 +89,12 @@ python validate_parity.py \
 - CER delta abs <= `0.005`
 - WER delta abs <= `0.01`
 
+## Оцінка (Evaluation)
+
+| Split | CER | WER | Примітки |
+|---|---:|---:|---|
+| real-world (124) | 0.176 | 0.440 | Скани документів (рукопис + друк) |
+
 ## Відомі обмеження
 
 - Складні артефакти скану, сильний blur, дуже низький контраст знижують якість.