phase 5

Author: cpbeamer

README.md

@@ -177,14 +177,45 @@ NanoMask now includes packaged integration recipes under `examples/integrations/
 
 The sidecar, gateway, and LiteLLM recipes each include smoke-test commands plus operator notes for auth, TLS, streaming, and health checks. The OpenAI-compatible kit includes reusable client environment settings and streaming client samples.
 
+### SDK Wrappers
+
+Phase 5 adds lightweight SDK wrappers under `sdk/` so teams can point official OpenAI clients at NanoMask without hand-assembling `base_url` and entity headers every time.
+
+- `sdk/python`: installable `nanomask-openai` package, imported as `nanomask`
+- `sdk/node`: installable `@nanomask/openai` package
+- both packages default the client endpoint to `http://127.0.0.1:8081/v1`
+- both packages expose `verify()` helpers for CI and readiness checks
+
+Quick local install:
+
+```bash
+pip install ./sdk/python
+npm install openai ./sdk/node
+```
+
+See `sdk/README.md` plus each package README for examples.
+
+### Buyer Evaluation Kit
+
+Phase 5 also packages the buyer-facing evaluation assets:
+
+- `evaluation/README.md`: evaluation kit entry point
+- `evaluation/report-only-workflow.md`: first-pass rollout workflow
+- `evaluation/benchmark-card.md`: short proof artifact
+- `evaluation/pilot-runbook.md`: pilot onboarding flow
+- `evaluation/pilot-success-criteria.md`: scorecard template
+- `docs/commercial_offers.md`: pilot, sidecar, and gateway offer ladder
+- `site/index.html`: single-page landing site with positioning, quick start, and competitor framing
+
 ### Supported Features
 
 Core redaction and restore surface:
 - SSN redaction is always available for supported text and JSON bodies.
 - Entity masking and response unmasking can be driven from `--entity-file` / `NANOMASK_ENTITY_FILE` or per-request `X-ZPG-Entities`.
 - Fuzzy matching targets OCR-style name drift in text that has already been extracted into the HTTP payload.
-- Optional pattern-library flags expose built-in redactors for email, phone, credit card, IP address, and healthcare identifiers.
+- Optional pattern-library flags expose built-in redactors for email, phone, credit card, IP address, healthcare identifiers, IBANs, UK National Insurance numbers, passport values, and common international phone formats.
 - Optional schema-aware JSON mode exposes `KEEP`, `REDACT`, `SCAN`, and `HASH` actions through `--schema-file`, `--schema-default`, `--hash-key`, and `--hash-key-file`.
+- Optional AI control-plane features expose request guardrails (`--enable-guardrails`) and tenant-aware semantic caching (`--enable-semantic-cache`).
 - Schema-aware request redaction now streams JSON bodies with bounded parser memory instead of buffering the full request body first.
 
 Current limits:

docs/brand_kit.md

@@ -0,0 +1,27 @@
+# NanoMask Brand Kit
+
+## Positioning line
+
+NanoMask is the self-hosted privacy firewall for regulated AI traffic.
+
+## Voice
+
+- direct
+- technical
+- compliance-aware
+- operator-friendly
+
+## Visual system
+
+- primary ink: `#0d1b19`
+- primary accent: `#0f766e`
+- secondary accent: `#c2410c`
+- surface: `#fff9f0`
+- grid line: `rgba(13, 27, 25, 0.10)`
+
+## Logo assets
+
+- `site/assets/nanomask-mark.svg`
+- `site/assets/nanomask-wordmark.svg`
+
+Use the mark for square surfaces and the wordmark for docs, decks, and the landing page hero.

docs/commercial_offers.md

@@ -0,0 +1,24 @@
+# Commercial Offers
+
+NanoMask's commercial packaging should stay aligned to the regulated-AI wedge and the actual deployment journey.
+
+## Offer ladder
+
+| Offer | Best fit | Includes | Upgrade trigger |
+|---|---|---|---|
+| Pilot package | first regulated-AI evaluation | evaluation kit, security packet, report-only onboarding, weekly review cadence | buyer approves success criteria and wants active masking on production-shaped traffic |
+| Team sidecar deployment | one application team or bounded service group | sidecar patterns, SDK wrappers, starter schemas, support for rollout and tuning | multiple services need shared policy, audit, or centralized controls |
+| Enterprise gateway deployment | hospital, payer, claims platform, or shared AI platform team | centralized gateway topology, admin API/RBAC, audit evidence, semantic-cache controls, security review support | cross-team traffic consolidation or procurement of broader support/security commitments |
+
+## Packaging principles
+
+- sell the pilot around speed-to-proof, not feature sprawl
+- keep sidecar deployment as the low-friction expansion path
+- reserve gateway packaging for orgs that actually need shared controls and auditable central policy
+
+## Success metrics for expansion
+
+- seeded coverage target hit on the buyer's evaluation corpus
+- latency overhead remains inside agreed SLO
+- no compatibility regressions on required headers or streaming routes
+- operator team can own the deployment without founder-only intervention

