API REFERENCE/omnibias-core

omnibias.core.uncertainty

0.5.0rc1Release candidatePython >=3.10Apache-2.0

Coefficient recurrences, activation contracts, jet algebra, and verified arithmetic shared by the numerical backends.

import omnibias.core.uncertainty

Module contract & mathematical conventions

Uncertainty slabs (theory 04-02).

A slab [lo, hi] is the shared *shape* of three different guarantees. They are not interchangeable.

The band role uses a **finite** gap. That is the opposite of founding bias collapse (delta -> 0). Temperature collapse (beta -> inf, feasibility) does not appear. do not conflate the two.

Conformal coverage is marginal and assumes exchangeability. It is not a sound enclosure and must not be sealed as one. theorem_prover_verified is not asserted.

Shared formulas do not imply universal floating-point identity. Verify dtype, shape, derivative-order support, and the stated numerical assumptions for the path you use.

Module source ↗Source revision 9a2d73df0573Running reference examples →

CLASS

CalibrationReport

omnibias.core.uncertainty.CalibrationReportSource ↗

class CalibrationReport

Dataclass constructor fields; inherited fields, if any, are declared by the base class. A field(...) expression describes a default factory or field options, not a literal argument default.

The module contract describes the context for this operation. Its signature, explicit validation, return expressions, and implementation are recorded below.

Parameters

Name	Type & default	Contract
marginal_coveragedataclass field	floatRequired	See the operation contract and implementation below.
conditional_coveragedataclass field	Mapping[str, float]Required	See the operation contract and implementation below.
average_widthdataclass field	floatRequired	See the operation contract and implementation below.
width_coverage_curvedataclass field	tuple[tuple[float, float], ...]Required	See the operation contract and implementation below.
exchangeability_okdataclass field	boolDefault: True	See the operation contract and implementation below.
shift_detecteddataclass field	boolDefault: False	See the operation contract and implementation below.

Regression example · g3 adaptive

This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_g3_adaptive() -> None:
    report = adaptive_vs_fixed()
    assert report["g3_earned"] is True
    assert report["high_noise_fixed_cover"] < 0.85

python -m pytest packages/omnibias-core/tests/test_uncertainty.py -k test_g3_adaptive -q

Regression example · g4 shift

This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_g4_shift() -> None:
    report = shift_diagnostic()
    assert report.shift_detected is True
    assert report.exchangeability_ok is False
    assert report.average_width > 0.0

python -m pytest packages/omnibias-core/tests/test_uncertainty.py -k test_g4_shift -q

Fields & methods

marginal_coveragefield

marginal_coverage: float

Declared float field on CalibrationReport. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗

conditional_coveragefield

conditional_coverage: Mapping[str, float]

Declared Mapping[str, float] field on CalibrationReport. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗

average_widthfield

average_width: float

Declared float field on CalibrationReport. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

Regression example · g4 shift

This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_g4_shift() -> None:
    report = shift_diagnostic()
    assert report.shift_detected is True
    assert report.exchangeability_ok is False
    assert report.average_width > 0.0

python -m pytest packages/omnibias-core/tests/test_uncertainty.py -k test_g4_shift -q

View source ↗

width_coverage_curvefield

width_coverage_curve: tuple[tuple[float, float], ...]

Declared tuple[tuple[float, float], ...] field on CalibrationReport. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗

exchangeability_okfield

exchangeability_ok: bool = True

Declared bool field on CalibrationReport. Default expression: True.

Regression example · g4 shift

This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_g4_shift() -> None:
    report = shift_diagnostic()
    assert report.shift_detected is True
    assert report.exchangeability_ok is False
    assert report.average_width > 0.0

python -m pytest packages/omnibias-core/tests/test_uncertainty.py -k test_g4_shift -q

View source ↗

shift_detectedfield

shift_detected: bool = False

Declared bool field on CalibrationReport. Default expression: False.

Regression example · g4 shift

This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_g4_shift() -> None:
    report = shift_diagnostic()
    assert report.shift_detected is True
    assert report.exchangeability_ok is False
    assert report.average_width > 0.0

python -m pytest packages/omnibias-core/tests/test_uncertainty.py -k test_g4_shift -q

View source ↗

Read the implementation

class CalibrationReport:
    marginal_coverage: float
    conditional_coverage: Mapping[str, float]
    average_width: float
    width_coverage_curve: tuple[tuple[float, float], ...]
    exchangeability_ok: bool = True
    shift_detected: bool = False

CLASS

CombinedStatement

omnibias.core.uncertainty.CombinedStatementSource ↗

class CombinedStatement

Dataclass constructor fields; inherited fields, if any, are declared by the base class. A field(...) expression describes a default factory or field options, not a literal argument default.

Enclosure and conformal residual, recorded separately.

Parameters

Name	Type & default	Contract
enclosuredataclass field	UncertaintyIntervalRequired	See the operation contract and implementation below.
conformal_qdataclass field	floatRequired	See the operation contract and implementation below.
alphadataclass field	floatRequired	See the operation contract and implementation below.
combined_lodataclass field	floatRequired	See the operation contract and implementation below.
combined_hidataclass field	floatRequired	See the operation contract and implementation below.

