tr-pii-guard 0.1.0__tar.gz

tr_pii_guard-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 suleymanssardogan
+
+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.

tr_pii_guard-0.1.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: tr-pii-guard
+Version: 0.1.0
+Summary: Turkish PII detection and redaction for LLM pipelines
+License-Expression: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: ner
+Requires-Dist: transformers>=4.30; extra == "ner"
+Requires-Dist: torch>=2.0; extra == "ner"
+Dynamic: license-file
+
+# tr-pii-guard
+
+Türkçe metinlerdeki kişisel verileri (TC kimlik no, IBAN, telefon, e-posta, isim, adres) LLM API çağrısından önce tespit edip maskeleyen açık kaynak Python kütüphanesi.
+
+KVKK/GDPR uyumu için, kullanıcı verisini OpenAI/Claude/Gemini gibi servislere göndermeden önce bir güvenlik katmanı sağlar.
+
+## Durum
+
+Erken geliştirme aşamasında.
+
+## Kurulum
+
+```bash
+pip install -e .
+```
+
+## Kullanım
+
+```python
+from tr_pii_guard import redact, restore
+
+masked_text, mapping = redact("TC no 10000000146, telefon 0532 123 45 67.")
+# masked_text -> "TC no [TC_NO_1], telefon [TELEFON_1]."
+
+original = restore(masked_text, mapping)
+```
+
+Şu an tespit edilen türler: TC kimlik no, IBAN, telefon, e-posta (hepsi checksum/format
+doğrulamalı).
+
+### İsim/adres tespiti (opsiyonel, NER)
+
+```bash
+pip install tr-pii-guard[ner]
+```
+
+```python
+masked_text, mapping = redact("Ahmet Yılmaz İstanbul'a gitti.", use_ner=True)
+```
+
+`use_ner` varsayılan olarak kapalı — temel paket `transformers`/`torch` indirmeden çalışır.
+Ekstra kurulu değilken `use_ner=True` çağrılırsa açık bir hata mesajıyla uyarır.
+
+### Komut satırı
+
+```bash
+tr-pii-guard scan dosya.txt
+```
+
+### Özel detector ekleme
+
+```python
+import re
+from tr_pii_guard import register_detector
+
+register_detector("CALISAN_ID", lambda text: list(re.finditer(r"EMP-\d{5}", text)))
+```
+
+## Lisans
+
+MIT

tr_pii_guard-0.1.0/README.md

@@ -0,0 +1,61 @@
+# tr-pii-guard
+
+Türkçe metinlerdeki kişisel verileri (TC kimlik no, IBAN, telefon, e-posta, isim, adres) LLM API çağrısından önce tespit edip maskeleyen açık kaynak Python kütüphanesi.
+
+KVKK/GDPR uyumu için, kullanıcı verisini OpenAI/Claude/Gemini gibi servislere göndermeden önce bir güvenlik katmanı sağlar.
+
+## Durum
+
+Erken geliştirme aşamasında.
+
+## Kurulum
+
+```bash
+pip install -e .
+```
+
+## Kullanım
+
+```python
+from tr_pii_guard import redact, restore
+
+masked_text, mapping = redact("TC no 10000000146, telefon 0532 123 45 67.")
+# masked_text -> "TC no [TC_NO_1], telefon [TELEFON_1]."
+
+original = restore(masked_text, mapping)
+```
+
+Şu an tespit edilen türler: TC kimlik no, IBAN, telefon, e-posta (hepsi checksum/format
+doğrulamalı).
+
+### İsim/adres tespiti (opsiyonel, NER)
+
+```bash
+pip install tr-pii-guard[ner]
+```
+
+```python
+masked_text, mapping = redact("Ahmet Yılmaz İstanbul'a gitti.", use_ner=True)
+```
+
+`use_ner` varsayılan olarak kapalı — temel paket `transformers`/`torch` indirmeden çalışır.
+Ekstra kurulu değilken `use_ner=True` çağrılırsa açık bir hata mesajıyla uyarır.
+
+### Komut satırı
+
+```bash
+tr-pii-guard scan dosya.txt
+```
+
+### Özel detector ekleme
+
+```python
+import re
+from tr_pii_guard import register_detector
+
+register_detector("CALISAN_ID", lambda text: list(re.finditer(r"EMP-\d{5}", text)))
+```
+
+## Lisans
+
+MIT

