Metadata-Version: 2.4
Name: privyscope-ja
Version: 0.1.5
Summary: privyscope-ja — Japanese language pack for the privyscope PII engine
Author: privyscope Core Team
License: Apache-2.0
Project-URL: Homepage, https://github.com/zafrem/privyscope-ja
Project-URL: Documentation, https://github.com/zafrem/privyscope-ja/blob/main/README.md
Keywords: pii,ner,redaction,privacy,japanese,onnx
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: privyscope>=0.1.5
Provides-Extra: train
Requires-Dist: privyscope[train]>=0.1.0; extra == "train"
Requires-Dist: fugashi>=1.3; extra == "train"
Requires-Dist: unidic-lite>=1.0.8; extra == "train"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Dynamic: license-file

# privyscope-ja

日本語テキストから**個人情報（PII）を検出・マスキング**するエンジンです。
[privyscope](https://github.com/zafrem) シリーズの日本語版で、氏名・電話番号・
各種ID・メールアドレス・住所・金融情報・非公開の日付・認証情報（シークレット）を
自動で見つけてマスキングします。

> ⚠️ privyscope はマスキングを**補助する**ツールであり、匿名化やコンプライアンスを
> 保証するものではありません。詳しくは[制限事項](#制限事項)をご覧ください。

📖 **[English README](README.en.md)**

## インストール

```bash
pip install privyscope-ja      # `privyscope` 本体も自動で入ります
```

## 1分で始める

**Python から使う**

```python
from privyscope_ja import Privyscope

engine = Privyscope.from_pretrained()                 # 初回実行時に ONNX 重みをダウンロード
result = engine.redact("田中さんの電話は090-1234-5678、メールは taro@example.co.jp")

result.masked_text        # "<PER>さんの電話は<PHONE>、メールは <EMAIL>"
result.detected_spans     # [DetectedSpan(label="PER", start=0, end=2, ...), ...]
result.summary            # {"span_count": 3, "by_label": {"PER": 1, "PHONE": 1, "EMAIL": 1}, ...}
```

**ターミナルから使う**

```bash
privyscope redact "田中さんの電話は090-1234-5678、メールは taro@example.co.jp"
cat notes.txt | privyscope redact --operating-point high_recall
```

## ドキュメント

詳しいガイドは [`docs/`](docs/) に目的別でまとめてあります。

| やりたいこと | ガイド |
|---|---|
| ターミナルで動かす | [CLI リファレンス](docs/CLI.md) |
| Python から呼び出す | [Python API リファレンス](docs/API.md) |
| JSON 出力の意味を知る | [出力スキーマ](docs/OUTPUT_SCHEMAS.md) |
| 自分のラベル付きデータで採点する | [評価と出力モード](docs/EVAL_AND_OUTPUT_MODES.md) |
| 適合率と再現率を調整する | [オペレーティングポイント](docs/OPERATING_POINTS.md) |
| オフライン / 閉域網で使う | [オフライン利用](docs/OFFLINE.md) |
| 自分のデータでファインチューニングする | [ファインチューニング](docs/FINETUNING.md) |

## 検出できる項目

基本項目（正規表現 + NER）は8種類です：
`PER` · `PHONE` · `ID_NUM` · `EMAIL` · `LOC` · `BANK` · `DATE` · `SECRET`。

正規表現のみで検出する拡張項目もあります：
`MYNUMBER` · `PASSPORT` · `DRIVER_LICENSE` · `CRYPTO` · `IP` · `DEVICE` · `URL`
— [`privyscope_ja/entity_config.yaml`](privyscope_ja/entity_config.yaml) を参照。

Stage-1 の正規表現ルールは
[pii-pattern-engine](https://github.com/zafrem/pii-pattern-engine) のルールセットから
取り込んでいます。多くのルールには**検証関数**（チェックサム・辞書チェック）が
付いており、形が似ているだけの値はマスキングしません。

日本語は漢字・ひらがな・カタカナの3種類の文字が混在し、単語間に空白がないため、
氏名の検出は正規表現ではなく NER 段に任せています。形態素解析には
`fugashi` + `unidic-lite`（MeCab）を使用します。

> `privyscope_ja/regex_rules.yaml` は `scripts/gen_regex_rules.py` が**自動生成**する
> ファイルで、ビルドのたびに上書きされます。ルールを変えるときは YAML ではなく
> そのスクリプトを編集してください。詳しくは [CONTRIBUTING](CONTRIBUTING.md) を参照。

## 仕組み

**2段ハイブリッドパイプライン**で PII を検出し、両者の結果を和集合で統合します
（SRS §3.4）：

1. **正規表現フィルタ** — 電話番号・メール・各種ID・カード番号・シークレットなど、
   形が決まっている PII を捕捉します。
2. **ONNX NER** — 氏名・住所・非公開の日付など、前後の文脈から判断する PII を
   捕捉します。BIOES トークン分類器に制約付き Viterbi デコーダを組み合わせています。

推論時は **ONNX Runtime のみで動作し、PyTorch は不要**です。既定では取りこぼしを
避ける（再現率重視）方針で、再学習なしに
[オペレーティングポイント](docs/OPERATING_POINTS.md)だけで挙動を調整できます。
PyTorch が要るのは[ファインチューニング](docs/FINETUNING.md)のときだけです。

## モデルと性能

- **構成** — `tohoku-nlp/bert-base-japanese-v3`（Apache-2.0）エンコーダ →
  BIOES トークン分類ヘッド → 制約付き Viterbi デコーダ。
- **配布物** — INT8 量子化した ONNX モデルで、サイズは**約 107 MB**（≤150 MB の
  予算内）、最大系列長 256。重みは初回利用時に Hugging Face Hub からダウンロードされ、
  整合性確認用の SHA-256 `checksum.txt` が付属します。
- **精度** — 学習と重複しない検証セット（1,000文、`typed`/strict 採点、
  regex + NER 全体パイプライン）でのエンティティ単位の strict F1：

  | PER | LOC | DATE | ID_NUM | BANK | PHONE | SECRET |
  |-----|-----|------|--------|------|-------|--------|
  | 0.99 | 1.00 | 1.00 | 0.56 | 0.71 | 0.90 | 0.84 |

  micro-F1 は **0.921**。氏名・住所・日付といった文脈依存の項目はほぼ完璧です。
  一方 `ID_NUM`（マイナンバー等）と `BANK` は数字項目で、口語・空白なし・タイポを
  含む**厳しめのストレステスト**を strict（オフセット完全一致）で採点するため低めに
  出ます —— これは**保守的な下限値**で、実際のきれいなテキストではより高くなります。
  `EMAIL` は正規表現で確定的に検出され、このサンプルには含まれていませんでした。
  学習と分離した検証セットなので、この数値は暗記ではなく汎化性能を表します。
  `privyscope eval --lang ja your_val.jsonl` で再現できます。

## 実例：ネットショップの問い合わせ

顧客がショッピングモールに送った実際の問い合わせ（約300文字、氏名・日付・メール・
電話番号・住所・カード番号を含む）を `engine.redact()` に通した結果です。

**入力**

```text
お世話になっております。田中太郎と申します。2024年3月14日に注文したランニングシューズがまだ届いておらず、ご連絡いたしました。会員登録の際に使用したメールアドレスは taro.tanaka92@gmail.com で、日中に連絡が取れる携帯電話番号は 090-2345-6789 です。お届け先の住所は東京都渋谷区神南1-2-3 で、お支払いはクレジットカード 4539-1488-0343-6467 で完了しております。もし商品が紛失している場合は、お支払いした金額をカードへ返金していただけますでしょうか。現在の配送状況をご確認のうえ、早めのご返信をお願いいたします。どうぞよろしくお願いいたします。
```

**マスキング結果（`result.masked_text`）**

```text
お世話になっております。<PER>と申します。<DATE>に注文したランニングシューズがまだ届いておらず、ご連絡いたしました。会員登録の際に使用したメールアドレスは <EMAIL> で、日中に連絡が取れる携帯電話番号は <PHONE> です。お届け先の住所は<LOC> で、お支払いはクレジットカード <BANK> で完了しております。もし商品が紛失している場合は、お支払いした金額をカードへ返金していただけますでしょうか。現在の配送状況をご確認のうえ、早めのご返信をお願いいたします。どうぞよろしくお願いいたします。
```

**検出された6件**

| ラベル | 検出されたテキスト |
|---|---|
| `PER` | 田中太郎 |
| `DATE` | 2024年3月14日 |
| `EMAIL` | taro.tanaka92@gmail.com |
| `PHONE` | 090-2345-6789 |
| `LOC` | 東京都渋谷区神南1-2-3 |
| `BANK` | 4539-1488-0343-6467 |

## 制限事項

- 匿名化やコンプライアンスを保証するものではありません。プライバシー設計の
  **多層防御のひとつ**として使ってください。
- 苦手なケースもあります。珍しい氏名や地域色の強い名前は取りこぼすことがあり、
  文脈が曖昧だと公人まで過剰にマスキングすることがあります。形式が複雑に混在した
  テキストではスパンが分割されたり、初見の形式の `SECRET` を見逃したりします。
- 医療・法務・金融・行政など機微な業務では、人によるダブルチェックを推奨します。

## ライセンス

Apache-2.0 で配布しています。モデルの重みも同じ Apache-2.0 で、整合性を確認できる
`checksum.txt`（SHA-256）とともに Hugging Face Hub に公開されています。コントリ
ビューションは歓迎です — [CONTRIBUTING.md](CONTRIBUTING.md) を参照してください。
