API Reference

The module-level APIs are the preferred implementation imports. The package root also exposes a curated convenience facade for notebook use.

Package Facade

FABLE Calculator-specific notebook helpers for Modelwright-generated models.

class fable_pyculator.FableBenchmarkMatrixEvidencePaths(workbook_version, evidence_id, output_dir, artifact_root, matrix_run_path, matrix_summary_path, modelwright_summary_json_path, modelwright_summary_markdown_path, benchmark_summary_json_path, benchmark_summary_markdown_path)[source]

Path contract for FABLE-facing benchmark matrix evidence packaging.

Parameters:

  • workbook_version (str)

  • evidence_id (str)

  • output_dir (Path)

  • artifact_root (Path)

  • matrix_run_path (Path | None)

  • matrix_summary_path (Path | None)

  • modelwright_summary_json_path (Path)

  • modelwright_summary_markdown_path (Path)

  • benchmark_summary_json_path (Path)

  • benchmark_summary_markdown_path (Path)

class fable_pyculator.FableBenchmarkMatrixEvidenceSummary(workbook_version, evidence_backend, evidence_id, evidence_status, equivalence_status, case_count, complete_count, incomplete_count, skipped_count, pass_count, fail_count, diagnostic_count, error_count, warning_count, paths, modelwright_summary, notes=())[source]

Compact FABLE-facing summary of a generated-model benchmark matrix.

Parameters:

  • workbook_version (str)

  • evidence_backend (Literal['modelwright'])

  • evidence_id (str)

  • evidence_status (str)

  • equivalence_status (str)

  • 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)

  • paths (dict[str, str | None])

  • modelwright_summary (dict[str, Any])

  • notes (tuple[str, ...])

to_dict()[source]

Return a stable JSON-serializable representation.

Return type:

dict[str, Any]

class fable_pyculator.FableBenchmarkRunPaths(workbook_version, artifact_dir, output_dir, benchmark_summary_json_path, benchmark_summary_markdown_path, validation_summary_json_path, validation_summary_markdown_path, workflow_path, freshforge_run_summary_path)[source]

Path contract for one opt-in FABLE benchmark evidence run.

Parameters:

  • workbook_version (str)

  • artifact_dir (Path)

  • output_dir (Path)

  • benchmark_summary_json_path (Path)

  • benchmark_summary_markdown_path (Path)

  • validation_summary_json_path (Path)

  • validation_summary_markdown_path (Path)

  • workflow_path (Path)

  • freshforge_run_summary_path (Path)

class fable_pyculator.FableBenchmarkRunSummary(workbook_version, mode, evidence_backend, evidence_status, equivalence_status, missing_artifacts, comparison, paths, freshforge=<factory>, scenario_bundle=<factory>, notes=())[source]

Compact benchmark orchestration summary safe for docs or CI artifacts.

Parameters:

  • workbook_version (str)

  • mode (Literal['evidence-only', 'freshforge-plan', 'freshforge-run'])

  • evidence_backend (Literal['modelwright', 'fable-local'])

  • evidence_status (str)

  • equivalence_status (str)

  • missing_artifacts (tuple[str, ...])

  • comparison (dict[str, Any])

  • paths (dict[str, str])

  • freshforge (dict[str, Any])

  • scenario_bundle (dict[str, Any])

  • notes (tuple[str, ...])

to_dict()[source]

Return a stable JSON-serializable representation.

Return type:

dict[str, Any]

class fable_pyculator.FableCalculatorSpec(parameters=<factory>, selection_controls=<factory>, scenario_definition_tables=<factory>, outputs=<factory>, output_tables=<factory>, headline_series=<factory>, workbook_id=None, provenance=None)[source]

Notebook-facing declaration of FABLE scenario inputs and outputs.

The spec is the central object passed to FABLE Pyculator control, execution, and rendering helpers. It keeps input declarations, discovered definition-table metadata, output declarations, and workbook provenance together while preserving their distinct semantics.

Parameters:
input_mapping(values)[source]

Convert friendly scenario values to generated-model cell inputs.

Values may reference curated scalar parameters or discovered selection controls by name. Unknown names are rejected so notebook typos do not silently produce partial scenarios.

Parameters:

values (dict[str, object])

Return type:

dict[str, object]

class fable_pyculator.FableFreshForgeBuildPaths(workbook_path, artifact_dir, output_refs_path, workflow_path, contract_path, expressions_path, constants_path, inference_result_path, generation_result_path, generated_model_path, generated_values_path, validation_scenario_path, evaluation_report_path)[source]

Version-specific artifact paths for a FABLE Modelwright/FreshForge build.

Parameters:

  • workbook_path (Path)

  • artifact_dir (Path)

  • output_refs_path (Path)

  • workflow_path (Path)

  • contract_path (Path)

  • expressions_path (Path)

  • constants_path (Path)

  • inference_result_path (Path)

  • generation_result_path (Path)

  • generated_model_path (Path)

  • generated_values_path (Path)

  • validation_scenario_path (Path)

  • evaluation_report_path (Path)

class fable_pyculator.FableFreshForgeRebuildPlan(paths, output_refs, validation_scenario, workflow)[source]

Prepared artifacts for a FABLE Modelwright/FreshForge rebuild.

The plan records the ignored local paths and JSON payloads produced before FreshForge execution. It is intentionally not an execution result: callers may inspect these files, run freshforge plan, or explicitly opt into a long freshforge run after review.

Parameters:

  • paths (FableFreshForgeBuildPaths)

  • output_refs (tuple[str, ...])

  • validation_scenario (dict[str, Any])

  • workflow (dict[str, Any])

property comparable_output_count: int

Return the count of nonblank cached workbook outputs in the validation scenario.

class fable_pyculator.HeadlinePoint(year, cell_refs)[source]

One year/value point in a curated headline output series.

Parameters:

  • year (int | str)

  • cell_refs (tuple[str, ...] | list[str])

class fable_pyculator.HeadlineSeries(name, label, group, sheet, table_name, points, unit=None, description=None, aggregation='value')[source]

One curated notebook headline series built from FABLE output tables.

A series is intentionally narrower than a full output table. It describes the source table, source cell references, units, and aggregation rule needed to render a compact analyst-facing time series.

Parameters:

  • name (str)

  • label (str)

  • group (str)

  • sheet (str)

  • table_name (str)

  • points (tuple[HeadlinePoint, ...] | list[HeadlinePoint])

  • unit (str | None)

  • description (str | None)

  • aggregation (Literal['value', 'sum'])

class fable_pyculator.NotebookLoopResult(run, output_tables, headline_frames, headline_figures, skipped_output_tables=<factory>)[source]

Rendered notebook artifacts from one FABLE Pyculator scenario run.

Parameters:

  • run (ScenarioRun)

  • output_tables (dict[str, Any])

  • headline_frames (dict[str, Any])

  • headline_figures (dict[str, Any])

  • skipped_output_tables (dict[str, str])

class fable_pyculator.OutputIndicator(name, label, cell_ref, unit=None, group=None, description=None)[source]

One scalar output cell rendered from a generated Modelwright model.

Parameters:

  • name (str)

  • label (str)

  • cell_ref (str)

  • unit (str | None)

  • group (str | None)

  • description (str | None)

class fable_pyculator.OutputRefStrategyCase(case_id, strategy, label, column_flavour_tags='OUTPUT-*', table_names=(), description='')[source]

One named output-ref boundary to compare.

Parameters:

  • case_id (str)

  • strategy (Literal['output-columns', 'headline-only', 'table', 'flavour-tags', 'all-columns'])

  • label (str)

  • column_flavour_tags (str | tuple[str, ...] | None)

  • table_names (tuple[str, ...])

  • description (str)

to_dict()[source]

Return a stable JSON representation.

Return type:

dict[str, Any]

class fable_pyculator.OutputRefStrategyComparisonEntry(case, output_ref_count, comparable_output_count, output_refs_path, workflow_path, run_namespace, evidence_source=None, evidence_summary=None, freshforge_run_summary=None)[source]

Compact comparison result for one strategy case.

Parameters:

  • case (OutputRefStrategyCase)

  • output_ref_count (int)

  • comparable_output_count (int)

  • output_refs_path (Path)

  • workflow_path (Path | None)

  • run_namespace (str)

  • evidence_source (str | None)

  • evidence_summary (dict[str, Any] | None)

  • freshforge_run_summary (dict[str, Any] | None)

to_dict()[source]

Return a stable JSON representation.

Return type:

dict[str, Any]

class fable_pyculator.OutputRefStrategyComparisonPaths(workbook_version, output_dir, summary_json_path, summary_markdown_path)[source]

Path layout for one strategy-comparison run.

Parameters:

  • workbook_version (str)

  • output_dir (Path)

  • summary_json_path (Path)

  • summary_markdown_path (Path)

case_dir(case_id)[source]

Return the per-case artifact directory.

Parameters:

case_id (str)

Return type:

Path

property matrix_path: Path

Return the default FreshForge matrix YAML path.

property matrix_template_path: Path

Return the default FreshForge matrix workflow-template YAML path.

output_refs_path(case_id)[source]

Return the per-case output refs JSON path.

Parameters:

case_id (str)

Return type:

Path

workflow_path(case_id)[source]

Return the per-case FreshForge workflow JSON path.

Parameters:

case_id (str)

Return type:

Path

class fable_pyculator.OutputRefStrategyComparisonResult(workbook_version, paths, entries, notes=<factory>)[source]

Collection of compared FABLE output-ref strategies.

Parameters:
to_dict()[source]

Return a stable JSON representation.

Return type:

dict[str, Any]

class fable_pyculator.OutputRefStrategyMatrixPaths(workbook_version, output_dir, matrix_path, workflow_template_path)[source]

Path layout for a FreshForge matrix built from a strategy comparison.

Parameters:

  • workbook_version (str)

  • output_dir (Path)

  • matrix_path (Path)

  • workflow_template_path (Path)

to_dict()[source]

Return a stable JSON representation.

Return type:

dict[str, Any]

class fable_pyculator.OutputRefStrategyMatrixResult(workbook_version, paths, matrix, workflow_template, case_count, notes=<factory>)[source]

Prepared FreshForge matrix artifacts for strategy comparison cases.

Parameters:

  • workbook_version (str)

  • paths (OutputRefStrategyMatrixPaths)

  • matrix (dict[str, Any])

  • workflow_template (dict[str, Any])

  • case_count (int)

  • notes (tuple[str, ...])

to_dict()[source]

Return a stable JSON representation.

Return type:

dict[str, Any]

class fable_pyculator.OutputTable(name, sheet, range_ref, cell_refs, row_labels, column_labels, values=(), column_flavour_tags=(), raw_column_flavour_tags=(), column_flavour_tag_refs=(), label=None, description=None)[source]

One rectangular output table on a canonical FABLE output sheet.

column_flavour_tags stores output-sheet flavour metadata such as DIRECT, DATA-5, or OUTPUT-8. That vocabulary belongs to output tables only; scenario-definition input tables use column_role_tags instead.

Parameters:

  • name (str)

  • sheet (str)

  • range_ref (str)

  • cell_refs (tuple[tuple[str, ...], ...])

  • row_labels (tuple[str, ...])

  • column_labels (tuple[str, ...])

  • values (tuple[tuple[object, ...], ...] | list[list[object]] | tuple[()])

  • column_flavour_tags (tuple[str | None, ...] | list[str | None])

  • raw_column_flavour_tags (tuple[str | None, ...] | list[str | None])

  • column_flavour_tag_refs (tuple[str | None, ...] | list[str | None])

  • label (str | None)

  • description (str | None)

class fable_pyculator.ScenarioBundle(version, bundle_id, workbook_version, scenarios, render=ScenarioBundleRenderOptions(output_table_names=None, output_table_column_flavour_tags=None, include_context_columns=True, headline_series_names=None, include_figures=False), description=None)[source]

A version-aware collection of named FABLE selection-control scenarios.

Parameters:
class fable_pyculator.ScenarioBundleArtifactPaths(output_dir, normalized_bundle_path, manifest_path)[source]

Ignored local output paths for a scenario-bundle run.

Parameters:

  • output_dir (Path)

  • normalized_bundle_path (Path)

  • manifest_path (Path)

scenario_dir(scenario_id)[source]

Return the output directory for one scenario id.

Parameters:

scenario_id (str)

Return type:

Path

class fable_pyculator.ScenarioBundleFreshForgeMatrixPaths(scenario_paths, matrix_path, workflow_template_path, matrix_summary_path)[source]

Ignored local paths for FreshForge matrix scenario-bundle orchestration.

Parameters:
property output_dir: Path

Return the scenario-bundle output root used as the FreshForge matrix workdir.

class fable_pyculator.ScenarioBundleFreshForgeMatrixPlan(bundle, paths, matrix, workflow_template, case_count)[source]

Prepared FreshForge matrix for a FABLE scenario bundle.

Parameters:
class fable_pyculator.ScenarioBundleFreshForgePaths(scenario_paths, workflow_path, run_summary_path)[source]

Ignored local paths for FreshForge-backed scenario-bundle orchestration.

Parameters:
namespaced_run_summary_path(run_namespace=None)[source]

Return the run-summary path for a namespace-aware FreshForge run.

Parameters:

run_namespace (str | None)

Return type:

Path

property output_dir: Path

Return the scenario-bundle output root used as the FreshForge workdir.

class fable_pyculator.ScenarioBundleFreshForgePlan(bundle, paths, workflow, run_namespace=None)[source]

Prepared FreshForge workflow for a FABLE scenario bundle.

Parameters:
class fable_pyculator.ScenarioBundleRunResult(bundle, render, scenario_results)[source]

Rendered results from running every scenario in a bundle.

Parameters:
class fable_pyculator.ScenarioCase(scenario_id, selections, label=None, description=None)[source]

One named scenario inside a scenario bundle.

Parameters:

  • scenario_id (str)

  • selections (dict[str, object])

  • label (str | None)

  • description (str | None)

class fable_pyculator.ScenarioControlSurface(spec)[source]

Small ipywidgets-backed control surface for a FABLE scenario spec.

The surface displays scalar parameters and mutually exclusive selection controls. It does not yet render editable widgets for the detailed SCENARIOS definition tables.

