Cite the dissertation and clarify the scope of archive observations

README.md

@@ -19,7 +19,7 @@ tags:
 
 This is a Sentence Transformers bi-encoder adapted by **[Saša Petalinkar](https://orcid.org/0009-0007-9664-3594)** from [intfloat/multilingual-e5-large](https://huggingface.co/intfloat/multilingual-e5-large) for **Serbian word-sense candidate ranking**. Given a sentence context and externally supplied candidate definitions, it ranks the candidates by cosine similarity. Its experiment preset is `mling`.
 
-These are original research checkpoint weights. **The retained training inputs have a substantial target-marking issue, and the historical evaluation figures below have not been independently verified for this exact weight file.** Read those limitations before using the model as a benchmark or production component.
+This checkpoint accompanies **Saša Z. Petalinkar's doctoral dissertation (University of Belgrade, 2026)**. The distillation method is described in **Section 3.4**, and the experiment results are reported in **Section 5.8**. See [Thesis and citation](#thesis-and-citation) for the full reference.
 
 ## Model and intended use
 
@@ -68,13 +68,13 @@ best = int(scores.argmax().item())
 print(candidates[best][0])
 ```
 
-The exact prefix `query: ` is required on **both** the context and candidate definitions to follow the experiment; do not substitute `passage: ` for definitions. Saved query/document prompts are empty strings, so loading the model does not apply this prefix automatically. For normal inference, use sentence-relative character offsets to surround the intended target with `**...**`. The training limitation below means that consistently target-sensitive behavior should not be assumed. Return the only candidate directly for a one-candidate item; for ambiguous items, all candidate definitions are required by the recorded evaluation protocol.
+The exact prefix `query: ` is required on **both** the context and candidate definitions to follow the experiment; do not substitute `passage: ` for definitions. Saved query/document prompts are empty strings, so loading the model does not apply this prefix automatically. For normal inference, use sentence-relative character offsets to surround the intended target with `**...**`. Return the only candidate directly for a one-candidate item; for ambiguous items, all candidate definitions are required by the recorded evaluation protocol.
 
 ## Training and checkpoint selection
 
 Training uses hard silver sense assignments from the LexiSense annotation pipeline. A context-definition pair has label 1 for the assigned sense and label 0 for other listed candidates. Candidates lacking definitions are skipped. Despite the experiment's “distillation” name, the implemented objective is hard-label cosine regression, without teacher logits, soft-label matching, temperature scaling, or KL divergence.
 
-The retained training-pair file contains **38,829 pairs**: 10,385 positive and 28,444 negative, covering 1,604 distinct sentence strings and five source-file values. All designated gold sentence texts were excluded by exact matching. A publication audit found zero exact overlaps with the 420 distinct sentence strings in the four retained gold files. This does not establish absence of near-duplicates or other leakage. The current training-file hash is recorded in the packaged provenance; no historical data hash establishes immutable input identity.
+The retained training-pair file contains **38,829 pairs**: 10,385 positive and 28,444 negative, covering 1,604 distinct sentence strings and five source-file values. All designated gold sentence texts were excluded by exact matching. A publication audit found zero exact overlaps with the 420 distinct sentence strings in the four retained gold files. This does not establish absence of near-duplicates or other leakage. The inspected training-file hash is recorded in the packaged provenance; see the archive inspection note below.
 
 | Recorded setting | Value |
 |---|---|
@@ -92,17 +92,11 @@ Generated trainer metadata records learning rate `5e-5`, linear scheduling, `ada
 
 Recorded software: Python 3.11.9, Sentence Transformers 5.5.0, Transformers 5.8.1, PyTorch 2.11.0+cu128, Accelerate 1.13.0, Datasets 4.8.5, and Tokenizers 0.22.2.
 
-## Known training-input limitation
+## Results reported in the dissertation
 
-An audit of the full retained JSONL found **38,727 of 38,829 pairs ending in empty `****` markers**; only 102 pairs contained a nonempty `**...**` span. Generated checkpoint cards also show empty markers. The model therefore cannot be described as having received consistently marked targets during training. The separate target field is not passed to the encoder.
+The dissertation (Section 5.8, Table 5-16) reports **1,394/1,921 correct (72.6% strict top-1)** for the trained `multilingual-e5-large` model (`mling` in the experiment code). The retained experiment summary records 1,894 covered targets and 73.60% covered-only accuracy. The final universe comprises 1,734 single-word targets and 187 multiword expressions. Strict accuracy counts the 27 uncovered targets as wrong; the retained report attributes them to missing candidate definitions.
 
-A mismatch between document offsets and sentence-relative slicing is a plausible cause inferred from the implementation. Its effect on these weights has not been isolated experimentally. These original weights are released without retraining or a silent correction of their training history.
-
-## Retained experiment results
-
-The handoff reports **1394/1921 correct (72.57% strict top-1)** for the `mling` trained experiment. It reports 1,894 covered targets and 73.60% covered-only accuracy. The final universe comprises 1,734 single-word targets and 187 multiword expressions. Strict accuracy counts the 27 uncovered targets as wrong; the retained report attributes them to missing candidate definitions.
-
-**These are historical experiment results, not independently verified metrics for this exact release.** The retained evaluation summary lacks checkpoint hashes and exact checkpoint paths, leaving its connection to this specific weight file unresolved.
+These figures are the results reported in the dissertation and agree with the retained experiment summary. The selected epochs and development scores in the saved training records agree with the experiment handoff. The full evaluation was not rerun for this Hub release; the release check below verifies model loading and a small inference example.
 
 The workbook evaluator adds the gold sense when it is absent from the supplied candidate set. Accordingly, these results measure ranking with a **gold-augmented candidate inventory**, not end-to-end candidate recall. One-candidate cases are answered deterministically without the encoder. These protocol choices matter when comparing other systems.
 
@@ -110,11 +104,17 @@ The workbook evaluator adds the gold sense when it is absent from the supplied c
 
 A local CPU smoke test on 2026-09-27 loaded these exact weights and executed the Python example above. It produced finite embeddings of the expected dimensions. The example selected the leaf sense although the synthetic sentence refers to paper. A successful technical load therefore should not be confused with successful disambiguation. See [runtime_verification.json](runtime_verification.json) for the observed scores. This is a three-text technical check, not an accuracy evaluation or a replication of the historical results.
 
+## Archive inspection note
+
+In the retained `silver_pairs.jsonl`, 38,727 of 38,829 pairs place the target markers at the end of the sentence rather than around the target span; 102 pairs contain a nonempty `**...**` span. The original checkpoint cards show the same format in their training examples, and their training configurations refer to this pair file. The exact count describes the retained file inspected during release preparation. The effect of this marking format on model performance was not separately measured.
+
+The retained Round 2 evaluation summary does not record weight-file checksums. The checksums in this release identify the uploaded files; the research results above are attributed to the dissertation and its experiment records.
+
 ## Provenance, attribution, and license
 
 The weights were adapted by **[Saša Petalinkar](https://orcid.org/0009-0007-9664-3594)**. Credit for the base model and its original authors belongs to the contributors identified in the [upstream model card](https://huggingface.co/intfloat/multilingual-e5-large). This adaptation is distributed under [MIT License](https://opensource.org/license/mit); see the included license files and preserve upstream attribution.
 
-[Companion implementation and reported settings, v0.1.0](https://github.com/sasa5linkar/serbian-wsd-distillation/tree/v0.1.0) document the workflow. That release is supporting documentation, not proof that every historical training/evaluation run used identical source code.
+[Companion implementation and reported settings, v0.1.0](https://github.com/sasa5linkar/serbian-wsd-distillation/tree/v0.1.0) document the workflow. That repository is the public software companion to the dissertation experiments.
 
 See [provenance.json](provenance.json) and [recorded_training_summary.json](recorded_training_summary.json) for packaged metadata. The released `model.safetensors` SHA-256 is:
 
@@ -122,4 +122,26 @@ See [provenance.json](provenance.json) and [recorded_training_summary.json](reco
 dc0cff1db0f5bf5072bf89b82b00b81cc30893d073914c8ce1d9b1f31a3b6b36
 ```
 
-The checksum identifies the released bytes; it does not certify the historical evaluation scores. Training corpora and external definition inventories are not included in this model repository.
+The checksum identifies the released weight file. Training corpora and external definition inventories are not included in this model repository.
+
+## Thesis and citation
+
+[Saša Z. Petalinkar](https://orcid.org/0009-0007-9664-3594) (2026). *Machine Learning and Large Language Models in the Development of Semantic Networks and Their Application in Automatic Text Understanding*. Doctoral dissertation manuscript, University of Belgrade. Written in Serbian.
+
+Original title: *Машинско учење и велики језички модели у развоју семантичких мрежа и њиховој примени на аутоматско разумевање текста*.
+
+- **Section 3.4, „Разрешење значења речи – дестилација“**: distillation method and experimental setup.
+- **Section 5.8, „Резултати дестилације модела за разрешење значења речи“, Table 5-16**: reported results for the `simple`, `tesla`, and `multilingual-e5-large` rankers. The last is called `mling` in the experiment code. Table 5-17 reports the paired significance tests.
+- **Section 5.6, Table 5-10**: mapping of the dissertation's model names to the pretrained checkpoints.
+
+The manuscript does not currently have a public URL or DOI. The [public software companion](https://github.com/sasa5linkar/serbian-wsd-distillation/tree/v0.1.0) contains the implementation, reported settings, and result summaries.
+
+```bibtex
+@unpublished{petalinkar2026semanticnetworks,
+  author = {Petalinkar, Saša Z.},
+  title = {Машинско учење и велики језички модели у развоју семантичких мрежа и њиховој примени на аутоматско разумевање текста},
+  year = {2026},
+  note = {Doctoral dissertation manuscript, University of Belgrade. Sections 3.4 and 5.8; Table 5-16},
+  language = {Serbian}
+}
+```

provenance.json

@@ -1,60 +1,86 @@
-{
-  "repo_id": "Tanor/serbian-wsd-distilled-e5-large",
-  "preset": "mling",
-  "release_date": "2026-09-27",
-  "base_model": "intfloat/multilingual-e5-large",
-  "base_revision_observed_at_preparation": "3d7cfbdacd47fdda877c5cd8a79fbcc4f2a574f3",
-  "base_metadata_observed_date": "2026-09-25",
-  "historical_base_revision_verified": false,
-  "license": "mit",
-  "weights": {
-    "file": "model.safetensors",
-    "sha256": "dc0cff1db0f5bf5072bf89b82b00b81cc30893d073914c8ce1d9b1f31a3b6b36",
-    "size_bytes": 2239607176,
-    "stored_dtype": [
-      "F32"
-    ]
-  },
-  "checkpoint_selection": {
-    "best_epoch": 7,
-    "orchestration_seed": 20260515,
-    "criterion": "development covered-only top-1 accuracy"
-  },
-  "training_pair_file_audit": {
-    "sha256": "0b0965273203a5285ce6bcc2638095306a77f6171063e455fa47aebc37836eda",
-    "pairs": 38829,
-    "positive": 10385,
-    "negative": 28444,
-    "distinct_sentence_strings": 1604,
-    "empty_trailing_target_markers": 38727,
-    "nonempty_marked_spans": 102,
-    "historical_input_identity_verified": false
-  },
-  "reported_round2_result": {
-    "split": "final_round2_matched",
-    "group": "total",
-    "model": "mling",
-    "model_name": "intfloat/multilingual-e5-large",
-    "mode": "trained",
-    "total_examples": 1921,
-    "covered_examples": 1894,
-    "coverage": 0.9859448204060385,
-    "correct_top1": 1394,
-    "incorrect_top1": 500,
-    "accuracy_covered": 0.7360084477296727,
-    "accuracy_covered_ci_low": 0.7156935322507435,
-    "accuracy_covered_ci_high": 0.7553679443783557,
-    "accuracy_covered_ci_95": "71.6-75.5",
-    "accuracy_strict": 0.7256637168141593,
-    "accuracy_strict_ci_low": 0.7052758505188592,
-    "accuracy_strict_ci_high": 0.7451508565883282,
-    "accuracy_strict_ci_95": "70.5-74.5",
-    "top3_accuracy": 0.9403379091869061,
-    "mrr": 0.8390760601887838
-  },
-  "reported_round2_checkpoint_identity_verified": false,
-  "reported_round2_protocol": "Gold sense appended if absent; one-candidate targets assigned without encoder; uncovered targets counted wrong in strict accuracy.",
-  "companion_code": "https://github.com/sasa5linkar/serbian-wsd-distillation/tree/v0.1.0",
-  "historical_code_identity_verified": false,
-  "source_model_weights_modified": false
-}
+{
+  "repo_id": "Tanor/serbian-wsd-distilled-e5-large",
+  "preset": "mling",
+  "release_date": "2026-09-27",
+  "base_model": "intfloat/multilingual-e5-large",
+  "base_revision_observed_at_preparation": "3d7cfbdacd47fdda877c5cd8a79fbcc4f2a574f3",
+  "base_metadata_observed_date": "2026-09-25",
+  "historical_base_revision_verified": false,
+  "license": "mit",
+  "weights": {
+    "file": "model.safetensors",
+    "sha256": "dc0cff1db0f5bf5072bf89b82b00b81cc30893d073914c8ce1d9b1f31a3b6b36",
+    "size_bytes": 2239607176,
+    "stored_dtype": [
+      "F32"
+    ]
+  },
+  "checkpoint_selection": {
+    "best_epoch": 7,
+    "orchestration_seed": 20260515,
+    "criterion": "development covered-only top-1 accuracy"
+  },
+  "training_pair_file_audit": {
+    "sha256": "0b0965273203a5285ce6bcc2638095306a77f6171063e455fa47aebc37836eda",
+    "pairs": 38829,
+    "positive": 10385,
+    "negative": 28444,
+    "distinct_sentence_strings": 1604,
+    "empty_trailing_target_markers": 38727,
+    "nonempty_marked_spans": 102,
+    "historical_input_identity_verified": false,
+    "scope_note": "Counts describe the retained JSONL inspected during release preparation. Saved checkpoint cards also show empty markers. Historical byte identity and the effect on reported scores were not established by this file inspection."
+  },
+  "reported_round2_result": {
+    "split": "final_round2_matched",
+    "group": "total",
+    "model": "mling",
+    "model_name": "intfloat/multilingual-e5-large",
+    "mode": "trained",
+    "total_examples": 1921,
+    "covered_examples": 1894,
+    "coverage": 0.9859448204060385,
+    "correct_top1": 1394,
+    "incorrect_top1": 500,
+    "accuracy_covered": 0.7360084477296727,
+    "accuracy_covered_ci_low": 0.7156935322507435,
+    "accuracy_covered_ci_high": 0.7553679443783557,
+    "accuracy_covered_ci_95": "71.6-75.5",
+    "accuracy_strict": 0.7256637168141593,
+    "accuracy_strict_ci_low": 0.7052758505188592,
+    "accuracy_strict_ci_high": 0.7451508565883282,
+    "accuracy_strict_ci_95": "70.5-74.5",
+    "top3_accuracy": 0.9403379091869061,
+    "mrr": 0.8390760601887838
+  },
+  "reported_round2_checkpoint_identity_verified": false,
+  "reported_round2_protocol": "Gold sense appended if absent; one-candidate targets assigned without encoder; uncovered targets counted wrong in strict accuracy.",
+  "companion_code": "https://github.com/sasa5linkar/serbian-wsd-distillation/tree/v0.1.0",
+  "historical_code_identity_verified": false,
+  "source_model_weights_modified": false,
+  "dissertation": {
+    "author": "Saša Z. Petalinkar",
+    "author_orcid": "https://orcid.org/0009-0007-9664-3594",
+    "title": "Машинско учење и велики језички модели у развоју семантичких мрежа и њиховој примени на аутоматско разумевање текста",
+    "title_english": "Machine Learning and Large Language Models in the Development of Semantic Networks and Their Application in Automatic Text Understanding",
+    "institution": "University of Belgrade",
+    "year": 2026,
+    "document_type": "doctoral dissertation manuscript",
+    "language": "Serbian",
+    "method_section": "3.4",
+    "method_section_title": "Разрешење значења речи – дестилација",
+    "results_section": "5.8",
+    "results_section_title": "Резултати дестилације модела за разрешење значења речи",
+    "results_table": "5-16",
+    "model_mapping_table": "5-10",
+    "public_url": null,
+    "doi": null
+  },
+  "reported_round2_result_source": {
+    "type": "doctoral dissertation manuscript and retained experiment summary",
+    "dissertation_section": "5.8",
+    "dissertation_table": "5-16",
+    "evaluation_rerun_for_hub_release": false,
+    "association_evidence": "Selected epochs and development scores agree between saved training records and experiment handoff; reported final counts agree with the dissertation."
+  }
+}