docs/spec.md

# 実装仕様

> v0.1 の履歴仕様です。表層読み、Mozc辞書候補、未使用PUD外部評価を採用した現行仕様は
> [`spec-v02.md`](spec-v02.md) を参照してください。

## ゴール

既存 IME が生成した有限個のかな漢字候補を
`ku-nlp/deberta-v2-tiny-japanese` の文脈スコアで再順位付けし、頻度順だけの
ベースラインより変換精度を大きく改善する。実装、CLI、再現可能評価、テスト、
Windows 向け実行手順を同じリポジトリで提供する。

## 公開境界

1. Python API: 前文脈・後文脈・読み・候補列を受け取り、根拠付き順位を返す。
2. CLI: 1 件の JSON または JSON Lines を受け取り、機械可読 JSON を返す。
3. 評価: 固定リビジョンの UD Japanese-GSD から train の読み別候補表を作り、
   dev で設定を選び、test で頻度ベースラインと再順位付けを比較する。

## 必須要件

- Masked LM を文章生成器として使わず、入力された有限候補だけを順位付けする。
- 候補が空、長すぎる、未知トークンを含む、スコア差が小さい、モデルを
  読み込めない場合は、既存順位を維持する fail-open/fail-safe 動作にする。
- モデルと評価コーパスの revision、依存関係、乱数 seed、設定を記録する。
- 頻度ベースライン、モデル単体、調整済み混合スコアを分離して報告する。
- dev で選んだ設定を test に固定し、test を調整に使わない。
- ローカル PASS を Windows TSF 統合、実機、公開、本番の PASS と呼ばない。

## 非ゴール

- OS の TSF サービスとしてのインストール。
- DeBERTa に候補生成や自由文生成をさせること。
- 外部 API、クラウド、モデル再学習、公開リポジトリへの push。
- 小規模な手作り例だけを根拠に「大幅改善」と主張すること。

## 成功条件

- test の oracle-in-pool 対象で、調整済み reranker の top-1 accuracy が頻度
  ベースラインを統計的に明確に上回る。
- 改善幅、対象件数、95% 信頼区間、悪化件数、棄却/維持件数、レイテンシを
  `outputs/` の再生成可能なレポートへ保存する。
- 全テスト、静的検査、CLI スモーク、オフライン再実行が成功する。

## 達成結果（2026-08-10）

- `ku-nlp/deberta-v2-tiny-japanese` の target-only pseudo-log-likelihood、
  upstream prior 混合、positive confidence margin、fail-safe fallback を実装した。
- dev 5,824件だけで `prior_weight=2.0`、`min_margin=0.1` を選択した。
- プロトタイプで参照した test 120件を除く sealed remainder 6,263件で、頻度順
  75.89% から 88.74% へ +12.85ポイント改善した。paired bootstrap 95%区間は
  +11.83〜+13.91ポイント、改善969件、悪化164件だった。
- model-only は 80.62% であり、prior と confidence gate の寄与を混同していない。
- tokenizer `[UNK]` を含む31行は除外せず、既存順位維持として分母に含めた。
- CPU p50 20.25 ms、p95 49.08 ms、model load 0.82秒だった。
- 証拠は `outputs/benchmark_full.json` と `outputs/benchmark_full.md` に保存した。

達成したのは条件付き `LOCAL_BENCHMARK` である。候補 recall、raw romaji、
Windows TSF、既存商用IMEの cost、実機入力、公開/本番/Human GO は未検証のまま。