maskflow-langchain 0.1.0__tar.gz

maskflow_langchain-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.env
+node_modules/
+dist/
+build/
+*.egg-info/
+.DS_Store
+.pytest_cache/
+.idea/
+.coverage
+.mypy_cache/
+.ruff_cache/
+bench/indiapii/quality/.cache/

maskflow_langchain-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.5
+Name: maskflow-langchain
+Version: 0.1.0
+Summary: MaskFlow for LangChain: a reversible PII anonymizer/deanonymizer pair (drop-in for langchain-experimental's Presidio anonymizer) plus a leak-guard callback. Indian identifiers included.
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: langchain-core<2,>=0.3
+Requires-Dist: maskflow-sdk<0.9,>=0.8.0
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.100; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: pyyaml>=6.0; extra == 'dev'
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+# maskflow-langchain
+
+MaskFlow for [LangChain](https://github.com/langchain-ai/langchain): a
+reversible PII anonymizer / deanonymizer pair that drops in for
+`langchain-experimental`'s Presidio anonymizer, plus a leak-guard callback.
+
+It runs MaskFlow's detection engine, so alongside the usual PII (email,
+phone, card numbers, ...) it covers the **Indian identifiers** most tools
+miss: Aadhaar, PAN, GSTIN, UPI VPA, IFSC, ABHA, Indian mobile / PIN code /
+voter ID / passport / driving licence / vehicle registration, and Indian
+names and addresses.
+
+- **Drop-in.** Same method names and mapping shapes as
+  `PresidioReversibleAnonymizer`, so migrating a chain is one import line.
+- **Streaming.** `anonymizer.deanonymizer` is a streaming-aware `Runnable`;
+  a placeholder split across two streamed chunks is stitched back before
+  the caller sees it. (Presidio's `RunnableLambda(deanonymize)` only fires
+  on the final string.)
+- **Leak guard.** An optional callback that fails a call closed if a prompt
+  still contains PII.
+- **MIT, no gates, no telemetry.**
+
+## Install
+
+```bash
+pip install maskflow-langchain
+pip install "maskflow-langchain[yaml]"   # if you save/load mappings as .yaml
+```
+
+`langchain-core` is a real dependency (`>=0.3,<2`). The first detection run
+downloads a small spaCy model for the name/address recognizers; pass
+`patterns_only=True` to skip it.
+
+## Migrating from the Presidio anonymizer
+
+```python
+# from langchain_experimental.data_anonymizer import PresidioReversibleAnonymizer
+from maskflow_langchain import MaskflowReversibleAnonymizer as PresidioReversibleAnonymizer
+```
+
+Everything a chain touches keeps working: `.anonymize(text, language=None,
+allow_list=None)`, `.deanonymize(text, strategy=exact_matching_strategy)`,
+`.reset_deanonymizer_mapping()`, `.deanonymizer_mapping`,
+`.anonymizer_mapping`, `.save_deanonymizer_mapping(path)`,
+`.load_deanonymizer_mapping(path)`.
+
+Two methods differ, because Presidio recognizer and operator objects have
+no MaskFlow equivalent:
+
+| Presidio | maskflow-langchain |
+|---|---|
+| `add_recognizer(recognizer_obj)` | `add_recognizer(entity_type=..., regex=..., base_confidence=0.6)` |
+| `add_operators({e: OperatorConfig(...)})` | `add_operators({e: "replace"\|"redact"\|"mask"\|"hash"\|"surrogate"})` |
+
+`allow_list` is passed to the **constructor** on the reversible anonymizer
+(the session is built once); a differing per-call `allow_list` raises.
+
+## Use it in a chain
+
+```python
+from langchain_core.output_parsers import StrOutputParser
+from langchain_core.prompts import ChatPromptTemplate
+from maskflow_langchain import MaskflowReversibleAnonymizer
+
+anonymizer = MaskflowReversibleAnonymizer()
+prompt = ChatPromptTemplate.from_template("Answer: {question}")
+
+chain = (
+    {"question": lambda x: anonymizer.anonymize(x["question"])}
+    | prompt
+    | llm
+    | StrOutputParser()
+    | anonymizer.deanonymizer  # streaming-aware
+)
+
+chain.invoke({"question": "Is PAN ABCPE1234F valid for a salaried filer?"})
+# the LLM sees "<PAN_1>"; you get "ABCPE1234F" back
+for piece in chain.stream({"question": "Confirm receipt of PAN ABCPE1234F"}):
+    print(piece, end="")  # deanonymized incrementally
+```
+
+## Leak-guard callback
+
+```python
+from maskflow_langchain import MaskflowLeakGuardCallback
+
+guard = MaskflowLeakGuardCallback(raise_on_prompt_pii=True)
+chain.invoke(x, config={"callbacks": [guard]})
+# raises MaskflowPIILeakError if a prompt reaching the LLM still has PII
+
+guard.summary()  # {"prompt": {"PAN": 0}, "completion": {...}} -- counts only, never values
+```
+
+Callbacks cannot rewrite prompts, so this does not mask; it audits (entity
+types and counts, never values) and, with `raise_on_prompt_pii=True`, aborts
+a call that would leak.
+
+## PII safety
+
+No original value is written to logs, `repr`, callback state, or a saved
+mapping's structure beyond what you explicitly persist with
+`save_deanonymizer_mapping` (which, like Presidio's, contains the real
+values -- treat that file as sensitive).
+
+See `docs/langchain.md` in the MaskFlow repo for design notes.

maskflow_langchain-0.1.0/README.md

@@ -0,0 +1,105 @@
+# maskflow-langchain
+
+MaskFlow for [LangChain](https://github.com/langchain-ai/langchain): a
+reversible PII anonymizer / deanonymizer pair that drops in for
+`langchain-experimental`'s Presidio anonymizer, plus a leak-guard callback.
+
+It runs MaskFlow's detection engine, so alongside the usual PII (email,
+phone, card numbers, ...) it covers the **Indian identifiers** most tools
+miss: Aadhaar, PAN, GSTIN, UPI VPA, IFSC, ABHA, Indian mobile / PIN code /
+voter ID / passport / driving licence / vehicle registration, and Indian
+names and addresses.
+
+- **Drop-in.** Same method names and mapping shapes as
+  `PresidioReversibleAnonymizer`, so migrating a chain is one import line.
+- **Streaming.** `anonymizer.deanonymizer` is a streaming-aware `Runnable`;
+  a placeholder split across two streamed chunks is stitched back before
+  the caller sees it. (Presidio's `RunnableLambda(deanonymize)` only fires
+  on the final string.)
+- **Leak guard.** An optional callback that fails a call closed if a prompt
+  still contains PII.
+- **MIT, no gates, no telemetry.**
+
+## Install
+
+```bash
+pip install maskflow-langchain
+pip install "maskflow-langchain[yaml]"   # if you save/load mappings as .yaml
+```
+
+`langchain-core` is a real dependency (`>=0.3,<2`). The first detection run
+downloads a small spaCy model for the name/address recognizers; pass
+`patterns_only=True` to skip it.
+
+## Migrating from the Presidio anonymizer
+
+```python
+# from langchain_experimental.data_anonymizer import PresidioReversibleAnonymizer
+from maskflow_langchain import MaskflowReversibleAnonymizer as PresidioReversibleAnonymizer
+```
+
+Everything a chain touches keeps working: `.anonymize(text, language=None,
+allow_list=None)`, `.deanonymize(text, strategy=exact_matching_strategy)`,
+`.reset_deanonymizer_mapping()`, `.deanonymizer_mapping`,
+`.anonymizer_mapping`, `.save_deanonymizer_mapping(path)`,
+`.load_deanonymizer_mapping(path)`.
+
+Two methods differ, because Presidio recognizer and operator objects have
+no MaskFlow equivalent:
+
+| Presidio | maskflow-langchain |
+|---|---|
+| `add_recognizer(recognizer_obj)` | `add_recognizer(entity_type=..., regex=..., base_confidence=0.6)` |
+| `add_operators({e: OperatorConfig(...)})` | `add_operators({e: "replace"\|"redact"\|"mask"\|"hash"\|"surrogate"})` |
+
+`allow_list` is passed to the **constructor** on the reversible anonymizer
+(the session is built once); a differing per-call `allow_list` raises.
+
+## Use it in a chain
+
+```python
+from langchain_core.output_parsers import StrOutputParser
+from langchain_core.prompts import ChatPromptTemplate
+from maskflow_langchain import MaskflowReversibleAnonymizer
+
+anonymizer = MaskflowReversibleAnonymizer()
+prompt = ChatPromptTemplate.from_template("Answer: {question}")
+
+chain = (
+    {"question": lambda x: anonymizer.anonymize(x["question"])}
+    | prompt
+    | llm
+    | StrOutputParser()
+    | anonymizer.deanonymizer  # streaming-aware
+)
+
+chain.invoke({"question": "Is PAN ABCPE1234F valid for a salaried filer?"})
+# the LLM sees "<PAN_1>"; you get "ABCPE1234F" back
+for piece in chain.stream({"question": "Confirm receipt of PAN ABCPE1234F"}):
+    print(piece, end="")  # deanonymized incrementally
+```
+
+## Leak-guard callback
+
+```python
+from maskflow_langchain import MaskflowLeakGuardCallback
+
+guard = MaskflowLeakGuardCallback(raise_on_prompt_pii=True)
+chain.invoke(x, config={"callbacks": [guard]})
+# raises MaskflowPIILeakError if a prompt reaching the LLM still has PII
+
+guard.summary()  # {"prompt": {"PAN": 0}, "completion": {...}} -- counts only, never values
+```
+
+Callbacks cannot rewrite prompts, so this does not mask; it audits (entity
+types and counts, never values) and, with `raise_on_prompt_pii=True`, aborts
+a call that would leak.
+
+## PII safety
+
+No original value is written to logs, `repr`, callback state, or a saved
+mapping's structure beyond what you explicitly persist with
+`save_deanonymizer_mapping` (which, like Presidio's, contains the real
+values -- treat that file as sensitive).
+
+See `docs/langchain.md` in the MaskFlow repo for design notes.

maskflow_langchain-0.1.0/examples/README.md

@@ -0,0 +1,22 @@
+# Runnable example
+
+`anonymized_chain.py` builds an LCEL chain that masks PII before the model
+and restores it after, and attaches the leak-guard callback.
+
+```bash
+pip install maskflow-langchain
+python packages/maskflow-langchain/examples/anonymized_chain.py
+```
+
+With `OPENAI_API_KEY` set it calls `gpt-4o-mini`; without one it uses a fake
+chat model so the mask/restore round-trip is still visible:
+
+```
+you asked   : Please file the return for PAN ABCPE1234F, UPI ramesh@oksbi, email ramesh@example.com.
+model saw   : Please file the return for PAN <PAN_1>, UPI <UPI_VPA_1>, email <EMAIL_1>.
+you get back: ...
+```
+
+`chain.stream(...)` deanonymizes incrementally through
+`anonymizer.deanonymizer`; `guard.summary()` reports detected entity types
+and counts, never values.

maskflow_langchain-0.1.0/examples/anonymized_chain.py

@@ -0,0 +1,57 @@
+"""Runnable example: a LangChain LCEL chain with MaskFlow anonymization.
+
+    pip install maskflow-langchain "langchain[openai]"
+    export OPENAI_API_KEY=sk-...
+    python packages/maskflow-langchain/examples/anonymized_chain.py
+
+Swap the model line for any chat model. With no API key it falls back to a
+fake model that echoes the (masked) prompt, so the round-trip is still
+visible.
+"""
+
+from __future__ import annotations
+
+import os
+
+from langchain_core.output_parsers import StrOutputParser
+from langchain_core.prompts import ChatPromptTemplate
+from maskflow_langchain import MaskflowLeakGuardCallback, MaskflowReversibleAnonymizer
+
+
+def _model():  # noqa: ANN202
+    if os.getenv("OPENAI_API_KEY"):
+        from langchain_openai import ChatOpenAI
+
+        return ChatOpenAI(model="gpt-4o-mini", temperature=0)
+    from langchain_core.language_models.fake_chat_models import FakeMessagesListChatModel
+    from langchain_core.messages import AIMessage
+
+    return FakeMessagesListChatModel(
+        responses=[AIMessage("Noted. I will reference the details you provided.")]
+    )
+
+
+anonymizer = MaskflowReversibleAnonymizer()
+prompt = ChatPromptTemplate.from_template(
+    "A user wrote: {question}\nAcknowledge and restate the identifiers you saw."
+)
+
+chain = (
+    {"question": lambda x: anonymizer.anonymize(x["question"])}
+    | prompt
+    | _model()
+    | StrOutputParser()
+    | anonymizer.deanonymizer
+)
+
+question = "Please file the return for PAN ABCPE1234F, UPI ramesh@oksbi, email ramesh@example.com."
+
+guard = MaskflowLeakGuardCallback()
+print("you asked   :", question)
+print("model saw   :", anonymizer.anonymize(question))
+print("you get back:", chain.invoke({"question": question}, config={"callbacks": [guard]}))
+print("streamed    :", end=" ")
+for piece in chain.stream({"question": question}):
+    print(piece, end="", flush=True)
+print()
+print("audit       :", guard.summary())

maskflow_langchain-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "maskflow-langchain"
+version = "0.1.0"
+description = "MaskFlow for LangChain: a reversible PII anonymizer/deanonymizer pair (drop-in for langchain-experimental's Presidio anonymizer) plus a leak-guard callback. Indian identifiers included."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+dependencies = [
+    # The masking engine, session identity (stable token <-> value), and the
+    # fuzz-tested StreamingUnmasker (0.8.0 -> maskflow.streaming) that the
+    # streaming deanonymizer is built on.
+    "maskflow-sdk>=0.8.0,<0.9",
+    # BaseCallbackHandler + Runnable. Pure-python, small; a real dependency,
+    # not a peer -- you install maskflow-langchain to use it *with* LangChain.
+    # Range spans the 0.3 line (still widely deployed) and 1.x.
+    "langchain-core>=0.3,<2",
+]
+
+[project.optional-dependencies]
+# save_deanonymizer_mapping / load_deanonymizer_mapping with .yaml paths.
+yaml = [
+    "pyyaml>=6.0",
+]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "hypothesis>=6.100",
+    "pyyaml>=6.0",
+]
+
+[tool.uv.sources]
+maskflow-sdk = { workspace = true }
+
+[tool.uv]
+package = true
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/maskflow_langchain"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+markers = [
+    "leak: guards against PII reaching logs, repr, callback state, or saved mappings",
+]

