Audience example handler

AudienceExampleHandler

AudienceExampleHandler(
    openapi_service: OpenAPIService, audience_id: str
)

Can be used to build different types of examples. That can then be added to Example sets

Source code in src/rapidata/rapidata_client/audience/audience_example_handler.py

def __init__(self, openapi_service: OpenAPIService, audience_id: str):
    self._openapi_service = openapi_service
    self._audience_id = audience_id
    self._asset_uploader = AssetUploader(openapi_service)

add_classification_example

add_classification_example(
    instruction: str,
    answer_options: list[str],
    datapoint: str,
    truth: list[str],
    data_type: Literal["media", "text"] = "media",
    context: str | None = None,
    media_context: list[str] | None = None,
    explanation: str | None = None,
    settings: Sequence[RapidataSetting] | None = None,
) -> None

add a classification example to the audience

Parameters:

Name	Type	Description	Default
instruction	str	The instruction/question to be shown to the labeler.	required
answer_options	list[str]	The options that the labeler can choose from to answer the question.	required
datapoint	str	The datapoint that the labeler will be labeling.	required
truth	list[str]	The correct answers to the question.	required
data_type	str	The type of the datapoint. Defaults to "media" (any form of image, video or audio).	'media'
context	str	The context is text that will be shown in addition to the instruction. Defaults to None.	None
media_context	list[str]	A list of image URLs / paths that will be shown in addition to the instruction (can be combined with context). Pass a single-element list for one image, or multiple to display several images. Defaults to None.	None
explanation	str	The explanation that will be shown to the labeler if the answer is wrong. Defaults to None.	None
settings	Sequence[RapidataSetting]	The list of settings to apply to the example as feature flags. Controls how the example is rendered to the labeler (e.g. NoShuffleSetting to keep the order of answer options). Defaults to None.	None

Source code in src/rapidata/rapidata_client/audience/audience_example_handler.py

def add_classification_example(
    self,
    instruction: str,
    answer_options: list[str],
    datapoint: str,
    truth: list[str],
    data_type: Literal["media", "text"] = "media",
    context: str | None = None,
    media_context: list[str] | None = None,
    explanation: str | None = None,
    settings: Sequence[RapidataSetting] | None = None,
) -> None:
    """add a classification example to the audience

    Args:
        instruction (str): The instruction/question to be shown to the labeler.
        answer_options (list[str]): The options that the labeler can choose from to answer the question.
        datapoint (str): The datapoint that the labeler will be labeling.
        truth (list[str]): The correct answers to the question.
        data_type (str, optional): The type of the datapoint. Defaults to "media" (any form of image, video or audio).
        context (str, optional): The context is text that will be shown in addition to the instruction. Defaults to None.
        media_context (list[str], optional): A list of image URLs / paths that will be shown in addition to the instruction (can be combined with context). Pass a single-element list for one image, or multiple to display several images. Defaults to None.
        explanation (str, optional): The explanation that will be shown to the labeler if the answer is wrong. Defaults to None.
        settings (Sequence[RapidataSetting], optional): The list of settings to apply to the example as feature flags. Controls how the example is rendered to the labeler (e.g. ``NoShuffleSetting`` to keep the order of answer options). Defaults to None.
    """
    from rapidata.api_client.models.add_example_to_audience_endpoint_input import (
        AddExampleToAudienceEndpointInput,
    )

    validate_instruction_length(instruction)

    if not isinstance(truth, list):
        raise ValueError("Truth must be a list of strings")

    if not all(truth in answer_options for truth in truth):
        raise ValueError("Truth must be part of the answer options")

    asset_input = self._asset_uploader.build_asset_input(datapoint, data_type)

    payload = IExamplePayload(
        actual_instance=IExamplePayloadClassifyExamplePayload(
            _t="ClassifyExamplePayload",
            categories=[
                ExampleCategory(label=option, value=option)
                for option in answer_options
            ],
            title=instruction,
        )
    )
    model_truth = IExampleTruth(
        actual_instance=IExampleTruthClassifyExampleTruth(
            correctCategories=truth, _t="ClassifyExampleTruth"
        )
    )

    self._openapi_service.audience.examples_api.audience_audience_id_example_post(
        audience_id=self._audience_id,
        add_example_to_audience_endpoint_input=AddExampleToAudienceEndpointInput(
            asset=asset_input,
            payload=payload,
            truth=model_truth,
            context=context,
            contextAsset=(
                self._asset_uploader.upload_and_map_asset(media_context)
                if media_context
                else None
            ),
            explanation=explanation,
            randomCorrectProbability=len(truth) / len(answer_options),
            featureFlags=(
                [s._to_feature_flag() for s in settings] if settings else None
            ),
        ),
    )

