bb-mask
English · Türkçe
Tags personal data in Turkish legal text and puts the real values back into the model’s answer. The package is a thin HTTP client. It never calls a model, never prints, never sleeps.
You get a dm_test_ key from the Data Mask console. Your backend installs this package and passes the key to init. The LLM call is yours; anonymize goes before it and restore after it.
import os
import bb_mask
bb_mask.init(api_key=os.environ["BB_ANONYM_TOKEN"])
def summarize(text: str) -> str:
tagged = bb_mask.anonymize(text)
reply = my_llm(tagged.text) # your code
return bb_mask.restore(tagged.doc_id, reply)
Python 3.11+. The only dependency is httpx. This folder is the Python package. Node, Go, C# and Java live in the other folders of the same repository.
Install
Once published:
pip install bb-mask
Before release, from the repository root:
pip install -e python
Never put the key in code or in the repository. An environment variable or your own config file is enough.
export BB_ANONYM_TOKEN="dm_test_..."
init runs once per process. It is not a model call. Module functions (bb_mask.anonymize and the rest) called before it raise BBError(401) and never reach the service.
client = bb_mask.init(
api_key=os.environ["BB_ANONYM_TOKEN"],
base_url="https://app.bbmask.co", # this is the default
timeout=150, # seconds
)
| Argument | Type | Meaning |
|---|---|---|
api_key |
str |
The dm_test_ key from the console. Empty → BBError(401). |
base_url |
str |
Service address. Default https://app.bbmask.co. |
timeout |
float |
HTTP timeout in seconds. Default 150; the engine waits up to 120 s and the client gives up after that. |
Returns a BBAnonym. Module functions use this client. A second init replaces the first.
If you need a second key, construct BBAnonym without touching the process-wide client. The constructor does not need init.
other = bb_mask.BBAnonym("https://app.bbmask.co", token, timeout=150)
Objects
Tagged
Returned by anonymize, anonymize_file and anonymize_documents.
| Field | Type | When it is set |
|---|---|---|
text |
str |
Always. Personal data is replaced by tags: <PERSON_0>, <TR_NATIONAL_ID_0>. |
doc_id |
str | None |
persist=True (default). The mapping’s key on the service. Only a key from the same workspace can open it. |
state |
dict | None |
persist=False. The mapping itself. Never stored on the service. |
entities_found |
dict[str, int] |
Always. Count per type: {"PERSON": 2}. No plain names. |
balance_credits |
str | None |
Balance left after the call: "9.00". |
request_id |
str | None |
The response’s X-Request-Id. Matches a row on the console’s Usage page. |
placeholder_style |
str |
Applied tag format: "angle" or "bracket_tr". |
keep_legal_form |
bool |
Applied value. |
health_data |
bool |
Applied value. |
llm_review |
dict | None |
If llm_review=True was requested, a status summary: status, model, chunks, chunks_failed, elapsed_ms, added_spans, error. No plain names. |
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
Tags look like <TYPE_0>. The same surface form gets the same number. If the model breaks a tag (<PERSON 0>), the service repairs it. Court and statute names are not tagged.
Options
All four anonymize calls (anonymize, anonymize_file, anonymize_bytes, anonymize_documents), their async counterparts and session() take the same keyword-only parameters. All are off by default; the service never falls back to its own defaults.
| Parameter | Default | Effect |
|---|---|---|
placeholder_style |
"angle" |
"angle" → <PERSON_0>. "bracket_tr" → [KİŞİ_1], [ŞİRKET_1]; numbering starts at 1. Any other value raises BBError(400) before the request is sent. |
keep_legal_form |
False |
True → the company type suffix stays outside the tag: [ŞİRKET_1] A.Ş., <ORGANIZATION_0> Ltd. Şti. |
health_data |
False |
True → also tags health data under KVKK Art. 6: diagnoses, medication, lab results, blood type, patient numbers, healthcare providers. |
llm_review |
False |
True → an LLM makes a second pass for people, companies, addresses and IDs the rules missed. The model sees the temporarily anonymized text. If the service layer is off, it is not an error; Tagged.llm_review["status"] tells you. |
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, ...}
The state and get_map dictionaries carry canonical tags (<PERSON_0>) regardless of format. restore opens both formats.
The state / get_map dictionary
Shape: dict[str, dict[str, str]]. The outer key is the entity type, the inner key is the plain text, the value is the tag.
{
"PERSON": {"Hasan Demirkol": "<PERSON_0>"},
"TR_NATIONAL_ID": {"62601815964": "<TR_NATIONAL_ID_0>"},
}
The dictionary carries plain names. Never put it in logs, tickets or the model. restore uses it for you; only tagged.text goes to the model.
BBError
Subclass of RuntimeError. status_code: int, detail: str, request_id: str | None. str(error) is the detail text. request_id is set when the service responded; include it when you contact support.
Network errors are BBError too; no httpx exception leaks out.
| Code | Meaning |
|---|---|
| 400 | Empty text, file count outside 1–3, invalid placeholder_style, nothing anonymized in the session, or neither doc_id nor state given. |
| 401 | init not called, or the key is empty or unknown. |
| 402 | No balance. Nothing is sent for anonymization. |
| 404 | Mapping not found. It was deleted, read with once=True, belongs to another workspace, or was never stored. |
| 413 | File larger than 20 MB. |
| 502 | The engine failed; the anonymize fee is refunded. A non-JSON response is also 502. |
| 503 | Service unreachable. The request was not sent. |
| 504 | timeout expired. The request may have reached the service and the fee may have been charged. Check the Usage page in the console. |
The fee is charged on a successful anonymize call. If the service fails, the fee is refunded. restore, get_map and delete are free.
MaskSession
Returned by with bb_mask.session(). The doc_id and state stay inside the session.
| Method | Returns |
|---|---|
anonymize(text) |
Tagged |
anonymize_file(path) |
Tagged. Reads the path. |
anonymize_documents(paths) |
Tagged |
restore(model_text) |
str |
close() |
None. Called automatically when the block ends. |
persist |
bool. True for pattern 1. Fixed for the session. |
options |
dict. The options passed to session(...). Sent with every anonymize call. |
Here restore takes only the model text. Called before any anonymize, it raises BBError(400). When the block ends close runs: with persist=True every kept doc_id is deleted; with persist=False the state is dropped and no delete is sent.
Calls
All of them need init first. File extensions: .txt, .pdf or .docx. Up to 20 MB per file.
anonymize_file(path) takes a path and reads the file. If you already hold the bytes, use anonymize_bytes(filename, content). Both names mean the same thing on the module and on BBAnonym. MaskSession.anonymize_file(path) reads a path too.
Pattern 1 — mapping on the service, you keep the doc_id
tagged = bb_mask.anonymize(text)
reply = my_llm(tagged.text)
restored = bb_mask.restore(tagged.doc_id, reply)
bb_mask.delete(tagged.doc_id) # when you are done
One file:
tagged = bb_mask.anonymize_file("petition.pdf")
restored = bb_mask.restore(tagged.doc_id, my_llm(tagged.text))
Several files share one doc_id. The same person is <PERSON_0> in both files. Up to 3 files. The fee is one anonymize.
tagged = bb_mask.anonymize_documents(
["petition.pdf", "response.docx", "appendix.txt"]
)
restored = bb_mask.restore(tagged.doc_id, my_llm(tagged.text))
restore does not take the original file. It opens the tags in the text the model wrote.
Pattern 2 — same doc_id, plus the dictionary
tagged = bb_mask.anonymize(text)
mapping = bb_mask.get_map(tagged.doc_id)
# mapping["PERSON"]["Hasan Demirkol"] == "<PERSON_0>"
restored = bb_mask.restore(tagged.doc_id, my_llm(tagged.text))
Delete the service copy as soon as you read it:
mapping = bb_mask.get_map(tagged.doc_id, once=True)
# from now on restore and get_map return 404
If you do not need the dictionary, pattern 1 is enough.
Pattern 3 — mapping on your side, the service stores nothing
doc_id is empty. state is the dictionary. Never send it to the model. You can store state on your side so restore still works after the process exits.
tagged = bb_mask.anonymize(text, persist=False)
assert tagged.doc_id is None and tagged.state is not None
reply = my_llm(tagged.text)
restored = bb_mask.restore(tagged.state, reply)
Files work the same way: anonymize_file(path, persist=False), anonymize_documents(paths, persist=False).
Pattern 4 — you never see an id or JSON
Pattern 1. The mapping is deleted on exit.
with bb_mask.session() as s:
tagged = s.anonymize_documents(["petition.pdf", "appendix.txt"])
reply = my_llm(tagged.text)
restored = s.restore(reply)
Pattern 3 surface. The state lives in the session object and is never stored on the service.
with bb_mask.session(persist=False) as s:
tagged = s.anonymize(text)
restored = s.restore(my_llm(tagged.text))
Async
There are four functions. Signatures match their sync counterparts. The HTTP work runs in a thread. They need init too.
aanonymize(text, persist=True, *, <options>) -> Tagged
aanonymize_file(path, persist=True, *, <options>) -> Tagged
aanonymize_documents(paths, persist=True, *, <options>) -> Tagged
arestore(doc_id_or_state, model_text) -> str
tagged = await bb_mask.aanonymize(text)
restored = await bb_mask.arestore(tagged.doc_id, reply)
get_map, delete, session and anonymize_bytes have no async version.
Reference
Module functions need init. BBAnonym methods use the key given to the constructor.
Module
init(api_key: str, base_url: str = "https://app.bbmask.co", timeout: float = 150) -> BBAnonym
anonymize(text: str, persist: bool = True, *, <options>) -> Tagged
anonymize_file(path: str | Path, persist: bool = True, *, <options>) -> Tagged
anonymize_bytes(filename: str, content: bytes, persist: bool = True, *, <options>) -> Tagged
anonymize_documents(paths: list[str | Path], persist: bool = True, *, <options>) -> 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, *, <options>) # MaskSession via with
aanonymize(text: str, persist: bool = True, *, <options>) -> Tagged
aanonymize_file(path: str | Path, persist: bool = True, *, <options>) -> Tagged
aanonymize_documents(paths: list[str | Path], persist: bool = True, *, <options>) -> Tagged
arestore(doc_id_or_state: str | dict, model_text: str) -> str
<options> are the four keyword-only parameters; they are spelled out in the signature, so your editor completes them and help(bb_mask.anonymize) explains them:
placeholder_style: Literal["angle", "bracket_tr"] = "angle",
keep_legal_form: bool = False,
health_data: bool = False,
llm_review: bool = False,
persist=True keeps the mapping on the service and sets Tagged.doc_id. persist=False stores nothing, sets Tagged.state, and doc_id is None.
restore takes a doc_id (str) or a state (dict) first. The second argument is the text the model wrote. It returns plain text.
get_map returns the dictionary. once=True deletes the service copy after reading; after that restore and get_map return 404.
delete returns True when the service reports deleted.
session is a context manager: with bb_mask.session() as s. s.close() runs on exit.
BBAnonym
No init needed. Same names as the module. It shares a single httpx.Client (connection pool); close it with with or close(). repr() masks the key.
BBAnonym(base_url: str, token: str, timeout: float = 150)
anonymize(text: str, persist: bool = True, *, <options>) -> Tagged
anonymize_file(path: str | Path, persist: bool = True, *, <options>) -> Tagged
anonymize_bytes(filename: str, content: bytes, persist: bool = True, *, <options>) -> Tagged
anonymize_documents(paths: list[str | Path], persist: bool = True, *, <options>) -> 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
The package ships py.typed; type checkers read the signatures.
MaskSession
Not constructed directly. persist and the options are given when the session opens and are not passed to the methods again: 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
Not in this package
- Your LLM call and
@ask. - A FastAPI app, console output,
sleep. - Key creation and balance. Those are in the console.
- Tag repair. The service fixes broken tags; dictionary keys are plain text.
Metadata
Release files for bb-mask 0.3.1
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.1.tar.gz | 18.8 kB | With provenance | Details for bb_mask-0.3.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| bb_mask-0.3.1-py3-none-any.whl | Python 3 | none | any | Details for bb_mask-0.3.1-py3-none-any.whl |
Total release size: 30.5 kB
Release files / bb_mask-0.3.1.tar.gz
| Download URL | bb_mask-0.3.1.tar.gz |
|---|---|
| Size | 18.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
01860ec4201c2fb43a14166487f594f72996734fab8b53d226fc4214ccac0c5e
|
|
BLAKE2b-256 checksum How to use checksums |
4407c75064f3c89daeb13b808706b7ae7b330cc2992f99138cb7815ac8ec69bd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logRelease files / bb_mask-0.3.1-py3-none-any.whl
| Download URL | bb_mask-0.3.1-py3-none-any.whl |
|---|---|
| Size | 11.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f840890564e3b3495fb831e9ce0af1ef7dfb55751ca67e74ef373426974f1ce7
|
|
BLAKE2b-256 checksum How to use checksums |
8be877b770c8eb47c1453b4ec97ad650b56ca56b5cbd350053107e84946b7076
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logSecurity for bb-mask 0.3.1
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.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for bb_mask-0.3.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logA 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.