Executed regression · g5 combine

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_g5_combine() -> None:
    box = UncertaintyInterval(2.31, 2.47, GuaranteeKind.SOUND_ENCLOSURE)
    stmt = combine_enclosure_with_conformal(box, 0.88, alpha=0.1)
    assert isinstance(stmt, CombinedStatement)
    assert stmt.combined_lo == pytest.approx(2.31 - 0.88)
    assert stmt.enclosure.kind is GuaranteeKind.SOUND_ENCLOSURE
    conf = UncertaintyInterval(-0.88, 0.88, GuaranteeKind.CONFORMAL, level=0.9)
    with pytest.raises(TypeError):
        combine_enclosure_with_conformal(conf, 0.88, alpha=0.1)
    with pytest.raises(ValueError, match="cannot be sealed"):
        refuse_conformal_seal(conf)

python -m pytest "packages/omnibias-core/tests/test_uncertainty.py::test_g5_combine" -q

Fields & methods

enclosurefield

enclosure: UncertaintyInterval

Declared UncertaintyInterval field on CombinedStatement. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗

conformal_qfield

conformal_q: float

Declared float field on CombinedStatement. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗

alphafield

alpha: float

Declared float field on CombinedStatement. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗

combined_lofield

combined_lo: float

Declared float field on CombinedStatement. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗

combined_hifield

combined_hi: float

Declared float field on CombinedStatement. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗

__post_init__method

__post_init__(self) -> None

See the class contract above and the exact method implementation below.

Returns: None

Validation & failure cases

• When self.enclosure.kind is not GuaranteeKind.SOUND_ENCLOSURE, raises TypeError('combine needs a sound enclosure').
• When self.enclosure.level is not None, raises TypeError('enclosure level must stay None').

Executed regression · g5 combine

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_g5_combine() -> None:
    box = UncertaintyInterval(2.31, 2.47, GuaranteeKind.SOUND_ENCLOSURE)
    stmt = combine_enclosure_with_conformal(box, 0.88, alpha=0.1)
    assert isinstance(stmt, CombinedStatement)
    assert stmt.combined_lo == pytest.approx(2.31 - 0.88)
    assert stmt.enclosure.kind is GuaranteeKind.SOUND_ENCLOSURE
    conf = UncertaintyInterval(-0.88, 0.88, GuaranteeKind.CONFORMAL, level=0.9)
    with pytest.raises(TypeError):
        combine_enclosure_with_conformal(conf, 0.88, alpha=0.1)
    with pytest.raises(ValueError, match="cannot be sealed"):
        refuse_conformal_seal(conf)

python -m pytest "packages/omnibias-core/tests/test_uncertainty.py::test_g5_combine" -q

Method implementation

    def __post_init__(self) -> None:
        if self.enclosure.kind is not GuaranteeKind.SOUND_ENCLOSURE:
            raise TypeError("combine needs a sound enclosure")
        if self.enclosure.level is not None:
            raise TypeError("enclosure level must stay None")

View source ↗

Read the implementation

class CombinedStatement:
    """Enclosure and conformal residual, recorded separately."""

    enclosure: UncertaintyInterval
    conformal_q: float
    alpha: float
    combined_lo: float
    combined_hi: float

    def __post_init__(self) -> None:
        if self.enclosure.kind is not GuaranteeKind.SOUND_ENCLOSURE:
            raise TypeError("combine needs a sound enclosure")
        if self.enclosure.level is not None:
            raise TypeError("enclosure level must stay None")

CONSTANT

DISCLAIMER

omnibias.core.uncertainty.DISCLAIMERSource ↗

DISCLAIMER = 'three guarantee kinds stay apart: sound enclosure, conformal, and model-based; conformal is not sealable'

This exported constant is defined by the expression above. Its exact value and annotation come from the pinned source; use it with the module contract.

Read the implementation

DISCLAIMER = (
    "three guarantee kinds stay apart: sound enclosure, conformal, "
    "and model-based; conformal is not sealable"
)

CLASS

GuaranteeKind

omnibias.core.uncertainty.GuaranteeKindSource ↗

class GuaranteeKind(str, Enum)

The module contract describes the context for this operation. Its signature, explicit validation, return expressions, and implementation are recorded below.

Regression example · g2 add raises

This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_g2_add_raises() -> None:
    sound = UncertaintyInterval(0.0, 1.0, GuaranteeKind.SOUND_ENCLOSURE)
    conf = UncertaintyInterval(0.0, 1.0, GuaranteeKind.CONFORMAL, level=0.9)
    with pytest.raises(TypeError, match="combine"):
        _ = sound + conf

python -m pytest packages/omnibias-core/tests/test_uncertainty.py -k test_g2_add_raises -q

Regression example · g5 combine

This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_g5_combine() -> None:
    box = UncertaintyInterval(2.31, 2.47, GuaranteeKind.SOUND_ENCLOSURE)
    stmt = combine_enclosure_with_conformal(box, 0.88, alpha=0.1)
    assert isinstance(stmt, CombinedStatement)
    assert stmt.combined_lo == pytest.approx(2.31 - 0.88)
    assert stmt.enclosure.kind is GuaranteeKind.SOUND_ENCLOSURE
    conf = UncertaintyInterval(-0.88, 0.88, GuaranteeKind.CONFORMAL, level=0.9)
    with pytest.raises(TypeError):
        combine_enclosure_with_conformal(conf, 0.88, alpha=0.1)
    with pytest.raises(ValueError, match="cannot be sealed"):
        refuse_conformal_seal(conf)

python -m pytest packages/omnibias-core/tests/test_uncertainty.py -k test_g5_combine -q

Read the implementation

class GuaranteeKind(str, Enum):
    SOUND_ENCLOSURE = "sound_enclosure"
    CONFORMAL = "conformal"
    MODEL_BASED = "model_based"