add_compare_example

add_compare_example(
    instruction: str,
    truth: str,
    datapoint: list[str],
    data_type: Literal["media", "text"] = "media",
    context: str | None = None,
    media_context: list[str] | None = None,
    explanation: str | None = None,
    settings: Sequence[RapidataSetting] | None = None,
) -> None

add a compare example to the audience

Parameters:

Name	Type	Description	Default
instruction	str	The instruction that the labeler will be comparing the assets on.	required
truth	str	The correct answer to the comparison. (has to be one of the assets)	required
datapoint	list[str]	The two assets that the labeler will be comparing.	required
data_type	str	The type of the datapoint. Defaults to "media" (any form of image, video or audio).	'media'
context	str	The context is text that will be shown in addition to the instruction. Defaults to None.	None
media_context	list[str]	A list of image URLs / paths that will be shown in addition to the instruction (can be combined with context). Pass a single-element list for one image, or multiple to display several images. Defaults to None.	None
explanation	str	The explanation that will be shown to the labeler if the answer is wrong. Defaults to None.	None
settings	Sequence[RapidataSetting]	The list of settings to apply to the example as feature flags. Controls how the example is rendered to the labeler (e.g. ComparePanoramaSetting to render panoramic images). Defaults to None.	None

Source code in src/rapidata/rapidata_client/audience/audience_example_handler.py

def add_compare_example(
    self,
    instruction: str,
    truth: str,
    datapoint: list[str],
    data_type: Literal["media", "text"] = "media",
    context: str | None = None,
    media_context: list[str] | None = None,
    explanation: str | None = None,
    settings: Sequence[RapidataSetting] | None = None,
) -> None:
    """add a compare example to the audience

    Args:
        instruction (str): The instruction that the labeler will be comparing the assets on.
        truth (str): The correct answer to the comparison. (has to be one of the assets)
        datapoint (list[str]): The two assets that the labeler will be comparing.
        data_type (str, optional): The type of the datapoint. Defaults to "media" (any form of image, video or audio).
        context (str, optional): The context is text that will be shown in addition to the instruction. Defaults to None.
        media_context (list[str], optional): A list of image URLs / paths that will be shown in addition to the instruction (can be combined with context). Pass a single-element list for one image, or multiple to display several images. Defaults to None.
        explanation (str, optional): The explanation that will be shown to the labeler if the answer is wrong. Defaults to None.
        settings (Sequence[RapidataSetting], optional): The list of settings to apply to the example as feature flags. Controls how the example is rendered to the labeler (e.g. ``ComparePanoramaSetting`` to render panoramic images). Defaults to None.
    """
    from rapidata.api_client.models.add_example_to_audience_endpoint_input import (
        AddExampleToAudienceEndpointInput,
    )

    validate_instruction_length(instruction)

    if truth not in datapoint:
        raise ValueError("Truth must be one of the datapoints")

    if len(datapoint) != 2:
        raise ValueError("Compare rapid requires exactly two media paths")

    payload = IExamplePayload(
        actual_instance=IExamplePayloadCompareExamplePayload(
            _t="CompareExamplePayload", criteria=instruction
        )
    )

    asset_input, asset_to_uploaded = (
        self._asset_uploader.build_asset_input_with_names(datapoint, data_type)
    )

    winner_id = asset_to_uploaded[truth] if data_type == "media" else truth
    model_truth = IExampleTruth(
        actual_instance=IExampleTruthCompareExampleTruth(
            _t="CompareExampleTruth", winnerId=winner_id
        )
    )

    self._openapi_service.audience.examples_api.audience_audience_id_example_post(
        audience_id=self._audience_id,
        add_example_to_audience_endpoint_input=AddExampleToAudienceEndpointInput(
            asset=asset_input,
            payload=payload,
            truth=model_truth,
            context=context,
            contextAsset=(
                self._asset_uploader.upload_and_map_asset(media_context)
                if media_context
                else None
            ),
            explanation=explanation,
            randomCorrectProbability=0.5,
            featureFlags=(
                [s._to_feature_flag() for s in settings] if settings else None
            ),
        ),
    )

