maskflow-sdk 0.1.0__tar.gz

maskflow_sdk-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.env
+node_modules/
+dist/
+build/
+*.egg-info/
+.DS_Store
+.pytest_cache/
+.idea/

maskflow_sdk-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

maskflow_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: maskflow-sdk
+Version: 0.1.0
+Summary: Mask PII before it reaches an LLM, unmask the response. Works with any provider.
+License: MIT
+Requires-Python: >=3.9
+Requires-Dist: maskflow-core<0.2,>=0.1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# maskflow
+
+Mask PII before it reaches an LLM. Unmask the response. Works with any provider.
+
+```python
+from maskflow import mask_and_call
+
+def call_claude(masked_prompt: str) -> str:
+    return anthropic_client.messages.create(
+        model="claude-sonnet-5",
+        max_tokens=1024,
+        messages=[{"role": "user", "content": masked_prompt}],
+    ).content[0].text
+
+response = mask_and_call(
+    "Hi, I'm Jane Doe (jane@example.com). My order shipped to 123 Main St but never arrived.",
+    call_claude,
+)
+# Claude only ever sees "Hi, I'm <PERSON_NAME_1> (<EMAIL_1>). My order shipped to
+# <ADDRESS_1> but never arrived." -- response comes back with the real values restored.
+```
+
+## Install
+
+```bash
+pip install maskflow-sdk
+```
+
+## Why this shape
+
+`mask_and_call` takes a plain function, not a specific provider's client. You write the one line
+that actually calls your LLM (Claude, OpenAI, Gemini, a local model, anything) -- maskflow never
+parses or depends on any provider's SDK, so it doesn't break when a provider changes their API and
+works with providers it's never heard of.
+
+```python
+response = mask_and_call(prompt, lambda masked: my_llm_client.generate(masked))
+```
+
+## Lower-level API
+
+For more control than the wrapper gives, `mask`/`unmask` are available directly and are pure,
+stateless functions -- no files, no database. Persisting the mapping between calls is your
+responsibility.
+
+```python
+from maskflow import mask, unmask
+
+result = mask("Email me at alice@example.com.")
+result.masked_text  # "Email me at <EMAIL_1>."
+result.mapping       # {"<EMAIL_1>": "alice@example.com"}
+
+unmask(result.masked_text, result.mapping)  # original text, restored
+```
+
+## What gets detected
+
+Email, phone, SSN, credit card, IP address, AWS access key, API key / generic secret, JWT, IBAN,
+street address, person name, date of birth -- via regex + structural validation (Luhn, mod-97,
+etc.) plus spaCy NER for names and dates, with keyword-context confidence boosting. See
+[`maskflow-core`](../../core) for detection internals.
+
+## Tests
+
+```bash
+uv run pytest
+```

maskflow_sdk-0.1.0/README.md

@@ -0,0 +1,67 @@
+# maskflow
+
+Mask PII before it reaches an LLM. Unmask the response. Works with any provider.
+
+```python
+from maskflow import mask_and_call
+
+def call_claude(masked_prompt: str) -> str:
+    return anthropic_client.messages.create(
+        model="claude-sonnet-5",
+        max_tokens=1024,
+        messages=[{"role": "user", "content": masked_prompt}],
+    ).content[0].text
+
+response = mask_and_call(
+    "Hi, I'm Jane Doe (jane@example.com). My order shipped to 123 Main St but never arrived.",
+    call_claude,
+)
+# Claude only ever sees "Hi, I'm <PERSON_NAME_1> (<EMAIL_1>). My order shipped to
+# <ADDRESS_1> but never arrived." -- response comes back with the real values restored.
+```
+
+## Install
+
+```bash
+pip install maskflow-sdk
+```
+
+## Why this shape
+
+`mask_and_call` takes a plain function, not a specific provider's client. You write the one line
+that actually calls your LLM (Claude, OpenAI, Gemini, a local model, anything) -- maskflow never
+parses or depends on any provider's SDK, so it doesn't break when a provider changes their API and
+works with providers it's never heard of.
+
+```python
+response = mask_and_call(prompt, lambda masked: my_llm_client.generate(masked))
+```
+
+## Lower-level API
+
+For more control than the wrapper gives, `mask`/`unmask` are available directly and are pure,
+stateless functions -- no files, no database. Persisting the mapping between calls is your
+responsibility.
+
+```python
+from maskflow import mask, unmask
+
+result = mask("Email me at alice@example.com.")
+result.masked_text  # "Email me at <EMAIL_1>."
+result.mapping       # {"<EMAIL_1>": "alice@example.com"}
+
+unmask(result.masked_text, result.mapping)  # original text, restored
+```
+
+## What gets detected
+
+Email, phone, SSN, credit card, IP address, AWS access key, API key / generic secret, JWT, IBAN,
+street address, person name, date of birth -- via regex + structural validation (Luhn, mod-97,
+etc.) plus spaCy NER for names and dates, with keyword-context confidence boosting. See
+[`maskflow-core`](../../core) for detection internals.
+
+## Tests
+
+```bash
+uv run pytest
+```

