meddeid-core

meddeid-core provides the language-neutral contracts shared by the MedDeID suite: the document schema, 15-label data taxonomy, ordered 14-label model head, record normalization, and character-offset validation.

The suite documentation explains how this contract moves through MedDeID workflows. This repository is the authority for the schema, taxonomy, label order, and offset rules.

Installation

pip install meddeid-core

Install the optional Pydantic models with:

pip install 'meddeid-core[models]'

Python API

from meddeid_core import BERT_ENTITY_LABELS, normalize_record, validate_record

record = normalize_record(record)
validate_record(record)

MedDeID uses half-open [begin, end) offsets measured in Unicode code points. The only canonical top-level span container is spans.

The core package also owns the language-neutral meddeid.age-granularity.v1 JSON contract. load_age_granularity_policy() loads the packaged default, a custom JSON path, or a mapping and returns its validated calendar generalizer and deterministic identity. Language packages remain responsible only for parsing and localized rendering.

Benchmark subannotations are nested under their parent primary span. A non-empty subannotation list must be a complete, contiguous partition of the parent, and all offsets remain absolute document offsets:

{
  "begin": 0,
  "end": 11,
  "text": "Jan Peeters",
  "label": "Name:Patient",
  "category": "Name",
  "subtype": "Patient",
  "subannotations": [
    {"begin": 0, "end": 3, "text": "Jan", "category": "given"},
    {"begin": 3, "end": 4, "text": " ", "category": "formatting"},
    {"begin": 4, "end": 11, "text": "Peeters", "category": "family"}
  ]
}

Normalize canonical JSONL

The normalizer standardizes fields within records that use the canonical document_id, text, and spans containers. For example, it can convert start to begin:

meddeid-normalize-jsonl input.jsonl normalized.jsonl

Other top-level span containers, including annotations, entities, deid_spans, and items, are not part of the MedDeID schema and are rejected.

Taxonomy contract

The Python taxonomy is authoritative. The generated language-neutral contract is committed at contracts/taxonomy.json for JavaScript and non-Python consumers. After an intentional taxonomy change, regenerate it with:

python scripts/export_contracts.py

Language-specific behavior belongs in packages such as meddeid-language-nl; this package has no language rules or model runtime.

Development

pip install -e '.[dev]'
pytest

Licence

AGPL-3.0-only. See NOTICE for attribution information.