maskflow_langchain-0.1.0/src/maskflow_langchain/__init__.py

@@ -0,0 +1,47 @@
+"""MaskFlow for LangChain.
+
+A reversible PII anonymizer / deanonymizer pair that drops in for
+``langchain_experimental.data_anonymizer``'s Presidio anonymizer (Indian
+identifiers included), plus a leak-guard callback.
+
+    from maskflow_langchain import MaskflowReversibleAnonymizer
+
+    anonymizer = MaskflowReversibleAnonymizer()
+    chain = (
+        {"question": lambda x: anonymizer.anonymize(x["question"])}
+        | prompt
+        | llm
+        | StrOutputParser()
+        | anonymizer.deanonymizer     # streaming-aware Runnable
+    )
+"""
+
+from __future__ import annotations
+
+from .anonymizer import MaskflowAnonymizer, MaskflowReversibleAnonymizer
+from .base import AnonymizerBase, ReversibleAnonymizerBase
+from .callbacks import (
+    AsyncMaskflowLeakGuardCallback,
+    MaskflowLeakGuardCallback,
+    MaskflowPIILeakError,
+)
+from .matching import (
+    MappingDataType,
+    case_insensitive_matching_strategy,
+    exact_matching_strategy,
+)
+from .runnables import MaskflowDeanonymizer
+
+__all__ = [
+    "MaskflowAnonymizer",
+    "MaskflowReversibleAnonymizer",
+    "MaskflowDeanonymizer",
+    "MaskflowLeakGuardCallback",
+    "AsyncMaskflowLeakGuardCallback",
+    "MaskflowPIILeakError",
+    "AnonymizerBase",
+    "ReversibleAnonymizerBase",
+    "MappingDataType",
+    "exact_matching_strategy",
+    "case_insensitive_matching_strategy",
+]

