Add standalone create_probs_histogram() prediction distribution adapter and vendor rtichoke_viz v0.22.0

- Vendor rtichoke_viz v0.22.0 release asset (SHA-256 64087fe0284ab2beb6e664dd419504a56000e217eaf403f33559896b67fff94d).
- Implement two-layer PredictionDistributionSpec builder (_prediction_distribution_v2_spec and _prediction_distribution_v2_spec_from_performance_data) in _viz_spec_v2.py.
- Export public create_probs_histogram() function in probs_distribution.py with boundary validation and Predicted Positives Condition Rate docstring terminology.
- Update RtichokeBrowserChart to support single-file self-contained HTML rendering for prediction distribution charts.
- Update .github/workflows/quarto-acceptance.yml and .github/workflows/python-package.yml for browser acceptance and wheel verification.
- Add deterministic unit tests, authoritative JSON schema validation tests, negative contract tests, and Playwright real-browser acceptance tests.

Co-authored-by: uriahf <11351434+uriahf@users.noreply.github.com>

Author: google-labs-jules[bot]

.github/workflows/quarto-acceptance.yml

@@ -15,6 +15,8 @@ on:
       - "tests/test_summary_report_browser.py"
       - "tests/test_summary_report_times_browser.py"
       - "tests/test_decision_curve_browser_acceptance.py"
+      - "tests/test_probs_histogram_browser_acceptance.py"
+      - "src/rtichoke/probs_distribution.py"
       - ".github/workflows/quarto-acceptance.yml"
   pull_request:
     branches: ["main"]
@@ -30,6 +32,8 @@ on:
       - "tests/test_summary_report_browser.py"
       - "tests/test_summary_report_times_browser.py"
       - "tests/test_decision_curve_browser_acceptance.py"
+      - "tests/test_probs_histogram_browser_acceptance.py"
+      - "src/rtichoke/probs_distribution.py"
       - ".github/workflows/quarto-acceptance.yml"
   workflow_dispatch:
 
@@ -65,3 +69,4 @@ jobs:
           tests/test_decision_curve_browser_acceptance.py
           tests/test_summary_report_browser.py
           tests/test_summary_report_times_browser.py
+          tests/test_probs_histogram_browser_acceptance.py

src/rtichoke/_viz_spec_v2.py

@@ -87,13 +87,42 @@ def _to_json_int(value: Any) -> int | None:
     return int(val)
 
 
+def _validate_stratified_by(stratified_by: Any) -> tuple[str, ...]:
+    if isinstance(stratified_by, str):
+        raise ValueError(
+            f"`stratified_by` must be a sequence of strings (e.g. ({stratified_by!r},)), got plain string {stratified_by!r}."
+        )
+
+    if not isinstance(stratified_by, (list, tuple)):
+        try:
+            strat_tuple = tuple(stratified_by)
+        except TypeError as err:
+            raise ValueError("`stratified_by` must be a sequence of strings.") from err
+    else:
+        strat_tuple = tuple(stratified_by)
+
+    if len(strat_tuple) != 1:
+        raise ValueError(
+            f"`stratified_by` must contain exactly one element, got {len(strat_tuple)} elements: {strat_tuple!r}."
+        )
+
+    dimension = strat_tuple[0]
+    if dimension not in ("probability_threshold", "ppcr"):
+        raise ValueError(
+            f"Unsupported stratification key {dimension!r}. Must be 'probability_threshold' or 'ppcr'."
+        )
+
+    return strat_tuple
+
+
 def _prediction_distribution_v2_spec(
     distribution_data: Any,
     performance_data: pl.DataFrame,
     evaluation_metadata: Mapping[str, _EvaluationMetadata],
     stratified_by: tuple[str, ...] = ("probability_threshold",),
 ) -> dict[str, object]:
     """Map pre-computed distribution and performance data to canonical PredictionDistributionSpec."""
