Metadata-Version: 2.4
Name: kalkan
Version: 0.3.0
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3
Classifier: Natural Language :: Turkish
Classifier: Natural Language :: English
Classifier: License :: OSI Approved :: MIT License
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Topic :: Security
Classifier: Topic :: Text Processing
Requires-Dist: langchain-core ; extra == 'langchain'
Requires-Dist: litellm ; extra == 'litellm'
Provides-Extra: langchain
Provides-Extra: litellm
Summary: Fast PII shield for Turkish text: masks personal data before it reaches an LLM and restores it in the reply (KVKK/GDPR, Rust).
Keywords: kvkk,pii,llm,turkish,anonymization,privacy
License: MIT OR Apache-2.0
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Changelog, https://github.com/CelkMehmett/kalkan/blob/main/CHANGELOG.md
Project-URL: Documentation, https://docs.rs/kalkan
Project-URL: Repository, https://github.com/CelkMehmett/kalkan

# kalkan (Python)

A fast PII shield for Turkish text: masks personal data (national ID, IBAN, phone, card, names,
addresses, SGK numbers, IP, date of birth, …) before it reaches an LLM and restores it in the reply. Built for KVKK
(Turkey's GDPR counterpart). Written in Rust; about 8× faster than pure-Python regex solutions on
a single core, and `mask_batch` uses all cores with the GIL released.

> **Türkçe:** Türkçe kişisel verileri LLM'e gitmeden maskeleyen, cevapta geri yükleyen KVKK
> motoru. Türkçe belgeler için [README.tr.md](https://github.com/CelkMehmett/kalkan/blob/main/README.tr.md).

## Usage

```bash
pip install kalkan
```

```python
import kalkan

k = kalkan.Kalkan(terms=["Proje Atlas"])
s = k.session()                        # one session per conversation

prompt = s.mask("Ayşe Kaya Hanım, TC 10000000146, Proje Atlas bütçesi")
# "[AD_SOYAD_1] Hanım, TC [TCKN_1], [OZEL_1] bütçesi"

reply = llm(prompt)
report = s.audit(reply)                # did the model produce new PII?
if not report:
    log.warning(report)
print(s.restore(reply))

# Streaming
stream = s.stream()
for chunk in llm_stream(prompt):
    send(stream.push(chunk))
send(stream.finish())

# Batch anonymization: all cores, GIL released
clean = kalkan.Kalkan(strategy="label").mask_batch(millions_of_records)
```

`start`/`end` in `detect()` results are character indices: `text[e.start:e.end]` works directly.
The vault is available as a dict via `s.vault` and can be loaded in another process with `import_vault`.

## Integrations

```python
from kalkan.messages import mask_messages                 # OpenAI SDK, no dependencies
from kalkan.integrations.litellm import completion        # pip install "kalkan[litellm]"
from kalkan.integrations.litellm import KalkanGuardrail   # LiteLLM Proxy guardrail
from kalkan.integrations.langchain import with_kalkan     # pip install "kalkan[langchain]"
```

All of them restore streaming replies, even when a placeholder is split across chunks.

Full documentation, limitations and benchmarks:
[github.com/CelkMehmett/kalkan](https://github.com/CelkMehmett/kalkan).

> kalkan is a helper, not a legal compliance guarantee. Detection is not 100%.

