Social-determinant evidence contract¶

Run the synthetic SDOH and timeline example for section-scoped extraction and a labels/offsets/states-only output projection.

Start with the SDOH extraction guide for the registered determinants, cue tables and runnable synthetic examples.

openmed.clinical.sdoh_evidence provides a small, deterministic envelope for social-determinant extraction results. It preserves provenance and uncertainty boundaries so an SDOH signal cannot be mistaken for a diagnosis or an automated eligibility decision.

The contract is local-first and contains no model, corpus, credential, or network-loading path. The source document remains caller-owned. The envelope stores only controlled labels and source offsets; it never stores an excerpt, surface value, document identifier, or raw input text.

Required fields¶

from openmed.clinical.sdoh_evidence import SDOHEvidence

finding = SDOHEvidence(
    evidence_type="self_report",
    assertion="unknown",
    source_section="social_history",
    source_span=(12, 27),
    review_status="needs_review",
    determinant="housing_insecurity",
)

The required evidence type distinguishes a self report, proxy report, clinician observation, structured record, inference, unknown provenance, or refused provenance. source_span is a non-empty half-open character-offset pair. No source excerpt is accepted by the contract.

assertion must be one of present, absent, uncertain, unknown, or refused. unknown means the available evidence does not establish a state; refused means the source explicitly declined to provide one. Neither value may be treated as an affirmative finding. review_status is needs_review by default for records built without an explicit approval state.

assert finding.to_dict() == {
    "evidence_type": "self_report",
    "assertion": "unknown",
    "source_section": "social_history",
    "source_span": [12, 27],
    "review_status": "needs_review",
    "determinant": "housing_insecurity",
}

The serialized mapping is safe for an audit report: it has offsets and controlled labels, but no source value. to_json() uses sorted keys and fixed separators for stable output. SDOHEvidence.from_dict() ignores unknown extension keys, including accidental text, value, surface, and excerpt fields, and revalidates the required fields.

Safe reports and upstream findings¶

Use build_sdoh_evidence_report() to validate and deterministically order a batch. Reports carry the assistive-use disclaimer and serialize only validated records. evidence_from_sdoh_finding() adapts the existing SHAC-style finding shape while retaining only its safe category and span; a missing upstream status becomes explicit unknown.

This contract is an evidence and review boundary, not a clinical decision engine, compliance certification, diagnosis, or eligibility determination. Use synthetic or public data in tests and examples. Restricted SHAC data is not bundled or loaded by this module.

The synthetic SDOH counterfactual checks test whether non-causal demographic substitutions change finding labels or confidence while keeping the Social History evidence fixed.