tr_pii_guard-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "tr-pii-guard"
+version = "0.1.0"
+description = "Turkish PII detection and redaction for LLM pipelines"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+
+[project.optional-dependencies]
+ner = ["transformers>=4.30", "torch>=2.0"]
+
+[project.scripts]
+tr-pii-guard = "tr_pii_guard.cli:main"
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]

tr_pii_guard-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tr_pii_guard-0.1.0/src/tr_pii_guard/__init__.py

@@ -0,0 +1,6 @@
+"""Turkish PII detection and redaction for LLM pipelines."""
+
+from .redactor import redact, register_detector, restore
+
+__version__ = "0.1.0"
+__all__ = ["redact", "restore", "register_detector"]

tr_pii_guard-0.1.0/src/tr_pii_guard/cli.py

@@ -0,0 +1,32 @@
+"""Command-line interface: tr-pii-guard scan <file>"""
+
+import argparse
+import sys
+
+from .redactor import redact
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(prog="tr-pii-guard")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    scan = subparsers.add_parser("scan", help="Print a file's content with PII masked")
+    scan.add_argument("path", help="Path to a text file")
+    scan.add_argument(
+        "--use-ner",
+        action="store_true",
+        help="Also mask names/locations (requires: pip install tr-pii-guard[ner])",
+    )
+
+    args = parser.parse_args(argv)
+
+    with open(args.path, encoding="utf-8") as f:
+        text = f.read()
+
+    masked, _ = redact(text, use_ner=args.use_ner)
+    print(masked)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tr_pii_guard-0.1.0/src/tr_pii_guard/detectors.py

@@ -0,0 +1,56 @@
+"""Regex-based detectors for Turkish PII: TC kimlik no, phone numbers, IBAN."""
+
+import re
+
+TC_NO_PATTERN = re.compile(r"(?<!\d)\d{11}(?!\d)")
+
+# shortcut: fixed area-code range [2-5]xx, no real operator/area-code table;
+# widen if a valid number gets missed in practice.
+PHONE_PATTERN = re.compile(
+    r"(?<!\d)(?:\+90[ .-]?|0090[ .-]?)?0?[ .-]?\(?[2-5]\d{2}\)?"
+    r"[ .-]?\d{3}[ .-]?\d{2}[ .-]?\d{2}(?!\d)"
+)
+
+IBAN_PATTERN = re.compile(r"TR\d{2}(?:[ ]?\d{4}){5}[ ]?\d{2}\b", re.IGNORECASE)
+
+EMAIL_PATTERN = re.compile(r"[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}")
+
+
+def _is_valid_tc_no(digits: str) -> bool:
+    if len(digits) != 11 or not digits.isdigit() or digits[0] == "0":
+        return False
+    d = [int(c) for c in digits]
+    odd_sum = d[0] + d[2] + d[4] + d[6] + d[8]
+    even_sum = d[1] + d[3] + d[5] + d[7]
+    d10 = (odd_sum * 7 - even_sum) % 10
+    d11 = (odd_sum + even_sum + d10) % 10
+    return d10 == d[9] and d11 == d[10]
+
+
+def _is_valid_iban(iban: str) -> bool:
+    iban = iban.replace(" ", "").upper()
+    if not re.fullmatch(r"TR\d{24}", iban):
+        return False
+    rearranged = iban[4:] + iban[:4]
+    numeric = "".join(str(int(ch, 36)) for ch in rearranged)
+    return int(numeric) % 97 == 1
+
+
+def find_tc_no(text: str) -> list[re.Match]:
+    """Find valid (checksum-passing) TC kimlik no occurrences in text."""
+    return [m for m in TC_NO_PATTERN.finditer(text) if _is_valid_tc_no(m.group())]
+
+
+def find_phone(text: str) -> list[re.Match]:
+    """Find Turkish phone number occurrences in text."""
+    return list(PHONE_PATTERN.finditer(text))
+
+
+def find_iban(text: str) -> list[re.Match]:
+    """Find valid (checksum-passing) Turkish IBAN occurrences in text."""
+    return [m for m in IBAN_PATTERN.finditer(text) if _is_valid_iban(m.group())]
+
+
+def find_email(text: str) -> list[re.Match]:
+    """Find email address occurrences in text."""
+    return list(EMAIL_PATTERN.finditer(text))

tr_pii_guard-0.1.0/src/tr_pii_guard/ner.py

