ContextZero

ContextZero sits between your application and external LLM providers, ensuring personal data never leaves the trust boundary.

PII Anonymization

Regex-based entity detection with configurable YAML rules — phones, emails, names, IDs.

Persona Engine

Template-based system prompt injection for consistent synthetic identities.

Ephemeral Encryption

AES-256 session keys in RAM only — never persisted, destroyed with the session.

Architecture

zero

Quick Start

from contextunity.zero import PrivacyMiddleware, ZeroConfig
from contextunity.zero.masking import MaskingConfig, EntityRule

# Define PII detection rules
masking_config = MaskingConfig(
    text_entity_rules=[
        EntityRule(entity_type="phone", prefix="PHN", pattern=r"\+380\d{9}"),
        EntityRule(entity_type="email", prefix="EML", pattern=r"[\w.]+@[\w.]+\.\w+"),
    ]
)

# Create middleware
config = ZeroConfig(enabled=True, persona_enabled=True)
middleware = PrivacyMiddleware.from_config(
    masking_config=masking_config,
    config=config,
)

# Wrap any async LLM call
result = await middleware.process(
    input_text="Call Oleksii at +380501234567",
    llm_call=my_llm_function,
)
# Input to LLM: "Call PHN_a1b2c3 at PHN_d4e5f6"
# Output to user: original names/phones restored

Key Components

Masking Pipeline (`masking/`)

PIIMasker — text + tabular PII detection and replacement
PIIUnmasker — restore original values from tokens
MappingStore — session-scoped token vault
PostMaskScanner — leak detection after masking
EphemeralAES256Backend — encryption (RAM-only keys)

ProxyService (`proxy.py`)

Central orchestrator supporting per-call rule merging.

LangGraph Pipeline (`graph.py`)

8-node privacy pipeline: detect → mask → check → persona → forward → receive → unmask → verify.

gRPC Service (6 RPCs)

RPC	Description
`Anonymize`	Mask PII in input text
`Deanonymize`	Restore original values
`ScanPII`	Scan text for PII entities (detection only)
`ProcessPrompt`	Full anonymize → LLM → deanonymize pipeline
`DestroySession`	Delete session keys from RAM
`GetStats`	Privacy metrics

Default Rules

Rules are loaded from masking/rules/defaults.yaml:

rules:
  - entity_type: "name"
    prefix: "PER"
    pattern: "(?i)[А-ЯІЇЄҐ][a-яіїєґ']+\\s+[А-ЯІЇЄҐ][a-яіїєґ']+"
  - entity_type: "phone"
    prefix: "PHN"
    pattern: "\\+380\\d{9}"
  - entity_type: "email"
    prefix: "EML"
    pattern: "[\\w.]+@[\\w.]+\\.\\w+"

Consumer projects can extend or override these rules via MaskingConfig.

Router Integration

Zero integrates with contextunity.router in two ways:

As LangChain Tools (Dispatcher Agent)

Tools are auto-registered when contextunity.zero is installed:

anonymize_text — Mask PII before LLM calls
deanonymize_text — Restore PII in responses
check_pii — Audit scan without modification
apply_persona — Inject persona instructions
destroy_privacy_session — Wipe encryption keys

Dual-mode: local package OR gRPC (set CU_ZERO_GRPC_HOST).

As LangGraph Subgraph

Registered as privacy_proxy builtin graph in Router dispatcher:

from contextunity.zero.graph import build_zero_graph
graph_registry.register("privacy_proxy", build_zero_graph, builtin=True)

Security Model

Ephemeral AES-256 — keys live only in RAM
Session-scoped — each session has isolated key material
PostMaskScanner — verifies no PII leaks post-anonymization
destroy_session() — irreversibly wipes encryption keys
Fail secure — if anonymization fails, the request is blocked