Supported Surface

Use abacus.scenarios for supported Python and CLI scenario workflows. The experimental abacus-dashboard application is deprecated. It is not a recommended entry point.

Legacy dashboard app-layer imports under abacus.scenario_planner remain as advisory compatibility facades in this checkout. Their warnings identify abacus_dashboard.* paths; those paths belong to the deprecated application.

Estimator prerequisites

The named FE and CRE presets support historical and manual scenarios for the complete set of fitted units; CRE also retains its frozen fitted summaries. They do not support FixedBudgetOptimizedScenarioSpec. The RE preset remains release-gated. Check the estimator support matrix before choosing a scenario type.

Dashboard compatibility code does not add estimator support.

Recommended entry points

Use these entry points in preference order.

Entry point Use it when you want to Notes
abacus.scenarios.ScenarioPlanner evaluate or compare scenarios from Python Preferred statistical API for notebooks, scripts, and testable planning flows
python -m abacus.scenarios evaluate a YAML recipe against a fitted run Writes an immutable, checksummed evidence bundle under the fitted run
abacus.scenarios.run_scenario_recipe(...) run the same retained recipe workflow from Python Preferred scripted handoff when the fitted model is already saved
abacus.scenarios.WorkspaceService work with saved workspaces programmatically Library-facing surface for cloning, saving, evaluating, sweeping, and exporting

Advanced integration surfaces

Abacus exposes lower-level statistical orchestration objects such as:

  • ThreadedScenarioPlannerJobRunner
  • SynchronousScenarioPlannerJobRunner
  • WorkspaceStore

These are public, but they are more implementation-shaped than the recommended entry points above. Use them only when you need to override job-runner or storage behaviour.

Results directory contract

The dashboard-specific sections below record the deprecated prototype, including its former compatibility plans. They do not recommend launching it or establish a future release commitment. The statistical recipe and workspace APIs remain available through abacus.scenarios.

The dashboard launcher and load_workspace_bundle(...) expect a fitted run directory, not raw modelling inputs.

The run directory must include:

Requirement Why it matters
run_manifest.json Abacus uses it to locate the config and saved artefacts
a fit-stage idata artefact Abacus attaches the saved posterior to the rebuilt model

When metadata-stage config artefacts are present, Abacus prefers those in-run files when rebuilding the saved PanelMMM:

  • 00_run_metadata/config.resolved.yaml
  • 00_run_metadata/config.original.yaml
  • the copied config file under 00_run_metadata/

Only when those in-run config artefacts are absent does the planner fall back to run_manifest.json["config_path"].

That makes the compatibility loader more portable when the original config path is no longer available, but it does not guarantee full relocation across machines. The chosen config can still reference dataset files outside the run directory.

The planner can also load these optional optimisation artefacts when they are present:

  • 70_optimisation/budget_response_curves.csv
  • 70_optimisation/budget_bounds_audit.csv

When these files are available, the app can show saved saturation-reference response-curve and bounds-audit views.

Companion dashboard handoff contract

A retained recipe writes scenario_payload.json for machine consumers. The companion abacus-dashboard package must:

  1. reject a missing or unknown contract_version;
  2. compare that value with SCENARIO_CONTRACT_VERSION before rendering;
  3. preserve all five record collections: totals, channels, contributions_over_time, allocations, and metadata;
  4. use scenario_validation.json, estimator_manifest.yaml, and scenario_artifact_manifest.json as provenance and integrity evidence; and
  5. label the outputs as posterior media contributions, not total outcomes, profits, causal effects, or model approval.

Abacus owns this statistical payload. The companion package owns rendering, interaction, and any application persistence. This repository does not add or change dashboard UI code as part of the recipe workflow.

The companion package also provides a read-only bundle viewer. It verifies the manifest checksums for every declared artifact and requires agreement among the payload, validation record, and estimator manifest before it renders the five collections. It rejects tampered or incompatible bundles rather than attempting a partial display.

What the app persists

The workspace app stores its own planning state under the fitted run directory:

Path Contents
scenario_planner/workspaces/<workspace_id>.json full persisted workspace state
scenario_planner/workspaces/<workspace_id>.manifest.json compact workspace manifest
scenario_planner/cache/cache_index.json evaluation cache index
scenario_planner/cache/evaluations/ cached evaluated scenarios
scenario_planner/exports/<workspace_id>/<export_id>/ export bundle contents
scenario_planner/exports/<workspace_id>/<export_id>.zip zipped export bundle
scenario_planner/recipes/<recipe>_<timestamp>/ immutable YAML-recipe evidence bundle

Workspaces persist:

  • workspace metadata such as name, owner, tags, and notes
  • draft metadata such as scenario owner, workflow status, approvals, pinning, notes, and tags
  • evaluated scenarios
  • sensitivity runs
  • revision history
  • job history
  • cache metadata

Background jobs in the dashboard app

The dashboard app launches with ThreadedScenarioPlannerJobRunner.

In this beta:

  • draft evaluation runs as a queued background job
  • sensitivity sweeps run as queued background jobs
  • export remains synchronous, but Abacus still records it in job history

The UI currently tracks one active planner job at a time. Wait for the current evaluation or sweep to finish before starting another one from the app.

Dashboard scope and current limits

The dashboard app scope is:

  • local use against fitted run directories
  • file-backed workspace persistence inside the run directory
  • interactive drafting, evaluation, comparison, sensitivity sweeps, and export

Current limits to keep in mind:

  • the app does not fit or refit PanelMMM
  • the launcher starts Dash’s built-in server for local evaluation
  • the UI does not yet manage multiple active planner jobs at the same time
  • legacy abacus.scenario_planner dashboard app-layer imports are advisory compatibility facades, not the preferred app API

Legacy removal criteria

No legacy dashboard app-layer compatibility facade under abacus.scenario_planner will be removed before Abacus 4.0. Removal also requires:

  • a documented abacus-dashboard release and install path
  • passing dashboard smoke checks against the supported Abacus scenario contract
  • zero known internal imports using legacy dashboard paths

Next pages