Upload README.md with huggingface_hub

README.md

@@ -12,28 +12,60 @@ tags:
 - low-resource
 base_model: facebook/w2v-bert-2.0
 pipeline_tag: automatic-speech-recognition
+metrics:
+- wer
+- cer
+model-index:
+- name: badini-w2v-bert-normalized
+  results:
+  - task:
+      type: automatic-speech-recognition
+    metrics:
+    - type: wer
+      value: 26.53
+      name: WER (normalized)
+    - type: cer
+      value: 11.32
+      name: CER (normalized)
 ---
 
-# Badini Kurdish ASR (Wav2Vec2-BERT)
+# Badini Kurdish ASR — Normalized (Wav2Vec2-BERT)
 
 An automatic speech recognition (ASR) model for **Badini Kurdish** (a variety of
 Kurmanji, written in Arabic script), fine-tuned from
 [`facebook/w2v-bert-2.0`](https://huggingface.co/facebook/w2v-bert-2.0)
 with a CTC head.
 
+This repository includes a companion text-normalization module
+(`badini_normalize.py`) alongside the model, so following the usage example
+below gives normalized output: **WER 26.5%, CER 11.3%** on a 1,123-sample
+test set.
+
+For the raw acoustic model without normalization (WER 46.5%, CER 12.0% on
+2,038 samples), see
+[computeram/badini-w2v-bert](https://huggingface.co/computeram/badini-w2v-bert).
 
 ## Input requirements
 
 - Audio must be **16 kHz, mono**.
-- Resample any other sample rate to 16 kHz before running inference.
+- Resample any other sample rate to 16 kHz before inference.
 
 ## Usage
 
 ```python
 import torch, soundfile as sf
 from transformers import Wav2Vec2BertForCTC, Wav2Vec2BertProcessor
+from huggingface_hub import hf_hub_download
+import importlib.util
+
+repo_id = "computeram/badini-w2v-bert-normalized"
+
+# download and load the companion normalization module
+norm_path = hf_hub_download(repo_id, "badini_normalize.py")
+spec = importlib.util.spec_from_file_location("badini_normalize", norm_path)
+badini_normalize = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(badini_normalize)
 
-repo_id = "computeram/badini-w2v-bert"
 processor = Wav2Vec2BertProcessor.from_pretrained(repo_id)
 model = Wav2Vec2BertForCTC.from_pretrained(repo_id).eval()
 
@@ -42,19 +74,15 @@ inputs = processor(speech, sampling_rate=16000, return_tensors="pt")
 with torch.no_grad():
     logits = model(**inputs).logits
 pred_ids = torch.argmax(logits, dim=-1)
-print(processor.batch_decode(pred_ids)[0])
-```
-
-## Important: text normalization
+raw_text = processor.batch_decode(pred_ids)[0]
 
-This repository contains **only the acoustic model**. The raw output is plain CTC
-decoding. A separate normalization pipeline — punctuation restoration,
-number-to-word expansion (with Badini-specific remapping), character
-normalization, and word-variant correction — is applied in the downstream
-application and is **not** included here. Output straight from this model will
-not match the fully normalized transcripts.
+# apply the normalization pipeline (punctuation handling, Badini number
+# expansion, character/word-variant unification)
+text = badini_normalize.normalize_transcript(raw_text)
+print(text)
+```
 
 ## Intended use
 
-Speech transcription for Badini Kurdish. Given the WER, best used with
-downstream normalization/post-processing rather than as raw final text.
+Speech transcription for Badini Kurdish, with the recommended normalization
+already applied by following the usage example above.