modelwright 0.1.0a1__tar.gz

modelwright-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UBC FRESH Lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

modelwright-0.1.0a1/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: modelwright
+Version: 0.1.0a1
+Summary: Tools for converting spreadsheet workbooks into transparent Python models.
+Author: UBC FRESH Lab
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/UBC-FRESH/modelwright
+Project-URL: Documentation, https://ubc-fresh.github.io/modelwright/
+Project-URL: Repository, https://github.com/UBC-FRESH/modelwright
+Project-URL: Issues, https://github.com/UBC-FRESH/modelwright/issues
+Project-URL: Changelog, https://github.com/UBC-FRESH/modelwright/blob/main/CHANGE_LOG.md
+Keywords: spreadsheets,excel,model-conversion,reproducible-models,validation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: rich>=13
+Requires-Dist: typer>=0.9
+Provides-Extra: docs
+Requires-Dist: sphinx>=7; extra == "docs"
+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: 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: oracle
+Requires-Dist: formulas; extra == "oracle"
+Provides-Extra: quality
+Requires-Dist: ruff>=0.8; extra == "quality"
+Provides-Extra: release
+Requires-Dist: build>=1.2; extra == "release"
+Requires-Dist: twine>=5; extra == "release"
+Provides-Extra: test
+Requires-Dist: formulas; extra == "test"
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+# Modelwright
+
+`modelwright` is an early-stage project for turning spreadsheet workbooks into transparent, version-controlled, standalone Python models.
+
+The intended direction is a generic workflow that can inspect workbook structure, extract formulas and dependencies, generate maintainable Python source, and validate the generated model against the original workbook outputs.
+
+This repository is currently an early implementation skeleton. It defines minimal Python package and test scaffolding plus initial validation, extraction, graph, generation, oracle records, and thin JSON command-line wrappers, but does not yet provide a release stability guarantee, catalog schema, or full workbook conversion.
+
+## Current Focus
+
+- Build the first package-backed validation/report, workbook extraction, generation, and CLI cores.
+- Keep extraction, code generation, validation, diagnostics, and reporting responsibilities separate.
+- Avoid committing private notes, source workbooks, generated clones, or large artifacts while the project shape is still being established.
+
+## Python API Boundary
+
+The durable API is organized by module responsibility:
+
+- `modelwright.extraction`: workbook extraction records and `extract_workbook`.
+- `modelwright.graph`: dependency graph records and `build_dependency_graph`.
+- `modelwright.formulas`: formula expression records, translation helpers, and reference-index helpers.
+- `modelwright.generation`: generated-module records and `generate_python_module`.
+- `modelwright.validation`: validation scenarios, scalar comparisons, and report records.
+- `modelwright.oracles`, `modelwright.formulas_oracle`, and `modelwright.oracle_validation`: oracle request/result records, optional `formulas` oracle execution, and oracle-backed report assembly.
+
+The package root `modelwright` exposes a curated convenience facade for those records and functions. Module-level imports remain preferred for implementation work because this project is still pre-release.
+
+## Command-Line Interface
+
+Bootstrap the repo-local virtual environment before using the console script:
+
+```bash
+scripts/bootstrap_dev_env.sh
+```
+
+The current CLI prints JSON to stdout and stays close to the Python APIs:
+
+```bash
+modelwright workbook extract path/to/workbook.xlsx > tmp/extraction.json
+modelwright workbook graph path/to/workbook.xlsx > tmp/dependency-graph.json
+modelwright conversion plan path/to/workbook.xlsx > tmp/conversion-plan.json
+modelwright model generate --contract tmp/contract.json --expressions tmp/expressions.json --constants tmp/constants.json --out tmp/generated_model.py > tmp/generation-result.json
+modelwright validation report --scenario tests/fixtures/synthetic_model/baseline_scenario.json --generated-values tmp/generated-values.json --oracle-values tmp/oracle-values.json > tmp/validation-report.json
+```
+
+These commands do not provide a one-step workbook converter. `conversion plan` reports extraction, graphing, formula-translation, and residual-blocker status; `model generate` expects explicit generated-module and formula-expression JSON inputs; and `validation report` compares already-observed generated/oracle values. See `planning/cli-json-workflows.md` for JSON examples and workflow boundaries.
+
+## Local Development
+
+Bootstrap a repo-local virtual environment:
+
+```bash
+scripts/bootstrap_dev_env.sh
+```
+
+This installs Modelwright with the `dev` extra:
+
+```bash
+.venv/bin/python -m pip install -e '.[dev]'
+```
+
+Run lint checks:
+
+```bash
+.venv/bin/python -m ruff check .
+```
+
+Run tests:
+
+```bash
+.venv/bin/python -m pytest
+```
+
+Build docs locally:
+
+```bash
+.venv/bin/sphinx-build -b html docs _build/html -W
+.venv/bin/python scripts/verify_docs_theme.py _build/html
+```
+
+Restore the public external FABLE benchmark workbooks into ignored local paths:
+
+```bash
+scripts/bootstrap_dev_env.sh --benchmarks
+```
+
+`modelwright` is pre-release. The first planned alpha line is `0.1.0a1`; alpha releases must not be described as full-workbook conversion guarantees.
+
+Check release artifacts locally:
+
+```bash
+scripts/check_release_artifacts.sh
+```
+
+Release checks write build outputs under ignored `tmp/release-checks/`.
+
+See `docs/guides/release-deployment.rst` for the release and deployment runbook.
+
+## Repository Conventions
+
+- `AGENTS.md` is the working contract for AI coding agents.
+- `CONTRIBUTING.md` is the contributor onboarding and development workflow guide.
+- `ROADMAP.md` is the current plan and next-step tracker.
+- `CHANGE_LOG.md` is the append-only project narrative.
+- `planning/` contains focused design notes and research records that are too detailed for the roadmap.
+- `benchmarks/` contains tracked metadata for official external benchmarks; large workbook binaries remain untracked and are restored locally under `tmp/`.
+- `src/modelwright/` contains the importable Python package.
+- `tests/` contains package-backed tests and tracked synthetic fixture helpers.
+- `tmp/` is ignored local working space for private notes, source workbooks, experiments, and generated scratch outputs.

