Skip to main content

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)

Source distribution for bb-mask 0.3.0
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)

Table of built distributions (wheels) for bb-mask 0.3.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.3.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page