DetectionVerifier

class rapidtools.processing.DetectionVerifier(model: BaseInferenceModel | None = None, *, classifier: Callable[[list[Path], str], list[tuple[bool, float, str]]] | None = None, descriptions: Mapping[str, str] | None = None, prompt: str | None = None, max_images_per_asset: int = 2, min_confidence: float = 0.5, min_visible_fraction: float = 0.5, keep_rejected: bool = False, reject_unverified: bool = False, attribute_prefix: str = 'verify', generation: GenerationConfig | None = None, max_workers: int | None = None, rate_limit: RateLimitPolicy | None = None, cancel_event: Event | None = None)

Bases: object

Confirm that each detected object is what its asset type claims.

For every asset the verifier picks the nearest downloaded images (by the range_m image property written by MapillaryObjectImageExtractor), asks a model whether they show the expected kind of object, and removes the assets that do not. Any wrapper from rapidtools.models.load() can be used, or a plain Python callable for a custom classifier.

Each verified asset receives the attributes <prefix>_match (bool), <prefix>_confidence (float or None), <prefix>_label (what the model saw), <prefix>_accepted (bool) and <prefix>_model. Assets without downloaded images, and assets whose request failed, are kept with <prefix>_accepted = None.

Parameters:

• model (BaseInferenceModel | None) – Any rapidtools model wrapper (see rapidtools.models.load()). Exactly one of model and classifier must be given.

• classifier (Callable | None) – Custom alternative to model: called once per asset as classifier(image_paths, description) and must return one (match, confidence, label) tuple per image. The asset is accepted when any image matches with at least min_confidence.

• descriptions (Mapping[str, str] | None) – asset_type -> what it must be, e.g. {'vehicles': 'a vehicle (car, truck, bus, van, pickup, trailer or motorcycle)'}. Types not listed fall back to describe_asset_type().

• prompt (str | None) – Replaces DEFAULT_PROMPT; {description} is substituted with the asset type’s description. The model must still reply with a JSON object holding match, confidence and label.

• max_images_per_asset (int) – Nearest images sent per asset. Defaults to 2.

• min_visible_fraction (float) – Objects the model reports as less visible than this fraction (hidden behind other things, cut off, too distant to tell) are rejected even when it says they match. Defaults to 0.5.

• min_confidence (float) – Minimum confidence for a positive match to count. A missing confidence counts as 1.0. Defaults to 0.5.

• keep_rejected (bool) – Keep rejected assets (flagged <prefix>_accepted = False) instead of removing them. Defaults to False.

• reject_unverified (bool) – Treat an asset the model gave no usable verdict for (a failed call or an unparseable reply) as rejected instead of leaving it accepted with <prefix>_accepted = None. Defaults to False.

• attribute_prefix (str) – Prefix of the attributes written. Defaults to 'verify'.

• generation (GenerationConfig | None) – Generation options for model; defaults to JSON mode at temperature 0.

• max_workers (int | None) – Concurrent requests for hosted models (see AssetAnalyzer).

• rate_limit (RateLimitPolicy | None) – Back-off and retry policy for hosted models.

• cancel_event (Event | None) – Cooperative cancellation flag; raises OperationCancelled when set.

Raises:

ValueError – If neither or both of model and classifier are given, or min_confidence is outside [0, 1].

Example

Detect vehicles from Mapillary, attach their crops, discard the detections a model does not recognise as vehicles, and only then pay for the detailed analysis:

>>> import rapidtools as rt
>>> from rapidtools.models import load
>>> from rapidtools.processing import (
...     AssetAnalyzer,
...     DetectionVerifier,
...     MapillaryFeatureExtractor,
...     MapillaryObjectImageExtractor,
... )
>>> pipeline = rt.Pipeline([
...     MapillaryFeatureExtractor(token, labels=['vehicles']),
...     MapillaryObjectImageExtractor(token, save_directory='crops'),
...     DetectionVerifier(load('gemini')),
...     AssetAnalyzer(load('gemini'), prompt='Describe the damage as JSON.'),
... ])
>>> collection = pipeline.run(collection)

A custom classifier needs no model wrapper at all:

>>> def my_classifier(paths, description):
...     return [(True, 0.9, 'car') for _ in paths]
>>> verifier = DetectionVerifier(classifier=my_classifier, min_confidence=0.8)
>>> verifier.stage
<Stage.VERIFY: 45>

Methods

description_for	Return what assets of asset_type must look like to be accepted.
prompt_for	Return the prompt sent for assets of asset_type.

property model_name: str

Identifier written to <prefix>_model on every verified asset.

description_for(asset_type: str | None) → str

Return what assets of asset_type must look like to be accepted.

Example

>>> v = DetectionVerifier(classifier=lambda p, d: [])
>>> v.description_for('vehicles')
'a vehicle (car, truck, bus, van, pickup, trailer or motorcycle)'

prompt_for(asset_type: str | None) → str

Return the prompt sent for assets of asset_type.