API Reference

The module-level APIs are the preferred implementation imports. The package root also exposes a curated convenience facade for the main records and functions.

Extraction

Workbook extraction records.

These records describe extracted workbook facts; they do not read workbook files themselves.

class modelwright.extraction.CellRecord(cell_ref, kind, raw_value, data_type=None, cached_value=None, formula=None)[source]

Extracted cell facts for one canonical workbook cell reference.

Parameters:

cell_ref (str)
kind (Literal['value', 'formula', 'blank', 'error'])
raw_value (str | int | float | bool | None | list[Any] | dict[str, Any])
data_type (str | None)
cached_value (str | int | float | bool | None | list[Any] | dict[str, Any])
formula (FormulaRecord | None)

class modelwright.extraction.ExtractionDiagnostic(code, message, severity='warning', location=None, raw_value=None)[source]

Extraction or interpretation concern tied to workbook provenance.

Parameters:

code (str)
message (str)
severity (Literal['info', 'warning', 'error'])
location (str | None)
raw_value (str | int | float | bool | None | list[Any] | dict[str, Any])

class modelwright.extraction.FormulaRecord(raw_formula, tokens=<factory>, raw_references=<factory>, normalized_references=<factory>, functions=<factory>, diagnostics=<factory>)[source]

Formula text and parsed extraction facts for one formula cell.

Parameters:

raw_formula (str)
tokens (tuple[str, ...])
raw_references (tuple[str, ...])
normalized_references (tuple[str, ...])
functions (tuple[str, ...])
diagnostics (tuple[ExtractionDiagnostic, ...])

class modelwright.extraction.NamedRangeRecord(name, scope, raw_definition, destinations=<factory>, status='unresolved', diagnostics=<factory>)[source]

Workbook or worksheet scoped defined name.

Parameters:

name (str)
scope (str)
raw_definition (str)
destinations (tuple[str, ...])
status (Literal['resolved', 'partially_resolved', 'unresolved'])
diagnostics (tuple[ExtractionDiagnostic, ...])

class modelwright.extraction.SheetRecord(sheet_id, title, state, index)[source]

Worksheet identity and ordering facts.

Parameters:

sheet_id (str)
title (str)
state (str)
index (int)

class modelwright.extraction.TableRecord(name, sheet, ref, columns=<factory>)[source]

Worksheet table metadata needed to resolve structured references.

Parameters:

name (str)
sheet (str)
ref (str)
columns (tuple[str, ...])

class modelwright.extraction.WorkbookRecord(workbook_id, source_path, sheets=<factory>, cells=<factory>, named_ranges=<factory>, tables=<factory>, diagnostics=<factory>)[source]

Extracted facts for one source workbook.

Parameters:

workbook_id (str)
source_path (str)
sheets (tuple[SheetRecord, ...])
cells (tuple[CellRecord, ...])
named_ranges (tuple[NamedRangeRecord, ...])
tables (tuple[TableRecord, ...])
diagnostics (tuple[ExtractionDiagnostic, ...])

modelwright.extraction.extract_workbook(path, progress=None)[source]

Extract workbook facts with openpyxl into Modelwright records.

Parameters:

path (str | Path)
progress (Callable[[str], None] | None)

Return type:

WorkbookRecord

References

Workbook reference normalization records and helpers.

class modelwright.references.WorkbookReference(kind, original, normalized, workbook=None, sheet=None, start_cell=None, end_cell=None, name=None, diagnostic_code=None)[source]

Canonical representation of one workbook reference token.

Parameters:

kind (Literal['cell', 'range', 'named_range', 'structured', 'external', 'unresolved'])
original (str)
normalized (str)
workbook (str | None)
sheet (str | None)
start_cell (str | None)
end_cell (str | None)
name (str | None)
diagnostic_code (str | None)

modelwright.references.cell_reference_coordinates(cell_ref)[source]

Return (row, column) (1-based) for a cell reference string.

Parameters:: cell_ref (str)
Return type:: tuple[int, int]

modelwright.references.normalize_cell_reference(reference, *, current_sheet=None)[source]

Normalize a token expected to identify one cell.

Parameters:

reference (str)
current_sheet (str | None)

Return type:

WorkbookReference

modelwright.references.normalize_reference(reference, *, current_sheet=None)[source]

Normalize one workbook formula reference token.

Parameters:

reference (str)
current_sheet (str | None)

Return type:

WorkbookReference

modelwright.references.repair_corrupted_structured_references(raw_formula)[source]

Repair duplicated structured-reference table prefixes.