Parameters:

spec (FableCalculatorSpec)

set_values(values)[source]

Set current widget values by spec input name.

Parameters:

values (dict[str, object])

Return type:

None

values()[source]

Return current widget values keyed by spec input name.

Return type:

dict[str, object]

class fable_pyculator.ScenarioDefinitionEdit(value, cell_ref=None, table=None, row_label=None, column_label=None)[source]

One requested scenario-definition cell edit.

Parameters:

  • value (str | int | float | bool | None)

  • cell_ref (str | None)

  • table (str | None)

  • row_label (str | None)

  • column_label (str | None)

to_dict()[source]

Return a stable JSON-serializable representation.

Return type:

dict[str, Any]

class fable_pyculator.ScenarioDefinitionEditableCell(table_name, table_label, sheet, cell_ref, row_label, column_label, column_role_tag, original_value, scenario_locations=())[source]

One editable cell from a FABLE SCENARIOS definition table.

Parameters:

  • table_name (str)

  • table_label (str | None)

  • sheet (str)

  • cell_ref (str)

  • row_label (str)

  • column_label (str)

  • column_role_tag (str | None)

  • original_value (object)

  • scenario_locations (tuple[str, ...])

to_dict()[source]

Return a stable JSON-serializable representation.

Return type:

dict[str, Any]

class fable_pyculator.ScenarioDefinitionPatch(version, patch_id, edits, workbook_version=None, description=None)[source]

Versioned collection of scenario-definition edits.

Parameters:

  • version (int)

  • patch_id (str)

  • edits (tuple[ScenarioDefinitionEdit, ...])

  • workbook_version (str | None)

  • description (str | None)

to_dict()[source]

Return a stable JSON-serializable representation.

Return type:

dict[str, Any]

class fable_pyculator.ScenarioDefinitionPatchResult(patch, edits, inputs, editable_cell_count, notes=<factory>)[source]

Validated scenario-definition patch and generated-model input mapping.

Parameters:

  • patch (ScenarioDefinitionPatch)

  • edits (tuple[dict[str, Any], ...])

  • inputs (dict[str, str | int | float | bool | None])

  • editable_cell_count (int)

  • notes (tuple[str, ...])

to_dict()[source]

Return a stable JSON-serializable representation.

Return type:

dict[str, Any]

class fable_pyculator.ScenarioDefinitionTable(name, sheet, range_ref, cell_refs, row_labels, column_labels, values=(), column_role_tags=(), raw_column_role_tags=(), column_role_tag_refs=(), scenario_locations=(), scenario_location_refs=(), label=None, description=None)[source]

One native table on the FABLE SCENARIOS definition sheet.

These records make definition tables inspectable in notebooks. column_role_tags preserves workbook role/source markers such as DIRECT, SCEN, CALC, and DATA-1. The scenario_locations field stores workbook markers such as S.3.C that help users browse related definition tables. The table is not yet an editable widget contract.

Parameters:

  • name (str)

  • sheet (str)

  • range_ref (str)

  • cell_refs (tuple[tuple[str, ...], ...])

  • row_labels (tuple[str, ...])

  • column_labels (tuple[str, ...])

  • values (tuple[tuple[object, ...], ...] | list[list[object]] | list[tuple[object, ...]])

  • column_role_tags (tuple[str | None, ...] | list[str | None])

  • raw_column_role_tags (tuple[str | None, ...] | list[str | None])

  • column_role_tag_refs (tuple[str | None, ...] | list[str | None])

  • scenario_locations (tuple[str, ...] | list[str])

  • scenario_location_refs (tuple[str, ...] | list[str])

  • label (str | None)

  • description (str | None)

class fable_pyculator.ScenarioParameter(name, label, cell_ref, kind='number', unit=None, description=None, default=None, choices=(), source=None)[source]

One scalar FABLE Calculator input exposed as a notebook scenario value.

A parameter maps a friendly Python name to a generated-model cell reference. This record is for curated scalar controls; discovered FABLE-C selection tables should normally use SelectionControl instead.

Parameters:

  • name (str)

  • label (str)

  • cell_ref (str)

  • kind (Literal['number', 'text', 'choice', 'boolean'])

  • unit (str | None)

  • description (str | None)

  • default (object)

  • choices (tuple[object, ...])

  • source (str | None)

class fable_pyculator.ScenarioRun(spec, scenario_name, inputs, values)[source]

Result from running one FABLE Pyculator scenario.

Parameters:

  • spec (FableCalculatorSpec)

  • scenario_name (str)

  • inputs (dict[str, object])

  • values (dict[str, object])

class fable_pyculator.SelectionControl(name, label, table_name, sheet, range_ref, code_header, options, location=None, description=None)[source]

One mutually exclusive FABLE scenario selection table.

FABLE-C selection tables use a first-column x marker. Selecting one option means placing x in that option’s marker cell and clearing all other marker cells in the same table.

Parameters:

  • name (str)

  • label (str)

  • table_name (str)

  • sheet (str)

  • range_ref (str)

  • code_header (str)

  • options (tuple[SelectionOption, ...] | list[SelectionOption])

  • location (str | None)

  • description (str | None)

input_mapping(selected_value)[source]

Return generated-model overrides that place one x in this table.

The returned mapping is keyed by normalized full cell references. It clears unselected marker cells with None because Modelwright scenarios accept explicit cell inputs, not workbook UI gestures.

Parameters:

selected_value (object)

Return type:

dict[str, object]

class fable_pyculator.SelectionOption(value, label, selection_cell_ref, description=None, selected=False)[source]

One selectable row in a FABLE scenario selection table.

Parameters:

  • value (str)

  • label (str | None)

  • selection_cell_ref (str)

  • description (str | None)

  • selected (bool)

class fable_pyculator.ValidationEvidencePaths(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]

Local artifact and compact evidence paths for one FABLE workbook version.

Parameters:

  • 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)

class fable_pyculator.ValidationEvidenceSummary(workbook_version, evidence_status, equivalence_status, missing_artifacts, artifacts, stages, comparison, notes=())[source]

Sanitized validation evidence summary suitable for sharing or uploading.

Parameters:

  • workbook_version (str)

  • evidence_status (str)

  • equivalence_status (str)

  • missing_artifacts (tuple[str, ...])

  • artifacts (dict[str, str])

  • stages (dict[str, dict[str, Any]])

  • comparison (dict[str, Any])

  • notes (tuple[str, ...])

to_dict()[source]

Return a stable JSON-serializable representation.

Return type:

dict[str, Any]

fable_pyculator.build_2020_notebook_spec(workbook_path=PosixPath('tmp/private-workbooks/2020_Open_FABLECalculator.xlsx'), *, workbook_id='fable-c-2020')[source]

Build the notebook spec from the public 2020 FABLE-C workbook structure.

Parameters:

  • workbook_path (str | Path)

  • workbook_id (str)

Return type:

FableCalculatorSpec

fable_pyculator.build_2021_notebook_spec(workbook_path=PosixPath('tmp/private-workbooks/2021_Open_FABLECalculator.xlsx'), *, workbook_id='fable-c-2021')[source]

Build the notebook spec from the public 2021 FABLE-C workbook structure.

The 2021 workbook shares the inspected 16-control wrapper structure with 2020, but running the loop still requires a matching 2021 Modelwright-generated Python model.

Parameters:

  • workbook_path (str | Path)

  • workbook_id (str)

Return type:

FableCalculatorSpec

fable_pyculator.build_cached_workbook_validation_scenario(workbook_path, output_refs, *, generated_model_path, scenario_id, description, source_workbook=None, generated_model=None, numeric_tolerance=1e-09)[source]

Build a Modelwright validation scenario from cached workbook output values.

Blank cached outputs are skipped because they are not comparable evidence. Numeric outputs get the supplied tolerance; text, boolean, and spreadsheet error values use exact matching.

Parameters:

  • workbook_path (str | Path)

  • output_refs (Iterable[str])

  • generated_model_path (str | Path)

  • scenario_id (str)

  • description (str)

  • source_workbook (str | Path | None)

  • generated_model (str | Path | None)

  • numeric_tolerance (float)

Return type:

dict[str, Any]

fable_pyculator.build_modelwright_freshforge_workflow(paths, *, workdir, workflow_id, name, description, module_name)[source]

Build a FreshForge workflow document for Modelwright generated-model stages.

Parameters:
Return type:

dict[str, Any]

fable_pyculator.build_notebook_spec(workbook_path, *, workbook_id)[source]

Build a notebook spec from a FABLE-C workbook structure.

This helper discovers wrapper metadata only. It does not generate Modelwright calculation code and it does not validate that a generated model artifact matches the workbook.

Parameters:

  • workbook_path (str | Path)

  • workbook_id (str)

Return type:

FableCalculatorSpec

fable_pyculator.build_output_ref_strategy_matrix(result, *, matrix_path=None)[source]

Build a FreshForge matrix document for prepared strategy-comparison workflows.

Matrix creation is FreshForge-free. Planning and running the written matrix require FreshForge to be installed separately.

Parameters:
Return type:

OutputRefStrategyMatrixResult

fable_pyculator.build_scenario_bundle_freshforge_matrix(bundle, *, template_path, matrix_path, bundle_path, workbook_path, generated_model_path, workbook_id, module_name)[source]

Build a FreshForge matrix document for one scenario bundle.

Parameters:

  • bundle (ScenarioBundle)

  • template_path (str | Path)

  • matrix_path (str | Path)

  • bundle_path (str | Path)

  • workbook_path (str | Path)

  • generated_model_path (str | Path)

  • workbook_id (str)

  • module_name (str)

Return type:

dict[str, Any]

fable_pyculator.build_scenario_bundle_freshforge_matrix_template()[source]

Build the FreshForge matrix workflow template for one scenario case.

Return type:

dict[str, Any]

fable_pyculator.build_scenario_bundle_freshforge_workflow(bundle, *, bundle_path, workbook_path, generated_model_path, workbook_id, module_name)[source]

Build a FreshForge workflow document for one scenario bundle.

Parameters:

  • bundle (ScenarioBundle)

  • bundle_path (str | Path)

  • workbook_path (str | Path)

  • generated_model_path (str | Path)

  • workbook_id (str)

  • module_name (str)

Return type:

dict[str, Any]

fable_pyculator.compare_output_ref_strategies(spec, *, workbook_version='2021', workbook_path, repo_root='.', output_dir=None, cases=None, selected_case_ids=None, include_workflows=False, include_existing_evidence=False)[source]

Compare output-ref strategies and write per-case preparation artifacts.

Parameters:

  • spec (FableCalculatorSpec)

  • workbook_version (str)

  • workbook_path (str | Path)

  • repo_root (str | Path)

  • output_dir (str | Path | None)

  • cases (Sequence[OutputRefStrategyCase] | None)

  • selected_case_ids (Sequence[str] | None)

  • include_workflows (bool)

  • include_existing_evidence (bool)

Return type:

OutputRefStrategyComparisonResult

fable_pyculator.curate_default_headline_series(workbook_path)[source]

Curate the first FOOD, LAND, GHG, and WATER headline output series.

The initial curation is intentionally narrow and provenance-friendly. It uses table descriptions from Indextables where available, then maps stable table columns on the canonical output sheets into notebook-ready time series.

Parameters:

workbook_path (str | Path)

Return type:

list[HeadlineSeries]

fable_pyculator.default_generated_model_path(*, workbook_version, repo_root='.')[source]

Return the default generated-model path for a scenario-bundle workflow.

Parameters:

  • workbook_version (str)

  • repo_root (str | Path)

Return type:

Path

fable_pyculator.default_output_ref_strategy_cases()[source]

Return deterministic default strategy cases for FABLE-C output tables.

Return type:

tuple[OutputRefStrategyCase, …]

fable_pyculator.derive_output_refs(spec, *, column_flavour_tags='OUTPUT-*', table_names=None)[source]

Derive sorted workbook cell refs from discovered output-table metadata.

column_flavour_tags accepts exact tags, the DATA/OUTPUT family aliases, and trailing wildcard patterns such as OUTPUT-*. Passing None selects every column in the selected output tables.

Parameters:

  • spec (FableCalculatorSpec)

  • column_flavour_tags (str | Sequence[str] | None)

  • table_names (Sequence[str] | None)

Return type:

tuple[str, …]

fable_pyculator.derive_output_refs_for_strategy(spec, *, strategy, column_flavour_tags='OUTPUT-*', table_names=None)[source]

Derive sorted output refs using a named FABLE build strategy.

Parameters:

  • spec (FableCalculatorSpec)

  • strategy (Literal['output-columns', 'headline-only', 'table', 'flavour-tags', 'all-columns'])

  • column_flavour_tags (str | Sequence[str] | None)

  • table_names (Sequence[str] | None)

Return type:

tuple[str, …]

fable_pyculator.discover_output_tables(workbook_path, *, sheet_names=('FOOD', 'PRODUCTION', 'TRADE', 'BIODIVERSITY', 'LAND', 'GHG', 'WATER'))[source]

Discover Excel tables on the canonical FABLE output data sheets.

Output tables preserve workbook cell references and optional output-column flavour tags. The flavour metadata powers output DataFrame filtering in fable_pyculator.output_table_frame().

Parameters:

  • workbook_path (str | Path)

  • sheet_names (Iterable[str])

Return type:

list[OutputTable]

fable_pyculator.discover_scenario_definition_tables(workbook_path, *, sheet_name='SCENARIOS definition')[source]

Discover native Excel tables on SCENARIOS definition.

Returned tables preserve headers, row labels, cell references, current workbook values, role/source markers, and scenario-definition location markers. They are intended for inspection and later curation; they are not yet automatically exposed as editable widgets.

Parameters:

  • workbook_path (str | Path)

  • sheet_name (str)

Return type:

list[ScenarioDefinitionTable]

fable_pyculator.discover_scenario_parameters(workbook_path, *, sheet_hints=('scenario', 'scenarios'), label_hints=('scenario', 'target', 'assumption', 'parameter', 'select', 'choice'), max_rows=250, max_columns=40)[source]

Return likely scenario controls from visible FABLE Calculator sheets.

