Technical Reference

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.

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.

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 failure and escalation scenarios; open any brass plaque for that control's rule_engine.config. ATR‑01 is the ledger on the right — it is not a checkpoint anyone walks through.

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 scene cannot drift from the engine. The room, the walking order and the artwork are staging — the verdicts are not.

What the Reference Implementation Actually Is

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.

Reference Artifacts

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.

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":{...}}'

from src.nhid_policy_engine_v1 import DelegationContext, evaluate_all
from src.trust_anchor import StaticTrustAnchorResolver

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

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}
    ]
  }'

Reference implementation

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

What ships

Determinism 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.

Getting started

Interoperability

This page shows how a real vendor's call transcript format can be mapped to an NHID-Clinical v1.3 event trace and evaluated for conformance. The adapter is open source — replace the sample input with real logs to test your own vendor.

How 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.

Case 1: Compliant Call

Agent discloses before requesting any operational data.

Input — Twilio 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"}
  ]
}

Output — NHID-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.

Case 2: Non-Compliant Call (Late Disclosure)

Agent requests data before identifying as automated — impersonation latency.

Input — Twilio 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"}
  ]
}

Output — NHID-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.

Run 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.

Other 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.

Implementation registry

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

Listed Implementations

How 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.

Going further: Part IV of the NHID-Clinical Playbook covers reference architecture, maturity labels, security boundaries and the implementation checklist.