Add Phase 0 research package

.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.venv/
+.env
+.DS_Store
+checkpoints/
+wandb/
+results/predictions/
+*.bin
+*.pt
+*.pth
+

ATTRIBUTION_AND_LICENSING.md

@@ -0,0 +1,54 @@
+# Attribution and Licensing Record
+
+This file tracks asset-level licensing. It is not legal advice.
+
+## Release decision
+
+The project metadata uses `license: other` with a pending-clarification label. The dataset is MIT-licensed, but the intermediate checkpoint has no declared license. Public release of derivative weights remains blocked.
+
+| Asset | Role | Recorded status | Required action |
+|---|---|---|---|
+| `microsoft/trocr-base-printed` | Ultimate base | MIT via Microsoft UniLM | Retain attribution and MIT notice |
+| `Ransaka/TrOCR-Sinhala` | Intermediate checkpoint | No declared license | Obtain explicit clarification before publishing derivative weights |
+| `Ransaka/sinhala_synthetic_ocr-large` | Training data | MIT `LICENSE`; DOI 10.57967/hf/1809 | Attribute Ransaka Ravihara and cite DOI |
+| `avishadilhara/sinhala-ocr-lk-acts-1010` | Evaluation source | CC BY 4.0 | Attribute authors and cite source |
+| Tesseract | Baseline | Apache 2.0 | Record version and cite |
+| Surya OCR | Optional baseline | Version-dependent code and model terms | Re-check terms at execution time |
+
+## Mandatory evidence to add
+
+- Link to the checkpoint license-clarification discussion
+- Author response or other permission record
+- Immutable revisions for all Hub assets
+- Copies or links to applicable notices at public release
+
+## Citations
+
+### TrOCR
+
+```bibtex
+@article{li2021trocr,
+  title={TrOCR: Transformer-based Optical Character Recognition with Pre-trained Models},
+  author={Li, Minghao and Lv, Tengchao and Cui, Lei and Lu, Yijuan and Florencio, Dinei and Zhang, Cha and Li, Zhoujun and Wei, Furu},
+  journal={arXiv preprint arXiv:2109.10282},
+  year={2021}
+}
+```
+
+### Synthetic Sinhala OCR dataset
+
+```bibtex
+@misc{ravihara2024sinhala,
+  author={Ransaka Ravihara},
+  title={sinhala_synthetic_ocr-large},
+  year={2024},
+  publisher={Hugging Face},
+  doi={10.57967/hf/1809},
+  url={https://huggingface.co/datasets/Ransaka/sinhala_synthetic_ocr-large}
+}
+```
+
+### Real Sinhala legislative-acts benchmark
+
+Add the authors' preferred BibTeX from arXiv:2606.29378 before publication. Do not reconstruct bibliographic details from memory when the canonical citation is available.
+

PROTOCOL.md