This is deliberately heuristic. It finds non-formula cells near text labels on sheets whose names look scenario-related; country-specific wrappers should review and curate the result into a committed spec before treating it as a stable user interface.

Parameters:

  • workbook_path (str | Path)

  • sheet_hints (Iterable[str])

  • label_hints (Iterable[str])

  • max_rows (int)

  • max_columns (int)

Return type:

list[ScenarioParameter]

fable_pyculator.discover_selection_controls(workbook_path, *, sheet_name='SCENARIOS selection')[source]

Discover mutually exclusive x selection tables on SCENARIOS selection.

The public 2020 and 2021 FABLE-C workbooks expose 16 high-level scenario controls with this structure. The first table column is the marker column; the second column contains the option value passed to fable_pyculator.SelectionControl.input_mapping().

Parameters:

  • workbook_path (str | Path)

  • sheet_name (str)

Return type:

list[SelectionControl]

fable_pyculator.editable_scenario_definition_cells(spec, *, role_tag='DIRECT')[source]

Return editable non-formula scenario-definition cells for spec.

Parameters:
Return type:

tuple[ScenarioDefinitionEditableCell, …]

fable_pyculator.extract_validation_evidence(paths, *, workbook_version, require_artifacts=False)[source]

Extract sanitized evidence from existing local artifacts.

Parameters:
Return type:

ValidationEvidenceSummary

fable_pyculator.fable_benchmark_matrix_evidence_paths(*, workbook_version='2021', repo_root='.', matrix_run_path=None, matrix_summary_path=None, artifact_root=None, output_dir=None, evidence_id=None)[source]

Return default paths for FABLE benchmark matrix evidence packaging.

Parameters:

  • workbook_version (str)

  • repo_root (str | Path)

  • matrix_run_path (str | Path | None)

  • matrix_summary_path (str | Path | None)

  • artifact_root (str | Path | None)

  • output_dir (str | Path | None)

  • evidence_id (str | None)

Return type:

FableBenchmarkMatrixEvidencePaths

fable_pyculator.fable_benchmark_run_paths(*, workbook_version='2021', repo_root='.', artifact_dir=None, output_dir=None)[source]

Return default paths for a version-specific FABLE benchmark evidence run.

Parameters:

  • workbook_version (str)

  • repo_root (str | Path)

  • artifact_dir (str | Path | None)

  • output_dir (str | Path | None)

Return type:

FableBenchmarkRunPaths

fable_pyculator.fable_freshforge_build_paths(*, workbook_version, repo_root='.', workbook_path=None, artifact_dir=None, workflow_filename='freshforge-modelwright-run-workflow.json')[source]

Return version-specific FABLE FreshForge build artifact paths by convention.

Parameters:

  • workbook_version (str)

  • repo_root (str | Path)

  • workbook_path (str | Path | None)

  • artifact_dir (str | Path | None)

  • workflow_filename (str)

Return type:

FableFreshForgeBuildPaths

fable_pyculator.fable_scenario_bundle_artifact_paths(*, workbook_version, bundle_id, repo_root='.', output_dir=None)[source]

Return the default ignored artifact paths for a scenario-bundle run.

Parameters:

  • workbook_version (str)

  • bundle_id (str)

  • repo_root (str | Path)

  • output_dir (str | Path | None)

Return type:

ScenarioBundleArtifactPaths

fable_pyculator.fable_scenario_bundle_freshforge_matrix_paths(*, workbook_version, bundle_id, repo_root='.', output_dir=None, matrix_path=None, workflow_template_path=None, matrix_summary_path=None)[source]

Return default paths for FreshForge matrix scenario-bundle orchestration.

Parameters:

  • workbook_version (str)

  • bundle_id (str)

  • repo_root (str | Path)

  • output_dir (str | Path | None)

  • matrix_path (str | Path | None)

  • workflow_template_path (str | Path | None)

  • matrix_summary_path (str | Path | None)

Return type:

ScenarioBundleFreshForgeMatrixPaths

fable_pyculator.fable_scenario_bundle_freshforge_paths(*, workbook_version, bundle_id, repo_root='.', output_dir=None, workflow_path=None, run_summary_path=None)[source]

Return default paths for FreshForge-backed scenario-bundle orchestration.

Parameters:

  • workbook_version (str)

  • bundle_id (str)

  • repo_root (str | Path)

  • output_dir (str | Path | None)

  • workflow_path (str | Path | None)

  • run_summary_path (str | Path | None)

Return type:

ScenarioBundleFreshForgePaths

fable_pyculator.fable_validation_evidence_paths(*, workbook_version='2021', repo_root='.', artifact_dir=None, output_dir=None)[source]

Return default validation-evidence input and output paths.

Parameters:

  • workbook_version (str)

  • repo_root (str | Path)

  • artifact_dir (str | Path | None)

  • output_dir (str | Path | None)

Return type:

ValidationEvidencePaths

fable_pyculator.freshforge_2021_build_paths(*, repo_root='.', workbook_path='tmp/private-workbooks/2021_Open_FABLECalculator.xlsx', artifact_dir=PosixPath('tmp/generated-models/fable-2021'), workflow_filename='freshforge-modelwright-run-workflow.json')[source]

Return the default 2021 FABLE FreshForge build artifact layout.

Paths are resolved under repo_root so notebooks can run from VSCode’s notebook directory or from the repository root while still writing artifacts to the same ignored tmp/ location.

Parameters:

  • repo_root (str | Path)

  • workbook_path (str | Path)

  • artifact_dir (str | Path)

  • workflow_filename (str)

Return type:

FableFreshForgeBuildPaths

fable_pyculator.headline_frame(run, series_name)[source]

Render one curated FABLE headline series as a tidy pandas DataFrame.

Parameters:
Return type:

Any

fable_pyculator.headline_frames(run)[source]

Render all declared FABLE headline series as tidy pandas DataFrames.

Parameters:

run (ScenarioRun)

Return type:

dict[str, Any]

fable_pyculator.load_generated_model(model_path=PosixPath('tmp/generated-models/fable-2020/generated_fable_2020_model.py'), *, module_name='fable_pyculator_generated_fable_2020')[source]

Load an ignored Modelwright-generated Python model from a local path.

The loaded module must expose the generated model interface expected by modelwright.wrappers.ModelFacade, usually a calculate function.

Parameters:

  • model_path (str | Path)

  • module_name (str)

Return type:

ModuleType

fable_pyculator.load_scenario_bundle(path)[source]

Load a scenario bundle from JSON, YAML, or YML.

Parameters:

path (str | Path)

Return type:

ScenarioBundle

fable_pyculator.load_scenario_definition_patch(path)[source]

Load a scenario-definition patch from JSON, YAML, or YML.

Parameters:

path (str | Path)

Return type:

ScenarioDefinitionPatch

fable_pyculator.output_ref_strategy_comparison_paths(*, workbook_version='2021', repo_root='.', output_dir=None)[source]

Return default output-ref strategy comparison paths.

Parameters:

  • workbook_version (str)

  • repo_root (str | Path)

  • output_dir (str | Path | None)

Return type:

OutputRefStrategyComparisonPaths

fable_pyculator.output_table_frame(run, table_name, column_flavour_tags=None, *, include_context_columns=True)[source]

Render one declared FABLE output table from a scenario run.

column_flavour_tags accepts exact tags such as OUTPUT-8, family aliases such as DATA, and trailing-star patterns such as OUTPUT-*. Context columns tagged DIRECT or AUX are retained by default when filtering.

Parameters:

  • run (ScenarioRun)

  • table_name (str)

  • column_flavour_tags (str | Sequence[str] | None)

  • include_context_columns (bool)

Return type:

Any

fable_pyculator.output_tables(run, column_flavour_tags=None, *, include_context_columns=True)[source]

Render all declared FABLE output tables from a scenario run.

Parameters:

  • run (ScenarioRun)

  • column_flavour_tags (str | Sequence[str] | None)

  • include_context_columns (bool)

Return type:

dict[str, Any]

fable_pyculator.outputs_frame(run)[source]

Render declared FABLE output indicators as a pandas DataFrame.

Parameters:

run (ScenarioRun)

Return type:

Any

fable_pyculator.package_fable_benchmark_evidence(*, workbook_version='2021', repo_root='.', artifact_dir=None, output_dir=None, mode='evidence-only', require_artifacts=False, output_ref_strategy='output-columns', workbook_path=None, run_namespace=None, bundle_path=None, include_scenario_bundle_summary=False)[source]

Package benchmark evidence and optionally prepare or run the FreshForge rebuild workflow.

mode="evidence-only" only summarizes existing artifacts. freshforge-plan prepares the build workflow when the source workbook is available. freshforge-run additionally executes that workflow through FreshForge and records a compact run summary. Missing local artifacts are reported as skipped evidence unless require_artifacts is true.

Parameters:

  • workbook_version (str)

  • repo_root (str | Path)

  • artifact_dir (str | Path | None)

  • output_dir (str | Path | None)

  • mode (Literal['evidence-only', 'freshforge-plan', 'freshforge-run'])

  • require_artifacts (bool)

  • output_ref_strategy (Literal['output-columns', 'headline-only', 'table', 'flavour-tags', 'all-columns'])

  • workbook_path (str | Path | None)

  • run_namespace (str | None)

  • bundle_path (str | Path | None)

  • include_scenario_bundle_summary (bool)

Return type:

FableBenchmarkRunSummary

fable_pyculator.package_fable_benchmark_matrix_evidence(*, workbook_version='2021', repo_root='.', matrix_run_path=None, matrix_summary_path=None, artifact_root=None, output_dir=None, evidence_id=None, require_evidence=False)[source]

Package compact FABLE benchmark matrix evidence through Modelwright.

This wrapper supplies FABLE-C path defaults and public-facing summary text. Generic matrix aggregation remains in Modelwright.

Parameters:

  • workbook_version (str)

  • repo_root (str | Path)

  • matrix_run_path (str | Path | None)

  • matrix_summary_path (str | Path | None)

  • artifact_root (str | Path | None)

  • output_dir (str | Path | None)

  • evidence_id (str | None)

  • require_evidence (bool)

Return type:

FableBenchmarkMatrixEvidenceSummary

fable_pyculator.plan_output_ref_strategy_matrix(matrix_path)[source]

Plan a FreshForge strategy matrix and return a serializable payload.

Parameters:

matrix_path (str | Path)

Return type:

dict[str, Any]

fable_pyculator.plan_scenario_bundle_freshforge_matrix(plan)[source]

Plan a prepared FreshForge scenario-bundle matrix.

Parameters:

plan (ScenarioBundleFreshForgeMatrixPlan)

Return type:

dict[str, Any]

fable_pyculator.plot_headline(run, series_name)[source]

Plot one curated FABLE headline series as a notebook-friendly line chart.

Parameters:
Return type:

Any

fable_pyculator.plot_outputs(run, *, group=None)[source]

Plot numeric output indicators as a simple horizontal bar chart.

Parameters:
Return type:

Any

fable_pyculator.prepare_2021_freshforge_rebuild(*, repo_root='.', workbook_path='tmp/private-workbooks/2021_Open_FABLECalculator.xlsx', artifact_dir=PosixPath('tmp/generated-models/fable-2021'), workflow_filename='freshforge-modelwright-run-workflow.json', output_ref_strategy='output-columns', column_flavour_tags='OUTPUT-*', table_names=None, module_name='generated_fable_2021_model', workflow_id='fable_2021_modelwright_run', workflow_name='FABLE 2021 Modelwright FreshForge run', workflow_description='FreshForge graph for rebuilding the 2021 FABLE generated model.', scenario_id='fable-c-2021-freshforge-rebuild', scenario_description='Cached-workbook validation slice derived from FABLE Pyculator output refs.', numeric_tolerance=1e-09, spec=None)[source]

Prepare the default 2021 FABLE FreshForge rebuild artifacts.

Parameters:

  • repo_root (str | Path)

  • workbook_path (str | Path)

  • artifact_dir (str | Path)

  • workflow_filename (str)

  • output_ref_strategy (Literal['output-columns', 'headline-only', 'table', 'flavour-tags', 'all-columns'])

  • column_flavour_tags (str | Sequence[str] | None)

  • table_names (Sequence[str] | None)

  • module_name (str)

  • workflow_id (str)

  • workflow_name (str)

  • workflow_description (str)

  • scenario_id (str)

  • scenario_description (str)

  • numeric_tolerance (float)

  • spec (FableCalculatorSpec | None)

Return type:

FableFreshForgeRebuildPlan

fable_pyculator.prepare_freshforge_rebuild(*, workbook_version, repo_root='.', workbook_path=None, artifact_dir=None, workflow_filename='freshforge-modelwright-run-workflow.json', output_ref_strategy='output-columns', column_flavour_tags='OUTPUT-*', table_names=None, module_name=None, workflow_id=None, workflow_name=None, workflow_description=None, scenario_id=None, scenario_description='Cached-workbook validation slice derived from FABLE Pyculator output refs.', numeric_tolerance=1e-09, spec=None)[source]

Prepare version-specific FABLE FreshForge rebuild artifacts.

This helper performs the deterministic setup work shared by notebooks and scripts:

  • build or receive the notebook spec;

  • derive output refs using a named strategy;

  • write output_refs.json;

  • write a cached-workbook validation scenario;

  • write the downstream Modelwright FreshForge workflow JSON.

It does not run FreshForge or Modelwright. The source workbook must already exist at the configured ignored local path.

Parameters:

  • workbook_version (str)

  • repo_root (str | Path)

  • workbook_path (str | Path | None)

  • artifact_dir (str | Path | None)

  • workflow_filename (str)

  • output_ref_strategy (Literal['output-columns', 'headline-only', 'table', 'flavour-tags', 'all-columns'])

  • column_flavour_tags (str | Sequence[str] | None)

  • table_names (Sequence[str] | None)

  • module_name (str | None)

  • workflow_id (str | None)

  • workflow_name (str | None)

  • workflow_description (str | None)

  • scenario_id (str | None)

  • scenario_description (str)

  • numeric_tolerance (float)

  • spec (FableCalculatorSpec | None)

Return type:

FableFreshForgeRebuildPlan