maskflow_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "maskflow-sdk"
+version = "0.1.0"
+description = "Mask PII before it reaches an LLM, unmask the response. Works with any provider."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+dependencies = [
+    "maskflow-core>=0.1.0,<0.2",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+]
+
+[tool.uv.sources]
+maskflow-core = { path = "../../core", editable = true }
+
+[tool.uv]
+package = true
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/maskflow"]

maskflow_sdk-0.1.0/src/maskflow/__init__.py

@@ -0,0 +1,13 @@
+from maskflow_core import Finding, MaskResult, PIIType, detect, mask, unmask
+
+from .sdk import mask_and_call
+
+__all__ = [
+    "detect",
+    "mask",
+    "unmask",
+    "mask_and_call",
+    "Finding",
+    "PIIType",
+    "MaskResult",
+]

maskflow_sdk-0.1.0/src/maskflow/sdk.py

@@ -0,0 +1,23 @@
+from typing import Callable
+
+from maskflow_core import mask, unmask
+from maskflow_core.detection import DEFAULT_MIN_CONFIDENCE
+
+
+def mask_and_call(
+    prompt: str,
+    call_fn: Callable[[str], str],
+    min_confidence: float = DEFAULT_MIN_CONFIDENCE,
+) -> str:
+    """Mask PII in `prompt`, pass the masked text to `call_fn`, and restore the
+    original values in whatever `call_fn` returns.
+
+    `call_fn` is any function that takes a string and returns a string --
+    typically a closure around an LLM provider's client call. This makes
+    mask_and_call provider-agnostic: it works with Claude, OpenAI, Gemini, a
+    local model, or anything else, without MaskFlow depending on any
+    provider's SDK.
+    """
+    result = mask(prompt, min_confidence=min_confidence)
+    response = call_fn(result.masked_text)
+    return unmask(response, result.mapping)

maskflow_sdk-0.1.0/tests/test_sdk.py

@@ -0,0 +1,51 @@
+from maskflow import Finding, MaskResult, PIIType, detect, mask, mask_and_call, unmask
+
+
+def test_mask_and_call_never_exposes_pii_to_call_fn():
+    seen = {}
+
+    def call_fn(masked_prompt: str) -> str:
+        seen["prompt"] = masked_prompt
+        return f"Sure, I'll email you back at {masked_prompt.split('at ')[1]}"
+
+    prompt = "Email me at alice@example.com with the update."
+    mask_and_call(prompt, call_fn)
+
+    assert "alice@example.com" not in seen["prompt"]
+    assert "<EMAIL_1>" in seen["prompt"]
+
+
+def test_mask_and_call_restores_original_values_in_response():
+    def call_fn(masked_prompt: str) -> str:
+        return f"Got it, confirming: {masked_prompt}"
+
+    prompt = "My phone number is 415-555-0132."
+    result = mask_and_call(prompt, call_fn)
+
+    assert "415-555-0132" in result
+    assert "<PHONE_1>" not in result
+
+
+def test_mask_and_call_is_provider_agnostic():
+    """call_fn is just a plain callable -- swapping providers means swapping the
+    closure, not touching mask_and_call itself."""
+
+    def fake_anthropic_call(masked_prompt: str) -> str:
+        return f"[claude] {masked_prompt}"
+
+    def fake_openai_call(masked_prompt: str) -> str:
+        return f"[gpt] {masked_prompt}"
+
+    prompt = "Contact bob@example.com."
+    assert mask_and_call(prompt, fake_anthropic_call) == f"[claude] {prompt}"
+    assert mask_and_call(prompt, fake_openai_call) == f"[gpt] {prompt}"
+
+
+def test_sdk_reexports_core_primitives():
+    text = "Reach me at carol@example.com."
+    result = mask(text)
+
+    assert isinstance(result, MaskResult)
+    assert unmask(result.masked_text, result.mapping) == text
+    assert detect(text)[0].type == PIIType.EMAIL
+    assert isinstance(detect(text)[0], Finding)