MapillaryLabelMapper

class rapidtools.processing.MapillaryLabelMapper(llm_model: BaseInferenceModel)

Bases: object

Map natural-language class names to exact Mapillary segmentation labels.

An LLM (Gemma, Gemini, Claude, etc.) is prompted with the user’s target objects and the full list of official Mapillary labels, and asked to return the matching labels as a JSON array. The response is parsed defensively and filtered against the official vocabulary.

Variables:

• llm_model (BaseInferenceModel) – The inference model used to perform the mapping.

• valid_labels (list[str]) – All official Mapillary label strings, extracted from rapidtools.data_sources.mapillary_labels.MapillaryLabels.

Example

>>> from rapidtools.models.base import ModelOutput
>>>
>>> class EchoModel:
...     def run_inference(self, image_inputs, prompt, **kwargs):
...         return ModelOutput(text='["object--vehicle--car"]')
>>>
>>> mapper = MapillaryLabelMapper(EchoModel())
>>> mapper.map_classes(['cars'])
['object--vehicle--car']

Methods

map_classes

Map a list of user strings to official Mapillary labels.

map_classes(user_classes: list[str]) → list[str]

Map a list of user strings to official Mapillary labels.

The model is asked to return only a JSON array of label strings. The first bracketed span in the response that parses as a JSON list is used; any element that is not an official Mapillary label is dropped. Failures (model errors, unparsable output) are logged and yield an empty list rather than raising.

Parameters:

user_classes (list[str]) – Desired items in plain language (e.g., ['fire hydrant', 'cars']).

Returns:

list[str] – A deduplicated list of exact Mapillary label strings in the order the model returned them. Empty if user_classes is empty, the model returns nothing, or the response cannot be parsed.

Example

>>> from rapidtools.models.base import ModelOutput
>>>
>>> class EchoModel:
...     def run_inference(self, image_inputs, prompt, **kwargs):
...         return ModelOutput(
...             text='Labels: ["object--vehicle--car", "not-a-label"]'
...         )
>>>
>>> mapper = MapillaryLabelMapper(EchoModel())
>>> mapper.map_classes(['cars'])
['object--vehicle--car']
>>> mapper.map_classes([])
[]