modelwright 0.1.0a4__tar.gz → 0.1.0a5__tar.gz

modelwright-0.1.0a5/MANIFEST.in

@@ -0,0 +1 @@
+recursive-include examples *.md *.py *.xz

{modelwright-0.1.0a4/src/modelwright.egg-info → modelwright-0.1.0a5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modelwright
-Version: 0.1.0a4
+Version: 0.1.0a5
 Summary: Tools for converting spreadsheet workbooks into transparent Python models.
 Author: UBC FRESH Lab
 License-Expression: MIT
@@ -32,11 +32,14 @@ Requires-Dist: sphinx-rtd-theme>=2; extra == "docs"
 Provides-Extra: dev
 Requires-Dist: build>=1.2; extra == "dev"
 Requires-Dist: formulas; extra == "dev"
+Requires-Dist: pandas>=2; extra == "dev"
 Requires-Dist: pytest>=8; extra == "dev"
 Requires-Dist: ruff>=0.8; extra == "dev"
 Requires-Dist: sphinx>=7; extra == "dev"
 Requires-Dist: sphinx-rtd-theme>=2; extra == "dev"
 Requires-Dist: twine>=5; extra == "dev"
+Provides-Extra: notebook
+Requires-Dist: pandas>=2; extra == "notebook"
 Provides-Extra: oracle
 Requires-Dist: formulas; extra == "oracle"
 Provides-Extra: quality
@@ -46,6 +49,7 @@ Requires-Dist: build>=1.2; extra == "release"
 Requires-Dist: twine>=5; extra == "release"
 Provides-Extra: test
 Requires-Dist: formulas; extra == "test"
+Requires-Dist: pandas>=2; extra == "test"
 Requires-Dist: pytest>=8; extra == "test"
 Dynamic: license-file
 
@@ -135,7 +139,7 @@ Restore the public external FABLE benchmark workbooks into ignored local paths:
 scripts/bootstrap_dev_env.sh --benchmarks
 ```
 
-`modelwright` is pre-release. The current alpha line is `0.1.0a4`; alpha releases must not be described as full-workbook conversion guarantees.
+`modelwright` is pre-release. The current alpha line is `0.1.0a5`; alpha releases must not be described as full-workbook conversion guarantees.
 
 Check release artifacts locally:
 

{modelwright-0.1.0a4 → modelwright-0.1.0a5}/README.md

@@ -84,7 +84,7 @@ Restore the public external FABLE benchmark workbooks into ignored local paths:
 scripts/bootstrap_dev_env.sh --benchmarks
 ```
 
-`modelwright` is pre-release. The current alpha line is `0.1.0a4`; alpha releases must not be described as full-workbook conversion guarantees.
+`modelwright` is pre-release. The current alpha line is `0.1.0a5`; alpha releases must not be described as full-workbook conversion guarantees.
 
 Check release artifacts locally:
 

modelwright-0.1.0a5/examples/README.md

@@ -0,0 +1,12 @@
+# Modelwright Examples
+
+These examples show how generated Modelwright Python models can be wrapped with analyst-facing
+facades and notebook-friendly DataFrame helpers.
+
+- `synthetic/`: a tiny generated-model example based on the tracked synthetic fixture shape.
+- `fable_2020/`: a production-size example using a compressed generated Python model converted from
+  the public 2020 FABLE Calculator benchmark workbook.
+
+The original FABLE workbook is not tracked here. The tracked FABLE example contains Modelwright's
+generated Python output, compressed as `generated_fable_2020_model.py.xz` because the uncompressed
+module is larger than ordinary GitHub per-file limits.

modelwright-0.1.0a5/examples/fable_2020/README.md

@@ -0,0 +1,21 @@
+# 2020 FABLE Generated Model Example
+
+This directory contains a compressed generated Python model produced by Modelwright from the public
+2020 FABLE Calculator benchmark workbook.
+
+The original workbook is not tracked in this repository. The generated model is tracked as
+`generated_fable_2020_model.py.xz` because the uncompressed Python module is about 117 MiB, which is
+larger than ordinary GitHub per-file limits. The example script decompresses it into ignored `tmp/`
+working space before importing it.
+
+The generated model preserves the P26 full-validation evidence boundary:
+
+- comparable cached outputs: 281,741;
+- matches: 281,741;
+- mismatches: 0.
+
+Run from the repository root:
+
+```bash
+python examples/fable_2020/notebook_interface.py
+```

modelwright-0.1.0a5/examples/fable_2020/notebook_interface.py

@@ -0,0 +1,95 @@
+"""Notebook-interface example for the generated 2020 FABLE benchmark model."""
+
+from __future__ import annotations
+
+import importlib.util
+import lzma
+import shutil
+import sys
+from pathlib import Path
+from types import ModuleType
+
+from modelwright.notebooks import outputs_frame, report_frames, table_frame
+from modelwright.wrappers import ModelFacade, cell, report, table
+
+
+EXAMPLE_DIR = Path(__file__).resolve().parent
+ARCHIVE_PATH = EXAMPLE_DIR / "generated_fable_2020_model.py.xz"
+WORK_DIR = Path("tmp/examples/fable_2020")
+MODEL_PATH = WORK_DIR / "generated_fable_2020_model.py"
+
+FABLE_SCENARIO_OUTPUTS = {
+    "SCENARIOS selection!D20": 2.146115426018433,
+    "SCENARIOS selection!D21": 1.8982220554032356,
+    "SCENARIOS selection!D22": 1.462761288724012,
+}
+
+
+def materialize_generated_model() -> Path:
+    """Decompress the tracked generated model into ignored local working space."""
+
+    WORK_DIR.mkdir(parents=True, exist_ok=True)
+    if not MODEL_PATH.exists():
+        with lzma.open(ARCHIVE_PATH, "rb") as source:
+            with MODEL_PATH.open("wb") as target:
+                shutil.copyfileobj(source, target)
+    return MODEL_PATH
+
+
+def load_generated_model(path: Path | None = None) -> ModuleType:
+    model_path = path or materialize_generated_model()
+    spec = importlib.util.spec_from_file_location("modelwright_example_fable_2020", model_path)
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"could not load generated model from {model_path}")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+def build_facade(module: ModuleType | None = None) -> ModelFacade:
+    generated_model = module or load_generated_model()
+    return ModelFacade(
+        generated_model,
+        cells=[
+            cell("SCENARIOS selection!D20", name="scenario_metric_1", role="output"),
+            cell("SCENARIOS selection!D21", name="scenario_metric_2", role="output"),
+            cell("SCENARIOS selection!D22", name="scenario_metric_3", role="output"),
+        ],
+        tables=[
+            table(
+                "scenario_selection_slice",
+                sheet="SCENARIOS selection",
+                range_ref="D20:D22",
+                row_labels=["d20", "d21", "d22"],
+                column_labels=["value"],
+            )
+        ],
+        reports=[
+            report(
+                "scenario_selection",
+                cells=["scenario_metric_1", "scenario_metric_2", "scenario_metric_3"],
+                tables=["scenario_selection_slice"],
+            )
+        ],
+    )
+
+
+def run_example():
+    facade = build_facade()
+    values = facade.calculate()
+    for cell_ref, expected in FABLE_SCENARIO_OUTPUTS.items():
+        observed = values[cell_ref]
+        if observed != expected:
+            raise RuntimeError(f"{cell_ref} expected {expected!r}, observed {observed!r}")
+    return {
+        "outputs": outputs_frame(facade),
+        "scenario_selection_slice": table_frame(facade, "scenario_selection_slice"),
+        "report": report_frames(facade, "scenario_selection"),
+    }
+
+
+if __name__ == "__main__":
+    frames = run_example()
+    print(frames["outputs"])
+    print(frames["scenario_selection_slice"])