@@ -0,0 +1,235 @@
+# Pre-registered Research Protocol
+
+## 1. Administrative record
+
+- Project: TrOCR Sinhala Printed Lines
+- Protocol version: 1.0
+- Protocol date: 2026-07-28
+- Researcher: Kalana Hewapathirana
+- Planned repository: `kaan84/trocr-sinhala-printed-lines`
+- Phase: Phase 0, before training
+
+Commit this file before training. Any later change must be appended to the deviation log with its date, rationale, and expected impact.
+
+## 2. Research question
+
+Does synthetic-data fine-tuning of `Ransaka/TrOCR-Sinhala` improve printed, line-level Sinhala OCR on real documents?
+
+## 3. Hypotheses
+
+### Primary hypothesis H1
+
+Fine-tuning the starting checkpoint on `Ransaka/sinhala_synthetic_ocr-large` will reduce CER on a real printed Sinhala line benchmark relative to the unchanged checkpoint and Tesseract 5.5.
+
+### Secondary hypothesis H2
+
+The fine-tuned checkpoint will reduce WER relative to the unchanged checkpoint and Tesseract 5.5.
+
+### Secondary hypothesis H3
+
+Performance will be lower on older or visibly degraded documents than on newer or cleaner documents.
+
+## 4. Experimental unit and scope
+
+The evaluation unit is one cropped text-line image paired with one reference transcription. Page-level and line-level metrics must not be combined in the same comparison table without an explicit unit label.
+
+Included:
+
+- Printed Sinhala
+- Real and synthetic text lines
+- CER and WER
+- Starting checkpoint and Tesseract comparisons
+- Optional Surya comparison
+
+Excluded:
+
+- Handwriting
+- End-to-end page layout analysis
+- Production-readiness claims
+- Hyperparameter optimization outside the declared contingency rules
+
+## 5. Assets and fixed revisions
+
+Before training, replace `TO_RECORD` with immutable Hub commit hashes:
+
+| Asset | Role | Revision |
+|---|---|---|
+| `Ransaka/TrOCR-Sinhala` | Starting model | `TO_RECORD` |
+| `Ransaka/sinhala_synthetic_ocr-large` | Train/validation | `TO_RECORD` |
+| `avishadilhara/sinhala-ocr-lk-acts-1010` | Real evaluation source | `TO_RECORD` |
+
+The experiment manifest must also record the Transformers, Datasets, PyTorch, CUDA, jiwer, Pillow, NumPy, and Tesseract versions.
+
+## 6. Data splits
+
+### Synthetic dataset
+
+Use the published dataset's single train split.
+
+- Split seed: 42
+- Train share: 90%
+- Validation share: 10%
+- Split method: deterministic shuffled index split
+- No sample may appear in both partitions
+- Save the exact indices to version-controlled JSON files
+- Record SHA-256 checksums of the index files
+
+### Real-document benchmark
+
+Use only the published test partition for the final real-document analysis. Do not use its labels for training or hyperparameter selection.
+
+Because the source is page-level, create line crops and transcriptions using one versioned procedure. Record:
+
+- Source page identifier
+- Line identifier
+- Crop coordinates
+- Reference transcription
+- Segmentation method and version
+- Any exclusion reason
+- Document year or period, if available
+
+Freeze the line benchmark before final evaluation. Manual corrections made after viewing model predictions invalidate the final test and must trigger a new held-out test set.
+
+## 7. Preprocessing
+
+### Images
+
+- Convert to RGB
+- Use the processor associated with the starting checkpoint
+- Do not apply test-time enhancement unless declared as a separate experimental condition
+- Preserve raw evaluation crops
+
+### Text normalization
+
+Report both raw and normalized metrics.
+
+The fixed normalized condition:
+
+1. Unicode normalize with NFC.
+2. Convert line breaks and tabs to spaces.
+3. Collapse consecutive Unicode whitespace to one ASCII space.
+4. Strip leading and trailing whitespace.
+5. Preserve Sinhala characters, punctuation, numerals, and letter case.
+
+Do not remove punctuation or diacritics in the primary analysis. Any alternative normalization is exploratory and must be labeled accordingly.
+
+## 8. Training configuration
+
+| Parameter | Fixed value |
+|---|---|
+| Model | `Ransaka/TrOCR-Sinhala` |
+| Optimizer | AdamW |
+| Learning rate | 4e-5 |
+| Epochs | 10 |
+| Effective batch size | 8 |
+| Precision | FP16 if supported |
+| Seeds | 42, 123, 2026 |
+| Generation beams | 4 |
+| Save strategy | Every epoch |
+| Selection rule | Lowest validation CER |
+
+Gradient accumulation may change only to preserve effective batch size 8. Physical batch size may be lowered for memory limits.
+
+## 9. Contingency rules
+
+Permitted without redefining hypotheses:
+
+- Reduce physical batch size and increase gradient accumulation.
+- Resume from the latest complete checkpoint after infrastructure interruption.
+- Use gradient checkpointing if the GPU cannot hold the declared effective batch.
+- Disable FP16 only if the hardware or software fails to support it reliably.
+
+Not permitted in the confirmatory experiment:
+
+- Selecting a new learning rate after inspecting final-test results
+- Increasing epochs because final-test performance is weak
+- Training on real-test labels
+- Removing difficult samples based on prediction errors
+- Reporting only the best seed
+
+Any other adjustment becomes exploratory and must be separated from confirmatory results.
+
+## 10. Baselines
+
+Required:
+
+1. Unchanged `Ransaka/TrOCR-Sinhala`
+2. Tesseract 5.5
+3. Fine-tuned TrOCR for all three seeds
+
+Optional:
+
+4. Surya OCR, only after recording the exact version and applicable model terms
+
+Every system must receive the same frozen line images. Use system-appropriate decoding without model-specific alteration of references.
+
+## 11. Metrics
+
+Primary: Character Error Rate.
+
+Secondary: Word Error Rate.
+
+Use `jiwer` with transformations that exactly implement Section 7. Compute:
+
+- Per-sample edit counts
+- Corpus-level raw CER and WER
+- Corpus-level normalized CER and WER
+- Mean and standard deviation across training seeds
+- Paired bootstrap 95% confidence interval for differences, resampling line IDs with 10,000 replicates and bootstrap seed 42
+
+## 12. Decision rules
+
+H1 is supported only when:
+
+1. The fine-tuned model's mean normalized CER is lower than both the starting checkpoint and Tesseract 5.5.
+2. Improvement over each comparator has a paired-bootstrap 95% confidence interval that excludes zero in the favorable direction.
+3. All three fine-tuning seeds improve over the starting checkpoint.
+
+H2 uses the same rule with normalized WER.
+
+H3 is descriptive unless each period contains at least 30 evaluation lines. Report counts and confidence intervals and avoid strong generalization when slices are small.
+
+Publish results regardless of outcome. A result above published page-level baselines is not automatically a failure because the evaluation units differ.
+
+## 13. Error analysis
+
+Before viewing predictions, define these error groups:
+
+- Character substitution
+- Character deletion
+- Character insertion
+- Whitespace or word-boundary error
+- Punctuation or numeral error
+- Degraded print
+- Skew or rotation
+- Segmentation failure
+- Mixed-language or unsupported symbol
+
+Sample up to 50 errors using a deterministic random seed. Do not select only visually compelling cases.
+
+## 14. Reporting requirements
+
+The final report must include:
+
+- Every seed
+- Mean and standard deviation
+- Confidence intervals
+- Dataset and code revisions
+- Hardware and runtime
+- Raw and normalized metrics
+- Exact evaluation-unit counts
+- Exclusion counts and reasons
+- Period-stratified results when valid
+- Known limitations
+- Deviations from this protocol
+
+## 15. Licensing gate
+
+The training dataset license is confirmed MIT. The intermediate checkpoint currently has no declared license. Training experiments may be prepared, but public redistribution of derivative weights is blocked until the checkpoint licensing position is clarified or independently reviewed.
+
+## 16. Deviation log
+
+| Date | Change | Rationale | Expected impact | Confirmatory or exploratory |
+|---|---|---|---|---|
+| — | None | — | — | — |
+