CLASS

UncertaintyInterval

omnibias.core.uncertainty.UncertaintyIntervalSource ↗

class UncertaintyInterval

Dataclass constructor fields; inherited fields, if any, are declared by the base class. A field(...) expression describes a default factory or field options, not a literal argument default.

The module contract describes the context for this operation. Its signature, explicit validation, return expressions, and implementation are recorded below.

Parameters

Name	Type & default	Contract
lodataclass field	floatRequired	See the operation contract and implementation below.
hidataclass field	floatRequired	See the operation contract and implementation below.
kinddataclass field	GuaranteeKindRequired	See the operation contract and implementation below.
leveldataclass field	float | NoneDefault: None	See the operation contract and implementation below.
assumptionsdataclass field	tuple[str, ...]Default: ()	See the operation contract and implementation below.

Executed regression · g2 add raises

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_g2_add_raises() -> None:
    sound = UncertaintyInterval(0.0, 1.0, GuaranteeKind.SOUND_ENCLOSURE)
    conf = UncertaintyInterval(0.0, 1.0, GuaranteeKind.CONFORMAL, level=0.9)
    with pytest.raises(TypeError, match="combine"):
        _ = sound + conf

python -m pytest "packages/omnibias-core/tests/test_uncertainty.py::test_g2_add_raises" -q

Regression example · g5 combine

This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_g5_combine() -> None:
    box = UncertaintyInterval(2.31, 2.47, GuaranteeKind.SOUND_ENCLOSURE)
    stmt = combine_enclosure_with_conformal(box, 0.88, alpha=0.1)
    assert isinstance(stmt, CombinedStatement)
    assert stmt.combined_lo == pytest.approx(2.31 - 0.88)
    assert stmt.enclosure.kind is GuaranteeKind.SOUND_ENCLOSURE
    conf = UncertaintyInterval(-0.88, 0.88, GuaranteeKind.CONFORMAL, level=0.9)
    with pytest.raises(TypeError):
        combine_enclosure_with_conformal(conf, 0.88, alpha=0.1)
    with pytest.raises(ValueError, match="cannot be sealed"):
        refuse_conformal_seal(conf)

python -m pytest packages/omnibias-core/tests/test_uncertainty.py -k test_g5_combine -q

Fields & methods

lofield

lo: float

Declared float field on UncertaintyInterval. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗

hifield

hi: float

Declared float field on UncertaintyInterval. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗

kindfield

kind: GuaranteeKind

Declared GuaranteeKind field on UncertaintyInterval. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗

levelfield

level: float | None = None

Declared float | None field on UncertaintyInterval. Default expression: None.

View source ↗

assumptionsfield

assumptions: tuple[str, ...] = ()

Declared tuple[str, ...] field on UncertaintyInterval. Default expression: ().

View source ↗

__post_init__method

__post_init__(self) -> None

See the class contract above and the exact method implementation below.

Returns: None

Validation & failure cases

• When float(self.lo) > float(self.hi), raises ValueError('lo must be <= hi').
• When self.level is not None, raises ValueError('sound enclosure has level None').
• When self.level is None, raises ValueError(f'{self.kind.value} requires a probability level').

Executed regression · g2 add raises

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_g2_add_raises() -> None:
    sound = UncertaintyInterval(0.0, 1.0, GuaranteeKind.SOUND_ENCLOSURE)
    conf = UncertaintyInterval(0.0, 1.0, GuaranteeKind.CONFORMAL, level=0.9)
    with pytest.raises(TypeError, match="combine"):
        _ = sound + conf

python -m pytest "packages/omnibias-core/tests/test_uncertainty.py::test_g2_add_raises" -q

Method implementation

    def __post_init__(self) -> None:
        if float(self.lo) > float(self.hi):
            raise ValueError("lo must be <= hi")
        if self.kind is GuaranteeKind.SOUND_ENCLOSURE:
            if self.level is not None:
                raise ValueError("sound enclosure has level None")
        elif self.level is None:
            raise ValueError(f"{self.kind.value} requires a probability level")

View source ↗

__add__method

__add__(self, other: object) -> UncertaintyInterval

See the class contract above and the exact method implementation below.

Parameters

Name	Type & default	Contract
otherpositional-or-keyword	objectRequired	See the operation contract and implementation below.

Returns: UncertaintyInterval

Executed regression · g2 add raises

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_g2_add_raises() -> None:
    sound = UncertaintyInterval(0.0, 1.0, GuaranteeKind.SOUND_ENCLOSURE)
    conf = UncertaintyInterval(0.0, 1.0, GuaranteeKind.CONFORMAL, level=0.9)
    with pytest.raises(TypeError, match="combine"):
        _ = sound + conf

python -m pytest "packages/omnibias-core/tests/test_uncertainty.py::test_g2_add_raises" -q

Method implementation

    def __add__(self, other: object) -> UncertaintyInterval:
        raise TypeError(
            "Intervals of different guarantee kinds do not combine by "
            "arithmetic. Use combine_enclosure_with_conformal."
        )

View source ↗

__radd__method

__radd__(self, other: object) -> UncertaintyInterval

See the class contract above and the exact method implementation below.

Parameters

Name	Type & default	Contract
otherpositional-or-keyword	objectRequired	See the operation contract and implementation below.

Returns: UncertaintyInterval

Method implementation

    def __radd__(self, other: object) -> UncertaintyInterval:
        return self.__add__(other)