modelwright-0.1.0a5/examples/synthetic/notebook_interface.py

@@ -0,0 +1,62 @@
+"""Tiny notebook-interface example for a generated Modelwright model."""
+
+from __future__ import annotations
+
+from modelwright.notebooks import compare_scenarios_frame, outputs_frame, table_frame
+from modelwright.wrappers import ModelFacade, cell, report, table
+
+
+def calculate(inputs=None):
+    """Small stand-in for generated Modelwright Python output."""
+
+    inputs = inputs or {}
+    base = inputs.get("Inputs!B2", 100)
+    growth = inputs.get("Inputs!B3", 0.1)
+    return {
+        "Summary!B2": base * (1 + growth),
+        "Summary!C2": base * 2,
+        "Summary!B3": "ok",
+        "Summary!C3": base + 5,
+    }
+
+
+def build_facade() -> ModelFacade:
+    return ModelFacade(
+        calculate,
+        cells=[
+            cell("Inputs!B2", name="base", label="Base volume", role="input", unit="t"),
+            cell("Inputs!B3", name="growth", label="Growth rate", role="input", unit="fraction"),
+            cell("Summary!B2", name="projected", label="Projected volume", role="output", unit="t"),
+            cell("Summary!B3", name="status", label="Status", role="output"),
+        ],
+        tables=[
+            table(
+                "summary_grid",
+                sheet="Summary",
+                range_ref="B2:C3",
+                row_labels=["volume", "status"],
+                column_labels=["primary", "secondary"],
+            )
+        ],
+        reports=[
+            report("summary", cells=["base", "projected", "status"], tables=["summary_grid"]),
+        ],
+    )
+
+
+def run_example():
+    facade = build_facade()
+    baseline = facade.scenario(name="baseline", inputs={"Inputs!B2": 100, "Inputs!B3": 0.1})
+    shock = baseline.with_input("Inputs!B2", 120)
+    return {
+        "outputs": outputs_frame(facade, shock),
+        "summary_grid": table_frame(facade, "summary_grid", shock),
+        "comparison": compare_scenarios_frame(facade, baseline, shock),
+    }
+
+
+if __name__ == "__main__":
+    frames = run_example()
+    for name, frame in frames.items():
+        print(f"\n{name}")
+        print(frame)