add_locate_example

add_locate_example(
    instruction: str,
    datapoint: str,
    truths: list[Box],
    required_precision: float | None = None,
    required_completeness: float | None = None,
    context: str | None = None,
    media_context: list[str] | None = None,
    explanation: str | None = None,
    settings: Sequence[RapidataSetting] | None = None,
) -> None

add a locate example to the audience

Parameters:

Name	Type	Description	Default
instruction	str	The instruction telling the labeler what to locate.	required
datapoint	str	The media datapoint the labeler will be locating the target in.	required
truths	list[Box]	The bounding boxes covering the correct regions to tap. Coordinates are ratios of the image size (0.0 to 1.0).	required
required_precision	float	Minimum ratio of the labeler's taps that fall inside a correct region required to pass. Defaults to None (backend default).	None
required_completeness	float	Minimum ratio of the correct regions that must be hit. Defaults to None (backend default).	None
context	str	The context is text that will be shown in addition to the instruction. Defaults to None.	None
media_context	list[str]	A list of image URLs / paths that will be shown in addition to the instruction (can be combined with context). Pass a single-element list for one image, or multiple to display several images. Defaults to None.	None
explanation	str	The explanation that will be shown to the labeler if the answer is wrong. Defaults to None.	None
settings	Sequence[RapidataSetting]	The list of settings to apply to the example as feature flags. Controls how the example is rendered to the labeler. Defaults to None.	None

Source code in src/rapidata/rapidata_client/audience/audience_example_handler.py

def add_locate_example(
    self,
    instruction: str,
    datapoint: str,
    truths: list[Box],
    required_precision: float | None = None,
    required_completeness: float | None = None,
    context: str | None = None,
    media_context: list[str] | None = None,
    explanation: str | None = None,
    settings: Sequence[RapidataSetting] | None = None,
) -> None:
    """add a locate example to the audience

    Args:
        instruction (str): The instruction telling the labeler what to locate.
        datapoint (str): The media datapoint the labeler will be locating the target in.
        truths (list[Box]): The bounding boxes covering the correct regions to tap. Coordinates are ratios of the image size (0.0 to 1.0).
        required_precision (float, optional): Minimum ratio of the labeler's taps that fall inside a correct region required to pass. Defaults to None (backend default).
        required_completeness (float, optional): Minimum ratio of the correct regions that must be hit. Defaults to None (backend default).
        context (str, optional): The context is text that will be shown in addition to the instruction. Defaults to None.
        media_context (list[str], optional): A list of image URLs / paths that will be shown in addition to the instruction (can be combined with context). Pass a single-element list for one image, or multiple to display several images. Defaults to None.
        explanation (str, optional): The explanation that will be shown to the labeler if the answer is wrong. Defaults to None.
        settings (Sequence[RapidataSetting], optional): The list of settings to apply to the example as feature flags. Controls how the example is rendered to the labeler. Defaults to None.
    """
    from rapidata.api_client.models.add_example_to_audience_endpoint_input import (
        AddExampleToAudienceEndpointInput,
    )

    validate_instruction_length(instruction)

    if not truths:
        raise ValueError("Locate example requires at least one truth bounding box")

    _validate_ratio("required_precision", required_precision)
    _validate_ratio("required_completeness", required_completeness)

    asset_input = self._asset_uploader.upload_and_map_asset(datapoint)

    payload = IExamplePayload(
        actual_instance=IExamplePayloadLocateExamplePayload(
            _t="LocateExamplePayload", target=instruction
        )
    )
    model_truth = IExampleTruth(
        actual_instance=IExampleTruthLocateExampleTruth(
            _t="LocateExampleTruth",
            boundingBoxes=[truth.to_example_model() for truth in truths],
            requiredPrecision=required_precision,
            requiredCompleteness=required_completeness,
        )
    )

    self._openapi_service.audience.examples_api.audience_audience_id_example_post(
        audience_id=self._audience_id,
        add_example_to_audience_endpoint_input=AddExampleToAudienceEndpointInput(
            asset=asset_input,
            payload=payload,
            truth=model_truth,
            context=context,
            contextAsset=(
                self._asset_uploader.upload_and_map_asset(media_context)
                if media_context
                else None
            ),
            explanation=explanation,
            randomCorrectProbability=calculate_boxes_coverage(truths),
            featureFlags=(
                [s._to_feature_flag() for s in settings] if settings else None
            ),
        ),
    )

