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.
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:
pip install bb-mask
Yayın öncesi, depo kökünden:
pip install -e python
Anahtarı koda veya repoya yazmayın. Ortam değişkeni veya kendi ayar dosyanız yeter.
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.
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.
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. |
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. |
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.
{
"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
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:
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.
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
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:
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.
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.
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.
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.
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
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
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:
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.
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).
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.
Metadata
Release files for bb-mask 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| bb_mask-0.3.0.tar.gz | 18.9 kB | Without provenance | Details for bb_mask-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| bb_mask-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for bb_mask-0.3.0-py3-none-any.whl |
Total release size: 30.7 kB
Release files / bb_mask-0.3.0.tar.gz
| Download URL | bb_mask-0.3.0.tar.gz |
|---|---|
| Size | 18.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a8138f01ff07130e3137b720ba4ffd775774fbc0d60586c77a80e682ac854257
|
|
BLAKE2b-256 checksum How to use checksums |
85e6e65d809f74ad14c08cd2df0a4c66325bbb5cedb0cc95c19d99ef1396860e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / bb_mask-0.3.0-py3-none-any.whl
| Download URL | bb_mask-0.3.0-py3-none-any.whl |
|---|---|
| Size | 11.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d095a639c1bb6649076cdb2cbfa71d380d10839a8faa0c810a812fc89ac6003c
|
|
BLAKE2b-256 checksum How to use checksums |
33d7413309e111e674000417eaa1f9770830324407e7d7d178de6811044aa829
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Security for bb-mask 0.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.