README.md

@@ -0,0 +1,229 @@
+---
+language:
+- si
+license: other
+license_name: pending-upstream-checkpoint-license-clarification
+library_name: transformers
+pipeline_tag: image-to-text
+tags:
+- trocr
+- ocr
+- sinhala
+- printed-text
+- vision-encoder-decoder
+base_model: Ransaka/TrOCR-Sinhala
+datasets:
+- Ransaka/sinhala_synthetic_ocr-large
+- avishadilhara/sinhala-ocr-lk-acts-1010
+metrics:
+- cer
+- wer
+---
+
+# TrOCR Sinhala Printed Lines
+
+> Phase 0 research repository. No fine-tuned weights or final evaluation results have been released yet.
+
+This project investigates whether fine-tuning `Ransaka/TrOCR-Sinhala` on synthetic Sinhala text-line images improves printed, line-level Sinhala OCR performance on real documents.
+
+## Project status
+
+| Workstream | Status |
+|---|---|
+| Research scope | Locked in `PROTOCOL.md` |
+| Dataset license | Confirmed MIT |
+| Intermediate checkpoint license | Clarification required |
+| Training | Not started |
+| Evaluation | Not started |
+| Model weights | Not published |
+
+The synthetic dataset contains an MIT `LICENSE` file. However, `Ransaka/TrOCR-Sinhala` does not currently declare a license. This repository therefore uses `license: other` as a temporary, conservative status. Do not publish or redistribute derived weights until the checkpoint author provides a clear license or the release basis is independently reviewed.
+
+## Research question
+
+Does synthetic-data fine-tuning of TrOCR improve printed, line-level Sinhala OCR on real documents?
+
+## Scope
+
+### In scope
+
+- Printed Sinhala text
+- Line-level text recognition
+- Character Error Rate (CER)
+- Word Error Rate (WER)
+- Comparisons with the unmodified checkpoint and Tesseract 5.5
+- Optional Surya comparison when its applicable terms are confirmed
+- Period-stratified analysis where document-year metadata is available
+
+### Out of scope
+
+- Handwriting
+- Full-page layout detection or reading order
+- Production or high-stakes deployment
+- Broad Sinhala-English code mixing
+- Claims of parity with page-level commercial or large vision-language systems
+
+## Data
+
+### Training and validation
+
+`Ransaka/sinhala_synthetic_ocr-large`
+
+- 6,969 synthetic Sinhala image-text pairs
+- One published `train` split
+- Five reported font families
+- Dataset DOI: [10.57967/hf/1809](https://doi.org/10.57967/hf/1809)
+- Repository `LICENSE`: MIT
+- Fixed project split: 90% train and 10% validation using seed 42
+
+The exact generated indices and dataset revision must be written to the experiment manifest before training.
+
+### Real-document evaluation
+
+`avishadilhara/sinhala-ocr-lk-acts-1010`
+
+- 1,010 page images from Sri Lankan legislative acts
+- Published splits: train 707, test 202, evaluation 101
+- License: CC BY 4.0
+- Paper: [arXiv:2606.29378](https://arxiv.org/abs/2606.29378)
+
+TrOCR is a line-recognition model. The page dataset must therefore be converted into a documented, deterministic line-level benchmark before direct evaluation. Page-level benchmark figures are contextual references and must not be presented as directly comparable line-level results.
+
+## Pre-registered experiment
+
+The hypotheses, fixed splits, seeds, metrics, normalization, hyperparameters, decision rules, and reporting requirements are defined in [`PROTOCOL.md`](PROTOCOL.md). Material deviations must be documented before results are interpreted.
+
+## Planned baselines
+
+| System | Role | Primary comparison |
+|---|---|---|
+| `Ransaka/TrOCR-Sinhala` | Starting checkpoint | Measures improvement from additional fine-tuning |
+| Tesseract 5.5 | Permissive classical baseline | CER and WER on the same line images |
+| Surya OCR | Optional research baseline | CER and WER on the same evaluation unit |
+
+Published page-level results are contextual targets only:
+
+| System | CER | WER | Evaluation unit |
+|---|---:|---:|---|
+| Tesseract v5 | 10.69% | Not reported | Real pages |
+| Surya OCR | 8.84% | 26.64% | Real pages |
+| Google Document AI | 2.06% | Not reported | Real pages |
+| Fine-tuned LightOnOCR-2-1B | 1.05% | 5.63% | Real pages |
+
+These figures come from a June 2026 preprint and are not direct line-level acceptance thresholds.
+
+## Planned training configuration
+
+| Parameter | Pre-registered value |
+|---|---|
+| Optimizer | AdamW |
+| Learning rate | 4e-5 |
+| Epochs | 10 |
+| Effective batch size | 8 |
+| Precision | FP16 when supported |
+| Seed | 42 |
+| Evaluation beams | 4 |
+| Runs | 3 independent runs |
+
+The machine-readable configuration is in [`configs/phase0.yaml`](configs/phase0.yaml).
+
+## Evaluation and reporting
+
+CER is the primary metric and WER is secondary. Report:
+
+- Results for every seed, plus mean and standard deviation
+- Exact dataset revisions and split-index checksum
+- Raw and normalized metrics
+- 95% paired bootstrap confidence intervals for model differences
+- Error examples grouped by degradation type
+- Results by document period where supported
+- Runtime and hardware details
+
+Final results belong in `results/metrics.json` and the table below. Do not add zero-value placeholders to Hugging Face `model-index` metadata because they can be mistaken for real results.
+
+| System | Dataset/slice | CER mean ± SD | WER mean ± SD | Status |
+|---|---|---:|---:|---|
+| Starting checkpoint | Real Sinhala line benchmark | TBD | TBD | Not run |
+| Fine-tuned model | Real Sinhala line benchmark | TBD | TBD | Not run |
+| Tesseract 5.5 | Real Sinhala line benchmark | TBD | TBD | Not run |
+| Surya OCR | Real Sinhala line benchmark | TBD | TBD | Optional |
+
+## Intended use
+
+The eventual model is intended for research and prototyping involving printed Sinhala text lines, including OCR experiments, document digitization research, and accessibility prototypes. Human review is required for consequential use.
+
+## Limitations
+
+- Synthetic training data may not represent real scanning noise, skew, bleed-through, compression, damaged print, or historical typography.
+- Training fonts cover only a limited part of Sinhala typography.
+- Accuracy may degrade on older documents, handwriting, mixed-language text, unusual symbols, curved lines, and full pages.
+- Line segmentation quality can dominate end-to-end page performance.
+- Results from legislative acts may not generalize to receipts, books, forms, signs, or contemporary digital screenshots.
+
+## Bias and responsible use
+
+The training domain may overrepresent clean, computer-generated Sinhala and underrepresent historical fonts and real capture conditions. Evaluate new domains before use. Do not use unreviewed OCR output as authoritative evidence in legal, medical, financial, identity, or public-administration decisions.
+
+Public legislative documents can contain names. Preserve source attribution, minimize unnecessary retention, and review extracted text before redistribution.
+
+## Planned inference
+
+The final release will support the standard Transformers interface:
+
+```python
+from PIL import Image
+from transformers import TrOCRProcessor, VisionEncoderDecoderModel
+
+repo_id = "kaan84/sinhala-print-trocr"
+processor = TrOCRProcessor.from_pretrained(repo_id)
+model = VisionEncoderDecoderModel.from_pretrained(repo_id)
+
+image = Image.open("sinhala-line.png").convert("RGB")
+pixel_values = processor(images=image, return_tensors="pt").pixel_values
+generated_ids = model.generate(pixel_values, num_beams=4)
+text = processor.batch_decode(generated_ids, skip_special_tokens=True)[0]
+print(text)
+```
+
+This snippet will work only after weights and processor assets are published.
+
+## Repository structure
+
+```text
+.
+├── README.md
+├── PROTOCOL.md
+├── RISK_REGISTER.md
+├── ATTRIBUTION_AND_LICENSING.md
+├── REPRODUCIBILITY_CHECKLIST.md
+├── requirements.txt
+├── configs/
+│   └── phase0.yaml
+├── scripts/
+│   └── README.md
+├── assets/
+│   └── README.md
+├── runs/
+│   └── README.md
+└── results/
+    ├── README.md
+    └── metrics.template.json
+```
+
+## Release gates
+
+1. Obtain and archive explicit licensing clarification for `Ransaka/TrOCR-Sinhala`.
+2. Record immutable dataset and model revisions.
+3. Commit split indices and their checksum.
+4. Complete three seeded runs.
+5. Run every baseline on identical evaluation units.
+6. Populate real metrics and add `model-index` metadata.
+7. Complete the reproducibility checklist.
+8. Publish model weights only after the licensing gate passes.
+
+## Citation
+
+If this research is published, add its final citation here. Upstream citations and licensing notes are maintained in [`ATTRIBUTION_AND_LICENSING.md`](ATTRIBUTION_AND_LICENSING.md).
+
+
+

REPRODUCIBILITY_CHECKLIST.md

@@ -0,0 +1,50 @@
+# Reproducibility Checklist
+
+Complete every item before public release.
+
+## Claims and scope
+
+- [x] Primary research question is stated.
+- [x] Confirmatory hypotheses are stated before training.
+- [x] In-scope and out-of-scope uses are stated.
+- [ ] Final claims match the evaluation unit.
+
+## Data
+
+- [ ] Immutable model and dataset revisions recorded.
+- [ ] Train and validation indices committed.
+- [ ] Split-index SHA-256 checksums recorded.
+- [ ] Real line benchmark frozen before prediction review.
+- [ ] Exclusion rules and counts reported.
+- [ ] Dataset licenses and attributions included.
+
+## Training
+
+- [x] Seeds and fixed hyperparameters declared.
+- [ ] Hardware and runtime recorded.
+- [ ] Dependency versions recorded.
+- [ ] Checkpoints saved in safetensors format.
+- [ ] TensorBoard logs retained under `runs/`.
+- [ ] Three seeded runs completed.
+
+## Evaluation
+
+- [x] CER is the primary metric.
+- [x] WER is secondary.
+- [x] Text normalization is specified.
+- [ ] Raw and normalized results reported.
+- [ ] Paired bootstrap confidence intervals reported.
+- [ ] Baselines run on identical evaluation units.
+- [ ] Period-level sample counts reported.
+- [ ] Error analysis follows the pre-declared taxonomy.
+
+## Publication
+
+- [ ] Intermediate checkpoint license clarified.
+- [ ] Model-card metadata updated with the final license.
+- [ ] Real results added to `model-index`.
+- [ ] Inference example tested from a clean environment.
+- [ ] Intended use, limitations, bias, and responsible-use sections reviewed.
+- [ ] DOI generated after the repository becomes stable.
+- [ ] Final citation added.
+

RISK_REGISTER.md

@@ -0,0 +1,33 @@
+# Risk Register
+
+Scales: likelihood and impact are Low, Medium, or High. The owner should update status at each project checkpoint.
+
+| ID | Risk | Likelihood | Impact | Early indicator | Mitigation | Contingency | Owner | Status |
+|---|---|---|---|---|---|---|---|---|
+| R01 | No declared license for `Ransaka/TrOCR-Sinhala` | High | High | No license tag or file | Request explicit clarification; retain evidence; attribute upstreams | Keep repository research-only and do not publish weights | Researcher | Open |
+| R02 | Synthetic-to-real domain shift | High | High | Validation improves while real CER remains weak | Use real frozen test benchmark; report gap; add pre-declared augmentation only in later exploratory phase | Publish negative result and design Phase 1 domain adaptation | Researcher | Open |
+| R03 | Line segmentation confounds recognition | High | High | Errors cluster around bad crops or merged lines | Version segmentation pipeline; audit a deterministic sample; retain crop coordinates | Report recognition and segmentation failures separately | Researcher | Open |
+| R04 | Older documents perform substantially worse | High | Medium | Period-level CER rises for early years | Report period-stratified metrics; document typography and degradation | Limit intended use and prioritize later historical augmentation | Researcher | Open |
+| R05 | Test-set leakage during benchmark construction | Medium | High | References corrected after predictions are viewed | Freeze benchmark before evaluation; checksum manifests; blind correction workflow | Create a new untouched holdout | Researcher | Open |
+| R06 | Too few independent real test units | Medium | Medium | Wide confidence intervals | Report paired bootstrap intervals and exact sample counts | Add a separately licensed benchmark without merging claims improperly | Researcher | Open |
+| R07 | Colab or GPU interruption | Medium | Medium | Runtime disconnects or out-of-memory errors | Save each epoch; log revisions; use FP16 and gradient accumulation | Resume from last complete checkpoint under protocol rules | Researcher | Open |
+| R08 | Non-deterministic training | Medium | Medium | Large seed-to-seed variance | Fix seeds; record environment; run three seeds | Increase runs in an explicitly amended protocol | Researcher | Open |
+| R09 | Inconsistent text normalization | Medium | High | Metric changes across scripts | Centralize normalization; unit test examples; report raw and normalized scores | Recompute all systems using the corrected fixed pipeline | Researcher | Open |
+| R10 | Baselines evaluated on different units | Medium | High | Page metrics compared with line metrics | Label evaluation unit in every table; run local baselines on identical lines | Treat published page results as context only | Researcher | Open |
+| R11 | Surya terms change or are misinterpreted | Medium | Medium | Conflicting license thresholds | Pin version and archive current terms before use | Omit Surya and retain Tesseract as required baseline | Researcher | Open |
+| R12 | Public documents contain personal names | Low | Medium | Named individuals appear in extracted text | Minimize retained text; preserve provenance; review redistribution | Release aggregate metrics and restricted examples only | Researcher | Open |
+| R13 | Model card overstates readiness | Medium | High | Unqualified benchmark or production claims | Use release gates; distinguish page and line results; maintain limitations | Correct card and issue a new version note | Researcher | Open |
+| R14 | Placeholder metrics mistaken for results | Medium | High | Zero values appear in metadata | Do not add `model-index` until results exist; use `TBD` only in prose | Remove incorrect metadata immediately | Researcher | Controlled |
+| R15 | Dependency or dataset revision drift | Medium | Medium | Re-run changes without code edits | Pin revisions and environment; save lock file or environment export | Reproduce using the archived manifest | Researcher | Open |
+
+## Review cadence
+
+Review this register:
+
+1. Before data download
+2. Before the first training run
+3. Before final-test evaluation
+4. Before any public release
+
+Close a risk only when evidence is recorded in the repository.
+

assets/README.md

@@ -0,0 +1,14 @@
+# Assets
+
+Place only redistributable demonstration images here.
+
+For each image, record:
+
+- Source
+- Creator
+- License
+- Date accessed
+- Whether the transcription is manually verified
+
+Do not upload benchmark images unless their license and redistribution terms permit it.
+

configs/phase0.yaml

@@ -0,0 +1,57 @@
+project:
+  name: trocr-sinhala-printed-lines
+  protocol_version: "1.0"
+  protocol_date: "2026-07-28"
+
+assets:
+  base_model:
+    id: Ransaka/TrOCR-Sinhala
+    revision: TO_RECORD
+  training_dataset:
+    id: Ransaka/sinhala_synthetic_ocr-large
+    revision: TO_RECORD
+    split: train
+  evaluation_dataset:
+    id: avishadilhara/sinhala-ocr-lk-acts-1010
+    revision: TO_RECORD
+    split: test
+
+data_split:
+  seed: 42
+  train_fraction: 0.90
+  validation_fraction: 0.10
+
+training:
+  optimizer: adamw
+  learning_rate: 0.00004
+  epochs: 10
+  effective_batch_size: 8
+  fp16: true
+  seeds: [42, 123, 2026]
+  save_strategy: epoch
+  selection_metric: normalized_cer
+  selection_mode: min
+
+generation:
+  num_beams: 4
+
+normalization:
+  unicode_form: NFC
+  convert_linebreaks_and_tabs_to_spaces: true
+  collapse_whitespace: true
+  strip_outer_whitespace: true
+  preserve_punctuation: true
+  preserve_diacritics: true
+
+evaluation:
+  primary_metric: cer
+  secondary_metric: wer
+  report_raw_and_normalized: true
+  bootstrap_replicates: 10000
+  bootstrap_seed: 42
+  confidence_level: 0.95
+
+release:
+  publish_weights: false
+  blocker: Ransaka/TrOCR-Sinhala has no declared license
+

requirements.txt

@@ -0,0 +1,13 @@
+accelerate
+datasets
+evaluate
+huggingface_hub
+jiwer
+numpy
+Pillow
+pyyaml
+safetensors
+tensorboard
+torch
+transformers
+

results/README.md

@@ -0,0 +1,11 @@
+# Results
+
+Store final, machine-readable results here.
+
+- `metrics.json` — aggregate and per-seed results
+- `predictions/` — sample IDs, references, predictions, and edit counts
+- `bootstrap/` — paired comparison intervals
+- `manifests/` — revisions, environment, split hashes, and hardware
+
+Do not publish sensitive or unnecessarily identifying text. Do not add `metrics.json` until evaluation has actually run.
+

results/metrics.template.json

@@ -0,0 +1,8 @@
+{
+  "status": "not_run",
+  "evaluation_unit": "line",
+  "dataset_revision": "TO_RECORD",
+  "normalization_version": "protocol-1.0",
+  "systems": []
+}
+

runs/README.md

@@ -0,0 +1,13 @@
+# Training Logs
+
+Upload TensorBoard event files under seed-specific directories:
+
+```text
+runs/
+├── seed-42/
+├── seed-123/
+└── seed-2026/
+```
+
+Do not overwrite runs. Each run must record the git commit, asset revisions, hardware, start time, end time, and configuration checksum.
+

scripts/README.md

@@ -0,0 +1,15 @@
+# Scripts
+
+Add version-controlled programs here during Phase 1:
+
+- `make_splits.py` — deterministic synthetic train/validation indices
+- `prepare_real_lines.py` — page-to-line benchmark construction
+- `train.py` — three-seed fine-tuning entry point
+- `evaluate.py` — raw and normalized CER/WER
+- `bootstrap.py` — paired bootstrap confidence intervals
+- `run_tesseract.py` — Tesseract baseline
+- `run_surya.py` — optional Surya baseline
+- `validate_release.py` — verify required files, revisions, metrics, and license gate
+
+Each script must expose `--help`, accept revisions and seeds explicitly, and write a machine-readable manifest.
+