@@ -0,0 +1,54 @@
+"""Optional Turkish NER-based name/location detection (PERSON/LOC).
+
+Needs the `ner` extra: pip install tr-pii-guard[ner]
+The model is loaded lazily on first use so importing this package never
+forces the transformers/torch download.
+"""
+
+_MODEL_NAME = "savasy/bert-base-turkish-ner-cased"
+_WANTED_LABELS = {"PER", "LOC"}
+
+_pipeline = None
+
+
+class _Span:
+    """Minimal re.Match-like wrapper so NER results fit the same
+    (start(), end(), group()) interface the regex detectors use."""
+
+    def __init__(self, start: int, end: int, value: str):
+        self._start = start
+        self._end = end
+        self._value = value
+
+    def start(self) -> int:
+        return self._start
+
+    def end(self) -> int:
+        return self._end
+
+    def group(self) -> str:
+        return self._value
+
+
+def _get_pipeline():
+    global _pipeline
+    if _pipeline is None:
+        try:
+            from transformers import pipeline
+        except ImportError as exc:
+            raise ImportError(
+                "İsim/adres tespiti için ek bağımlılıklar gerekli: "
+                "pip install tr-pii-guard[ner]"
+            ) from exc
+        _pipeline = pipeline("ner", model=_MODEL_NAME, aggregation_strategy="simple")
+    return _pipeline
+
+
+def find_names(text: str) -> list[_Span]:
+    """Find person/location entities in `text` using a Turkish NER model."""
+    ner = _get_pipeline()
+    return [
+        _Span(r["start"], r["end"], text[r["start"] : r["end"]])
+        for r in ner(text)
+        if r["entity_group"] in _WANTED_LABELS
+    ]

tr_pii_guard-0.1.0/src/tr_pii_guard/redactor.py

@@ -0,0 +1,82 @@
+"""Combine all PII detectors into a single mask/unmask API."""
+
+from collections import defaultdict
+from typing import Callable
+
+from .detectors import find_email, find_iban, find_phone, find_tc_no
+
+_BASE_DETECTORS = (
+    ("TC_NO", find_tc_no),
+    ("IBAN", find_iban),
+    ("TELEFON", find_phone),
+    ("EPOSTA", find_email),
+)
+
+_extra_detectors: list[tuple[str, Callable]] = []
+
+
+def register_detector(label: str, finder) -> None:
+    """Register a custom detector used by every later `redact()` call.
+
+    `finder(text)` must return matches exposing `.start()`, `.end()`, `.group()`
+    (anything `re.finditer` returns satisfies this).
+    """
+    _extra_detectors.append((label, finder))
+
+
+def _collect_matches(text: str, detectors) -> list[tuple[int, int, str, str]]:
+    candidates = [
+        (m.start(), m.end(), label, m.group())
+        for label, finder in detectors
+        for m in finder(text)
+    ]
+    # Longer matches win when two detectors claim overlapping spans.
+    candidates.sort(key=lambda c: (-(c[1] - c[0]), c[0]))
+
+    selected: list[tuple[int, int, str, str]] = []
+    occupied: list[tuple[int, int]] = []
+    for start, end, label, value in candidates:
+        if any(start < o_end and end > o_start for o_start, o_end in occupied):
+            continue
+        selected.append((start, end, label, value))
+        occupied.append((start, end))
+
+    selected.sort(key=lambda c: c[0])
+    return selected
+
+
+def redact(text: str, use_ner: bool = False) -> tuple[str, dict[str, str]]:
+    """Mask Turkish PII in `text`. Returns (masked_text, mapping) where
+    mapping maps each placeholder back to the original value.
+
+    use_ner=True also masks person/location names via an optional Turkish
+    NER model (pip install tr-pii-guard[ner]); off by default so the base
+    package stays dependency-light.
+    """
+    detectors = _BASE_DETECTORS + tuple(_extra_detectors)
+    if use_ner:
+        from .ner import find_names
+
+        detectors = detectors + (("ISIM", find_names),)
+
+    mapping: dict[str, str] = {}
+    counters: dict[str, int] = defaultdict(int)
+    pieces = []
+    cursor = 0
+    for start, end, label, value in _collect_matches(text, detectors):
+        counters[label] += 1
+        placeholder = f"[{label}_{counters[label]}]"
+        mapping[placeholder] = value
+        pieces.append(text[cursor:start])
+        pieces.append(placeholder)
+        cursor = end
+    pieces.append(text[cursor:])
+    return "".join(pieces), mapping
+
+
+def restore(masked_text: str, mapping: dict[str, str]) -> str:
+    """Reverse `redact`: replace placeholders with their original values."""
+    result = masked_text
+    for placeholder, original in mapping.items():
+        result = result.replace(placeholder, original)
+    return result