fable_pyculator.prepare_scenario_bundle_freshforge_matrix(bundle, *, bundle_path, workbook_path, generated_model_path, paths, repo_root='.', workbook_id=None, module_name=None, spec=None)[source]

Write a FreshForge matrix for one scenario-bundle case per scenario.

Parameters:

  • bundle (ScenarioBundle)

  • bundle_path (str | Path)

  • workbook_path (str | Path)

  • generated_model_path (str | Path)

  • paths (ScenarioBundleFreshForgeMatrixPaths)

  • repo_root (str | Path)

  • workbook_id (str | None)

  • module_name (str | None)

  • spec (Any | None)

Return type:

ScenarioBundleFreshForgeMatrixPlan

fable_pyculator.prepare_scenario_bundle_freshforge_workflow(bundle, *, bundle_path, workbook_path, generated_model_path, paths, repo_root='.', workbook_id=None, module_name=None, run_namespace=None, spec=None)[source]

Write a FreshForge workflow for a FABLE scenario bundle without running it.

Parameters:

  • bundle (ScenarioBundle)

  • bundle_path (str | Path)

  • workbook_path (str | Path)

  • generated_model_path (str | Path)

  • paths (ScenarioBundleFreshForgePaths)

  • repo_root (str | Path)

  • workbook_id (str | None)

  • module_name (str | None)

  • run_namespace (str | None)

  • spec (Any | None)

Return type:

ScenarioBundleFreshForgePlan

fable_pyculator.run_2020_notebook_loop(selections=None, *, workbook_path=PosixPath('tmp/private-workbooks/2020_Open_FABLECalculator.xlsx'), generated_model_path=PosixPath('tmp/generated-models/fable-2020/generated_fable_2020_model.py'), scenario_name='scenario', output_table_names=None, output_table_column_flavour_tags=None, include_context_columns=True, headline_series_names=None, include_figures=True, scenario_definition_patch=None)[source]

Run the default 2020 FABLE-C notebook loop from ignored local artifacts.

Parameters:

  • selections (Mapping[str, object] | None)

  • workbook_path (str | Path)

  • generated_model_path (str | Path)

  • scenario_name (str)

  • output_table_names (Sequence[str] | None)

  • output_table_column_flavour_tags (str | Sequence[str] | None)

  • include_context_columns (bool)

  • headline_series_names (Sequence[str] | None)

  • include_figures (bool)

  • scenario_definition_patch (ScenarioDefinitionPatch | Mapping[str, Any] | str | Path | None)

Return type:

NotebookLoopResult

fable_pyculator.run_2021_notebook_loop(selections=None, *, workbook_path=PosixPath('tmp/private-workbooks/2021_Open_FABLECalculator.xlsx'), generated_model_path=PosixPath('tmp/generated-models/fable-2021/generated_fable_2021_model.py'), scenario_name='scenario', output_table_names=None, output_table_column_flavour_tags=None, include_context_columns=True, headline_series_names=None, include_figures=True, scenario_definition_patch=None)[source]

Run the default 2021 FABLE-C notebook loop from ignored local artifacts.

This helper intentionally points to a separate 2021 generated-model path. It never falls back to the tracked compressed 2020 generated model in the sibling Modelwright repository.

Parameters:

  • selections (Mapping[str, object] | None)

  • workbook_path (str | Path)

  • generated_model_path (str | Path)

  • scenario_name (str)

  • output_table_names (Sequence[str] | None)

  • output_table_column_flavour_tags (str | Sequence[str] | None)

  • include_context_columns (bool)

  • headline_series_names (Sequence[str] | None)

  • include_figures (bool)

  • scenario_definition_patch (ScenarioDefinitionPatch | Mapping[str, Any] | str | Path | None)

Return type:

NotebookLoopResult

fable_pyculator.run_notebook_loop(generated_model, spec, selections=None, *, scenario_name='scenario', output_table_names=None, output_table_column_flavour_tags=None, include_context_columns=True, headline_series_names=None, include_figures=True, scenario_definition_patch=None)[source]

Run a generated model and render selected FABLE notebook artifacts.

By default, output_table_names=None and headline_series_names=None render every declared output table and headline frame from the spec after a single generated-model execution.

Parameters:

  • generated_model (ModuleType | object)

  • spec (FableCalculatorSpec)

  • selections (Mapping[str, object] | None)

  • scenario_name (str)

  • output_table_names (Sequence[str] | None)

  • output_table_column_flavour_tags (str | Sequence[str] | None)

  • include_context_columns (bool)

  • headline_series_names (Sequence[str] | None)

  • include_figures (bool)

  • scenario_definition_patch (ScenarioDefinitionPatch | Mapping[str, Any] | str | Path | None)

Return type:

NotebookLoopResult

fable_pyculator.run_output_ref_strategy_matrix(matrix_path, *, workdir=None, fail_fast=False)[source]

Run a FreshForge strategy matrix and return a serializable payload.

Parameters:

  • matrix_path (str | Path)

  • workdir (str | Path | None)

  • fail_fast (bool)

Return type:

dict[str, Any]

fable_pyculator.run_scenario(generated_model, spec, values=None, *, name='scenario', scenario_definition_patch=None)[source]

Run a generated Modelwright model using FABLE parameter names.

Parameters:
Return type:

ScenarioRun

fable_pyculator.run_scenario_bundle(generated_model, spec, bundle, *, output_table_names=None, output_table_column_flavour_tags=None, include_context_columns=None, headline_series_names=None, include_figures=None)[source]

Run every scenario in bundle using the existing notebook-loop renderer.

Parameters:

  • generated_model (ModuleType | object)

  • spec (FableCalculatorSpec)

  • bundle (ScenarioBundle)

  • output_table_names (Sequence[str] | None)

  • output_table_column_flavour_tags (str | Sequence[str] | None)

  • include_context_columns (bool | None)

  • headline_series_names (Sequence[str] | None)

  • include_figures (bool | None)

Return type:

ScenarioBundleRunResult

fable_pyculator.run_scenario_bundle_freshforge_matrix(plan, *, registry=None, fail_fast=False)[source]

Run a prepared FreshForge scenario-bundle matrix.

Parameters:
Return type:

Any

fable_pyculator.run_scenario_bundle_freshforge_workflow(plan, *, run_namespace=None, registry=None)[source]

Run a prepared scenario-bundle FreshForge workflow.

Parameters:
Return type:

Any

fable_pyculator.scenario_definition_input_mapping(spec, patch)[source]

Return generated-model input overrides for a validated scenario-definition patch.

Parameters:
Return type:

dict[str, str | int | float | bool | None]

fable_pyculator.scenario_definition_table_frame(spec, table_name)[source]

Render one discovered FABLE scenario definition table as a pandas DataFrame.

Parameters:
Return type:

Any

fable_pyculator.scenario_definition_tables(spec)[source]

Render all discovered FABLE scenario definition tables as pandas DataFrames.

Parameters:

spec (FableCalculatorSpec)

Return type:

dict[str, Any]

fable_pyculator.scenario_definition_tables_for_location(spec, location, *, include_family=True)[source]

Render scenario definition tables associated with a workbook scenario location.

Passing S.3 with include_family=True returns tables marked S.3.A, S.3.B, and so on. Passing an exact marker such as S.3.C returns only tables with that marker.

Parameters:
Return type:

dict[str, Any]

fable_pyculator.scenario_frame(run)[source]

Render scenario inputs as a pandas DataFrame.

Parameters:

run (ScenarioRun)

Return type:

Any

fable_pyculator.validate_scenario_bundle(bundle, spec)[source]

Validate bundle ids and selection-control values against a FABLE spec.

Parameters:
Return type:

ScenarioBundle

fable_pyculator.validate_scenario_definition_patch(spec, patch)[source]

Validate patch against spec and return generated-model inputs.

Parameters:
Return type:

ScenarioDefinitionPatchResult

fable_pyculator.write_fable_benchmark_matrix_evidence(summary, paths=None)[source]

Write compact FABLE-facing JSON and Markdown matrix evidence summaries.

Parameters:
Return type:

dict[str, Any]

fable_pyculator.write_fable_benchmark_summary(summary, paths=None)[source]

Write compact JSON and Markdown benchmark summaries.

Parameters:
Return type:

dict[str, Any]

fable_pyculator.write_freshforge_workflow(path, workflow)[source]

Write a FreshForge workflow document as stable JSON.

Parameters:

  • path (str | Path)

  • workflow (dict[str, Any])

Return type:

dict[str, Any]

fable_pyculator.write_output_ref_strategy_comparison(result)[source]

Write compact JSON and Markdown strategy-comparison summaries.

Parameters:

result (OutputRefStrategyComparisonResult)

Return type:

dict[str, Any]

fable_pyculator.write_output_ref_strategy_matrix(result)[source]

Write a FreshForge strategy matrix and workflow template as YAML.

Parameters:

result (OutputRefStrategyMatrixResult)

Return type:

dict[str, Any]

fable_pyculator.write_output_refs(path, output_refs)[source]

Write sorted unique output refs as stable JSON and return the written refs.

Parameters:

  • path (str | Path)

  • output_refs (Iterable[str])

Return type:

tuple[str, …]

fable_pyculator.write_scenario_artifacts(result, scenario, *, scenario_dir, output_dir)[source]

Write rendered artifacts for one scenario and return a manifest entry.

Parameters:
Return type:

dict[str, Any]

fable_pyculator.write_scenario_bundle_artifacts(run_result, paths)[source]

Write normalized bundle metadata and rendered scenario artifacts.

Parameters:
Return type:

dict[str, Any]

fable_pyculator.write_scenario_bundle_freshforge_matrix_summary(run_result, paths, *, path=None)[source]

Write a compact FreshForge matrix summary for a scenario-bundle matrix run.

Parameters:
Return type:

dict[str, Any]

fable_pyculator.write_scenario_bundle_freshforge_summary(run_result, paths, *, run_namespace=None, path=None)[source]

Write a compact FreshForge run summary for a scenario-bundle workflow.

Parameters:
Return type:

dict[str, Any]

fable_pyculator.write_scenario_definition_patch(path, patch)[source]

Write a normalized scenario-definition patch as JSON.

Parameters:
Return type:

dict[str, Any]

fable_pyculator.write_validation_evidence(summary, paths)[source]

Write compact JSON and Markdown validation-evidence summaries.

Parameters:
Return type:

dict[str, Any]

fable_pyculator.write_validation_scenario(path, scenario)[source]

Write a Modelwright validation scenario as stable JSON.

Parameters:

  • path (str | Path)

  • scenario (dict[str, Any])

Return type:

dict[str, Any]

Typed Specifications

Typed notebook declarations for FABLE Calculator wrapper specs.

This module is deliberately declarative. The records here describe the workbook-backed surfaces that FABLE Pyculator can expose in notebooks: high-level scenario selections, scenario-definition tables, canonical output tables, and curated headline series. They do not execute Excel formulas and they do not claim that every workbook cell has been converted into a stable public API.

class fable_pyculator.spec.FableCalculatorSpec(parameters=<factory>, selection_controls=<factory>, scenario_definition_tables=<factory>, outputs=<factory>, output_tables=<factory>, headline_series=<factory>, workbook_id=None, provenance=None)[source]

Notebook-facing declaration of FABLE scenario inputs and outputs.

The spec is the central object passed to FABLE Pyculator control, execution, and rendering helpers. It keeps input declarations, discovered definition-table metadata, output declarations, and workbook provenance together while preserving their distinct semantics.

Parameters:
input_mapping(values)[source]

Convert friendly scenario values to generated-model cell inputs.

Values may reference curated scalar parameters or discovered selection controls by name. Unknown names are rejected so notebook typos do not silently produce partial scenarios.

Parameters:

values (dict[str, object])

Return type:

dict[str, object]

class fable_pyculator.spec.HeadlinePoint(year, cell_refs)[source]

One year/value point in a curated headline output series.

Parameters:

  • year (int | str)

  • cell_refs (tuple[str, ...] | list[str])

class fable_pyculator.spec.HeadlineSeries(name, label, group, sheet, table_name, points, unit=None, description=None, aggregation='value')[source]

One curated notebook headline series built from FABLE output tables.

A series is intentionally narrower than a full output table. It describes the source table, source cell references, units, and aggregation rule needed to render a compact analyst-facing time series.

Parameters:

  • name (str)

  • label (str)

  • group (str)

  • sheet (str)

  • table_name (str)

  • points (tuple[HeadlinePoint, ...] | list[HeadlinePoint])

  • unit (str | None)

  • description (str | None)

  • aggregation (Literal['value', 'sum'])

class fable_pyculator.spec.OutputIndicator(name, label, cell_ref, unit=None, group=None, description=None)[source]

One scalar output cell rendered from a generated Modelwright model.

Parameters:

  • name (str)

  • label (str)

  • cell_ref (str)

  • unit (str | None)

  • group (str | None)

  • description (str | None)

class fable_pyculator.spec.OutputTable(name, sheet, range_ref, cell_refs, row_labels, column_labels, values=(), column_flavour_tags=(), raw_column_flavour_tags=(), column_flavour_tag_refs=(), label=None, description=None)[source]

One rectangular output table on a canonical FABLE output sheet.

column_flavour_tags stores output-sheet flavour metadata such as DIRECT, DATA-5, or OUTPUT-8. That vocabulary belongs to output tables only; scenario-definition input tables use column_role_tags instead.

Parameters:

  • name (str)

  • sheet (str)

  • range_ref (str)

  • cell_refs (tuple[tuple[str, ...], ...])

  • row_labels (tuple[str, ...])

  • column_labels (tuple[str, ...])

  • values (tuple[tuple[object, ...], ...] | list[list[object]] | tuple[()])

  • column_flavour_tags (tuple[str | None, ...] | list[str | None])

  • raw_column_flavour_tags (tuple[str | None, ...] | list[str | None])

  • column_flavour_tag_refs (tuple[str | None, ...] | list[str | None])

  • label (str | None)

  • description (str | None)

class fable_pyculator.spec.ScenarioDefinitionTable(name, sheet, range_ref, cell_refs, row_labels, column_labels, values=(), column_role_tags=(), raw_column_role_tags=(), column_role_tag_refs=(), scenario_locations=(), scenario_location_refs=(), label=None, description=None)[source]

