brushline.optimization.telemetry

The versioned progress-event stream, SSE rendering, archive-event insertion, and studio compatibility check.

Versioned progress-event and archive compatibility contract for the studio.

The telemetry stream is a report of search progress, not a second model state. Events reference the archive, plan, and evidence artifacts. The studio compatibility check reads only the versioned event stream and the archive.

class brushline.optimization.telemetry.EventStream(*, schema_version: str = 'brushline.optimization-telemetry.v1', run_id: Annotated[str, MinLen(min_length=1)], instance_id: Annotated[str, MinLen(min_length=1)], model_version: Annotated[str, MinLen(min_length=1)], data_version: Annotated[str, MinLen(min_length=1)], archive_path: str | None = None, events: Annotated[list[TelemetryEvent], MinLen(min_length=1)])[source]

Bases: BaseModel

A versioned progress-event stream.

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

  • run_id (str) – Run id.

  • instance_id (str) – Instance id.

  • model_version (str) – Vegetation-model version.

  • data_version (str) – Data version.

  • archive_path (str or None) – Archive-relative path to pareto.json.

  • events (list of TelemetryEvent) – Ordered events.

model_config = {'extra': 'forbid'}

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

class brushline.optimization.telemetry.StudioCompatibility(*, ok: bool, errors: list[str] = <factory>, warnings: list[str] = <factory>, archive_path: str | None = None, member_count: int = 0, event_count: int = 0)[source]

Bases: BaseModel

The result of a studio compatibility check.

Parameters:
  • ok (bool) – Whether the stream and archive are compatible.

  • errors (list of str) – Compatibility errors.

  • warnings (list of str) – Compatibility warnings.

  • archive_path (str or None) – Archive path.

  • member_count (int) – Archive member count.

  • event_count (int) – Event count.

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

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

exception brushline.optimization.telemetry.TelemetryError[source]

Bases: ValueError

Raised when an event stream or compatibility check is invalid.

class brushline.optimization.telemetry.TelemetryEvent(*, schema_version: str = 'brushline.optimization-event.v1', event_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], run_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], sequence: ~typing.Annotated[int, ~annotated_types.Ge(ge=0)], event_type: str, created_utc: ~datetime.datetime, instance_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], adapter: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], fresh_solutions_version: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], seed: int, budget: ~typing.Annotated[int, ~annotated_types.Ge(ge=0)], payload: dict[str, ~typing.Any] = <factory>, objective_vector: dict[str, float] | None = None, feasible: bool | None = None, plan_id: str | None = None, evidence_path: str | None = None)[source]

Bases: BaseModel

One progress event.

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

  • event_id (str) – Stable event id.

  • run_id (str) – Run id.

  • sequence (int) – Zero-based sequence.

  • event_type (str) – Event type.

  • created_utc (datetime) – Timezone-aware creation time.

  • instance_id (str) – Instance id.

  • adapter (str) – Adapter name.

  • fresh_solutions_version (str) – Fresh Solutions version.

  • seed (int) – Search seed.

  • budget (int) – Requested budget.

  • payload (dict) – Event-specific data.

  • objective_vector (dict of str to float or None) – Four objectives, when relevant.

  • feasible (bool or None) – Feasibility, when relevant.

  • plan_id (str or None) – Archive plan id, when relevant.

  • evidence_path (str or None) – Archive-relative evidence path, when relevant.

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

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

brushline.optimization.telemetry.check_studio_compatibility(stream: EventStream, archive: ParetoArchive | None, *, archive_path: str | None = None) → StudioCompatibility[source]

Check that the studio can read the stream and archive without private state.

Parameters:
  • stream (EventStream) – Progress stream.

  • archive (ParetoArchive or None) – Archive. None is an explicit missing artifact.

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

Returns:

StudioCompatibility – Compatibility result.

brushline.optimization.telemetry.events_from_run(run: SearchRun, *, run_id: str, model_version: str, data_version: str, archive_path: str | None = None, created_utc: datetime | None = None) → EventStream[source]

Create start, incumbent, checkpoint, and finish events for a run.

Parameters:
  • run (SearchRun) – Replayable search result.

  • run_id (str) – Run id.

  • model_version (str) – Vegetation-model version.

  • data_version (str) – Data version.

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

  • created_utc (datetime, optional) – Creation time.

Returns:

EventStream – Progress stream. An archive event is not fabricated.

brushline.optimization.telemetry.load_event_stream(path: str | Path) → EventStream[source]

Load and validate an event stream.

Parameters:

path (str or Path) – Source.

Returns:

EventStream – Stream.

Raises:

TelemetryError – When the stream is invalid.

brushline.optimization.telemetry.make_event(*, event_id: str, run_id: str, sequence: int, event_type: str, created_utc: datetime, instance_id: str, adapter: str, fresh_solutions_version: str, seed: int, budget: int, payload: dict[str, Any] | None = None, objective_vector: dict[str, float] | None = None, feasible: bool | None = None, plan_id: str | None = None, evidence_path: str | None = None) → TelemetryEvent[source]

Construct one validated event.

Parameters:
  • event_id (str) – Event id.

  • run_id (str) – Run id.

  • sequence (int) – Sequence.

  • event_type (str) – Type.

  • created_utc (datetime) – Creation time.

  • instance_id (str) – Instance id.

  • adapter (str) – Adapter name.

  • fresh_solutions_version (str) – Fresh Solutions version.

  • seed (int) – Seed.

  • budget (int) – Budget.

  • payload (dict, optional) – Event data.

  • objective_vector (dict, optional) – Objectives.

  • feasible (bool, optional) – Feasibility.

  • plan_id (str, optional) – Plan id.

  • evidence_path (str, optional) – Evidence path.

Returns:

TelemetryEvent – Event.

brushline.optimization.telemetry.to_sse(stream: EventStream) → str[source]

Render an event stream as server-sent events.

Parameters:

stream (EventStream) – Stream.

Returns:

str – SSE body.

brushline.optimization.telemetry.validate_event_stream(stream: EventStream) → ContractValidation[source]

Validate sequence, run identity, event order, and artifact references.

Parameters:

stream (EventStream) – Stream to validate.

Returns:

ContractValidation – Errors and warnings.

brushline.optimization.telemetry.with_archive_event(stream: EventStream, archive: ParetoArchive, *, archive_path: str | None = None, created_utc: datetime | None = None) → EventStream[source]

Insert a validated archive event before the finish event.

Parameters:
  • stream (EventStream) – Existing stream.

  • archive (ParetoArchive) – Archive.

  • archive_path (str or None, optional) – Archive path. Defaults to the stream path.

  • created_utc (datetime, optional) – Event time.

Returns:

EventStream – Stream with an archive event before finish.

Raises:

TelemetryError – When the archive is invalid or no finish event exists.

brushline.optimization.telemetry.write_event_stream(stream: EventStream, path: str | Path) → Path[source]

Validate and write an event stream as JSON.

Parameters:
  • stream (EventStream) – Stream.

  • path (str or Path) – Destination.

Returns:

Path – Written path.

Raises:

TelemetryError – When the stream is invalid.

brushline.optimization.telemetry.write_sse(stream: EventStream, path: str | Path) → Path[source]

Write a validated SSE event stream.

Parameters:
  • stream (EventStream) – Stream.

  • path (str or Path) – Destination.

Returns:

Path – Written path.