docs/semantic_cache.md

@@ -0,0 +1,50 @@
+# Semantic Cache
+
+Semantic caching lets NanoMask skip duplicate upstream LLM calls after de-identification.
+
+## What is cached
+
+- request key inputs: HTTP method, URI, tenant identifier, transformed request body
+- cached value: eligible upstream response body
+- isolation: per-tenant using `--semantic-cache-tenant-header`
+
+## Enable it
+
+```bash
+zig build run -- \
+  --target-host api.openai.com \
+  --target-port 443 \
+  --target-tls \
+  --enable-semantic-cache \
+  --semantic-cache-ttl-ms 300000 \
+  --semantic-cache-max-entries 256 \
+  --semantic-cache-tenant-header X-NanoMask-Tenant
+```
+
+## Current behavior
+
+- duplicate transformed prompts can short-circuit the upstream request path
+- entries expire by TTL
+- cache capacity is bounded and old entries are evicted
+- response caching is limited to successful, identity-encoded, text or JSON responses
+
+## Metrics
+
+- `nanomask_semantic_cache_requests_total{result="hit"}`
+- `nanomask_semantic_cache_requests_total{result="miss"}`
+- `nanomask_semantic_cache_requests_total{result="eviction"}`
+- `nanomask_semantic_cache_entries`
+
+## Cost reduction framing
+
+Use semantic cache when the same de-identified prompts recur across:
+
+- repeated summarization templates
+- common support or claims-routing prompts
+- batch reprocessing jobs
+
+Estimated savings model:
+
+`monthly_savings = cache_hits * average_prompt_cost`
+
+The buyer conversation is not just privacy. It becomes privacy plus reduced API spend.

evaluation/README.md

@@ -0,0 +1,58 @@
+# NanoMask Evaluation Kit
+
+This folder is the repeatable buyer package for healthcare, claims, and regulated-AI evaluations.
+
+## What is included
+
+- Reference deployments:
+  `examples/integrations/sidecar/README.md`,
+  `examples/integrations/gateway/README.md`,
+  `starters/healthcare/deployments/`
+- Sample data packs:
+  `starters/healthcare/payloads/`,
+  `starters/healthcare/entities/`,
+  `starters/healthcare/schemas/`
+- Report-only evaluation workflow:
+  [report-only-workflow.md](report-only-workflow.md)
+- Benchmark card:
+  [benchmark-card.md](benchmark-card.md)
+- Compatibility summary:
+  [compatibility-summary.md](compatibility-summary.md)
+- Pilot scorecard and runbook:
+  [pilot-success-criteria.md](pilot-success-criteria.md),
+  [pilot-runbook.md](pilot-runbook.md)
+- Security packet:
+  `docs/security_packet.md`
+
+## Recommended evaluation flow
+
+1. Start in report-only mode with the healthcare starter assets.
+2. Run the compatibility suite and attach `compatibility/compatibility-matrix.json` to the evaluation packet.
+3. Switch one bounded workflow from report-only to active masking.
+4. Review the security packet and threat model with the buyer's security team.
+5. Lock pilot success criteria before production-shaped traffic is enabled.
+
+## Reproducible starter command
+
+```bash
+zig build run -- \
+  --listen-host 127.0.0.1 \
+  --target-host httpbin.org \
+  --target-port 80 \
+  --entity-file starters/healthcare/entities/patient-demographics.txt \
+  --schema-file starters/healthcare/schemas/patient-demographics.nmschema \
+  --schema-default KEEP \
+  --hash-key-file starters/healthcare/hash-key.example.txt \
+  --enable-email \
+  --enable-phone \
+  --enable-healthcare \
+  --report-only
+```
+
+Then send the included sample payload:
+
+```bash
+curl -X POST http://127.0.0.1:8081/post \
+  -H "Content-Type: application/json" \
+  --data-binary @starters/healthcare/payloads/patient-demographics.json
+```

evaluation/benchmark-card.md

@@ -0,0 +1,27 @@
+# Benchmark Card
+
+This card is the short proof artifact to hand to buyers during technical evaluation.
+
+## Core performance claims
+
+| Surface | Current proof point | How to reproduce |
+|---|---|---|
+| SSN redaction | 16+ GB/s single-core scan in ReleaseFast | `zig build bench-all` |
+| Exact entity masking | 260 MB/s | `zig build proof-report` |
+| OCR-tolerant fuzzy matching | 193 MB/s | `zig build proof-report` |
+| Compatibility coverage | 5/5 reference flows passing | `zig build compat-matrix -- compatibility/compatibility-matrix.json` |
+
+## Operational proof points
+
+- single static Zig binary with no runtime dependency chain
+- request and response header fidelity covered by the compatibility matrix
+- optional report-only mode for low-risk first deployment
+- Prometheus metrics for redaction, guardrail, and semantic-cache behavior
+
+## Evaluation note
+
+Use this card together with:
+
+- `compatibility/compatibility-matrix.json`
+- `docs/security_packet.md`
+- `evaluation/pilot-success-criteria.md`

