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:
BaseModelA 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:
ValueErrorRaised 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:
BaseModelA 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:
BaseModelVersions 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:
BaseModelA 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:
scenario (StrategicScenario) – Scenario record.
portfolio (StrategicPortfolio or None) – Reconstructed portfolio.
report (StrategicReport or None) – Reconstructed report.
- 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:
scenario (StrategicScenario) – Scenario.
path (str or Path) – Destination.
- 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.