maskflow_langchain-0.1.0/src/maskflow_langchain/_mapping.py

@@ -0,0 +1,52 @@
+"""Conversions between a ``maskflow.Session`` mapping and LangChain's
+``MappingDataType`` (``{entity_type: {anonymized: original}}``).
+
+The nested-by-entity-type shape is what ``PresidioReversibleAnonymizer``
+exposes as ``.deanonymizer_mapping`` / ``.anonymizer_mapping`` and what its
+``save``/``load`` round-trips, so a chain that inspects or persists the
+mapping keeps working after the import swap.
+"""
+
+from __future__ import annotations
+
+from maskflow import Session
+
+from .matching import MappingDataType
+
+
+def session_deanonymizer_mapping(session: Session) -> MappingDataType:
+    """``{ENTITY: {<token>: original}}`` for every reversible entry in the
+    session's current mapping."""
+    out: MappingDataType = {}
+    mapping = session.mapping
+    for token in mapping:
+        entry = mapping[token]
+        if not entry.reversible:
+            continue
+        out.setdefault(entry.entity_type.value, {})[token] = entry.original
+    return out
+
+
+def invert(mapping_data: MappingDataType) -> MappingDataType:
+    """``{ENTITY: {token: original}}`` -> ``{ENTITY: {original: token}}``."""
+    return {
+        entity_type: {original: anon for anon, original in inner.items()}
+        for entity_type, inner in mapping_data.items()
+    }
+
+
+def flat_token_pairs(mapping_data: MappingDataType) -> dict[str, str]:
+    """Flatten to ``{<token>: original}`` for whole-text or streaming unmask."""
+    pairs: dict[str, str] = {}
+    for inner in mapping_data.values():
+        pairs.update(inner)
+    return pairs
+
+
+def merge_into(dst: MappingDataType, src: MappingDataType) -> None:
+    """Merge ``src`` into ``dst`` in place; existing token->original entries
+    are not overwritten."""
+    for entity_type, inner in src.items():
+        target = dst.setdefault(entity_type, {})
+        for anon, original in inner.items():
+            target.setdefault(anon, original)