modelwright-0.1.0a1/README.md

@@ -0,0 +1,109 @@
+# Modelwright
+
+`modelwright` is an early-stage project for turning spreadsheet workbooks into transparent, version-controlled, standalone Python models.
+
+The intended direction is a generic workflow that can inspect workbook structure, extract formulas and dependencies, generate maintainable Python source, and validate the generated model against the original workbook outputs.
+
+This repository is currently an early implementation skeleton. It defines minimal Python package and test scaffolding plus initial validation, extraction, graph, generation, oracle records, and thin JSON command-line wrappers, but does not yet provide a release stability guarantee, catalog schema, or full workbook conversion.
+
+## Current Focus
+
+- Build the first package-backed validation/report, workbook extraction, generation, and CLI cores.
+- Keep extraction, code generation, validation, diagnostics, and reporting responsibilities separate.
+- Avoid committing private notes, source workbooks, generated clones, or large artifacts while the project shape is still being established.
+
+## Python API Boundary
+
+The durable API is organized by module responsibility:
+
+- `modelwright.extraction`: workbook extraction records and `extract_workbook`.
+- `modelwright.graph`: dependency graph records and `build_dependency_graph`.
+- `modelwright.formulas`: formula expression records, translation helpers, and reference-index helpers.
+- `modelwright.generation`: generated-module records and `generate_python_module`.
+- `modelwright.validation`: validation scenarios, scalar comparisons, and report records.
+- `modelwright.oracles`, `modelwright.formulas_oracle`, and `modelwright.oracle_validation`: oracle request/result records, optional `formulas` oracle execution, and oracle-backed report assembly.
+
+The package root `modelwright` exposes a curated convenience facade for those records and functions. Module-level imports remain preferred for implementation work because this project is still pre-release.
+
+## Command-Line Interface
+
+Bootstrap the repo-local virtual environment before using the console script:
+
+```bash
+scripts/bootstrap_dev_env.sh
+```
+
+The current CLI prints JSON to stdout and stays close to the Python APIs:
+
+```bash
+modelwright workbook extract path/to/workbook.xlsx > tmp/extraction.json
+modelwright workbook graph path/to/workbook.xlsx > tmp/dependency-graph.json
+modelwright conversion plan path/to/workbook.xlsx > tmp/conversion-plan.json
+modelwright model generate --contract tmp/contract.json --expressions tmp/expressions.json --constants tmp/constants.json --out tmp/generated_model.py > tmp/generation-result.json
+modelwright validation report --scenario tests/fixtures/synthetic_model/baseline_scenario.json --generated-values tmp/generated-values.json --oracle-values tmp/oracle-values.json > tmp/validation-report.json
+```
+
+These commands do not provide a one-step workbook converter. `conversion plan` reports extraction, graphing, formula-translation, and residual-blocker status; `model generate` expects explicit generated-module and formula-expression JSON inputs; and `validation report` compares already-observed generated/oracle values. See `planning/cli-json-workflows.md` for JSON examples and workflow boundaries.
+
+## Local Development
+
+Bootstrap a repo-local virtual environment:
+
+```bash
+scripts/bootstrap_dev_env.sh
+```
+
+This installs Modelwright with the `dev` extra:
+
+```bash
+.venv/bin/python -m pip install -e '.[dev]'
+```
+
+Run lint checks:
+
+```bash
+.venv/bin/python -m ruff check .
+```
+
+Run tests:
+
+```bash
+.venv/bin/python -m pytest
+```
+
+Build docs locally:
+
+```bash
+.venv/bin/sphinx-build -b html docs _build/html -W
+.venv/bin/python scripts/verify_docs_theme.py _build/html
+```
+
+Restore the public external FABLE benchmark workbooks into ignored local paths:
+
+```bash
+scripts/bootstrap_dev_env.sh --benchmarks
+```
+
+`modelwright` is pre-release. The first planned alpha line is `0.1.0a1`; alpha releases must not be described as full-workbook conversion guarantees.
+
+Check release artifacts locally:
+
+```bash
+scripts/check_release_artifacts.sh
+```
+
+Release checks write build outputs under ignored `tmp/release-checks/`.
+
+See `docs/guides/release-deployment.rst` for the release and deployment runbook.
+
+## Repository Conventions
+
+- `AGENTS.md` is the working contract for AI coding agents.
+- `CONTRIBUTING.md` is the contributor onboarding and development workflow guide.
+- `ROADMAP.md` is the current plan and next-step tracker.
+- `CHANGE_LOG.md` is the append-only project narrative.
+- `planning/` contains focused design notes and research records that are too detailed for the roadmap.
+- `benchmarks/` contains tracked metadata for official external benchmarks; large workbook binaries remain untracked and are restored locally under `tmp/`.
+- `src/modelwright/` contains the importable Python package.
+- `tests/` contains package-backed tests and tracked synthetic fixture helpers.
+- `tmp/` is ignored local working space for private notes, source workbooks, experiments, and generated scratch outputs.