View source ↗

Read the implementation

class UncertaintyInterval:
    lo: float
    hi: float
    kind: GuaranteeKind
    level: float | None = None
    assumptions: tuple[str, ...] = ()

    def __post_init__(self) -> None:
        if float(self.lo) > float(self.hi):
            raise ValueError("lo must be <= hi")
        if self.kind is GuaranteeKind.SOUND_ENCLOSURE:
            if self.level is not None:
                raise ValueError("sound enclosure has level None")
        elif self.level is None:
            raise ValueError(f"{self.kind.value} requires a probability level")

    def __add__(self, other: object) -> UncertaintyInterval:
        raise TypeError(
            "Intervals of different guarantee kinds do not combine by "
            "arithmetic. Use combine_enclosure_with_conformal."
        )

    def __radd__(self, other: object) -> UncertaintyInterval:
        return self.__add__(other)

CONSTANT

WORKED_RESIDUALS

omnibias.core.uncertainty.WORKED_RESIDUALSSource ↗

WORKED_RESIDUALS: tuple[float, ...] = (0.02, 0.05, 0.07, 0.09, 0.11, 0.14, 0.16, 0.19, 0.22, 0.25, 0.28, 0.33, 0.38, 0.44, 0.51, 0.6, 0.72, 0.88, 1.15)

This exported constant is defined by the expression above. Its exact value and annotation come from the pinned source; use it with the module contract.

Read the implementation

WORKED_RESIDUALS: tuple[float, ...] = (
    0.02,
    0.05,
    0.07,
    0.09,
    0.11,
    0.14,
    0.16,
    0.19,
    0.22,
    0.25,
    0.28,
    0.33,
    0.38,
    0.44,
    0.51,
    0.60,
    0.72,
    0.88,
    1.15,
)

FUNCTION

adaptive_conformal

omnibias.core.uncertainty.adaptive_conformalSource ↗

adaptive_conformal(residuals: Sequence[float], widths: Sequence[float], *, alpha: float) -> float

Quantile of the normalized score |y - f| / w(x).

Parameters

Name	Type & default	Contract
residualspositional-or-keyword	Sequence[float]Required	See the operation contract and implementation below.
widthspositional-or-keyword	Sequence[float]Required	See the operation contract and implementation below.
alphakeyword-only	floatRequired	See the operation contract and implementation below.

Returnsfloat

Explicit validation & failure cases

• When len(residuals) != len(widths), raises ValueError('residuals and widths must have the same length').
• When w <= 0.0, raises ValueError('widths must be positive').

These are explicit source guards. Backend operations may also raise for invalid shapes, dtypes, or unsupported devices.

Executed regression · g3 adaptive

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_g3_adaptive() -> None:
    report = adaptive_vs_fixed()
    assert report["g3_earned"] is True
    assert report["high_noise_fixed_cover"] < 0.85

python -m pytest "packages/omnibias-core/tests/test_uncertainty.py::test_g3_adaptive" -q

Read the implementation

def adaptive_conformal(
    residuals: Sequence[float],
    widths: Sequence[float],
    *,
    alpha: float,
) -> float:
    """Quantile of the normalized score ``|y - f| / w(x)``."""
    if len(residuals) != len(widths):
        raise ValueError("residuals and widths must have the same length")
    norms: list[float] = []
    for res, width in zip(residuals, widths, strict=True):
        w = float(width)
        if w <= 0.0:
            raise ValueError("widths must be positive")
        norms.append(abs(float(res)) / w)
    return split_conformal(norms, alpha=alpha)

Related APIsomnibias.core.uncertainty.split_conformal↗

FUNCTION

adaptive_vs_fixed

omnibias.core.uncertainty.adaptive_vs_fixedSource ↗

adaptive_vs_fixed(*, seeds: int=5, n_cal: int=4000, n_test: int=5000, alpha: float=0.1) -> dict[str, object]

G3: heteroscedastic mixture; adaptive conditional coverage wins.

Parameters

Name	Type & default	Contract
seedskeyword-only	intDefault: 5	See the operation contract and implementation below.
n_calkeyword-only	intDefault: 4000	See the operation contract and implementation below.
n_testkeyword-only	intDefault: 5000	See the operation contract and implementation below.
alphakeyword-only	floatDefault: 0.1	See the operation contract and implementation below.

Returnsdict[str, object]

Executed regression · g3 adaptive

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_g3_adaptive() -> None:
    report = adaptive_vs_fixed()
    assert report["g3_earned"] is True
    assert report["high_noise_fixed_cover"] < 0.85

python -m pytest "packages/omnibias-core/tests/test_uncertainty.py::test_g3_adaptive" -q

Read the implementation

