modelwright 0.1.0a3__tar.gz → 0.1.0a4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modelwright
-Version: 0.1.0a3
+Version: 0.1.0a4
 Summary: Tools for converting spreadsheet workbooks into transparent Python models.
 Author: UBC FRESH Lab
 License-Expression: MIT
@@ -135,7 +135,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.0a4`; alpha releases must not be described as full-workbook conversion guarantees.
 
 Check release artifacts locally:
 

{modelwright-0.1.0a3 → modelwright-0.1.0a4}/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.0a4`; alpha releases must not be described as full-workbook conversion guarantees.
 
 Check release artifacts locally:
 

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "modelwright"
-version = "0.1.0a3"
+version = "0.1.0a4"
 description = "Tools for converting spreadsheet workbooks into transparent Python models."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -82,6 +82,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.0a4}/src/modelwright/__init__.py

@@ -80,11 +80,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.0a4"
 
 __all__ = [
     "CellRecord",
+    "CellRef",
+    "CellView",
     "ComparisonResult",
     "ComparisonRules",
     "ConversionPlan",
@@ -109,6 +125,7 @@ __all__ = [
     "GenerationDiagnostic",
     "GenerationResult",
     "MISSING_VALUE",
+    "ModelFacade",
     "NamedRangeRecord",
     "OracleConfig",
     "OracleDiagnostic",
@@ -117,10 +134,14 @@ __all__ = [
     "PlanRecommendation",
     "PrivacyReview",
     "ResidualBlocker",
+    "ReportRef",
+    "Scenario",
     "ScenarioInput",
     "ScenarioOutput",
     "SheetRecord",
+    "TableRef",
     "TableRecord",
+    "TableView",
     "ValidationReport",
     "ValidationEvaluationResult",
     "ValidationScenario",
@@ -129,12 +150,15 @@ __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",
     "execute_generated_model",
     "evaluate_generated_model",
@@ -144,5 +168,7 @@ __all__ = [
     "load_validation_scenario",
     "normalize_cell_reference",
     "normalize_reference",
+    "report",
+    "table",
     "translate_formula_cell",
 ]

modelwright-0.1.0a4/src/modelwright/wrappers.py

@@ -0,0 +1,426 @@
+"""Lightweight facades for generated Modelwright models."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from types import ModuleType
+from typing import Any, Literal
+
+from openpyxl.utils import get_column_letter
+from openpyxl.utils.cell import column_index_from_string, range_boundaries
+
+from modelwright.references import normalize_cell_reference, normalize_reference
+
+
+CellRole = Literal["input", "output", "intermediate", "metadata"]
+GeneratedCalculate = Callable[[dict[str, object] | None], dict[str, object]]
+
+
+class WrapperDeclarationError(ValueError):
+    """Raised when wrapper declarations are malformed or inconsistent."""
+
+
+class WrapperExecutionError(RuntimeError):
+    """Raised when a generated model cannot be executed through a facade."""
+
+
+@dataclass(frozen=True)
+class CellRef:
+    """Declared facade metadata for one generated-model cell reference."""
+
+    cell_ref: str
+    name: str
+    label: str | None = None
+    role: CellRole = "metadata"
+    unit: str | None = None
+    description: str | None = None
+
+
+@dataclass(frozen=True)
+class TableRef:
+    """Declared rectangular workbook-like table facade."""
+
+    name: str
+    sheet: str
+    range_ref: str
+    cell_refs: tuple[tuple[str, ...], ...]
+    row_labels: tuple[str, ...]
+    column_labels: tuple[str, ...]
+    role: CellRole = "output"
+    label: str | None = None
+    description: str | None = None
+
+
+@dataclass(frozen=True)
+class ReportRef:
+    """Declared named output bundle."""
+
+    name: str
+    cells: tuple[str, ...] = ()
+    tables: tuple[str, ...] = ()
+    label: str | None = None
+    description: str | None = None
+
+
+@dataclass(frozen=True)
+class CellView:
+    """Inspection payload for one cell in a facade scenario."""
+
+    cell_ref: str
+    name: str | None = None
+    label: str | None = None
+    role: CellRole | None = None
+    unit: str | None = None
+    description: str | None = None
+    value: object = None
+    has_value: bool = False
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "cell_ref": self.cell_ref,
+            "name": self.name,
+            "label": self.label,
+            "role": self.role,
+            "unit": self.unit,
+            "description": self.description,
+            "value": self.value,
+            "has_value": self.has_value,
+        }
+
+
+@dataclass(frozen=True)
+class TableView:
+    """Calculated rectangular table payload."""
+
+    name: str
+    sheet: str
+    range_ref: str
+    rows: tuple[str, ...]
+    columns: tuple[str, ...]
+    cell_refs: tuple[tuple[str, ...], ...]
+    values: tuple[tuple[object, ...], ...]
+    label: str | None = None
+    description: str | None = None
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "name": self.name,
+            "sheet": self.sheet,
+            "range_ref": self.range_ref,
+            "rows": list(self.rows),
+            "columns": list(self.columns),
+            "cell_refs": [list(row) for row in self.cell_refs],
+            "values": [list(row) for row in self.values],
+            "label": self.label,
+            "description": self.description,
+        }
+
+
+@dataclass(frozen=True)
+class Scenario:
+    """Immutable input override set for a facade calculation."""
+
+    name: str = "default"
+    _inputs: tuple[tuple[str, object], ...] = field(default_factory=tuple)
+
+    @classmethod
+    def from_inputs(cls, name: str = "default", inputs: Mapping[str, object] | None = None) -> "Scenario":
+        if inputs is None:
+            return cls(name=name)
+        normalized = {normalize_full_cell_ref(cell_ref): value for cell_ref, value in inputs.items()}
+        return cls(name=name, _inputs=tuple(normalized.items()))
+
+    @property
+    def inputs(self) -> dict[str, object]:
+        return dict(self._inputs)
+
+    def with_input(self, cell_ref: str, value: object) -> "Scenario":
+        inputs = self.inputs
+        inputs[normalize_full_cell_ref(cell_ref)] = value
+        return Scenario.from_inputs(name=self.name, inputs=inputs)
+
+
+def cell(
+    cell_ref: str,
+    *,
+    name: str | None = None,
+    label: str | None = None,
+    role: CellRole = "metadata",
+    unit: str | None = None,
+    description: str | None = None,
+) -> CellRef:
+    """Declare one facade cell."""
+
+    normalized = normalize_full_cell_ref(cell_ref)
+    return CellRef(
+        cell_ref=normalized,
+        name=name or normalized,
+        label=label,
+        role=role,
+        unit=unit,
+        description=description,
+    )
+
+
+def table(
+    name: str,
+    *,
+    sheet: str | None = None,
+    range_ref: str,
+    row_labels: tuple[str, ...] | list[str] | None = None,
+    column_labels: tuple[str, ...] | list[str] | None = None,
+    role: CellRole = "output",
+    label: str | None = None,
+    description: str | None = None,
+) -> TableRef:
+    """Declare one rectangular facade table."""
+
+    table_sheet, coordinate = normalize_table_range(sheet=sheet, range_ref=range_ref)
+    min_col, min_row, max_col, max_row = range_boundaries(coordinate)
+    row_count = max_row - min_row + 1
+    column_count = max_col - min_col + 1
+
+    rows = tuple(row_labels) if row_labels is not None else tuple(str(row) for row in range(min_row, max_row + 1))
+    columns = (
+        tuple(column_labels)
+        if column_labels is not None
+        else tuple(get_column_letter(column) for column in range(min_col, max_col + 1))
+    )
+    if len(rows) != row_count:
+        raise WrapperDeclarationError(
+            f"table {name!r} declares {len(rows)} row labels for {row_count} table rows"
+        )
+    if len(columns) != column_count:
+        raise WrapperDeclarationError(
+            f"table {name!r} declares {len(columns)} column labels for {column_count} table columns"
+        )
+
+    cell_refs = tuple(
+        tuple(f"{table_sheet}!{get_column_letter(column)}{row}" for column in range(min_col, max_col + 1))
+        for row in range(min_row, max_row + 1)
+    )
+    normalized_range = f"{get_column_letter(min_col)}{min_row}:{get_column_letter(max_col)}{max_row}"
+    return TableRef(
+        name=name,
+        sheet=table_sheet,
+        range_ref=normalized_range,
+        cell_refs=cell_refs,
+        row_labels=rows,
+        column_labels=columns,
+        role=role,
+        label=label,
+        description=description,
+    )
+
+
+def report(
+    name: str,
+    *,
+    cells: tuple[str, ...] | list[str] = (),
+    tables: tuple[str, ...] | list[str] = (),
+    label: str | None = None,
+    description: str | None = None,
+) -> ReportRef:
+    """Declare one structured report selection."""
+
+    return ReportRef(
+        name=name,
+        cells=tuple(cells),
+        tables=tuple(tables),
+        label=label,
+        description=description,
+    )
+
+
+class ModelFacade:
+    """Analyst-facing facade around a generated Modelwright model."""
+
+    def __init__(
+        self,
+        generated_model: ModuleType | GeneratedCalculate | object,
+        *,
+        cells: tuple[CellRef, ...] | list[CellRef] = (),
+        tables: tuple[TableRef, ...] | list[TableRef] = (),
+        reports: tuple[ReportRef, ...] | list[ReportRef] = (),
+    ) -> None:
+        self._calculate = generated_calculate(generated_model)
+        self._cells = keyed_declarations(cells, kind="cell")
+        self._cells_by_ref = {declaration.cell_ref: declaration for declaration in self._cells.values()}
+        self._tables = keyed_declarations(tables, kind="table")
+        self._reports = keyed_declarations(reports, kind="report")
+        self._last_scenario: Scenario | None = None
+        self._last_inputs: dict[str, object] = {}
+        self._last_values: dict[str, object] | None = None
+        self._validate_reports()
+
+    @property
+    def cells(self) -> dict[str, CellRef]:
+        return dict(self._cells)
+
+    @property
+    def tables(self) -> dict[str, TableRef]:
+        return dict(self._tables)
+
+    @property
+    def reports(self) -> dict[str, ReportRef]:
+        return dict(self._reports)
+
+    def inputs(self) -> dict[str, CellRef]:
+        return {
+            name: declaration
+            for name, declaration in self._cells.items()
+            if declaration.role == "input"
+        }
+
+    def outputs(self) -> dict[str, CellRef]:
+        return {
+            name: declaration
+            for name, declaration in self._cells.items()
+            if declaration.role == "output"
+        }
+
+    def scenario(self, name: str = "default", inputs: Mapping[str, object] | None = None) -> Scenario:
+        return Scenario.from_inputs(name=name, inputs=inputs)
+
+    def calculate(self, scenario: Scenario | None = None) -> dict[str, object]:
+        scenario = scenario or Scenario()
+        try:
+            values = self._calculate(scenario.inputs)
+        except Exception as error:  # noqa: BLE001
+            raise WrapperExecutionError(f"generated model calculation failed: {error!r}") from error
+        if not isinstance(values, dict):
+            raise WrapperExecutionError("generated model calculate() did not return a dictionary")
+        self._last_scenario = scenario
+        self._last_inputs = scenario.inputs
+        self._last_values = dict(values)
+        return dict(values)
+
+    def inspect(self, cell_ref: str, scenario: Scenario | None = None) -> CellView:
+        normalized = normalize_full_cell_ref(cell_ref)
+        values = self._values_for(scenario)
+        declaration = self._cells_by_ref.get(normalized)
+        has_value = normalized in values
+        return CellView(
+            cell_ref=normalized,
+            name=declaration.name if declaration else None,
+            label=declaration.label if declaration else None,
+            role=declaration.role if declaration else None,
+            unit=declaration.unit if declaration else None,
+            description=declaration.description if declaration else None,
+            value=values.get(normalized),
+            has_value=has_value,
+        )
+
+    def table(self, name: str, scenario: Scenario | None = None) -> TableView:
+        declaration = self._tables.get(name)
+        if declaration is None:
+            raise WrapperDeclarationError(f"unknown table declaration {name!r}")
+        values = self._values_for(scenario)
+        table_values = tuple(
+            tuple(values.get(cell_ref) for cell_ref in row)
+            for row in declaration.cell_refs
+        )
+        return TableView(
+            name=declaration.name,
+            sheet=declaration.sheet,
+            range_ref=declaration.range_ref,
+            rows=declaration.row_labels,
+            columns=declaration.column_labels,
+            cell_refs=declaration.cell_refs,
+            values=table_values,
+            label=declaration.label,
+            description=declaration.description,
+        )
+
+    def report(self, name: str, scenario: Scenario | None = None) -> dict[str, object]:
+        declaration = self._reports.get(name)
+        if declaration is None:
+            raise WrapperDeclarationError(f"unknown report declaration {name!r}")
+        cell_payloads = {}
+        for cell_name in declaration.cells:
+            cell_declaration = self._cells.get(cell_name)
+            if cell_declaration is None:
+                raise WrapperDeclarationError(f"report {name!r} references unknown cell {cell_name!r}")
+            cell_payloads[cell_name] = self.inspect(cell_declaration.cell_ref, scenario=scenario).to_dict()
+        table_payloads = {
+            table_name: self.table(table_name, scenario=scenario).to_dict()
+            for table_name in declaration.tables
+        }
+        return {
+            "name": declaration.name,
+            "label": declaration.label,
+            "description": declaration.description,
+            "cells": cell_payloads,
+            "tables": table_payloads,
+        }
+
+    def _values_for(self, scenario: Scenario | None) -> dict[str, object]:
+        if scenario is None and self._last_values is not None:
+            return {**self._last_inputs, **self._last_values}
+        active_scenario = scenario or Scenario()
+        values = self.calculate(active_scenario)
+        return {**active_scenario.inputs, **values}
+
+    def _validate_reports(self) -> None:
+        for report_declaration in self._reports.values():
+            for cell_name in report_declaration.cells:
+                if cell_name not in self._cells:
+                    raise WrapperDeclarationError(
+                        f"report {report_declaration.name!r} references unknown cell {cell_name!r}"
+                    )
+            for table_name in report_declaration.tables:
+                if table_name not in self._tables:
+                    raise WrapperDeclarationError(
+                        f"report {report_declaration.name!r} references unknown table {table_name!r}"
+                    )
+
+
+def generated_calculate(generated_model: ModuleType | GeneratedCalculate | object) -> GeneratedCalculate:
+    if callable(generated_model):
+        return generated_model
+    calculate = getattr(generated_model, "calculate", None)
+    if callable(calculate):
+        return calculate
+    raise WrapperDeclarationError("generated model must be callable or expose a callable calculate()")
+
+
+def keyed_declarations(declarations: tuple[Any, ...] | list[Any], *, kind: str) -> dict[str, Any]:
+    keyed: dict[str, Any] = {}
+    for declaration in declarations:
+        name = getattr(declaration, "name", None)
+        if not isinstance(name, str) or not name:
+            raise WrapperDeclarationError(f"{kind} declaration is missing a non-empty name")
+        if name in keyed:
+            raise WrapperDeclarationError(f"duplicate {kind} declaration {name!r}")
+        keyed[name] = declaration
+    return keyed
+
+
+def normalize_full_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 normalize_table_range(*, sheet: str | None, range_ref: str) -> tuple[str, str]:
+    if sheet is not None:
+        reference = normalize_reference(f"{sheet}!{range_ref}")
+    else:
+        reference = normalize_reference(range_ref)
+    if reference.kind != "range" or reference.sheet is None or reference.start_cell is None or reference.end_cell is None:
+        raise WrapperDeclarationError(
+            f"expected a rectangular range with a sheet, got sheet={sheet!r} range_ref={range_ref!r}"
+        )
+    start_col, start_row = split_cell(reference.start_cell)
+    end_col, end_row = split_cell(reference.end_cell)
+    return reference.sheet, f"{start_col}{start_row}:{end_col}{end_row}"
+
+
+def split_cell(cell_ref: str) -> tuple[str, int]:
+    column = "".join(character for character in cell_ref if character.isalpha())
+    row = "".join(character for character in cell_ref if character.isdigit())
+    if not column or not row:
+        raise WrapperDeclarationError(f"invalid cell coordinate {cell_ref!r}")
+    return get_column_letter(column_index_from_string(column)), int(row)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modelwright
-Version: 0.1.0a3
+Version: 0.1.0a4
 Summary: Tools for converting spreadsheet workbooks into transparent Python models.
 Author: UBC FRESH Lab
 License-Expression: MIT
@@ -135,7 +135,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.0a4`; alpha releases must not be described as full-workbook conversion guarantees.
 
 Check release artifacts locally:
 

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

@@ -15,6 +15,7 @@ src/modelwright/oracle_validation.py
 src/modelwright/oracles.py
 src/modelwright/references.py
 src/modelwright/validation.py
+src/modelwright/wrappers.py
 src/modelwright.egg-info/PKG-INFO
 src/modelwright.egg-info/SOURCES.txt
 src/modelwright.egg-info/dependency_links.txt
@@ -26,6 +27,7 @@ tests/test_conversion_plan.py
 tests/test_dependency_graph.py
 tests/test_evaluation_orchestration.py
 tests/test_extraction_records.py
+tests/test_fable_wrapper_benchmark.py
 tests/test_formula_expressions.py
 tests/test_formula_translation.py
 tests/test_formulas_oracle.py
@@ -45,4 +47,5 @@ tests/test_synthetic_fixture.py
 tests/test_validation.py
 tests/test_validation_regression.py
 tests/test_validation_report_builder.py
-tests/test_validation_scenario.py
+tests/test_validation_scenario.py
+tests/test_wrappers.py

modelwright-0.1.0a4/tests/test_fable_wrapper_benchmark.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import importlib.util
+import json
+import os
+import sys
+from pathlib import Path
+from types import ModuleType
+
+import pytest
+
+from modelwright.wrappers import ModelFacade, cell, report, table
+
+
+FABLE_ARTIFACT_DIR = Path("tmp/p26-fable-full-validation")
+FABLE_MODEL_PATH = FABLE_ARTIFACT_DIR / "generated_fable_2020_model.py"
+FABLE_SUMMARY_PATH = FABLE_ARTIFACT_DIR / "summary.json"
+FABLE_SCENARIO_OUTPUTS = {
+    "SCENARIOS selection!D20": 2.146115426018433,
+    "SCENARIOS selection!D21": 1.8982220554032356,
+    "SCENARIOS selection!D22": 1.462761288724012,
+}
+
+
+def load_module(path: Path) -> ModuleType:
+    spec = importlib.util.spec_from_file_location("generated_fable_2020_model_for_wrapper_test", path)
+    assert spec is not None
+    assert spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+@pytest.mark.benchmark
+def test_model_facade_wraps_2020_fable_benchmark_model_outputs() -> None:
+    if os.environ.get("MODELWRIGHT_RUN_FABLE_BENCHMARKS") != "1":
+        pytest.skip("set MODELWRIGHT_RUN_FABLE_BENCHMARKS=1 to run local FABLE benchmark facade tests")
+    if not FABLE_MODEL_PATH.exists() or not FABLE_SUMMARY_PATH.exists():
+        pytest.skip("materialize local P26 FABLE validation artifacts before running this benchmark test")
+
+    summary = json.loads(FABLE_SUMMARY_PATH.read_text())
+    assert summary["status"] == "pass"
+    assert summary["validated_output_universe"]["matches"] == 281741
+    assert summary["validated_output_universe"]["mismatches"] == 0
+
+    module = load_module(FABLE_MODEL_PATH)
+    facade = ModelFacade(
+        module,
+        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"],
+            )
+        ],
+    )
+
+    values = facade.calculate()
+
+    for cell_ref, expected in FABLE_SCENARIO_OUTPUTS.items():
+        assert values[cell_ref] == pytest.approx(expected)
+        assert facade.inspect(cell_ref).value == pytest.approx(expected)
+    table_values = facade.table("scenario_selection_slice").to_dict()["values"]
+    assert table_values[0][0] == pytest.approx(FABLE_SCENARIO_OUTPUTS["SCENARIOS selection!D20"])
+    assert table_values[1][0] == pytest.approx(FABLE_SCENARIO_OUTPUTS["SCENARIOS selection!D21"])
+    assert table_values[2][0] == pytest.approx(FABLE_SCENARIO_OUTPUTS["SCENARIOS selection!D22"])
+
+    report_payload = facade.report("scenario_selection")
+    assert report_payload["cells"]["scenario_metric_1"]["value"] == pytest.approx(
+        FABLE_SCENARIO_OUTPUTS["SCENARIOS selection!D20"]
+    )
+    assert report_payload["tables"]["scenario_selection_slice"]["values"][2][0] == pytest.approx(
+        FABLE_SCENARIO_OUTPUTS["SCENARIOS selection!D22"]
+    )

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

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

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

@@ -16,6 +16,11 @@ def test_root_facade_exports_primary_entrypoints() -> None:
     assert "ValidationEvaluationResult" in modelwright.__all__
     assert "infer_generated_module_contract" in modelwright.__all__
     assert "GeneratedContractInferenceResult" in modelwright.__all__
+    assert "ModelFacade" in modelwright.__all__
+    assert "Scenario" in modelwright.__all__
+    assert "cell" in modelwright.__all__
+    assert "table" in modelwright.__all__
+    assert "report" in modelwright.__all__
 
 
 def test_root_facade_does_not_export_internal_helpers() -> None:

modelwright-0.1.0a4/tests/test_wrappers.py

@@ -0,0 +1,212 @@
+import importlib.util
+import sys
+from pathlib import Path
+from types import ModuleType
+
+import pytest
+
+from modelwright.extraction import extract_workbook
+from modelwright.formulas import translate_formula_cell
+from modelwright.generation import generate_python_module, infer_generated_module_contract
+from modelwright.graph import build_dependency_graph
+from modelwright.wrappers import (
+    ModelFacade,
+    Scenario,
+    WrapperDeclarationError,
+    WrapperExecutionError,
+    cell,
+    report,
+    table,
+)
+from tests.fixtures.synthetic_model.build_workbook import build_workbook
+
+
+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 load_module(path: Path) -> ModuleType:
+    spec = importlib.util.spec_from_file_location("wrapped_generated_synthetic_model", path)
+    assert spec is not None
+    assert spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+def build_generated_synthetic_model(tmp_path: Path) -> ModuleType:
+    workbook = extract_workbook(build_workbook(tmp_path / "synthetic_model.xlsx"))
+    graph = build_dependency_graph(workbook)
+    formula_cells = {cell.cell_ref: cell for cell in workbook.cells if cell.formula is not None}
+    expressions = {
+        cell_ref: translate_formula_cell(cell, graph)
+        for cell_ref, cell in formula_cells.items()
+    }
+    inference = infer_generated_module_contract(
+        workbook=workbook,
+        graph=graph,
+        expressions=expressions,
+        output_refs=("Summary!B2", "Summary!B3"),
+        module_name="synthetic_model",
+    )
+    output_path = tmp_path / "generated_synthetic_model.py"
+
+    generation = generate_python_module(
+        contract=inference.contract,
+        expressions=inference.expressions,
+        constants=inference.constants,
+        output_path=output_path,
+    )
+
+    assert generation.generated is True
+    return load_module(output_path)
+
+
+def test_model_facade_wraps_generated_model_with_scenario_tables_and_reports() -> None:
+    facade = ModelFacade(
+        generated_model,
+        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"),
+        ],
+        tables=[
+            table(
+                "summary_grid",
+                sheet="Summary",
+                range_ref="B2:C3",
+                row_labels=["volume", "status"],
+                column_labels=["primary", "secondary"],
+            )
+        ],
+        reports=[report("summary", cells=["base", "projected"], tables=["summary_grid"])],
+    )
+
+    scenario = facade.scenario(inputs={"Inputs!B2": 50}).with_input("Inputs!B3", 0.2)
+
+    assert facade.inputs()["base"].cell_ref == "Inputs!B2"
+    assert facade.outputs()["projected"].cell_ref == "Summary!B2"
+    assert facade.calculate(scenario) == {
+        "Summary!B2": 60.0,
+        "Summary!C2": 100,
+        "Summary!B3": "ok",
+        "Summary!C3": 55,
+    }
+
+    input_view = facade.inspect("Inputs!B2", scenario)
+    assert input_view.to_dict() == {
+        "cell_ref": "Inputs!B2",
+        "name": "base",
+        "label": "Base volume",
+        "role": "input",
+        "unit": "t",
+        "description": None,
+        "value": 50,
+        "has_value": True,
+    }
+
+    table_view = facade.table("summary_grid", scenario)
+    assert table_view.to_dict() == {
+        "name": "summary_grid",
+        "sheet": "Summary",
+        "range_ref": "B2:C3",
+        "rows": ["volume", "status"],
+        "columns": ["primary", "secondary"],
+        "cell_refs": [["Summary!B2", "Summary!C2"], ["Summary!B3", "Summary!C3"]],
+        "values": [[60.0, 100], ["ok", 55]],
+        "label": None,
+        "description": None,
+    }
+
+    report_payload = facade.report("summary", scenario)
+    assert report_payload["cells"]["base"]["value"] == 50
+    assert report_payload["cells"]["projected"]["value"] == 60.0
+    assert report_payload["tables"]["summary_grid"]["values"] == [[60.0, 100], ["ok", 55]]
+
+
+def test_model_facade_preserves_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("Inputs!B3", name="growth", label="Growth rate", role="input"),
+            cell("Inputs!B4", name="harvest_share", label="Harvest share", 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"],
+            )
+        ],
+        reports=[report("default", cells=["base", "harvest", "status"], tables=["summary"])],
+    )
+
+    assert facade.calculate() == module.calculate()
+
+    scenario = facade.scenario(name="low-volume", inputs={"Inputs!B2": 10})
+    generated_values = module.calculate(scenario.inputs)
+
+    assert facade.calculate(scenario) == generated_values
+    assert generated_values == {"Summary!B2": 7.02, "Summary!B3": "low"}
+    assert facade.inspect("Summary!B2", scenario).value == generated_values["Summary!B2"]
+    assert facade.table("summary", scenario).to_dict()["values"] == [[7.02], ["low"]]
+
+    report_payload = facade.report("default", scenario)
+    assert report_payload["cells"]["base"]["value"] == 10
+    assert report_payload["cells"]["harvest"]["value"] == generated_values["Summary!B2"]
+    assert report_payload["tables"]["summary"]["values"] == [[7.02], ["low"]]
+
+
+def test_scenario_is_copy_on_write_and_normalizes_input_refs() -> None:
+    original = Scenario.from_inputs(inputs={"Inputs!B2": 10})
+    updated = original.with_input("Inputs!B3", 0.25)
+
+    assert original.inputs == {"Inputs!B2": 10}
+    assert updated.inputs == {"Inputs!B2": 10, "Inputs!B3": 0.25}
+
+
+def test_table_declaration_validates_label_shape() -> None:
+    with pytest.raises(WrapperDeclarationError, match="row labels"):
+        table("bad_rows", sheet="Summary", range_ref="A1:A2", row_labels=["only one"])
+
+    with pytest.raises(WrapperDeclarationError, match="column labels"):
+        table("bad_columns", sheet="Summary", range_ref="A1:B1", column_labels=["only one"])
+
+
+def test_facade_validates_duplicate_names_and_report_references() -> None:
+    with pytest.raises(WrapperDeclarationError, match="duplicate cell declaration"):
+        ModelFacade(
+            generated_model,
+            cells=[
+                cell("Inputs!B2", name="base"),
+                cell("Inputs!B3", name="base"),
+            ],
+        )
+
+    with pytest.raises(WrapperDeclarationError, match="unknown table"):
+        ModelFacade(generated_model, reports=[report("bad", tables=["missing"])])
+
+
+def test_facade_wraps_generated_model_execution_errors() -> None:
+    def broken_model(inputs=None):
+        raise RuntimeError("boom")
+
+    facade = ModelFacade(broken_model)
+
+    with pytest.raises(WrapperExecutionError, match="calculation failed"):
+        facade.calculate()