Add TypedDicts: RougeScore, TokenizationStats family, CorefResult; export from public APIs

- metrics.py: add RougeScore TypedDict (precision/recall/fmeasure);
  rouge_score() now returns dict[str, RougeScore] instead of
  dict[str, tuple[float, float, float]] (breaking change)
- word_tokenization.py: add CharLevelStats, WordLevelStats, GlobalStats,
  TokenizationStats TypedDicts; update compute_stats() return type;
  _flatten_result() uses @overload to accept both TokenizationStats and
  generic Mapping without a cast
- benchmarks/__init__.py: export RougeScore, CharLevelStats, WordLevelStats,
  GlobalStats, TokenizationStats
- _fastcoref.py: rename CorefResultDict -> CorefResult; alias the
  fastcoref.modeling.CorefResult import as FastCorefResult to avoid clash
- coref/__init__.py: export CorefResult
- coref/core.py: update return type and fallback return to use CorefResult
- tag/named_entity.py: improve EntitySpan docstring
- tests/extra/testx_benchmarks.py: update rouge tests for named-field access;
  add test_rouge_score_return_type and test_compute_stats_return_type
- CHANGELOG.md: add migration notes for all TypedDicts

Co-authored-by: bact <128572+bact@users.noreply.github.com>
Agent-Logs-Url: https://github.com/PyThaiNLP/pythainlp/sessions/de0a9df1-25ba-4e89-a047-7ee0664753c1

Author: Copilot

CHANGELOG.md

@@ -19,6 +19,73 @@ and this project adheres to
 
 ## [Unreleased]
 
