Release Koshur OCR v2 — 100k epoch-18 checkpoint

README.md

@@ -10,32 +10,47 @@ language:
 library_name: pytorch
 ---
 
-# Koshur OCR
+# Koshur OCR v2
 
-A compact Kashmiri Perso-Arabic printed-line OCR model from **Kash Labs AI**.
+A compact Kashmiri Perso-Arabic **printed-line** OCR model from **Kash Labs AI**.
 
-## Results
+## v2 results
 
-- **Deduplicated validation CER:** 28.13%
-- **Deduplicated exact match:** 15.11%
+- **Deduplicated validation CER:** 22.62%
+- **Deduplicated exact match:** 25.54%
+- **Full validation CER:** 23.06%
+- **Full validation exact match:** 26.40%
 - **Validation rows:** 920 deduplicated / 1,000 full
-- **Best epoch:** 47 of 60
-- **Training rows:** 10,000 synthetic sentence-line images
-- **W&B:** https://wandb.ai/kash-ai-labs-kash-labs/koshur-pixel-ocr/runs/hdab4ed4
+- **Best epoch:** 18
+- **Training rows:** 100,000 synthetic sentence-line images
+- **W&B:** https://wandb.ai/kash-ai-labs-kash-labs/koshur-pixel-ocr/runs/ctc-100k-control-p0-20260729T061125Z-retry1
+
+The deduplicated errors comprise 378 insertions, 6,859 deletions, and 3,146 substitutions over 45,907 reference characters.
 
 ## Architecture
 
-`64×2048 grayscale line → CNN (48→96→160→192) → temporal feature dropout (p=0.3) → 2-layer bidirectional GRU (256 per direction) → 138-way CTC`
+`64×2048 grayscale line → CNN (48→96→160→192) → 2-layer bidirectional GRU (256 per direction) → 155-way CTC`
+
+The model has **4,475,931 trainable parameters**, a 154-character inventory, and no temporal feature dropout in the selected v2 control checkpoint. This is a custom PyTorch checkpoint, not a Transformers-format model.
+
+## Versioning
 
-The network has **4,467,210 trainable parameters**. The repository contains a custom PyTorch checkpoint, not a Transformers-format model.
+- `v1.0.0` — 10k temporal-dropout checkpoint, 28.13% deduplicated CER
+- `v2.0.0` — 100k control checkpoint, 22.62% deduplicated CER (current)
+
+Use a Hub revision to pin a release.
 
 ## Files
 
-- `best-model.pt` — best epoch-47 state dictionary, character inventory, architecture metadata, and validation CER
+- `best-model.pt` — epoch-18 state dictionary, character inventory, architecture metadata, and validation CER
 - `model.py` — architecture, preprocessing, CTC decoding, and `recognize_line()`
-- `config.json` — training and preprocessing configuration
+- `config.json` — release, training, preprocessing, metrics, and checkpoint checksum
+
+## Local CPU or Apple Silicon inference
 
-## Local inference
+```bash
+pip install -r requirements.txt
+```
 
 ```python
 from PIL import Image
@@ -43,13 +58,16 @@ from model import recognize_line
 
 text, diagnostics = recognize_line(Image.open("single-line.png"))
 print(text)
+print(diagnostics)
 ```
 
-The input should be one tightly cropped printed line. It is normalized to height 64 and left-aligned on a width-2048 canvas.
+The input should be one tightly cropped, upright printed line. It is resized to height 64 and left-aligned on a width-2048 canvas. Inference runs on CPU and does not require a GPU.
 
 ## Limitations
 
-- Experimental research checkpoint; error rate remains substantial.
-- Trained on synthetic printed line images, not handwriting or complete pages.
-- Training targets had the established Kashmiri diacritic set removed. This model recognizes base text and does not restore those diacritics.
-- Predictions should be reviewed before publication or archival use.
+- The reported score is an in-domain synthetic validation result, not real-world scan quality.
+- Trained on synthetic printed lines, not handwriting or full pages.
+- Camera photos should be rotated, deskewed, tightly cropped, and segmented into individual lines.
+- Training targets exclude the established Kashmiri diacritic set; the model recognizes base text and does not restore those marks.
+- Error rate remains substantial, with deletions the dominant residual error.
+- Predictions require review before publication or archival use.

best-model.pt

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:ebdf01f2ebe7cb8bd06d7233940e0f72ff7ef894942bf3de801df931d50990ad
-size 17889058
+oid sha256:38382437ace33611c15ddbbf718ddcd88bf25f31092883bdcab540734199648d
+size 17924194

config.json