def adaptive_vs_fixed(
    *,
    seeds: int = 5,
    n_cal: int = 4000,
    n_test: int = 5000,
    alpha: float = 0.1,
) -> dict[str, object]:
    """G3: heteroscedastic mixture; adaptive conditional coverage wins."""
    fixed_devs: list[float] = []
    adapt_devs: list[float] = []
    fixed_widths: list[float] = []
    adapt_widths: list[float] = []
    for seed in range(seeds):
        rng = random.Random(1000 + seed)
        cal_r: list[float] = []
        cal_w: list[float] = []
        for _ in range(n_cal):
            low = rng.random() < 0.5
            scale = 0.1 if low else 1.0
            cal_r.append(rng.gauss(0.0, scale))
            cal_w.append(scale)
        q_fix = split_conformal(cal_r, alpha=alpha)
        q_ad = adaptive_conformal(cal_r, cal_w, alpha=alpha)
        low_fix: list[float] = []
        high_fix: list[float] = []
        low_ad: list[float] = []
        high_ad: list[float] = []
        w_fix = 0.0
        w_ad = 0.0
        for _ in range(n_test):
            low = rng.random() < 0.5
            scale = 0.1 if low else 1.0
            res = rng.gauss(0.0, scale)
            w_fix += 2.0 * q_fix
            w_ad += 2.0 * q_ad * scale
            if low:
                low_fix.append(res)
                low_ad.append(res / scale)
            else:
                high_fix.append(res)
                high_ad.append(res / scale)
        fix_low = _cover_rate(low_fix, q_fix)
        fix_high = _cover_rate(high_fix, q_fix)
        ad_low = _cover_rate(low_ad, q_ad)
        ad_high = _cover_rate(high_ad, q_ad)
        nom = 1.0 - alpha
        fixed_devs.append(max(abs(fix_low - nom), abs(fix_high - nom)))
        adapt_devs.append(max(abs(ad_low - nom), abs(ad_high - nom)))
        fixed_widths.append(w_fix / float(n_test))
        adapt_widths.append(w_ad / float(n_test))
    return {
        "fixed_max_dev": max(fixed_devs),
        "adaptive_max_dev": max(adapt_devs),
        "fixed_mean_dev": sum(fixed_devs) / float(seeds),
        "adaptive_mean_dev": sum(adapt_devs) / float(seeds),
        "fixed_width": sum(fixed_widths) / float(seeds),
        "adaptive_width": sum(adapt_widths) / float(seeds),
        "g3_earned": (
            (sum(adapt_devs) / float(seeds)) <= 0.03
            and max(adapt_devs) <= 0.045
            and max(fixed_devs) >= 0.08
            and (sum(adapt_widths) / float(seeds)) <= (sum(fixed_widths) / float(seeds))
        ),
        "population_fixed_q": 1.2815515655446004,
        "population_adaptive_z": 1.6448536269514722,
        "low_noise_fixed_cover": _abs_normal_cdf(1.2815515655446004, 0.1),
        "high_noise_fixed_cover": _abs_normal_cdf(1.2815515655446004, 1.0),
    }

Related APIsomnibias.core.uncertainty.adaptive_conformal↗omnibias.core.uncertainty.split_conformal↗

FUNCTION

calibration_report

omnibias.core.uncertainty.calibration_reportSource ↗

calibration_report(residuals: Sequence[float], *, q: float, strata: Mapping[str, Sequence[float]] | None=None, alphas: Sequence[float]=(0.2, 0.1, 0.05), exchangeability_ok: bool=True, shift_detected: bool=False) -> CalibrationReport

The module contract describes the context for this operation. Its signature, explicit validation, return expressions, and implementation are recorded below.

Parameters

Name	Type & default	Contract
residualspositional-or-keyword	Sequence[float]Required	See the operation contract and implementation below.
qkeyword-only	floatRequired	See the operation contract and implementation below.
stratakeyword-only	Mapping[str, Sequence[float]] | NoneDefault: None	See the operation contract and implementation below.
alphaskeyword-only	Sequence[float]Default: (0.2, 0.1, 0.05)	See the operation contract and implementation below.
exchangeability_okkeyword-only	boolDefault: True	See the operation contract and implementation below.
shift_detectedkeyword-only	boolDefault: False	See the operation contract and implementation below.

ReturnsCalibrationReport

Executed regression · g4 shift

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_g4_shift() -> None:
    report = shift_diagnostic()
    assert report.shift_detected is True
    assert report.exchangeability_ok is False
    assert report.average_width > 0.0

python -m pytest "packages/omnibias-core/tests/test_uncertainty.py::test_g4_shift" -q

Read the implementation

def calibration_report(
    residuals: Sequence[float],
    *,
    q: float,
    strata: Mapping[str, Sequence[float]] | None = None,
    alphas: Sequence[float] = (0.2, 0.1, 0.05),
    exchangeability_ok: bool = True,
    shift_detected: bool = False,
) -> CalibrationReport:
    half = 2.0 * abs(float(q))
    cond: dict[str, float] = {}
    if strata is not None:
        cond = {name: _cover_rate(vals, q) for name, vals in strata.items()}
    curve = tuple(
        (float(a), _cover_rate(residuals, split_conformal(residuals, alpha=float(a))))
        for a in alphas
    )
    return CalibrationReport(
        marginal_coverage=_cover_rate(residuals, q),
        conditional_coverage=cond,
        average_width=half,
        width_coverage_curve=curve,
        exchangeability_ok=exchangeability_ok,
        shift_detected=shift_detected,
    )

Related APIsomnibias.core.uncertainty.CalibrationReport↗omnibias.core.uncertainty.split_conformal↗

FUNCTION

combine_enclosure_with_conformal

omnibias.core.uncertainty.combine_enclosure_with_conformalSource ↗

combine_enclosure_with_conformal(enclosure: UncertaintyInterval, q: float, *, alpha: float) -> CombinedStatement

The module contract describes the context for this operation. Its signature, explicit validation, return expressions, and implementation are recorded below.

Parameters

Name	Type & default	Contract
enclosurepositional-or-keyword	UncertaintyIntervalRequired	See the operation contract and implementation below.
qpositional-or-keyword	floatRequired	See the operation contract and implementation below.
alphakeyword-only	floatRequired	See the operation contract and implementation below.

