Inference result contract

Ethnicolr returns name-pattern estimates under inference contract version 1.0. The contract separates whether a model produced a probability distribution from whether Ethnicolr chose to return a label. This distinction matters because a model can score a name while abstaining from a label when the evidence is ambiguous.

The contract is intended to be shared by Pranaam, Instate, Outkast, Naampy, and other name-inference packages. Each package retains its target-specific probability columns; the common columns make results interpretable and testable across packages.

If an input column uses a name reserved for estimator output, Ethnicolr preserves the input under input_<name>. It adds a numeric suffix when that name already exists.

Common columns

Column	Meaning
inference_contract_version	Version of this result contract.
estimate_type	Always name-pattern estimate.
target	Quantity estimated, such as race-ethnicity or country-origin.
input_scope	Name components used: first-name, last-name, or full-name.
predicted_label	Highest-probability returned label, or missing after abstention.
predicted_probability	Probability of predicted_label on a 0 to 1 scale.
scored	Whether the model produced a usable probability distribution.
script_supported	Whether the input script is supported.
abstained	Whether the package declined to return a label.
abstention_reason	Machine-readable reason for abstention.
model_id	Stable identifier for the model or dictionary.
model_version	Version of the package producing the estimate.
model_revision	Immutable revision of every artifact used for inference.
reference_population	Population represented by the training or lookup data.
calibration_status	Whether and how probability calibration was validated.
calibration_reference	Data population used to assess or fit calibration.
uncertainty_method	Method used for uncertainty output, when requested.
uncertainty_level	Requested interval, range, or coverage level.

Required invariants

• An unscored row must abstain.

• A row that does not abstain must be scored and have a predicted label and probability.

• An unsupported-script row cannot be scored.

• Target probabilities on a scored row must be finite, between zero and one, and sum to one, apart from documented rounding.

• predicted_probability must equal the target probability associated with predicted_label.

• model_revision must identify an immutable, complete artifact bundle. A mutable branch name such as main or latest is not a revision.

• A scored row may still abstain when a package applies an uncertainty rule. In that case the probability distribution remains available but predicted_label is missing.

Abstention reasons

The shared vocabulary is missing-name, no-letters, unsupported-script, out-of-vocabulary, out-of-dictionary, uncertain-score, and insufficient-evidence. Packages may add a reason only when none of these is accurate.

Uncertainty columns

Statistical interval columns use <probability_column>_lower and <probability_column>_upper. Monte Carlo dropout summaries use <probability_column>_mc_mean, _mc_std, _mc_lower, and _mc_upper because their empirical quantiles are not automatically confidence intervals.

Intended use

These outputs describe patterns associated with names in a stated reference population. They do not establish a person’s identity, ancestry, citizenship, religion, caste, race, or ethnicity. Do not use them for individual profiling or consequential decisions. Prefer aggregate analysis, disclose abstention and coverage, and report sensitivity to the reference population.