One native table on the FABLE SCENARIOS definition sheet.

These records make definition tables inspectable in notebooks. column_role_tags preserves workbook role/source markers such as DIRECT, SCEN, CALC, and DATA-1. The scenario_locations field stores workbook markers such as S.3.C that help users browse related definition tables. The table is not yet an editable widget contract.

Parameters:

  • name (str)

  • sheet (str)

  • range_ref (str)

  • cell_refs (tuple[tuple[str, ...], ...])

  • row_labels (tuple[str, ...])

  • column_labels (tuple[str, ...])

  • values (tuple[tuple[object, ...], ...] | list[list[object]] | list[tuple[object, ...]])

  • column_role_tags (tuple[str | None, ...] | list[str | None])

  • raw_column_role_tags (tuple[str | None, ...] | list[str | None])

  • column_role_tag_refs (tuple[str | None, ...] | list[str | None])

  • scenario_locations (tuple[str, ...] | list[str])

  • scenario_location_refs (tuple[str, ...] | list[str])

  • label (str | None)

  • description (str | None)

class fable_pyculator.spec.ScenarioParameter(name, label, cell_ref, kind='number', unit=None, description=None, default=None, choices=(), source=None)[source]

One scalar FABLE Calculator input exposed as a notebook scenario value.

A parameter maps a friendly Python name to a generated-model cell reference. This record is for curated scalar controls; discovered FABLE-C selection tables should normally use SelectionControl instead.

Parameters:

  • name (str)

  • label (str)

  • cell_ref (str)

  • kind (Literal['number', 'text', 'choice', 'boolean'])

  • unit (str | None)

  • description (str | None)

  • default (object)

  • choices (tuple[object, ...])

  • source (str | None)

class fable_pyculator.spec.SelectionControl(name, label, table_name, sheet, range_ref, code_header, options, location=None, description=None)[source]

One mutually exclusive FABLE scenario selection table.

FABLE-C selection tables use a first-column x marker. Selecting one option means placing x in that option’s marker cell and clearing all other marker cells in the same table.

Parameters:

  • name (str)

  • label (str)

  • table_name (str)

  • sheet (str)

  • range_ref (str)

  • code_header (str)

  • options (tuple[SelectionOption, ...] | list[SelectionOption])

  • location (str | None)

  • description (str | None)

input_mapping(selected_value)[source]

Return generated-model overrides that place one x in this table.

The returned mapping is keyed by normalized full cell references. It clears unselected marker cells with None because Modelwright scenarios accept explicit cell inputs, not workbook UI gestures.

Parameters:

selected_value (object)

Return type:

dict[str, object]

class fable_pyculator.spec.SelectionOption(value, label, selection_cell_ref, description=None, selected=False)[source]

One selectable row in a FABLE scenario selection table.

Parameters:

  • value (str)

  • label (str | None)

  • selection_cell_ref (str)

  • description (str | None)

  • selected (bool)

Workbook Discovery

Workbook discovery helpers for public FABLE-C workbook conventions.

Discovery functions read workbook structure and return typed notebook declarations. They are workbook-version informed, not a generic Excel conversion layer; generic extraction and formula translation remain Modelwright responsibilities.

fable_pyculator.discovery.curate_default_headline_series(workbook_path)[source]

Curate the first FOOD, LAND, GHG, and WATER headline output series.

The initial curation is intentionally narrow and provenance-friendly. It uses table descriptions from Indextables where available, then maps stable table columns on the canonical output sheets into notebook-ready time series.

Parameters:

workbook_path (str | Path)

Return type:

list[HeadlineSeries]

fable_pyculator.discovery.discover_output_tables(workbook_path, *, sheet_names=('FOOD', 'PRODUCTION', 'TRADE', 'BIODIVERSITY', 'LAND', 'GHG', 'WATER'))[source]

Discover Excel tables on the canonical FABLE output data sheets.

Output tables preserve workbook cell references and optional output-column flavour tags. The flavour metadata powers output DataFrame filtering in fable_pyculator.output_table_frame().

Parameters:

  • workbook_path (str | Path)

  • sheet_names (Iterable[str])

Return type:

list[OutputTable]

fable_pyculator.discovery.discover_scenario_definition_tables(workbook_path, *, sheet_name='SCENARIOS definition')[source]

Discover native Excel tables on SCENARIOS definition.

Returned tables preserve headers, row labels, cell references, current workbook values, role/source markers, and scenario-definition location markers. They are intended for inspection and later curation; they are not yet automatically exposed as editable widgets.

Parameters:

  • workbook_path (str | Path)

  • sheet_name (str)

Return type:

list[ScenarioDefinitionTable]

fable_pyculator.discovery.discover_scenario_parameters(workbook_path, *, sheet_hints=('scenario', 'scenarios'), label_hints=('scenario', 'target', 'assumption', 'parameter', 'select', 'choice'), max_rows=250, max_columns=40)[source]

Return likely scenario controls from visible FABLE Calculator sheets.

This is deliberately heuristic. It finds non-formula cells near text labels on sheets whose names look scenario-related; country-specific wrappers should review and curate the result into a committed spec before treating it as a stable user interface.

Parameters:

  • workbook_path (str | Path)

  • sheet_hints (Iterable[str])

  • label_hints (Iterable[str])

  • max_rows (int)

  • max_columns (int)

Return type:

list[ScenarioParameter]

fable_pyculator.discovery.discover_selection_controls(workbook_path, *, sheet_name='SCENARIOS selection')[source]

Discover mutually exclusive x selection tables on SCENARIOS selection.

The public 2020 and 2021 FABLE-C workbooks expose 16 high-level scenario controls with this structure. The first table column is the marker column; the second column contains the option value passed to fable_pyculator.SelectionControl.input_mapping().

Parameters:

  • workbook_path (str | Path)

  • sheet_name (str)

Return type:

list[SelectionControl]

Workbook Loading

Workbook loading helpers for FABLE Calculator workbooks.

fable_pyculator.workbook.load_fable_workbook(path, **kwargs)[source]

Load a FABLE workbook while suppressing known irrelevant OpenPyXL warnings.

The public FABLE-C workbooks include workbook features that FABLE Pyculator does not use for scenario control discovery, output-table discovery, notebook rendering, or generated-model rebuild preparation. OpenPyXL warns when it drops unsupported WMF images or data-validation extension metadata; those warnings are benign for this package’s workbook surfaces.

Parameters:

  • path (str | Path)

  • kwargs (Any)

Return type:

Workbook

fable_pyculator.workbook.suppress_benign_openpyxl_warnings()[source]

Suppress only the known benign OpenPyXL warnings seen in FABLE workbooks.

Return type:

Iterator[None]

Notebook Controls

Jupyter widget controls for FABLE scenario inputs.

The widgets in this module are intentionally thin. They collect values for curated scalar parameters and FABLE-C selection controls, then hand those values back to FableCalculatorSpec for conversion into generated-model cell inputs.

class fable_pyculator.controls.ScenarioControlSurface(spec)[source]

Small ipywidgets-backed control surface for a FABLE scenario spec.

The surface displays scalar parameters and mutually exclusive selection controls. It does not yet render editable widgets for the detailed SCENARIOS definition tables.

Parameters:

spec (FableCalculatorSpec)

set_values(values)[source]

Set current widget values by spec input name.

Parameters:

values (dict[str, object])

Return type:

None

values()[source]

Return current widget values keyed by spec input name.

Return type:

dict[str, object]

Notebook Loop

High-level notebook loop helpers for FABLE-C generated models.

This module packages version-specific FABLE-C notebook workflows: build a workbook-derived spec, import a locally generated Modelwright Python model, apply scenario selections, and render the discovered output tables/headline series. The helpers assume local artifacts are restored under ignored tmp/ paths.

The workbook and generated model must come from the same FABLE Calculator version. A 2021 workbook should not be paired with the 2020 generated model, because the wrapper can render outputs only as accurately as the generated calculation artifact it wraps.

class fable_pyculator.notebook.NotebookLoopResult(run, output_tables, headline_frames, headline_figures, skipped_output_tables=<factory>)[source]

Rendered notebook artifacts from one FABLE Pyculator scenario run.

Parameters:

  • run (ScenarioRun)

  • output_tables (dict[str, Any])

  • headline_frames (dict[str, Any])

  • headline_figures (dict[str, Any])

  • skipped_output_tables (dict[str, str])

fable_pyculator.notebook.build_2020_notebook_spec(workbook_path=PosixPath('tmp/private-workbooks/2020_Open_FABLECalculator.xlsx'), *, workbook_id='fable-c-2020')[source]

Build the notebook spec from the public 2020 FABLE-C workbook structure.

Parameters:

  • workbook_path (str | Path)

  • workbook_id (str)

Return type:

FableCalculatorSpec

fable_pyculator.notebook.build_2021_notebook_spec(workbook_path=PosixPath('tmp/private-workbooks/2021_Open_FABLECalculator.xlsx'), *, workbook_id='fable-c-2021')[source]

Build the notebook spec from the public 2021 FABLE-C workbook structure.

The 2021 workbook shares the inspected 16-control wrapper structure with 2020, but running the loop still requires a matching 2021 Modelwright-generated Python model.

Parameters:

  • workbook_path (str | Path)

  • workbook_id (str)

Return type:

FableCalculatorSpec

fable_pyculator.notebook.build_notebook_spec(workbook_path, *, workbook_id)[source]

Build a notebook spec from a FABLE-C workbook structure.

This helper discovers wrapper metadata only. It does not generate Modelwright calculation code and it does not validate that a generated model artifact matches the workbook.

Parameters:

  • workbook_path (str | Path)

  • workbook_id (str)

Return type:

FableCalculatorSpec

fable_pyculator.notebook.load_generated_model(model_path=PosixPath('tmp/generated-models/fable-2020/generated_fable_2020_model.py'), *, module_name='fable_pyculator_generated_fable_2020')[source]

Load an ignored Modelwright-generated Python model from a local path.

The loaded module must expose the generated model interface expected by modelwright.wrappers.ModelFacade, usually a calculate function.

Parameters:

  • model_path (str | Path)

  • module_name (str)

Return type:

ModuleType

fable_pyculator.notebook.run_2020_notebook_loop(selections=None, *, workbook_path=PosixPath('tmp/private-workbooks/2020_Open_FABLECalculator.xlsx'), generated_model_path=PosixPath('tmp/generated-models/fable-2020/generated_fable_2020_model.py'), scenario_name='scenario', output_table_names=None, output_table_column_flavour_tags=None, include_context_columns=True, headline_series_names=None, include_figures=True, scenario_definition_patch=None)[source]

Run the default 2020 FABLE-C notebook loop from ignored local artifacts.

Parameters:

  • selections (Mapping[str, object] | None)

  • workbook_path (str | Path)

  • generated_model_path (str | Path)

  • scenario_name (str)

  • output_table_names (Sequence[str] | None)

  • output_table_column_flavour_tags (str | Sequence[str] | None)

  • include_context_columns (bool)

  • headline_series_names (Sequence[str] | None)

  • include_figures (bool)

  • scenario_definition_patch (ScenarioDefinitionPatch | Mapping[str, Any] | str | Path | None)

Return type:

NotebookLoopResult

fable_pyculator.notebook.run_2021_notebook_loop(selections=None, *, workbook_path=PosixPath('tmp/private-workbooks/2021_Open_FABLECalculator.xlsx'), generated_model_path=PosixPath('tmp/generated-models/fable-2021/generated_fable_2021_model.py'), scenario_name='scenario', output_table_names=None, output_table_column_flavour_tags=None, include_context_columns=True, headline_series_names=None, include_figures=True, scenario_definition_patch=None)[source]

Run the default 2021 FABLE-C notebook loop from ignored local artifacts.

This helper intentionally points to a separate 2021 generated-model path. It never falls back to the tracked compressed 2020 generated model in the sibling Modelwright repository.

Parameters:

  • selections (Mapping[str, object] | None)

  • workbook_path (str | Path)

  • generated_model_path (str | Path)

  • scenario_name (str)

  • output_table_names (Sequence[str] | None)

  • output_table_column_flavour_tags (str | Sequence[str] | None)

  • include_context_columns (bool)

  • headline_series_names (Sequence[str] | None)

  • include_figures (bool)

  • scenario_definition_patch (ScenarioDefinitionPatch | Mapping[str, Any] | str | Path | None)

Return type:

NotebookLoopResult

fable_pyculator.notebook.run_notebook_loop(generated_model, spec, selections=None, *, scenario_name='scenario', output_table_names=None, output_table_column_flavour_tags=None, include_context_columns=True, headline_series_names=None, include_figures=True, scenario_definition_patch=None)[source]

Run a generated model and render selected FABLE notebook artifacts.

By default, output_table_names=None and headline_series_names=None render every declared output table and headline frame from the spec after a single generated-model execution.

Parameters:

  • generated_model (ModuleType | object)

  • spec (FableCalculatorSpec)

  • selections (Mapping[str, object] | None)

  • scenario_name (str)

  • output_table_names (Sequence[str] | None)

  • output_table_column_flavour_tags (str | Sequence[str] | None)

  • include_context_columns (bool)

  • headline_series_names (Sequence[str] | None)

  • include_figures (bool)

  • scenario_definition_patch (ScenarioDefinitionPatch | Mapping[str, Any] | str | Path | None)

Return type:

NotebookLoopResult

Rendering And Execution

Notebook scenario execution, table rendering, and plotting helpers.

Rendering helpers convert FABLE Pyculator declarations into pandas DataFrames and matplotlib figures. They operate on generated-model values already returned by Modelwright and keep workbook provenance in DataFrame.attrs wherever practical.

class fable_pyculator.surface.ScenarioRun(spec, scenario_name, inputs, values)[source]

Result from running one FABLE Pyculator scenario.

Parameters:

  • spec (FableCalculatorSpec)

  • scenario_name (str)

  • inputs (dict[str, object])

  • values (dict[str, object])

fable_pyculator.surface.headline_frame(run, series_name)[source]

Render one curated FABLE headline series as a tidy pandas DataFrame.

Parameters:
Return type:

Any

fable_pyculator.surface.headline_frames(run)[source]

Render all declared FABLE headline series as tidy pandas DataFrames.

