Metadata-Version: 2.4
Name: bb-mask
Version: 0.3.0
Summary: Data Mask istemcisi: metin ve dosya anonimleştirme, restore. Model çağrısı yok.
Author: BigBrains
License: MIT
Project-URL: Homepage, https://app.bbmask.co
Project-URL: Documentation, https://app.bbmask.co/#/sdk
Project-URL: Repository, https://github.com/bigbrains-company/bb-mask-sdk
Keywords: anonymization,kvkk,pii,data-mask,bigbrains
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27.0
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Dynamic: license-file

# bb-mask

Türkçe hukuki metindeki kişisel veriyi etiketler, model cevabındaki etiketleri geri açar. Paket ince bir HTTP istemcisidir. Model çağırmaz, metin yazdırmaz, bekletmez.

Müşteri Data Mask konsolundan `dm_test_` anahtarı alır. Kendi backend’i bu paketi kurar ve anahtarı `init`’e verir. LLM satırı müşterinindir; SDK’nın öncesine `anonymize`, sonrasına `restore` konur.

```python
import os
import bb_mask

bb_mask.init(api_key=os.environ["BB_ANONYM_TOKEN"])


def ozetle(metin: str) -> str:
    tagged = bb_mask.anonymize(metin)
    cevap = kendi_llm(tagged.text)                 # bu satır sizde
    return bb_mask.restore(tagged.doc_id, cevap)
```

Python 3.11+. Tek bağımlılık `httpx`. Bu klasör Python paketidir. Node, Go, C# ve Java aynı deponun diğer klasörlerindedir.

## Kurulum

Paket yayınlanınca:

```bash
pip install bb-mask
```

Yayın öncesi, depo kökünden:

```bash
pip install -e python
```

Anahtarı koda veya repoya yazmayın. Ortam değişkeni veya kendi ayar dosyanız yeter.

```bash
export BB_ANONYM_TOKEN="dm_test_..."
```

`init` süreçte bir kez çalışır. Model çağrısı değildir. Modül fonksiyonları (`bb_mask.anonymize` ve diğerleri) bundan önce çağrılırsa `BBError(401)` verir ve servise gitmez.

```python
istemci = bb_mask.init(
    api_key=os.environ["BB_ANONYM_TOKEN"],
    base_url="https://app.bbmask.co",  # varsayılan budur
    timeout=150,                       # saniye
)
```

| Argüman | Tip | Anlam |
|---|---|---|
| `api_key` | `str` | Konsoldaki `dm_test_` anahtarı. Boşsa `BBError(401)`. |
| `base_url` | `str` | Servis adresi. Varsayılan `https://app.bbmask.co`. |
| `timeout` | `float` | HTTP zaman aşımı, saniye. Varsayılan `150`; motor 120 sn bekler, istemci ondan sonra pes eder. |

Dönüş `BBAnonym`'dur. Modül fonksiyonları bu istemciyi kullanır. İkinci `init` öncekinin yerine geçer.

İkinci bir anahtar gerekiyorsa süreç globaline dokunmadan `BBAnonym` kurun. Kurucu `init` istemez.

```python
diger = bb_mask.BBAnonym("https://app.bbmask.co", token, timeout=150)
```

## Nesneler

### `Tagged`

`anonymize`, `anonymize_file` ve `anonymize_documents` bunu döner.

| Alan | Tip | Ne zaman dolu |
|---|---|---|
| `text` | `str` | Her zaman. Kişisel veri yerine etiket vardır: `<PERSON_0>`, `<TR_NATIONAL_ID_0>`. |
| `doc_id` | `str \| None` | `persist=True` (varsayılan). Haritanın servisteki anahtarı. Yalnız aynı çalışma alanının anahtarı açar. |
| `state` | `dict \| None` | `persist=False`. Haritanın kendisi. Servise yazılmaz. |
| `entities_found` | `dict[str, int]` | Her zaman. Tip başına sayı: `{"PERSON": 2}`. Düz isim taşımaz. |
| `balance_credits` | `str \| None` | Çağrıdan sonra kalan bakiye: `"9.00"`. |
| `request_id` | `str \| None` | Yanıtın `X-Request-Id` değeri. Konsoldaki Kullanım satırıyla eşleşir. |
| `placeholder_style` | `str` | Uygulanan etiket biçimi: `"angle"` veya `"bracket_tr"`. |
| `keep_legal_form` | `bool` | Uygulanan değer. |
| `health_data` | `bool` | Uygulanan değer. |
| `llm_review` | `dict \| None` | `llm_review=True` istendiyse durum özeti: `status`, `model`, `chunks`, `chunks_failed`, `elapsed_ms`, `added_spans`, `error`. Düz isim taşımaz. |

