brushline.monitoring.value

Coverage and approximate value of information.

class brushline.monitoring.value.MonitoringCandidate(*, candidate_id: Annotated[str, MinLen(min_length=1)], span_id: Annotated[str, MinLen(min_length=1)], cost: Annotated[float, Ge(ge=0)], coverage: Annotated[float, Ge(ge=0), Le(le=1)], uncertainty: Annotated[float, Ge(ge=0), Le(le=1)], expected_loss_reduction: Annotated[float, Ge(ge=0)])[source]

Bases: BaseModel

One monitoring candidate.

Parameters:
  • candidate_id (str) – Candidate id.

  • span_id (str) – Span.

  • cost (float) – Cost.

  • coverage (float) – Coverage from 0 to 1.

  • uncertainty (float) – Current uncertainty.

  • expected_loss_reduction (float) – Expected decision-loss reduction.

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

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

class brushline.monitoring.value.MonitoringChoice(*, candidate_id: str, span_id: str, cost: Annotated[float, Ge(ge=0)], coverage: Annotated[float, Ge(ge=0), Le(le=1)], expected_loss_reduction: float, value_of_information: float)[source]

Bases: BaseModel

One selected candidate.

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

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

class brushline.monitoring.value.MonitoringValue(*, schema_version: Literal['brushline.monitoring-value.v1'] = 'brushline.monitoring-value.v1', report_id: str, choices: list[MonitoringChoice], total_cost: Annotated[float, Ge(ge=0)], expected_loss_reduction: float, value_of_information: float, regret_per_dollar: float, feasible: bool, created_utc: datetime)[source]

Bases: BaseModel

A value-of-information report.

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

  • report_id (str) – Report id.

  • choices (list of MonitoringChoice) – Selected choices.

  • total_cost (float) – Total cost.

  • expected_loss_reduction (float) – Sum of reductions.

  • value_of_information (float) – Reduction minus cost.

  • regret_per_dollar (float) – Reduction divided by cost.

  • feasible (bool) – Budget satisfied.

  • 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.monitoring.value.fixed_calendar(candidates: list[MonitoringCandidate], *, report_id: str, budget: float, created_utc: datetime | None = None) → MonitoringValue[source]

Select a deterministic fixed-calendar baseline.

Parameters:
  • candidates (list of MonitoringCandidate) – Candidates.

  • report_id (str) – Report id.

  • budget (float) – Budget.

  • created_utc (datetime, optional) – Creation time.

Returns:

MonitoringValue – Fixed-calendar selection.

brushline.monitoring.value.select_monitoring(candidates: list[MonitoringCandidate], *, report_id: str, budget: float, value_per_loss: float = 1.0, created_utc: datetime | None = None) → MonitoringValue[source]

Select candidates greedily by net value and budget.

Parameters:
  • candidates (list of MonitoringCandidate) – Candidates.

  • report_id (str) – Report id.

  • budget (float) – Budget.

  • value_per_loss (float, optional) – Value per loss unit.

  • created_utc (datetime, optional) – Creation time.

Returns:

MonitoringValue – Selection and regret-per-dollar evidence.