brushline.strategic.scenario

The versioned scenario record, canonical digests, replay evidence, and scenario archive.

Strategic scenario archive and reproducibility record.

class brushline.strategic.scenario.ScenarioArchive(*, schema_version: ~typing.Literal['brushline.strategic-scenario-archive.v1'] = 'brushline.strategic-scenario-archive.v1', scenarios: list[~brushline.strategic.scenario.StrategicScenario] = <factory>, created_utc: ~datetime.datetime, created_by: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)])[source]

Bases: BaseModel

A versioned set of strategic scenarios.

Parameters:
  • schema_version ({"brushline.strategic-scenario-archive.v1"}) – Schema version.

  • scenarios (list of StrategicScenario) – Scenarios.

  • created_utc (datetime) – Timezone-aware time.

  • created_by (str) – Creator.

model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

exception brushline.strategic.scenario.ScenarioError[source]

Bases: ValueError

Raised when scenario inputs or replay are inconsistent.

class brushline.strategic.scenario.ScenarioReplay(*, scenario_id: str, ok: bool, errors: list[str] = <factory>, portfolio_digest: str | None = None, report_digest: str | None = None)[source]

Bases: BaseModel

A verified scenario replay.

Parameters:
  • scenario_id (str) – Scenario id.

  • ok (bool) – Whether the artifacts match.

  • errors (list of str) – Replay errors.

  • portfolio_digest (str or None) – Recomputed portfolio digest.

  • report_digest (str or None) – Recomputed report digest.

model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class brushline.strategic.scenario.ScenarioVersions(*, dataset_version: Annotated[str, MinLen(min_length=1)], dataset_digest: Annotated[str, MinLen(min_length=1)], state_model: Annotated[str, MinLen(min_length=1)], growth_model: Annotated[str, MinLen(min_length=1)], treatment_model: Annotated[str, MinLen(min_length=1)], adapter: Annotated[str, MinLen(min_length=1)], brushline_version: Annotated[str, MinLen(min_length=1)])[source]

Bases: BaseModel

Versions that identify a strategic scenario.

Parameters:
  • dataset_version (str) – Dataset version.

  • dataset_digest (str) – Dataset content digest.

  • state_model (str) – State model version.

  • growth_model (str) – Growth model version.

  • treatment_model (str) – Treatment model version.

  • adapter (str) – Adapter version.

  • brushline_version (str) – Brushline version.

model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class brushline.strategic.scenario.StrategicScenario(*, schema_version: Literal['brushline.strategic-scenario.v1'] = 'brushline.strategic-scenario.v1', scenario_id: str, instance_id: str, versions: ScenarioVersions, configuration: dict[str, Any], config_digest: str, seed: int, budget: Annotated[int, Ge(ge=0)], horizon_years: Annotated[int, Ge(ge=1)], portfolio_id: str, report_id: str, portfolio_path: str, report_path: str, archive_path: str | None = None, portfolio_digest: str, report_digest: str, created_utc: datetime)[source]

Bases: BaseModel

A reproducible strategic scenario record.

Parameters:
  • schema_version ({"brushline.strategic-scenario.v1"}) – Schema version.

  • scenario_id (str) – Scenario id.

  • instance_id (str) – Instance id.

  • versions (ScenarioVersions) – Data/model/adapter versions.

  • configuration (dict) – Scenario configuration.

  • config_digest (str) – Canonical configuration digest.

  • seed (int) – Seed.

  • budget (int) – Search or planning budget.

  • horizon_years (int) – Horizon.

  • portfolio_id (str) – Portfolio id.

  • report_id (str) – Report id.

  • portfolio_path (str) – Portfolio artifact path.

  • report_path (str) – Report artifact path.

  • archive_path (str or None) – Optional P5 archive path.

  • portfolio_digest (str) – Canonical portfolio digest.

  • report_digest (str) – Canonical report digest.

  • created_utc (datetime) – Timezone-aware time.

model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

brushline.strategic.scenario.build_scenario(*, scenario_id: str, instance_id: str, versions: ScenarioVersions, configuration: dict[str, Any], portfolio: StrategicPortfolio, report: StrategicReport, seed: int, budget: int, horizon_years: int, portfolio_path: str, report_path: str, archive_path: str | None = None, created_utc: datetime | None = None) → StrategicScenario[source]

Build a scenario with canonical configuration, portfolio, and report digests.

Parameters:
  • scenario_id (str) – Scenario id.

  • instance_id (str) – Instance id.

  • versions (ScenarioVersions) – Versions.

  • configuration (dict) – Configuration.

  • portfolio (StrategicPortfolio) – Portfolio.

  • report (StrategicReport) – Report.

  • seed (int) – Seed.

  • budget (int) – Budget.

  • horizon_years (int) – Horizon.

  • portfolio_path (str) – Portfolio path.

  • report_path (str) – Report path.

  • archive_path (str or None, optional) – P5 archive path.

  • created_utc (datetime, optional) – Creation time.

Returns:

StrategicScenario – Scenario record.

brushline.strategic.scenario.canonical_digest(value: object) → str[source]

Return a canonical SHA-256 digest of a JSON-like value.

Parameters:

value (object) – JSON-like value.

Returns:

str – Hex digest.

brushline.strategic.scenario.load_scenario(path: str | Path) → StrategicScenario[source]

Load a scenario record.

Parameters:

path (str or Path) – Source.

Returns:

StrategicScenario – Scenario.

brushline.strategic.scenario.load_scenario_archive(path: str | Path) → ScenarioArchive[source]

Load and validate a scenario archive.

Parameters:

path (str or Path) – Source.

Returns:

ScenarioArchive – Archive.

brushline.strategic.scenario.replay_scenario(scenario: StrategicScenario, *, portfolio: StrategicPortfolio | None, report: StrategicReport | None) → ScenarioReplay[source]

Verify that reconstructed artifacts match the scenario record.

Parameters:
Returns:

ScenarioReplay – Match evidence. Missing artifacts are errors.

brushline.strategic.scenario.validate_scenario_archive(archive: ScenarioArchive) → ContractValidation[source]

Validate duplicate scenario ids and record references.

Parameters:

archive (ScenarioArchive) – Archive.

Returns:

ContractValidation – Errors and counts.

brushline.strategic.scenario.write_scenario(scenario: StrategicScenario, path: str | Path) → Path[source]

Write a scenario record as JSON.

Parameters:
Returns:

Path – Written path.

brushline.strategic.scenario.write_scenario_archive(archive: ScenarioArchive, path: str | Path) → Path[source]

Validate and write a scenario archive.

Parameters:
  • archive (ScenarioArchive) – Archive.

  • path (str or Path) – Destination.

Returns:

Path – Written path.

Raises:

ScenarioError – When the archive is invalid.