Metadata-Version: 2.4
Name: privyscope-ko
Version: 0.1.2
Summary: privyscope-ko — Korean language pack for the privyscope PII engine
Author: privyscope Core Team
License: Apache-2.0
Project-URL: Homepage, https://github.com/zafrem/privyscope-ko
Project-URL: Documentation, https://github.com/zafrem/privyscope-ko/blob/main/README.md
Keywords: pii,ner,redaction,privacy,korean,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.0
Provides-Extra: train
Requires-Dist: privyscope[train]>=0.1.0; extra == "train"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Dynamic: license-file

# privyscope-ko

한국어 텍스트에서 **개인정보(PII)를 찾는** 엔진이에요.
[privyscope](https://github.com/zafrem) 시리즈의 한국어 버전으로, 사람 이름,
전화번호, 주민등록번호, 이메일, 주소, 금융 정보, 비공개 날짜, 인증 정보(시크릿)를
알아서 찾아 마스킹해 줍니다.

> ⚠️ privyscope는 마스킹을 **도와주는** 도구일 뿐, 비식별화나 컴플라이언스를
> 보장하지는 않아요. 자세한 내용은 [한계](#한계)를 꼭 읽어보세요.

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

## 설치

```bash
pip install privyscope-ko
```

## 1분 만에 시작하기

**Python에서 쓰기**

```python
from privyscope_ko import Privyscope

engine = Privyscope.from_pretrained()                 # 처음 실행할 때 ONNX 가중치를 내려받아요
result = engine.redact("홍길동의 전화번호는 010-1234-5678")

result.masked_text        # "<PER>의 전화번호는 <PHONE>"
result.detected_spans     # [DetectedSpan(label="PER", start=0, end=3, ...), ...]
result.summary            # {"span_count": 2, "by_label": {"PER": 1, "PHONE": 1}, ...}
```

**터미널에서 쓰기**

```bash
privyscope redact "홍길동의 전화번호는 010-1234-5678"
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) |

## 어떤 걸 찾아주나요

찾아주는 항목은 이렇게 여덟 가지예요:
`PER` · `PHONE` · `ID_NUM` · `EMAIL` · `LOC` · `BANK` · `DATE` · `SECRET`.

정규식 규칙은 [`privyscope/regex_rules.yaml`](privyscope/regex_rules.yaml)에 들어
있고, 코드를 건드리지 않고도 직접 추가하거나 고칠 수 있어요. 한국어에만 있는
확장 항목은 [`privyscope/entity_config.yaml`](privyscope/entity_config.yaml)에
정의돼 있습니다.

## 어떻게 동작하나요

크게 **두 단계**로 나눠서 PII를 찾고, 두 결과를 합쳐서(합집합) 돌려줘요
(SRS §3.4):

1. **정규식 필터** — 전화번호, 이메일, 주민번호, 카드번호, 시크릿처럼 형태가
   딱 정해져 있는 PII를 잡아냅니다.
2. **ONNX NER** — 이름, 주소, 비공개 날짜처럼 앞뒤 문맥을 봐야 알 수 있는
   PII를 잡아내요. BIOES 토큰 분류기에 제약 Viterbi 디코더를 붙여서 판단합니다.

추론할 때는 **ONNX Runtime만 쓰고 PyTorch는 필요 없어요**. 기본적으로 빠뜨리지
않는 걸(재현율) 우선하고, 재학습 없이 [운영 포인트](docs/OPERATING_POINTS.md)만
바꿔서 동작을 조절할 수 있습니다. PyTorch는 [파인튜닝](docs/FINETUNING.md)을 할
때만 있으면 돼요.

## 모델과 성능

- **구조** — `klue/roberta-base` 인코더 → BIOES 토큰 분류 헤드 → Viterbi
  디코더로 이어지는 형태예요.
- **실제 배포 파일** — INT8로 양자화한 ONNX 모델이고 크기는 **약 105 MB**라
  150 MB 안에 넉넉히 들어와요. 최대 문장 길이는 256입니다. 가중치는 처음
  쓸 때 Hugging Face Hub에서 내려받고, 파일이 멀쩡한지 확인할 수 있게 SHA-256
  `checksum.txt`가 함께 들어 있어요.
- **정확도** — 학습과 겹치지 않는 검증 세트(2,000문장, `typed`/strict 채점,
  regex + NER 전체 파이프라인)에서 엔티티 단위 **strict 마이크로 F1 = 0.966**을
  기록했어요. 엔티티별 strict F1:

  | PER | LOC | DATE | EMAIL | ID_NUM | BANK | PHONE |
  |-----|-----|------|-------|--------|------|-------|
  | 0.98 | 1.00 | 1.00 | 1.00 | 1.00 | 0.92 | 0.78 |

  `PHONE`는 정밀도가 0.64로 전화번호처럼 보이는 숫자를 과검출하는 경향이 있고,
  `BANK`는 재현율이 0.85라 일부를 놓쳐요. 검증 세트가 학습과 분리돼 있어 이
  점수는 암기가 아니라 일반화 성능을 보여주지만, 분포 밖 문장에서는 더 낮게
  나올 수 있어요. `privyscope eval --lang ko your_val.jsonl`로 직접 재현할 수
  있고, 자세한 내용은 [평가 및 출력 모드](docs/EVAL_AND_OUTPUT_MODES.md)를
  참고하세요.

## 한계

쓰기 전에 이 점들은 꼭 알아두세요:

- 비식별화나 컴플라이언스를 보장하지는 않아요. 프라이버시 설계의 **여러 안전장치
  중 하나**로 생각하고 쓰는 게 맞습니다.
- 잘 못 잡는 경우도 있어요. 예를 들어 드물거나 지역색이 강한 이름은 놓칠 수
  있고, 문맥이 애매하면 공인(공개 인물)까지 과하게 가릴 수 있어요. 형식이 복잡하게
  섞인 텍스트에서는 한 덩어리가 여러 조각으로 쪼개지기도 하고, 처음 보는 형식의
  `SECRET`은 못 잡을 수 있습니다.
- 의료·법률·금융·정부 업무처럼 민감한 곳에서는 사람이 한 번 더 검토하는 걸
  권장해요.

## 라이선스

Apache-2.0으로 배포돼요. 모델 가중치도 같은 Apache-2.0이고, 파일 무결성을 확인할
수 있는 `checksum.txt`(SHA-256)와 함께 Hugging Face Hub에 올라가 있습니다. 기여는
언제든 환영이에요 — [CONTRIBUTING.md](CONTRIBUTING.md)를 참고해 주세요.
