Technical Reference · v1.3 · Open Source
Technical Reference
Last updated: June 2026
Reference implementation artifacts for the NHID-Clinical v1.3 specification. These tools demonstrate that the specification can be implemented, replayed, and evaluated through deterministic trace artifacts and conformance testing.
Staged Integration — Stop at Any Rung
Integration is a ladder, not an all-or-nothing commitment. Tier 0 needs nothing but curl; Tier 2's cryptographic identity layer (NHID-Auth v2) is optional. Full walkthrough: v2-integration-guide.md.
See the Controls Run: The Front-Desk Walkthrough
Before the schemas and YAML below, here's what IDG‑01, PDX‑01, DBC‑01, and EIT‑01 actually enforce on a call, staged as a doctor's-office check-in desk. Run the conformant pass, then the three failure/escalation scenarios; hover any booth for its live rule_engine.config.
Illustrative — dialogue, mock config payloads, and artwork are for explanation only. Control names, field names, and the engine's deterministic priority order are taken directly from docs/nhid-clinical-technical-specification.md and src/nhid_cas.py.
Reference Artifacts
Canonical Event Schema
schema/nhid_trace_schema_v1.json
JSON Schema (Draft 2020‑12) for a single NHID‑Trace event. Includes schema annotations referencing disclosure, identity, and auditability considerations associated with TCPA, HIPAA, CA AB 489, and NY S7263.
Policy Engine
src/nhid_policy_engine_v1.py
Pure Python reference implementation of the four core controls plus the supplemental ATR-01 audit-trail control, and a bot‑to‑bot detection rule. No external dependencies; fully deterministic.
Conformance Test Suite
tests/nhid_conformance_test_suite_v1.yaml
18 machine‑readable test cases covering every pass/fail/edge scenario in the v1.3 spec. Vendors can use this YAML file to self‑validate their implementations.
Failure Injection Harness
tests/failure_injection_harness.py
pytest‑based test suite. Unit tests run with no server required. Integration tests validate a live FastAPI endpoint against malformed inputs and replay determinism.
Trace Generator & Example Traces
tests/trace_generator.py
CLI script that produces canonical NHID‑Clinical trace files. Ten pre‑generated failure traces are available in the /traces directory.
Payer-Initiated Call Guidance
docs/payer-initiated-calls.md
Policy-extension guide for the reversed call direction — a payer's AI agent calling a provider — covering how IDG‑01, PDX‑01, and DBC‑01 apply when NHID‑Clinical's controls were originally framed around inbound calls.
SIP Header Integration Feedback
docs/sip-header-integration-feedback.md
Standards-feedback position paper proposing an Identity-Disclosure SIP header convention for AI voice agents, referencing the IETF AgentID Protocol draft.
Policy Engine Playground experimental
Browser-based interactive demo of the disclosure policy rules. Paste or select a canonical event JSON, run the engine, and inspect the deterministic trace output. Identical input always produces identical output.
Open Playground →Quick Start
git clone https://github.com/NHID-Clinical/NHID-Clinical.git cd NHID-Clinical pip install -r requirements.txt python -m pytest tests/ -v python -m jsonschema schema/nhid_trace_schema_v1.json python tests/trace_generator.py --offline
Unit tests run without a server. Integration tests require a FastAPI instance at https://gfvq4swdtf.execute-api.us-east-1.amazonaws.com/prod and will be automatically skipped if the server is not reachable.
Hosted API
A public conformance endpoint is available for integration testing without self-hosting. Send any NHID-Clinical v1.3 event and receive a structured policy decision.
Endpoint
POST https://gfvq4swdtf.execute-api.us-east-1.amazonaws.com/prod/v1/conformance/check
Requests require an x-api-key header. The Governance Simulator uses a rate-limited demo key automatically. To obtain a key for your integration, contact contact@nhid-clinical.org.
curl -s -X POST \
https://gfvq4swdtf.execute-api.us-east-1.amazonaws.com/prod/v1/conformance/check \
-H "x-api-key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"session":{"turn_count":1,"escalation_path_available":true},"event":{...}}'
Returns: {"conformant": true/false, "action": "...", "violations": [...], "next_state": "...", "cas": {"score": ..., "tier": ...}}. See sample_request.json for a complete example.
Call Authorization Score (CAS) — Tier Thresholds
Every conformance and adapter response includes a cas block. The score is a 0.0–1.0 composite; the band it falls in determines the suggested action.
Vendor Quick-Start
POST your platform's native call payload — no NHID schema required. The adapter translates and evaluates automatically.
| Vendor | Endpoint | Auth | Status |
|---|---|---|---|
| VAPI | /v1/adapters/vapi/check |
None | ✅ Live |
| Twilio | /v1/adapters/twilio/check |
None | ✅ Live |
| Vonage | /v1/adapters/vonage/check |
None | ✅ Live |
| Retell AI | /v1/adapters/retell/check |
None | ✅ Live |
| Amazon Connect | /v1/adapters/connect/check |
None | ✅ Live |
Example — VAPI non-compliant call (bot requests PHI before disclosing identity):
curl -s -X POST \
https://gfvq4swdtf.execute-api.us-east-1.amazonaws.com/prod/v1/adapters/vapi/check \
-H "Content-Type: application/json" \
-d '{
"call": {"id": "call_demo", "startedAt": "2026-06-09T10:00:00Z"},
"messages": [
{"role": "bot", "message": "Hi, can I get the member ID and NPI?", "secondsFromStart": 0.3},
{"role": "user", "message": "NPI is 1234567890.", "secondsFromStart": 3.1},
{"role": "bot", "message": "Thanks. I am an automated system.", "secondsFromStart": 5.8}
]
}'
Returns "conformant": false with an IDG-01 violation. Move the disclosure to the first message and re-run — result flips to "conformant": true. See interoperability demo → for full examples.
Vendor Interoperability
The adapters/ directory contains format adapters that convert vendor-specific call transcripts to NHID-Clinical event traces. Available: VAPI, Twilio Voice Intelligence, Vonage, Retell AI, Amazon Connect Contact Lens. See the interoperability demo →
Important
These tools are experimental and not for production use. NHID‑Clinical does not issue certifications, conduct audits, or provide legal advice. Conformance testing is self‑administered. No external authority validates results. Adoption of these artifacts does not confer HIPAA compliance, TCPA compliance, or any regulatory approval.
Open for feedback
Questions or suggestions?
Start a pilot or reach out directly.