Parameters:

run (ScenarioRun)

Return type:

dict[str, Any]

fable_pyculator.surface.output_table_frame(run, table_name, column_flavour_tags=None, *, include_context_columns=True)[source]

Render one declared FABLE output table from a scenario run.

column_flavour_tags accepts exact tags such as OUTPUT-8, family aliases such as DATA, and trailing-star patterns such as OUTPUT-*. Context columns tagged DIRECT or AUX are retained by default when filtering.

Parameters:

  • run (ScenarioRun)

  • table_name (str)

  • column_flavour_tags (str | Sequence[str] | None)

  • include_context_columns (bool)

Return type:

Any

fable_pyculator.surface.output_tables(run, column_flavour_tags=None, *, include_context_columns=True)[source]

Render all declared FABLE output tables from a scenario run.

Parameters:

  • run (ScenarioRun)

  • column_flavour_tags (str | Sequence[str] | None)

  • include_context_columns (bool)

Return type:

dict[str, Any]

fable_pyculator.surface.outputs_frame(run)[source]

Render declared FABLE output indicators as a pandas DataFrame.

Parameters:

run (ScenarioRun)

Return type:

Any

fable_pyculator.surface.plot_headline(run, series_name)[source]

Plot one curated FABLE headline series as a notebook-friendly line chart.

Parameters:
Return type:

Any

fable_pyculator.surface.plot_outputs(run, *, group=None)[source]

Plot numeric output indicators as a simple horizontal bar chart.

Parameters:
Return type:

Any

fable_pyculator.surface.run_scenario(generated_model, spec, values=None, *, name='scenario', scenario_definition_patch=None)[source]

Run a generated Modelwright model using FABLE parameter names.

Parameters:
Return type:

ScenarioRun

fable_pyculator.surface.scenario_definition_table_frame(spec, table_name)[source]

Render one discovered FABLE scenario definition table as a pandas DataFrame.

Parameters:
Return type:

Any

fable_pyculator.surface.scenario_definition_tables(spec)[source]

Render all discovered FABLE scenario definition tables as pandas DataFrames.

Parameters:

spec (FableCalculatorSpec)

Return type:

dict[str, Any]

fable_pyculator.surface.scenario_definition_tables_for_location(spec, location, *, include_family=True)[source]

Render scenario definition tables associated with a workbook scenario location.

Passing S.3 with include_family=True returns tables marked S.3.A, S.3.B, and so on. Passing an exact marker such as S.3.C returns only tables with that marker.

Parameters:
Return type:

dict[str, Any]

fable_pyculator.surface.scenario_frame(run)[source]

Render scenario inputs as a pandas DataFrame.

Parameters:

run (ScenarioRun)

Return type:

Any

Scenario-Definition Patches

Editable FABLE scenario-definition table surfaces.

This module turns discovered SCENARIOS definition metadata into a conservative patch surface. It never mutates source workbooks; valid patches become generated-model input overrides keyed by normalized workbook cell references.

class fable_pyculator.scenario_definitions.ScenarioDefinitionEdit(value, cell_ref=None, table=None, row_label=None, column_label=None)[source]

One requested scenario-definition cell edit.

Parameters:

  • value (str | int | float | bool | None)

  • cell_ref (str | None)

  • table (str | None)

  • row_label (str | None)

  • column_label (str | None)

to_dict()[source]

Return a stable JSON-serializable representation.

Return type:

dict[str, Any]

class fable_pyculator.scenario_definitions.ScenarioDefinitionEditableCell(table_name, table_label, sheet, cell_ref, row_label, column_label, column_role_tag, original_value, scenario_locations=())[source]

One editable cell from a FABLE SCENARIOS definition table.

Parameters:

  • table_name (str)

  • table_label (str | None)

  • sheet (str)

  • cell_ref (str)

  • row_label (str)

  • column_label (str)

  • column_role_tag (str | None)

  • original_value (object)

  • scenario_locations (tuple[str, ...])

to_dict()[source]

Return a stable JSON-serializable representation.

Return type:

dict[str, Any]

class fable_pyculator.scenario_definitions.ScenarioDefinitionPatch(version, patch_id, edits, workbook_version=None, description=None)[source]

Versioned collection of scenario-definition edits.

Parameters:

  • version (int)

  • patch_id (str)

  • edits (tuple[ScenarioDefinitionEdit, ...])

  • workbook_version (str | None)

  • description (str | None)

to_dict()[source]

Return a stable JSON-serializable representation.

Return type:

dict[str, Any]

class fable_pyculator.scenario_definitions.ScenarioDefinitionPatchResult(patch, edits, inputs, editable_cell_count, notes=<factory>)[source]

Validated scenario-definition patch and generated-model input mapping.

Parameters:

  • patch (ScenarioDefinitionPatch)

  • edits (tuple[dict[str, Any], ...])

  • inputs (dict[str, str | int | float | bool | None])

  • editable_cell_count (int)

  • notes (tuple[str, ...])

to_dict()[source]

Return a stable JSON-serializable representation.

Return type:

dict[str, Any]

fable_pyculator.scenario_definitions.editable_scenario_definition_cells(spec, *, role_tag='DIRECT')[source]

Return editable non-formula scenario-definition cells for spec.

Parameters:
Return type:

tuple[ScenarioDefinitionEditableCell, …]

fable_pyculator.scenario_definitions.load_scenario_definition_patch(path)[source]

Load a scenario-definition patch from JSON, YAML, or YML.

Parameters:

path (str | Path)

Return type:

ScenarioDefinitionPatch

fable_pyculator.scenario_definitions.scenario_definition_input_mapping(spec, patch)[source]

Return generated-model input overrides for a validated scenario-definition patch.

Parameters:
Return type:

dict[str, str | int | float | bool | None]

fable_pyculator.scenario_definitions.validate_scenario_definition_patch(spec, patch)[source]

Validate patch against spec and return generated-model inputs.

Parameters:
Return type:

ScenarioDefinitionPatchResult

fable_pyculator.scenario_definitions.write_scenario_definition_patch(path, patch)[source]

Write a normalized scenario-definition patch as JSON.

Parameters:
Return type:

dict[str, Any]

Scenario Bundles

Scenario-bundle helpers for repeated FABLE Pyculator notebook runs.

Scenario bundles are a small analyst-facing layer over the existing notebook loop. They load named selection-control scenarios from JSON or YAML, validate them against a workbook-derived FableCalculatorSpec, run each scenario against an already available generated model, and write rendered table/headline artifacts under ignored local paths.

class fable_pyculator.scenarios.ScenarioBundle(version, bundle_id, workbook_version, scenarios, render=ScenarioBundleRenderOptions(output_table_names=None, output_table_column_flavour_tags=None, include_context_columns=True, headline_series_names=None, include_figures=False), description=None)[source]

A version-aware collection of named FABLE selection-control scenarios.

Parameters:
class fable_pyculator.scenarios.ScenarioBundleArtifactPaths(output_dir, normalized_bundle_path, manifest_path)[source]

Ignored local output paths for a scenario-bundle run.

Parameters:

  • output_dir (Path)

  • normalized_bundle_path (Path)

  • manifest_path (Path)

scenario_dir(scenario_id)[source]

Return the output directory for one scenario id.

Parameters:

scenario_id (str)

Return type:

Path

class fable_pyculator.scenarios.ScenarioBundleRenderOptions(output_table_names=None, output_table_column_flavour_tags=None, include_context_columns=True, headline_series_names=None, include_figures=False)[source]

Output rendering options shared by all scenarios in a bundle.

Parameters:

  • output_table_names (tuple[str, ...] | None)

  • output_table_column_flavour_tags (str | tuple[str, ...] | None)

  • include_context_columns (bool)

  • headline_series_names (tuple[str, ...] | None)

  • include_figures (bool)

class fable_pyculator.scenarios.ScenarioBundleRunResult(bundle, render, scenario_results)[source]

Rendered results from running every scenario in a bundle.

Parameters:
class fable_pyculator.scenarios.ScenarioCase(scenario_id, selections, label=None, description=None)[source]

One named scenario inside a scenario bundle.

Parameters:

  • scenario_id (str)

  • selections (dict[str, object])

  • label (str | None)

  • description (str | None)

fable_pyculator.scenarios.fable_scenario_bundle_artifact_paths(*, workbook_version, bundle_id, repo_root='.', output_dir=None)[source]

Return the default ignored artifact paths for a scenario-bundle run.

Parameters:

  • workbook_version (str)

  • bundle_id (str)

  • repo_root (str | Path)

  • output_dir (str | Path | None)

Return type:

ScenarioBundleArtifactPaths

fable_pyculator.scenarios.load_scenario_bundle(path)[source]

Load a scenario bundle from JSON, YAML, or YML.

Parameters:

path (str | Path)

Return type:

ScenarioBundle

fable_pyculator.scenarios.run_scenario_bundle(generated_model, spec, bundle, *, output_table_names=None, output_table_column_flavour_tags=None, include_context_columns=None, headline_series_names=None, include_figures=None)[source]

Run every scenario in bundle using the existing notebook-loop renderer.

Parameters:

  • generated_model (ModuleType | object)

  • spec (FableCalculatorSpec)

  • bundle (ScenarioBundle)

  • output_table_names (Sequence[str] | None)

  • output_table_column_flavour_tags (str | Sequence[str] | None)

  • include_context_columns (bool | None)

  • headline_series_names (Sequence[str] | None)

  • include_figures (bool | None)

Return type:

ScenarioBundleRunResult

fable_pyculator.scenarios.validate_scenario_bundle(bundle, spec)[source]

Validate bundle ids and selection-control values against a FABLE spec.

Parameters:
Return type:

ScenarioBundle

fable_pyculator.scenarios.write_scenario_artifacts(result, scenario, *, scenario_dir, output_dir)[source]

Write rendered artifacts for one scenario and return a manifest entry.

Parameters:
Return type:

dict[str, Any]

fable_pyculator.scenarios.write_scenario_bundle_artifacts(run_result, paths)[source]

Write normalized bundle metadata and rendered scenario artifacts.

Parameters:
Return type:

dict[str, Any]

Scenario-Bundle FreshForge Workflows

FreshForge orchestration helpers for FABLE scenario bundles.

class fable_pyculator.scenario_workflows.ScenarioBundleFreshForgeMatrixPaths(scenario_paths, matrix_path, workflow_template_path, matrix_summary_path)[source]

Ignored local paths for FreshForge matrix scenario-bundle orchestration.

Parameters:
property output_dir: Path

Return the scenario-bundle output root used as the FreshForge matrix workdir.

class fable_pyculator.scenario_workflows.ScenarioBundleFreshForgeMatrixPlan(bundle, paths, matrix, workflow_template, case_count)[source]

Prepared FreshForge matrix for a FABLE scenario bundle.

Parameters:
class fable_pyculator.scenario_workflows.ScenarioBundleFreshForgePaths(scenario_paths, workflow_path, run_summary_path)[source]

Ignored local paths for FreshForge-backed scenario-bundle orchestration.

Parameters:
namespaced_run_summary_path(run_namespace=None)[source]

Return the run-summary path for a namespace-aware FreshForge run.

Parameters:

run_namespace (str | None)

Return type:

Path

property output_dir: Path

Return the scenario-bundle output root used as the FreshForge workdir.

class fable_pyculator.scenario_workflows.ScenarioBundleFreshForgePlan(bundle, paths, workflow, run_namespace=None)[source]

Prepared FreshForge workflow for a FABLE scenario bundle.

Parameters:
fable_pyculator.scenario_workflows.build_scenario_bundle_freshforge_matrix(bundle, *, template_path, matrix_path, bundle_path, workbook_path, generated_model_path, workbook_id, module_name)[source]

Build a FreshForge matrix document for one scenario bundle.

Parameters:

  • bundle (ScenarioBundle)

  • template_path (str | Path)

  • matrix_path (str | Path)

  • bundle_path (str | Path)

  • workbook_path (str | Path)

  • generated_model_path (str | Path)

  • workbook_id (str)

  • module_name (str)

Return type:

dict[str, Any]

fable_pyculator.scenario_workflows.build_scenario_bundle_freshforge_matrix_template()[source]

Build the FreshForge matrix workflow template for one scenario case.

Return type:

dict[str, Any]

fable_pyculator.scenario_workflows.build_scenario_bundle_freshforge_workflow(bundle, *, bundle_path, workbook_path, generated_model_path, workbook_id, module_name)[source]

Build a FreshForge workflow document for one scenario bundle.

Parameters:

  • bundle (ScenarioBundle)

  • bundle_path (str | Path)

  • workbook_path (str | Path)

  • generated_model_path (str | Path)

  • workbook_id (str)

  • module_name (str)

Return type:

dict[str, Any]

fable_pyculator.scenario_workflows.default_generated_model_path(*, workbook_version, repo_root='.')[source]

Return the default generated-model path for a scenario-bundle workflow.

Parameters:

  • workbook_version (str)

  • repo_root (str | Path)

Return type:

Path

fable_pyculator.scenario_workflows.fable_scenario_bundle_freshforge_matrix_paths(*, workbook_version, bundle_id, repo_root='.', output_dir=None, matrix_path=None, workflow_template_path=None, matrix_summary_path=None)[source]

Return default paths for FreshForge matrix scenario-bundle orchestration.

Parameters:

  • workbook_version (str)

  • bundle_id (str)

  • repo_root (str | Path)

  • output_dir (str | Path | None)

  • matrix_path (str | Path | None)

  • workflow_template_path (str | Path | None)

  • matrix_summary_path (str | Path | None)

Return type:

ScenarioBundleFreshForgeMatrixPaths

fable_pyculator.scenario_workflows.fable_scenario_bundle_freshforge_paths(*, workbook_version, bundle_id, repo_root='.', output_dir=None, workflow_path=None, run_summary_path=None)[source]

Return default paths for FreshForge-backed scenario-bundle orchestration.

Parameters:

  • workbook_version (str)

  • bundle_id (str)

  • repo_root (str | Path)

  • output_dir (str | Path | None)

  • workflow_path (str | Path | None)

  • run_summary_path (str | Path | None)

Return type:

ScenarioBundleFreshForgePaths