tr_pii_guard-0.1.0/src/tr_pii_guard.egg-info/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: tr-pii-guard
+Version: 0.1.0
+Summary: Turkish PII detection and redaction for LLM pipelines
+License-Expression: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: ner
+Requires-Dist: transformers>=4.30; extra == "ner"
+Requires-Dist: torch>=2.0; extra == "ner"
+Dynamic: license-file
+
+# tr-pii-guard
+
+Türkçe metinlerdeki kişisel verileri (TC kimlik no, IBAN, telefon, e-posta, isim, adres) LLM API çağrısından önce tespit edip maskeleyen açık kaynak Python kütüphanesi.
+
+KVKK/GDPR uyumu için, kullanıcı verisini OpenAI/Claude/Gemini gibi servislere göndermeden önce bir güvenlik katmanı sağlar.
+
+## Durum
+
+Erken geliştirme aşamasında.
+
+## Kurulum
+
+```bash
+pip install -e .
+```
+
+## Kullanım
+
+```python
+from tr_pii_guard import redact, restore
+
+masked_text, mapping = redact("TC no 10000000146, telefon 0532 123 45 67.")
+# masked_text -> "TC no [TC_NO_1], telefon [TELEFON_1]."
+
+original = restore(masked_text, mapping)
+```
+
+Şu an tespit edilen türler: TC kimlik no, IBAN, telefon, e-posta (hepsi checksum/format
+doğrulamalı).
+
+### İsim/adres tespiti (opsiyonel, NER)
+
+```bash
+pip install tr-pii-guard[ner]
+```
+
+```python
+masked_text, mapping = redact("Ahmet Yılmaz İstanbul'a gitti.", use_ner=True)
+```
+
+`use_ner` varsayılan olarak kapalı — temel paket `transformers`/`torch` indirmeden çalışır.
+Ekstra kurulu değilken `use_ner=True` çağrılırsa açık bir hata mesajıyla uyarır.
+
+### Komut satırı
+
+```bash
+tr-pii-guard scan dosya.txt
+```
+
+### Özel detector ekleme
+
+```python
+import re
+from tr_pii_guard import register_detector
+
+register_detector("CALISAN_ID", lambda text: list(re.finditer(r"EMP-\d{5}", text)))
+```
+
+## Lisans
+
+MIT

tr_pii_guard-0.1.0/src/tr_pii_guard.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+LICENSE
+README.md
+pyproject.toml
+src/tr_pii_guard/__init__.py
+src/tr_pii_guard/cli.py
+src/tr_pii_guard/detectors.py
+src/tr_pii_guard/ner.py
+src/tr_pii_guard/redactor.py
+src/tr_pii_guard.egg-info/PKG-INFO
+src/tr_pii_guard.egg-info/SOURCES.txt
+src/tr_pii_guard.egg-info/dependency_links.txt
+src/tr_pii_guard.egg-info/entry_points.txt
+src/tr_pii_guard.egg-info/requires.txt
+src/tr_pii_guard.egg-info/top_level.txt
+tests/test_basic.py
+tests/test_cli.py
+tests/test_detectors.py
+tests/test_ner.py
+tests/test_plugin.py
+tests/test_redactor.py

tr_pii_guard-0.1.0/src/tr_pii_guard.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

tr_pii_guard-0.1.0/src/tr_pii_guard.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tr-pii-guard = tr_pii_guard.cli:main

tr_pii_guard-0.1.0/src/tr_pii_guard.egg-info/requires.txt

@@ -0,0 +1,4 @@
+
+[ner]
+transformers>=4.30
+torch>=2.0

tr_pii_guard-0.1.0/src/tr_pii_guard.egg-info/top_level.txt

@@ -0,0 +1 @@
+tr_pii_guard

tr_pii_guard-0.1.0/tests/test_basic.py

@@ -0,0 +1,5 @@
+import tr_pii_guard
+
+
+def test_package_importable():
+    assert tr_pii_guard.__version__

tr_pii_guard-0.1.0/tests/test_cli.py

@@ -0,0 +1,15 @@
+from tr_pii_guard.cli import main
+
+VALID_TC_NO = "10000000146"
+
+
+def test_cli_scan_masks_file(tmp_path, capsys):
+    f = tmp_path / "input.txt"
+    f.write_text(f"TC no {VALID_TC_NO}.", encoding="utf-8")
+
+    exit_code = main(["scan", str(f)])
+    out = capsys.readouterr().out
+
+    assert exit_code == 0
+    assert VALID_TC_NO not in out
+    assert "[TC_NO_1]" in out