ReturnsCombinedStatement

Explicit validation & failure cases

• When enclosure.kind is not GuaranteeKind.SOUND_ENCLOSURE, raises TypeError('combine_enclosure_with_conformal needs a sound enclosure').

These are explicit source guards. Backend operations may also raise for invalid shapes, dtypes, or unsupported devices.

Executed regression · g5 combine

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_g5_combine() -> None:
    box = UncertaintyInterval(2.31, 2.47, GuaranteeKind.SOUND_ENCLOSURE)
    stmt = combine_enclosure_with_conformal(box, 0.88, alpha=0.1)
    assert isinstance(stmt, CombinedStatement)
    assert stmt.combined_lo == pytest.approx(2.31 - 0.88)
    assert stmt.enclosure.kind is GuaranteeKind.SOUND_ENCLOSURE
    conf = UncertaintyInterval(-0.88, 0.88, GuaranteeKind.CONFORMAL, level=0.9)
    with pytest.raises(TypeError):
        combine_enclosure_with_conformal(conf, 0.88, alpha=0.1)
    with pytest.raises(ValueError, match="cannot be sealed"):
        refuse_conformal_seal(conf)

python -m pytest "packages/omnibias-core/tests/test_uncertainty.py::test_g5_combine" -q

Read the implementation

def combine_enclosure_with_conformal(
    enclosure: UncertaintyInterval,
    q: float,
    *,
    alpha: float,
) -> CombinedStatement:
    if enclosure.kind is not GuaranteeKind.SOUND_ENCLOSURE:
        raise TypeError("combine_enclosure_with_conformal needs a sound enclosure")
    half = abs(float(q))
    return CombinedStatement(
        enclosure=enclosure,
        conformal_q=half,
        alpha=float(alpha),
        combined_lo=enclosure.lo - half,
        combined_hi=enclosure.hi + half,
    )

Related APIsomnibias.core.uncertainty.CombinedStatement↗

FUNCTION

conformal_index

omnibias.core.uncertainty.conformal_indexSource ↗

conformal_index(n: int, alpha: float) -> int

1-based index ceil((n + 1)(1 - alpha)). May equal n + 1.

Parameters

Name	Type & default	Contract
npositional-or-keyword	intRequired	See the operation contract and implementation below.
alphapositional-or-keyword	floatRequired	See the operation contract and implementation below.

Returnsint

Explicit validation & failure cases

• When n < 1, raises ValueError(f'n must be >= 1, got {n}').
• When not 0.0 < float(alpha) < 1.0, raises ValueError(f'alpha must be in (0, 1), got {alpha}').

These are explicit source guards. Backend operations may also raise for invalid shapes, dtypes, or unsupported devices.

Executed regression · g3 adaptive

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_g3_adaptive() -> None:
    report = adaptive_vs_fixed()
    assert report["g3_earned"] is True
    assert report["high_noise_fixed_cover"] < 0.85

python -m pytest "packages/omnibias-core/tests/test_uncertainty.py::test_g3_adaptive" -q

Regression example · g1 worked quantile

This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_g1_worked_quantile() -> None:
    ex = worked_example()
    assert ex["q"] == 0.88
    assert conformal_index(19, 0.1) == 18
    naive = int(math.ceil(20 * 0.9))
    assert naive == 18

python -m pytest packages/omnibias-core/tests/test_uncertainty.py -k test_g1_worked_quantile -q

Read the implementation

def conformal_index(n: int, alpha: float) -> int:
    """1-based index ``ceil((n + 1)(1 - alpha))``. May equal ``n + 1``."""
    if n < 1:
        raise ValueError(f"n must be >= 1, got {n}")
    if not 0.0 < float(alpha) < 1.0:
        raise ValueError(f"alpha must be in (0, 1), got {alpha}")
    return int(math.ceil((n + 1) * (1.0 - float(alpha))))

FUNCTION

honesty_payload

omnibias.core.uncertainty.honesty_payloadSource ↗

honesty_payload() -> dict[str, bool]

The module contract describes the context for this operation. Its signature, explicit validation, return expressions, and implementation are recorded below.

Returnsdict[str, bool]

Executed regression · honesty

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_honesty() -> None:
    payload = honesty_payload()
    assert payload["registers_blended"] is False
    assert payload["conformal_sealed"] is False
    assert payload["theorem_prover_verified"] is False

python -m pytest "packages/omnibias-core/tests/test_uncertainty.py::test_honesty" -q

Read the implementation

def honesty_payload() -> dict[str, bool]:
    return {
        "registers_blended": False,
        "conformal_sealed": False,
        "conditional_coverage_guaranteed": False,
        "exchangeability_assumed": True,
        "stretch_claim": False,
        "theorem_prover_verified": False,
    }

FUNCTION

refuse_conformal_seal

omnibias.core.uncertainty.refuse_conformal_sealSource ↗

refuse_conformal_seal(interval: UncertaintyInterval) -> None

Certificate v1 seals enclosures, not statistical intervals.

Parameters

Name	Type & default	Contract
intervalpositional-or-keyword	UncertaintyIntervalRequired	See the operation contract and implementation below.

ReturnsNone

Explicit validation & failure cases

• When interval.kind is GuaranteeKind.CONFORMAL, raises ValueError('conformal intervals cannot be sealed into certificate v1').
• When interval.kind is GuaranteeKind.MODEL_BASED, raises ValueError('model-based intervals cannot be sealed into certificate v1').

