Open proposal · v1.3 · Not an accredited standard or certification
Home/Developers

Developers · v1.3 · open source

Developers

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.

  • UpdatedJune 2026
  • EnginePure Python · deterministic
  • CodeApache-2.0
  • SpecificationCC BY 4.0
  • StatusPre-standardization draft
Get the repository ↗ Quick start

Pre‑standardization draft. The artifacts linked below are a reference implementation of the NHID‑Clinical v1.3 specification. They demonstrate that the specification can be implemented, replayed, and evaluated through deterministic trace artifacts and conformance testing. These tools are not a certification program, and there is no external certification authority. Conformance testing is self‑administered. All artifacts are open for community review and feedback.

Integration

Staged integration — stop at any rung

A ladder, not an all-or-nothing commitment.

01 / 09

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.

The integration ladder, and what each rung produces Three tiers, each stating the work, the capability gained and the evidence produced. Tier 0, paste a payload, takes about fifteen minutes: POST a transcript to the hosted demo endpoint or a vendor payload to an adapter route. It changes nothing in the call path and produces a PolicyDecision with reason codes per turn. Tier 1, wire into the call pipeline, takes about two hours: one HTTP call from your existing end-of-call handler, storing the score and alerting on non-conformance. It gives continuous monitoring and produces a stored, alertable decision and ATR-01 trace. Tier 2, cryptographic agent identity, takes about a day: add NHID-Auth v2 with NPI-bound agent passports and scoped, short-lived delegation. It gives verified authorization and produces a signed passport and verification record. Each rung is a stopping point; none requires the next. 0 Tier 0 · Paste a payload POST a transcript to the hosted demo endpoint, or a vendor payload to an adapter route. effort ~15 minutes · capability No call-path change · evidence PolicyDecision + reason codes per turn 1 Tier 1 · Wire into the call pipeline One HTTP call from your existing end-of-call handler; store the decision, alert on non-conformance. effort ~2 hours · capability Continuous monitoring · evidence Stored decision + ATR-01 trace, alertable 2 Tier 2 · Cryptographic agent identity Add NHID-Auth v2: NPI-bound agent passports with scoped, short-lived delegation. effort ~1 day · capability Verified authorization · evidence Signed passport + verification record

Reference Each rung is a stopping point. Nothing above Tier 0 is required to get a conformance verdict, and Tier 2 is optional. Full walkthrough: v2-integration-guide.md.

Evidence

See the controls run: the readout

What the engine returns on a call, turn by turn.

02 / 09

Before the schemas and YAML below, here is what the engine returns on a call, turn by turn. All five controls are evaluated on every turn and resolved by priority, so the screen shows five rows every time — there is no pipeline and no sequence of gates. Watch the IDG‑01 failure in particular: IDG‑01 returns DISCLOSE_IDENTITY while the composite is DENY_DATA, because PDX‑01 outranks it. Open any row for that control's rule_engine.config. ATR‑01 sits below the rule — it gates nothing, and is written on every turn whatever the other four returned.

Every action, reason code and violation in the scene is the output of src/nhid_policy_engine_v1.py :: evaluate_all, recorded by scripts/build_walkthrough_fixture.py replaying five real scenarios from tests/evaluation_corpus_v1.json; the same script's --check mode runs in CI, so the readout cannot drift from the engine. The chrome is drawn; the readout is read — --check fails the build if an action or a reason code is ever typed into the markup.

Architecture

What the reference implementation actually is

One path, drawn end to end, each part labelled by what it is today.

03 / 09

One path, drawn end to end, with each part labelled by what it actually is today. Three of the pieces a production deployment would need are not in this picture as built components, because they are not built — they are shown where they would go.