@@ -1,34 +1,42 @@
 {
-  "run_name": "ctc-temporal-intervention-p0.3-20260728T163111Z",
-  "smoke": false,
-  "train_rows": 10000,
+  "release": "v2.0.0",
+  "run_name": "ctc-100k-control-p0-20260729T061125Z-retry1",
+  "wandb_run": "https://wandb.ai/kash-ai-labs-kash-labs/koshur-pixel-ocr/runs/ctc-100k-control-p0-20260729T061125Z-retry1",
+  "train_rows": 100000,
   "val_rows": 1000,
   "val_dedup_rows": 920,
-  "epochs": 60,
+  "trained_epochs": 38,
+  "best_epoch": 18,
   "batch_size": 32,
   "learning_rate": 0.0007,
   "weight_decay": 0.0001,
-  "temporal_dropout_p": 0.3,
+  "temporal_dropout_p": 0.0,
   "seed": 11,
   "image_height": 64,
   "image_width": 2048,
   "canvas_align": "left",
   "horizontal_stride": 4,
-  "cnn_channels": [
-    48,
-    96,
-    160,
-    192
-  ],
+  "cnn_channels": [48, 96, 160, 192],
   "rnn_hidden": 256,
   "rnn_layers": 2,
   "rnn_dropout": 0.05,
-  "snapshot_volume": "koshur-ppocrv6-kp-breakthrough-data",
-  "snapshot_relative_path": "kp_breakthrough/sentence_line-r874c4df69c3f-n10000-1000-len90",
+  "character_classes": 154,
+  "ctc_classes_including_blank": 155,
+  "parameters": 4475931,
+  "snapshot_relative_path": "kp_scale/sentence_line-r874c4df69c3f-n100000-1000-len90",
   "snapshot_images_mirrored": true,
   "images_unmirrored_in_memory": true,
   "labels_reversed_for_ltr_ctc": true,
-  "hf_token_required": false,
   "dataset_images_uploaded": false,
-  "selection_metric": "val_dedup/cer"
-}
+  "selection_metric": "val_dedup/cer",
+  "metrics": {
+    "val_cer": 0.23057324840764332,
+    "val_exact_rate": 0.264,
+    "val_dedup_cer": 0.22617465745964668,
+    "val_dedup_exact_rate": 0.2554347826086957,
+    "val_dedup_insertions": 378,
+    "val_dedup_deletions": 6859,
+    "val_dedup_substitutions": 3146
+  },
+  "checkpoint_sha256": "38382437ace33611c15ddbbf718ddcd88bf25f31092883bdcab540734199648d"
+}

model.py

@@ -19,12 +19,11 @@ CHECKPOINT = Path(__file__).with_name("best-model.pt")
 
 
 class TemporalFeatureDropout(nn.Module):
-    def __init__(self, probability: float = 0.3):
+    def __init__(self, probability: float = 0.0):
         super().__init__()
         self.p = float(probability)
 
     def forward(self, x: torch.Tensor) -> torch.Tensor:
-        # Dropout is disabled by model.eval() during inference.
         if not self.training or self.p == 0.0:
             return x
         keep = x.new_empty((x.shape[0], x.shape[1], 1)).bernoulli_(1.0 - self.p)
@@ -32,7 +31,7 @@ class TemporalFeatureDropout(nn.Module):
 
 
 class KoshurCRNN(nn.Module):
-    def __init__(self, n_classes: int, temporal_dropout_p: float = 0.3):
+    def __init__(self, n_classes: int, temporal_dropout_p: float = 0.0):
         super().__init__()
         self.cnn = nn.Sequential(
             nn.Conv2d(1, 48, 3, padding=1), nn.BatchNorm2d(48), nn.ReLU(), nn.MaxPool2d((2, 2)),
@@ -59,7 +58,9 @@ class KoshurCRNN(nn.Module):
 def load_model() -> tuple[KoshurCRNN, dict[int, str]]:
     checkpoint = torch.load(CHECKPOINT, map_location="cpu", weights_only=False)
     chars = list(checkpoint["chars"])
-    model = KoshurCRNN(len(chars) + 1, temporal_dropout_p=0.3)
+    architecture = checkpoint.get("architecture") or {}
+    temporal_dropout_p = float(architecture.get("temporal_dropout_p", 0.0))
+    model = KoshurCRNN(len(chars) + 1, temporal_dropout_p=temporal_dropout_p)
     model.load_state_dict(checkpoint["model_state_dict"], strict=True)
     model.eval()
     return model, {i + 1: char for i, char in enumerate(chars)}
@@ -75,8 +76,10 @@ def preprocess(image: Image.Image) -> tuple[torch.Tensor, int, int]:
     canvas = Image.new("L", (IMAGE_WIDTH, IMAGE_HEIGHT), 255)
     canvas.paste(normal, (0, 0))
     pixels = 1.0 - np.asarray(canvas, dtype=np.float32) / 255.0
-    input_length = max(1, min(IMAGE_WIDTH // HORIZONTAL_STRIDE,
-                              int(math.ceil(resized_width / HORIZONTAL_STRIDE))))
+    input_length = max(
+        1,
+        min(IMAGE_WIDTH // HORIZONTAL_STRIDE, int(math.ceil(resized_width / HORIZONTAL_STRIDE))),
+    )
     return torch.from_numpy(pixels).unsqueeze(0).unsqueeze(0), input_length, resized_width
 
 
@@ -87,8 +90,6 @@ def ctc_decode(ids: list[int], itos: dict[int, str]) -> str:
         if token != 0 and token != previous:
             output.append(itos.get(token, ""))
         previous = token
-    # CTC was trained in increasing-x visual order. Reverse back to logical RTL
-    # order for human-readable Kashmiri output.
     return "".join(output)[::-1]
 
 
@@ -99,5 +100,9 @@ def recognize_line(image: Image.Image) -> tuple[str, dict[str, int]]:
         logits = model(tensor)
     ids = logits.argmax(-1).permute(1, 0)[0, :input_length].tolist()
     text = ctc_decode(ids, itos)
-    return text, {"input_width": image.width, "input_height": image.height,
-                  "resized_width": resized_width, "ctc_frames": input_length}
+    return text, {
+        "input_width": image.width,
+        "input_height": image.height,
+        "resized_width": resized_width,
+        "ctc_frames": input_length,
+    }

requirements.txt

@@ -1,3 +1,3 @@
-torch>=2.5
-numpy>=2.1
-Pillow>=11.0
+torch==2.5.1
+numpy==2.1.3
+Pillow==11.0.0