evaluation/compatibility-summary.md

@@ -0,0 +1,21 @@
+# Compatibility Summary
+
+Current checked-in compatibility artifact: `compatibility/compatibility-matrix.json`
+
+## Summary
+
+- total reference flows: 5
+- passed: 5
+- failed: 0
+
+## Covered flows
+
+- OpenAI-compatible JSON: header fidelity, body mutation, response headers, path/query fidelity
+- Anthropic-style SSE: streaming fidelity plus request and response header checks
+- Azure OpenAI-style routes: path and query preservation
+- Generic REST JSON: ordinary API compatibility outside AI-specific routes
+- LiteLLM-style headers: proxy and vendor header preservation
+
+## Buyer takeaway
+
+NanoMask is positioned as a drop-in reverse proxy, not a custom integration project. This artifact is the proof packet for that claim.

evaluation/pilot-runbook.md

@@ -0,0 +1,35 @@
+# Pilot Runbook
+
+## Before kickoff
+
+- confirm target workflow, owner, and upstream API surface
+- choose deployment shape: sidecar or centralized gateway
+- choose evaluation corpus from `starters/healthcare/` or buyer-supplied sanitized payloads
+- agree on pilot success criteria and review cadence
+
+## Day 0 setup
+
+1. Validate the config with `--validate-config`.
+2. Start in report-only mode.
+3. Run the compatibility suite against the buyer's preferred API shape.
+4. Hand over the security packet and threat model.
+
+## Day 1 validation
+
+1. Replay seeded traffic and compare detections to the expected corpus.
+2. Review false positives and tighten schema or entity inputs.
+3. Enable active masking for one bounded route or integration.
+
+## Day 2+ operationalization
+
+1. Turn on audit logging and metrics scraping.
+2. Measure latency overhead and operational fit.
+3. If applicable, enable guardrails or semantic cache after privacy controls are accepted.
+
+## Closeout packet
+
+- benchmark card
+- compatibility summary
+- pilot scorecard against success criteria
+- security packet
+- recommended next commercial motion

evaluation/pilot-success-criteria.md

@@ -0,0 +1,13 @@
+# Pilot Success Criteria
+
+Agree on these metrics before pilot start so expansion is tied to evidence, not opinion.
+
+| Area | Target | Evidence |
+|---|---|---|
+| Detection coverage | 95%+ of seeded PII/PHI test values detected in agreed workflows | report-only logs, audit events, sample replay |
+| False positive rate | <2% on buyer-approved evaluation corpus | redaction review worksheet |
+| Latency overhead | within buyer-approved SLO for proxied routes | local benchmark plus pilot traffic measurement |
+| Deployment time | first environment live in 1 business day or less | onboarding runbook timestamps |
+| Compatibility | no auth, header, or SSE regressions in target workflows | compatibility suite plus pilot smoke tests |
+| Security review readiness | security packet accepted for initial review without blocker gaps | buyer security questionnaire and meeting notes |
+| Expansion trigger | sidecar or gateway rollout justified by measured coverage and operator fit | signed pilot closeout |

evaluation/report-only-workflow.md

@@ -0,0 +1,50 @@
+# Report-Only Workflow
+
+Use report-only mode to prove coverage and operational safety before payload mutation is enabled.
+
+## Objectives
+
+- measure what NanoMask would redact without changing traffic
+- baseline false positives on real prompts, notes, and claims payloads
+- show auditors that rollout starts with observation, not blind enforcement
+
+## Commands
+
+Start NanoMask with the healthcare starter pack:
+
+```bash
+zig build run -- \
+  --listen-host 127.0.0.1 \
+  --target-host httpbin.org \
+  --target-port 80 \
+  --entity-file starters/healthcare/entities/encounter-notes.txt \
+  --schema-file starters/healthcare/schemas/encounter-notes.nmschema \
+  --schema-default KEEP \
+  --hash-key-file starters/healthcare/hash-key.example.txt \
+  --enable-email \
+  --enable-phone \
+  --enable-healthcare \
+  --report-only \
+  --audit-log
+```
+
+Send representative traffic:
+
+```bash
+curl -X POST http://127.0.0.1:8081/post \
+  -H "Content-Type: application/json" \
+  --data-binary @starters/healthcare/payloads/encounter-note.json
+```
+
+## Evidence to capture
+
+- structured logs showing detected classes and request IDs
+- audit events for each detected pattern or entity match
+- `/metrics` snapshots before and after the sample run
+- operator notes on any expected-but-undetected values or false positives
+
+## Exit criteria
+
+- all sample payloads produce detections on the expected fields
+- no critical false positives block adjacent non-PII fields
+- operators understand what will change when enforcement is turned on