The NHID-Clinical reference implementation, end to end A vendor platform sends a call event to one of eight adapter modules, five of which are wired to hosted routes. The adapter normalises the event and passes it to the policy engine, which evaluates the five controls deterministically and returns a policy decision carrying a reason code and any violations. The decision is written to an append-only event store and emitted as a FHIR R4 AuditEvent. The conformance test suite replays recorded events through the same engine, which is what makes the published figures reproducible. Three further components a production deployment would require are shown separately as not built: durable key custody and rotation, an NPI-to-public-key registry, and multi-hop federation. Their absence is the difference between a reference implementation and deployable infrastructure. BUILT, AND COVERED BY THE SUITE Vendor platform Twilio, VAPI, Vonage, Retell, Amazon Connect Adapter 8 modules; 5 wired to hosted routes Policy engine Five controls, evaluated deterministically PolicyDecision Action, reason code, violations Event store Append-only, hash-chained FHIR AuditEvent R4, CI-validated Conformance test suite Replays recorded events through the same engine. This is what makes the published figures reproducible. NOT BUILT — WHERE THEY WOULD GO Key custody & rotation Documented production path Registry: NPI → public key Requires a neutral operator Multi-hop federation Open problem, not a shipped capability The gap between the two halves is the difference between a reference implementation and deployable infrastructure.
Standings: the built path is Implemented and its figures are Verified. Key custody is Conceptual; the registry and federation are Future. Each follows claim-boundaries.md.

Artifacts

Reference artifacts

Seven files, each one runnable or readable in the repository.

04 / 09
  • SCHEMA

    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.

  • ENGINE

    Policy Engine

    src/nhid_policy_engine_v1.py

    Pure Python reference implementation of the five canonical controls (IDG-01, PDX-01, DBC-01, EIT-01, ATR-01) plus the supplemental bot‑to‑bot rule. No external dependencies; fully deterministic.

  • SUITE

    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.

  • HARNESS

    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.

  • TRACES

    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.

  • GUIDE

    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

    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.

  • PLAY

    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.

Run

Quick start

Three ways in: run the suite locally, call the hosted routes with curl, or call them from Python. Synthetic data only.

05 / 09
Shell · from a clean checkoutpython 3.11+
git clone https://github.com/NHID-Clinical/NHID-Clinical.git
cd NHID-Clinical
pip install -r requirements.txt
python -m uvicorn app:app --port 8000 &    # integration tests need it
python -m pytest tests/ -q
Python · one turn through the enginesrc.nhid_policy_engine_v1
from src.nhid_policy_engine_v1 import evaluate_all
from src.synthetic_eval_loop import build_event, build_session

turn = {"turn_count": 0, "phi_accessed": ["member_id"],
        "speech_text": "Hi, this is Morgan from provider services. Can I get the member ID?"}
decision = evaluate_all(build_session(turn), build_event("demo-call", 0, turn))
decision.action.value, decision.reason_code   # ('DENY_DATA', 'PDX01_PHI_GATE_TRIGGERED')

The schema tests in tests/test_schema_conformance.py are part of the suite; there is no standalone validator to run. CI starts the API and requires 0 skipped.

Try the live API

One request, the engine’s answer

Synthetic data only, never PHI: the transcript is invented and the identifiers are not real. The response is not typed by hand. scripts/build_api_sample.py runs this exact request through the same handler the hosted route calls, and CI fails if the recorded answer drifts from the engine.

Request · synthetic transcriptPOST /v1/adapters/vapi/check
{
  "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
    }
  ]
}
Response · recorded from the handlerHTTP 200
{
  "conformant": false,
  "action": "DENY_DATA",
  "reason_code": "PDX01_PHI_GATE_TRIGGERED",
  "policy_version": "1.0.0",
  "violations": [
    {
      "rule_id": "IDG-01",
      "description": "AI agent has not disclosed non-human identity. Turn count: 3. ",
      "severity": "critical"
    },
    {
      "rule_id": "PDX-01",
      "description": "PHI exchange attempted before identity disclosure. Speech PHI signal: True. PHI fields: none.",
      "severity": "critical"
    }
  ],
  "next_state": "GATE_BLOCKED",
  "twiml_fallback": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Response>\n  <Gather input=\"speech\" speechTimeout=\"auto\" action=\"/voice/process\">\n    <Say>Before we continue, I need to confirm: I am an automated system, not a human representative. Can you confirm you understand?</Say>\n  </Gather>\n</Response>",
  "gather_speech": true,
  "evidence_completeness": {
    "present": 4,
    "expected": 4,
    "fraction": 1.0,
    "fields": [
      "event_id",
      "timestamp",
      "session_id",
      "event_type"
    ]
  },
  "human_review": {
    "queued": false,
    "trigger_reason": null,
    "queue_id": null
  },
  "vendor": "vapi"
}