Some workbooks carry a malformed prefix where a table name is written twice, once as a dangling name[] token and again as the real structured reference (name[] name[[#This Row],[Column]]). This is a source defect in the workbook; the repair drops the dangling prefix so the remaining structured reference parses normally.

Parameters:: raw_formula (str)
Return type:: str

modelwright.references.static_indirect_cell_reference(cell_ref, raw_formula)[source]

Resolve a statically-computable INDIRECT(ADDRESS(ROW(), COLUMN())).

Returns the target cell reference (e.g. Sheet!B4) for the fixed pattern INDIRECT(ADDRESS(ROW() +- k, COLUMN() +- k)) that some workbooks use to reference the cell directly above the formula, or None when the formula does not match the pattern.

Parameters:

cell_ref (str)
raw_formula (str)

Return type:

str | None

Dependency Graph

Dependency graph records built from extracted workbook facts.

class modelwright.graph.DependencyEdge(source, target, edge_kind, raw_reference, resolved_from=None, diagnostic_code=None)[source]

One dependency edge from an upstream source to a formula cell target.

Parameters:

source (WorkbookReference)
target (WorkbookReference)
edge_kind (Literal['semantic', 'execution'])
raw_reference (str)
resolved_from (WorkbookReference | None)
diagnostic_code (str | None)

class modelwright.graph.DependencyGraph(workbook_id, edges=<factory>, diagnostics=<factory>)[source]

Dependency edges for one workbook extraction.

Parameters:

workbook_id (str)
edges (tuple[DependencyEdge, ...])
diagnostics (tuple[str, ...])

modelwright.graph.build_dependency_graph(workbook, progress=None)[source]

Build semantic and execution dependency edges from extracted formulas.

Parameters:

workbook (WorkbookRecord)
progress (Callable[[str], None] | None)

Return type:

DependencyGraph

Formula Translation

Formula expression records.

These records describe translated formula structure; they do not translate Excel formula text themselves.

class modelwright.formulas.FormulaExpression(source_cell, raw_formula, root=None, diagnostics=<factory>)[source]

Translated expression for one source formula cell.

Parameters:

source_cell (str)
raw_formula (str)
root (FormulaExpressionNode | None)
diagnostics (tuple[FormulaTranslationDiagnostic, ...])

class modelwright.formulas.FormulaExpressionNode(kind, value=None, reference=None, operator=None, function_name=None, operands=<factory>)[source]

One node in a translated formula expression tree.

Parameters:

kind (Literal['literal', 'reference', 'unary', 'binary', 'comparison', 'function_call'])
value (str | int | float | bool | None | list[Any] | dict[str, Any])
reference (WorkbookReference | None)
operator (str | None)
function_name (str | None)
operands (tuple[FormulaExpressionNode, ...])

class modelwright.formulas.FormulaTranslationDiagnostic(code, message, severity='warning', location=None, raw_value=None)[source]

Formula translation concern tied to source formula provenance.

Parameters:

code (str)
message (str)
severity (Literal['info', 'warning', 'error'])
location (str | None)
raw_value (str | int | float | bool | None | list[Any] | dict[str, Any])

exception modelwright.formulas.FormulaTranslationError(code, message, raw_value=None)[source]

Parameters:

code (str)
message (str)
raw_value (JsonValue)

Return type:

None

modelwright.formulas.build_formula_reference_index(graph)[source]

Build fast lookup for formula raw references by target cell.

Parameters:: graph (DependencyGraph)
Return type:: dict[tuple[str, str], WorkbookReference]

modelwright.formulas.translate_formula_cell(cell, graph, reference_index=None)[source]

Translate one supported formula cell into an expression tree.

Parameters:

cell (CellRecord)
graph (DependencyGraph)
reference_index (dict[tuple[str, str], WorkbookReference] | None)

Return type:

FormulaExpression

Generation

Generated Python module contracts.

class modelwright.generation.GeneratedContractInferenceResult(contract, expressions=<factory>, constants=<factory>, diagnostics=<factory>)[source]

Generated-model contract inference result for selected workbook outputs.

Parameters:

contract (GeneratedModuleContract)
expressions (dict[str, FormulaExpression])
constants (dict[str, str | int | float | bool | None | list[Any] | dict[str, Any]])
diagnostics (tuple[GenerationDiagnostic, ...])

class modelwright.generation.GeneratedModuleContract(workbook_id, module_name, entrypoint='calculate', input_refs=<factory>, output_refs=<factory>, symbols=<factory>, include_provenance_comments=True, formula_storage='lambdas')[source]

Contract for one generated standalone Python module.

Parameters:

workbook_id (str)
module_name (str)
entrypoint (str)
input_refs (tuple[str, ...])
output_refs (tuple[str, ...])
symbols (tuple[GeneratedSymbol, ...])
include_provenance_comments (bool)
formula_storage (Literal['lambdas', 'expression_source'])

class modelwright.generation.GeneratedSymbol(cell_ref, symbol_name, kind, raw_formula=None)[source]

Generated Python symbol tied back to workbook provenance.

Parameters:

cell_ref (str)
symbol_name (str)
kind (Literal['input', 'intermediate', 'output'])
raw_formula (str | None)

class modelwright.generation.GenerationDiagnostic(code, message, severity='warning', location=None, raw_value=None)[source]

Generation concern tied to workbook or generated-code provenance.

Parameters:

code (str)
message (str)
severity (Literal['info', 'warning', 'error'])
location (str | None)
raw_value (str | int | float | bool | None | list[Any] | dict[str, Any])

class modelwright.generation.GenerationResult(contract, source_code='', diagnostics=<factory>)[source]

Result of generating one Python module.

Parameters:

contract (GeneratedModuleContract)
source_code (str)
diagnostics (tuple[GenerationDiagnostic, ...])

modelwright.generation.generate_python_module(*, contract, expressions, constants=None, output_path=None, progress=None, runtime_progress_interval=None)[source]

Generate standalone Python source from translated formula expressions.

Parameters:

contract (GeneratedModuleContract)
expressions (Mapping[str, FormulaExpression])
constants (Mapping[str, str | int | float | bool | None | list[Any] | dict[str, Any]] | None)
output_path (str | Path | None)
progress (Callable[[str], None] | None)
runtime_progress_interval (int | None)

Return type:

GenerationResult

modelwright.generation.infer_generated_module_contract(*, workbook, graph, expressions, output_refs, module_name, input_refs=(), progress=None, inline_provenance_comment_limit=50000, inline_formula_lambda_limit=50000)[source]

Infer a generated module contract by walking dependencies for selected outputs.

Parameters:

workbook (WorkbookRecord)
graph (DependencyGraph)
expressions (Mapping[str, FormulaExpression])
output_refs (Sequence[str])
module_name (str)
input_refs (Sequence[str])
progress (Callable[[str], None] | None)
inline_provenance_comment_limit (int | None)
inline_formula_lambda_limit (int | None)

Return type:

GeneratedContractInferenceResult

modelwright.generation.symbol_name_for_cell_ref(cell_ref)[source]

Build a stable Python identifier from a canonical workbook cell ref.

Parameters:: cell_ref (str)
Return type:: str

Generated Model Execution

Execution helpers for generated Modelwright Python models.

class modelwright.execution.ExecutionDiagnostic(code, message, severity='warning', location=None, raw_value=None)[source]

Execution concern tied to a generated model run.

Parameters:

code (str)
message (str)
severity (Literal['info', 'warning', 'error'])
location (str | None)
raw_value (str | int | float | bool | None | list[Any] | dict[str, Any])

class modelwright.execution.GeneratedExecutionResult(contract, module_path, entrypoint, output_values=<factory>, diagnostics=<factory>)[source]

Observed outputs from one generated Python model execution.

Parameters:

contract (GeneratedModuleContract)
module_path (str)
entrypoint (str)
output_values (dict[str, str | int | float | bool | None | list[Any] | dict[str, Any]])
diagnostics (tuple[ExecutionDiagnostic, ...])

modelwright.execution.execute_generated_model(*, contract, module_path, inputs=None)[source]

Execute a generated Python module and return observed declared outputs.

Parameters:

contract (GeneratedModuleContract)
module_path (str | Path)
inputs (Mapping[str, str | int | float | bool | None | list[Any] | dict[str, Any]] | None)

Return type:

GeneratedExecutionResult

Evaluation Orchestration

Validation orchestration over generated outputs, cached values, and oracles.

class modelwright.evaluation.ValidationEvaluationResult(scenario_id, generated_execution, cached_validation_report=None, oracle_validation_report=None, diagnostics=<factory>)[source]

Generated-model execution plus validation reports for one scenario.

Parameters:

scenario_id (str)
generated_execution (GeneratedExecutionResult)
cached_validation_report (ValidationReport | None)
oracle_validation_report (ValidationReport | None)
diagnostics (tuple[Diagnostic, ...])

modelwright.evaluation.evaluate_generated_model(*, contract, module_path, scenario, workbook=None, oracle_result=None)[source]

Execute a generated model and build available validation reports.

Parameters:

contract (GeneratedModuleContract)
module_path (str | Path)
scenario (ValidationScenario)
workbook (WorkbookRecord | None)
oracle_result (OracleResult | None)

Return type:

ValidationEvaluationResult

Validation Evidence

Compact validation-evidence summaries for generated-model workflows.

This module summarizes artifacts that were already produced by Modelwright generation, execution, and validation steps. It deliberately does not rerun those steps, and it does not copy raw generated source, raw generated output values, workbook contents, or full comparison rows into the shareable summary.

class modelwright.evidence.MatrixEvidenceCaseSummary(case_id, namespace, run_status, evidence_status, equivalence_status, comparable_output_count=None, match_count=None, mismatch_count=None, diagnostic_count=0, error_count=0, warning_count=0, artifact_dir=None, evidence_source='missing', notes=<factory>)[source]

Sanitized generated-model evidence summary for one matrix case.

Parameters:

case_id (str)
namespace (str | None)
run_status (str | None)
evidence_status (Literal['skipped', 'incomplete', 'complete'])
equivalence_status (Literal['pass', 'fail', 'incomplete'])
comparable_output_count (int | None)
match_count (int | None)
mismatch_count (int | None)
diagnostic_count (int)
error_count (int)
warning_count (int)
artifact_dir (str | None)
evidence_source (str)
notes (tuple[str, ...])

to_dict()[source]

Serialize the compact matrix case summary.

Return type:: dict[str, str | int | float | bool | None | list[Any] | dict[str, Any]]

class modelwright.evidence.MatrixEvidencePaths(evidence_id, output_dir, matrix_run_path=None, matrix_summary_path=None, artifact_root=None, summary_json_path=None, summary_markdown_path=None)[source]

Filesystem contract for compact matrix-evidence aggregation.

Parameters:

evidence_id (str)
output_dir (Path)
matrix_run_path (Path | None)
matrix_summary_path (Path | None)
artifact_root (Path | None)
summary_json_path (Path | None)
summary_markdown_path (Path | None)

class modelwright.evidence.MatrixEvidenceSummary(evidence_id, matrix_id, evidence_status, equivalence_status, case_count, complete_count, incomplete_count, skipped_count, pass_count, fail_count, diagnostic_count=0, error_count=0, warning_count=0, artifacts=<factory>, cases=<factory>, notes=<factory>)[source]

Sanitized generated-model evidence summary for a FreshForge matrix.

Parameters:

evidence_id (str)
matrix_id (str | None)
evidence_status (Literal['skipped', 'incomplete', 'complete'])
equivalence_status (Literal['pass', 'fail', 'incomplete'])
case_count (int)
complete_count (int)
incomplete_count (int)
skipped_count (int)
pass_count (int)
fail_count (int)
diagnostic_count (int)
error_count (int)
warning_count (int)
artifacts (dict[str, str])
cases (tuple[MatrixEvidenceCaseSummary, ...])
notes (tuple[str, ...])

to_dict()[source]

Serialize the compact matrix evidence summary.

Return type:: dict[str, str | int | float | bool | None | list[Any] | dict[str, Any]]

class modelwright.evidence.ValidationEvidencePaths(evidence_id, artifact_dir, output_dir, inference_result_path, generation_result_path, generated_values_path, validation_scenario_path, evaluation_report_path, summary_json_path, summary_markdown_path)[source]

Filesystem contract for compact validation-evidence extraction.

Parameters:

evidence_id (str)
artifact_dir (Path)
output_dir (Path)
inference_result_path (Path)
generation_result_path (Path)
generated_values_path (Path)
validation_scenario_path (Path)
evaluation_report_path (Path)
summary_json_path (Path)
summary_markdown_path (Path)

property required_artifact_paths: tuple[Path, ...]: Return artifacts used as evidence inputs.

class modelwright.evidence.ValidationEvidenceSummary(evidence_id, evidence_status, equivalence_status, missing_artifacts=<factory>, artifacts=<factory>, stages=<factory>, comparison=<factory>, notes=<factory>)[source]

Sanitized validation-evidence summary for publication or CI artifacts.

Parameters:

evidence_id (str)
evidence_status (Literal['skipped', 'incomplete', 'complete'])
equivalence_status (Literal['pass', 'fail', 'incomplete'])
missing_artifacts (tuple[str, ...])
artifacts (dict[str, str])
stages (dict[str, str | int | float | bool | None | list[Any] | dict[str, Any]])
comparison (dict[str, str | int | float | bool | None | list[Any] | dict[str, Any]])
notes (tuple[str, ...])

to_dict()[source]

Serialize the compact evidence summary.

Return type:: dict[str, str | int | float | bool | None | list[Any] | dict[str, Any]]

modelwright.evidence.extract_matrix_evidence(paths=None, *, evidence_id='generated-model-matrix', matrix_run_path=None, matrix_summary_path=None, artifact_root=None, output_dir=None, require_evidence=False)[source]

Aggregate compact evidence from an existing FreshForge matrix run or summary.

Parameters:

paths (MatrixEvidencePaths | None)
evidence_id (str)
matrix_run_path (str | Path | None)
matrix_summary_path (str | Path | None)
artifact_root (str | Path | None)
output_dir (str | Path | None)
require_evidence (bool)

Return type:

MatrixEvidenceSummary

modelwright.evidence.extract_validation_evidence(paths=None, *, evidence_id='generated-model', artifact_dir=None, output_dir=None, validation_scenario_path=None, require_artifacts=False)[source]

Extract compact evidence from existing generated-model workflow artifacts.

Parameters:

paths (ValidationEvidencePaths | None)
evidence_id (str)
artifact_dir (str | Path | None)
output_dir (str | Path | None)
validation_scenario_path (str | Path | None)
require_artifacts (bool)

Return type:

ValidationEvidenceSummary

modelwright.evidence.matrix_evidence_paths(*, evidence_id='generated-model-matrix', output_dir=None, matrix_run_path=None, matrix_summary_path=None, artifact_root=None)[source]

Build the generic path contract for matrix evidence aggregation.

Parameters:

evidence_id (str)
output_dir (str | Path | None)
matrix_run_path (str | Path | None)
matrix_summary_path (str | Path | None)
artifact_root (str | Path | None)

Return type:

MatrixEvidencePaths

modelwright.evidence.validation_evidence_paths(*, evidence_id='generated-model', artifact_dir=None, output_dir=None, validation_scenario_path=None)[source]

Build the generic path contract for validation-evidence extraction.

Parameters:

evidence_id (str)
artifact_dir (str | Path | None)
output_dir (str | Path | None)
validation_scenario_path (str | Path | None)

Return type:

ValidationEvidencePaths

modelwright.evidence.write_matrix_evidence(summary, paths=None, *, output_dir=None)[source]

Write compact matrix evidence summary.json and summary.md.

Parameters:

summary (MatrixEvidenceSummary)
paths (MatrixEvidencePaths | None)
output_dir (str | Path | None)

Return type:

modelwright.evidence.write_validation_evidence(summary, paths=None, *, output_dir=None)[source]

Write summary.json and summary.md for compact evidence.

Parameters:

summary (ValidationEvidenceSummary)
paths (ValidationEvidencePaths | None)
output_dir (str | Path | None)

Return type:

Conversion Planning

Conversion plan records and assembly helpers.

class modelwright.conversion.ConversionPlan(plan_id, created_at, modelwright_commit, source, workflow_status, coverage, diagnostic_summary, residual_blockers=<factory>, generation=<factory>, validation=<factory>, recommendations=<factory>, privacy_review=<factory>)[source]

Inspectable plan for partial or complete workbook conversion.

Parameters:

plan_id (str)
created_at (str)
modelwright_commit (str)
source (ConversionSource)
workflow_status (WorkflowStatus)
coverage (CoverageSummary)
diagnostic_summary (DiagnosticSummary)
residual_blockers (tuple[ResidualBlocker, ...])
generation (GenerationSummary)
validation (ValidationSummary)
recommendations (tuple[PlanRecommendation, ...])
privacy_review (PrivacyReview)

class modelwright.conversion.ConversionSource(workbook_id, file_type, benchmark_role, source_path=None, sanitized=True)[source]

Source workbook identity and benchmark role.

Parameters:

workbook_id (str)
file_type (str)
benchmark_role (Literal['primary_benchmark', 'stress_benchmark', 'broken_reference_regression', 'synthetic_fixture', 'ad_hoc_private'])
source_path (str | None)
sanitized (bool)

class modelwright.conversion.CoverageSummary(sheets, cells, value_cells, formula_cells, translated_formula_cells, untranslated_formula_cells, translation_coverage, named_ranges, dependency_edges, semantic_edges, execution_edges)[source]

Workbook coverage counts for conversion planning.

Parameters:

sheets (int)
cells (int)
value_cells (int)
formula_cells (int)
translated_formula_cells (int)
untranslated_formula_cells (int)
translation_coverage (float)
named_ranges (int)
dependency_edges (int)
semantic_edges (int)
execution_edges (int)

class modelwright.conversion.DiagnosticSummary(workbook_extraction=<factory>, named_ranges=<factory>, formula_extraction=<factory>, graph=<factory>, translation=<factory>, generation=<factory>, cached_validation=<factory>, oracle_validation=<factory>)[source]

Diagnostic counts by workflow stage.

Parameters:

workbook_extraction (dict[str, int])
named_ranges (dict[str, int])
formula_extraction (dict[str, int])
graph (dict[str, int])
translation (dict[str, int])
generation (dict[str, int])
cached_validation (dict[str, int])
oracle_validation (dict[str, int])

class modelwright.conversion.GenerationSummary(generated=False, generated_model_path=None, selected_outputs=0, selected_input_dependencies=0, selection_strategy='not_run', full_workbook_model=False)[source]

Generated model summary for conversion planning.

Parameters:

generated (bool)
generated_model_path (str | None)
selected_outputs (int)
selected_input_dependencies (int)
selection_strategy (str)
full_workbook_model (bool)

class modelwright.conversion.PlanRecommendation(priority, action, rationale, target_issue=None)[source]

Recommended next action from a conversion plan.

Parameters:

priority (int)
action (str)
rationale (str)
target_issue (int | None)

class modelwright.conversion.PrivacyReview(contains_source_path=False, contains_sheet_names=False, contains_named_ranges=False, contains_raw_formulas=False, contains_raw_cell_values=False, contains_generated_source=False)[source]

Privacy flags for local or tracked conversion plans.

Parameters:

contains_source_path (bool)
contains_sheet_names (bool)
contains_named_ranges (bool)
contains_raw_formulas (bool)
contains_raw_cell_values (bool)
contains_generated_source (bool)

class modelwright.conversion.ResidualBlocker(blocker_id, category, diagnostic_code, item, count, severity, disposition, next_action, provenance)[source]

Classified residual blocker for conversion planning.

Parameters:

blocker_id (str)
category (Literal['source_workbook_defect', 'unsupported_formula_semantics', 'unsupported_reference_semantics', 'graph_semantics', 'generation_scope', 'validation_oracle', 'missing_cached_values', 'external_dependency', 'unknown'])
diagnostic_code (str)
item (str)
count (int)
severity (Literal['info', 'warning', 'error'])
disposition (Literal['resolved', 'blocked_by_design', 'deferred', 'out_of_scope', 'next_target'])
next_action (str)
provenance (str)

class modelwright.conversion.ValidationSummary(cached_validation_status='not_run', cached_outputs=0, cached_mismatches=0, oracle_backend=None, oracle_status='not_run', oracle_mismatches=0, oracle_blockers=<factory>)[source]

Validation summary for generated outputs.

Parameters:

cached_validation_status (Literal['pass', 'fail', 'blocked', 'not_run'])
cached_outputs (int)
cached_mismatches (int)
oracle_backend (str | None)
oracle_status (Literal['pass', 'fail', 'blocked', 'not_run'])
oracle_mismatches (int)
oracle_blockers (tuple[str, ...])

class modelwright.conversion.WorkflowStatus(extraction='not_run', dependency_graph='not_run', formula_translation='not_run', generation='not_run', cached_validation='not_run', oracle_validation='not_run', overall='blocked')[source]

Stage-level conversion workflow status.

Parameters:

extraction (Literal['pass', 'blocked', 'not_run'])
dependency_graph (Literal['pass', 'blocked', 'not_run'])
formula_translation (Literal['pass', 'blocked', 'not_run'])
generation (Literal['pass', 'blocked', 'not_run'])
cached_validation (Literal['pass', 'fail', 'blocked', 'not_run'])
oracle_validation (Literal['pass', 'fail', 'blocked', 'not_run'])
overall (Literal['complete', 'partial', 'blocked'])

modelwright.conversion.build_conversion_plan(*, plan_id, workbook, graph, expressions, benchmark_role, modelwright_commit='unknown', generation_result=None, cached_validation_report=None, oracle_validation_report=None, oracle_blockers=(), generated_model_path=None, include_source_path=False, full_workbook_model=False)[source]

Build a JSON-serializable conversion plan from workflow records.

Parameters:

plan_id (str)
workbook (WorkbookRecord)
graph (DependencyGraph)
expressions (Mapping[str, FormulaExpression])
benchmark_role (Literal['primary_benchmark', 'stress_benchmark', 'broken_reference_regression', 'synthetic_fixture', 'ad_hoc_private'])
modelwright_commit (str)
generation_result (GenerationResult | None)
cached_validation_report (ValidationReport | None)
oracle_validation_report (ValidationReport | None)
oracle_blockers (tuple[str, ...])
generated_model_path (str | None)
include_source_path (bool)
full_workbook_model (bool)

Return type:

ConversionPlan

Wrapper Facades

Lightweight facades for generated Modelwright models.

class modelwright.wrappers.CellRef(cell_ref, name, label=None, role='metadata', unit=None, description=None)[source]

Declared facade metadata for one generated-model cell reference.

Parameters:

cell_ref (str)
name (str)
label (str | None)
role (Literal['input', 'output', 'intermediate', 'metadata'])
unit (str | None)
description (str | None)

class modelwright.wrappers.CellView(cell_ref, name=None, label=None, role=None, unit=None, description=None, value=None, has_value=False)[source]

Inspection payload for one cell in a facade scenario.

Parameters:

cell_ref (str)
name (str | None)
label (str | None)
role (Literal['input', 'output', 'intermediate', 'metadata'] | None)
unit (str | None)
description (str | None)
value (object)
has_value (bool)

class modelwright.wrappers.ModelFacade(generated_model, *, cells=(), tables=(), reports=())[source]

Analyst-facing facade around a generated Modelwright model.

Parameters:

generated_model (ModuleType | GeneratedCalculate | object)
cells (tuple[CellRef, ...] | list[CellRef])
tables (tuple[TableRef, ...] | list[TableRef])
reports (tuple[ReportRef, ...] | list[ReportRef])

class modelwright.wrappers.ReportRef(name, cells=(), tables=(), label=None, description=None)[source]

Declared named output bundle.

Parameters:

name (str)
cells (tuple[str, ...])
tables (tuple[str, ...])
label (str | None)
description (str | None)

class modelwright.wrappers.Scenario(name='default', _inputs=<factory>)[source]

Immutable input override set for a facade calculation.

Parameters:

name (str)
_inputs (tuple[tuple[str, object], ...])

class modelwright.wrappers.TableRef(name, sheet, range_ref, cell_refs, row_labels, column_labels, role='output', label=None, description=None)[source]

Declared rectangular workbook-like table facade.

Parameters:

name (str)
sheet (str)
range_ref (str)
cell_refs (tuple[tuple[str, ...], ...])
row_labels (tuple[str, ...])
column_labels (tuple[str, ...])
role (Literal['input', 'output', 'intermediate', 'metadata'])
label (str | None)
description (str | None)

class modelwright.wrappers.TableView(name, sheet, range_ref, rows, columns, cell_refs, values, label=None, description=None)[source]

Calculated rectangular table payload.

Parameters:

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)
description (str | None)

exception modelwright.wrappers.WrapperDeclarationError[source]: Raised when wrapper declarations are malformed or inconsistent.

exception modelwright.wrappers.WrapperExecutionError[source]: Raised when a generated model cannot be executed through a facade.

modelwright.wrappers.cell(cell_ref, *, name=None, label=None, role='metadata', unit=None, description=None)[source]

Declare one facade cell.

Parameters:

cell_ref (str)
name (str | None)
label (str | None)
role (Literal['input', 'output', 'intermediate', 'metadata'])
unit (str | None)
description (str | None)

Return type:

CellRef

modelwright.wrappers.report(name, *, cells=(), tables=(), label=None, description=None)[source]

Declare one structured report selection.

Parameters:

name (str)
cells (tuple[str, ...] | list[str])
tables (tuple[str, ...] | list[str])
label (str | None)
description (str | None)

Return type:

ReportRef

modelwright.wrappers.table(name, *, sheet=None, range_ref, row_labels=None, column_labels=None, role='output', label=None, description=None)[source]

Declare one rectangular facade table.

Parameters:

name (str)
sheet (str | None)
range_ref (str)
row_labels (tuple[str, ...] | list[str] | None)
column_labels (tuple[str, ...] | list[str] | None)
role (Literal['input', 'output', 'intermediate', 'metadata'])
label (str | None)
description (str | None)

Return type:

TableRef

Notebook Helpers

Notebook-friendly DataFrame helpers for wrapped generated models.

exception modelwright.notebooks.NotebookDependencyError[source]: Raised when notebook helpers need an optional dependency that is not installed.

modelwright.notebooks.compare_scenarios_frame(facade, baseline, scenario, *, cells=None)[source]

Compare declared output cells between two scenarios as a tidy DataFrame.

Parameters:

facade (ModelFacade)
baseline (Scenario)
scenario (Scenario)
cells (Iterable[str] | None)

Return type:

pd.DataFrame

modelwright.notebooks.inputs_frame(facade, scenario=None)[source]

Return declared facade inputs as a tidy pandas DataFrame.

Parameters:

facade (ModelFacade)
scenario (Scenario | None)

Return type:

pd.DataFrame

modelwright.notebooks.outputs_frame(facade, scenario=None)[source]

Return declared facade outputs as a tidy pandas DataFrame.

Parameters:

facade (ModelFacade)
scenario (Scenario | None)

Return type:

pd.DataFrame

modelwright.notebooks.report_frames(facade, name, scenario=None)[source]

Return DataFrame payloads for a declared facade report.

Parameters:

facade (ModelFacade)
name (str)
scenario (Scenario | None)

Return type:

dict[str, Any]

modelwright.notebooks.scenario_frame(scenario)[source]

Return scenario input overrides as a tidy pandas DataFrame.

Parameters:: scenario (Scenario)
Return type:: pd.DataFrame

modelwright.notebooks.table_frame(facade, name, scenario=None)[source]

Return a declared facade table as a pandas DataFrame.

Parameters:

facade (ModelFacade)
name (str)
scenario (Scenario | None)

Return type:

pd.DataFrame

FreshForge Provider

FreshForge provider integration for Modelwright workflow stages.

class modelwright.freshforge.ModelwrightFreshForgeProvider[source]

FreshForge provider for Modelwright workflow stages.

metadata()[source]

Return FreshForge provider metadata.

Return type:: Any

run_node(node, node_type, *, context)[source]

Execute one supported generated-model workflow node.

Parameters:

node (Any)
node_type (Any)
context (Any)

Return type:

Any

validate_node(node, node_type, *, location)[source]

Validate broad Modelwright node shape without executing Modelwright.

Parameters:

node (Any)
node_type (Any)
location (str)

Return type:

tuple[Any, …]

modelwright.freshforge.provider_factory()[source]

Return the Modelwright FreshForge provider for entry-point discovery.

Return type:: ModelwrightFreshForgeProvider

Validation

Validation report records.

These objects describe validation results; they do not run workbook or generated model comparisons themselves.

class modelwright.validation.ComparisonResult(scenario_id, cell_ref, kind, generated, oracle, matches, tolerance, difference, diagnostic_code, message, oracle_backend)[source]

Comparison result for one declared workbook output.

Parameters:

scenario_id (str)
cell_ref (str)
kind (Literal['number', 'text', 'boolean', 'blank', 'error'])
generated (str | int | float | bool | None | list[Any] | dict[str, Any])
oracle (str | int | float | bool | None | list[Any] | dict[str, Any])
matches (bool)
tolerance (float | None)
difference (float | None)
diagnostic_code (str | None)
message (str)
oracle_backend (str)

class modelwright.validation.ComparisonRules(default_numeric_tolerance=1e-09, default_numeric_relative_tolerance=0.0, text='exact', boolean='exact')[source]

Default comparison rules declared by a validation scenario.

Parameters:

default_numeric_tolerance (float)
default_numeric_relative_tolerance (float)
text (Literal['exact'])
boolean (Literal['exact'])

class modelwright.validation.Diagnostic(diagnostic_code, message, severity='warning', location=None)[source]

Run-level diagnostic not tied to one output comparison.

Parameters:

diagnostic_code (str)
message (str)
severity (Literal['info', 'warning', 'error'])
location (str | None)

class modelwright.validation.OracleConfig(backend, options=<factory>)[source]

Oracle backend configuration from a validation scenario.

Parameters:

backend (str)
options (dict[str, str | int | float | bool | None | list[Any] | dict[str, Any]])

class modelwright.validation.ScenarioInput(cell_ref, value, kind, source=None)[source]

Input override declared by a validation scenario.

Parameters:

cell_ref (str)
value (str | int | float | bool | None | list[Any] | dict[str, Any])
kind (Literal['number', 'text', 'boolean', 'blank', 'error'])
source (str | None)

class modelwright.validation.ScenarioOutput(cell_ref, kind, tolerance=None)[source]

Output expectation declared by a validation scenario.

Parameters:

cell_ref (str)
kind (Literal['number', 'text', 'boolean', 'blank', 'error'])
tolerance (float | None)

class modelwright.validation.ValidationReport(scenario_id, oracle_backend, comparisons=<factory>, diagnostics=<factory>)[source]

Validation report for one scenario.

Parameters:

scenario_id (str)
oracle_backend (str)
comparisons (tuple[ComparisonResult, ...])
diagnostics (tuple[Diagnostic, ...])

class modelwright.validation.ValidationScenario(scenario_id, description, source_workbook, generated_model, oracle, inputs, outputs, comparison)[source]

Validation scenario loaded from a JSON boundary.

Parameters:

scenario_id (str)
description (str)
source_workbook (str)
generated_model (str)
oracle (OracleConfig)
inputs (tuple[ScenarioInput, ...])
outputs (tuple[ScenarioOutput, ...])
comparison (ComparisonRules)

modelwright.validation.build_validation_report(*, scenario, generated_values, oracle_values)[source]

Build a report from scenario outputs and already-observed values.

Parameters:

scenario (ValidationScenario)
generated_values (Mapping[str, str | int | float | bool | None | list[Any] | dict[str, Any]])
oracle_values (Mapping[str, str | int | float | bool | None | list[Any] | dict[str, Any]])

Return type:

ValidationReport

modelwright.validation.compare_scalar_output(*, scenario_id, output, generated, oracle, oracle_backend, default_numeric_tolerance=1e-09, default_numeric_relative_tolerance=0.0)[source]

Compare one observed generated value against one oracle value.

Parameters:

scenario_id (str)
output (ScenarioOutput)
generated (str | int | float | bool | None | list[Any] | dict[str, Any] | _MissingValue)
oracle (str | int | float | bool | None | list[Any] | dict[str, Any] | _MissingValue)
oracle_backend (str)
default_numeric_tolerance (float)
default_numeric_relative_tolerance (float)

Return type:

ComparisonResult

modelwright.validation.load_validation_scenario(path)[source]

Load a validation scenario JSON file from disk.

Parameters:: path (str | Path)
Return type:: ValidationScenario

Oracle Interfaces

Workbook oracle interface records.

Oracle implementations evaluate source workbook outputs for validation. This module defines the boundary only; backend-specific execution belongs in separate modules.

class modelwright.oracles.OracleDiagnostic(diagnostic_code, message, severity='warning', location=None, raw_value=None)[source]

Diagnostic produced while asking a workbook oracle for observed values.

Parameters:

diagnostic_code (str)
message (str)
severity (Literal['info', 'warning', 'error'])
location (str | None)
raw_value (str | int | float | bool | None | list[Any] | dict[str, Any])

class modelwright.oracles.OracleRequest(source_workbook, outputs, inputs=<factory>, options=<factory>)[source]

Request for observed workbook output values from one oracle backend.

Parameters:

source_workbook (str)
outputs (tuple[ScenarioOutput, ...])
inputs (tuple[ScenarioInput, ...])
options (dict[str, str | int | float | bool | None | list[Any] | dict[str, Any]])

class modelwright.oracles.OracleResult(backend, source_workbook, outputs=<factory>, diagnostics=<factory>)[source]

Observed workbook output values returned by an oracle backend.

Parameters:

backend (str)
source_workbook (str)
outputs (dict[str, str | int | float | bool | None | list[Any] | dict[str, Any]])
diagnostics (tuple[OracleDiagnostic, ...])

class modelwright.oracles.WorkbookOracle(*args, **kwargs)[source]

Protocol implemented by source-workbook oracle backends.

evaluate(request)[source]

Return observed workbook values for the requested outputs.

Parameters:: request (OracleRequest)
Return type:: OracleResult

modelwright.oracles.missing_optional_dependency_diagnostic(*, dependency, extra, backend)[source]

Build a standard diagnostic for an unavailable optional oracle backend.

Parameters:

dependency (str)
extra (str)
backend (str)

Return type:

OracleDiagnostic

formulas-backed workbook oracle.

class modelwright.formulas_oracle.FormulasWorkbookOracle(*args, **kwargs)[source]

Evaluate workbook outputs with the optional formulas package.

evaluate(request)[source]

Return observed workbook values for the requested outputs.

Parameters:: request (OracleRequest)
Return type:: OracleResult

Validation report helpers for oracle-backed comparisons.

modelwright.oracle_validation.build_oracle_validation_report(*, scenario, generated_values, oracle_result)[source]

Compare generated values against an oracle result for one scenario.

Parameters:

scenario (ValidationScenario)
generated_values (Mapping[str, str | int | float | bool | None | list[Any] | dict[str, Any]])
oracle_result (OracleResult)

Return type:

ValidationReport