+### Added
+
+- `RougeScore` TypedDict in `pythainlp.benchmarks`: precision, recall, and
+  fmeasure fields replace the previous `tuple[float, float, float]` value
+  in the `rouge_score()` return dict. **Breaking change** – migrate as follows:
+
+  ```python
+  # Before (tuple indexing, error-prone)
+  precision, recall, fmeasure = scores["rouge1"]
+
+  # After (named fields)
+  precision  = scores["rouge1"]["precision"]
+  recall     = scores["rouge1"]["recall"]
+  fmeasure   = scores["rouge1"]["fmeasure"]
+  ```
+
+- `CharLevelStats`, `WordLevelStats`, `GlobalStats`, and `TokenizationStats`
+  TypedDicts in `pythainlp.benchmarks`: give named, type-safe access to the
+  dict returned by `word_tokenization.compute_stats()`.
+
+  ```python
+  # Before (opaque nested dict)
+  result = compute_stats(ref, hyp)
+  tp = result["char_level"]["tp"]
+
+  # After (same access, now type-safe with TokenizationStats)
+  from pythainlp.benchmarks import TokenizationStats
+  result: TokenizationStats = compute_stats(ref, hyp)
+  tp = result["char_level"]["tp"]
+  ```
+
+- `CorefResult` TypedDict is now exported from `pythainlp.coref`.
+  `coreference_resolution()` return type updated from `list[dict[str, Any]]`
+  to `list[CorefResult]`.
+
+  ```python
+  # Before
+  from pythainlp.coref import coreference_resolution
+
+  # After – import the TypedDict for type annotations
+  from pythainlp.coref import CorefResult, coreference_resolution
+  ```
+
+- `EntitySpan` TypedDict (`pythainlp.tag.named_entity`, #1363) and
+  `BleuScore` TypedDict (`pythainlp.benchmarks`, #1365) were introduced in
+  previous releases. Migration notes for completeness:
+
+  ```python
+  # EntitySpan – Before (plain dict)
+  entity = {"text": ["สมชาย"], "span": [0, 1], "entity_type": "PERSON"}
+
+  # EntitySpan – After (TypedDict constructor)
+  from pythainlp.tag.named_entity import EntitySpan
+  entity = EntitySpan(text=["สมชาย"], span=[0, 1], entity_type="PERSON")
+  ```
+
+  ```python
+  # BleuScore – Before (plain dict, no type hint)
+  score = bleu_score(refs, hyps)
+  print(score["bleu"])
+
+  # BleuScore – After (TypedDict annotation)
+  from pythainlp.benchmarks import BleuScore, bleu_score
+  score: BleuScore = bleu_score(refs, hyps)
+  print(score["bleu"])
+  ```
+
 ### Fixed
 
 - thai2rom_onnx: fix ONNX encoder model and fix inference bugs (#1349)

pythainlp/benchmarks/__init__.py

@@ -5,6 +5,11 @@
 
 __all__: list[str] = [
     "BleuScore",
+    "CharLevelStats",
+    "GlobalStats",
+    "RougeScore",
+    "TokenizationStats",
+    "WordLevelStats",
     "benchmark",
     "bleu_score",
     "character_error_rate",
@@ -14,9 +19,16 @@
 
 from pythainlp.benchmarks.metrics import (
     BleuScore,
+    RougeScore,
     bleu_score,
     character_error_rate,
     rouge_score,
     word_error_rate,
 )
-from pythainlp.benchmarks.word_tokenization import benchmark
+from pythainlp.benchmarks.word_tokenization import (
+    CharLevelStats,
+    GlobalStats,
+    TokenizationStats,
+    WordLevelStats,
+    benchmark,
+)

pythainlp/benchmarks/metrics.py

@@ -16,7 +16,7 @@
 
 
 class BleuScore(TypedDict):
-    """BLEU score"""
+    """BLEU score components returned by :func:`bleu_score`."""
 
     bleu: float  # BLEU score as a percentage (0.0 to 100.0)
     precisions: list[float]
@@ -26,6 +26,14 @@ class BleuScore(TypedDict):
     ref_length: int
 
 
+class RougeScore(TypedDict):
+    """Precision, recall, and F-measure for a single ROUGE type."""
+
+    precision: float
+    recall: float
+    fmeasure: float
+
+
 def _get_ngrams(tokens: list[str], n: int) -> list[tuple[str, ...]]:
     """
     Get n-grams from a list of tokens.
@@ -249,7 +257,7 @@ def rouge_score(
     hypothesis: str,
     tokenize: str = "newmm",
     rouge_types: Optional[list[str]] = None,
-) -> dict[str, tuple[float, float, float]]:
+) -> dict[str, RougeScore]:
     """
     Calculate ROUGE scores for Thai text with automatic tokenization.
 
@@ -269,8 +277,9 @@ def rouge_score(
     :param Optional[list[str]] rouge_types: list of ROUGE types to calculate.
         Default is ["rouge1", "rouge2", "rougeL"]
 
-    :return: dictionary mapping ROUGE type to (precision, recall, fmeasure)
-    :rtype: dict[str, tuple[float, float, float]]
+    :return: dictionary mapping ROUGE type to a :class:`RougeScore` typed dict
+        with ``'precision'``, ``'recall'``, and ``'fmeasure'`` keys.
+    :rtype: dict[str, RougeScore]
 
     :Example:
     ::
@@ -280,9 +289,9 @@ def rouge_score(
         reference = "สวัสดีครับ วันนี้อากาศดีมาก"
         hypothesis = "สวัสดีค่ะ วันนี้อากาศดี"
         scores = rouge_score(reference, hypothesis)
-        print(f"ROUGE-1 F-measure: {scores['rouge1'][2]:.4f}")
-        print(f"ROUGE-2 F-measure: {scores['rouge2'][2]:.4f}")
-        print(f"ROUGE-L F-measure: {scores['rougeL'][2]:.4f}")
+        print(f"ROUGE-1 F-measure: {scores['rouge1']['fmeasure']:.4f}")
+        print(f"ROUGE-2 F-measure: {scores['rouge2']['fmeasure']:.4f}")
+        print(f"ROUGE-L F-measure: {scores['rougeL']['fmeasure']:.4f}")
     """
     from pythainlp.tokenize import word_tokenize
 
@@ -297,7 +306,7 @@ def rouge_score(
         hypothesis, engine=tokenize, keep_whitespace=False
     )
 
-    result: dict[str, tuple[float, float, float]] = {}
+    result: dict[str, RougeScore] = {}
 
     for rouge_type in rouge_types:
         if rouge_type == "rouge1":
@@ -309,9 +318,12 @@ def rouge_score(
             ref_count = len(ref_tokens)
             hyp_count = len(hyp_tokens)
 
-            result[rouge_type] = _calculate_precision_recall_fmeasure(
+            precision, recall, fmeasure = _calculate_precision_recall_fmeasure(
                 overlap, hyp_count, ref_count
             )
+            result[rouge_type] = RougeScore(
+                precision=precision, recall=recall, fmeasure=fmeasure
+            )
 
         elif rouge_type == "rouge2":
             # Bigram-based
@@ -325,19 +337,25 @@ def rouge_score(
             ref_count = len(ref_bigrams)
             hyp_count = len(hyp_bigrams)
 
-            result[rouge_type] = _calculate_precision_recall_fmeasure(
+            precision, recall, fmeasure = _calculate_precision_recall_fmeasure(
                 overlap, hyp_count, ref_count
             )
+            result[rouge_type] = RougeScore(
+                precision=precision, recall=recall, fmeasure=fmeasure
+            )
 
         elif rouge_type == "rougeL":
             # Longest Common Subsequence-based
             lcs_len = _lcs_length(ref_tokens, hyp_tokens)
             ref_count = len(ref_tokens)
             hyp_count = len(hyp_tokens)
 
-            result[rouge_type] = _calculate_precision_recall_fmeasure(
+            precision, recall, fmeasure = _calculate_precision_recall_fmeasure(
                 lcs_len, hyp_count, ref_count
             )
+            result[rouge_type] = RougeScore(
+                precision=precision, recall=recall, fmeasure=fmeasure
+            )
 
     return result
 

pythainlp/benchmarks/word_tokenization.py

@@ -5,7 +5,8 @@
 
 import re
 import sys
-from typing import TYPE_CHECKING, Union
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any, TypedDict, Union, overload
 
 if TYPE_CHECKING:
     import numpy as np
@@ -29,6 +30,41 @@
 TAILING_SEP_RX: re.Pattern[str] = re.compile(f"{re.escape(SEPARATOR)}$")
 
 
+class CharLevelStats(TypedDict):
+    """Character-level confusion matrix statistics for tokenization."""
+
+    tp: int
+    fp: int
+    tn: int
+    fn: int
+
+
+class WordLevelStats(TypedDict):
+    """Word-level tokenization statistics."""
+
+    correctly_tokenised_words: int
+    total_words_in_sample: int
+    total_words_in_ref_sample: int
+
+
+class GlobalStats(TypedDict):
+    """Global tokenization indicators as a binary indicator string."""
+
+    tokenisation_indicators: str
+
+
+# Functional form is required because 'global' is a Python reserved keyword.
+TokenizationStats = TypedDict(
+    "TokenizationStats",
+    {
+        "char_level": CharLevelStats,
+        "word_level": WordLevelStats,
+        "global": GlobalStats,
+    },
+)
+"""Tokenization quality statistics at character, word, and global level."""
+
+
 def _f1(precision: float, recall: float) -> float:
     """Compute f1.
 
@@ -43,8 +79,21 @@ def _f1(precision: float, recall: float) -> float:
     return 2 * precision * recall / (precision + recall)
 
 
+@overload
+def _flatten_result(
+    my_dict: TokenizationStats, sep: str = ...
+) -> dict[str, Union[int, str]]: ...
+
+
+@overload
+def _flatten_result(
+    my_dict: Mapping[str, Mapping[str, Union[int, str]]], sep: str = ...
+) -> dict[str, Union[int, str]]: ...
+
+
 def _flatten_result(
-    my_dict: dict[str, dict[str, Union[int, str]]], sep: str = ":"
+    my_dict: Any,
+    sep: str = ":",
 ) -> dict[str, Union[int, str]]:
     """Flatten two-dimension dictionary.
 
@@ -55,8 +104,9 @@ def _flatten_result(
     { "a:b": 7 }
 
 
-    :param dict[str, dict[str, Union[int, str]]] my_dict: dictionary
-        containing stats
+    :param my_dict: dictionary containing stats
+    :type my_dict: TokenizationStats or
+        collections.abc.Mapping[str, collections.abc.Mapping[str, Union[int, str]]]
     :param str sep: separator between the two keys (default: ":")
 
     :return: a one-dimension dictionary with keys combined
@@ -139,7 +189,7 @@ def preprocessing(txt: str, remove_space: bool = True) -> str:
 
 def compute_stats(
     ref_sample: str, raw_sample: str
-) -> dict[str, dict[str, Union[int, str]]]:
+) -> TokenizationStats:
     """Compute statistics for tokenization quality
 
     These statistics include:
@@ -156,7 +206,7 @@ def compute_stats(
     :param str samples: samples that we want to evaluate
 
     :return: metrics at character- and word-level and indicators of correctly tokenized words
-    :rtype: dict[str, dict[str, Union[int, str]]]
+    :rtype: TokenizationStats
     """
     import numpy as np
 
@@ -194,20 +244,20 @@ def compute_stats(
     tokenization_indicators_str = list(map(str, tokenization_indicators))
 
     return {
-        "char_level": {
-            "tp": c_tp,
-            "fp": c_fp,
-            "tn": c_tn,
-            "fn": c_fn,
-        },
-        "word_level": {
-            "correctly_tokenised_words": correctly_tokenised_words,
-            "total_words_in_sample": int(np.sum(sample_arr)),
-            "total_words_in_ref_sample": int(np.sum(ref_sample_arr)),
-        },
-        "global": {
-            "tokenisation_indicators": "".join(tokenization_indicators_str)
-        },
+        "char_level": CharLevelStats(
+            tp=c_tp,
+            fp=c_fp,
+            tn=c_tn,
+            fn=c_fn,
+        ),
+        "word_level": WordLevelStats(
+            correctly_tokenised_words=correctly_tokenised_words,
+            total_words_in_sample=int(np.sum(sample_arr)),
+            total_words_in_ref_sample=int(np.sum(ref_sample_arr)),
+        ),
+        "global": GlobalStats(
+            tokenisation_indicators="".join(tokenization_indicators_str),
+        ),
     }
 
 

pythainlp/coref/__init__.py

@@ -3,6 +3,7 @@
 # SPDX-License-Identifier: Apache-2.0
 """PyThaiNLP Coreference Resolution"""
 
-__all__: list[str] = ["coreference_resolution"]
+__all__: list[str] = ["CorefResult", "coreference_resolution"]
 
+from pythainlp.coref._fastcoref import CorefResult
 from pythainlp.coref.core import coreference_resolution

pythainlp/coref/_fastcoref.py

@@ -6,12 +6,13 @@
 from typing import TYPE_CHECKING, Optional, TypedDict
 
 if TYPE_CHECKING:
-    from fastcoref.modeling import CorefModel, CorefResult
+    from fastcoref.modeling import CorefModel
+    from fastcoref.modeling import CorefResult as FastCorefResult
     from spacy.language import Language
 
 
-class CorefResultDict(TypedDict):
-    """Dictionary representation of coreference resolution results."""
+class CorefResult(TypedDict):
+    """Coreference resolution result for a single text."""
 
     text: str
     clusters_string: list[list[str]]
@@ -42,14 +43,14 @@ def __init__(
             self.model_name, device=device, nlp=self.nlp
         )
 
-    def _to_json(self, _predict: "CorefResult") -> CorefResultDict:
+    def _to_json(self, _predict: "FastCorefResult") -> CorefResult:
         return {
             "text": _predict.text,
             "clusters_string": _predict.get_clusters(as_strings=True),
             "clusters": _predict.get_clusters(as_strings=False),
         }
 
-    def predict(self, texts: list[str]) -> list[CorefResultDict]:
+    def predict(self, texts: list[str]) -> list[CorefResult]:
         return [
             self._to_json(pred) for pred in self.model.predict(texts=texts)
         ]