bb-mask 0.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
bb_mask-0.3.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 BigBrains
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
bb_mask-0.3.0/PKG-INFO ADDED
@@ -0,0 +1,373 @@
1
+ Metadata-Version: 2.4
2
+ Name: bb-mask
3
+ Version: 0.3.0
4
+ Summary: Data Mask istemcisi: metin ve dosya anonimleştirme, restore. Model çağrısı yok.
5
+ Author: BigBrains
6
+ License: MIT
7
+ Project-URL: Homepage, https://app.bbmask.co
8
+ Project-URL: Documentation, https://app.bbmask.co/#/sdk
9
+ Project-URL: Repository, https://github.com/bigbrains-company/bb-mask-sdk
10
+ Keywords: anonymization,kvkk,pii,data-mask,bigbrains
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: License :: OSI Approved :: MIT License
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Topic :: Security
19
+ Classifier: Typing :: Typed
20
+ Requires-Python: >=3.11
21
+ Description-Content-Type: text/markdown
22
+ License-File: LICENSE
23
+ Requires-Dist: httpx>=0.27.0
24
+ Provides-Extra: test
25
+ Requires-Dist: pytest>=8; extra == "test"
26
+ Dynamic: license-file
27
+
28
+ # bb-mask
29
+
30
+ 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.
31
+
32
+ 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.
33
+
34
+ ```python
35
+ import os
36
+ import bb_mask
37
+
38
+ bb_mask.init(api_key=os.environ["BB_ANONYM_TOKEN"])
39
+
40
+
41
+ def ozetle(metin: str) -> str:
42
+ tagged = bb_mask.anonymize(metin)
43
+ cevap = kendi_llm(tagged.text) # bu satır sizde
44
+ return bb_mask.restore(tagged.doc_id, cevap)
45
+ ```
46
+
47
+ 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.
48
+
49
+ ## Kurulum
50
+
51
+ Paket yayınlanınca:
52
+
53
+ ```bash
54
+ pip install bb-mask
55
+ ```
56
+
57
+ Yayın öncesi, depo kökünden:
58
+
59
+ ```bash
60
+ pip install -e python
61
+ ```
62
+
63
+ Anahtarı koda veya repoya yazmayın. Ortam değişkeni veya kendi ayar dosyanız yeter.
64
+
65
+ ```bash
66
+ export BB_ANONYM_TOKEN="dm_test_..."
67
+ ```
68
+
69
+ `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.
70
+
71
+ ```python
72
+ istemci = bb_mask.init(
73
+ api_key=os.environ["BB_ANONYM_TOKEN"],
74
+ base_url="https://app.bbmask.co", # varsayılan budur
75
+ timeout=150, # saniye
76
+ )
77
+ ```
78
+
79
+ | Argüman | Tip | Anlam |
80
+ |---|---|---|
81
+ | `api_key` | `str` | Konsoldaki `dm_test_` anahtarı. Boşsa `BBError(401)`. |
82
+ | `base_url` | `str` | Servis adresi. Varsayılan `https://app.bbmask.co`. |
83
+ | `timeout` | `float` | HTTP zaman aşımı, saniye. Varsayılan `150`; motor 120 sn bekler, istemci ondan sonra pes eder. |
84
+
85
+ Dönüş `BBAnonym`'dur. Modül fonksiyonları bu istemciyi kullanır. İkinci `init` öncekinin yerine geçer.
86
+
87
+ İkinci bir anahtar gerekiyorsa süreç globaline dokunmadan `BBAnonym` kurun. Kurucu `init` istemez.
88
+
89
+ ```python
90
+ diger = bb_mask.BBAnonym("https://app.bbmask.co", token, timeout=150)
91
+ ```
92
+
93
+ ## Nesneler
94
+
95
+ ### `Tagged`
96
+
97
+ `anonymize`, `anonymize_file` ve `anonymize_documents` bunu döner.
98
+
99
+ | Alan | Tip | Ne zaman dolu |
100
+ |---|---|---|
101
+ | `text` | `str` | Her zaman. Kişisel veri yerine etiket vardır: `<PERSON_0>`, `<TR_NATIONAL_ID_0>`. |
102
+ | `doc_id` | `str \| None` | `persist=True` (varsayılan). Haritanın servisteki anahtarı. Yalnız aynı çalışma alanının anahtarı açar. |
103
+ | `state` | `dict \| None` | `persist=False`. Haritanın kendisi. Servise yazılmaz. |
104
+ | `entities_found` | `dict[str, int]` | Her zaman. Tip başına sayı: `{"PERSON": 2}`. Düz isim taşımaz. |
105
+ | `balance_credits` | `str \| None` | Çağrıdan sonra kalan bakiye: `"9.00"`. |
106
+ | `request_id` | `str \| None` | Yanıtın `X-Request-Id` değeri. Konsoldaki Kullanım satırıyla eşleşir. |
107
+ | `placeholder_style` | `str` | Uygulanan etiket biçimi: `"angle"` veya `"bracket_tr"`. |
108
+ | `keep_legal_form` | `bool` | Uygulanan değer. |
109
+ | `health_data` | `bool` | Uygulanan değer. |
110
+ | `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. |
111
+
112
+ ```python
113
+ tagged = bb_mask.anonymize("Davacı Hasan Demirkol, TC 62601815964")
114
+ tagged.doc_id # "a1b2..."
115
+ tagged.text # "Davacı <PERSON_0>, TC <TR_NATIONAL_ID_0>"
116
+ tagged.state # None
117
+ ```
118
+
119
+ 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.
120
+
121
+ ### Seçenekler
122
+
123
+ 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.
124
+
125
+ | Parametre | Varsayılan | Etki |
126
+ |---|---|---|
127
+ | `placeholder_style` | `"angle"` | `"angle"` → `<PERSON_0>`. `"bracket_tr"` → `[KİŞİ_1]`, `[ŞİRKET_1]`; 1'den başlar. Başka değer istek gitmeden `BBError(400)`. |
128
+ | `keep_legal_form` | `False` | `True` → şirket türü eki etiketin dışında kalır: `[ŞİRKET_1] A.Ş.`, `<ORGANIZATION_0> Ltd. Şti.` |
129
+ | `health_data` | `False` | `True` → KVKK m.6 sağlık verisi de etiketlenir: tanı, ilaç, tahlil, kan grubu, hasta no, sağlık kurumu. |
130
+ | `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. |
131
+
132
+ ```python
133
+ tagged = bb_mask.anonymize(
134
+ "Davalı Kaya İnşaat A.Ş. çalışanı Ali Kaya, tanı: diyabet",
135
+ placeholder_style="bracket_tr",
136
+ keep_legal_form=True,
137
+ health_data=True,
138
+ llm_review=True,
139
+ )
140
+ tagged.text # "Davalı [ŞİRKET_1] A.Ş. çalışanı [KİŞİ_1], tanı: [TANI_1]"
141
+ tagged.llm_review # {"status": "ok", "model": "qwen/qwen3.8-27b", "added_spans": 0, ...}
142
+ ```
143
+
144
+ `state` ve `get_map` sözlüğü biçimden bağımsız kanonik etiket taşır (`<PERSON_0>`). `restore` iki biçimi de açar.
145
+
146
+ ### `state` / `get_map` sözlüğü
147
+
148
+ Şekil: `dict[str, dict[str, str]]`. Dış anahtar varlık tipi, iç anahtar düz metin, değer etikettir.
149
+
150
+ ```python
151
+ {
152
+ "PERSON": {"Hasan Demirkol": "<PERSON_0>"},
153
+ "TR_NATIONAL_ID": {"62601815964": "<TR_NATIONAL_ID_0>"},
154
+ }
155
+ ```
156
+
157
+ 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.
158
+
159
+ ### `BBError`
160
+
161
+ `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.
162
+
163
+ Ağ hatası da `BBError` olur; `httpx` istisnası dışarı sızmaz.
164
+
165
+ | Kod | Anlam |
166
+ |---|---|
167
+ | 400 | Boş metin, 1–3 dışı dosya sayısı, geçersiz `placeholder_style`, oturumda anonymize yok, `doc_id` ve `state` ikisi de yok. |
168
+ | 401 | `init` çağrılmadı, anahtar boş veya tanınmıyor. |
169
+ | 402 | Bakiye yok. Anonimleştirme servise gitmez. |
170
+ | 404 | Harita yok. Silinmiş, `once=True` ile okunmuş, başka çalışma alanının veya servis tutmuyordur. |
171
+ | 413 | Dosya 20 MB üstü. |
172
+ | 502 | Motor hata verdi; anonymize ücreti iade edilir. Yanıt JSON değilse de 502 olur. |
173
+ | 503 | Servise ulaşılamadı. İstek gitmedi. |
174
+ | 504 | `timeout` doldu. İstek servise ulaşmış olabilir; ücret düşmüş olabilir. Konsoldaki Kullanım sayfasına bakın. |
175
+
176
+ Ü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.
177
+
178
+ ### `MaskSession`
179
+
180
+ `with bb_mask.session()` bunu verir. `doc_id` ve `state` oturumun içindedir.
181
+
182
+ | Metod | Dönüş |
183
+ |---|---|
184
+ | `anonymize(text)` | `Tagged` |
185
+ | `anonymize_file(path)` | `Tagged`. Yolu okur. |
186
+ | `anonymize_documents(paths)` | `Tagged` |
187
+ | `restore(model_metni)` | `str` |
188
+ | `close()` | `None`. Blok bitince kendiliğinden çağrılır. |
189
+ | `persist` | `bool`. Kurgu 1 ise `True`. Oturumda sabittir. |
190
+ | `options` | `dict`. `session(...)` içine verilen seçenekler. Her anonymize çağrısına gider. |
191
+
192
+ `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.
193
+
194
+ ## Çağrılar
195
+
196
+ Hepsi `init` sonrasında. Dosya uzantısı `.txt`, `.pdf` veya `.docx`. Dosya başına tavan 20 MB.
197
+
198
+ `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.
199
+
200
+ ### Kurgu 1 — harita serviste, siz `doc_id` tutarsınız
201
+
202
+ ```python
203
+ tagged = bb_mask.anonymize(metin)
204
+ cevap = kendi_llm(tagged.text)
205
+ duz = bb_mask.restore(tagged.doc_id, cevap)
206
+ bb_mask.delete(tagged.doc_id) # iş bitince
207
+ ```
208
+
209
+ Tek dosya:
210
+
211
+ ```python
212
+ tagged = bb_mask.anonymize_file("dilekce.pdf")
213
+ duz = bb_mask.restore(tagged.doc_id, kendi_llm(tagged.text))
214
+ ```
215
+
216
+ 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.
217
+
218
+ ```python
219
+ tagged = bb_mask.anonymize_documents(
220
+ ["dilekce.pdf", "cevap.docx", "ek.txt"]
221
+ )
222
+ duz = bb_mask.restore(tagged.doc_id, kendi_llm(tagged.text))
223
+ ```
224
+
225
+ `restore` orijinal dosyayı almaz. Modelin yazdığı metindeki etiketleri açar.
226
+
227
+ ### Kurgu 2 — aynı `doc_id`, üstüne sözlük
228
+
229
+ ```python
230
+ tagged = bb_mask.anonymize(metin)
231
+ sozluk = bb_mask.get_map(tagged.doc_id)
232
+ # sozluk["PERSON"]["Hasan Demirkol"] == "<PERSON_0>"
233
+
234
+ duz = bb_mask.restore(tagged.doc_id, kendi_llm(tagged.text))
235
+ ```
236
+
237
+ Okuyunca servisteki kopya da silinsin:
238
+
239
+ ```python
240
+ sozluk = bb_mask.get_map(tagged.doc_id, once=True)
241
+ # bundan sonra restore ve get_map 404 döner
242
+ ```
243
+
244
+ Sözlük gerekmiyorsa Kurgu 1 yeter.
245
+
246
+ ### Kurgu 3 — harita sizde, servis saklamaz
247
+
248
+ `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.
249
+
250
+ ```python
251
+ tagged = bb_mask.anonymize(metin, persist=False)
252
+ assert tagged.doc_id is None and tagged.state is not None
253
+
254
+ cevap = kendi_llm(tagged.text)
255
+ duz = bb_mask.restore(tagged.state, cevap)
256
+ ```
257
+
258
+ Dosyada da aynıdır: `anonymize_file(yol, persist=False)`, `anonymize_documents(yollar, persist=False)`.
259
+
260
+ ### Kurgu 4 — siz id veya json görmezsiniz
261
+
262
+ Kurgu 1. Çıkışta harita silinir.
263
+
264
+ ```python
265
+ with bb_mask.session() as s:
266
+ tagged = s.anonymize_documents(["dilekce.pdf", "ek.txt"])
267
+ cevap = kendi_llm(tagged.text)
268
+ duz = s.restore(cevap)
269
+ ```
270
+
271
+ Kurgu 3 yüzeyi. State oturum nesnesindedir, servise yazılmaz.
272
+
273
+ ```python
274
+ with bb_mask.session(persist=False) as s:
275
+ tagged = s.anonymize(metin)
276
+ duz = s.restore(kendi_llm(tagged.text))
277
+ ```
278
+
279
+ ### Async
280
+
281
+ 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.
282
+
283
+ ```python
284
+ aanonymize(text, persist=True, *, <seçenekler>) -> Tagged
285
+ aanonymize_file(path, persist=True, *, <seçenekler>) -> Tagged
286
+ aanonymize_documents(paths, persist=True, *, <seçenekler>) -> Tagged
287
+ arestore(doc_id_or_state, model_text) -> str
288
+ ```
289
+
290
+ ```python
291
+ tagged = await bb_mask.aanonymize(metin)
292
+ duz = await bb_mask.arestore(tagged.doc_id, cevap)
293
+ ```
294
+
295
+ `get_map`, `delete`, `session` ve `anonymize_bytes` için async karşılık yoktur.
296
+
297
+ ## Referans
298
+
299
+ Modül fonksiyonları `init` ister. `BBAnonym` metotları kurucudaki anahtarı kullanır.
300
+
301
+ ### Modül
302
+
303
+ ```python
304
+ init(api_key: str, base_url: str = "https://app.bbmask.co", timeout: float = 150) -> BBAnonym
305
+ anonymize(text: str, persist: bool = True, *, <seçenekler>) -> Tagged
306
+ anonymize_file(path: str | Path, persist: bool = True, *, <seçenekler>) -> Tagged
307
+ anonymize_bytes(filename: str, content: bytes, persist: bool = True, *, <seçenekler>) -> Tagged
308
+ anonymize_documents(paths: list[str | Path], persist: bool = True, *, <seçenekler>) -> Tagged
309
+ restore(doc_id_or_state: str | dict, model_text: str) -> str
310
+ get_map(doc_id: str, once: bool = False) -> dict
311
+ delete(doc_id: str) -> bool
312
+ session(persist: bool = True, *, <seçenekler>) # with ile MaskSession
313
+ aanonymize(text: str, persist: bool = True, *, <seçenekler>) -> Tagged
314
+ aanonymize_file(path: str | Path, persist: bool = True, *, <seçenekler>) -> Tagged
315
+ aanonymize_documents(paths: list[str | Path], persist: bool = True, *, <seçenekler>) -> Tagged
316
+ arestore(doc_id_or_state: str | dict, model_text: str) -> str
317
+ ```
318
+
319
+ `<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:
320
+
321
+ ```python
322
+ placeholder_style: Literal["angle", "bracket_tr"] = "angle",
323
+ keep_legal_form: bool = False,
324
+ health_data: bool = False,
325
+ llm_review: bool = False,
326
+ ```
327
+
328
+ `persist=True` haritayı serviste tutar, `Tagged.doc_id` dolar. `persist=False` haritayı yazmaz, `Tagged.state` dolar, `doc_id` `None` olur.
329
+
330
+ `restore` ilk argüman `doc_id` (`str`) veya `state` (`dict`). İkinci argüman modelin yazdığı metindir. Dönüş düz metindir.
331
+
332
+ `get_map` sözlüğü döner. `once=True` okuyunca servisteki kopyayı siler; bundan sonra `restore` ve `get_map` `404` verir.
333
+
334
+ `delete` servis `deleted` derse `True` döner.
335
+
336
+ `session` context manager'dır: `with bb_mask.session() as s`. Çıkışta `s.close()` çalışır.
337
+
338
+ ### `BBAnonym`
339
+
340
+ `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.
341
+
342
+ ```python
343
+ BBAnonym(base_url: str, token: str, timeout: float = 150)
344
+ anonymize(text: str, persist: bool = True, *, <seçenekler>) -> Tagged
345
+ anonymize_file(path: str | Path, persist: bool = True, *, <seçenekler>) -> Tagged
346
+ anonymize_bytes(filename: str, content: bytes, persist: bool = True, *, <seçenekler>) -> Tagged
347
+ anonymize_documents(paths: list[str | Path], persist: bool = True, *, <seçenekler>) -> Tagged
348
+ restore(doc_id_or_state: str | dict, model_text: str) -> str
349
+ get_map(doc_id: str, once: bool = False) -> dict
350
+ delete(doc_id: str) -> bool
351
+ close() -> None
352
+ ```
353
+
354
+ Paket `py.typed` taşır; tip denetleyiciler imzaları okur.
355
+
356
+ ### `MaskSession`
357
+
358
+ 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)`.
359
+
360
+ ```python
361
+ anonymize(text: str) -> Tagged
362
+ anonymize_file(path: str | Path) -> Tagged
363
+ anonymize_documents(paths: list[str | Path]) -> Tagged
364
+ restore(model_text: str) -> str
365
+ close() -> None
366
+ ```
367
+
368
+ ## Bu pakette olmayanlar
369
+
370
+ - Müşterinin LLM çağrısı ve `@ask`.
371
+ - FastAPI uygulaması, konsol çıktısı, `sleep`.
372
+ - Anahtar üretimi ve bakiye. Onlar panelde.
373
+ - Etiket onarımı. Bozuk etiketi servis düzeltir; sözlükteki anahtar düz metindir.