DENY_DATA PDX01_PHI_GATE_TRIGGERED is the engine’s composite decision for this transcript.

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 and no external authority validates results. Adoption of these artifacts does not confer HIPAA or TCPA compliance.

Optional, opt-in

Delegated Authority (DLG-01)

Pass a delegation context and the verified scope constrains the data boundary.

06 / 09

Pass a DelegationContext to evaluate_all() and put the agent’s passport on the session; the engine verifies the delegation against a trust anchor you configure, and the verified scope constrains PDX-01. Pass nothing and the control is not evaluated at all, so existing integrations are unaffected. The normative text and the four claim boundaries live on the specification; the delegation flow is drawn on NHID-Auth.

Pythonsrc.nhid_policy_engine_v1
resolver = StaticTrustAnchorResolver({"1234567890": provider_public_key_b64})
session["agent_passport"] = passport          # or a list, for a chain
decision = evaluate_all(session, event, DelegationContext(resolver=resolver))
# decision.reason_code == "PDX01_SCOPE_NOT_AUTHORIZED" when out of scope

Implementation

Reference implementation

A working implementation of every control in the specification — so “conformant” means something you can run, not something you can claim.

07 / 09

AWhat ships

ENGINE

Policy engine

Pure Python with zero runtime dependencies. Evaluates each control against a session and event and returns a deterministic verdict.

MIDDLEWARE

TypeScript middleware

Request-path enforcement for Node services, mirroring the Python engine’s verdicts.

ADAPTERS

VAPI & Twilio adapters

Accept native call payloads from either platform and normalize them into the evaluation format — no transcript reformatting required.

AUTH

NHID-Auth v2

Ed25519 agent passports, provider-signed delegation, and offline verification. Details →

SCHEMA

Trace schema

The machine-readable audit envelope every event validates against, published as JSON Schema.

TOOLING

OpenAPI, Postman, PowerShell

An OpenAPI description, a Postman collection, and a PowerShell module for teams whose operations tooling lives there.

BDeterminism is the point

The engine contains no model calls and no scoring heuristics in the control path. The same session and event produce the same verdict on every machine, every run. That is what makes a conformance claim checkable by someone who does not trust you — including a regulator, an auditor, or a competitor.

It is also what lets the same control logic run in three places without drift: in the test suite, in the simulator, and in production enforcement.

Interoperability

Interoperability

A real vendor's call transcript format, mapped to an NHID-Clinical v1.3 event trace and evaluated for conformance.

08 / 09

The adapter is open source — replace the sample input with real logs to test your own vendor.

These examples use synthetic Twilio-format transcripts to demonstrate the mapping. No real call data is shown. The adapter source is at adapters/twilio_adapter.py.

AHow it works

Vendors who use Twilio produce call transcripts with text, timestamps, and speaker labels. The NHID-Clinical Twilio adapter reads that format and produces a structured event trace showing when disclosure happened, when data was first requested, and whether the call passes IDG-01.

The same pattern applies to other voice platforms — each needs its own adapter, but the output schema is identical. Five adapters are wired to live routes today: POST /v1/adapters/{twilio|vapi|vonage|retell|connect}/check. An ElevenLabs post-call adapter exists in the repository without a hosted route.

BCase 1: compliant call

Agent discloses before requesting any operational data.

InputTwilio transcript
{
  "call_sid": "CA123456789",
  "start_time": "2026-05-27T14:00:00Z",
  "transcript": [
    {"text": "Hello, this is an automated system calling on behalf of Dr. Smith's office.",
     "timestamp": 0.5, "speaker": "agent"},
    {"text": "Can I get the NPI number please?",
     "timestamp": 3.2, "speaker": "agent"},
    {"text": "Sure, it's 1234567890.",
     "timestamp": 5.8, "speaker": "human"}
  ]
}
OutputNHID-Clinical trace
{
  "trace_id": "twilio_CA123456789",
  "source_format": "twilio_transcript",
  "policy_version": "1.3",
  "events": [
    {"event_type": "DISCLOSURE",    "timestamp_offset_s": 0.5, "nhid_rule": "IDG-01"},
    {"event_type": "DATA_REQUEST",  "timestamp_offset_s": 3.2, "nhid_rule": "PDX-01"}
  ],
  "compliance": {
    "IDG-01": "PASS",
    "disclosure_timestamp_offset_s": 0.5,
    "first_data_request_offset_s": 3.2,
    "disclosure_made": true
  }
}

