kocer 0.1.0__tar.gz

kocer-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,19 @@
+# v로 시작하는 태그(v0.1.0 등)를 푸시하면 테스트 후 PyPI에 올린다. 토큰 없이 Trusted Publishing 사용.
+name: publish
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]" build && python -m pytest -q && python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

kocer-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+.pytest_cache/

kocer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Choi Kwan-u
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kocer-0.1.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.5
+Name: kocer
+Version: 0.1.0
+Summary: 한국어 STT를 공정하게 채점하는 CER/WER — 띄어쓰기·숫자·문장부호 차이를 오류로 세지 않음
+Project-URL: Repository, https://github.com/Choi-kwan-u/kocer
+Author: Choi Kwan-u
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asr,cer,evaluation,korean,stt,wer
+Classifier: Natural Language :: Korean
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# kocer
+
+한국어 STT를 공정하게 채점하는 CER — 띄어쓰기·숫자·문장부호·영문 약어 표기 차이를 오류로 세지 않습니다.
+
+*Fair CER/WER for Korean speech recognition. Spacing, punctuation, number notation (3개 ↔ 세 개) and Latin acronyms (AI ↔ 에이아이) are not counted as errors. Pure Python, zero dependencies, `jiwer`-compatible API.*
+
+```
+ref: 사과 세 개 주세요
+hyp: 사과 3개 주세요
+jiwer CER 0.200   nlptutti CER 0.143   kocer CER 0.000
+```
+
+## 설치
+
+```bash
+pip install git+https://github.com/Choi-kwan-u/kocer.git
+```
+
+## 사용
+
+```python
+import kocer
+
+kocer.cer("사과 세 개 주세요", "사과 3개 주세요")   # 0.0
+kocer.cer(refs, hyps)                                # 리스트도 됨 (jiwer와 같은 코퍼스 집계)
+kocer.wer(ref, hyp)
+
+r = kocer.measure("세 시 삼십 분", "3시 30분")
+r.cer         # 0.0  정규화 후
+r.raw_cer     # 0.625  정규화 전 (jiwer와 같은 값). 둘의 차이가 "가짜 오류"의 크기
+r.ops         # {'S': 0, 'D': 0, 'I': 0}
+r.alignment   # [('H', '세', '세'), ...]
+r.chosen_ref  # 숫자 후보 중 실제로 채택된 정답
+r.chosen_hyp  # '세시삼십분'
+```
+
+```bash
+kocer ref.txt hyp.txt          # 줄 단위 쌍, raw CER과 kocer CER을 같이 출력
+kocer ref.txt hyp.txt --diff   # 틀린 글자만 색으로 표시
+```
+
+## 무엇을 무시하고, 무엇을 세는가
+
+정규화는 순서대로 적용되고 각 단계를 끌 수 있습니다.
+
+| 단계 | 기본 | 끄기 | 예 |
+|---|---|---|---|
+| 유니코드 NFC | 켬 | - | 자모 분리 입력 |
+| 문장부호 제거 | 켬 | `punct=False` | `네, 알겠습니다.` = `네 알겠습니다` |
+| 필러 제거 (음, 어, 그) | **끔** | `fillers=True` | 실제 단어 "그"도 지워질 수 있어 기본은 끔 |
+| 영문 약어·단위 | 켬 | `letters=False` | `AI` = `에이아이`, `50%` = `50퍼센트` |
+| 숫자 후보 전개 | 켬 | `numbers=False` | `3개` = `세 개`, `3층` = `삼 층` |
+| 공백 제거 | CER만 | - | WER은 공백 유지 |
+
+`normalize=False`면 jiwer와 같은 순수 CER을 돌려줍니다.
+
+### 숫자: 정답 하나가 아니라 후보 집합
+
+숫자는 조수사에 따라 읽기가 달라서(3개=세 개, 3층=삼 층, 3시 30분=세 시 삼십 분) 규칙 하나로 정답을 만들 수 없습니다. kocer는 숫자마다 `{원문 숫자, 한자어 읽기, 고유어 읽기, 자릿수 읽기}` 후보를 만들고 CER이 최소가 되는 조합을 고릅니다.
+
+- 조수사 사전([counters.py](src/kocer/counters.py))에 있으면 그 읽기만, **없으면 두 읽기 모두 허용**합니다. 틀리게 감점하는 것보다 관대한 쪽이 안전하다는 정책입니다.
+- 반대 방향(ref가 한글 수사, hyp가 숫자)도 처리합니다.
+- 전화번호·연도는 자릿수 읽기(010 = 공일공, 2024 = 이공이사)도 후보에 들어갑니다.
+- 고유어 읽기는 1~99까지. `100개`는 `백 개`만 허용합니다.
+
+### "너무 관대하다"는 비판에 대해
+
+정규화는 실제 오류를 숨길 수 있습니다. 그래서 `raw_cer`를 항상 같이 돌려주고, 모든 단계를 끌 수 있게 했습니다. 두 값을 같이 보고하세요.
+
+## 기존 도구 비교 (2026-10-23 실측)
+
+nlptutti 0.0.0.24, jiwer 4.0.0. [tests/cases.tsv](tests/cases.tsv)의 케이스 일부.
+
+| ref | hyp | jiwer | nlptutti | kocer |
+|---|---|---|---|---|
+| 사과 세 개 주세요 | 사과 3개 주세요 | 0.200 | 0.143 | 0.000 |
+| 삼 층으로 가세요 | 3층으로 가세요 | 0.222 | 0.143 | 0.000 |
+| 세 시 삼십 분 | 3시 30분 | 0.625 | 0.600 | 0.000 |
+| 에이아이 모델 | AI 모델 | 0.571 | 0.667 | 0.000 |
+| 네, 알겠습니다. | 네 알겠습니다 | 0.222 | 0.000 | 0.000 |
+| 오늘날씨가좋다 | 오늘 날씨가 좋다 | 0.286 | 0.000 | 0.000 |
+
+nlptutti는 띄어쓰기·문장부호를 이미 처리하고, CLI·코퍼스 비교 리포트·개체명 평가 등 kocer에 없는 기능이 많습니다. kocer의 차이는 숫자·영문 약어 정규화와 `raw_cer` 대비 표시입니다.
+
+## 한계
+
+- WER은 띄어쓰기 차이를 오류로 셉니다. 한국어 WER의 본질적 한계이고, CER을 권합니다.
+- 조수사 사전은 완전하지 않습니다. 사전에 없는 조수사는 두 읽기를 다 허용합니다. 케이스를 [tests/cases.tsv](tests/cases.tsv)에 추가하는 PR을 환영합니다.
+- 입력은 텍스트 쌍만 받습니다. 음성 파일·모델 실행은 다루지 않습니다.
+
+## 라이선스
+
+MIT

