rapidata 2.37.0__py3-none-any.whl → 3.0.0a8__py3-none-any.whl

rapidata/rapidata_client/__init__.py

@@ -1,4 +1,12 @@
 from .rapidata_client import RapidataClient
+from .audience import (
+    RapidataAudience,
+    RapidataAudienceManager,
+)
+from .order import RapidataOrderManager, RapidataOrder
+from .job import RapidataJob, JobDefinition, JobManager
+from .validation import ValidationSetManager, RapidataValidationSet, Box
+from .results import RapidataResults
 from .selection import (
     DemographicSelection,
     LabelingSelection,
@@ -13,10 +21,8 @@ from .datapoints import Datapoint
 from .datapoints.metadata import (
     PrivateTextMetadata,
     PublicTextMetadata,
-    PromptMetadata,
     SelectWordsMetadata,
 )
-from .datapoints.assets import MediaAsset, TextAsset, MultiAsset, RapidataDataTypes
 from .settings import (
     RapidataSettings,
     TranslationBehaviourOptions,
@@ -27,11 +33,15 @@ from .settings import (
     PlayVideoUntilTheEnd,
     CustomSetting,
     AllowNeitherBoth,
+    SwapContextInstruction,
+    MuteVideo,
 )
-from .country_codes import CountryCodes
 from .filter import (
     CountryFilter,
     LanguageFilter,
+    NotFilter,
+    OrFilter,
+    AndFilter,
     UserScoreFilter,
     CampaignFilter,
     AgeFilter,
@@ -39,13 +49,6 @@ from .filter import (
     CustomFilter,
     AgeGroup,
     Gender,
-    NotFilter,
-    OrFilter,
-    ResponseCountFilter,
 )
-
-from .logging import configure_logger, logger, RapidataOutputManager
-
-from .validation import Box
 from .exceptions import FailedUploadException
-from .config import rapidata_config
+from .config import rapidata_config, logger, managed_print

rapidata/rapidata_client/api/{rapidata_exception.py → rapidata_api_client.py}

@@ -1,10 +1,19 @@
 from typing import Optional, Any
-from rapidata.api_client.api_client import ApiClient, rest, ApiResponse, ApiResponseT
+from rapidata.api_client.api_client import (
+    ApiClient,
+    rest,
+    ApiResponse,
+    ApiResponseT,
+)
 from rapidata.api_client.exceptions import ApiException
 import json
 import threading
 from contextlib import contextmanager
-from rapidata.rapidata_client.logging import logger
+from rapidata.rapidata_client.config import logger, tracer
+from opentelemetry import trace
+from opentelemetry.trace import format_trace_id, format_span_id, Link, SpanContext
+from opentelemetry.sdk.trace.id_generator import RandomIdGenerator
+
 
 # Thread-local storage for controlling error logging
 _thread_local = threading.local()
@@ -91,6 +100,114 @@ class RapidataError(Exception):
 class RapidataApiClient(ApiClient):
     """Custom API client that wraps errors in RapidataError."""
 
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.id_generator = RandomIdGenerator()
+
+    def call_api(
+        self,
+        method,
+        url,
+        header_params=None,
+        body=None,
+        post_params=None,
+        _request_timeout=None,
+    ) -> rest.RESTResponse:
+        # Get the current span from OpenTelemetry
+        current_span = trace.get_current_span()
+
+        # Initialize header_params if it's None
+        if header_params is None:
+            header_params = {}
+
+        # Add tracing headers if we have a valid span
+        if not current_span.is_recording():
+            return super().call_api(
+                method,
+                url,
+                header_params,
+                body,
+                post_params,
+                _request_timeout,
+            )
+
+        current_span_context = current_span.get_span_context()
+
+        # Generate a new trace ID for backend communication
+        # This separates the backend trace from the SDK trace
+        backend_trace_id = self.id_generator.generate_trace_id()
+        backend_span_id = self.id_generator.generate_span_id()
+
+        # Create a new span context for the backend trace
+        backend_span_context = SpanContext(
+            trace_id=backend_trace_id,
+            span_id=backend_span_id,
+            is_remote=True,
+            trace_flags=current_span_context.trace_flags,
+        )
+
+        # Create a link from current SDK span to the backend trace
+        link_to_backend = Link(backend_span_context)
+
+        # Create a link from backend trace back to the original SDK span
+        link_back_to_sdk = Link(current_span_context)
+
+        # Create a span in the current SDK trace that links to the backend
+        with tracer.start_span(
+            f"{str(method).upper()} {url}",
+            links=[link_to_backend],
+        ) as sdk_request_span:
+            # Set attributes on the SDK span
+            sdk_request_span.set_attribute("http.method", method)
+            sdk_request_span.set_attribute("http.target", url)
+            sdk_request_span.set_attribute(
+                "rapidata.backend_trace_id", format_trace_id(backend_trace_id)
+            )
+            sdk_request_span.set_attribute(
+                "rapidata.original_trace_id",
+                format_trace_id(current_span_context.trace_id),
+            )
+
+            # Now create the initial span for the backend trace that will be sent
+            # This span will be the starting point for the backend trace
+            with tracer.start_span(
+                f"{str(method).upper()} {url}",
+                context=trace.set_span_in_context(
+                    trace.NonRecordingSpan(backend_span_context)
+                ),
+                links=[link_back_to_sdk],
+            ) as backend_initial_span:
+                # Set attributes on the backend initial span
+                backend_initial_span.set_attribute("http.method", method)
+                backend_initial_span.set_attribute("http.target", url)
+                backend_initial_span.set_attribute(
+                    "rapidata.trace_type", "backend_start"
+                )
+                backend_initial_span.set_attribute(
+                    "rapidata.sdk_trace_id",
+                    format_trace_id(current_span_context.trace_id),
+                )
+
+                # Format the traceparent header with the backend trace ID
+                # The backend will receive this and continue the trace
+                header_params["traceparent"] = (
+                    "00-"
+                    + format_trace_id(backend_trace_id)
+                    + "-"
+                    + format_span_id(backend_initial_span.get_span_context().span_id)
+                    + "-"
+                    + f"{backend_span_context.trace_flags:02x}"
+                )
+
+                return super().call_api(
+                    method,
+                    url,
+                    header_params,
+                    body,
+                    post_params,
+                    _request_timeout,
+                )
+
     def response_deserialize(
         self,
         response_data: rest.RESTResponse,

rapidata/rapidata_client/audience/__init__.py

@@ -0,0 +1,2 @@
+from .rapidata_audience import RapidataAudience
+from .rapidata_audience_manager import RapidataAudienceManager

rapidata/rapidata_client/audience/audience_example_handler.py

@@ -0,0 +1,168 @@
+from typing import Literal
+
+from rapidata.api_client.models.i_validation_truth_attach_category_truth import (
+    IValidationTruthAttachCategoryTruth,
+)
+from rapidata.api_client.models.i_rapid_payload_classify_payload import (
+    IRapidPayloadClassifyPayload,
+)
+from rapidata.api_client.models.classify_payload_category import ClassifyPayloadCategory
+from rapidata.api_client.models.i_rapid_payload_compare_payload import (
+    IRapidPayloadComparePayload,
+)
+from rapidata.api_client.models.i_validation_truth_compare_truth import (
+    IValidationTruthCompareTruth,
+)
+from rapidata.service.openapi_service import OpenAPIService
+from rapidata.api_client.models.i_rapid_payload import IRapidPayload
+from rapidata.api_client.models.i_validation_truth import IValidationTruth
+from rapidata.rapidata_client.datapoints._asset_uploader import AssetUploader
+
+
+class AudienceExampleHandler:
+    """
+    Can be used to build different types of examples. That can then be added to Example sets
+    """
+
+    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)
+
+    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: str | None = None,
+        explanation: str | 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.
+            truts (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 (str, optional): The media context is a link to an image / video that will be shown in addition to the instruction (can be combined with context). Defaults to None.
+            explanation (str, optional): The explanation that will be shown to the labeler if the answer is wrong. Defaults to None.
+        """
+        from rapidata.api_client.models.add_rapid_to_audience_model import (
+            AddRapidToAudienceModel,
+        )
+
+        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")
+
+        if data_type == "media":
+            asset_input = self._asset_uploader.get_uploaded_asset_input(datapoint)
+        else:
+            asset_input = self._asset_uploader.get_uploaded_text_input(datapoint)
+
+        payload = IRapidPayload(
+            actual_instance=IRapidPayloadClassifyPayload(
+                _t="ClassifyPayload",
+                categories=[
+                    ClassifyPayloadCategory(label=option, value=option)
+                    for option in answer_options
+                ],
+                title=instruction,
+            )
+        )
+        model_truth = IValidationTruth(
+            actual_instance=IValidationTruthAttachCategoryTruth(
+                correctCategories=truth, _t="AttachCategoryTruth"
+            )
+        )
+
+        self._openapi_service.audience_api.audience_audience_id_rapid_post(
+            audience_id=self._audience_id,
+            add_rapid_to_audience_model=AddRapidToAudienceModel(
+                asset=asset_input,
+                payload=payload,
+                truth=model_truth,
+                context=context,
+                contextAsset=(
+                    self._asset_uploader.get_uploaded_asset_input(media_context)
+                    if media_context
+                    else None
+                ),
+                explanation=explanation,
+                randomCorrectProbability=len(truth) / len(answer_options),
+            ),
+        )
+
+    def add_compare_example(
+        self,
+        instruction: str,
+        truth: str,
+        datapoint: list[str],
+        data_type: Literal["media", "text"] = "media",
+        context: str | None = None,
+        media_context: str | None = None,
+        explanation: str | 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 (str, optional): The media context is a link to an image / video that will be shown in addition to the instruction (can be combined with context). Defaults to None.
+            explanation (str, optional): The explanation that will be shown to the labeler if the answer is wrong. Defaults to None.
+        """
+        from rapidata.api_client.models.add_rapid_to_audience_model import (
+            AddRapidToAudienceModel,
+        )
+
+        payload = IRapidPayload(
+            actual_instance=IRapidPayloadComparePayload(
+                _t="ComparePayload", criteria=instruction
+            )
+        )
+        model_truth = IValidationTruth(
+            actual_instance=IValidationTruthCompareTruth(
+                _t="CompareTruth", winnerId=truth
+            )
+        )
+
+        if data_type == "media":
+            asset_input = self._asset_uploader.get_uploaded_asset_input(datapoint)
+        else:
+            asset_input = self._asset_uploader.get_uploaded_text_input(datapoint)
+
+        if len(datapoint) != 2:
+            raise ValueError("Compare rapid requires exactly two media paths")
+
+        self._openapi_service.audience_api.audience_audience_id_rapid_post(
+            audience_id=self._audience_id,
+            add_rapid_to_audience_model=AddRapidToAudienceModel(
+                asset=asset_input,
+                payload=payload,
+                truth=model_truth,
+                context=context,
+                contextAsset=(
+                    self._asset_uploader.get_uploaded_asset_input(media_context)
+                    if media_context
+                    else None
+                ),
+                explanation=explanation,
+                randomCorrectProbability=0.5,
+            ),
+        )
+
+    def __str__(self) -> str:
+        return "RapidsManager"
+
+    def __repr__(self) -> str:
+        return self.__str__()

rapidata/rapidata_client/audience/rapidata_audience.py

@@ -0,0 +1,287 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+from rapidata.rapidata_client.config import logger, tracer, rapidata_config
+from rapidata.rapidata_client.audience.audience_example_handler import (
+    AudienceExampleHandler,
+)
+
+if TYPE_CHECKING:
+    from rapidata.service.openapi_service import OpenAPIService
+    from rapidata.rapidata_client.filter import RapidataFilter
+    from rapidata.rapidata_client.job.job_definition import (
+        JobDefinition,
+    )
+    from rapidata.rapidata_client.job.rapidata_job import RapidataJob
+
+
+class RapidataAudience:
+    """Represents a Rapidata audience.
+
+    An audience is a group of annotators that can be recruited based on example tasks and assigned jobs.
+
+    Attributes:
+        id (str): The unique identifier of the audience.
+        name (str): The name of the audience.
+        filters (list[RapidataFilter]): The list of filters applied to the audience.
+    """
+
+    def __init__(
+        self,
+        id: str,
+        name: str,
+        filters: list[RapidataFilter],
+        openapi_service: OpenAPIService,
+    ):
+        self.id = id
+        self._name = name
+        self._filters = filters
+        self._openapi_service = openapi_service
+        self._example_handler = AudienceExampleHandler(openapi_service, id)
+
+    @property
+    def name(self) -> str:
+        """The name of the audience."""
+        return self._name
+
+    @property
+    def filters(self) -> list[RapidataFilter]:
+        """The list of filters applied to the audience."""
+        return self._filters
+
+    def update_filters(self, filters: list[RapidataFilter]) -> RapidataAudience:
+        """Update the filters for this audience.
+
+        Args:
+            filters (list[RapidataFilter]): The new list of filters to apply to the audience.
+
+        Returns:
+            RapidataAudience: The updated audience instance (self) for method chaining.
+        """
+        with tracer.start_as_current_span("RapidataAudience.update_filters"):
+            from rapidata.api_client.models.update_audience_request import (
+                UpdateAudienceRequest,
+            )
+
+            logger.debug(f"Updating filters for audience: {self.id} to {filters}")
+            self._openapi_service.audience_api.audience_audience_id_patch(
+                audience_id=self.id,
+                update_audience_request=UpdateAudienceRequest(
+                    filters=[filter._to_audience_model() for filter in filters],
+                ),
+            )
+            self._filters = filters
+            return self
+
+    def update_name(self, name: str) -> RapidataAudience:
+        """Update the name of this audience.
+
+        Args:
+            name (str): The new name for the audience.
+
+        Returns:
+            RapidataAudience: The updated audience instance (self) for method chaining.
+        """
+        with tracer.start_as_current_span("RapidataAudience.update_name"):
+            from rapidata.api_client.models.update_audience_request import (
+                UpdateAudienceRequest,
+            )
+
+            logger.debug(f"Updating name for audience: {self.id} to {name}")
+            self._openapi_service.audience_api.audience_audience_id_patch(
+                audience_id=self.id,
+                update_audience_request=UpdateAudienceRequest(name=name),
+            )
+            self._name = name
+            return self
+
+    def start_recruiting(self) -> RapidataAudience:
+        """Start recruiting annotators for this audience.
+
+        This will begin the process of onboarding annotators for this audience.
+
+        Returns:
+            RapidataAudience: The audience instance (self) for method chaining.
+        """
+        with tracer.start_as_current_span("RapidataAudience.start_recruiting"):
+            logger.debug(f"Sending request to start recruiting for audience: {self.id}")
+            self._openapi_service.audience_api.audience_audience_id_recruit_post(
+                audience_id=self.id,
+            )
+            logger.info(f"Started recruiting for audience: {self.id}")
+            return self
+
+    def assign_job(self, job_definition: JobDefinition) -> RapidataJob:
+        """Assign a job to this audience.
+
+        Creates a new job instance from the job definition and assigns it to this audience.
+        The job will be executed by the annotators in this audience.
+
+        Args:
+            job_definition (JobDefinition): The job definition to create and assign to the audience.
+
+        Returns:
+            RapidataJob: The created job instance.
+        """
+        with tracer.start_as_current_span("RapidataAudience.assign_job"):
+            from rapidata.api_client.models.create_job_endpoint_input import (
+                CreateJobEndpointInput,
+            )
+            from rapidata.rapidata_client.job.rapidata_job import RapidataJob
+
+            logger.debug(f"Assigning job to audience: {self.id}")
+            response = self._openapi_service.job_api.job_post(
+                create_job_endpoint_input=CreateJobEndpointInput(
+                    audienceId=self.id,
+                    jobDefinitionId=job_definition._id,
+                ),
+            )
+            job = RapidataJob(
+                response.job_id, job_definition._name, self._openapi_service
+            )
+            logger.info(f"Assigned job to audience: {self.id}")
+            return job
+
+    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: str | None = None,
+        explanation: str | None = None,
+    ) -> RapidataAudience:
+        """Add a classification training example to this audience.
+
+        Training examples help annotators understand the task by showing them
+        a sample datapoint with the correct answer before they start labeling.
+
+        Args:
+            instruction (str): The instruction for how the data should be classified.
+            answer_options (list[str]): The list of possible answer options for the classification.
+            datapoint (str): The datapoint (URL or path) to use as the training example.
+            truth (list[str]): The correct answer(s) for this training example.
+            data_type (Literal["media", "text"], optional): The data type of the datapoint. Defaults to "media".
+            context (str, optional): Additional text context to display with the example. Defaults to None.
+            media_context (str, optional): Additional media (URL or path) to display with the example. Defaults to None.
+            explanation (str, optional): An explanation of why the truth is correct. Defaults to None.
+
+        Returns:
+            RapidataAudience: The audience instance (self) for method chaining.
+        """
+        with tracer.start_as_current_span(
+            "RapidataAudience.add_classification_example"
+        ):
+            logger.debug(
+                f"Adding classification example to audience: {self.id} with instruction: {instruction}, answer_options: {answer_options}, datapoint: {datapoint}, truths: {truth}, data_type: {data_type}, context: {context}, media_context: {media_context}, explanation: {explanation}"
+            )
+            self._example_handler.add_classification_example(
+                instruction,
+                answer_options,
+                datapoint,
+                truth,
+                data_type,
+                context,
+                media_context,
+                explanation,
+            )
+            return self
+
+    def add_compare_example(
+        self,
+        instruction: str,
+        truth: str,
+        datapoint: list[str],
+        data_type: Literal["media", "text"] = "media",
+        context: str | None = None,
+        media_context: str | None = None,
+        explanation: str | None = None,
+    ) -> RapidataAudience:
+        """Add a comparison training example to this audience.
+
+        Training examples help annotators understand the task by showing them
+        a sample comparison with the correct answer before they start labeling.
+
+        Args:
+            instruction (str): The instruction for the comparison task.
+            truth (str): The correct answer for this training example (which option should be selected).
+            datapoint (list[str]): A list of exactly two datapoints (URLs or paths) to compare.
+            data_type (Literal["media", "text"], optional): The data type of the datapoints. Defaults to "media".
+            context (str, optional): Additional text context to display with the example. Defaults to None.
+            media_context (str, optional): Additional media (URL or path) to display with the example. Defaults to None.
+            explanation (str, optional): An explanation of why the truth is correct. Defaults to None.
+
+        Returns:
+            RapidataAudience: The audience instance (self) for method chaining.
+        """
+        with tracer.start_as_current_span("RapidataAudience.add_compare_example"):
+            logger.debug(
+                f"Adding compare example to audience: {self.id} with instruction: {instruction}, truth: {truth}, datapoint: {datapoint}, data_type: {data_type}, context: {context}, media_context: {media_context}, explanation: {explanation}"
+            )
+            self._example_handler.add_compare_example(
+                instruction,
+                truth,
+                datapoint,
+                data_type,
+                context,
+                media_context,
+                explanation,
+            )
+            return self
+
+    def find_jobs(self, name: str = "", amount: int = 10) -> list[RapidataJob]:
+        """Find jobs assigned to this audience.
+
+        Args:
+            name (str, optional): Filter jobs by name (matching jobs will contain this string). Defaults to "" for any job.
+            amount (int, optional): The maximum number of jobs to return. Defaults to 10.
+
+        Returns:
+            list[RapidataJob]: A list of RapidataJob instances assigned to this audience.
+        """
+        with tracer.start_as_current_span("RapidataAudience.find_jobs"):
+            from rapidata.rapidata_client.job.rapidata_job import RapidataJob
+            from rapidata.api_client.models.query_model import QueryModel
+            from rapidata.api_client.models.root_filter import RootFilter
+            from rapidata.api_client.models.filter import Filter
+            from rapidata.api_client.models.filter_operator import FilterOperator
+            from rapidata.api_client.models.page_info import PageInfo
+            from rapidata.api_client.models.sort_criterion import SortCriterion
+            from rapidata.api_client.models.sort_direction import SortDirection
+
+            response = self._openapi_service.job_api.jobs_get(
+                request=QueryModel(
+                    page=PageInfo(index=1, size=amount),
+                    filter=RootFilter(
+                        filters=[
+                            Filter(
+                                field="AudienceId",
+                                operator=FilterOperator.EQ,
+                                value=self.id,
+                            ),
+                            Filter(
+                                field="Name",
+                                operator=FilterOperator.CONTAINS,
+                                value=name,
+                            ),
+                        ]
+                    ),
+                    sortCriteria=[
+                        SortCriterion(
+                            direction=SortDirection.DESC, propertyName="CreatedAt"
+                        )
+                    ],
+                ),
+            )
+            return [
+                RapidataJob(job.job_id, job.name, self._openapi_service)
+                for job in response.items
+            ]
+
+    def __str__(self) -> str:
+        return f"RapidataAudience(id={self.id}, name={self._name}, filters={self._filters})"
+
+    def __repr__(self) -> str:
+        return self.__str__()