IDG-01: PASS disclosure at 0.5s, data request at 3.2s. Disclosure preceded data exchange.

CCase 2: non-compliant call (late disclosure)

Agent requests data before identifying as automated — impersonation latency.

InputTwilio transcript
{
  "call_sid": "CA999888777",
  "start_time": "2026-05-27T14:05:00Z",
  "transcript": [
    {"text": "Hi, can I get the member ID and NPI?",
     "timestamp": 0.3, "speaker": "agent"},
    {"text": "Sure — NPI is 1234567890.",
     "timestamp": 2.1, "speaker": "human"},
    {"text": "Thank you. By the way, I'm an automated system.",
     "timestamp": 4.0, "speaker": "agent"}
  ]
}
OutputNHID-Clinical trace
{
  "trace_id": "twilio_CA999888777",
  "source_format": "twilio_transcript",
  "policy_version": "1.3",
  "events": [
    {"event_type": "DATA_REQUEST",  "timestamp_offset_s": 2.1, "nhid_rule": "PDX-01"},
    {"event_type": "DISCLOSURE",    "timestamp_offset_s": 4.0, "nhid_rule": "IDG-01"}
  ],
  "compliance": {
    "IDG-01": "FAIL – disclosure occurred after data request (impersonation latency)",
    "disclosure_timestamp_offset_s": 4.0,
    "first_data_request_offset_s": 2.1,
    "disclosure_made": true
  }
}

IDG-01: FAIL data requested at 2.1s, disclosure not until 4.0s. 1.9 seconds of impersonation latency.

DRun it yourself

git clone https://github.com/NHID-Clinical/NHID-Clinical.git
cd NHID-Clinical
pip install -r requirements.txt
python -m pytest tests/ -v

Replace SAMPLE_TWILIO_COMPLIANT or SAMPLE_TWILIO_NONCOMPLIANT in the adapter with your own call transcript to test your vendor's output.

EOther vendor formats

The adapters/ directory contains format adapters that convert vendor-specific call transcripts to NHID-Clinical event traces. Available: Twilio Voice Intelligence, VAPI, Vonage, Retell AI, and Amazon Connect, each behind a hosted /v1/adapters/…/check route, plus an ElevenLabs post-call adapter in the repository.

Registry

Implementation registry

A self-attestation list of NHID-Clinical implementations. NHID-Clinical does not score, rate, certify, or verify the entries.

09 / 09

This is a self-attestation list, not a certification. NHID-Clinical does not certify, audit, or warrant any vendor's implementation. A listing means the vendor ran the public conformance test suite (CTS) against their own integration and chose to publish the result. NHID-Clinical assigns no score, grade, tier, or badge to any listed entry, and publishing an entry involves no review by this project. Verify a vendor's claims independently — by running the conformance suite against their integration yourself — before relying on any listing for a procurement decision.

AListed implementations

No implementations are listed yet. This is a self-attestation list, not a certification; the first entry will be the first vendor to run the suite against its own integration and open a pull request.

BHow to get listed

Run the conformance test suite against your integration, then complete the vendor trust questionnaire and open a pull request adding your entry to content/registry_entries.json. Each entry needs a vendor_id. Listing publishes what you attest to; it does not add any assessment by this project.

Vendor Trust Questionnaire → Quick start →

Open for feedback

Questions or suggestions?

Run a shadow evaluation, or reach out directly.

Read the evaluation guide →

Build on it

The code is Apache-2.0 and the specification is CC BY 4.0. Fork it, vendor it, or replace it with your own engine and test against the same suite.

Conformance suite →Prove your engine agrees. Interoperability →Working with existing telephony. Implementation Registry →Self-attested implementations. The trust stack →Where adapters, the engine, NHID-Auth v2 and the audit ledger sit. Contribute →Issues, discussions, pull requests.

NHID-Clinical is a voluntary open framework — not an accredited standard, certification, or regulatory requirement. Everything on this page is published under CC BY 4.0. Going further: Part IV of the NHID-Clinical Playbook covers reference architecture, maturity labels, security boundaries and the implementation checklist.