{modelwright-0.1.0a4 → modelwright-0.1.0a5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "modelwright"
-version = "0.1.0a4"
+version = "0.1.0a5"
 description = "Tools for converting spreadsheet workbooks into transparent Python models."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -56,12 +56,16 @@ docs = [
 dev = [
   "build>=1.2",
   "formulas",
+  "pandas>=2",
   "pytest>=8",
   "ruff>=0.8",
   "sphinx>=7",
   "sphinx-rtd-theme>=2",
   "twine>=5"
 ]
+notebook = [
+  "pandas>=2"
+]
 oracle = [
   "formulas"
 ]
@@ -74,6 +78,7 @@ release = [
 ]
 test = [
   "formulas",
+  "pandas>=2",
   "pytest>=8"
 ]
 

{modelwright-0.1.0a4 → modelwright-0.1.0a5}/src/modelwright/__init__.py

@@ -54,6 +54,15 @@ from modelwright.graph import (
     DependencyGraph,
     build_dependency_graph,
 )
+from modelwright.notebooks import (
+    NotebookDependencyError,
+    compare_scenarios_frame,
+    inputs_frame,
+    outputs_frame,
+    report_frames,
+    scenario_frame,
+    table_frame,
+)
 from modelwright.oracles import (
     OracleDiagnostic,
     OracleRequest,
@@ -95,7 +104,7 @@ from modelwright.wrappers import (
     table,
 )
 
-__version__ = "0.1.0a4"
+__version__ = "0.1.0a5"
 
 __all__ = [
     "CellRecord",
@@ -127,6 +136,7 @@ __all__ = [
     "MISSING_VALUE",
     "ModelFacade",
     "NamedRangeRecord",
+    "NotebookDependencyError",
     "OracleConfig",
     "OracleDiagnostic",
     "OracleRequest",
@@ -160,15 +170,21 @@ __all__ = [
     "build_validation_report",
     "cell",
     "compare_scalar_output",
+    "compare_scenarios_frame",
     "execute_generated_model",
     "evaluate_generated_model",
     "extract_workbook",
     "generate_python_module",
     "infer_generated_module_contract",
+    "inputs_frame",
     "load_validation_scenario",
     "normalize_cell_reference",
     "normalize_reference",
+    "outputs_frame",
     "report",
+    "report_frames",
+    "scenario_frame",
     "table",
+    "table_frame",
     "translate_formula_cell",
 ]

modelwright-0.1.0a5/src/modelwright/notebooks.py

@@ -0,0 +1,246 @@
+"""Notebook-friendly DataFrame helpers for wrapped generated models."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from numbers import Real
+from typing import TYPE_CHECKING, Any
+
+from modelwright.references import normalize_cell_reference
+from modelwright.wrappers import CellRef, ModelFacade, Scenario, WrapperDeclarationError
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+
+class NotebookDependencyError(RuntimeError):
+    """Raised when notebook helpers need an optional dependency that is not installed."""
+
+
+def inputs_frame(facade: ModelFacade, scenario: Scenario | None = None) -> "pd.DataFrame":
+    """Return declared facade inputs as a tidy pandas DataFrame."""
+
+    values = _values_for(facade, scenario)
+    return _cell_frame(facade.inputs().values(), values)
+
+
+def outputs_frame(facade: ModelFacade, scenario: Scenario | None = None) -> "pd.DataFrame":
+    """Return declared facade outputs as a tidy pandas DataFrame."""
+
+    values = _values_for(facade, scenario)
+    return _cell_frame(facade.outputs().values(), values)
+
+
+def scenario_frame(scenario: Scenario) -> "pd.DataFrame":
+    """Return scenario input overrides as a tidy pandas DataFrame."""
+
+    pd = _load_pandas()
+    return pd.DataFrame(
+        [
+            {
+                "scenario": scenario.name,
+                "cell_ref": cell_ref,
+                "value": value,
+            }
+            for cell_ref, value in scenario.inputs.items()
+        ],
+        columns=["scenario", "cell_ref", "value"],
+    )
+
+
+def table_frame(facade: ModelFacade, name: str, scenario: Scenario | None = None) -> "pd.DataFrame":
+    """Return a declared facade table as a pandas DataFrame."""
+
+    pd = _load_pandas()
+    table = facade.table(name, scenario=scenario)
+    frame = pd.DataFrame(table.values, index=list(table.rows), columns=list(table.columns))
+    frame.index.name = "row"
+    frame.attrs.update(
+        {
+            "name": table.name,
+            "label": table.label,
+            "description": table.description,
+            "sheet": table.sheet,
+            "range_ref": table.range_ref,
+            "cell_refs": [list(row) for row in table.cell_refs],
+        }
+    )
+    return frame
+
+
+def report_frames(facade: ModelFacade, name: str, scenario: Scenario | None = None) -> dict[str, Any]:
+    """Return DataFrame payloads for a declared facade report."""
+
+    report = facade.reports.get(name)
+    if report is None:
+        raise WrapperDeclarationError(f"unknown report declaration {name!r}")
+
+    values = _values_for(facade, scenario)
+    cells = [facade.cells[cell_name] for cell_name in report.cells]
+    return {
+        "name": report.name,
+        "label": report.label,
+        "description": report.description,
+        "cells": _cell_frame(cells, values),
+        "tables": {
+            table_name: table_frame(facade, table_name, scenario=scenario)
+            for table_name in report.tables
+        },
+    }
+
+
+def compare_scenarios_frame(
+    facade: ModelFacade,
+    baseline: Scenario,
+    scenario: Scenario,
+    *,
+    cells: Iterable[str] | None = None,
+) -> "pd.DataFrame":
+    """Compare declared output cells between two scenarios as a tidy DataFrame."""
+
+    baseline_values = _values_for(facade, baseline)
+    scenario_values = _values_for(facade, scenario)
+    declarations = _comparison_cells(facade, cells)
+
+    rows = []
+    for declaration in declarations:
+        baseline_value = baseline_values.get(declaration.cell_ref)
+        scenario_value = scenario_values.get(declaration.cell_ref)
+        absolute_change = _absolute_change(baseline_value, scenario_value)
+        rows.append(
+            {
+                "name": declaration.name,
+                "label": declaration.label,
+                "cell_ref": declaration.cell_ref,
+                "baseline_value": baseline_value,
+                "scenario_value": scenario_value,
+                "absolute_change": absolute_change,
+                "percent_change": _percent_change(baseline_value, absolute_change),
+                "unit": declaration.unit,
+                "role": declaration.role,
+                "description": declaration.description,
+            }
+        )
+
+    pd = _load_pandas()
+    return pd.DataFrame(
+        rows,
+        columns=[
+            "name",
+            "label",
+            "cell_ref",
+            "baseline_value",
+            "scenario_value",
+            "absolute_change",
+            "percent_change",
+            "unit",
+            "role",
+            "description",
+        ],
+        dtype=object,
+    )
+
+
+def _cell_frame(cells: Iterable[CellRef], values: Mapping[str, object]) -> "pd.DataFrame":
+    pd = _load_pandas()
+    return pd.DataFrame(
+        [
+            {
+                "name": declaration.name,
+                "label": declaration.label,
+                "cell_ref": declaration.cell_ref,
+                "role": declaration.role,
+                "unit": declaration.unit,
+                "description": declaration.description,
+                "value": values.get(declaration.cell_ref),
+                "has_value": declaration.cell_ref in values,
+            }
+            for declaration in cells
+        ],
+        columns=[
+            "name",
+            "label",
+            "cell_ref",
+            "role",
+            "unit",
+            "description",
+            "value",
+            "has_value",
+        ],
+    )
+
+
+def _comparison_cells(facade: ModelFacade, cells: Iterable[str] | None) -> list[CellRef]:
+    declarations_by_name = facade.cells
+    if cells is None:
+        return list(facade.outputs().values())
+
+    declarations = []
+    for selector in cells:
+        declaration = declarations_by_name.get(selector)
+        if declaration is not None:
+            declarations.append(declaration)
+            continue
+
+        normalized = _normalize_cell_ref(selector)
+        for candidate in declarations_by_name.values():
+            if candidate.cell_ref == normalized:
+                declarations.append(candidate)
+                break
+        else:
+            declarations.append(CellRef(cell_ref=normalized, name=normalized))
+    return declarations
+
+
+def _values_for(facade: ModelFacade, scenario: Scenario | None) -> dict[str, object]:
+    facade_values_for = getattr(facade, "_values_for", None)
+    if callable(facade_values_for):
+        return dict(facade_values_for(scenario))
+
+    active_scenario = scenario or facade.scenario()
+    values = facade.calculate(active_scenario)
+    return {**active_scenario.inputs, **values}
+
+
+def _normalize_cell_ref(cell_ref: str) -> str:
+    normalized = normalize_cell_reference(cell_ref)
+    if normalized.kind != "cell" or normalized.sheet is None:
+        raise WrapperDeclarationError(f"expected a full cell reference like 'Sheet!A1', got {cell_ref!r}")
+    return normalized.normalized
+
+
+def _absolute_change(baseline_value: object, scenario_value: object) -> float | int | None:
+    if _is_number(baseline_value) and _is_number(scenario_value):
+        return scenario_value - baseline_value
+    return None
+
+
+def _percent_change(baseline_value: object, absolute_change: object) -> float | None:
+    if _is_number(baseline_value) and baseline_value != 0 and _is_number(absolute_change):
+        return absolute_change / baseline_value
+    return None
+
+
+def _is_number(value: object) -> bool:
+    return isinstance(value, Real) and not isinstance(value, bool)
+
+
+def _load_pandas() -> Any:
+    try:
+        import pandas as pd
+    except ImportError as error:
+        raise NotebookDependencyError(
+            "Install modelwright[notebook] to use pandas-backed notebook helpers."
+        ) from error
+    return pd
+
+
+__all__ = [
+    "NotebookDependencyError",
+    "compare_scenarios_frame",
+    "inputs_frame",
+    "outputs_frame",
+    "report_frames",
+    "scenario_frame",
+    "table_frame",
+]

{modelwright-0.1.0a4 → modelwright-0.1.0a5/src/modelwright.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modelwright
-Version: 0.1.0a4
+Version: 0.1.0a5
 Summary: Tools for converting spreadsheet workbooks into transparent Python models.
 Author: UBC FRESH Lab
 License-Expression: MIT
@@ -32,11 +32,14 @@ Requires-Dist: sphinx-rtd-theme>=2; extra == "docs"
 Provides-Extra: dev
 Requires-Dist: build>=1.2; extra == "dev"
 Requires-Dist: formulas; extra == "dev"
+Requires-Dist: pandas>=2; extra == "dev"
 Requires-Dist: pytest>=8; extra == "dev"
 Requires-Dist: ruff>=0.8; extra == "dev"
 Requires-Dist: sphinx>=7; extra == "dev"
 Requires-Dist: sphinx-rtd-theme>=2; extra == "dev"
 Requires-Dist: twine>=5; extra == "dev"
+Provides-Extra: notebook
+Requires-Dist: pandas>=2; extra == "notebook"
 Provides-Extra: oracle
 Requires-Dist: formulas; extra == "oracle"
 Provides-Extra: quality
@@ -46,6 +49,7 @@ Requires-Dist: build>=1.2; extra == "release"
 Requires-Dist: twine>=5; extra == "release"
 Provides-Extra: test
 Requires-Dist: formulas; extra == "test"
+Requires-Dist: pandas>=2; extra == "test"
 Requires-Dist: pytest>=8; extra == "test"
 Dynamic: license-file
 
@@ -135,7 +139,7 @@ Restore the public external FABLE benchmark workbooks into ignored local paths:
 scripts/bootstrap_dev_env.sh --benchmarks
 ```
 
-`modelwright` is pre-release. The current alpha line is `0.1.0a4`; alpha releases must not be described as full-workbook conversion guarantees.
+`modelwright` is pre-release. The current alpha line is `0.1.0a5`; alpha releases must not be described as full-workbook conversion guarantees.
 
 Check release artifacts locally:
 

{modelwright-0.1.0a4 → modelwright-0.1.0a5}/src/modelwright.egg-info/SOURCES.txt

@@ -1,6 +1,12 @@
 LICENSE
+MANIFEST.in
 README.md
 pyproject.toml
+examples/README.md
+examples/fable_2020/README.md
+examples/fable_2020/generated_fable_2020_model.py.xz
+examples/fable_2020/notebook_interface.py
+examples/synthetic/notebook_interface.py
 src/modelwright/__init__.py
 src/modelwright/cli.py
 src/modelwright/conversion.py
@@ -11,6 +17,7 @@ src/modelwright/formulas.py
 src/modelwright/formulas_oracle.py
 src/modelwright/generation.py
 src/modelwright/graph.py
+src/modelwright/notebooks.py
 src/modelwright/oracle_validation.py
 src/modelwright/oracles.py
 src/modelwright/references.py
@@ -26,6 +33,7 @@ tests/test_cli.py
 tests/test_conversion_plan.py
 tests/test_dependency_graph.py
 tests/test_evaluation_orchestration.py
+tests/test_examples.py
 tests/test_extraction_records.py
 tests/test_fable_wrapper_benchmark.py
 tests/test_formula_expressions.py
@@ -35,6 +43,7 @@ tests/test_generated_execution.py
 tests/test_generation_contract.py
 tests/test_import.py
 tests/test_materialize_fable_benchmarks.py
+tests/test_notebooks.py
 tests/test_openpyxl_extraction.py
 tests/test_oracle_backed_validation.py
 tests/test_oracle_interface.py

{modelwright-0.1.0a4 → modelwright-0.1.0a5}/src/modelwright.egg-info/requires.txt

@@ -5,6 +5,7 @@ typer>=0.9
 [dev]
 build>=1.2
 formulas
+pandas>=2
 pytest>=8
 ruff>=0.8
 sphinx>=7
@@ -15,6 +16,9 @@ twine>=5
 sphinx>=7
 sphinx-rtd-theme>=2
 
+[notebook]
+pandas>=2
+
 [oracle]
 formulas
 
@@ -27,4 +31,5 @@ twine>=5
 
 [test]
 formulas
+pandas>=2
 pytest>=8

modelwright-0.1.0a5/tests/test_examples.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import importlib.util
+import lzma
+from pathlib import Path
+from types import ModuleType
+
+import pytest
+
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def load_example(path: Path, module_name: str) -> ModuleType:
+    spec = importlib.util.spec_from_file_location(module_name, path)
+    assert spec is not None
+    assert spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def test_synthetic_notebook_example_runs() -> None:
+    module = load_example(ROOT / "examples/synthetic/notebook_interface.py", "synthetic_notebook_example")
+
+    frames = module.run_example()
+
+    assert frames["outputs"].set_index("name").loc["projected", "value"] == 132.0
+    assert frames["summary_grid"].loc["volume", "primary"] == 132.0
+    assert frames["comparison"].set_index("name").loc["projected", "absolute_change"] == pytest.approx(22.0)
+
+
+def test_fable_generated_model_archive_is_tracked_and_readable() -> None:
+    archive_path = ROOT / "examples/fable_2020/generated_fable_2020_model.py.xz"
+
+    assert archive_path.exists()
+    assert archive_path.stat().st_size < 10_000_000
+    with lzma.open(archive_path, "rb") as archive:
+        prefix = archive.read(128)
+
+    assert b"Generated Modelwright model" in prefix

{modelwright-0.1.0a4 → modelwright-0.1.0a5}/tests/test_fable_wrapper_benchmark.py

@@ -9,6 +9,7 @@ from types import ModuleType
 
 import pytest
 
+from modelwright.notebooks import outputs_frame, report_frames, table_frame
 from modelwright.wrappers import ModelFacade, cell, report, table
 
 
@@ -87,3 +88,24 @@ def test_model_facade_wraps_2020_fable_benchmark_model_outputs() -> None:
     assert report_payload["tables"]["scenario_selection_slice"]["values"][2][0] == pytest.approx(
         FABLE_SCENARIO_OUTPUTS["SCENARIOS selection!D22"]
     )
+
+    output_rows = outputs_frame(facade).set_index("cell_ref")
+    assert output_rows.loc["SCENARIOS selection!D20", "value"] == pytest.approx(
+        FABLE_SCENARIO_OUTPUTS["SCENARIOS selection!D20"]
+    )
+
+    table_rows = table_frame(facade, "scenario_selection_slice")
+    assert table_rows.loc["d21", "value"] == pytest.approx(FABLE_SCENARIO_OUTPUTS["SCENARIOS selection!D21"])
+    assert table_rows.attrs["cell_refs"] == [
+        ["SCENARIOS selection!D20"],
+        ["SCENARIOS selection!D21"],
+        ["SCENARIOS selection!D22"],
+    ]
+
+    frames = report_frames(facade, "scenario_selection")
+    assert frames["cells"].set_index("name").loc["scenario_metric_3", "value"] == pytest.approx(
+        FABLE_SCENARIO_OUTPUTS["SCENARIOS selection!D22"]
+    )
+    assert frames["tables"]["scenario_selection_slice"].loc["d20", "value"] == pytest.approx(
+        FABLE_SCENARIO_OUTPUTS["SCENARIOS selection!D20"]
+    )

{modelwright-0.1.0a4 → modelwright-0.1.0a5}/tests/test_import.py

@@ -2,4 +2,4 @@ import modelwright
 
 
 def test_package_imports() -> None:
-    assert modelwright.__version__ == "0.1.0a4"
+    assert modelwright.__version__ == "0.1.0a5"

modelwright-0.1.0a5/tests/test_notebooks.py

@@ -0,0 +1,211 @@
+from __future__ import annotations
+
+import builtins
+import importlib
+from pathlib import Path
+
+import pytest
+
+from modelwright.notebooks import (
+    NotebookDependencyError,
+    compare_scenarios_frame,
+    inputs_frame,
+    outputs_frame,
+    report_frames,
+    scenario_frame,
+    table_frame,
+)
+from modelwright.wrappers import ModelFacade, cell, report, table
+from tests.test_wrappers import build_generated_synthetic_model
+
+
+def generated_model(inputs=None):
+    inputs = inputs or {}
+    base = inputs.get("Inputs!B2", 100)
+    growth = inputs.get("Inputs!B3", 0.1)
+    return {
+        "Summary!B2": base * (1 + growth),
+        "Summary!C2": base * 2,
+        "Summary!B3": "ok",
+        "Summary!C3": base + 5,
+    }
+
+
+def notebook_facade(generated=generated_model) -> ModelFacade:
+    return ModelFacade(
+        generated,
+        cells=[
+            cell("Inputs!B2", name="base", label="Base volume", role="input", unit="t"),
+            cell("Inputs!B3", name="growth", label="Growth rate", role="input", unit="fraction"),
+            cell("Summary!B2", name="projected", label="Projected volume", role="output", unit="t"),
+            cell("Summary!B3", name="status", label="Status", role="output"),
+        ],
+        tables=[
+            table(
+                "summary_grid",
+                sheet="Summary",
+                range_ref="B2:C3",
+                row_labels=["volume", "status"],
+                column_labels=["primary", "secondary"],
+            )
+        ],
+        reports=[report("summary", cells=["base", "projected", "status"], tables=["summary_grid"])],
+    )
+
+
+def test_notebook_frames_expose_declared_inputs_outputs_tables_and_reports() -> None:
+    facade = notebook_facade()
+    scenario = facade.scenario(name="shock", inputs={"Inputs!B2": 50}).with_input("Inputs!B3", 0.2)
+
+    input_rows = inputs_frame(facade, scenario)
+    assert input_rows.to_dict("records") == [
+        {
+            "name": "base",
+            "label": "Base volume",
+            "cell_ref": "Inputs!B2",
+            "role": "input",
+            "unit": "t",
+            "description": None,
+            "value": 50,
+            "has_value": True,
+        },
+        {
+            "name": "growth",
+            "label": "Growth rate",
+            "cell_ref": "Inputs!B3",
+            "role": "input",
+            "unit": "fraction",
+            "description": None,
+            "value": 0.2,
+            "has_value": True,
+        },
+    ]
+
+    output_rows = outputs_frame(facade, scenario)
+    assert output_rows[["name", "cell_ref", "value", "has_value"]].to_dict("records") == [
+        {"name": "projected", "cell_ref": "Summary!B2", "value": 60.0, "has_value": True},
+        {"name": "status", "cell_ref": "Summary!B3", "value": "ok", "has_value": True},
+    ]
+
+    scenario_rows = scenario_frame(scenario)
+    assert scenario_rows.to_dict("records") == [
+        {"scenario": "shock", "cell_ref": "Inputs!B2", "value": 50},
+        {"scenario": "shock", "cell_ref": "Inputs!B3", "value": 0.2},
+    ]
+
+    summary_grid = table_frame(facade, "summary_grid", scenario)
+    assert list(summary_grid.index) == ["volume", "status"]
+    assert list(summary_grid.columns) == ["primary", "secondary"]
+    assert summary_grid.loc["volume", "primary"] == 60.0
+    assert summary_grid.loc["status", "secondary"] == 55
+    assert summary_grid.attrs["sheet"] == "Summary"
+    assert summary_grid.attrs["range_ref"] == "B2:C3"
+    assert summary_grid.attrs["cell_refs"] == [["Summary!B2", "Summary!C2"], ["Summary!B3", "Summary!C3"]]
+
+    frames = report_frames(facade, "summary", scenario)
+    assert frames["name"] == "summary"
+    assert frames["cells"][["name", "value"]].to_dict("records") == [
+        {"name": "base", "value": 50},
+        {"name": "projected", "value": 60.0},
+        {"name": "status", "value": "ok"},
+    ]
+    assert frames["tables"]["summary_grid"].loc["volume", "secondary"] == 100
+
+
+def test_compare_scenarios_frame_handles_numeric_text_and_zero_baseline() -> None:
+    def comparison_model(inputs=None):
+        inputs = inputs or {}
+        base = inputs.get("Inputs!B2", 100)
+        multiplier = inputs.get("Inputs!B3", 1)
+        return {
+            "Summary!B2": base * multiplier,
+            "Summary!B3": "ok" if multiplier == 1 else "changed",
+            "Summary!B4": base - 100,
+        }
+
+    facade = ModelFacade(
+        comparison_model,
+        cells=[
+            cell("Inputs!B2", name="base", role="input"),
+            cell("Inputs!B3", name="multiplier", role="input"),
+            cell("Summary!B2", name="projected", label="Projected volume", role="output", unit="t"),
+            cell("Summary!B3", name="status", label="Status", role="output"),
+            cell("Summary!B4", name="delta", label="Delta", role="output"),
+        ],
+    )
+
+    baseline = facade.scenario(name="baseline", inputs={"Inputs!B2": 100, "Inputs!B3": 1})
+    shock = baseline.with_input("Inputs!B3", 1.2)
+    comparison = compare_scenarios_frame(facade, baseline, shock)
+
+    projected = comparison.set_index("name").loc["projected"]
+    assert projected["baseline_value"] == 100
+    assert projected["scenario_value"] == 120
+    assert projected["absolute_change"] == 20
+    assert projected["percent_change"] == pytest.approx(0.2)
+
+    status = comparison.set_index("name").loc["status"]
+    assert status["baseline_value"] == "ok"
+    assert status["scenario_value"] == "changed"
+    assert status["absolute_change"] is None
+    assert status["percent_change"] is None
+
+    delta = comparison.set_index("name").loc["delta"]
+    assert delta["baseline_value"] == 0
+    assert delta["scenario_value"] == 0
+    assert delta["absolute_change"] == 0
+    assert delta["percent_change"] is None
+
+
+def test_notebook_helpers_preserve_real_generated_synthetic_model_semantics(tmp_path: Path) -> None:
+    module = build_generated_synthetic_model(tmp_path)
+    facade = ModelFacade(
+        module,
+        cells=[
+            cell("Inputs!B2", name="base", label="Base volume", role="input"),
+            cell("Summary!B2", name="harvest", label="Rounded harvest", role="output"),
+            cell("Summary!B3", name="status", label="Status", role="output"),
+        ],
+        tables=[
+            table(
+                "summary",
+                sheet="Summary",
+                range_ref="B2:B3",
+                row_labels=["harvest", "status"],
+                column_labels=["value"],
+            )
+        ],
+    )
+    scenario = facade.scenario(name="low-volume", inputs={"Inputs!B2": 10})
+
+    assert facade.calculate(scenario) == module.calculate(scenario.inputs)
+    assert outputs_frame(facade, scenario).set_index("name").loc["harvest", "value"] == 7.02
+    assert table_frame(facade, "summary", scenario).loc["status", "value"] == "low"
+
+
+def test_modelwright_import_does_not_require_pandas(monkeypatch: pytest.MonkeyPatch) -> None:
+    real_import = builtins.__import__
+
+    def guarded_import(name, globals=None, locals=None, fromlist=(), level=0):
+        if name == "pandas":
+            raise ModuleNotFoundError("No module named 'pandas'")
+        return real_import(name, globals, locals, fromlist, level)
+
+    monkeypatch.setattr(builtins, "__import__", guarded_import)
+    module = importlib.reload(importlib.import_module("modelwright"))
+
+    assert "inputs_frame" in module.__all__
+
+
+def test_notebook_helpers_report_missing_pandas(monkeypatch: pytest.MonkeyPatch) -> None:
+    real_import = builtins.__import__
+
+    def guarded_import(name, globals=None, locals=None, fromlist=(), level=0):
+        if name == "pandas":
+            raise ModuleNotFoundError("No module named 'pandas'")
+        return real_import(name, globals, locals, fromlist, level)
+
+    monkeypatch.setattr(builtins, "__import__", guarded_import)
+
+    with pytest.raises(NotebookDependencyError, match=r"modelwright\[notebook\]"):
+        scenario_frame(notebook_facade().scenario())

{modelwright-0.1.0a4 → modelwright-0.1.0a5}/tests/test_public_api.py

@@ -21,6 +21,10 @@ def test_root_facade_exports_primary_entrypoints() -> None:
     assert "cell" in modelwright.__all__
     assert "table" in modelwright.__all__
     assert "report" in modelwright.__all__
+    assert "inputs_frame" in modelwright.__all__
+    assert "outputs_frame" in modelwright.__all__
+    assert "table_frame" in modelwright.__all__
+    assert "compare_scenarios_frame" in modelwright.__all__
 
 
 def test_root_facade_does_not_export_internal_helpers() -> None: