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:
parameters (tuple[ScenarioParameter, ...] | list[ScenarioParameter])
selection_controls (tuple[SelectionControl, ...] | list[SelectionControl])
scenario_definition_tables (tuple[ScenarioDefinitionTable, ...] | list[ScenarioDefinitionTable])
outputs (tuple[OutputIndicator, ...] | list[OutputIndicator])
output_tables (tuple[OutputTable, ...] | list[OutputTable])
headline_series (tuple[HeadlineSeries, ...] | list[HeadlineSeries])
workbook_id (str | None)
provenance (str | None)
- 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 longfreshforge runafter 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:
workbook_version (str)
paths (OutputRefStrategyComparisonPaths)
entries (tuple[OutputRefStrategyComparisonEntry, ...])
notes (tuple[str, ...])
- 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_tagsstores output-sheet flavour metadata such asDIRECT,DATA-5, orOUTPUT-8. That vocabulary belongs to output tables only; scenario-definition input tables usecolumn_role_tagsinstead.- 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:
version (int)
bundle_id (str)
workbook_version (str)
scenarios (tuple[ScenarioCase, ...])
render (ScenarioBundleRenderOptions)
description (str | None)
- 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:
scenario_paths (ScenarioBundleArtifactPaths)
matrix_path (Path)
workflow_template_path (Path)
matrix_summary_path (Path)
- 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:
bundle (ScenarioBundle)
matrix (dict[str, Any])
workflow_template (dict[str, Any])
case_count (int)
- class fable_pyculator.ScenarioBundleFreshForgePaths(scenario_paths, workflow_path, run_summary_path)[source]
Ignored local paths for FreshForge-backed scenario-bundle orchestration.
- Parameters:
scenario_paths (ScenarioBundleArtifactPaths)
workflow_path (Path)
run_summary_path (Path)
- 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:
bundle (ScenarioBundle)
paths (ScenarioBundleFreshForgePaths)
workflow (dict[str, Any])
run_namespace (str | None)
- class fable_pyculator.ScenarioBundleRunResult(bundle, render, scenario_results)[source]
Rendered results from running every scenario in a bundle.
- Parameters:
bundle (ScenarioBundle)
render (ScenarioBundleRenderOptions)
scenario_results (dict[str, NotebookLoopResult])
- 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 definitiontables.- 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 definitiontable.- 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 definitionsheet.These records make definition tables inspectable in notebooks.
column_role_tagspreserves workbook role/source markers such asDIRECT,SCEN,CALC, andDATA-1. Thescenario_locationsfield stores workbook markers such asS.3.Cthat 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
SelectionControlinstead.- 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
xmarker. Selecting one option means placingxin 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
xin this table.The returned mapping is keyed by normalized full cell references. It clears unselected marker cells with
Nonebecause 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:
- 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:
- 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:
paths (FableFreshForgeBuildPaths)
workdir (str | Path)
workflow_id (str)
name (str)
description (str)
module_name (str)
- Return type:
dict[str, Any]
- fable_pyculator.build_notebook_spec(workbook_path, *, workbook_id, strict_headlines=False)[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. Unsupported default headline series are skipped unless
strict_headlinesis true.- Parameters:
workbook_path (str | Path)
workbook_id (str)
strict_headlines (bool)
- Return type:
- 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:
result (OutputRefStrategyComparisonResult)
matrix_path (str | Path | None)
- Return type:
- 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:
- fable_pyculator.curate_default_headline_series(workbook_path, *, strict=False)[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
Indextableswhere available, then maps stable table columns on the canonical output sheets into notebook-ready time series.Workbook versions differ. The 2024 Canada workbook, for example, has a
ResultsWaterirrigation table instead of theTotalResultsWFwater-footprint table used by the 2020 and 2021 workbooks. By default, a series whose table or headers are absent is skipped so a version can still expose the headline series it does support. Passstrict=Trueto keep the older fail-fast behavior.- Parameters:
workbook_path (str | Path)
strict (bool)
- 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_tagsaccepts exact tags, theDATA/OUTPUTfamily aliases, and trailing wildcard patterns such asOUTPUT-*. PassingNoneselects 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
xselection tables onSCENARIOS 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:
spec (FableCalculatorSpec)
role_tag (str)
- Return type:
tuple[ScenarioDefinitionEditableCell, …]
- fable_pyculator.extract_validation_evidence(paths, *, workbook_version, require_artifacts=False)[source]
Extract sanitized evidence from existing local artifacts.
- Parameters:
paths (ValidationEvidencePaths)
workbook_version (str)
require_artifacts (bool)
- Return type:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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_rootso notebooks can run from VSCode’s notebook directory or from the repository root while still writing artifacts to the same ignoredtmp/location.- Parameters:
repo_root (str | Path)
workbook_path (str | Path)
artifact_dir (str | Path)
workflow_filename (str)
- Return type:
- fable_pyculator.headline_frame(run, series_name)[source]
Render one curated FABLE headline series as a tidy pandas DataFrame.
- Parameters:
run (ScenarioRun)
series_name (str)
- 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 acalculatefunction.- 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:
- fable_pyculator.load_scenario_definition_patch(path)[source]
Load a scenario-definition patch from JSON, YAML, or YML.
- Parameters:
path (str | Path)
- Return type:
- 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:
- 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_tagsaccepts exact tags such asOUTPUT-8, family aliases such asDATA, and trailing-star patterns such asOUTPUT-*. Context columns taggedDIRECTorAUXare 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-planprepares the build workflow when the source workbook is available.freshforge-runadditionally executes that workflow through FreshForge and records a compact run summary. Missing local artifacts are reported as skipped evidence unlessrequire_artifactsis 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:
- 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:
- 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:
- 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:
run (ScenarioRun)
series_name (str)
- Return type:
Any
- fable_pyculator.plot_outputs(run, *, group=None)[source]
Plot numeric output indicators as a simple horizontal bar chart.
- Parameters:
run (ScenarioRun)
group (str | None)
- 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:
- 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:
- 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)
repo_root (str | Path)
workbook_id (str | None)
module_name (str | None)
spec (Any | None)
- Return type:
- 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:
- 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:
- 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:
- 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=Noneandheadline_series_names=Nonerender 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:
- 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:
generated_model (ModuleType | object)
spec (FableCalculatorSpec)
values (Mapping[str, object] | None)
name (str)
scenario_definition_patch (ScenarioDefinitionPatch | Mapping[str, Any] | str | Path | None)
- Return type:
- 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
bundleusing 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:
- fable_pyculator.run_scenario_bundle_freshforge_matrix(plan, *, registry=None, fail_fast=False)[source]
Run a prepared FreshForge scenario-bundle matrix.
- Parameters:
registry (Any | None)
fail_fast (bool)
- 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:
plan (ScenarioBundleFreshForgePlan)
run_namespace (str | None)
registry (Any | None)
- Return type:
Any
- fable_pyculator.scenario_definition_input_mapping(spec, patch)[source]
Return generated-model input overrides for a validated scenario-definition patch.
- Parameters:
spec (FableCalculatorSpec)
patch (ScenarioDefinitionPatch | Mapping[str, Any] | str | Path | None)
- 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:
spec (FableCalculatorSpec)
table_name (str)
- 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.3withinclude_family=Truereturns tables markedS.3.A,S.3.B, and so on. Passing an exact marker such asS.3.Creturns only tables with that marker.- Parameters:
spec (FableCalculatorSpec)
location (str)
include_family (bool)
- 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:
bundle (ScenarioBundle)
spec (FableCalculatorSpec)
- Return type:
- fable_pyculator.validate_scenario_definition_patch(spec, patch)[source]
Validate
patchagainstspecand return generated-model inputs.- Parameters:
spec (FableCalculatorSpec)
patch (ScenarioDefinitionPatch)
- Return type:
- fable_pyculator.write_fable_benchmark_matrix_evidence(summary, paths=None)[source]
Write compact FABLE-facing JSON and Markdown matrix evidence summaries.
- Parameters:
summary (FableBenchmarkMatrixEvidenceSummary)
paths (FableBenchmarkMatrixEvidencePaths | None)
- Return type:
dict[str, Any]
- fable_pyculator.write_fable_benchmark_summary(summary, paths=None)[source]
Write compact JSON and Markdown benchmark summaries.
- Parameters:
summary (FableBenchmarkRunSummary)
paths (FableBenchmarkRunPaths | None)
- 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:
result (NotebookLoopResult)
scenario (ScenarioCase)
scenario_dir (str | Path)
output_dir (str | Path)
- Return type:
dict[str, Any]
- fable_pyculator.write_scenario_bundle_artifacts(run_result, paths)[source]
Write normalized bundle metadata and rendered scenario artifacts.
- Parameters:
run_result (ScenarioBundleRunResult)
paths (ScenarioBundleArtifactPaths)
- 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:
run_result (Any)
path (str | Path | None)
- 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:
run_result (Any)
paths (ScenarioBundleFreshForgePaths)
run_namespace (str | None)
path (str | Path | None)
- Return type:
dict[str, Any]
- fable_pyculator.write_scenario_definition_patch(path, patch)[source]
Write a normalized scenario-definition patch as JSON.
- Parameters:
path (str | Path)
patch (ScenarioDefinitionPatch)
- Return type:
dict[str, Any]
- fable_pyculator.write_validation_evidence(summary, paths)[source]
Write compact JSON and Markdown validation-evidence summaries.
- Parameters:
summary (ValidationEvidenceSummary)
paths (ValidationEvidencePaths)
- 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:
parameters (tuple[ScenarioParameter, ...] | list[ScenarioParameter])
selection_controls (tuple[SelectionControl, ...] | list[SelectionControl])
scenario_definition_tables (tuple[ScenarioDefinitionTable, ...] | list[ScenarioDefinitionTable])
outputs (tuple[OutputIndicator, ...] | list[OutputIndicator])
output_tables (tuple[OutputTable, ...] | list[OutputTable])
headline_series (tuple[HeadlineSeries, ...] | list[HeadlineSeries])
workbook_id (str | None)
provenance (str | None)
- 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_tagsstores output-sheet flavour metadata such asDIRECT,DATA-5, orOUTPUT-8. That vocabulary belongs to output tables only; scenario-definition input tables usecolumn_role_tagsinstead.- 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 definitionsheet.These records make definition tables inspectable in notebooks.
column_role_tagspreserves workbook role/source markers such asDIRECT,SCEN,CALC, andDATA-1. Thescenario_locationsfield stores workbook markers such asS.3.Cthat 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
SelectionControlinstead.- 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
xmarker. Selecting one option means placingxin 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
xin this table.The returned mapping is keyed by normalized full cell references. It clears unselected marker cells with
Nonebecause Modelwright scenarios accept explicit cell inputs, not workbook UI gestures.- Parameters:
selected_value (object)
- Return type:
dict[str, object]
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, *, strict=False)[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
Indextableswhere available, then maps stable table columns on the canonical output sheets into notebook-ready time series.Workbook versions differ. The 2024 Canada workbook, for example, has a
ResultsWaterirrigation table instead of theTotalResultsWFwater-footprint table used by the 2020 and 2021 workbooks. By default, a series whose table or headers are absent is skipped so a version can still expose the headline series it does support. Passstrict=Trueto keep the older fail-fast behavior.- Parameters:
workbook_path (str | Path)
strict (bool)
- 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
xselection tables onSCENARIOS 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
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 definitiontables.- Parameters:
spec (FableCalculatorSpec)
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:
- 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:
- fable_pyculator.notebook.build_notebook_spec(workbook_path, *, workbook_id, strict_headlines=False)[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. Unsupported default headline series are skipped unless
strict_headlinesis true.- Parameters:
workbook_path (str | Path)
workbook_id (str)
strict_headlines (bool)
- Return type:
- 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 acalculatefunction.- 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:
- 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:
- 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=Noneandheadline_series_names=Nonerender 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:
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:
run (ScenarioRun)
series_name (str)
- 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_tagsaccepts exact tags such asOUTPUT-8, family aliases such asDATA, and trailing-star patterns such asOUTPUT-*. Context columns taggedDIRECTorAUXare 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:
run (ScenarioRun)
series_name (str)
- Return type:
Any
- fable_pyculator.surface.plot_outputs(run, *, group=None)[source]
Plot numeric output indicators as a simple horizontal bar chart.
- Parameters:
run (ScenarioRun)
group (str | None)
- 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:
generated_model (ModuleType | object)
spec (FableCalculatorSpec)
values (Mapping[str, object] | None)
name (str)
scenario_definition_patch (ScenarioDefinitionPatch | Mapping[str, Any] | str | Path | None)
- Return type:
- fable_pyculator.surface.scenario_definition_table_frame(spec, table_name)[source]
Render one discovered FABLE scenario definition table as a pandas DataFrame.
- Parameters:
spec (FableCalculatorSpec)
table_name (str)
- 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.3withinclude_family=Truereturns tables markedS.3.A,S.3.B, and so on. Passing an exact marker such asS.3.Creturns only tables with that marker.- Parameters:
spec (FableCalculatorSpec)
location (str)
include_family (bool)
- 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)
- 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 definitiontable.- 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, ...])
- 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)
- 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, ...])
- fable_pyculator.scenario_definitions.editable_scenario_definition_cells(spec, *, role_tag='DIRECT')[source]
Return editable non-formula scenario-definition cells for
spec.- Parameters:
spec (FableCalculatorSpec)
role_tag (str)
- 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:
- fable_pyculator.scenario_definitions.scenario_definition_input_mapping(spec, patch)[source]
Return generated-model input overrides for a validated scenario-definition patch.
- Parameters:
spec (FableCalculatorSpec)
patch (ScenarioDefinitionPatch | Mapping[str, Any] | str | Path | None)
- Return type:
dict[str, str | int | float | bool | None]
- fable_pyculator.scenario_definitions.validate_scenario_definition_patch(spec, patch)[source]
Validate
patchagainstspecand return generated-model inputs.- Parameters:
spec (FableCalculatorSpec)
patch (ScenarioDefinitionPatch)
- Return type:
- fable_pyculator.scenario_definitions.write_scenario_definition_patch(path, patch)[source]
Write a normalized scenario-definition patch as JSON.
- Parameters:
path (str | Path)
patch (ScenarioDefinitionPatch)
- Return type:
dict[str, Any]
Scenario Consistency Rules
Status-aware scenario-consistency rules for FABLE scenario selections.
- class fable_pyculator.scenario_rules.RuleEvaluation(errors=(), warnings=(), exploratory=())[source]
Rule consequences for one scenario.
- Parameters:
- property valid: bool
Return whether no hard error was raised.
- class fable_pyculator.scenario_rules.RuleHit(rule_id, family, severity, status, message, review_question)[source]
One rule consequence for a scenario.
- Parameters:
rule_id (str)
family (str)
severity (str)
status (str)
message (str)
review_question (str)
- class fable_pyculator.scenario_rules.ScenarioRule(id, family, severity, confidence, status, message, review_question, condition=None, require=None, coherence=None, review=None)[source]
One reviewable scenario-consistency rule.
- Parameters:
id (str)
family (str)
severity (str)
confidence (str)
status (str)
message (str)
review_question (str)
condition (Mapping[str, Any] | None)
require (Mapping[str, Any] | None)
coherence (Mapping[str, Any] | None)
review (Mapping[str, Any] | None)
- fable_pyculator.scenario_rules.enumerate_domain(controls, baseline, rules, *, table_status=None, mode='exploratory')[source]
Enumerate a small control domain and count rule outcomes.
- Parameters:
controls (Sequence[Mapping[str, Any]])
baseline (Mapping[str, Any])
rules (Iterable[ScenarioRule])
table_status (Mapping[str, Any] | None)
mode (str)
- Return type:
dict[str, Any]
- fable_pyculator.scenario_rules.evaluate_scenario(selections, rules, *, table_status=None, mode='exploratory')[source]
Evaluate one scenario under approved, exploratory, or draft-enforced semantics.
- Parameters:
selections (Mapping[str, Any])
rules (Iterable[ScenarioRule])
table_status (Mapping[str, Any] | None)
mode (str)
- Return type:
- fable_pyculator.scenario_rules.load_rule_registry(path)[source]
Load the YAML rule registry into typed rules.
- Parameters:
path (str | Path)
- Return type:
tuple[ScenarioRule, …]
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:
version (int)
bundle_id (str)
workbook_version (str)
scenarios (tuple[ScenarioCase, ...])
render (ScenarioBundleRenderOptions)
description (str | None)
- 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)
- 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:
bundle (ScenarioBundle)
render (ScenarioBundleRenderOptions)
scenario_results (dict[str, NotebookLoopResult])
- 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:
- fable_pyculator.scenarios.load_scenario_bundle(path)[source]
Load a scenario bundle from JSON, YAML, or YML.
- Parameters:
path (str | Path)
- Return type:
- 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
bundleusing 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:
- fable_pyculator.scenarios.validate_scenario_bundle(bundle, spec)[source]
Validate bundle ids and selection-control values against a FABLE spec.
- Parameters:
bundle (ScenarioBundle)
spec (FableCalculatorSpec)
- Return type:
- 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:
result (NotebookLoopResult)
scenario (ScenarioCase)
scenario_dir (str | Path)
output_dir (str | Path)
- 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:
run_result (ScenarioBundleRunResult)
paths (ScenarioBundleArtifactPaths)
- Return type:
dict[str, Any]
Optional Web Portal Helpers
Artifact discovery for the FABLE Pyculator web portal.
The portal is a presentation layer over the same ignored local artifacts the notebook helpers use. This module names each artifact path, reports whether it exists, and materializes the approved compressed generated-model artifact when a local working copy is missing.
- class fable_pyculator.web.artifacts.ArtifactPaths(version, workbook, generated_model, compressed_model, checksum, contract, inference_result, validation_scenario, evaluation_report, generated_values, validation_summary, output_dir)[source]
Every local path the portal may read for one FABLE workbook version.
- Parameters:
version (str)
workbook (Path)
generated_model (Path)
compressed_model (Path)
checksum (Path)
contract (Path)
inference_result (Path)
validation_scenario (Path)
evaluation_report (Path)
generated_values (Path)
validation_summary (Path)
output_dir (Path)
- fable_pyculator.web.artifacts.artifact_paths(repo_root, version)[source]
Return the conventional artifact paths for one workbook version.
Paths follow the tracked artifact and ignored local-artifact conventions documented in
examples/fable_<version>/README.mdanddocs/guides/generated-model-artifacts.rst.- Parameters:
repo_root (str | Path)
version (str)
- Return type:
- fable_pyculator.web.artifacts.artifact_summary(repo_root, version)[source]
Summarize whether a version can be prepared, validated, or run.
A version is preparable when the source workbook and either a decompressed or approved compressed generated model are present. Nothing is guessed: every missing file is named.
- Parameters:
repo_root (str | Path)
version (str)
- Return type:
dict[str, Any]
- fable_pyculator.web.artifacts.bundle_summaries(repo_root)[source]
Return the tracked scenario-bundle examples as compact summaries.
Bad or partially written bundles are reported with an
errorfield rather than being hidden.- Parameters:
repo_root (str | Path)
- Return type:
list[dict[str, Any]]
- fable_pyculator.web.artifacts.file_info(path)[source]
Return compact existence, size, and modification metadata for a path.
- Parameters:
path (Path)
- Return type:
dict[str, Any]
- fable_pyculator.web.artifacts.materialize_generated_model(repo_root, version, *, force=False)[source]
Decompress the approved generated-model archive into the ignored working path.
The operation is atomic: the archive is streamed to a sibling temporary file and then replaced. It never overwrites an existing working model unless
forceis true.- Parameters:
repo_root (str | Path)
version (str)
force (bool)
- Return type:
dict[str, Any]
- fable_pyculator.web.artifacts.model_checksum_status(repo_root, version)[source]
Compare the local working model with the tracked approved checksum.
- Parameters:
repo_root (str | Path)
version (str)
- Return type:
dict[str, Any]
JSON serialization for prepared FABLE specs.
Building a spec from a real FABLE workbook is expensive. The portal prepares it once, writes the typed declaration to a cache under the ignored runtime directory, and reloads it on the next start. Only declaration metadata is cached; generated values are never cached here.
- fable_pyculator.web.spec_io.spec_from_payload(payload)[source]
Reconstruct a spec from
spec_to_payload()output.- Parameters:
payload (dict[str, Any])
- Return type:
- fable_pyculator.web.spec_io.spec_summary(spec)[source]
Return the compact declaration metadata the browser needs.
- Parameters:
spec (FableCalculatorSpec)
- Return type:
dict[str, Any]
- fable_pyculator.web.spec_io.spec_to_payload(spec)[source]
Serialize a spec to a stable JSON-ready payload.
- Parameters:
spec (FableCalculatorSpec)
- Return type:
dict[str, Any]
Persistent chat sessions for the FABLE portal assistant.
Chats are small JSON records under the ignored runtime directory. The browser can list, reopen, and delete them across page reloads and service restarts. Each record keeps the OpenCode session id so a resumed chat continues the same local agent conversation.
- class fable_pyculator.web.chats.ChatRecord(chat_id, title, created_at, updated_at, messages=<factory>, agent_session=None, run_id=None, pinned=False, archived=False)[source]
One persisted assistant conversation.
- Parameters:
chat_id (str)
title (str)
created_at (str)
updated_at (str)
messages (list[dict[str, Any]])
agent_session (str | None)
run_id (str | None)
pinned (bool)
archived (bool)
- class fable_pyculator.web.chats.ChatStore(directory)[source]
Thread-safe JSON chat store under one directory.
- Parameters:
directory (str | Path)
- append_message(chat_id, *, role, content, actions=None, run_id=None)[source]
Append one message and persist the chat.
- Parameters:
chat_id (str)
role (str)
content (str)
actions (list[dict[str, str]] | None)
run_id (str | None)
- Return type:
- create(*, run_id=None, title='New chat')[source]
Create and persist an empty chat.
- Parameters:
run_id (str | None)
title (str)
- Return type:
- delete(chat_id)[source]
Delete one chat; return whether it existed.
- Parameters:
chat_id (str)
- Return type:
bool
- list(*, limit=100, include_archived=False, query=None)[source]
Return chat summaries, pinned first and newest first within each group.
- Parameters:
limit (int)
include_archived (bool)
query (str | None)
- Return type:
list[dict[str, Any]]
- set_metadata(chat_id, *, title=None, pinned=None, archived=None)[source]
Update chat title, pin, and archive state.
- Parameters:
chat_id (str)
title (str | None)
pinned (bool | None)
archived (bool | None)
- Return type:
- fable_pyculator.web.chats.auto_title(user_message, assistant_message=None)[source]
Choose a concise title from the first exchange.
Short or generic user prompts fall back to the first meaningful assistant line.
- Parameters:
user_message (str)
assistant_message (str | None)
- Return type:
str
Compiled grounding sheet for the portal assistant.
The assistant is required to read this document and the files it lists before answering a new chat session. It contains only facts the portal can verify from local configuration, artifacts, prepared specs, and saved runs, plus explicit pointers to the FABLE Pyculator and Modelwright documentation and source code.
- class fable_pyculator.web.cheatsheet.CheatSheet(path, markdown, generated_at, required_reading)[source]
One compiled grounding document.
- Parameters:
path (Path)
markdown (str)
generated_at (str)
required_reading (tuple[str, ...])
- fable_pyculator.web.cheatsheet.build_cheat_sheet(*, repo_root, artifacts, prepared_summaries, runs, generated_at)[source]
Return the markdown grounding sheet and the absolute required-reading paths.
- Parameters:
repo_root (Path)
artifacts (list[dict[str, Any]])
prepared_summaries (dict[str, dict[str, Any]])
runs (list[dict[str, Any]])
generated_at (str)
- Return type:
tuple[str, list[str]]
- fable_pyculator.web.cheatsheet.ensure_cheat_sheet(*, repo_root, runtime_dir, artifacts, prepared_summaries, runs)[source]
Build, write, and return the current grounding sheet.
- Parameters:
repo_root (Path)
runtime_dir (Path)
artifacts (list[dict[str, Any]])
prepared_summaries (dict[str, dict[str, Any]])
runs (list[dict[str, Any]])
- Return type:
- fable_pyculator.web.cheatsheet.modelwright_root(repo_root)[source]
Resolve the local Modelwright checkout used for documentation and source pointers.
- Parameters:
repo_root (Path)
- Return type:
Path | None
Grounding evaluations for the FABLE portal assistant.
The structural checks always run and verify that the generated cheat sheet points at real, existing docs/source files and contains the expected API facts. The live checks are opt-in: they run the installed OpenCode CLI with the same new-session grounding prompt and check that each answer cites an expected source and contains the expected facts.
- class fable_pyculator.web.grounding_evals.GroundingCase(case_id, question, expected_paths, required_terms, forbidden_terms=())[source]
One assistant grounding question and its required evidence.
- Parameters:
case_id (str)
question (str)
expected_paths (tuple[str, ...])
required_terms (tuple[str, ...])
forbidden_terms (tuple[str, ...])
- class fable_pyculator.web.grounding_evals.GroundingCaseResult(case_id, status, seconds=0.0, failures=<factory>, response='', actions=<factory>)[source]
Outcome of one structural or live grounding case.
- Parameters:
case_id (str)
status (str)
seconds (float)
failures (list[str])
response (str)
actions (list[dict[str, str]])
- class fable_pyculator.web.grounding_evals.GroundingEvalSummary(repo_root, cheat_sheet_path, structural, cases, live)[source]
Combined structural and optional live evaluation summary.
- Parameters:
repo_root (str)
cheat_sheet_path (str)
structural (list[str])
cases (list[GroundingCaseResult])
live (bool)
- property passed: bool
Return whether every check passed.
- fable_pyculator.web.grounding_evals.run_grounding_evals(repo_root, *, runtime_dir=None, cases=(GroundingCase(case_id='notebook_signature', question='What is the exact signature of build_notebook_spec in the current fable-pyculator source, including the optional headline-curation flag? Cite the exact file path.', expected_paths=('src/fable_pyculator/notebook.py',), required_terms=('build_notebook_spec', 'strict_headlines'), forbidden_terms=('no optional', 'does not exist')), GroundingCase(case_id='modelwright_facade', question='Which Modelwright module defines ModelFacade, and what does it wrap? Cite the exact file path.', expected_paths=('src/modelwright/wrappers.py',), required_terms=('ModelFacade', 'generated'), forbidden_terms=()), GroundingCase(case_id='fable_2024_water', question='Which default FABLE headline series is unavailable in the 2024 Canada workbook, and why? Cite the workbook table name and a file path you used.', expected_paths=('docs/guides/workbook-structure.rst', 'src/fable_pyculator/discovery.py'), required_terms=('TotalResultsWF', '2024'), forbidden_terms=()), GroundingCase(case_id='portal_read_only', question='Does the portal recompute FABLE results in the browser? Answer directly and cite a file path.', expected_paths=('docs/guides/web-portal.rst',), required_terms=('does not', 'recompute'), forbidden_terms=()), GroundingCase(case_id='github_issue_filing', question="How would you file a bug report for this repository on the user's behalf? Which template, issue level, labels, validation command, and gh command would you use? Cite the workflow doc and template path.", expected_paths=('docs/guides/github-issue-workflow.rst', '.github/ISSUE_TEMPLATE/task.md'), required_terms=('gh issue create', '--body-file', 'check_issue_body.py', 'bug', 'task'), forbidden_terms=('invent the issue number', 'without confirmation'))), include_live=False, timeout=600.0)[source]
Run structural checks and, when requested, live assistant evaluations.
- Parameters:
repo_root (str | Path)
runtime_dir (str | Path | None)
cases (tuple[GroundingCase, ...])
include_live (bool)
timeout (float)
- Return type:
Runtime state, preparation, and scenario execution for the FABLE web portal.
The service is deliberately a thin presentation layer over the notebook APIs. Model execution and workbook discovery happen in background jobs; every response is built from a real run or a real artifact, never from browser-only state.
- class fable_pyculator.web.service.Job(job_id, kind, status='queued', progress=0, message='queued', result=None, error=None, created_at=<factory>, started_at=None, finished_at=None)[source]
One background preparation or scenario-run job.
- Parameters:
job_id (str)
kind (str)
status (Literal['queued', 'running', 'ok', 'error'])
progress (int)
message (str)
result (Any)
error (str | None)
created_at (str)
started_at (str | None)
finished_at (str | None)
- class fable_pyculator.web.service.JobManager(*, keep=50)[source]
Run callables on daemon threads and expose pollable status snapshots.
- Parameters:
keep (int)
- class fable_pyculator.web.service.PortalConfig(repo_root=<factory>, runtime_dir=None, versions=('2021', '2024', '2020'), allow_agent=False, agent_command=('opencode', 'run', '--format', 'json', '--auto'), agent_model='opencode-go/deepseek-v4.1-flash', agent_timeout=600.0, auth_user=None, auth_password=None, history_retention_days=0, history_retention_dry_run=False, history_retention_interval_minutes=0, library_snapshot_interval_minutes=0, library_snapshot_keep=10, title='FABLE Pyculator')[source]
Portal configuration.
- Parameters:
repo_root (Path)
runtime_dir (Path | None)
versions (tuple[str, ...])
allow_agent (bool)
agent_command (tuple[str, ...])
agent_model (str | None)
agent_timeout (float)
auth_user (str | None)
auth_password (str | None)
history_retention_days (int)
history_retention_dry_run (bool)
history_retention_interval_minutes (int)
library_snapshot_interval_minutes (int)
library_snapshot_keep (int)
title (str)
- repo_root
Repository root containing
examples/andtmp/.- Type:
pathlib.Path
- runtime_dir
Ignored directory for prepared specs and saved runs.
- Type:
pathlib.Path | None
- versions
Workbook versions offered by the portal.
- Type:
tuple[str, …]
- allow_agent
Enable the optional local assistant.
- Type:
bool
- agent_command
Command prefix for the assistant CLI.
- Type:
tuple[str, …]
- agent_model
Optional model identifier passed to the assistant CLI.
- Type:
str | None
- agent_timeout
Assistant timeout in seconds.
- Type:
float
- title
Browser title and header label.
- Type:
str
- exception fable_pyculator.web.service.PortalError(message, *, status_code=400)[source]
A user-facing portal error with an HTTP status hint.
- Parameters:
message (str)
status_code (int)
- Return type:
None
- class fable_pyculator.web.service.PortalState(config)[source]
Shared state for artifact summaries, prepared models, saved runs, and jobs.
- Parameters:
config (PortalConfig)
- artifact(version)[source]
Return one artifact summary with its validation state.
- Parameters:
version (str)
- Return type:
dict[str, Any]
- artifacts()[source]
Return one artifact summary per configured version.
- Return type:
list[dict[str, Any]]
- assistant_context(run_id)[source]
Build a compact context object for the optional local assistant.
- Parameters:
run_id (str | None)
- Return type:
dict[str, Any]
- compare(run_ids)[source]
Compare two or more saved runs by headline series and selected inputs.
- Parameters:
run_ids (Sequence[str])
- Return type:
dict[str, Any]
- create_chat(*, run_id=None)[source]
Create a persistent assistant chat.
- Parameters:
run_id (str | None)
- Return type:
dict[str, Any]
- create_library_snapshot(source='manual')[source]
Write one immutable library snapshot and retain the newest configured count.
- Parameters:
source (str)
- Return type:
dict[str, Any]
- delete_chat(chat_id)[source]
Delete one persistent chat.
- Parameters:
chat_id (str)
- Return type:
dict[str, Any]
- delete_library_snapshot(name)[source]
Delete one stored snapshot.
- Parameters:
name (str)
- Return type:
dict[str, Any]
- delete_optimization_preset(name)[source]
Delete one shared Optimization preset by name.
- Parameters:
name (str)
- Return type:
dict[str, Any]
- delete_timeline_view(name)[source]
Delete one shared timeline filter view.
- Parameters:
name (str)
- Return type:
dict[str, Any]
- diff_library_snapshot(name, mode='merge')[source]
Return an exact read-only diff between one snapshot and the current library.
- Parameters:
name (str)
mode (str)
- Return type:
dict[str, Any]
- ensure_cheat_sheet()[source]
Regenerate the compiled assistant grounding sheet from current portal state.
- Return type:
- export_chat(chat_id)[source]
Return a Markdown export of one chat.
- Parameters:
chat_id (str)
- Return type:
str
- get_chat(chat_id)[source]
Return one persistent chat.
- Parameters:
chat_id (str)
- Return type:
dict[str, Any]
- library_snapshot(name)[source]
Return one stored snapshot bundle.
- Parameters:
name (str)
- Return type:
dict[str, Any]
- library_snapshot_policy()[source]
Return snapshot scheduling and retention policy metadata.
- Return type:
dict[str, Any]
- library_snapshots(limit=20)[source]
Return recent snapshot metadata, newest first.
- Parameters:
limit (int)
- Return type:
list[dict[str, Any]]
- list_chats(*, include_archived=False, query=None)[source]
Return persistent chat summaries, pinned first and newest first.
- Parameters:
include_archived (bool)
query (str | None)
- Return type:
list[dict[str, Any]]
- optimization_frontier(version)[source]
Return one tracked exact frontier artifact for the browser.
- Parameters:
version (str)
- Return type:
dict[str, Any]
- optimization_frontiers()[source]
Return summaries of tracked exact frontier artifacts.
- Return type:
list[dict[str, Any]]
- optimization_library()[source]
Return a portable backup of shared presets and timeline views.
- Return type:
dict[str, Any]
- optimization_presets()[source]
Return the shared Optimization preset library.
- Return type:
list[dict[str, Any]]
- prepare(version, report)[source]
Materialize, discover, load, and cache one version.
The operation is guarded so two analyst tabs do not decompress or build the same model at the same time. A valid cache avoids rebuilding the expensive workbook spec after a restart.
- Parameters:
version (str)
report (Callable[[int, str], None])
- Return type:
dict[str, Any]
- prepare_job(version)[source]
Start a background preparation job for one version.
- Parameters:
version (str)
- Return type:
- prune_optimization_history(days=90, dry_run=False, *, source='manual')[source]
Remove history events older than the retention window, keeping each latest event.
- Parameters:
days (int)
dry_run (bool)
source (str)
- Return type:
dict[str, Any]
- restore_library_snapshot(name, *, mode='merge', dry_run=True)[source]
Preview or apply a restore directly from a stored snapshot.
- Parameters:
name (str)
mode (str)
dry_run (bool)
- Return type:
dict[str, Any]
- restore_optimization_library(presets, timeline_views, *, mode='merge', dry_run=True)[source]
Preview or apply a shared-library backup in merge or replace mode.
- Parameters:
presets (Any)
timeline_views (Any)
mode (str)
dry_run (bool)
- Return type:
dict[str, Any]
- retention_runs(limit=20)[source]
Return recent retention maintenance records, newest first.
- Parameters:
limit (int)
- Return type:
list[dict[str, Any]]
- retention_status()[source]
Return the startup retention policy and the last recorded result.
- Return type:
dict[str, Any]
- run_job(*, version, name, selections, output_table_names=None, headline_series_names=None, column_flavour_tags=None, include_context_columns=True, horizon=2050)[source]
Start a background scenario run.
- Parameters:
version (str)
name (str)
selections (Mapping[str, object])
output_table_names (Sequence[str] | None)
headline_series_names (Sequence[str] | None)
column_flavour_tags (str | Sequence[str] | None)
include_context_columns (bool)
horizon (int)
- Return type:
- run_scenario(*, version, name, selections, output_table_names=None, headline_series_names=None, column_flavour_tags=None, include_context_columns=True, horizon=2050, report=None)[source]
Run one scenario and persist its summary and table payloads.
- Parameters:
version (str)
name (str)
selections (Mapping[str, object])
output_table_names (Sequence[str] | None)
headline_series_names (Sequence[str] | None)
column_flavour_tags (str | Sequence[str] | None)
include_context_columns (bool)
horizon (int)
report (Callable[[int, str], None] | None)
- Return type:
dict[str, Any]
- runs()[source]
Return saved runs, newest first, without loading table files.
- Return type:
list[dict[str, Any]]
- property runtime_dir: Path
Return the resolved runtime directory.
- save_optimization_preset(name, state, saved_at=None, *, author=None, note=None, review_status=None)[source]
Create or replace one shared Optimization preset.
- Parameters:
name (str)
state (Mapping[str, Any])
saved_at (str | None)
author (str | None)
note (str | None)
review_status (str | None)
- Return type:
dict[str, Any]
- save_timeline_view(name, timeline_filter, saved_at=None, *, author=None, note=None, review_status=None)[source]
Create or replace one shared timeline filter view.
- Parameters:
name (str)
timeline_filter (Mapping[str, Any])
saved_at (str | None)
author (str | None)
note (str | None)
review_status (str | None)
- Return type:
dict[str, Any]
- spec(version)[source]
Return the compact prepared spec, or a 409 when preparation is not done.
- Parameters:
version (str)
- Return type:
dict[str, Any]
- status(version)[source]
Return in-memory preparation status for one version.
- Parameters:
version (str)
- Return type:
dict[str, Any]
- table(run_id, table_name)[source]
Return one saved table payload.
- Parameters:
run_id (str)
table_name (str)
- Return type:
dict[str, Any]
- timeline_views()[source]
Return the shared timeline filter library.
- Return type:
list[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:
scenario_paths (ScenarioBundleArtifactPaths)
matrix_path (Path)
workflow_template_path (Path)
matrix_summary_path (Path)
- 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:
bundle (ScenarioBundle)
matrix (dict[str, Any])
workflow_template (dict[str, Any])
case_count (int)
- class fable_pyculator.scenario_workflows.ScenarioBundleFreshForgePaths(scenario_paths, workflow_path, run_summary_path)[source]
Ignored local paths for FreshForge-backed scenario-bundle orchestration.
- Parameters:
scenario_paths (ScenarioBundleArtifactPaths)
workflow_path (Path)
run_summary_path (Path)
- 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:
bundle (ScenarioBundle)
paths (ScenarioBundleFreshForgePaths)
workflow (dict[str, Any])
run_namespace (str | None)
- 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:
- 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:
- fable_pyculator.scenario_workflows.plan_scenario_bundle_freshforge_matrix(plan)[source]
Plan a prepared FreshForge scenario-bundle matrix.
- Parameters:
- 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)
repo_root (str | Path)
workbook_id (str | None)
module_name (str | None)
spec (Any | None)
- Return type:
- 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:
- fable_pyculator.scenario_workflows.run_scenario_bundle_freshforge_matrix(plan, *, registry=None, fail_fast=False)[source]
Run a prepared FreshForge scenario-bundle matrix.
- Parameters:
registry (Any | None)
fail_fast (bool)
- 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:
plan (ScenarioBundleFreshForgePlan)
run_namespace (str | None)
registry (Any | None)
- 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:
run_result (Any)
path (str | Path | None)
- 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:
run_result (Any)
paths (ScenarioBundleFreshForgePaths)
run_namespace (str | None)
path (str | Path | None)
- 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, ...])
- 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, ...])
- 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:
- 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:
- 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-planprepares the build workflow when the source workbook is available.freshforge-runadditionally executes that workflow through FreshForge and records a compact run summary. Missing local artifacts are reported as skipped evidence unlessrequire_artifactsis 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:
- 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:
- fable_pyculator.benchmarks.write_fable_benchmark_matrix_evidence(summary, paths=None)[source]
Write compact FABLE-facing JSON and Markdown matrix evidence summaries.
- Parameters:
summary (FableBenchmarkMatrixEvidenceSummary)
paths (FableBenchmarkMatrixEvidencePaths | None)
- Return type:
dict[str, Any]
- fable_pyculator.benchmarks.write_fable_benchmark_summary(summary, paths=None)[source]
Write compact JSON and Markdown benchmark summaries.
- Parameters:
summary (FableBenchmarkRunSummary)
paths (FableBenchmarkRunPaths | None)
- 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, ...])
- fable_pyculator.validation.extract_validation_evidence(paths, *, workbook_version, require_artifacts=False)[source]
Extract sanitized evidence from existing local artifacts.
- Parameters:
paths (ValidationEvidencePaths)
workbook_version (str)
require_artifacts (bool)
- Return type:
- 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:
- fable_pyculator.validation.write_validation_evidence(summary, paths)[source]
Write compact JSON and Markdown validation-evidence summaries.
- Parameters:
summary (ValidationEvidenceSummary)
paths (ValidationEvidencePaths)
- 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)
- 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)
- 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.
- class fable_pyculator.strategy_comparison.OutputRefStrategyComparisonResult(workbook_version, paths, entries, notes=<factory>)[source]
Collection of compared FABLE output-ref strategies.
- Parameters:
workbook_version (str)
paths (OutputRefStrategyComparisonPaths)
entries (tuple[OutputRefStrategyComparisonEntry, ...])
notes (tuple[str, ...])
- 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)
- 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, ...])
- 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:
result (OutputRefStrategyComparisonResult)
matrix_path (str | Path | None)
- Return type:
- 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:
- 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:
- 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 longfreshforge runafter 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:
paths (FableFreshForgeBuildPaths)
workdir (str | Path)
workflow_id (str)
name (str)
description (str)
module_name (str)
- 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_tagsaccepts exact tags, theDATA/OUTPUTfamily aliases, and trailing wildcard patterns such asOUTPUT-*. PassingNoneselects 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:
- 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_rootso notebooks can run from VSCode’s notebook directory or from the repository root while still writing artifacts to the same ignoredtmp/location.- Parameters:
repo_root (str | Path)
workbook_path (str | Path)
artifact_dir (str | Path)
workflow_filename (str)
- Return type:
- 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:
- 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:
- 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]
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.