modelwright 0.1.0a3__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.0a3/src/modelwright.egg-info → modelwright-0.1.0a5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modelwright
-Version: 0.1.0a3
+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.0a3`; 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.0a3 → 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.0a3`; 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.0a3 → modelwright-0.1.0a5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "modelwright"
-version = "0.1.0a3"
+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"
 ]
 
@@ -82,6 +87,9 @@ where = ["src"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+markers = [
+  "benchmark: tests that require local benchmark artifacts and are skipped unless explicitly enabled"
+]
 
 [tool.ruff]
 line-length = 120

{modelwright-0.1.0a3 → 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,
@@ -80,11 +89,27 @@ from modelwright.validation import (
     compare_scalar_output,
     load_validation_scenario,
 )
+from modelwright.wrappers import (
+    CellRef,
+    CellView,
+    ModelFacade,
+    ReportRef,
+    Scenario,
+    TableRef,
+    TableView,
+    WrapperDeclarationError,
+    WrapperExecutionError,
+    cell,
+    report,
+    table,
+)
 
-__version__ = "0.1.0a3"
+__version__ = "0.1.0a5"
 
 __all__ = [
     "CellRecord",
+    "CellRef",
+    "CellView",
     "ComparisonResult",
     "ComparisonRules",
     "ConversionPlan",
@@ -109,7 +134,9 @@ __all__ = [
     "GenerationDiagnostic",
     "GenerationResult",
     "MISSING_VALUE",
+    "ModelFacade",
     "NamedRangeRecord",
+    "NotebookDependencyError",
     "OracleConfig",
     "OracleDiagnostic",
     "OracleRequest",
@@ -117,10 +144,14 @@ __all__ = [
     "PlanRecommendation",
     "PrivacyReview",
     "ResidualBlocker",
+    "ReportRef",
+    "Scenario",
     "ScenarioInput",
     "ScenarioOutput",
     "SheetRecord",
+    "TableRef",
     "TableRecord",
+    "TableView",
     "ValidationReport",
     "ValidationEvaluationResult",
     "ValidationScenario",
@@ -129,20 +160,31 @@ __all__ = [
     "WorkbookReference",
     "WorkbookRecord",
     "WorkflowStatus",
+    "WrapperDeclarationError",
+    "WrapperExecutionError",
     "__version__",
     "build_dependency_graph",
     "build_conversion_plan",
     "build_formula_reference_index",
     "build_oracle_validation_report",
     "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",
+]