```python
tagged = bb_mask.anonymize("Davacı Hasan Demirkol, TC 62601815964")
tagged.doc_id   # "a1b2..."
tagged.text     # "Davacı <PERSON_0>, TC <TR_NATIONAL_ID_0>"
tagged.state    # None
```

Etiket biçimi `<TIP_0>`. Aynı yüzey aynı numarayı alır. Model etiketi bozarsa (`<PERSON 0>`) onarım servistedir. Mahkeme ve kanun adları etiketlenmez.

### Seçenekler

Dört anonymize çağrısı (`anonymize`, `anonymize_file`, `anonymize_bytes`, `anonymize_documents`), async kardeşleri ve `session()` aynı isimli parametreleri alır. Yalnız isimle verilir. Hepsi kapalı başlar; servis kendi varsayılanına düşmez.

| Parametre | Varsayılan | Etki |
|---|---|---|
| `placeholder_style` | `"angle"` | `"angle"` → `<PERSON_0>`. `"bracket_tr"` → `[KİŞİ_1]`, `[ŞİRKET_1]`; 1'den başlar. Başka değer istek gitmeden `BBError(400)`. |
| `keep_legal_form` | `False` | `True` → şirket türü eki etiketin dışında kalır: `[ŞİRKET_1] A.Ş.`, `<ORGANIZATION_0> Ltd. Şti.` |
| `health_data` | `False` | `True` → KVKK m.6 sağlık verisi de etiketlenir: tanı, ilaç, tahlil, kan grubu, hasta no, sağlık kurumu. |
| `llm_review` | `False` | `True` → kuralların kaçırdığı kişi, şirket, adres ve kimlikler bir LLM ile ikinci kez aranır. Model geçici anonim metni görür. Servis katmanı kapalıysa hata değildir; `Tagged.llm_review["status"]` bunu söyler. |

```python
tagged = bb_mask.anonymize(
    "Davalı Kaya İnşaat A.Ş. çalışanı Ali Kaya, tanı: diyabet",
    placeholder_style="bracket_tr",
    keep_legal_form=True,
    health_data=True,
    llm_review=True,
)
tagged.text        # "Davalı [ŞİRKET_1] A.Ş. çalışanı [KİŞİ_1], tanı: [TANI_1]"
tagged.llm_review  # {"status": "ok", "model": "qwen/qwen3.8-27b", "added_spans": 0, ...}
```

`state` ve `get_map` sözlüğü biçimden bağımsız kanonik etiket taşır (`<PERSON_0>`). `restore` iki biçimi de açar.

### `state` / `get_map` sözlüğü

Şekil: `dict[str, dict[str, str]]`. Dış anahtar varlık tipi, iç anahtar düz metin, değer etikettir.

```python
{
    "PERSON": {"Hasan Demirkol": "<PERSON_0>"},
    "TR_NATIONAL_ID": {"62601815964": "<TR_NATIONAL_ID_0>"},
}
```

Sözlük düz isim taşır. Loga, bilete veya modele koymayın. `restore` bu sözlüğü kendisi kullanır; modele yalnız `tagged.text` gider.

### `BBError`

`RuntimeError` alt sınıfı. `status_code: int`, `detail: str`, `request_id: str | None`. `str(hata)` ayrıntı metnidir. `request_id` servisten yanıt geldiyse doludur; destek isterken bu değeri iletin.

Ağ hatası da `BBError` olur; `httpx` istisnası dışarı sızmaz.

| Kod | Anlam |
|---|---|
| 400 | Boş metin, 1–3 dışı dosya sayısı, geçersiz `placeholder_style`, oturumda anonymize yok, `doc_id` ve `state` ikisi de yok. |
| 401 | `init` çağrılmadı, anahtar boş veya tanınmıyor. |
| 402 | Bakiye yok. Anonimleştirme servise gitmez. |
| 404 | Harita yok. Silinmiş, `once=True` ile okunmuş, başka çalışma alanının veya servis tutmuyordur. |
| 413 | Dosya 20 MB üstü. |
| 502 | Motor hata verdi; anonymize ücreti iade edilir. Yanıt JSON değilse de 502 olur. |
| 503 | Servise ulaşılamadı. İstek gitmedi. |
| 504 | `timeout` doldu. İstek servise ulaşmış olabilir; ücret düşmüş olabilir. Konsoldaki Kullanım sayfasına bakın. |

Ücret başarılı anonymize çağrısında düşer. Servis hata verirse ücret geri yazılır. `restore`, `get_map` ve `delete` ücret yazmaz.

### `MaskSession`

`with bb_mask.session()` bunu verir. `doc_id` ve `state` oturumun içindedir.

| Metod | Dönüş |
|---|---|
| `anonymize(text)` | `Tagged` |
| `anonymize_file(path)` | `Tagged`. Yolu okur. |
| `anonymize_documents(paths)` | `Tagged` |
| `restore(model_metni)` | `str` |
| `close()` | `None`. Blok bitince kendiliğinden çağrılır. |
| `persist` | `bool`. Kurgu 1 ise `True`. Oturumda sabittir. |
| `options` | `dict`. `session(...)` içine verilen seçenekler. Her anonymize çağrısına gider. |

`restore` burada yalnız model metnini alır. Anonymize olmadan çağrılırsa `BBError(400)`. Blok bitince `close` çalışır: `persist=True` ise tutulan her `doc_id` silinir, `persist=False` ise state düşer ve servise silme gitmez.

## Çağrılar

Hepsi `init` sonrasında. Dosya uzantısı `.txt`, `.pdf` veya `.docx`. Dosya başına tavan 20 MB.

`anonymize_file(path)` bir yol alır ve dosyayı okur. Bayt sizdeyse `anonymize_bytes(filename, content)` kullanın. İki ad modülde ve `BBAnonym` üzerinde aynı anlama gelir. `MaskSession.anonymize_file(path)` de yolu okur.

### Kurgu 1 — harita serviste, siz `doc_id` tutarsınız

```python
tagged = bb_mask.anonymize(metin)
cevap = kendi_llm(tagged.text)
duz = bb_mask.restore(tagged.doc_id, cevap)
bb_mask.delete(tagged.doc_id)          # iş bitince
```

Tek dosya:

```python
tagged = bb_mask.anonymize_file("dilekce.pdf")
duz = bb_mask.restore(tagged.doc_id, kendi_llm(tagged.text))
```

Birden çok dosya tek `doc_id` paylaşır. Aynı kişi iki dosyada da `<PERSON_0>` olur. Üst sınır 3 dosyadır. Ücret tek anonymize’dir.

```python
tagged = bb_mask.anonymize_documents(
    ["dilekce.pdf", "cevap.docx", "ek.txt"]
)
duz = bb_mask.restore(tagged.doc_id, kendi_llm(tagged.text))
```

`restore` orijinal dosyayı almaz. Modelin yazdığı metindeki etiketleri açar.

### Kurgu 2 — aynı `doc_id`, üstüne sözlük

```python
tagged = bb_mask.anonymize(metin)
sozluk = bb_mask.get_map(tagged.doc_id)
# sozluk["PERSON"]["Hasan Demirkol"] == "<PERSON_0>"

duz = bb_mask.restore(tagged.doc_id, kendi_llm(tagged.text))
```

Okuyunca servisteki kopya da silinsin:

```python
sozluk = bb_mask.get_map(tagged.doc_id, once=True)
# bundan sonra restore ve get_map 404 döner
```

Sözlük gerekmiyorsa Kurgu 1 yeter.

### Kurgu 3 — harita sizde, servis saklamaz

`doc_id` boştur. `state` sözlüktür. Onu modele koymayın. Süreç ölünce de `restore` çalışsın diye `state`’i kendi tarafta saklayabilirsiniz.

```python
tagged = bb_mask.anonymize(metin, persist=False)
assert tagged.doc_id is None and tagged.state is not None

cevap = kendi_llm(tagged.text)
duz = bb_mask.restore(tagged.state, cevap)
```

Dosyada da aynıdır: `anonymize_file(yol, persist=False)`, `anonymize_documents(yollar, persist=False)`.

### Kurgu 4 — siz id veya json görmezsiniz

Kurgu 1. Çıkışta harita silinir.

```python
with bb_mask.session() as s:
    tagged = s.anonymize_documents(["dilekce.pdf", "ek.txt"])
    cevap = kendi_llm(tagged.text)
    duz = s.restore(cevap)
```

Kurgu 3 yüzeyi. State oturum nesnesindedir, servise yazılmaz.

```python
with bb_mask.session(persist=False) as s:
    tagged = s.anonymize(metin)
    duz = s.restore(kendi_llm(tagged.text))
```

### Async

Dört fonksiyon vardır. İmzalar senkron kardeşleriyle aynıdır. HTTP işi bir thread’de yürür. `init` bunlarda da gerekir.

```python
aanonymize(text, persist=True, *, <seçenekler>) -> Tagged
aanonymize_file(path, persist=True, *, <seçenekler>) -> Tagged
aanonymize_documents(paths, persist=True, *, <seçenekler>) -> Tagged
arestore(doc_id_or_state, model_text) -> str
```

```python
tagged = await bb_mask.aanonymize(metin)
duz = await bb_mask.arestore(tagged.doc_id, cevap)
```

`get_map`, `delete`, `session` ve `anonymize_bytes` için async karşılık yoktur.

## Referans

Modül fonksiyonları `init` ister. `BBAnonym` metotları kurucudaki anahtarı kullanır.

### Modül

```python
init(api_key: str, base_url: str = "https://app.bbmask.co", timeout: float = 150) -> BBAnonym
anonymize(text: str, persist: bool = True, *, <seçenekler>) -> Tagged
anonymize_file(path: str | Path, persist: bool = True, *, <seçenekler>) -> Tagged
anonymize_bytes(filename: str, content: bytes, persist: bool = True, *, <seçenekler>) -> Tagged
anonymize_documents(paths: list[str | Path], persist: bool = True, *, <seçenekler>) -> Tagged
restore(doc_id_or_state: str | dict, model_text: str) -> str
get_map(doc_id: str, once: bool = False) -> dict
delete(doc_id: str) -> bool
session(persist: bool = True, *, <seçenekler>)  # with ile MaskSession
aanonymize(text: str, persist: bool = True, *, <seçenekler>) -> Tagged
aanonymize_file(path: str | Path, persist: bool = True, *, <seçenekler>) -> Tagged
aanonymize_documents(paths: list[str | Path], persist: bool = True, *, <seçenekler>) -> Tagged
arestore(doc_id_or_state: str | dict, model_text: str) -> str
```

`<seçenekler>` yalnız isimle verilen dört parametredir; imzada açıkça yazılıdır, editör tamamlar, `help(bb_mask.anonymize)` açıklar:

```python
placeholder_style: Literal["angle", "bracket_tr"] = "angle",
keep_legal_form: bool = False,
health_data: bool = False,
llm_review: bool = False,
```

`persist=True` haritayı serviste tutar, `Tagged.doc_id` dolar. `persist=False` haritayı yazmaz, `Tagged.state` dolar, `doc_id` `None` olur.

`restore` ilk argüman `doc_id` (`str`) veya `state` (`dict`). İkinci argüman modelin yazdığı metindir. Dönüş düz metindir.

`get_map` sözlüğü döner. `once=True` okuyunca servisteki kopyayı siler; bundan sonra `restore` ve `get_map` `404` verir.

`delete` servis `deleted` derse `True` döner.

`session` context manager'dır: `with bb_mask.session() as s`. Çıkışta `s.close()` çalışır.

### `BBAnonym`

`init` gerekmez. Modülle aynı adları taşır. Tek bir `httpx.Client` paylaşır (bağlantı havuzu); `with` ile veya `close()` ile kapatılır. `repr()` anahtarı maskeler.

```python
BBAnonym(base_url: str, token: str, timeout: float = 150)
anonymize(text: str, persist: bool = True, *, <seçenekler>) -> Tagged
anonymize_file(path: str | Path, persist: bool = True, *, <seçenekler>) -> Tagged
anonymize_bytes(filename: str, content: bytes, persist: bool = True, *, <seçenekler>) -> Tagged
anonymize_documents(paths: list[str | Path], persist: bool = True, *, <seçenekler>) -> Tagged
restore(doc_id_or_state: str | dict, model_text: str) -> str
get_map(doc_id: str, once: bool = False) -> dict
delete(doc_id: str) -> bool
close() -> None
```

Paket `py.typed` taşır; tip denetleyiciler imzaları okur.

### `MaskSession`

Kurucu dışarıdan çağrılmaz. `persist` ve seçenekler oturum açılırken verilir, metotlara tekrar geçilmez: `bb_mask.session(placeholder_style="bracket_tr", llm_review=True)`.

```python
anonymize(text: str) -> Tagged
anonymize_file(path: str | Path) -> Tagged
anonymize_documents(paths: list[str | Path]) -> Tagged
restore(model_text: str) -> str
close() -> None
```

## Bu pakette olmayanlar

- Müşterinin LLM çağrısı ve `@ask`.
- FastAPI uygulaması, konsol çıktısı, `sleep`.
- Anahtar üretimi ve bakiye. Onlar panelde.
- Etiket onarımı. Bozuk etiketi servis düzeltir; sözlükteki anahtar düz metindir.
