testmechs 0.1.0__py3-none-any.whl

testmechs/__init__.py

@@ -0,0 +1,395 @@
+"""Public contracts for the TestMechs Python package."""
+
+from importlib.metadata import PackageNotFoundError, version
+from importlib import import_module
+
+try:
+    __version__ = version("testmechs")
+except PackageNotFoundError:
+    __version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "ADEBoundsRequest",
+    "ADEBoundsResult",
+    "AdjustedMediatorMassResult",
+    "AdjustedProbabilityInfluenceResult",
+    "AdjustedProbabilityResult",
+    "BinaryCSMonteCarloDesign",
+    "BinaryEmpiricalMixtureBenchmarkDataSource",
+    "BinaryEmpiricalMixtureMonteCarloDesign",
+    "BinaryPartialDensityMonteCarloDesign",
+    "BreakdownDefierShareRequest",
+    "BoundsSupport",
+    "CellCountDiagnosticsSupport",
+    "ClusterCellCount",
+    "MonteCarloBlockedBenchmarkRow",
+    "MonteCarloBenchmarkCell",
+    "MonteCarloBenchmarkDataSourceDiagnostic",
+    "LowerBoundResult",
+    "LowerBoundRequest",
+    "MonteCarloBenchmarkDiagnostic",
+    "MonteCarloBenchmarkMatrixResult",
+    "MonteCarloCellCountHeuristic",
+    "MonteCarloBenchmarkPlan",
+    "MonteCarloBenchmarkPlanReadinessReport",
+    "MonteCarloBenchmarkPlanRerunCell",
+    "MonteCarloBenchmarkPlanRerunManifest",
+    "MonteCarloBenchmarkPlanRunResult",
+    "MonteCarloBenchmarkSuiteReadinessReport",
+    "MonteCarloBenchmarkSuiteRunResult",
+    "MonteCarloContracts",
+    "MonteCarloDrawResult",
+    "MonteCarloMethodExecutionContract",
+    "MonteCarloMethodGuidance",
+    "MonteCarloResultRow",
+    "MonteCarloSizeDiagnostic",
+    "MonteCarloSimulationResult",
+    "PaperMonteCarloReproductionReport",
+    "PartialDensityDataResult",
+    "PartialDensityRequest",
+    "PartialDensitySupport",
+    "PaperEmpiricalReproductionReport",
+    "PaperEmpiricalReproductionRequest",
+    "PaperMonteCarloReproductionRequest",
+    "PaperReproductionComparisonReport",
+    "PaperReproductionComparisonRequest",
+    "PaperReproductionE2EReport",
+    "PaperReproductionE2ERequest",
+    "PaperReproductionResource",
+    "PaperReproductionResourceManifestRequest",
+    "PaperReproductionResourceManifestPacket",
+    "RegressionAdjustmentSupport",
+    "RegressionFormulaSpec",
+    "SharedCSVInput",
+    "SharpNullRequest",
+    "SharpNullResult",
+    "TVConfidenceIntervalResult",
+    "SharpNullDiagnosticsSupport",
+    "bounds_ade_ats",
+    "breakdown_defier_share",
+    "build_python_fixture_summary",
+    "build_cell_count_diagnostics",
+    "bounds_diagnostic_schema_frame",
+    "bounds_support_contract",
+    "bounds_support_frame",
+    "cell_count_diagnostics_support_contract",
+    "cell_count_diagnostics_support_frame",
+    "ci_TV",
+    "compute_positive_part_partial_pmf_diff",
+    "compute_adjusted_mediator_masses",
+    "compute_adjusted_probability_influences",
+    "compute_adjusted_probabilities",
+    "discretize_y",
+    "diff_fixture_summaries",
+    "lb_frac_affected",
+    "load_paper_monte_carlo_reproduction_report_json",
+    "load_monte_carlo_suite_run_result_json",
+    "load_paper_empirical_mixture_benchmark_data_sources",
+    "load_paper_monte_carlo_contracts",
+    "load_paper_reproduction_resource_manifest_json",
+    "load_paper_reproduction_resource_manifest_packet_json",
+    "milestone_audit_status_for_version",
+    "milestone_audit_status_from_file",
+    "paper_monte_carlo_reproduction_display_frame",
+    "paper_monte_carlo_reproduction_report",
+    "paper_monte_carlo_reproduction_report_frame",
+    "summarize_paper_empirical_mixture_benchmark_suite_archive_blocker_packet",
+    "summarize_paper_empirical_mixture_benchmark_suite_archive_gate",
+    "raise_for_milestone_archive_blockers",
+    "raise_for_paper_empirical_mixture_benchmark_suite_archive_blockers",
+    "partial_density_data",
+    "partial_density_diagnostic_schema_frame",
+    "partial_density_plot",
+    "partial_density_support_contract",
+    "partial_density_support_frame",
+    "parse_reg_formula",
+    "paper_empirical_reproduction_display_frame",
+    "paper_empirical_reproduction_report",
+    "paper_empirical_reproduction_report_frame",
+    "paper_reproduction_comparison_display_frame",
+    "paper_reproduction_comparison_report",
+    "paper_reproduction_comparison_report_frame",
+    "paper_reproduction_e2e_display_frame",
+    "paper_reproduction_e2e_report",
+    "paper_reproduction_e2e_report_frame",
+    "paper_reproduction_resource_manifest",
+    "paper_reproduction_resource_manifest_frame",
+    "paper_reproduction_resource_manifest_packet",
+    "remove_missing_from_df",
+    "run_r_bounds_ade_ats_case",
+    "run_r_fixture_summary",
+    "run_r_lb_frac_affected_case",
+    "run_r_sharp_null_arp_case",
+    "run_r_sharp_null_cr_case",
+    "run_r_simulate_data_binary_m_contract",
+    "run_r_sharp_null_cs_case",
+    "run_binary_cs_monte_carlo",
+    "run_binary_empirical_mixture_cs_benchmark_focused_probe",
+    "run_binary_empirical_mixture_cs_benchmark_matrix",
+    "run_binary_empirical_mixture_cs_benchmark_manifest",
+    "run_binary_empirical_mixture_cs_benchmark_plan",
+    "run_binary_empirical_mixture_cs_benchmark_plan_by_source",
+    "run_binary_empirical_mixture_cs_monte_carlo",
+    "run_binary_partial_density_cs_monte_carlo",
+    "run_empirical_mixture_arp_benchmark_manifest",
+    "run_empirical_mixture_benchmark_focused_probe",
+    "run_empirical_mixture_benchmark_manifest",
+    "run_empirical_mixture_benchmark_plan_by_source",
+    "run_empirical_mixture_fsstdd_benchmark_manifest",
+    "run_empirical_mixture_fsstndd_benchmark_manifest",
+    "run_empirical_mixture_k_benchmark_manifest",
+    "run_empirical_mixture_cs_benchmark_focused_probe",
+    "run_empirical_mixture_cs_benchmark_matrix",
+    "run_empirical_mixture_cs_benchmark_manifest",
+    "run_empirical_mixture_cs_benchmark_plan",
+    "run_empirical_mixture_cs_benchmark_plan_by_source",
+    "run_nonbinary_empirical_mixture_cs_monte_carlo",
+    "write_monte_carlo_suite_run_result_json",
+    "write_merged_monte_carlo_suite_run_result_json",
+    "write_paper_monte_carlo_reproduction_report_json",
+    "write_paper_reproduction_comparison_report_json",
+    "write_paper_reproduction_e2e_report_json",
+    "write_paper_reproduction_resource_manifest_json",
+    "load_paper_reproduction_comparison_report_json",
+    "load_paper_reproduction_e2e_report_json",
+    "write_paper_empirical_mixture_benchmark_suite_evidence",
+    "write_next_paper_empirical_mixture_benchmark_suite_archive_evidence",
+    "run_paper_empirical_mixture_benchmark_suite_chunk",
+    "summarize_paper_empirical_mixture_benchmark_suite_evidence",
+    "regression_adjustment_support_contract",
+    "regression_adjustment_support_frame",
+    "sharp_null_diagnostic_schema_frame",
+    "sharp_null_diagnostics_support_contract",
+    "sharp_null_diagnostics_support_frame",
+    "test_sharp_null_cr",
+    "test_sharp_null",
+    "theta_kk_min_ordered_monotone",
+    "write_next_paper_empirical_mixture_benchmark_suite_chunk_evidence",
+    "write_paper_empirical_mixture_benchmark_suite_chunk_evidence",
+]
+
+_EXPORT_MODULES = {
+    "ADEBoundsResult": "results",
+    "LowerBoundResult": "results",
+    "SharpNullResult": "results",
+    "TVConfidenceIntervalResult": "results",
+    "bounds_ade_ats": "bounds",
+    "breakdown_defier_share": "bounds",
+    "compute_positive_part_partial_pmf_diff": "bounds",
+    "lb_frac_affected": "bounds",
+    "theta_kk_min_ordered_monotone": "bounds",
+    "ADEBoundsRequest": "contracts",
+    "BreakdownDefierShareRequest": "contracts",
+    "BoundsSupport": "contracts",
+    "CellCountDiagnosticsSupport": "contracts",
+    "LowerBoundRequest": "contracts",
+    "PartialDensityRequest": "contracts",
+    "PartialDensitySupport": "contracts",
+    "PaperEmpiricalReproductionRequest": "contracts",
+    "PaperMonteCarloReproductionRequest": "contracts",
+    "PaperReproductionComparisonRequest": "contracts",
+    "PaperReproductionE2ERequest": "contracts",
+    "PaperReproductionResourceManifestRequest": "contracts",
+    "RegressionAdjustmentSupport": "contracts",
+    "SharedCSVInput": "contracts",
+    "SharpNullDiagnosticsSupport": "contracts",
+    "SharpNullRequest": "contracts",
+    "bounds_diagnostic_schema_frame": "contracts",
+    "bounds_support_contract": "contracts",
+    "bounds_support_frame": "contracts",
+    "cell_count_diagnostics_support_contract": "contracts",
+    "cell_count_diagnostics_support_frame": "contracts",
+    "ci_TV": "sharp_null",
+    "partial_density_diagnostic_schema_frame": "contracts",
+    "partial_density_support_contract": "contracts",
+    "partial_density_support_frame": "contracts",
+    "regression_adjustment_support_contract": "contracts",
+    "regression_adjustment_support_frame": "contracts",
+    "sharp_null_diagnostic_schema_frame": "contracts",
+    "sharp_null_diagnostics_support_contract": "contracts",
+    "sharp_null_diagnostics_support_frame": "contracts",
+    "test_sharp_null_cr": "sharp_null",
+    "PaperEmpiricalReproductionReport": "empirical",
+    "paper_empirical_reproduction_display_frame": "empirical",
+    "paper_empirical_reproduction_report": "empirical",
+    "paper_empirical_reproduction_report_frame": "empirical",
+    "build_python_fixture_summary": "parity",
+    "diff_fixture_summaries": "parity",
+    "run_r_bounds_ade_ats_case": "parity",
+    "run_r_fixture_summary": "parity",
+    "run_r_lb_frac_affected_case": "parity",
+    "run_r_sharp_null_arp_case": "parity",
+    "run_r_sharp_null_cr_case": "parity",
+    "run_r_simulate_data_binary_m_contract": "parity",
+    "run_r_sharp_null_cs_case": "parity",
+    "PartialDensityDataResult": "partial_density",
+    "partial_density_data": "partial_density",
+    "partial_density_plot": "partial_density",
+    "build_cell_count_diagnostics": "preprocess",
+    "discretize_y": "preprocess",
+    "remove_missing_from_df": "preprocess",
+    "AdjustedMediatorMassResult": "regression",
+    "AdjustedProbabilityInfluenceResult": "regression",
+    "AdjustedProbabilityResult": "regression",
+    "RegressionFormulaSpec": "regression",
+    "compute_adjusted_mediator_masses": "regression",
+    "compute_adjusted_probability_influences": "regression",
+    "compute_adjusted_probabilities": "regression",
+    "parse_reg_formula": "regression",
+    "PaperReproductionComparisonReport": "reproduction",
+    "PaperReproductionE2EReport": "reproduction",
+    "load_paper_reproduction_comparison_report_json": "reproduction",
+    "load_paper_reproduction_e2e_report_json": "reproduction",
+    "paper_reproduction_comparison_display_frame": "reproduction",
+    "paper_reproduction_comparison_report": "reproduction",
+    "paper_reproduction_comparison_report_frame": "reproduction",
+    "paper_reproduction_e2e_display_frame": "reproduction",
+    "paper_reproduction_e2e_report": "reproduction",
+    "paper_reproduction_e2e_report_frame": "reproduction",
+    "write_paper_reproduction_comparison_report_json": "reproduction",
+    "write_paper_reproduction_e2e_report_json": "reproduction",
+    "PaperReproductionResource": "resources",
+    "PaperReproductionResourceManifestPacket": "resources",
+    "load_paper_reproduction_resource_manifest_json": "resources",
+    "load_paper_reproduction_resource_manifest_packet_json": "resources",
+    "paper_reproduction_resource_manifest": "resources",
+    "paper_reproduction_resource_manifest_frame": "resources",
+    "paper_reproduction_resource_manifest_packet": "resources",
+    "write_paper_reproduction_resource_manifest_json": "resources",
+    "test_sharp_null": "sharp_null",
+}
+
+_MONTE_CARLO_EXPORTS = {
+    "BinaryCSMonteCarloDesign",
+    "BinaryEmpiricalMixtureBenchmarkDataSource",
+    "BinaryEmpiricalMixtureMonteCarloDesign",
+    "BinaryPartialDensityMonteCarloDesign",
+    "ClusterCellCount",
+    "MonteCarloBlockedBenchmarkRow",
+    "MonteCarloBenchmarkCell",
+    "MonteCarloBenchmarkDataSourceDiagnostic",
+    "MonteCarloBenchmarkDiagnostic",
+    "MonteCarloBenchmarkMatrixResult",
+    "MonteCarloCellCountHeuristic",
+    "MonteCarloBenchmarkPlan",
+    "MonteCarloBenchmarkPlanReadinessReport",
+    "MonteCarloBenchmarkPlanRerunCell",
+    "MonteCarloBenchmarkPlanRerunManifest",
+    "MonteCarloBenchmarkPlanRunResult",
+    "MonteCarloBenchmarkSuiteReadinessReport",
+    "MonteCarloBenchmarkSuiteRunResult",
+    "MonteCarloContracts",
+    "MonteCarloDrawResult",
+    "MonteCarloMethodExecutionContract",
+    "MonteCarloMethodGuidance",
+    "MonteCarloResultRow",
+    "MonteCarloSizeDiagnostic",
+    "MonteCarloSimulationResult",
+    "PaperMonteCarloReproductionReport",
+    "load_paper_empirical_mixture_benchmark_data_sources",
+    "load_paper_monte_carlo_contracts",
+    "load_paper_monte_carlo_reproduction_report_json",
+    "load_monte_carlo_suite_run_result_json",
+    "milestone_audit_status_for_version",
+    "milestone_audit_status_from_file",
+    "paper_monte_carlo_reproduction_display_frame",
+    "paper_monte_carlo_reproduction_report",
+    "paper_monte_carlo_reproduction_report_frame",
+    "raise_for_milestone_archive_blockers",
+    "raise_for_paper_empirical_mixture_benchmark_suite_archive_blockers",
+    "run_binary_cs_monte_carlo",
+    "run_binary_empirical_mixture_cs_benchmark_focused_probe",
+    "run_binary_empirical_mixture_cs_benchmark_manifest",
+    "run_binary_empirical_mixture_cs_benchmark_matrix",
+    "run_binary_empirical_mixture_cs_benchmark_plan",
+    "run_binary_empirical_mixture_cs_benchmark_plan_by_source",
+    "run_binary_empirical_mixture_cs_monte_carlo",
+    "run_binary_partial_density_cs_monte_carlo",
+    "run_empirical_mixture_arp_benchmark_manifest",
+    "run_empirical_mixture_benchmark_focused_probe",
+    "run_empirical_mixture_benchmark_manifest",
+    "run_empirical_mixture_benchmark_plan_by_source",
+    "run_empirical_mixture_cs_benchmark_focused_probe",
+    "run_empirical_mixture_cs_benchmark_manifest",
+    "run_empirical_mixture_cs_benchmark_matrix",
+    "run_empirical_mixture_cs_benchmark_plan",
+    "run_empirical_mixture_cs_benchmark_plan_by_source",
+    "run_empirical_mixture_fsstdd_benchmark_manifest",
+    "run_empirical_mixture_fsstndd_benchmark_manifest",
+    "run_empirical_mixture_k_benchmark_manifest",
+    "run_nonbinary_empirical_mixture_cs_monte_carlo",
+    "run_paper_empirical_mixture_benchmark_suite_chunk",
+    "summarize_paper_empirical_mixture_benchmark_suite_archive_blocker_packet",
+    "summarize_paper_empirical_mixture_benchmark_suite_archive_gate",
+    "summarize_paper_empirical_mixture_benchmark_suite_evidence",
+    "write_monte_carlo_suite_run_result_json",
+    "write_merged_monte_carlo_suite_run_result_json",
+    "write_next_paper_empirical_mixture_benchmark_suite_archive_evidence",
+    "write_next_paper_empirical_mixture_benchmark_suite_chunk_evidence",
+    "write_paper_empirical_mixture_benchmark_suite_chunk_evidence",
+    "write_paper_empirical_mixture_benchmark_suite_evidence",
+    "write_paper_monte_carlo_reproduction_report_json",
+}
+
+_ROOT_EXPORT_EXCLUSIONS = {
+    "build_python_fixture_summary",
+    "diff_fixture_summaries",
+    "run_r_bounds_ade_ats_case",
+    "run_r_fixture_summary",
+    "run_r_lb_frac_affected_case",
+    "run_r_sharp_null_arp_case",
+    "run_r_sharp_null_cr_case",
+    "run_r_sharp_null_cs_case",
+    "run_r_simulate_data_binary_m_contract",
+}
+
+_ROOT_EXPORT_EXCLUSION_FRAGMENTS = (
+    "archive",
+    "benchmark",
+    "chunk",
+    "evidence",
+    "focused_probe",
+    "milestone_audit",
+)
+
+
+def _is_root_export_excluded(name: str) -> bool:
+    lower_name = name.lower()
+    return (
+        name in _ROOT_EXPORT_EXCLUSIONS
+        or name.startswith("run_")
+        or name.startswith("write_next_")
+        or any(fragment in lower_name for fragment in _ROOT_EXPORT_EXCLUSION_FRAGMENTS)
+    )
+
+
+__all__ = [name for name in __all__ if not _is_root_export_excluded(name)]
+
+_EXPORT_MODULES.update(
+    {
+        name: "monte_carlo"
+        for name in _MONTE_CARLO_EXPORTS
+    }
+)
+
+for _name in tuple(_EXPORT_MODULES):
+    if _is_root_export_excluded(_name):
+        _EXPORT_MODULES.pop(_name, None)
+for _name in _ROOT_EXPORT_EXCLUSIONS:
+    _EXPORT_MODULES.pop(_name, None)
+
+
+def __getattr__(name: str) -> object:
+    if name == "__version__":
+        return __version__
+    module_name = _EXPORT_MODULES.get(name)
+    if module_name is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    value = getattr(import_module(f".{module_name}", __name__), name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(__all__))

