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:
BaseModelA 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:
BaseModelThe 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:
ValueErrorRaised 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:
BaseModelOne 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.