add_draw_example

add_draw_example(
    instruction: str,
    datapoint: str,
    truths: list[Box],
    required_precision: float | None = None,
    required_completeness: float | None = None,
    context: str | None = None,
    media_context: list[str] | None = None,
    explanation: str | None = None,
    settings: Sequence[RapidataSetting] | None = None,
) -> None

add a draw example to the audience

Parameters:

Name	Type	Description	Default
instruction	str	The instruction telling the labeler what to draw.	required
datapoint	str	The media datapoint the labeler will be drawing on.	required
truths	list[Box]	The bounding boxes covering the correct regions — labelers are graded on whether their drawn lines fall within any of these boxes. Coordinates are ratios of the image size (0.0 to 1.0).	required
required_precision	float	Minimum ratio of the labeler's lines that fall inside a correct region required to pass. Defaults to None (backend default).	None
required_completeness	float	Minimum ratio of the correct regions that must be hit. Defaults to None (backend default).	None
context	str	The context is text that will be shown in addition to the instruction. Defaults to None.	None
media_context	list[str]	A list of image URLs / paths that will be shown in addition to the instruction (can be combined with context). Pass a single-element list for one image, or multiple to display several images. Defaults to None.	None
explanation	str	The explanation that will be shown to the labeler if the answer is wrong. Defaults to None.	None
settings	Sequence[RapidataSetting]	The list of settings to apply to the example as feature flags. Controls how the example is rendered to the labeler. Defaults to None.	None

Source code in src/rapidata/rapidata_client/audience/audience_example_handler.py

def add_draw_example(
    self,
    instruction: str,
    datapoint: str,
    truths: list[Box],
    required_precision: float | None = None,
    required_completeness: float | None = None,
    context: str | None = None,
    media_context: list[str] | None = None,
    explanation: str | None = None,
    settings: Sequence[RapidataSetting] | None = None,
) -> None:
    """add a draw example to the audience

    Args:
        instruction (str): The instruction telling the labeler what to draw.
        datapoint (str): The media datapoint the labeler will be drawing on.
        truths (list[Box]): The bounding boxes covering the correct regions — labelers are graded on whether their drawn lines fall within any of these boxes. Coordinates are ratios of the image size (0.0 to 1.0).
        required_precision (float, optional): Minimum ratio of the labeler's lines that fall inside a correct region required to pass. Defaults to None (backend default).
        required_completeness (float, optional): Minimum ratio of the correct regions that must be hit. Defaults to None (backend default).
        context (str, optional): The context is text that will be shown in addition to the instruction. Defaults to None.
        media_context (list[str], optional): A list of image URLs / paths that will be shown in addition to the instruction (can be combined with context). Pass a single-element list for one image, or multiple to display several images. Defaults to None.
        explanation (str, optional): The explanation that will be shown to the labeler if the answer is wrong. Defaults to None.
        settings (Sequence[RapidataSetting], optional): The list of settings to apply to the example as feature flags. Controls how the example is rendered to the labeler. Defaults to None.
    """
    from rapidata.api_client.models.add_example_to_audience_endpoint_input import (
        AddExampleToAudienceEndpointInput,
    )

    validate_instruction_length(instruction)

    if not truths:
        raise ValueError("Draw example requires at least one truth bounding box")

    _validate_ratio("required_precision", required_precision)
    _validate_ratio("required_completeness", required_completeness)

    asset_input = self._asset_uploader.upload_and_map_asset(datapoint)

    payload = IExamplePayload(
        actual_instance=IExamplePayloadLineExamplePayload(
            _t="LineExamplePayload", target=instruction
        )
    )
    model_truth = IExampleTruth(
        actual_instance=IExampleTruthLineExampleTruth(
            _t="LineExampleTruth",
            boundingBoxes=[truth.to_example_model() for truth in truths],
            requiredPrecision=required_precision,
            requiredCompleteness=required_completeness,
        )
    )

    self._openapi_service.audience.examples_api.audience_audience_id_example_post(
        audience_id=self._audience_id,
        add_example_to_audience_endpoint_input=AddExampleToAudienceEndpointInput(
            asset=asset_input,
            payload=payload,
            truth=model_truth,
            context=context,
            contextAsset=(
                self._asset_uploader.upload_and_map_asset(media_context)
                if media_context
                else None
            ),
            explanation=explanation,
            randomCorrectProbability=calculate_boxes_coverage(truths),
            featureFlags=(
                [s._to_feature_flag() for s in settings] if settings else None
            ),
        ),
    )

