modelwright 0.1.0a4__tar.gz → 0.1.0a6__tar.gz

modelwright-0.1.0a6/MANIFEST.in

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modelwright
-Version: 0.1.0a4
+Version: 0.1.0a6
 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.0a6`; alpha releases must not be described as full-workbook conversion guarantees.
 
 Check release artifacts locally:
 

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

modelwright-0.1.0a6/examples/README.md

@@ -0,0 +1,35 @@
+# 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.
+- `notebooks/`: real Jupyter notebooks with markdown explanation, code cells, and stored outputs for
+  the synthetic and FABLE examples.
+
+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.
+
+## Importing From Local Notebooks
+
+These are source-tree examples. If your notebook file lives under `tmp/notebooks/`, add the repository
+root to `sys.path` before importing from `examples`:
+
+```python
+from pathlib import Path
+import sys
+
+repo_root = Path.cwd().resolve()
+while repo_root != repo_root.parent and not (repo_root / "pyproject.toml").exists():
+    repo_root = repo_root.parent
+
+if not (repo_root / "pyproject.toml").exists():
+    raise RuntimeError("Could not find the Modelwright repository root.")
+
+sys.path.insert(0, str(repo_root))
+```
+
+Then imports such as `from examples.synthetic.notebook_interface import build_facade` will resolve.

modelwright-0.1.0a6/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.0a6/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.0a6/examples/notebooks/README.md

@@ -0,0 +1,11 @@
+# Literate Notebook Examples
+
+These notebooks are tracked examples for the Sphinx Examples Gallery.
+
+- `synthetic-notebook-interface.ipynb` is a tiny, fast notebook that can be checked in default tests.
+- `fable-2020-notebook-interface.ipynb` documents the production-size generated 2020 FABLE model
+  workflow. The notebook contains known-valid stored outputs, while full execution remains opt-in
+  because the generated model import and calculation are intentionally large.
+
+Open them from a source checkout with JupyterLab or Jupyter Notebook. The first code cell adds the
+repository root to `sys.path` so imports from the local `examples/` directory resolve.

modelwright-0.1.0a6/examples/notebooks/fable-2020-notebook-interface.ipynb

@@ -0,0 +1,300 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# 2020 FABLE Notebook Interface Example\n",
+    "\n",
+    "This notebook shows the same notebook-facing workflow on a production-size generated Modelwright model from the public 2020 FABLE Calculator benchmark workbook.\n",
+    "\n",
+    "The original workbook is not tracked in this repository. The tracked artifact is Modelwright's generated Python output, compressed as `examples/fable_2020/generated_fable_2020_model.py.xz`. The example script decompresses that generated model into ignored `tmp/` working space before import."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2ceb2405",
+   "metadata": {},
+   "source": [
+    "## 1. Make The Source Checkout Importable\n",
+    "\n",
+    "This notebook is meant to be opened from a source checkout. The setup cell finds the repository root and places it on `sys.path`, so imports from `examples/` resolve even if the notebook file is copied under `tmp/notebooks/`.\n",
+    "\n",
+    "Expected output: the package project name, `modelwright`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "d40dcd53",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Using project: modelwright\n"
+     ]
+    }
+   ],
+   "source": [
+    "from pathlib import Path\n",
+    "import sys\n",
+    "import tomllib\n",
+    "\n",
+    "repo_root = Path.cwd().resolve()\n",
+    "while repo_root != repo_root.parent and not (repo_root / \"pyproject.toml\").exists():\n",
+    "    repo_root = repo_root.parent\n",
+    "\n",
+    "if not (repo_root / \"pyproject.toml\").exists():\n",
+    "    raise RuntimeError(\"Could not find the Modelwright repository root.\")\n",
+    "\n",
+    "project_name = tomllib.loads((repo_root / \"pyproject.toml\").read_text())[\"project\"][\"name\"]\n",
+    "\n",
+    "if str(repo_root) not in sys.path:\n",
+    "    sys.path.insert(0, str(repo_root))\n",
+    "\n",
+    "print(f\"Using project: {project_name}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 2. Load The Production-Size Example Facade\n",
+    "\n",
+    "`build_facade()` imports the generated FABLE Python model and declares a small analyst-facing wrapper around three validated `SCENARIOS selection` outputs. The first import may take time because the generated model is intentionally production-sized.\n",
+    "\n",
+    "Expected output: the compressed archive path, the decompressed generated-model path under `tmp/`, and the declared output names."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Archive: examples/fable_2020/generated_fable_2020_model.py.xz\n",
+      "Generated model path: tmp/examples/fable_2020/generated_fable_2020_model.py\n",
+      "Declared outputs: ['scenario_metric_1', 'scenario_metric_2', 'scenario_metric_3']\n"
+     ]
+    }
+   ],
+   "source": [
+    "from examples.fable_2020.notebook_interface import ARCHIVE_PATH, MODEL_PATH, build_facade\n",
+    "from modelwright.notebooks import outputs_frame, report_frames, table_frame\n",
+    "\n",
+    "facade = build_facade()\n",
+    "\n",
+    "print(f\"Archive: {ARCHIVE_PATH.relative_to(repo_root)}\")\n",
+    "print(f\"Generated model path: {MODEL_PATH}\")\n",
+    "print(f\"Declared outputs: {list(facade.outputs())}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 3. Calculate The Wrapped Model\n",
+    "\n",
+    "This cell calls the generated model through the facade. The stored output records the three wrapped FABLE outputs. The Phase 26 full-validation evidence for the underlying generated model remains: 281,741 comparable cached outputs, 281,741 matches, and 0 mismatches.\n",
+    "\n",
+    "Expected output: three `SCENARIOS selection` values."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "{'SCENARIOS selection!D20': 2.146115426018433,\n",
+       " 'SCENARIOS selection!D21': 1.8982220554032356,\n",
+       " 'SCENARIOS selection!D22': 1.462761288724012}"
+      ]
+     },
+     "execution_count": 3,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "values = facade.calculate()\n",
+    "{cell_ref: values[cell_ref] for cell_ref in [\n",
+    "    \"SCENARIOS selection!D20\",\n",
+    "    \"SCENARIOS selection!D21\",\n",
+    "    \"SCENARIOS selection!D22\",\n",
+    "]}"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 4. Display Wrapped Outputs As A DataFrame\n",
+    "\n",
+    "The notebook helper presents the declared outputs with human names while preserving raw cell references for provenance.\n",
+    "\n",
+    "Expected output: a three-row DataFrame for the wrapped scenario metrics."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "                name                 cell_ref     value\n",
+       "0  scenario_metric_1  SCENARIOS selection!D20  2.146115\n",
+       "1  scenario_metric_2  SCENARIOS selection!D21  1.898222\n",
+       "2  scenario_metric_3  SCENARIOS selection!D22  1.462761"
+      ]
+     },
+     "execution_count": 4,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "outputs_frame(facade)[[\"name\", \"cell_ref\", \"value\"]]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 5. Display A Declared FABLE Table Slice\n",
+    "\n",
+    "The wrapper declares `SCENARIOS selection!D20:D22` as a rectangular table with row labels. This turns a raw output slice into an inspectable table.\n",
+    "\n",
+    "Expected output: the three selected FABLE values as a one-column DataFrame."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "        value\n",
+       "row          \n",
+       "d20  2.146115\n",
+       "d21  1.898222\n",
+       "d22  1.462761"
+      ]
+     },
+     "execution_count": 5,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "table_frame(facade, \"scenario_selection_slice\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 6. Keep Provenance Available\n",
+    "\n",
+    "DataFrame display is the humane interface, but workbook provenance is still available. Table frame metadata stores the sheet, range, and cell references used to build the view.\n",
+    "\n",
+    "Expected output: the original workbook sheet and range."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "{'sheet': 'SCENARIOS selection',\n",
+       " 'range_ref': 'D20:D22',\n",
+       " 'cell_refs': [['SCENARIOS selection!D20'],\n",
+       "  ['SCENARIOS selection!D21'],\n",
+       "  ['SCENARIOS selection!D22']]}"
+      ]
+     },
+     "execution_count": 6,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "scenario_table = table_frame(facade, \"scenario_selection_slice\")\n",
+    "{\n",
+    "    \"sheet\": scenario_table.attrs[\"sheet\"],\n",
+    "    \"range_ref\": scenario_table.attrs[\"range_ref\"],\n",
+    "    \"cell_refs\": scenario_table.attrs[\"cell_refs\"],\n",
+    "}"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 7. Bundle Outputs Into A Report\n",
+    "\n",
+    "Reports collect declared cells and tables under one human-facing name. This gives a notebook user a repeatable reporting boundary without editing the generated model.\n",
+    "\n",
+    "Expected output: the report's cell DataFrame."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "                name                 cell_ref     value\n",
+       "0  scenario_metric_1  SCENARIOS selection!D20  2.146115\n",
+       "1  scenario_metric_2  SCENARIOS selection!D21  1.898222\n",
+       "2  scenario_metric_3  SCENARIOS selection!D22  1.462761"
+      ]
+     },
+     "execution_count": 7,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "frames = report_frames(facade, \"scenario_selection\")\n",
+    "frames[\"cells\"][[\"name\", \"cell_ref\", \"value\"]]"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}