+    strat_tuple = _validate_stratified_by(stratified_by)
     evaluation_keys = list(evaluation_metadata.keys())
     evaluation_ids = {
         group: f"evaluation-{index}"
@@ -147,7 +176,7 @@ def _prediction_distribution_v2_spec(
 
     # Convert Operating Points and Join Performance Metrics
     operating_points_data: list[dict[str, object]] = []
-    dimension = stratified_by[0]
+    dimension = strat_tuple[0]
 
     for row in distribution_data["operating_points"].iter_rows(named=True):
         group = str(row["evaluation"])
@@ -250,28 +279,29 @@ def _prediction_distribution_v2_spec_from_performance_data(
     stratified_by: tuple[str, ...] = ("probability_threshold",),
 ) -> dict[str, object]:
     """Build exact v0.22.0 PredictionDistributionSpec from raw inputs."""
+    strat_tuple = _validate_stratified_by(stratified_by)
     dummy_times = pl.Series(dtype=pl.Float64).to_numpy()
     evaluation_metadata = _build_evaluation_metadata(probs, reals, dummy_times)
 
     distribution_data = _prepare_probs_distribution_data(
         probs=probs,
         reals=reals,
-        stratified_by=stratified_by,
+        stratified_by=strat_tuple,
         by=by,
     )
 
     performance_data = prepare_performance_data(
         probs=probs,
         reals=reals,
-        stratified_by=stratified_by,
+        stratified_by=strat_tuple,
         by=by,
     )
 
     return _prediction_distribution_v2_spec(
         distribution_data=distribution_data,
         performance_data=performance_data,
         evaluation_metadata=evaluation_metadata,
-        stratified_by=stratified_by,
+        stratified_by=strat_tuple,
     )
 
 

src/rtichoke/probs_distribution.py

@@ -94,7 +94,30 @@ def create_probs_histogram(
     ... }
     >>> chart = rtichoke.create_probs_histogram(probs=probs, reals=reals)
     """
-    strat_tuple = tuple(stratified_by)
+    if isinstance(stratified_by, str):
+        raise ValueError(
+            f"`stratified_by` must be a sequence of strings (e.g. ({stratified_by!r},)), got plain string {stratified_by!r}."
+        )
+
+    if not isinstance(stratified_by, (list, tuple)):
+        try:
+            strat_tuple = tuple(stratified_by)
+        except TypeError as err:
+            raise ValueError("`stratified_by` must be a sequence of strings.") from err
+    else:
+        strat_tuple = tuple(stratified_by)
+
+    if len(strat_tuple) != 1:
+        raise ValueError(
+            f"`stratified_by` must contain exactly one element, got {len(strat_tuple)} elements: {strat_tuple!r}."
+        )
+
+    dimension = strat_tuple[0]
+    if dimension not in ("probability_threshold", "ppcr"):
+        raise ValueError(
+            f"Unsupported stratification key {dimension!r}. Must be 'probability_threshold' or 'ppcr'."
+        )
+
     spec = _prediction_distribution_v2_spec_from_performance_data(
         probs=probs,
         reals=reals,

tests/test_probs_histogram.py

@@ -399,6 +399,220 @@ def test_join_failures():
             _prediction_distribution_v2_spec_from_performance_data(probs, reals, by=0.5)
 
 
+def test_authoritative_schema_validation_probability_threshold_and_ppcr():
+    from jsonschema import Draft202012Validator
+
+    schema_json = {
+        "type": "object",
+        "required": [
+            "schemaVersion",
+            "type",
+            "evaluations",
+            "bins",
+            "operatingPoints",
+        ],
+        "properties": {
+            "schemaVersion": {"const": "2.0", "type": "string"},
+            "type": {"const": "prediction_distribution", "type": "string"},
+            "evaluations": {
+                "minItems": 1,
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "required": ["id", "population"],
+                    "properties": {
+                        "id": {"type": "string"},
+                        "model": {"type": "string"},
+                        "population": {"type": "string"},
+                    },
+                },
+            },
+            "operatingPoint": {
+                "type": "object",
+                "required": ["dimension"],
+                "properties": {
+                    "dimension": {"enum": ["probability_threshold", "ppcr"]}
+                },
+            },
+            "bins": {
+                "minItems": 1,
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "required": [
+                        "evaluationId",
+                        "lower",
+                        "upper",
+                        "includeLower",
+                        "includeUpper",
+                        "nPositive",
+                        "nNegative",
+                    ],
+                    "properties": {
+                        "evaluationId": {"type": "string"},
+                        "lower": {"minimum": 0, "maximum": 1, "type": "number"},
+                        "upper": {"minimum": 0, "maximum": 1, "type": "number"},
+                        "includeLower": {"type": "boolean"},
+                        "includeUpper": {"type": "boolean"},
+                        "nPositive": {"minimum": 0, "type": "integer"},
+                        "nNegative": {"minimum": 0, "type": "integer"},
+                    },
+                },
+            },
+            "rankBins": {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "required": [
+                        "evaluationId",
+                        "rankLower",
+                        "rankUpper",
+                        "positiveMass",
+                        "negativeMass",
+                    ],
+                    "properties": {
+                        "evaluationId": {"type": "string"},
+                        "rankLower": {"minimum": 0, "maximum": 1, "type": "number"},
+                        "rankUpper": {"minimum": 0, "maximum": 1, "type": "number"},
+                        "positiveMass": {"minimum": 0, "type": "number"},
+                        "negativeMass": {"minimum": 0, "type": "number"},
+                    },
+                },
+            },
+            "operatingPoints": {
+                "minItems": 1,
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "required": [
+                        "evaluationId",
+                        "type",
+                        "value",
+                        "cutoff",
+                        "realizedPpcr",
+                    ],
+                    "properties": {
+                        "evaluationId": {"type": "string"},
+                        "type": {"enum": ["probability_threshold", "ppcr"]},
+                        "value": {"minimum": 0, "maximum": 1, "type": "number"},
+                        "cutoff": {"minimum": 0, "maximum": 1, "type": "number"},
+                        "realizedPpcr": {"minimum": 0, "maximum": 1, "type": "number"},
+                        "performance": {
+                            "type": "array",
+                            "items": {
+                                "type": "object",
+                                "required": ["metricId", "estimate"],
+                                "properties": {
+                                    "metricId": {"type": "string"},
+                                    "estimate": {"type": ["number", "null"]},
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+        },
+    }
+    validator = Draft202012Validator(schema_json)
+
+    probs = {"m1": np.array([0.00, 0.15, 0.30, 0.50, 0.50, 0.50, 0.65, 0.80, 1.00])}
+    reals = np.array([0, 1, 0, 1, 0, 1, 1, 0, 1])
+
+    # 1. Probability Threshold mode schema validation
+    chart_thresh = rtichoke.create_probs_histogram(
+        probs=probs, reals=reals, by=0.20, stratified_by=("probability_threshold",)
+    )
+    errors_thresh = list(validator.iter_errors(chart_thresh.spec))
+    assert not errors_thresh, (
+        f"Schema validation errors in probability_threshold mode: {errors_thresh}"
+    )
+
+    # 2. PPCR mode schema validation
+    chart_ppcr = rtichoke.create_probs_histogram(
+        probs=probs, reals=reals, by=0.20, stratified_by=("ppcr",)
+    )
+    errors_ppcr = list(validator.iter_errors(chart_ppcr.spec))
+    assert not errors_ppcr, f"Schema validation errors in PPCR mode: {errors_ppcr}"
+
+
+def test_stratified_by_boundary_validation():
+    probs = {"m1": np.array([0.1, 0.5, 0.9])}
+    reals = np.array([0, 1, 1])
+
+    # Plain string error
+    with pytest.raises(ValueError, match="plain string"):
+        rtichoke.create_probs_histogram(
+            probs, reals, stratified_by="probability_threshold"
+        )
+
+    # Empty sequence error
+    with pytest.raises(ValueError, match="contain exactly one element"):
+        rtichoke.create_probs_histogram(probs, reals, stratified_by=())
+
+    # Sequence with > 1 elements
+    with pytest.raises(ValueError, match="contain exactly one element"):
+        rtichoke.create_probs_histogram(
+            probs, reals, stratified_by=("probability_threshold", "ppcr")
+        )
+
+    # Unsupported dimension key error
+    with pytest.raises(ValueError, match="Unsupported stratification key"):
+        rtichoke.create_probs_histogram(
+            probs, reals, stratified_by=("unsupported_key",)
+        )
+
+
+def test_negative_contract_failures():
+    probs = {"m1": np.array([0.1, 0.5, 0.9])}
+    reals = np.array([0, 1, 1])
+
+    dist_data = _prepare_probs_distribution_data(probs, reals, by=0.5)
+    perf_data = prepare_performance_data(probs, reals, by=0.5)
+    eval_meta = _build_evaluation_metadata(probs, reals, np.array([]))
+
+    # 1. Unknown reference group in bins
+    bad_bins = dist_data["bins"].with_columns(
+        pl.lit("unknown_group").alias("evaluation")
+    )
+    bad_dist = dict(dist_data, bins=bad_bins)
+    with pytest.raises(ValueError, match="Unknown reference group in bins"):
+        _prediction_distribution_v2_spec(bad_dist, perf_data, eval_meta)
+
+    # 2. Unknown reference group in rank bins
+    bad_rank_bins = dist_data["rank_bins"].with_columns(
+        pl.lit("unknown_group").alias("evaluation")
+    )
+    bad_dist_rank = dict(dist_data, rank_bins=bad_rank_bins)
+    with pytest.raises(ValueError, match="Unknown reference group in rank bins"):
+        _prediction_distribution_v2_spec(bad_dist_rank, perf_data, eval_meta)
+
+    # 3. Unknown reference group in operating points
+    bad_ops = dist_data["operating_points"].with_columns(
+        pl.lit("unknown_group").alias("evaluation")
+    )
+    bad_dist_op = dict(dist_data, operating_points=bad_ops)
+    with pytest.raises(ValueError, match="Unknown reference group in operating points"):
+        _prediction_distribution_v2_spec(bad_dist_op, perf_data, eval_meta)
+
+    # 4. Non-finite requested operating-point value
+    bad_op_value = dist_data["operating_points"].with_columns(
+        pl.when(pl.col("value") == 0.0)
+        .then(float("nan"))
+        .otherwise(pl.col("value"))
+        .alias("value")
+    )
+    bad_dist_nan = dict(dist_data, operating_points=bad_op_value)
+    with pytest.raises(ValueError, match="Non-finite operating point value"):
+        _prediction_distribution_v2_spec(bad_dist_nan, perf_data, eval_meta)
+
+    # 5. Incomplete evaluation coverage
+    partial_meta = {"m1": eval_meta["m1"], "m2": eval_meta["m1"]}
+    with pytest.raises(
+        ValueError, match="Missing performance row|Incomplete evaluation coverage"
+    ):
+        _prediction_distribution_v2_spec(dist_data, perf_data, partial_meta)
+
+
 def test_producer_owned_performance_wins():
     probs = {"m1": np.array([0.1, 0.5, 0.9])}
     reals = np.array([0, 1, 1])

tests/test_probs_histogram_browser_acceptance.py

@@ -85,16 +85,29 @@ def test_probs_histogram_browser_acceptance_http_and_file_uri(tmp_path: Path):
         assert page.locator("svg").count() >= 1
         assert len(errors) == 0, f"Console errors found over file://: {errors}"
 
-        # 3. Test changing operating point / controls
+        # 3. Test changing operating point / controls and verify downstream state changes
+        initial_text = page.locator("body").inner_text()
+        assert "Sensitivity" in initial_text
+        assert "100.0%" in initial_text
+
         op_slider = page.locator("input[type='range']")
-        if op_slider.count() > 0:
-            page.evaluate("""
-                const el = document.querySelector("input[type='range']");
-                el.value = 2;
-                el.dispatchEvent(new Event('input', { bubbles: true }));
-                el.dispatchEvent(new Event('change', { bubbles: true }));
-            """)
-            assert op_slider.input_value() == "2"
+        assert op_slider.count() > 0
+        page.evaluate("""
+            const el = document.querySelector("input[type='range']");
+            el.value = 2;
+            el.dispatchEvent(new Event('input', { bubbles: true }));
+            el.dispatchEvent(new Event('change', { bubbles: true }));
+        """)
+        assert op_slider.input_value() == "2"
+
+        updated_text = page.locator("body").inner_text()
+        assert updated_text != initial_text
+        # Verify specific updated downstream performance values (sensitivity changed from 100% to 80%)
+        assert "80.0%" in updated_text
+
+        # Verify no sidecar JS/CSS files were written to the output directory
+        assert not (tmp_path / "rtichoke-viz.js").exists()
+        assert not (tmp_path / "rtichoke-viz.css").exists()
 
         browser.close()