add_select_words_example

add_select_words_example(
    instruction: str,
    datapoint: str,
    sentence: str,
    truths: list[int],
    required_precision: float = 1,
    required_completeness: float = 1,
    explanation: str | None = None,
    settings: Sequence[RapidataSetting] | None = None,
) -> None

add a select words example to the audience

Parameters:

Name	Type	Description	Default
instruction	str	The instruction telling the labeler which words to select.	required
datapoint	str	The media datapoint the labeler will be selecting words for.	required
sentence	str	The sentence that the labeler will be selecting words from. (split up by spaces)	required
truths	list[int]	The indices of the words that are the correct answers.	required
required_precision	float	The required precision for the labeler to get the example correct (minimum ratio of the words selected that need to be correct). Defaults to 1. (no wrong words can be selected)	1
required_completeness	float	The required completeness for the labeler to get the example correct (minimum ratio of total correct words selected). Defaults to 1. (all correct words need to be selected)	1
explanation	str	The explanation that will be shown to the labeler if the answer is wrong. Defaults to None.	None
settings	Sequence[RapidataSetting]	The list of settings to apply to the example as feature flags. Controls how the example is rendered to the labeler. Defaults to None.	None

Source code in src/rapidata/rapidata_client/audience/audience_example_handler.py

def add_select_words_example(
    self,
    instruction: str,
    datapoint: str,
    sentence: str,
    truths: list[int],
    required_precision: float = 1,
    required_completeness: float = 1,
    explanation: str | None = None,
    settings: Sequence[RapidataSetting] | None = None,
) -> None:
    """add a select words example to the audience

    Args:
        instruction (str): The instruction telling the labeler which words to select.
        datapoint (str): The media datapoint the labeler will be selecting words for.
        sentence (str): The sentence that the labeler will be selecting words from. (split up by spaces)
        truths (list[int]): The indices of the words that are the correct answers.
        required_precision (float): The required precision for the labeler to get the example correct (minimum ratio of the words selected that need to be correct). Defaults to 1. (no wrong words can be selected)
        required_completeness (float): The required completeness for the labeler to get the example correct (minimum ratio of total correct words selected). Defaults to 1. (all correct words need to be selected)
        explanation (str, optional): The explanation that will be shown to the labeler if the answer is wrong. Defaults to None.
        settings (Sequence[RapidataSetting], optional): The list of settings to apply to the example as feature flags. Controls how the example is rendered to the labeler. Defaults to None.
    """
    from rapidata.api_client.models.add_example_to_audience_endpoint_input import (
        AddExampleToAudienceEndpointInput,
    )

    validate_instruction_length(instruction)

    transcription_words = [
        ExampleTranscriptionWord(word=word, wordIndex=i)
        for i, word in enumerate(sentence.split(" "))
    ]

    if not truths:
        raise ValueError("Select words example requires at least one truth index")

    if any(index < 0 or index >= len(transcription_words) for index in truths):
        raise ValueError(
            "Truth indices must be within the range of words in the sentence"
        )

    correct_words = [
        ExampleTranscriptionWord(
            word=transcription_words[index].word, wordIndex=index
        )
        for index in truths
    ]

    asset_input = self._asset_uploader.upload_and_map_asset(datapoint)

    payload = IExamplePayload(
        actual_instance=IExamplePayloadTranscriptionExamplePayload(
            _t="TranscriptionExamplePayload",
            title=instruction,
            transcription=transcription_words,
        )
    )
    model_truth = IExampleTruth(
        actual_instance=IExampleTruthTranscriptionExampleTruth(
            _t="TranscriptionExampleTruth",
            correctWords=correct_words,
            requiredPrecision=required_precision,
            requiredCompleteness=required_completeness,
        )
    )

    self._openapi_service.audience.examples_api.audience_audience_id_example_post(
        audience_id=self._audience_id,
        add_example_to_audience_endpoint_input=AddExampleToAudienceEndpointInput(
            asset=asset_input,
            payload=payload,
            truth=model_truth,
            explanation=explanation,
            randomCorrectProbability=len(correct_words) / len(transcription_words),
            featureFlags=(
                [s._to_feature_flag() for s in settings] if settings else None
            ),
        ),
    )