fable_pyculator.scenario_workflows.plan_scenario_bundle_freshforge_matrix(plan)[source]

Plan a prepared FreshForge scenario-bundle matrix.

Parameters:

plan (ScenarioBundleFreshForgeMatrixPlan)

Return type:

dict[str, Any]

fable_pyculator.scenario_workflows.prepare_scenario_bundle_freshforge_matrix(bundle, *, bundle_path, workbook_path, generated_model_path, paths, repo_root='.', workbook_id=None, module_name=None, spec=None)[source]

Write a FreshForge matrix for one scenario-bundle case per scenario.

Parameters:

  • bundle (ScenarioBundle)

  • bundle_path (str | Path)

  • workbook_path (str | Path)

  • generated_model_path (str | Path)

  • paths (ScenarioBundleFreshForgeMatrixPaths)

  • repo_root (str | Path)

  • workbook_id (str | None)

  • module_name (str | None)

  • spec (Any | None)

Return type:

ScenarioBundleFreshForgeMatrixPlan

fable_pyculator.scenario_workflows.prepare_scenario_bundle_freshforge_workflow(bundle, *, bundle_path, workbook_path, generated_model_path, paths, repo_root='.', workbook_id=None, module_name=None, run_namespace=None, spec=None)[source]

Write a FreshForge workflow for a FABLE scenario bundle without running it.

Parameters:

  • bundle (ScenarioBundle)

  • bundle_path (str | Path)

  • workbook_path (str | Path)

  • generated_model_path (str | Path)

  • paths (ScenarioBundleFreshForgePaths)

  • repo_root (str | Path)

  • workbook_id (str | None)

  • module_name (str | None)

  • run_namespace (str | None)

  • spec (Any | None)

Return type:

ScenarioBundleFreshForgePlan

fable_pyculator.scenario_workflows.run_scenario_bundle_freshforge_matrix(plan, *, registry=None, fail_fast=False)[source]

Run a prepared FreshForge scenario-bundle matrix.

Parameters:
Return type:

Any

fable_pyculator.scenario_workflows.run_scenario_bundle_freshforge_workflow(plan, *, run_namespace=None, registry=None)[source]

Run a prepared scenario-bundle FreshForge workflow.

Parameters:
Return type:

Any

fable_pyculator.scenario_workflows.write_scenario_bundle_freshforge_matrix_summary(run_result, paths, *, path=None)[source]

Write a compact FreshForge matrix summary for a scenario-bundle matrix run.

Parameters:
Return type:

dict[str, Any]

fable_pyculator.scenario_workflows.write_scenario_bundle_freshforge_summary(run_result, paths, *, run_namespace=None, path=None)[source]

Write a compact FreshForge run summary for a scenario-bundle workflow.

Parameters:
Return type:

dict[str, Any]

Benchmark Evidence

Opt-in FABLE benchmark evidence orchestration.

This module packages compact benchmark evidence from local generated-model artifacts and, when requested, prepares or runs the existing FreshForge/Modelwright rebuild workflow. It is intentionally conservative: no workflow runs unless the caller opts in, no source workbooks or raw reports are copied, and equivalence is reported only from explicit comparison counts.

class fable_pyculator.benchmarks.FableBenchmarkMatrixEvidencePaths(workbook_version, evidence_id, output_dir, artifact_root, matrix_run_path, matrix_summary_path, modelwright_summary_json_path, modelwright_summary_markdown_path, benchmark_summary_json_path, benchmark_summary_markdown_path)[source]

Path contract for FABLE-facing benchmark matrix evidence packaging.

Parameters:

  • workbook_version (str)

  • evidence_id (str)

  • output_dir (Path)

  • artifact_root (Path)

  • matrix_run_path (Path | None)

  • matrix_summary_path (Path | None)

  • modelwright_summary_json_path (Path)

  • modelwright_summary_markdown_path (Path)

  • benchmark_summary_json_path (Path)

  • benchmark_summary_markdown_path (Path)

class fable_pyculator.benchmarks.FableBenchmarkMatrixEvidenceSummary(workbook_version, evidence_backend, evidence_id, evidence_status, equivalence_status, case_count, complete_count, incomplete_count, skipped_count, pass_count, fail_count, diagnostic_count, error_count, warning_count, paths, modelwright_summary, notes=())[source]

Compact FABLE-facing summary of a generated-model benchmark matrix.

Parameters:

  • workbook_version (str)

  • evidence_backend (Literal['modelwright'])

  • evidence_id (str)

  • evidence_status (str)

  • equivalence_status (str)

  • 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)

  • paths (dict[str, str | None])

  • modelwright_summary (dict[str, Any])

  • notes (tuple[str, ...])

to_dict()[source]

Return a stable JSON-serializable representation.

Return type:

dict[str, Any]

class fable_pyculator.benchmarks.FableBenchmarkRunPaths(workbook_version, artifact_dir, output_dir, benchmark_summary_json_path, benchmark_summary_markdown_path, validation_summary_json_path, validation_summary_markdown_path, workflow_path, freshforge_run_summary_path)[source]

Path contract for one opt-in FABLE benchmark evidence run.

Parameters:

  • workbook_version (str)

  • artifact_dir (Path)

  • output_dir (Path)

  • benchmark_summary_json_path (Path)

  • benchmark_summary_markdown_path (Path)

  • validation_summary_json_path (Path)

  • validation_summary_markdown_path (Path)

  • workflow_path (Path)

  • freshforge_run_summary_path (Path)

class fable_pyculator.benchmarks.FableBenchmarkRunSummary(workbook_version, mode, evidence_backend, evidence_status, equivalence_status, missing_artifacts, comparison, paths, freshforge=<factory>, scenario_bundle=<factory>, notes=())[source]

Compact benchmark orchestration summary safe for docs or CI artifacts.

Parameters:

  • workbook_version (str)

  • mode (Literal['evidence-only', 'freshforge-plan', 'freshforge-run'])

  • evidence_backend (Literal['modelwright', 'fable-local'])

  • evidence_status (str)

  • equivalence_status (str)

  • missing_artifacts (tuple[str, ...])

  • comparison (dict[str, Any])

  • paths (dict[str, str])

  • freshforge (dict[str, Any])

  • scenario_bundle (dict[str, Any])

  • notes (tuple[str, ...])

to_dict()[source]

Return a stable JSON-serializable representation.

Return type:

dict[str, Any]

fable_pyculator.benchmarks.fable_benchmark_matrix_evidence_paths(*, workbook_version='2021', repo_root='.', matrix_run_path=None, matrix_summary_path=None, artifact_root=None, output_dir=None, evidence_id=None)[source]

Return default paths for FABLE benchmark matrix evidence packaging.

Parameters:

  • workbook_version (str)

  • repo_root (str | Path)

  • matrix_run_path (str | Path | None)

  • matrix_summary_path (str | Path | None)

  • artifact_root (str | Path | None)

  • output_dir (str | Path | None)

  • evidence_id (str | None)

Return type:

FableBenchmarkMatrixEvidencePaths

fable_pyculator.benchmarks.fable_benchmark_run_paths(*, workbook_version='2021', repo_root='.', artifact_dir=None, output_dir=None)[source]

Return default paths for a version-specific FABLE benchmark evidence run.

Parameters:

  • workbook_version (str)

  • repo_root (str | Path)

  • artifact_dir (str | Path | None)

  • output_dir (str | Path | None)

Return type:

FableBenchmarkRunPaths

fable_pyculator.benchmarks.package_fable_benchmark_evidence(*, workbook_version='2021', repo_root='.', artifact_dir=None, output_dir=None, mode='evidence-only', require_artifacts=False, output_ref_strategy='output-columns', workbook_path=None, run_namespace=None, bundle_path=None, include_scenario_bundle_summary=False)[source]

Package benchmark evidence and optionally prepare or run the FreshForge rebuild workflow.

mode="evidence-only" only summarizes existing artifacts. freshforge-plan prepares the build workflow when the source workbook is available. freshforge-run additionally executes that workflow through FreshForge and records a compact run summary. Missing local artifacts are reported as skipped evidence unless require_artifacts is true.

Parameters:

  • workbook_version (str)

  • repo_root (str | Path)

  • artifact_dir (str | Path | None)

  • output_dir (str | Path | None)

  • mode (Literal['evidence-only', 'freshforge-plan', 'freshforge-run'])

  • require_artifacts (bool)

  • output_ref_strategy (Literal['output-columns', 'headline-only', 'table', 'flavour-tags', 'all-columns'])

  • workbook_path (str | Path | None)

  • run_namespace (str | None)

  • bundle_path (str | Path | None)

  • include_scenario_bundle_summary (bool)

Return type:

FableBenchmarkRunSummary

fable_pyculator.benchmarks.package_fable_benchmark_matrix_evidence(*, workbook_version='2021', repo_root='.', matrix_run_path=None, matrix_summary_path=None, artifact_root=None, output_dir=None, evidence_id=None, require_evidence=False)[source]

Package compact FABLE benchmark matrix evidence through Modelwright.

This wrapper supplies FABLE-C path defaults and public-facing summary text. Generic matrix aggregation remains in Modelwright.

Parameters:

  • workbook_version (str)

  • repo_root (str | Path)

  • matrix_run_path (str | Path | None)

  • matrix_summary_path (str | Path | None)

  • artifact_root (str | Path | None)

  • output_dir (str | Path | None)

  • evidence_id (str | None)

  • require_evidence (bool)

Return type:

FableBenchmarkMatrixEvidenceSummary

fable_pyculator.benchmarks.write_fable_benchmark_matrix_evidence(summary, paths=None)[source]

Write compact FABLE-facing JSON and Markdown matrix evidence summaries.

Parameters:
Return type:

dict[str, Any]

fable_pyculator.benchmarks.write_fable_benchmark_summary(summary, paths=None)[source]

Write compact JSON and Markdown benchmark summaries.

Parameters:
Return type:

dict[str, Any]

Validation Evidence

Compact validation-evidence extraction for FABLE generated-model artifacts.

The helpers in this module summarize existing local Modelwright/FreshForge artifacts without copying raw workbooks, raw generated values, raw reports, or generated Python source into tracked-friendly evidence. A summary may claim pass only when explicit comparable-output, match, and mismatch counts prove zero mismatches.

class fable_pyculator.validation.ValidationEvidencePaths(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]

Local artifact and compact evidence paths for one FABLE workbook version.

Parameters:

  • 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)

class fable_pyculator.validation.ValidationEvidenceSummary(workbook_version, evidence_status, equivalence_status, missing_artifacts, artifacts, stages, comparison, notes=())[source]

Sanitized validation evidence summary suitable for sharing or uploading.

Parameters:

  • workbook_version (str)

  • evidence_status (str)

  • equivalence_status (str)

  • missing_artifacts (tuple[str, ...])

  • artifacts (dict[str, str])

  • stages (dict[str, dict[str, Any]])

  • comparison (dict[str, Any])

  • notes (tuple[str, ...])

to_dict()[source]

Return a stable JSON-serializable representation.

Return type:

dict[str, Any]

fable_pyculator.validation.extract_validation_evidence(paths, *, workbook_version, require_artifacts=False)[source]

Extract sanitized evidence from existing local artifacts.

Parameters:
Return type:

ValidationEvidenceSummary

fable_pyculator.validation.fable_validation_evidence_paths(*, workbook_version='2021', repo_root='.', artifact_dir=None, output_dir=None)[source]

Return default validation-evidence input and output paths.

Parameters:

  • workbook_version (str)

  • repo_root (str | Path)

  • artifact_dir (str | Path | None)

  • output_dir (str | Path | None)

Return type:

ValidationEvidencePaths

fable_pyculator.validation.write_validation_evidence(summary, paths)[source]

Write compact JSON and Markdown validation-evidence summaries.

Parameters:
Return type:

dict[str, Any]

Output-Ref Strategy Comparison

Compare FABLE output-ref strategies before generated-model rebuilds.

This module prepares compact, local comparison artifacts for different FABLE output-ref boundaries. It does not run FreshForge or Modelwright and does not claim generated-model equivalence.

class fable_pyculator.strategy_comparison.OutputRefStrategyCase(case_id, strategy, label, column_flavour_tags='OUTPUT-*', table_names=(), description='')[source]

One named output-ref boundary to compare.

Parameters:

  • case_id (str)

  • strategy (Literal['output-columns', 'headline-only', 'table', 'flavour-tags', 'all-columns'])

  • label (str)

  • column_flavour_tags (str | tuple[str, ...] | None)

  • table_names (tuple[str, ...])

  • description (str)

to_dict()[source]

Return a stable JSON representation.

Return type:

dict[str, Any]

class fable_pyculator.strategy_comparison.OutputRefStrategyComparisonEntry(case, output_ref_count, comparable_output_count, output_refs_path, workflow_path, run_namespace, evidence_source=None, evidence_summary=None, freshforge_run_summary=None)[source]

Compact comparison result for one strategy case.

Parameters:

  • case (OutputRefStrategyCase)

  • output_ref_count (int)

  • comparable_output_count (int)

  • output_refs_path (Path)

  • workflow_path (Path | None)

  • run_namespace (str)

  • evidence_source (str | None)

  • evidence_summary (dict[str, Any] | None)

  • freshforge_run_summary (dict[str, Any] | None)

to_dict()[source]

Return a stable JSON representation.

Return type:

dict[str, Any]

class fable_pyculator.strategy_comparison.OutputRefStrategyComparisonPaths(workbook_version, output_dir, summary_json_path, summary_markdown_path)[source]

Path layout for one strategy-comparison run.

Parameters:

  • workbook_version (str)

  • output_dir (Path)

  • summary_json_path (Path)

  • summary_markdown_path (Path)

case_dir(case_id)[source]

Return the per-case artifact directory.

Parameters:

case_id (str)

Return type:

Path

property matrix_path: Path

Return the default FreshForge matrix YAML path.

property matrix_template_path: Path

Return the default FreshForge matrix workflow-template YAML path.

output_refs_path(case_id)[source]

Return the per-case output refs JSON path.

Parameters:

case_id (str)

Return type:

Path

workflow_path(case_id)[source]

Return the per-case FreshForge workflow JSON path.

Parameters:

case_id (str)

Return type:

