brushline.model artifacts
The plan, run, Pareto archive, operations timeline, and demo manifest contracts, plus the shared validation report.
Plan contract: the shared owner-contractor plan artifact.
A plan has a versioned header, a list of actions with a line-item cost build-up, and a list of named assumptions. The plan is the exchange object between the owner and the contractor; every number in it is traceable to a cost line, a rate, or a stated assumption.
- class brushline.model.plan.CostLine(*, category: Literal['labour', 'equipment', 'materials', 'travel', 'access', 'supervision', 'overhead', 'risk', 'other'], amount: Annotated[float, Ge(ge=0)], description: str = '', quantity: Annotated[float | None, Ge(ge=0)] = None, rate: Annotated[float | None, Ge(ge=0)] = None, currency: Annotated[str, MinLen(min_length=1)] = 'CAD', source: str = '')[source]
Bases:
BaseModelOne line in a plan’s cost build-up.
- Parameters:
category ({"labour", "equipment", "materials", "travel", "access", "supervision",) – “overhead”, “risk”, “other”} Cost category.
amount (float) – Line amount. Must be non-negative.
description (str, optional) – Human description.
quantity (float or None, optional) – Quantity, when the line is rate-based.
rate (float or None, optional) – Rate per unit, when the line is rate-based.
currency (str, optional) – Currency code. Defaults to
CAD.source (str, optional) – Rate or cost source.
- model_config = {'allow_inf_nan': False, 'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.model.plan.Plan(*, header: ~brushline.model.plan.PlanHeader, actions: ~typing.Annotated[list[~brushline.model.plan.PlanAction], ~annotated_types.MinLen(min_length=1)], assumptions: list[~brushline.model.plan.PlanAssumption] = <factory>)[source]
Bases:
BaseModelA complete plan artifact.
- Parameters:
header (PlanHeader) – Plan header.
actions (list of PlanAction) – Plan actions. At least one is required.
assumptions (list of PlanAssumption, optional) – Plan-level assumptions.
- model_config = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- property total_cost: float
Return the sum of every action’s cost.
- Returns:
float – Total plan cost in the plan currency.
- class brushline.model.plan.PlanAction(*, action_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], segment_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], year: ~typing.Annotated[int, ~annotated_types.Ge(ge=1900), ~annotated_types.Le(le=2200)], season: ~typing.Literal['spring', 'summer', 'fall', 'winter', 'any'], method: ~typing.Literal['manual', 'mechanical', 'chemical', 'mowing', 'grazing', 'prescribed_fire', 'other'], intensity: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1)], efficacy: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1)] = 0.5, cost_lines: ~typing.Annotated[list[~brushline.model.plan.CostLine], ~annotated_types.MinLen(min_length=1)], treatment_unit_id: str | None = None, quantity_ha: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)] = 0.0, quantity_km: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)] = 0.0, assumptions: list[str] = <factory>, risk_notes: str = '')[source]
Bases:
BaseModelOne treatment or monitoring action in a plan.
- Parameters:
action_id (str) – Stable action identifier.
segment_id (str) – Segment identifier.
year (int) – Action year.
season ({"spring", "summer", "fall", "winter", "any"}) – Action season.
method ({"manual", "mechanical", "chemical", "mowing", "grazing", "prescribed_fire", "other"}) – Treatment method.
intensity (float) – Intensity from 0 to 1.
efficacy (float, optional) – Expected efficacy from 0 to 1. Defaults to
0.5.cost_lines (list of CostLine) – Line-item cost build-up. At least one line is required.
treatment_unit_id (str or None, optional) – Owning treatment unit.
quantity_ha (float, optional) – Treated area in hectares. Defaults to
0.quantity_km (float, optional) – Treated corridor length in kilometres. Defaults to
0.assumptions (list of str, optional) – Assumptions specific to this action.
risk_notes (str, optional) – Risk notes.
- model_config = {'allow_inf_nan': False, 'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- property action_cost: float
Return the sum of the action’s cost lines.
- Returns:
float – Total action cost in the plan currency.
- class brushline.model.plan.PlanAssumption(*, assumption_id: Annotated[str, MinLen(min_length=1)], statement: Annotated[str, MinLen(min_length=1)], source: Annotated[str, MinLen(min_length=1)], impact: str = '')[source]
Bases:
BaseModelA named assumption in a plan.
- Parameters:
assumption_id (str) – Stable assumption identifier.
statement (str) – The assumption.
source (str) – Source or owner of the assumption.
impact (str, optional) – What the assumption affects.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.model.plan.PlanHeader(*, schema_version: ~typing.Literal['brushline.plan.v1'] = 'brushline.plan.v1', plan_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], version: ~typing.Annotated[int, ~annotated_types.Ge(ge=1)], status: ~typing.Literal['draft', 'proposed', 'approved', 'superseded'], scenario_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], dataset_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], data_version: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], model_versions: ~typing.Annotated[dict[str, str], ~annotated_types.MinLen(min_length=1)], configuration: dict[str, object] = <factory>, currency: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], created_utc: ~datetime.datetime, created_by: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], parent_plan_id: str | None = None, seed: int | None = None, service_standard_ids: list[str] = <factory>, notes: str = '')[source]
Bases:
BaseModelThe versioned header of a plan.
- Parameters:
plan_id (str) – Stable plan identifier.
version (int) – Plan version, starting at 1.
status ({"draft", "proposed", "approved", "superseded"}) – Plan status.
scenario_id (str) – Scenario identifier.
dataset_id (str) – Compiled dataset identifier.
data_version (str) – Data version or digest.
model_versions (dict of str to str) – Model ids and versions used by the plan.
configuration (dict of str to object) – Plan configuration.
currency (str) – Plan currency.
created_utc (datetime) – Timezone-aware creation time.
created_by (str) – Person, process, or agent that created the plan.
parent_plan_id (str or None, optional) – Previous plan version, when this is a refinement.
seed (int or None, optional) – Random seed, when a search produced the plan.
service_standard_ids (list of str, optional) – Service standards used by the plan.
notes (str, optional) – Free notes.
- model_config = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- brushline.model.plan.validate_plan(plan: Plan, *, known_segment_ids: set[str] | None = None) ContractValidation[source]
Validate plan ids, references, currencies, and assumptions.
- Parameters:
plan (Plan) – Plan to validate.
known_segment_ids (set of str or None, optional) – Segment ids that the plan may reference. When
None, the check is skipped.
- Returns:
ContractValidation – Errors, warnings, and counts.
Run contract: the manifest of one build, simulation, plan, or demo run.
A run directory contains run.json and the artifacts it names. The manifest records the run
type, the data and model versions, the configuration, the seed, the status, and the artifact index.
An artifact that is not available must say why.
- class brushline.model.run.RunArtifact(*, name: Annotated[str, MinLen(min_length=1)], path: Annotated[str, MinLen(min_length=1)], schema_version: Annotated[str, MinLen(min_length=1)], media_type: Annotated[str, MinLen(min_length=1)], available: bool = True, sha256: Annotated[str | None, _PydanticGeneralMetadata(pattern='^[0-9a-f]{64}$')] = None, reason: str | None = None)[source]
Bases:
BaseModelOne artifact in a run directory.
- Parameters:
name (str) – Stable artifact name, such as
planorpareto.path (str) – Run-relative path.
schema_version (str) – Artifact schema version.
media_type (str) – Media type, such as
application/jsonortext/csv.available (bool) – Whether the artifact exists and is usable.
sha256 (str or None, optional) – SHA-256 of the artifact file. Required when
availableis true.reason (str or None, optional) – Why the artifact is unavailable. Required when
availableis false.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.model.run.RunManifest(*, schema_version: ~typing.Literal['brushline.run.v1'] = 'brushline.run.v1', run_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], run_type: ~typing.Literal['build', 'simulate', 'plan', 'monitor', 'compare', 'demo'], status: ~typing.Literal['running', 'complete', 'failed'], created_utc: ~datetime.datetime, data_version: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], model_versions: ~typing.Annotated[dict[str, str], ~annotated_types.MinLen(min_length=1)], configuration: dict[str, object] = <factory>, artifacts: ~typing.Annotated[list[~brushline.model.run.RunArtifact], ~annotated_types.MinLen(min_length=1)], created_by: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], seed: int | None = None, summary: dict[str, object] = <factory>)[source]
Bases:
BaseModelThe manifest of one run.
- Parameters:
run_id (str) – Stable run identifier.
run_type ({"build", "simulate", "plan", "monitor", "compare", "demo"}) – Run type.
status ({"running", "complete", "failed"}) – Run status.
created_utc (datetime) – Timezone-aware creation time.
data_version (str) – Dataset version or digest.
model_versions (dict of str to str) – Model ids and versions.
configuration (dict of str to object) – Run configuration.
artifacts (list of RunArtifact) – Artifact index. At least one is required.
created_by (str) – Person, process, or agent that created the run.
seed (int or None, optional) – Random seed.
summary (dict of str to object, optional) – Run summary.
- model_config = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- brushline.model.run.validate_run_manifest(manifest: RunManifest) ContractValidation[source]
Validate run artifact names, status, and availability.
- Parameters:
manifest (RunManifest) – Run manifest to validate.
- Returns:
ContractValidation – Errors, warnings, and counts.
Pareto archive contract for multi-objective searches.
The archive keeps the non-dominated plans found by a search portfolio. Each member carries its objective vector, its plan path, its evidence record, and the seed that produced it. The validator checks the objective definitions, the scalarization weights, the member keys, and the non-dominance invariant.
- class brushline.model.archive.ArchiveMember(*, plan_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], plan_path: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], objective: ~typing.Annotated[dict[str, float], ~annotated_types.MinLen(min_length=1)], feasible: bool, seed: int, evidence_path: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], budget: ~typing.Annotated[int | None, ~annotated_types.Ge(ge=0)] = None, metadata: dict[str, object] = <factory>)[source]
Bases:
BaseModelOne non-dominated plan in a Pareto archive.
- Parameters:
plan_id (str) – Plan identifier.
plan_path (str) – Archive-relative plan path.
objective (dict of str to float) – Objective vector. Keys must match the archive objectives.
feasible (bool) – Whether the plan satisfies the hard constraints.
seed (int) – Seed that produced the plan.
evidence_path (str) – Archive-relative evidence record.
budget (int or None, optional) – Search budget used to produce the plan.
metadata (dict of str to object, optional) – Additional member metadata.
- model_config = {'allow_inf_nan': False, 'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.model.archive.Objective(*, name: Annotated[str, MinLen(min_length=1)], direction: Literal['minimize', 'maximize'], unit: Annotated[str, MinLen(min_length=1)])[source]
Bases:
BaseModelOne objective dimension.
- Parameters:
name (str) – Objective name.
direction ({"minimize", "maximize"}) – Whether lower or higher is better.
unit (str) – Unit or index label.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.model.archive.ParetoArchive(*, schema_version: ~typing.Literal['brushline.pareto.v1'] = 'brushline.pareto.v1', instance_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], run_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], objectives: ~typing.Annotated[list[~brushline.model.archive.Objective], ~annotated_types.MinLen(min_length=1)], scalarizations: list[~brushline.model.archive.Scalarization] = <factory>, members: list[~brushline.model.archive.ArchiveMember] = <factory>, eviction: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], created_utc: ~datetime.datetime, created_by: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)])[source]
Bases:
BaseModelThe archive of non-dominated solutions from one run.
- Parameters:
instance_id (str) – Instance identifier.
run_id (str) – Run identifier.
objectives (list of Objective) – Objective definitions. At least one is required.
scalarizations (list of Scalarization) – Scalarizations used by the search portfolio.
members (list of ArchiveMember) – Archive members.
eviction (str) – Eviction policy, such as
crowding-distance.created_utc (datetime) – Timezone-aware creation time.
created_by (str) – Person, process, or agent that created the archive.
- model_config = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.model.archive.Scalarization(*, scalarization_id: Annotated[str, MinLen(min_length=1)], weights: Annotated[dict[str, float], MinLen(min_length=1)], description: str = '')[source]
Bases:
BaseModelOne weighted scalarization used to seed the archive.
- Parameters:
scalarization_id (str) – Stable identifier.
weights (dict of str to float) – Objective weights. They must be non-negative and sum to 1.
description (str, optional) – Human description.
- model_config = {'allow_inf_nan': False, 'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- brushline.model.archive.dominates(left: ArchiveMember, right: ArchiveMember, objectives: list[Objective]) bool[source]
Return whether one member dominates another.
- Parameters:
left (ArchiveMember) – Candidate dominator.
right (ArchiveMember) – Candidate dominated member.
objectives (list of Objective) – Objective definitions.
- Returns:
bool –
Truewhenleftis at least as good on every objective and strictly better on one. ReturnsFalsewhen an objective is missing from either member.
- brushline.model.archive.validate_pareto_archive(archive: ParetoArchive) ContractValidation[source]
Validate objective definitions, scalarizations, member keys, and non-dominance.
- Parameters:
archive (ParetoArchive) – Archive to validate.
- Returns:
ContractValidation – Errors, warnings, and counts.
Operations timeline contract for the 2D map and 3D scene.
The timeline is a sequence of timestamped events: a crew or machine travels, starts, treats, pauses, or finishes a segment. It drives the animation. The timeline is a simulation artifact, not a live telemetry feed, and it never invents a position that is not in the file.
- class brushline.model.timeline.OperationsTimeline(*, schema_version: Literal['brushline.timeline.v1'] = 'brushline.timeline.v1', run_id: Annotated[str, MinLen(min_length=1)], events: Annotated[list[TimelineEvent], MinLen(min_length=1)], created_utc: datetime, created_by: Annotated[str, MinLen(min_length=1)])[source]
Bases:
BaseModelThe operations timeline for one run.
- Parameters:
run_id (str) – Run identifier.
events (list of TimelineEvent) – Timeline events. At least one is required.
created_utc (datetime) – Timezone-aware creation time.
created_by (str) – Person, process, or agent that created the timeline.
- model_config = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.model.timeline.TimelineEvent(*, event_id: Annotated[str, MinLen(min_length=1)], resource_id: Annotated[str, MinLen(min_length=1)], resource_type: Literal['crew', 'machine', 'vehicle', 'other'], segment_id: Annotated[str, MinLen(min_length=1)], event_type: Literal['travel', 'start', 'treatment', 'pause', 'finish', 'other'], start_utc: datetime, state: Annotated[str, MinLen(min_length=1)], action_id: str | None = None, end_utc: datetime | None = None, cost: Annotated[float, Ge(ge=0)] = 0.0, currency: Annotated[str, MinLen(min_length=1)] = 'CAD', notes: str = '')[source]
Bases:
BaseModelOne timestamped operations event.
- Parameters:
event_id (str) – Stable event identifier.
resource_id (str) – Crew, machine, or vehicle identifier.
resource_type ({"crew", "machine", "vehicle", "other"}) – Resource class.
segment_id (str) – Segment identifier.
event_type ({"travel", "start", "treatment", "pause", "finish", "other"}) – Event class.
start_utc (datetime) – Timezone-aware start time.
state (str) – Resource state, such as
idleorworking.action_id (str or None, optional) – Plan action identifier.
end_utc (datetime or None, optional) – Timezone-aware end time. Must not be before
start_utc.cost (float, optional) – Event cost. Defaults to
0.currency (str, optional) – Currency code. Defaults to
CAD.notes (str, optional) – Free notes.
- model_config = {'allow_inf_nan': False, 'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- brushline.model.timeline.validate_timeline(timeline: OperationsTimeline, *, known_segment_ids: set[str] | None = None) ContractValidation[source]
Validate event ids, ordering, and segment references.
- Parameters:
timeline (OperationsTimeline) – Timeline to validate.
known_segment_ids (set of str or None, optional) – Segment ids that the timeline may reference.
- Returns:
ContractValidation – Errors, warnings, and counts.
Demo manifest contract for the public portal.
A demo manifest describes one public example: the partner question, the data sources and licences, the scenarios, the artifact paths, the headline metrics, the caveats, and the pilot link. The public portal is public-data-only and read-only.
- class brushline.model.demo.DemoArtifacts(*, run: Annotated[str, MinLen(min_length=1)], plan: Annotated[str, MinLen(min_length=1)], reports: Annotated[str, MinLen(min_length=1)], pareto: str | None = None, timeline: str | None = None)[source]
Bases:
BaseModelThe artifact paths for a demo.
- Parameters:
run (str) – Run directory or manifest path.
plan (str) – Plan path.
reports (str) – Reports directory or index path.
pareto (str or None, optional) – Pareto archive path.
timeline (str or None, optional) – Operations timeline path.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.model.demo.DemoManifest(*, schema_version: Literal['brushline.demo.v1'] = 'brushline.demo.v1', id: Annotated[str, _PydanticGeneralMetadata(pattern='^[a-z0-9][a-z0-9-]{1,62}$')], title: Annotated[str, MinLen(min_length=1)], sector: Annotated[str, MinLen(min_length=1)], region: Annotated[str, MinLen(min_length=1)], aoi: Annotated[str, MinLen(min_length=1)], question: Annotated[str, MinLen(min_length=1)], data_sources: Annotated[list[DemoSource], MinLen(min_length=1)], scenarios: Annotated[list[str], MinLen(min_length=1)], artifacts: DemoArtifacts, headline_metrics: Annotated[list[DemoMetric], MinLen(min_length=1)], caveats: Annotated[list[str], MinLen(min_length=1)], pilot: Annotated[str, MinLen(min_length=1)], status: Literal['draft', 'published', 'retired'], created_utc: datetime, contact: str = '')[source]
Bases:
BaseModelThe manifest of one public demo.
- Parameters:
id (str) – Lowercase demo identifier.
title (str) – Human title.
sector (str) – Partner sector, such as utility, pipeline, rail, or road.
region (str) – Region label.
aoi (str) – Demo-relative AOI path.
question (str) – The partner question the demo answers.
data_sources (list of DemoSource) – Data sources and licences. At least one is required.
scenarios (list of str) – Scenario names. At least one is required.
artifacts (DemoArtifacts) – Artifact paths.
headline_metrics (list of DemoMetric) – Headline metrics. At least one is required.
caveats (list of str) – Caveats. At least one is required.
pilot (str) – Demo-relative pilot brief path.
status ({"draft", "published", "retired"}) – Demo status.
created_utc (datetime) – Timezone-aware creation time.
contact (str, optional) – Contact or pilot-request link.
- model_config = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.model.demo.DemoMetric(*, name: Annotated[str, MinLen(min_length=1)], value: float, unit: Annotated[str, MinLen(min_length=1)])[source]
Bases:
BaseModelOne headline metric for a demo.
- Parameters:
name (str) – Metric name.
value (float) – Metric value.
unit (str) – Unit or index label.
- model_config = {'allow_inf_nan': False, 'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.model.demo.DemoSource(*, name: Annotated[str, MinLen(min_length=1)], licence: Annotated[str, MinLen(min_length=1)], version: Annotated[str, MinLen(min_length=1)], url: str = '')[source]
Bases:
BaseModelOne data source used by a demo.
- Parameters:
name (str) – Source name.
licence (str) – Licence identifier.
version (str) – Source version or vintage.
url (str, optional) – Public source URL.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- brushline.model.demo.validate_demo_manifest(manifest: DemoManifest) ContractValidation[source]
Validate demo sources, caveats, artifact paths, and publication status.
- Parameters:
manifest (DemoManifest) – Demo manifest to validate.
- Returns:
ContractValidation – Errors, warnings, and counts.
Shared validation report and helpers for the Brushline artifact contracts.
- class brushline.model.validation.ContractValidation(errors: tuple[str, ...], warnings: tuple[str, ...], counts: dict[str, int | float])[source]
Bases:
objectThe outcome of validating one artifact contract.
- Parameters:
errors (tuple of str) – Named errors. An empty tuple means the artifact is valid.
warnings (tuple of str) – Non-fatal findings.
counts (dict of str to int or float) – Object counts or summary values.
- property is_valid: bool
Return whether the artifact passed every check.
- Returns:
bool –
Truewhen there are no errors.
- brushline.model.validation.check_duplicates(prefix: str, label: str, values: list[str], errors: list[str]) None[source]
Append one error for each duplicated value.
- Parameters:
prefix (str) – Error-code prefix, such as
PLAN.label (str) – Human label for the collection.
values (list of str) – Identifiers in the collection.
errors (list of str) – Error accumulator.
- brushline.model.validation.ensure_relative_path(value: str, label: str) str[source]
Reject an absolute path or a path that escapes the artifact directory.
- Parameters:
value (str) – Path to check.
label (str) – Human label for the path.
- Returns:
str – The original path when it is relative and contained.
- Raises:
ValueError – When the path is absolute or contains
...