Update README.md

README.md

@@ -1,8 +1,98 @@
 ---
+language:
+- he
+library_name: timm
 license: mit
 pipeline_tag: image-classification
 tags:
 - hebrew-manuscripts
-- handwritten-hebrew-documents
-- hebrew-script-mode-classification
----
+- hebrew-paleography
+- document-image-analysis
+- script-classification
+- computational-humanities
+- digital-humanities
+- attention-visualization
+- convnext
+---
+
+# Hebrew Script Mode Classifier
+
+The Hebrew Script Mode Classifier is a deep learning model for classifying
+handwritten Hebrew document images into two script mode categories:
+
+- **Square**
+- **Non-square**
+
+The accompanying inference interface also produces a spatial attention
+overlay showing the regions that received higher weights from the model's
+gated-attention pooling layer.
+
+## Model Details
+
+### Model Description
+
+The model processes a handwritten Hebrew document image using a ConvNeXt
+feature extractor followed by masked gated-attention pooling and a binary
+classification head.
+
+The pixel mask prevents padded image regions from contributing to the
+attention pooling operation. The output consists of class probabilities for
+`square` and `non_square`.
+
+The public checkpoint is approximately 950 MB.
+
+- **Shared by:** Tel Aviv University Computational Humanities (TAU-CH) GitHub organization
+- **Model type:** Image classifier with a ConvNeXt backbone and masked gated-attention pooling
+- **Task:** Hebrew script mode classification
+- **Language:** Hebrew handwritten document images
+- **Number of classes:** 2
+- **Classes:** `square`, `non_square`
+- **Framework:** PyTorch and timm
+- **Checkpoint format:** PyTorch `.pt`
+- **Base architecture:** ConvNeXt; the exact backbone configuration is stored in the checkpoint
+- **Default backbone fallback:** `convnext_base.fb_in22k_ft_in1k`
+
+### Model Sources
+
+- **GitHub repository:**  
+  https://github.com/TAU-CH/midrash_hebrew_script_mode_classifier
+
+- **Model repository:**  
+  https://huggingface.co/beratkurar/hebrew_script_mode_classifier
+
+- **Interactive Colab demo:**  
+  https://colab.research.google.com/github/TAU-CH/midrash_hebrew_script_mode_classifier/blob/main/Hebrew_Script_Mode_Classifier.ipynb
+
+- **Paper:** TODO: add the publication link when available
+
+## Uses
+
+### Direct Use
+
+The model is intended for classification of handwritten
+Hebrew document images into square and non-square script modes.
+
+The provided Colab interface allows users to:
+
+1. Start the inference environment.
+2. Upload a handwritten Hebrew document image.
+3. Receive class probabilities for square and non-square.
+4. View an attention heatmap overlaid on the input image.
+
+The simplest way to use the model is through the public Colab notebook:
+
+[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/TAU-CH/midrash_hebrew_script_mode_classifier/blob/main/Hebrew_Script_Mode_Classifier.ipynb)
+
+### Mixed-Script Documents
+
+A page may contain multiple hands, scripts, annotations, marginalia, or mixed
+square and non-square writing. The model returns one page-level classification
+and does not explicitly model mixed-script content.
+
+### Image Cropping
+
+Images larger than the configured maximum dimensions are center-cropped.
+Relevant evidence near the page boundaries may therefore be excluded.
+
+The public inference code uses checkpoint-configured maximum dimensions, with
+a fallback of 2500 × 2500 pixels.