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:
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.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

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:
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:
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:
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:
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:
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:
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:
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:
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:
Return type:

ValidationEvaluationResult

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:
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:
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:
Return type:

pd.DataFrame

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

Return declared facade inputs as a tidy pandas DataFrame.

Parameters:
Return type:

pd.DataFrame

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

Return declared facade outputs as a tidy pandas DataFrame.

Parameters:
Return type:

pd.DataFrame

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

Return DataFrame payloads for a declared facade report.

Parameters:
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:
Return type:

pd.DataFrame

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:
class modelwright.validation.ValidationScenario(scenario_id, description, source_workbook, generated_model, oracle, inputs, outputs, comparison)[source]

Validation scenario loaded from a JSON boundary.

Parameters:
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