kocer-0.1.0/README.md

@@ -0,0 +1,93 @@
+# kocer
+
+한국어 STT를 공정하게 채점하는 CER — 띄어쓰기·숫자·문장부호·영문 약어 표기 차이를 오류로 세지 않습니다.
+
+*Fair CER/WER for Korean speech recognition. Spacing, punctuation, number notation (3개 ↔ 세 개) and Latin acronyms (AI ↔ 에이아이) are not counted as errors. Pure Python, zero dependencies, `jiwer`-compatible API.*
+
+```
+ref: 사과 세 개 주세요
+hyp: 사과 3개 주세요
+jiwer CER 0.200   nlptutti CER 0.143   kocer CER 0.000
+```
+
+## 설치
+
+```bash
+pip install git+https://github.com/Choi-kwan-u/kocer.git
+```
+
+## 사용
+
+```python
+import kocer
+
+kocer.cer("사과 세 개 주세요", "사과 3개 주세요")   # 0.0
+kocer.cer(refs, hyps)                                # 리스트도 됨 (jiwer와 같은 코퍼스 집계)
+kocer.wer(ref, hyp)
+
+r = kocer.measure("세 시 삼십 분", "3시 30분")
+r.cer         # 0.0  정규화 후
+r.raw_cer     # 0.625  정규화 전 (jiwer와 같은 값). 둘의 차이가 "가짜 오류"의 크기
+r.ops         # {'S': 0, 'D': 0, 'I': 0}
+r.alignment   # [('H', '세', '세'), ...]
+r.chosen_ref  # 숫자 후보 중 실제로 채택된 정답
+r.chosen_hyp  # '세시삼십분'
+```
+
+```bash
+kocer ref.txt hyp.txt          # 줄 단위 쌍, raw CER과 kocer CER을 같이 출력
+kocer ref.txt hyp.txt --diff   # 틀린 글자만 색으로 표시
+```
+
+## 무엇을 무시하고, 무엇을 세는가
+
+정규화는 순서대로 적용되고 각 단계를 끌 수 있습니다.
+
+| 단계 | 기본 | 끄기 | 예 |
+|---|---|---|---|
+| 유니코드 NFC | 켬 | - | 자모 분리 입력 |
+| 문장부호 제거 | 켬 | `punct=False` | `네, 알겠습니다.` = `네 알겠습니다` |
+| 필러 제거 (음, 어, 그) | **끔** | `fillers=True` | 실제 단어 "그"도 지워질 수 있어 기본은 끔 |
+| 영문 약어·단위 | 켬 | `letters=False` | `AI` = `에이아이`, `50%` = `50퍼센트` |
+| 숫자 후보 전개 | 켬 | `numbers=False` | `3개` = `세 개`, `3층` = `삼 층` |
+| 공백 제거 | CER만 | - | WER은 공백 유지 |
+
+`normalize=False`면 jiwer와 같은 순수 CER을 돌려줍니다.
+
+### 숫자: 정답 하나가 아니라 후보 집합
+
+숫자는 조수사에 따라 읽기가 달라서(3개=세 개, 3층=삼 층, 3시 30분=세 시 삼십 분) 규칙 하나로 정답을 만들 수 없습니다. kocer는 숫자마다 `{원문 숫자, 한자어 읽기, 고유어 읽기, 자릿수 읽기}` 후보를 만들고 CER이 최소가 되는 조합을 고릅니다.
+
+- 조수사 사전([counters.py](src/kocer/counters.py))에 있으면 그 읽기만, **없으면 두 읽기 모두 허용**합니다. 틀리게 감점하는 것보다 관대한 쪽이 안전하다는 정책입니다.
+- 반대 방향(ref가 한글 수사, hyp가 숫자)도 처리합니다.
+- 전화번호·연도는 자릿수 읽기(010 = 공일공, 2024 = 이공이사)도 후보에 들어갑니다.
+- 고유어 읽기는 1~99까지. `100개`는 `백 개`만 허용합니다.
+
+### "너무 관대하다"는 비판에 대해
+
+정규화는 실제 오류를 숨길 수 있습니다. 그래서 `raw_cer`를 항상 같이 돌려주고, 모든 단계를 끌 수 있게 했습니다. 두 값을 같이 보고하세요.
+
+## 기존 도구 비교 (2026-10-23 실측)
+
+nlptutti 0.0.0.24, jiwer 4.0.0. [tests/cases.tsv](tests/cases.tsv)의 케이스 일부.
+
+| ref | hyp | jiwer | nlptutti | kocer |
+|---|---|---|---|---|
+| 사과 세 개 주세요 | 사과 3개 주세요 | 0.200 | 0.143 | 0.000 |
+| 삼 층으로 가세요 | 3층으로 가세요 | 0.222 | 0.143 | 0.000 |
+| 세 시 삼십 분 | 3시 30분 | 0.625 | 0.600 | 0.000 |
+| 에이아이 모델 | AI 모델 | 0.571 | 0.667 | 0.000 |
+| 네, 알겠습니다. | 네 알겠습니다 | 0.222 | 0.000 | 0.000 |
+| 오늘날씨가좋다 | 오늘 날씨가 좋다 | 0.286 | 0.000 | 0.000 |
+
+nlptutti는 띄어쓰기·문장부호를 이미 처리하고, CLI·코퍼스 비교 리포트·개체명 평가 등 kocer에 없는 기능이 많습니다. kocer의 차이는 숫자·영문 약어 정규화와 `raw_cer` 대비 표시입니다.
+
+## 한계
+
+- WER은 띄어쓰기 차이를 오류로 셉니다. 한국어 WER의 본질적 한계이고, CER을 권합니다.
+- 조수사 사전은 완전하지 않습니다. 사전에 없는 조수사는 두 읽기를 다 허용합니다. 케이스를 [tests/cases.tsv](tests/cases.tsv)에 추가하는 PR을 환영합니다.
+- 입력은 텍스트 쌍만 받습니다. 음성 파일·모델 실행은 다루지 않습니다.
+
+## 라이선스
+
+MIT