modelwright-0.1.0a1/pyproject.toml

@@ -0,0 +1,89 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "modelwright"
+version = "0.1.0a1"
+description = "Tools for converting spreadsheet workbooks into transparent Python models."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "UBC FRESH Lab" }
+]
+keywords = [
+  "spreadsheets",
+  "excel",
+  "model-conversion",
+  "reproducible-models",
+  "validation"
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Office/Business",
+  "Topic :: Scientific/Engineering"
+]
+dependencies = [
+  "openpyxl>=3.1",
+  "rich>=13",
+  "typer>=0.9"
+]
+
+[project.urls]
+Homepage = "https://github.com/UBC-FRESH/modelwright"
+Documentation = "https://ubc-fresh.github.io/modelwright/"
+Repository = "https://github.com/UBC-FRESH/modelwright"
+Issues = "https://github.com/UBC-FRESH/modelwright/issues"
+Changelog = "https://github.com/UBC-FRESH/modelwright/blob/main/CHANGE_LOG.md"
+
+[project.scripts]
+modelwright = "modelwright.cli:app"
+
+[project.optional-dependencies]
+docs = [
+  "sphinx>=7",
+  "sphinx-rtd-theme>=2"
+]
+dev = [
+  "build>=1.2",
+  "formulas",
+  "pytest>=8",
+  "ruff>=0.8",
+  "sphinx>=7",
+  "sphinx-rtd-theme>=2",
+  "twine>=5"
+]
+oracle = [
+  "formulas"
+]
+quality = [
+  "ruff>=0.8"
+]
+release = [
+  "build>=1.2",
+  "twine>=5"
+]
+test = [
+  "formulas",
+  "pytest>=8"
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+extend-exclude = ["tmp"]

modelwright-0.1.0a1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

modelwright-0.1.0a1/src/modelwright/__init__.py

@@ -0,0 +1,148 @@
+"""Modelwright package skeleton."""
+
+from modelwright.extraction import (
+    CellRecord,
+    ExtractionDiagnostic,
+    FormulaRecord,
+    NamedRangeRecord,
+    SheetRecord,
+    TableRecord,
+    WorkbookRecord,
+    extract_workbook,
+)
+from modelwright.execution import (
+    ExecutionDiagnostic,
+    GeneratedExecutionResult,
+    execute_generated_model,
+)
+from modelwright.evaluation import (
+    ValidationEvaluationResult,
+    evaluate_generated_model,
+)
+from modelwright.conversion import (
+    ConversionPlan,
+    ConversionSource,
+    CoverageSummary,
+    DiagnosticSummary,
+    GenerationSummary,
+    PlanRecommendation,
+    PrivacyReview,
+    ResidualBlocker,
+    ValidationSummary,
+    WorkflowStatus,
+    build_conversion_plan,
+)
+from modelwright.formulas import (
+    FormulaExpression,
+    FormulaExpressionNode,
+    FormulaTranslationDiagnostic,
+    build_formula_reference_index,
+    translate_formula_cell,
+)
+from modelwright.formulas_oracle import FormulasWorkbookOracle
+from modelwright.generation import (
+    GeneratedContractInferenceResult,
+    GeneratedModuleContract,
+    GeneratedSymbol,
+    GenerationDiagnostic,
+    GenerationResult,
+    generate_python_module,
+    infer_generated_module_contract,
+)
+from modelwright.graph import (
+    DependencyEdge,
+    DependencyGraph,
+    build_dependency_graph,
+)
+from modelwright.oracles import (
+    OracleDiagnostic,
+    OracleRequest,
+    OracleResult,
+    WorkbookOracle,
+)
+from modelwright.oracle_validation import build_oracle_validation_report
+from modelwright.references import (
+    WorkbookReference,
+    normalize_cell_reference,
+    normalize_reference,
+)
+from modelwright.validation import (
+    ComparisonResult,
+    ComparisonRules,
+    Diagnostic,
+    MISSING_VALUE,
+    OracleConfig,
+    ScenarioInput,
+    ScenarioOutput,
+    ValidationReport,
+    ValidationScenario,
+    build_validation_report,
+    compare_scalar_output,
+    load_validation_scenario,
+)
+
+__version__ = "0.1.0a1"
+
+__all__ = [
+    "CellRecord",
+    "ComparisonResult",
+    "ComparisonRules",
+    "ConversionPlan",
+    "ConversionSource",
+    "CoverageSummary",
+    "DependencyEdge",
+    "DependencyGraph",
+    "Diagnostic",
+    "DiagnosticSummary",
+    "ExtractionDiagnostic",
+    "ExecutionDiagnostic",
+    "FormulaExpression",
+    "FormulaExpressionNode",
+    "FormulaRecord",
+    "FormulaTranslationDiagnostic",
+    "FormulasWorkbookOracle",
+    "GeneratedModuleContract",
+    "GeneratedExecutionResult",
+    "GeneratedContractInferenceResult",
+    "GeneratedSymbol",
+    "GenerationSummary",
+    "GenerationDiagnostic",
+    "GenerationResult",
+    "MISSING_VALUE",
+    "NamedRangeRecord",
+    "OracleConfig",
+    "OracleDiagnostic",
+    "OracleRequest",
+    "OracleResult",
+    "PlanRecommendation",
+    "PrivacyReview",
+    "ResidualBlocker",
+    "ScenarioInput",
+    "ScenarioOutput",
+    "SheetRecord",
+    "TableRecord",
+    "ValidationReport",
+    "ValidationEvaluationResult",
+    "ValidationScenario",
+    "ValidationSummary",
+    "WorkbookOracle",
+    "WorkbookReference",
+    "WorkbookRecord",
+    "WorkflowStatus",
+    "__version__",
+    "build_dependency_graph",
+    "build_conversion_plan",
+    "build_formula_reference_index",
+    "build_oracle_validation_report",
+    "build_validation_report",
+    "compare_scalar_output",
+    "execute_generated_model",
+    "evaluate_generated_model",
+    "extract_workbook",
+    "generate_python_module",
+    "infer_generated_module_contract",
+    "load_validation_scenario",
+    "normalize_cell_reference",
+    "normalize_reference",
+    "translate_formula_cell",
+]