These are explicit source guards. Backend operations may also raise for invalid shapes, dtypes, or unsupported devices.

Executed regression · g5 combine

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_g5_combine() -> None:
    box = UncertaintyInterval(2.31, 2.47, GuaranteeKind.SOUND_ENCLOSURE)
    stmt = combine_enclosure_with_conformal(box, 0.88, alpha=0.1)
    assert isinstance(stmt, CombinedStatement)
    assert stmt.combined_lo == pytest.approx(2.31 - 0.88)
    assert stmt.enclosure.kind is GuaranteeKind.SOUND_ENCLOSURE
    conf = UncertaintyInterval(-0.88, 0.88, GuaranteeKind.CONFORMAL, level=0.9)
    with pytest.raises(TypeError):
        combine_enclosure_with_conformal(conf, 0.88, alpha=0.1)
    with pytest.raises(ValueError, match="cannot be sealed"):
        refuse_conformal_seal(conf)

python -m pytest "packages/omnibias-core/tests/test_uncertainty.py::test_g5_combine" -q

Read the implementation

def refuse_conformal_seal(interval: UncertaintyInterval) -> None:
    """Certificate v1 seals enclosures, not statistical intervals."""
    if interval.kind is GuaranteeKind.CONFORMAL:
        raise ValueError("conformal intervals cannot be sealed into certificate v1")
    if interval.kind is GuaranteeKind.MODEL_BASED:
        raise ValueError("model-based intervals cannot be sealed into certificate v1")

FUNCTION

resample_coverage

omnibias.core.uncertainty.resample_coverageSource ↗

resample_coverage(n: int, alpha: float, *, trials: int, seed: int) -> float

The module contract describes the context for this operation. Its signature, explicit validation, return expressions, and implementation are recorded below.

Parameters

Name	Type & default	Contract
npositional-or-keyword	intRequired	See the operation contract and implementation below.
alphapositional-or-keyword	floatRequired	See the operation contract and implementation below.
trialskeyword-only	intRequired	See the operation contract and implementation below.
seedkeyword-only	intRequired	See the operation contract and implementation below.

Returnsfloat

Executed regression · g1 theory and resample

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_g1_theory_and_resample() -> None:
    for alpha in (0.01, 0.05, 0.1, 0.2):
        for n in (19, 99, 999):
            assert theoretical_coverage(n, alpha) + 1e-15 >= 1.0 - alpha
    cover = resample_coverage(19, 0.1, trials=400, seed=0)
    assert cover >= 0.84

python -m pytest "packages/omnibias-core/tests/test_uncertainty.py::test_g1_theory_and_resample" -q

Read the implementation

def resample_coverage(
    n: int,
    alpha: float,
    *,
    trials: int,
    seed: int,
) -> float:
    rng = random.Random(seed)
    hits = 0
    for _ in range(trials):
        data = [abs(rng.gauss(0.0, 1.0)) for _ in range(n + 1)]
        q = split_conformal(data[:n], alpha=alpha)
        if data[n] <= q:
            hits += 1
    return hits / float(trials)

Related APIsomnibias.core.uncertainty.split_conformal↗

FUNCTION

shift_diagnostic

omnibias.core.uncertainty.shift_diagnosticSource ↗

shift_diagnostic(*, n: int=99, seed: int=0, alpha: float=0.1) -> CalibrationReport

G4: calibration N(0,1), test N(0,3). Coverage drops; the report says so.

Parameters

Name	Type & default	Contract
nkeyword-only	intDefault: 99	See the operation contract and implementation below.
seedkeyword-only	intDefault: 0	See the operation contract and implementation below.
alphakeyword-only	floatDefault: 0.1	See the operation contract and implementation below.

ReturnsCalibrationReport

Executed regression · g4 shift

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_g4_shift() -> None:
    report = shift_diagnostic()
    assert report.shift_detected is True
    assert report.exchangeability_ok is False
    assert report.average_width > 0.0

python -m pytest "packages/omnibias-core/tests/test_uncertainty.py::test_g4_shift" -q

Read the implementation

def shift_diagnostic(
    *,
    n: int = 99,
    seed: int = 0,
    alpha: float = 0.1,
) -> CalibrationReport:
    """G4: calibration N(0,1), test N(0,3). Coverage drops; the report says so."""
    rng = random.Random(seed)
    cal = [abs(rng.gauss(0.0, 1.0)) for _ in range(n)]
    test = [abs(rng.gauss(0.0, 3.0)) for _ in range(n)]
    q = split_conformal(cal, alpha=alpha)
    cover = _cover_rate(test, q)
    shifted = cover < (1.0 - alpha) - 0.15
    return calibration_report(
        test,
        q=q,
        exchangeability_ok=not shifted,
        shift_detected=shifted,
    )

Related APIsomnibias.core.uncertainty.calibration_report↗omnibias.core.uncertainty.split_conformal↗

FUNCTION

softplus_width

omnibias.core.uncertainty.softplus_widthSource ↗

softplus_width(z: float) -> float

Positive OMBU width. Derivative is sigmoid(z) (closed form).

Parameters

Name	Type & default	Contract
zpositional-or-keyword	floatRequired	See the operation contract and implementation below.

Returnsfloat

Executed regression · softplus prime

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_softplus_prime() -> None:
    assert abs(softplus_width_prime(0.0) - 0.5) < 1e-12
    z = 0.3
    h = 1e-6
    num = (softplus_width(z + h) - softplus_width(z - h)) / (2.0 * h)
    assert abs(num - softplus_width_prime(z)) < 1e-6

python -m pytest "packages/omnibias-core/tests/test_uncertainty.py::test_softplus_prime" -q

Read the implementation

def softplus_width(z: float) -> float:
    """Positive OMBU width. Derivative is ``sigmoid(z)`` (closed form)."""
    x = float(z)
    if x > 40.0:
        return x
    if x < -40.0:
        return math.exp(x)
    return math.log1p(math.exp(x))

FUNCTION

softplus_width_prime

omnibias.core.uncertainty.softplus_width_primeSource ↗

softplus_width_prime(z: float) -> float

The module contract describes the context for this operation. Its signature, explicit validation, return expressions, and implementation are recorded below.

Parameters

Name	Type & default	Contract
zpositional-or-keyword	floatRequired	See the operation contract and implementation below.

Returnsfloat

Executed regression · softplus prime

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_softplus_prime() -> None:
    assert abs(softplus_width_prime(0.0) - 0.5) < 1e-12
    z = 0.3
    h = 1e-6
    num = (softplus_width(z + h) - softplus_width(z - h)) / (2.0 * h)
    assert abs(num - softplus_width_prime(z)) < 1e-6

python -m pytest "packages/omnibias-core/tests/test_uncertainty.py::test_softplus_prime" -q

Read the implementation

def softplus_width_prime(z: float) -> float:
    x = float(z)
    if x >= 0.0:
        e = math.exp(-x)
        return 1.0 / (1.0 + e)
    e = math.exp(x)
    return e / (1.0 + e)

FUNCTION

split_conformal

omnibias.core.uncertainty.split_conformalSource ↗

split_conformal(residuals: Sequence[float], *, alpha: float) -> float

Finite-sample corrected quantile of |residual|.

Parameters

Name	Type & default	Contract
residualspositional-or-keyword	Sequence[float]Required	See the operation contract and implementation below.
alphakeyword-only	floatRequired	See the operation contract and implementation below.

Returnsfloat

Executed regression · g3 adaptive

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_g3_adaptive() -> None:
    report = adaptive_vs_fixed()
    assert report["g3_earned"] is True
    assert report["high_noise_fixed_cover"] < 0.85

python -m pytest "packages/omnibias-core/tests/test_uncertainty.py::test_g3_adaptive" -q

Regression example · g1 off by one differs

This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_g1_off_by_one_differs() -> None:
    scores = [float(i) for i in range(1, 21)]
    q = split_conformal(scores, alpha=0.1)
    assert conformal_index(20, 0.1) == 19
    naive_k = int(math.ceil(20 * 0.9))
    assert naive_k == 18
    assert q == scores[18]
    assert q != scores[17]

python -m pytest packages/omnibias-core/tests/test_uncertainty.py -k test_g1_off_by_one_differs -q

Read the implementation

def split_conformal(residuals: Sequence[float], *, alpha: float) -> float:
    """Finite-sample corrected quantile of ``|residual|``."""
    scores = sorted(abs(float(v)) for v in residuals)
    n = len(scores)
    k = conformal_index(n, alpha)
    if k > n:
        return math.inf
    return scores[k - 1]

Related APIsomnibias.core.uncertainty.conformal_index↗

FUNCTION

theoretical_coverage

omnibias.core.uncertainty.theoretical_coverageSource ↗

theoretical_coverage(n: int, alpha: float) -> float

The module contract describes the context for this operation. Its signature, explicit validation, return expressions, and implementation are recorded below.

Parameters

Name	Type & default	Contract
npositional-or-keyword	intRequired	See the operation contract and implementation below.
alphapositional-or-keyword	floatRequired	See the operation contract and implementation below.

Returnsfloat

Executed regression · g1 theory and resample

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_g1_theory_and_resample() -> None:
    for alpha in (0.01, 0.05, 0.1, 0.2):
        for n in (19, 99, 999):
            assert theoretical_coverage(n, alpha) + 1e-15 >= 1.0 - alpha
    cover = resample_coverage(19, 0.1, trials=400, seed=0)
    assert cover >= 0.84

python -m pytest "packages/omnibias-core/tests/test_uncertainty.py::test_g1_theory_and_resample" -q

Read the implementation

def theoretical_coverage(n: int, alpha: float) -> float:
    k = conformal_index(n, alpha)
    if k > n:
        return 1.0
    return k / float(n + 1)

Related APIsomnibias.core.uncertainty.conformal_index↗

FUNCTION

worked_example

omnibias.core.uncertainty.worked_exampleSource ↗

worked_example() -> dict[str, float]

The module contract describes the context for this operation. Its signature, explicit validation, return expressions, and implementation are recorded below.

Returnsdict[str, float]

Executed regression · g1 worked quantile

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_g1_worked_quantile() -> None:
    ex = worked_example()
    assert ex["q"] == 0.88
    assert conformal_index(19, 0.1) == 18
    naive = int(math.ceil(20 * 0.9))
    assert naive == 18

python -m pytest "packages/omnibias-core/tests/test_uncertainty.py::test_g1_worked_quantile" -q

Read the implementation

def worked_example() -> dict[str, float]:
    q = split_conformal(WORKED_RESIDUALS, alpha=0.1)
    return {"q": q, "alpha": 0.1, "n": float(len(WORKED_RESIDUALS))}

Related APIsomnibias.core.uncertainty.split_conformal↗

← Package overviewRunnable learning examples →