tr_pii_guard-0.1.0/tests/test_detectors.py

@@ -0,0 +1,37 @@
+from tr_pii_guard.detectors import find_iban, find_phone, find_tc_no
+
+VALID_TC_NO = "10000000146"  # well-known checksum-valid test number, not a real person
+VALID_IBAN = "TR33 0006 1005 1978 6457 8413 26"
+
+
+def test_find_tc_no_valid():
+    text = f"Müşteri TC no: {VALID_TC_NO}."
+    matches = find_tc_no(text)
+    assert [m.group() for m in matches] == [VALID_TC_NO]
+
+
+def test_find_tc_no_rejects_bad_checksum():
+    text = "Rastgele sayı 12345678901 burada."
+    assert find_tc_no(text) == []
+
+
+def test_find_phone_variants():
+    samples = [
+        "0532 123 45 67",
+        "+90 532 123 45 67",
+        "05321234567",
+        "0212 123 45 67",
+    ]
+    for s in samples:
+        assert find_phone(s), f"should match: {s}"
+
+
+def test_find_iban_valid():
+    text = f"IBAN: {VALID_IBAN}"
+    matches = find_iban(text)
+    assert len(matches) == 1
+
+
+def test_find_iban_rejects_bad_checksum():
+    text = "IBAN: TR33 0006 1005 1978 6457 8413 27"  # last digit tampered
+    assert find_iban(text) == []

tr_pii_guard-0.1.0/tests/test_ner.py

@@ -0,0 +1,24 @@
+import pytest
+
+
+def test_redact_use_ner_without_extra_raises_helpful_error():
+    try:
+        import transformers  # noqa: F401
+    except ImportError:
+        pass
+    else:
+        pytest.skip("transformers is installed; nothing to assert here")
+
+    from tr_pii_guard import redact
+
+    with pytest.raises(ImportError, match="tr-pii-guard\\[ner\\]"):
+        redact("Ahmet Yılmaz İstanbul'a gitti.", use_ner=True)
+
+
+def test_find_names_detects_person():
+    pytest.importorskip("transformers")
+
+    from tr_pii_guard.ner import find_names
+
+    results = find_names("Ahmet Yılmaz İstanbul'a gitti.")
+    assert any(r.group() for r in results)

tr_pii_guard-0.1.0/tests/test_plugin.py

@@ -0,0 +1,18 @@
+import re
+
+from tr_pii_guard import redact
+from tr_pii_guard.redactor import _extra_detectors, register_detector
+
+
+def test_register_custom_detector():
+    def find_secret(text):
+        return list(re.finditer(r"GIZLI-\d+", text))
+
+    register_detector("OZEL", find_secret)
+    try:
+        masked, mapping = redact("Kod: GIZLI-42 burada.")
+        assert "GIZLI-42" not in masked
+        assert "[OZEL_1]" in masked
+        assert mapping["[OZEL_1]"] == "GIZLI-42"
+    finally:
+        _extra_detectors.clear()

tr_pii_guard-0.1.0/tests/test_redactor.py

@@ -0,0 +1,37 @@
+from tr_pii_guard import redact, restore
+
+VALID_TC_NO = "10000000146"  # checksum-valid test number, not a real person
+VALID_IBAN = "TR33 0006 1005 1978 6457 8413 26"
+
+
+def test_redact_masks_every_type():
+    text = (
+        f"TC no {VALID_TC_NO}, telefon 0532 123 45 67, "
+        f"IBAN {VALID_IBAN}, e-posta test@example.com."
+    )
+    masked, _ = redact(text)
+
+    assert VALID_TC_NO not in masked
+    assert "0532 123 45 67" not in masked
+    assert VALID_IBAN not in masked
+    assert "test@example.com" not in masked
+
+
+def test_redact_restore_roundtrip():
+    text = f"Kart sahibi, IBAN {VALID_IBAN}, TC no {VALID_TC_NO}."
+    masked, mapping = redact(text)
+    assert restore(masked, mapping) == text
+
+
+def test_redact_numbers_repeated_type():
+    text = "Birinci telefon 0532 123 45 67, ikinci telefon 0212 123 45 67."
+    masked, mapping = redact(text)
+    assert "[TELEFON_1]" in masked and "[TELEFON_2]" in masked
+    assert restore(masked, mapping) == text
+
+
+def test_redact_leaves_clean_text_untouched():
+    text = "Bugün hava çok güzel."
+    masked, mapping = redact(text)
+    assert masked == text
+    assert mapping == {}