kocer-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kocer"
+version = "0.1.0"
+description = "한국어 STT를 공정하게 채점하는 CER/WER — 띄어쓰기·숫자·문장부호 차이를 오류로 세지 않음"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "Choi Kwan-u" }]
+keywords = ["korean", "stt", "asr", "cer", "wer", "evaluation"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Natural Language :: Korean",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = []
+
+[project.urls]
+Repository = "https://github.com/Choi-kwan-u/kocer"
+
+[project.scripts]
+kocer = "kocer.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kocer"]

kocer-0.1.0/src/kocer/__init__.py

@@ -0,0 +1,80 @@
+"""kocer — 한국어 STT를 공정하게 채점하는 CER/WER.
+띄어쓰기·문장부호·숫자 표기·영문 약어 차이를 오류로 세지 않는다."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List, Sequence, Union
+
+from . import numbers as _numbers
+from .align import Op, align, distance
+from .normalize import normalize as _normalize
+
+__version__ = "0.1.0"
+__all__ = ["cer", "wer", "measure", "Result"]
+
+Text = Union[str, Sequence[str]]
+
+
+@dataclass
+class Result:
+    cer: float            # 정규화 후 오류율 (unit="word"면 WER)
+    raw_cer: float        # 정규화 전 오류율 (jiwer와 같은 값)
+    hits: int
+    substitutions: int
+    deletions: int
+    insertions: int
+    alignment: List[Op] = field(repr=False)
+    chosen_ref: str = ""  # 숫자 후보 중 실제로 채택된 정답
+    chosen_hyp: str = ""
+
+    @property
+    def ops(self):
+        return {"S": self.substitutions, "D": self.deletions, "I": self.insertions}
+
+    @property
+    def errors(self) -> int:
+        return self.substitutions + self.deletions + self.insertions
+
+
+def _units(text: str, unit: str) -> List[str]:
+    return text.split() if unit == "word" else list(text.replace(" ", ""))
+
+
+def measure(reference: str, hypothesis: str, *, unit: str = "char", normalize: bool = True,
+            numbers: bool = True, punct: bool = True, fillers: bool = False, letters: bool = True) -> Result:
+    raw_ref, raw_hyp = (reference.split(), hypothesis.split()) if unit == "word" else (list(reference), list(hypothesis))
+    raw = distance(raw_ref, raw_hyp) / max(len(raw_ref), 1)
+
+    ref, hyp = reference, hypothesis
+    if normalize:
+        ref = _normalize(reference, punct, fillers, letters)
+        hyp = _normalize(hypothesis, punct, fillers, letters)
+        if numbers:
+            # shortcut: hyp 후보를 먼저 ref 원문에 맞춰 고르고, 그다음 ref 후보를 고른 hyp에 맞춤(양쪽 곱집합 아님), 혼합 표기에서 틀리면 곱집합으로 올릴 것
+            hyp = _numbers.best(hyp, lambda c: distance(_units(ref, unit), _units(c, unit)))
+            ref = _numbers.best(ref, lambda c: distance(_units(c, unit), _units(hyp, unit)))
+    r, h = (_units(ref, unit), _units(hyp, unit)) if normalize else (raw_ref, raw_hyp)
+    ops = align(r, h)
+    counts = {k: sum(op == k for op, _, _ in ops) for k in "HSDI"}
+    err = counts["S"] + counts["D"] + counts["I"]
+    return Result(err / max(len(r), 1), raw, counts["H"], counts["S"], counts["D"], counts["I"], ops, ref, hyp)
+
+
+def _rate(reference: Text, hypothesis: Text, unit: str, **opts) -> float:
+    if isinstance(reference, str):
+        reference, hypothesis = [reference], [hypothesis]
+    if len(reference) != len(hypothesis):
+        raise ValueError("reference and hypothesis must have the same length")
+    results = [measure(r, h, unit=unit, **opts) for r, h in zip(reference, hypothesis)]
+    total = sum(x.hits + x.substitutions + x.deletions for x in results)
+    return sum(x.errors for x in results) / max(total, 1)
+
+
+def cer(reference: Text, hypothesis: Text, **opts) -> float:
+    """jiwer.cer 호환. 문자열 하나 또는 리스트."""
+    return _rate(reference, hypothesis, "char", **opts)
+
+
+def wer(reference: Text, hypothesis: Text, **opts) -> float:
+    """jiwer.wer 호환. 띄어쓰기 차이는 오류로 센다 (한국어 WER의 한계)."""
+    return _rate(reference, hypothesis, "word", **opts)

kocer-0.1.0/src/kocer/align.py

@@ -0,0 +1,33 @@
+"""편집거리 + 정렬. 문자 리스트든 단어 리스트든 같은 코드."""
+from typing import List, Sequence, Tuple
+
+Op = Tuple[str, str, str]  # ('H'|'S'|'D'|'I', ref_item, hyp_item)
+
+
+def align(ref: Sequence[str], hyp: Sequence[str]) -> List[Op]:
+    n, m = len(ref), len(hyp)
+    d = [[0] * (m + 1) for _ in range(n + 1)]
+    for i in range(1, n + 1):
+        d[i][0] = i
+    for j in range(1, m + 1):
+        d[0][j] = j
+    for i in range(1, n + 1):
+        for j in range(1, m + 1):
+            d[i][j] = min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + (ref[i - 1] != hyp[j - 1]))
+    ops: List[Op] = []
+    i, j = n, m
+    while i or j:
+        if i and j and d[i][j] == d[i - 1][j - 1] + (ref[i - 1] != hyp[j - 1]):
+            ops.append(("H" if ref[i - 1] == hyp[j - 1] else "S", ref[i - 1], hyp[j - 1]))
+            i, j = i - 1, j - 1
+        elif i and d[i][j] == d[i - 1][j] + 1:
+            ops.append(("D", ref[i - 1], ""))
+            i -= 1
+        else:
+            ops.append(("I", "", hyp[j - 1]))
+            j -= 1
+    return ops[::-1]
+
+
+def distance(ref: Sequence[str], hyp: Sequence[str]) -> int:
+    return sum(op != "H" for op, _, _ in align(ref, hyp))

kocer-0.1.0/src/kocer/cli.py

@@ -0,0 +1,51 @@
+"""kocer ref.txt hyp.txt [--diff]  — 줄 단위 쌍을 채점."""
+import argparse
+import sys
+
+from . import __version__, measure
+
+RED, GREEN, STRIKE, END = "\x1b[31m", "\x1b[32m", "\x1b[9;31m", "\x1b[0m"
+
+
+def render(alignment) -> str:
+    out = []
+    for op, r, h in alignment:
+        if op == "H":
+            out.append(r)
+        elif op == "S":
+            out.append(f"{RED}{h}{END}")
+        elif op == "D":
+            out.append(f"{STRIKE}{r}{END}")
+        else:
+            out.append(f"{GREEN}{h}{END}")
+    return "".join(out)
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(prog="kocer", description=__doc__)
+    p.add_argument("ref")
+    p.add_argument("hyp")
+    p.add_argument("--diff", action="store_true", help="틀린 글자를 색으로 표시 (빨강=치환/삭제, 초록=삽입)")
+    p.add_argument("--no-numbers", action="store_true", help="숫자 정규화 끔")
+    p.add_argument("--version", action="version", version=__version__)
+    a = p.parse_args(argv)
+    refs = open(a.ref, encoding="utf-8").read().splitlines()
+    hyps = open(a.hyp, encoding="utf-8").read().splitlines()
+    if len(refs) != len(hyps):
+        sys.exit(f"줄 수가 다릅니다: ref {len(refs)}, hyp {len(hyps)}")
+    err = raw_err = total = 0
+    for i, (r, h) in enumerate(zip(refs, hyps), 1):
+        m = measure(r, h, numbers=not a.no_numbers)
+        n = m.hits + m.substitutions + m.deletions
+        err += m.errors
+        raw_err += round(m.raw_cer * max(len(r), 1))
+        total += n
+        if a.diff and m.errors:
+            print(f"{i}: {render(m.alignment)}  (cer {m.cer:.3f})")
+    print(f"raw CER   {raw_err / max(sum(map(len, refs)), 1):.4f}")
+    print(f"kocer CER {err / max(total, 1):.4f}   ({len(refs)} lines)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

kocer-0.1.0/src/kocer/counters.py

@@ -0,0 +1,30 @@
+"""조수사 사전. 고유어 읽기(세 개) / 한자어 읽기(삼 층) 중 어느 쪽이 쓰이는지.
+사전에 없는 조수사는 두 읽기를 모두 후보로 넣는다 (틀리게 감점하는 것보다 관대한 쪽이 안전)."""
+
+NATIVE = {
+    "개", "명", "시", "시간", "살", "마리", "번", "번째", "잔", "병", "권", "장", "대", "그루",
+    "송이", "사람", "켤레", "벌", "채", "척", "통", "자루", "줄", "곳", "군데", "가지", "달",
+    "끼", "판", "조각", "알", "포기", "다발", "봉지", "상자", "컵", "접시", "쌍", "팀", "배",
+    "편", "곡", "줄기", "개월",  # 개월은 "삼 개월"이 표준이지만 "세 개월"도 흔히 쓰임 → 아래 SINO에도 넣어 둘 다 허용
+}
+SINO = {
+    "층", "원", "년", "월", "일", "호", "초", "세", "도", "퍼센트", "미터", "킬로미터", "킬로그램",
+    "그램", "리터", "번지", "학년", "반", "쪽", "페이지", "교시", "차", "회", "주", "개월", "세기",
+    "등", "위", "점", "인분", "인", "호선", "분기", "단계", "차선", "번길", "동", "급", "차례",
+}
+# 둘 다에 있으면 lookup은 None(둘 다 허용)으로 처리된다
+_BOTH = NATIVE & SINO
+MAX_LEN = max(map(len, NATIVE | SINO))
+
+
+def lookup(following: str):
+    """숫자 뒤에 오는 글자들에서 가장 긴 조수사를 찾아 'native' | 'sino' | None 반환."""
+    for n in range(min(MAX_LEN, len(following)), 0, -1):
+        word = following[:n]
+        if word in _BOTH:
+            return None
+        if word in NATIVE:
+            return "native"
+        if word in SINO:
+            return "sino"
+    return None

kocer-0.1.0/src/kocer/normalize.py

@@ -0,0 +1,48 @@
+"""단계별 정규화. 각 단계는 독립 함수, normalize()가 순서대로 적용."""
+import re
+import unicodedata
+
+# 숫자 사이의 . 과 , (3.5 / 1,000)는 남긴다
+_PUNCT = re.compile(r"(?<!\d)[.,]|[.,](?!\d)|[?!~…·'\"‘’“”()\[\]{}<>:;/\\_\-—–、。，！？「」『』【】]")
+_THOUSANDS = re.compile(r"(?<=\d),(?=\d)")
+_FILLER = re.compile(r"(?<!\S)(?:음+|어+|아+|에+|그+)(?!\S)")
+_LETTERS = dict(zip(
+    "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
+    "에이 비 시 디 이 에프 지 에이치 아이 제이 케이 엘 엠 엔 오 피 큐 알 에스 티 유 브이 더블유 엑스 와이 지".split(),
+))
+_UNITS = {"%": "퍼센트", "km": "킬로미터", "kg": "킬로그램", "cm": "센티미터", "mm": "밀리미터", "ml": "밀리리터"}
+_UNIT_RE = re.compile(r"(?<=\d)\s*(" + "|".join(map(re.escape, sorted(_UNITS, key=len, reverse=True))) + r")(?![A-Za-z])")
+_CAPS = re.compile(r"[A-Z]+")
+
+
+def nfc(text: str) -> str:
+    return unicodedata.normalize("NFC", text)
+
+
+def strip_punct(text: str) -> str:
+    return _PUNCT.sub(" ", _THOUSANDS.sub("", text))
+
+
+def strip_fillers(text: str) -> str:
+    return _FILLER.sub(" ", text)
+
+
+def spell_letters(text: str) -> str:
+    """AI → 에이아이, 50% → 50퍼센트. 대문자 연속과 단위 기호만 바꾼다."""
+    text = _UNIT_RE.sub(lambda m: _UNITS[m.group(1)], text)
+    return _CAPS.sub(lambda m: "".join(_LETTERS[c] for c in m.group()), text)
+
+
+def squeeze(text: str) -> str:
+    return " ".join(text.split())
+
+
+def normalize(text: str, punct: bool = True, fillers: bool = False, letters: bool = True) -> str:
+    text = nfc(text)
+    if punct:
+        text = strip_punct(text)
+    if fillers:
+        text = strip_fillers(text)
+    if letters:
+        text = spell_letters(text)
+    return squeeze(text)

kocer-0.1.0/src/kocer/numbers.py

@@ -0,0 +1,103 @@
+"""숫자 읽기와 후보 전개."""
+from __future__ import annotations
+
+import re
+from itertools import product
+from typing import Callable, List, Sequence, Tuple
+
+from .counters import lookup
+
+NUMBER = re.compile(r"\d+(?:\.\d+)?")  # 천 단위 콤마는 normalize 단계에서 이미 제거됨
+
+_DIGIT = "영일이삼사오육칠팔구"
+_SMALL = ["", "십", "백", "천"]
+_BIG = ["", "만", "억", "조", "경"]
+_NATIVE_TENS = ["", "열", "스물", "서른", "마흔", "쉰", "예순", "일흔", "여든", "아흔"]
+_NATIVE_ONES = ["", "한", "두", "세", "네", "다섯", "여섯", "일곱", "여덟", "아홉"]
+
+
+def digitwise(s: str) -> str:
+    """010 → 공일공, 1234 → 일이삼사 (전화번호·코드)."""
+    return "".join("공" if c == "0" else _DIGIT[int(c)] for c in s if c.isdigit())
+
+
+def _sino_small(n: int) -> str:
+    out = []
+    for pos in (3, 2, 1, 0):
+        d = n // 10**pos % 10
+        if d == 0:
+            continue
+        out.append(("" if d == 1 and pos else _DIGIT[d]) + _SMALL[pos])
+    return "".join(out)
+
+
+def sino(s: str) -> str:
+    """한자어 읽기. 2024 → 이천이십사, 15000 → 만오천, 3.5 → 삼점오."""
+    if "." in s:
+        whole, frac = s.split(".", 1)
+        return sino(whole) + "점" + digitwise(frac)
+    if s.startswith("0") and len(s) > 1:
+        return digitwise(s)
+    n = int(s)
+    if n == 0:
+        return "영"
+    parts = []
+    i = 0
+    while n:
+        g, n = n % 10000, n // 10000
+        if g:
+            parts.append(("" if g == 1 and i == 1 else _sino_small(g)) + _BIG[i])
+        i += 1
+    return "".join(reversed(parts))
+
+
+def native(s: str):
+    """고유어 관형형 읽기 (3 → 세, 20 → 스무, 21 → 스물한). 1~99만 지원, 그 외 None."""
+    if not s.isdigit() or not 1 <= int(s) <= 99:
+        return None
+    n = int(s)
+    if n == 20:
+        return "스무"
+    return _NATIVE_TENS[n // 10] + _NATIVE_ONES[n % 10]
+
+
+def options(num: str, following: str) -> List[str]:
+    """숫자 하나의 읽기 후보. 원문 숫자는 항상 포함."""
+    kind = lookup(following.lstrip())
+    opts = [num]
+    nat = native(num) if kind != "sino" else None
+    if nat:
+        opts.append(nat)
+    if kind != "native" or not nat:  # 고유어 읽기가 없는 수(100개 → 백 개)는 한자어로
+        opts.append(sino(num))
+    if len(num) >= 2 and num.isdigit() and not num.startswith("0"):
+        opts.append(digitwise(num))  # 2024 → 이공이사, 전화번호 등
+    return list(dict.fromkeys(opts))
+
+
+def _spans(text: str) -> List[Tuple[int, int, List[str]]]:
+    return [(m.start(), m.end(), options(m.group(), text[m.end():m.end() + 6])) for m in NUMBER.finditer(text)]
+
+
+def _build(text: str, spans, choice: Sequence[str]) -> str:
+    for (start, end, _), rep in sorted(zip(spans, choice), reverse=True):
+        text = text[:start] + rep + text[end:]
+    return text
+
+
+def best(text: str, score: Callable[[str], float], limit: int = 1024) -> str:
+    """text의 숫자들을 읽기 후보로 바꿔 본 문자열 중 score가 최소인 것."""
+    spans = _spans(text)
+    if not spans:
+        return text
+    total = 1
+    for _, _, o in spans:
+        total *= len(o)
+    if total <= limit:
+        return min((_build(text, spans, c) for c in product(*(o for _, _, o in spans))), key=score)
+    # shortcut: 후보 조합이 limit 초과면 구간별로 따로 고름(다른 구간은 원문 숫자 유지), 인접 구간 간섭으로 틀리면 묶음 전개로 올릴 것
+    base = [o[0] for _, _, o in spans]
+    choice = []
+    for i, (_, _, o) in enumerate(spans):
+        choice.append(min(o, key=lambda opt: score(_build(text, spans, base[:i] + [opt] + base[i + 1:]))))
+    return _build(text, spans, choice)

kocer-0.1.0/tests/cases.tsv

@@ -0,0 +1,103 @@
+ref	hyp	cer
+네, 알겠습니다.	네 알겠습니다	0
+안녕하세요!	안녕하세요	0
+뭐라고요?	뭐라고요	0
+음... 그래요	음 그래요	0
+"안녕"이라고 말했다	안녕이라고 말했다	0
+(웃음) 좋네요	웃음 좋네요	0
+서울·부산	서울 부산	0
+그래~ 알았어	그래 알았어	0
+첫째, 둘째, 셋째	첫째 둘째 셋째	0
+안녕하세요. 반갑습니다.	안녕하세요 반갑습니다	0
+좋아요… 그럼요	좋아요 그럼요	0
+‘따옴표’ 테스트	따옴표 테스트	0
+[자막] 시작합니다	자막 시작합니다	0
+가-나-다	가나다	0
+오늘날씨가좋다	오늘 날씨가 좋다	0
+아버지가 방에 들어가신다	아버지가방에들어가신다	0
+잘  지내세요	잘 지내세요	0
+한국어 음성 인식	한국어음성인식	0
+안녕 하세요	안녕하세요	0
+이것은 테스트 입니다	이것은 테스트입니다	0
+에이아이 모델	AI 모델	0
+케이티엑스 타고 갔어	KTX 타고 갔어	0
+유에스비 꽂아	USB 꽂아	0
+에스케이티 요금제	SKT 요금제	0
+티브이 켜줘	TV 켜줘	0
+지피에스 켜	GPS 켜	0
+AI 모델	에이아이 모델	0
+사과 세 개 주세요	사과 3개 주세요	0
+사과 한 개	사과 1개	0
+두 명이요	2명이요	0
+네 마리	4마리	0
+다섯 번째	5번째	0
+열 개	10개	0
+열한 명	11명	0
+스무 살	20살	0
+스물한 살	21살	0
+서른 명	30명	0
+세 시간 걸려	3시간 걸려	0
+커피 두 잔	커피 2잔	0
+책 세 권	책 3권	0
+두 배	2배	0
+세 달 동안	3달 동안	0
+아흔아홉 개	99개	0
+삼 층으로 가세요	3층으로 가세요	0
+삼층으로 가세요	3층으로 가세요	0
+이천이십사 년	2024년	0
+십이 월 이십오 일	12월 25일	0
+오천 원	5000원	0
+오천 원	5,000원	0
+백만 원	1,000,000원	0
+만 원	10000원	0
+만 오천 원	15000원	0
+삼십 분	30분	0
+사십오 초	45초	0
+이십 세	20세	0
+삼 학년	3학년	0
+오십 퍼센트	50%	0
+삼 킬로미터	3km	0
+백 점	100점	0
+백 개	100개	0
+이백삼십 쪽	230쪽	0
+이 호선	2호선	0
+삼천 원	3천 원	0
+십억	10억	0
+세 시 삼십 분	3시 30분	0
+열두 시 오 분	12시 5분	0
+세 시 삼십 분	3시 삼십 분	0
+삼 월 삼 일	3월 3일	0
+이천이십오 년 삼 월	2025년 3월	0
+사과 두 개 천 원	사과 2개 1000원	0
+삼 층 세 개	3층 3개	0
+열 시 십 분 전	10시 10분 전	0
+두 명이 삼 층에	2명이 3층에	0
+오 분 뒤에 세 명	5분 뒤에 3명	0
+삼 점 오	3.5	0
+영 점 오 퍼센트	0.5%	0
+공일공	010	0
+공일공 일이삼사 오육칠팔	010-1234-5678	0
+이공이사 년	2024년	0
+영 도	0도	0
+천 원	1,000원	0
+3개	세 개	0
+3층	삼 층	0
+3시 30분	세 시 삼십 분	0
+2024년	이천이십사 년	0
+3개	3개	0
+사과 3개	사과 세개	0
+사과	사가	0.5
+삼 층으로 가세요	세 층으로 가세요	0.142857
+3층	세층	0.5
+3개	삼개	0.5
+안녕하세요	안녕하세요 반갑습니다	1.0
+안녕하세요 반갑습니다	안녕하세요	0.5
+세 개	네 개	0.5
+열 명	여덟 명	1.0
+30분	3분	0.333333
+네, 알겟습니다.	네 알겠습니다요	0.333333
+AI 모델	에이 모델	0.333333
+세 시 삼십 분	3시 13분	0.4
+사과 세 개 주세요	사과 3개 주세	0.142857
+오늘 날씨가 좋다	오늘 날씨가 춥다	0.142857
+안녕		1.0

kocer-0.1.0/tests/test_cases.py

@@ -0,0 +1,58 @@
+import csv
+import pathlib
+import unicodedata
+
+import pytest
+
+import kocer
+from kocer import numbers
+
+ROWS = list(csv.DictReader(open(pathlib.Path(__file__).with_name("cases.tsv"), encoding="utf-8"), delimiter="\t"))
+
+
+@pytest.mark.parametrize("row", ROWS, ids=[f"{r['ref']}|{r['hyp']}" for r in ROWS])
+def test_golden(row):
+    assert kocer.cer(row["ref"], row["hyp"]) == pytest.approx(float(row["cer"]), abs=1e-4)
+
+
+def test_raw_cer_is_reported_alongside():
+    r = kocer.measure("네, 알겠습니다.", "네 알겠습니다")
+    assert r.cer == 0 and r.raw_cer > 0
+    assert kocer.cer("네, 알겠습니다.", "네 알겠습니다", normalize=False) == pytest.approx(r.raw_cer)
+
+
+def test_numbers_can_be_turned_off():
+    assert kocer.cer("세 개", "3개", numbers=False) > 0
+
+
+def test_nfd_input():
+    assert kocer.cer(unicodedata.normalize("NFD", "한글 테스트"), "한글 테스트") == 0
+
+
+def test_list_input_matches_jiwer_style_corpus_rate():
+    refs, hyps = ["가나", "다라마"], ["가나", "다라바"]
+    assert kocer.cer(refs, hyps) == pytest.approx(1 / 5)
+
+
+def test_wer_basic():
+    assert kocer.wer("오늘 날씨 좋다", "오늘 날씨 좋다") == 0
+    assert kocer.wer("오늘 날씨 좋다", "오늘 날씨 춥다") == pytest.approx(1 / 3)
+
+
+@pytest.mark.parametrize("n,expect", [("0", "영"), ("7", "칠"), ("10", "십"), ("11", "십일"), ("100", "백"),
+                                      ("2024", "이천이십사"), ("10000", "만"), ("15000", "만오천"),
+                                      ("100000000", "일억"), ("1000000", "백만"), ("3.5", "삼점오"), ("010", "공일공")])
+def test_sino(n, expect):
+    assert numbers.sino(n) == expect
+
+
+@pytest.mark.parametrize("n,expect", [("1", "한"), ("3", "세"), ("10", "열"), ("11", "열한"), ("20", "스무"),
+                                      ("21", "스물한"), ("99", "아흔아홉"), ("100", None), ("0", None)])
+def test_native(n, expect):
+    assert numbers.native(n) == expect
+
+
+def test_many_numbers_fall_back_to_greedy_without_blowing_up():
+    ref = " ".join(f"{i}개" for i in range(1, 13))
+    hyp = " ".join(["한 개", "두 개", "세 개", "네 개", "다섯 개", "여섯 개", "일곱 개", "여덟 개", "아홉 개", "열 개", "열한 개", "열두 개"])
+    assert kocer.cer(ref, hyp) == 0