Path

class fable_pyculator.strategy_comparison.OutputRefStrategyComparisonResult(workbook_version, paths, entries, notes=<factory>)[source]

Collection of compared FABLE output-ref strategies.

Parameters:
to_dict()[source]

Return a stable JSON representation.

Return type:

dict[str, Any]

class fable_pyculator.strategy_comparison.OutputRefStrategyMatrixPaths(workbook_version, output_dir, matrix_path, workflow_template_path)[source]

Path layout for a FreshForge matrix built from a strategy comparison.

Parameters:

  • workbook_version (str)

  • output_dir (Path)

  • matrix_path (Path)

  • workflow_template_path (Path)

to_dict()[source]

Return a stable JSON representation.

Return type:

dict[str, Any]

class fable_pyculator.strategy_comparison.OutputRefStrategyMatrixResult(workbook_version, paths, matrix, workflow_template, case_count, notes=<factory>)[source]

Prepared FreshForge matrix artifacts for strategy comparison cases.

Parameters:

  • workbook_version (str)

  • paths (OutputRefStrategyMatrixPaths)

  • matrix (dict[str, Any])

  • workflow_template (dict[str, Any])

  • case_count (int)

  • notes (tuple[str, ...])

to_dict()[source]

Return a stable JSON representation.

Return type:

dict[str, Any]

fable_pyculator.strategy_comparison.build_output_ref_strategy_matrix(result, *, matrix_path=None)[source]

Build a FreshForge matrix document for prepared strategy-comparison workflows.

Matrix creation is FreshForge-free. Planning and running the written matrix require FreshForge to be installed separately.

Parameters:
Return type:

OutputRefStrategyMatrixResult

fable_pyculator.strategy_comparison.compare_output_ref_strategies(spec, *, workbook_version='2021', workbook_path, repo_root='.', output_dir=None, cases=None, selected_case_ids=None, include_workflows=False, include_existing_evidence=False)[source]

Compare output-ref strategies and write per-case preparation artifacts.

Parameters:

  • spec (FableCalculatorSpec)

  • workbook_version (str)

  • workbook_path (str | Path)

  • repo_root (str | Path)

  • output_dir (str | Path | None)

  • cases (Sequence[OutputRefStrategyCase] | None)

  • selected_case_ids (Sequence[str] | None)

  • include_workflows (bool)

  • include_existing_evidence (bool)

Return type:

OutputRefStrategyComparisonResult

fable_pyculator.strategy_comparison.default_output_ref_strategy_cases()[source]

Return deterministic default strategy cases for FABLE-C output tables.

Return type:

tuple[OutputRefStrategyCase, …]

fable_pyculator.strategy_comparison.output_ref_strategy_comparison_paths(*, workbook_version='2021', repo_root='.', output_dir=None)[source]

Return default output-ref strategy comparison paths.

Parameters:

  • workbook_version (str)

  • repo_root (str | Path)

  • output_dir (str | Path | None)

Return type:

OutputRefStrategyComparisonPaths

fable_pyculator.strategy_comparison.plan_output_ref_strategy_matrix(matrix_path)[source]

Plan a FreshForge strategy matrix and return a serializable payload.

Parameters:

matrix_path (str | Path)

Return type:

dict[str, Any]

fable_pyculator.strategy_comparison.run_output_ref_strategy_matrix(matrix_path, *, workdir=None, fail_fast=False)[source]

Run a FreshForge strategy matrix and return a serializable payload.

Parameters:

  • matrix_path (str | Path)

  • workdir (str | Path | None)

  • fail_fast (bool)

Return type:

dict[str, Any]

fable_pyculator.strategy_comparison.write_output_ref_strategy_comparison(result)[source]

Write compact JSON and Markdown strategy-comparison summaries.

Parameters:

result (OutputRefStrategyComparisonResult)

Return type:

dict[str, Any]

fable_pyculator.strategy_comparison.write_output_ref_strategy_matrix(result)[source]

Write a FreshForge strategy matrix and workflow template as YAML.

Parameters:

result (OutputRefStrategyMatrixResult)

Return type:

dict[str, Any]

FreshForge Workflow Helpers

FreshForge workflow helpers for FABLE generated-model builds.

The functions in this module turn workbook-derived FABLE Pyculator metadata into the explicit artifact files that Modelwright needs. They do not generate Python models directly; they prepare the output-ref lists, cached-workbook validation scenarios, and FreshForge workflow documents that hand the generic generation and validation stages back to Modelwright.

class fable_pyculator.workflows.FableFreshForgeBuildPaths(workbook_path, artifact_dir, output_refs_path, workflow_path, contract_path, expressions_path, constants_path, inference_result_path, generation_result_path, generated_model_path, generated_values_path, validation_scenario_path, evaluation_report_path)[source]

Version-specific artifact paths for a FABLE Modelwright/FreshForge build.

Parameters:

  • workbook_path (Path)

  • artifact_dir (Path)

  • output_refs_path (Path)

  • workflow_path (Path)

  • contract_path (Path)

  • expressions_path (Path)

  • constants_path (Path)

  • inference_result_path (Path)

  • generation_result_path (Path)

  • generated_model_path (Path)

  • generated_values_path (Path)

  • validation_scenario_path (Path)

  • evaluation_report_path (Path)

class fable_pyculator.workflows.FableFreshForgeRebuildPlan(paths, output_refs, validation_scenario, workflow)[source]

Prepared artifacts for a FABLE Modelwright/FreshForge rebuild.

The plan records the ignored local paths and JSON payloads produced before FreshForge execution. It is intentionally not an execution result: callers may inspect these files, run freshforge plan, or explicitly opt into a long freshforge run after review.

Parameters:

  • paths (FableFreshForgeBuildPaths)

  • output_refs (tuple[str, ...])

  • validation_scenario (dict[str, Any])

  • workflow (dict[str, Any])

property comparable_output_count: int

Return the count of nonblank cached workbook outputs in the validation scenario.

fable_pyculator.workflows.build_cached_workbook_validation_scenario(workbook_path, output_refs, *, generated_model_path, scenario_id, description, source_workbook=None, generated_model=None, numeric_tolerance=1e-09)[source]

Build a Modelwright validation scenario from cached workbook output values.

Blank cached outputs are skipped because they are not comparable evidence. Numeric outputs get the supplied tolerance; text, boolean, and spreadsheet error values use exact matching.

Parameters:

  • workbook_path (str | Path)

  • output_refs (Iterable[str])

  • generated_model_path (str | Path)

  • scenario_id (str)

  • description (str)

  • source_workbook (str | Path | None)

  • generated_model (str | Path | None)

  • numeric_tolerance (float)

Return type:

dict[str, Any]

fable_pyculator.workflows.build_modelwright_freshforge_workflow(paths, *, workdir, workflow_id, name, description, module_name)[source]

Build a FreshForge workflow document for Modelwright generated-model stages.

Parameters:
Return type:

dict[str, Any]

fable_pyculator.workflows.derive_output_refs(spec, *, column_flavour_tags='OUTPUT-*', table_names=None)[source]

Derive sorted workbook cell refs from discovered output-table metadata.

column_flavour_tags accepts exact tags, the DATA/OUTPUT family aliases, and trailing wildcard patterns such as OUTPUT-*. Passing None selects every column in the selected output tables.

Parameters:

  • spec (FableCalculatorSpec)

  • column_flavour_tags (str | Sequence[str] | None)

  • table_names (Sequence[str] | None)

Return type:

tuple[str, …]

fable_pyculator.workflows.derive_output_refs_for_strategy(spec, *, strategy, column_flavour_tags='OUTPUT-*', table_names=None)[source]

Derive sorted output refs using a named FABLE build strategy.

Parameters:

  • spec (FableCalculatorSpec)

  • strategy (Literal['output-columns', 'headline-only', 'table', 'flavour-tags', 'all-columns'])

  • column_flavour_tags (str | Sequence[str] | None)

  • table_names (Sequence[str] | None)

Return type:

tuple[str, …]

fable_pyculator.workflows.fable_freshforge_build_paths(*, workbook_version, repo_root='.', workbook_path=None, artifact_dir=None, workflow_filename='freshforge-modelwright-run-workflow.json')[source]

Return version-specific FABLE FreshForge build artifact paths by convention.

Parameters:

  • workbook_version (str)

  • repo_root (str | Path)

  • workbook_path (str | Path | None)

  • artifact_dir (str | Path | None)

  • workflow_filename (str)

Return type:

FableFreshForgeBuildPaths

fable_pyculator.workflows.freshforge_2021_build_paths(*, repo_root='.', workbook_path='tmp/private-workbooks/2021_Open_FABLECalculator.xlsx', artifact_dir=PosixPath('tmp/generated-models/fable-2021'), workflow_filename='freshforge-modelwright-run-workflow.json')[source]

Return the default 2021 FABLE FreshForge build artifact layout.

Paths are resolved under repo_root so notebooks can run from VSCode’s notebook directory or from the repository root while still writing artifacts to the same ignored tmp/ location.

Parameters:

  • repo_root (str | Path)

  • workbook_path (str | Path)

  • artifact_dir (str | Path)

  • workflow_filename (str)

Return type:

FableFreshForgeBuildPaths

fable_pyculator.workflows.prepare_2021_freshforge_rebuild(*, repo_root='.', workbook_path='tmp/private-workbooks/2021_Open_FABLECalculator.xlsx', artifact_dir=PosixPath('tmp/generated-models/fable-2021'), workflow_filename='freshforge-modelwright-run-workflow.json', output_ref_strategy='output-columns', column_flavour_tags='OUTPUT-*', table_names=None, module_name='generated_fable_2021_model', workflow_id='fable_2021_modelwright_run', workflow_name='FABLE 2021 Modelwright FreshForge run', workflow_description='FreshForge graph for rebuilding the 2021 FABLE generated model.', scenario_id='fable-c-2021-freshforge-rebuild', scenario_description='Cached-workbook validation slice derived from FABLE Pyculator output refs.', numeric_tolerance=1e-09, spec=None)[source]

Prepare the default 2021 FABLE FreshForge rebuild artifacts.

Parameters:

  • repo_root (str | Path)

  • workbook_path (str | Path)

  • artifact_dir (str | Path)

  • workflow_filename (str)

  • output_ref_strategy (Literal['output-columns', 'headline-only', 'table', 'flavour-tags', 'all-columns'])

  • column_flavour_tags (str | Sequence[str] | None)

  • table_names (Sequence[str] | None)

  • module_name (str)

  • workflow_id (str)

  • workflow_name (str)

  • workflow_description (str)

  • scenario_id (str)

  • scenario_description (str)

  • numeric_tolerance (float)

  • spec (FableCalculatorSpec | None)

Return type:

FableFreshForgeRebuildPlan

fable_pyculator.workflows.prepare_freshforge_rebuild(*, workbook_version, repo_root='.', workbook_path=None, artifact_dir=None, workflow_filename='freshforge-modelwright-run-workflow.json', output_ref_strategy='output-columns', column_flavour_tags='OUTPUT-*', table_names=None, module_name=None, workflow_id=None, workflow_name=None, workflow_description=None, scenario_id=None, scenario_description='Cached-workbook validation slice derived from FABLE Pyculator output refs.', numeric_tolerance=1e-09, spec=None)[source]

Prepare version-specific FABLE FreshForge rebuild artifacts.

This helper performs the deterministic setup work shared by notebooks and scripts:

  • build or receive the notebook spec;

  • derive output refs using a named strategy;

  • write output_refs.json;

  • write a cached-workbook validation scenario;

  • write the downstream Modelwright FreshForge workflow JSON.

It does not run FreshForge or Modelwright. The source workbook must already exist at the configured ignored local path.

Parameters:

  • workbook_version (str)

  • repo_root (str | Path)

  • workbook_path (str | Path | None)

  • artifact_dir (str | Path | None)

  • workflow_filename (str)

  • output_ref_strategy (Literal['output-columns', 'headline-only', 'table', 'flavour-tags', 'all-columns'])

  • column_flavour_tags (str | Sequence[str] | None)

  • table_names (Sequence[str] | None)

  • module_name (str | None)

  • workflow_id (str | None)

  • workflow_name (str | None)

  • workflow_description (str | None)

  • scenario_id (str | None)

  • scenario_description (str)

  • numeric_tolerance (float)

  • spec (FableCalculatorSpec | None)

Return type:

FableFreshForgeRebuildPlan

fable_pyculator.workflows.write_freshforge_workflow(path, workflow)[source]

Write a FreshForge workflow document as stable JSON.

Parameters:

  • path (str | Path)

  • workflow (dict[str, Any])

Return type:

dict[str, Any]

fable_pyculator.workflows.write_output_refs(path, output_refs)[source]

Write sorted unique output refs as stable JSON and return the written refs.

Parameters:

  • path (str | Path)

  • output_refs (Iterable[str])

Return type:

tuple[str, …]

fable_pyculator.workflows.write_validation_scenario(path, scenario)[source]

Write a Modelwright validation scenario as stable JSON.

Parameters:

  • path (str | Path)

  • scenario (dict[str, Any])

Return type:

dict[str, Any]

FreshForge Provider

FreshForge provider metadata for FABLE Pyculator notebook workflows.

This module is intentionally plan-only. It lets FreshForge validate and plan FABLE-specific notebook workflow stages, while execution stays with notebooks, FABLE Pyculator helper APIs, and Modelwright’s generated-model provider.

class fable_pyculator.freshforge.FablePyculatorFreshForgeProvider[source]

FreshForge provider for plan-only FABLE Pyculator notebook workflow stages.

metadata()[source]

Return FreshForge provider metadata.

Return type:

Any

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

Execute Phase 19 scenario-bundle nodes while leaving Phase 9 nodes plan-only.

Parameters:

  • node (Any)

  • node_type (Any)

  • context (Any)

Return type:

Any

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

Validate broad FABLE Pyculator node shape without executing notebook helpers.

Parameters:

  • node (Any)

  • node_type (Any)

  • location (str)

Return type:

tuple[Any, …]

fable_pyculator.freshforge.provider_factory()[source]

Return the FABLE Pyculator FreshForge provider for entry-point discovery.

Return type:

FablePyculatorFreshForgeProvider