testmechs/_json_io.py

@@ -0,0 +1,69 @@
+"""Atomic strict-JSON file writer for testmechs report persistence.
+
+This module provides a single utility function that serializes a Python
+object to a JSON file using an atomic write pattern (write-to-temp then
+rename). Non-finite floats (NaN, Infinity) are rejected at serialization
+time so that all persisted artifacts remain valid strict JSON.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+import tempfile
+from typing import Any
+
+
+def write_strict_json_atomic(path: Path, payload: Any) -> None:
+    """Serialize *payload* to *path* as strict JSON using an atomic write.
+
+    The function writes to a temporary file in the same directory as *path*
+    and then atomically renames it to *path*, ensuring readers never observe
+    a partially-written file.
+
+    Parameters
+    ----------
+    path : Path
+        Destination file path.  Parent directories are created if absent.
+    payload : Any
+        JSON-serializable object.  Must not contain ``NaN`` or ``Infinity``
+        values (``allow_nan=False`` is enforced).
+
+    Raises
+    ------
+    ValueError
+        If *payload* contains non-finite numeric values.
+    OSError
+        If the temporary file cannot be written or renamed.
+
+    Examples
+    --------
+    >>> from pathlib import Path
+    >>> write_strict_json_atomic(Path("/tmp/result.json"), {"score": 0.95})
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temp_path: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            "w",
+            encoding="utf-8",
+            dir=path.parent,
+            prefix=f".{path.name}.",
+            suffix=".tmp",
+            delete=False,
+        ) as handle:
+            temp_path = Path(handle.name)
+            json.dump(
+                payload,
+                handle,
+                allow_nan=False,
+                ensure_ascii=False,
+                indent=2,
+                sort_keys=True,
+            )
+            handle.write("\n")
+        temp_path.replace(path)
+    except Exception:
+        if temp_path is not None:
+            temp_path.unlink(missing_ok=True)
+        raise