Skip to content

Label module

Queries

Set of Label queries.

Source code in kili/entrypoints/queries/label/__init__.py
class QueriesLabel:
    """Set of Label queries."""

    # pylint: disable=too-many-arguments,too-many-locals,dangerous-default-value

    def __init__(self, auth: KiliAuth):
        """Initialize the subclass.

        Args:
            auth: KiliAuth object
        """
        self.auth = auth

    @overload
    def labels(
        self,
        project_id: str,
        asset_id: Optional[str] = None,
        asset_status_in: Optional[List[str]] = None,
        asset_external_id_in: Optional[List[str]] = None,
        author_in: Optional[List[str]] = None,
        created_at: Optional[str] = None,
        created_at_gte: Optional[str] = None,
        created_at_lte: Optional[str] = None,
        fields: List[str] = [
            "author.email",
            "author.id",
            "id",
            "jsonResponse",
            "labelType",
            "secondsToLabel",
        ],
        first: Optional[int] = None,
        honeypot_mark_gte: Optional[float] = None,
        honeypot_mark_lte: Optional[float] = None,
        id_contains: Optional[List[str]] = None,
        label_id: Optional[str] = None,
        skip: int = 0,
        type_in: Optional[List[str]] = None,
        user_id: Optional[str] = None,
        disable_tqdm: bool = False,
        category_search: Optional[str] = None,
        output_format: Literal["dict"] = "dict",
        *,
        as_generator: Literal[True],
    ) -> Generator[Dict, None, None]:
        ...

    @overload
    def labels(
        self,
        project_id: str,
        asset_id: Optional[str] = None,
        asset_status_in: Optional[List[str]] = None,
        asset_external_id_in: Optional[List[str]] = None,
        author_in: Optional[List[str]] = None,
        created_at: Optional[str] = None,
        created_at_gte: Optional[str] = None,
        created_at_lte: Optional[str] = None,
        fields: List[str] = [
            "author.email",
            "author.id",
            "id",
            "jsonResponse",
            "labelType",
            "secondsToLabel",
        ],
        first: Optional[int] = None,
        honeypot_mark_gte: Optional[float] = None,
        honeypot_mark_lte: Optional[float] = None,
        id_contains: Optional[List[str]] = None,
        label_id: Optional[str] = None,
        skip: int = 0,
        type_in: Optional[List[str]] = None,
        user_id: Optional[str] = None,
        disable_tqdm: bool = False,
        category_search: Optional[str] = None,
        output_format: Literal["dict"] = "dict",
        *,
        as_generator: Literal[False] = False,
    ) -> List[Dict]:
        ...

    @overload
    def labels(
        self,
        project_id: str,
        asset_id: Optional[str] = None,
        asset_status_in: Optional[List[str]] = None,
        asset_external_id_in: Optional[List[str]] = None,
        author_in: Optional[List[str]] = None,
        created_at: Optional[str] = None,
        created_at_gte: Optional[str] = None,
        created_at_lte: Optional[str] = None,
        fields: List[str] = [
            "author.email",
            "author.id",
            "id",
            "jsonResponse",
            "labelType",
            "secondsToLabel",
        ],
        first: Optional[int] = None,
        honeypot_mark_gte: Optional[float] = None,
        honeypot_mark_lte: Optional[float] = None,
        id_contains: Optional[List[str]] = None,
        label_id: Optional[str] = None,
        skip: int = 0,
        type_in: Optional[List[str]] = None,
        user_id: Optional[str] = None,
        disable_tqdm: bool = False,
        category_search: Optional[str] = None,
        output_format: Literal["parsed_label"] = "parsed_label",
        *,
        as_generator: Literal[False] = False,
    ) -> List[ParsedLabel]:
        ...

    @overload
    def labels(
        self,
        project_id: str,
        asset_id: Optional[str] = None,
        asset_status_in: Optional[List[str]] = None,
        asset_external_id_in: Optional[List[str]] = None,
        author_in: Optional[List[str]] = None,
        created_at: Optional[str] = None,
        created_at_gte: Optional[str] = None,
        created_at_lte: Optional[str] = None,
        fields: List[str] = [
            "author.email",
            "author.id",
            "id",
            "jsonResponse",
            "labelType",
            "secondsToLabel",
        ],
        first: Optional[int] = None,
        honeypot_mark_gte: Optional[float] = None,
        honeypot_mark_lte: Optional[float] = None,
        id_contains: Optional[List[str]] = None,
        label_id: Optional[str] = None,
        skip: int = 0,
        type_in: Optional[List[str]] = None,
        user_id: Optional[str] = None,
        disable_tqdm: bool = False,
        category_search: Optional[str] = None,
        output_format: Literal["parsed_label"] = "parsed_label",
        *,
        as_generator: Literal[True] = True,
    ) -> Generator[ParsedLabel, None, None]:
        ...

    @typechecked
    def labels(
        self,
        project_id: str,
        asset_id: Optional[str] = None,
        asset_status_in: Optional[List[str]] = None,
        asset_external_id_in: Optional[List[str]] = None,
        author_in: Optional[List[str]] = None,
        created_at: Optional[str] = None,
        created_at_gte: Optional[str] = None,
        created_at_lte: Optional[str] = None,
        fields: List[str] = [
            "author.email",
            "author.id",
            "id",
            "jsonResponse",
            "labelType",
            "secondsToLabel",
        ],
        first: Optional[int] = None,
        honeypot_mark_gte: Optional[float] = None,
        honeypot_mark_lte: Optional[float] = None,
        id_contains: Optional[List[str]] = None,
        label_id: Optional[str] = None,
        skip: int = 0,
        type_in: Optional[List[str]] = None,
        user_id: Optional[str] = None,
        disable_tqdm: bool = False,
        category_search: Optional[str] = None,
        output_format: Literal["dict", "parsed_label"] = "dict",
        *,
        as_generator: bool = False,
    ) -> Iterable[Union[Dict, ParsedLabel]]:
        # pylint: disable=line-too-long
        """Get a label list or a label generator from a project based on a set of criteria.

        Args:
            project_id: Identifier of the project.
            asset_id: Identifier of the asset.
            asset_status_in: Returned labels should have a status that belongs to that list, if given.
                Possible choices : `TODO`, `ONGOING`, `LABELED`, `TO REVIEW` or `REVIEWED`.
            asset_external_id_in: Returned labels should have an external id that belongs to that list, if given.
            author_in: Returned labels should have been made by authors in that list, if given.
                An author can be designated by the first name, the last name, or the first name + last name.
            created_at: Returned labels should have their creation date equal to this date.
            created_at_gte: Returned labels should have their creation date greater or equal to this date.
            created_at_lte: Returned labels should have their creation date lower or equal to this date.
            fields: All the fields to request among the possible fields for the labels.
                See [the documentation](https://docs.kili-technology.com/reference/graphql-api#label) for all possible fields.
            first: Maximum number of labels to return.
            honeypot_mark_gte: Returned labels should have a label whose honeypot is greater than this number.
            honeypot_mark_lte: Returned labels should have a label whose honeypot is lower than this number.
            id_contains: Filters out labels not belonging to that list. If empty, no filtering is applied.
            label_id: Identifier of the label.
            skip: Number of labels to skip (they are ordered by their date of creation, first to last).
            type_in: Returned labels should have a label whose type belongs to that list, if given.
            user_id: Identifier of the user.
            disable_tqdm: If `True`, the progress bar will be disabled.
            as_generator: If `True`, a generator on the labels is returned.
            category_search: Query to filter labels based on the content of their jsonResponse.
            output_format: If `dict`, the output is an iterable of Python dictionaries.
                If `parsed_label`, the output is an iterable of parsed labels objects. More information on parsed labels in the [documentation](https://python-sdk-docs.kili-technology.com/latest/sdk/tutorials/label_parsing/).

        !!! info "Dates format"
            Date strings should have format: "YYYY-MM-DD"

        Returns:
            A result object which contains the query if it was successful, else an error message.

        Examples:
            >>> kili.labels(project_id=project_id, fields=['jsonResponse', 'labelOf.externalId']) # returns a list of all labels of a project and their assets external ID
            >>> kili.labels(project_id=project_id, fields=['jsonResponse'], as_generator=True) # returns a generator of all labels of a project

        !!! example "How to filter based on label categories"
            The search query is composed of logical expressions following this format:

                [job_name].[category_name].count [comparaison_operator] [value]
            where:

            - `[job_name]` is the name of the job in the interface
            - `[category_name]` is the name of the category in the interface for this job
            - `[comparaison_operator]` can be one of: [`==`, `>=`, `<=`, `<`, `>`]
            - `[value]` is an integer that represents the count of such objects of the given category in the label

            These operations can be separated by OR and AND operators

            Example:

                category_search = `JOB_CLASSIF.CATEGORY_A.count > 0`
                category_search = `JOB_CLASSIF.CATEGORY_A.count > 0 OR JOB_NER.CATEGORY_B.count > 0`
                category_search = `(JOB_CLASSIF.CATEGORY_A.count > 0 OR JOB_NER.CATEGORY_B.count > 0) AND JOB_BBOX.CATEGORY_C.count > 10`
        """
        if category_search:
            validate_category_search_query(category_search)

        where = LabelWhere(
            project_id=project_id,
            asset_id=asset_id,
            asset_status_in=asset_status_in,
            asset_external_id_in=asset_external_id_in,
            author_in=author_in,
            created_at=created_at,
            created_at_gte=created_at_gte,
            created_at_lte=created_at_lte,
            honeypot_mark_gte=honeypot_mark_gte,
            honeypot_mark_lte=honeypot_mark_lte,
            id_contains=id_contains,
            label_id=label_id,
            type_in=type_in,
            user_id=user_id,
            category_search=category_search,
        )

        post_call_function = None
        if output_format == "parsed_label":
            if "jsonResponse" not in fields:
                raise ValueError(
                    "The field 'jsonResponse' is required to parse labels. Please add it to the"
                    " 'fields' argument."
                )

            project = next(
                ProjectQuery(self.auth.client)(
                    ProjectWhere(project_id=project_id),
                    fields=["jsonInterface", "inputType"],
                    options=QueryOptions(disable_tqdm=True, first=1, skip=0),
                )
            )
            post_call_function = partial(
                parse_labels,
                json_interface=project["jsonInterface"],
                input_type=project["inputType"],
            )

        disable_tqdm = disable_tqdm_if_as_generator(as_generator, disable_tqdm)
        options = QueryOptions(disable_tqdm, first, skip)
        labels_gen = LabelQuery(self.auth.client)(where, fields, options, post_call_function)

        if as_generator:
            return labels_gen
        return list(labels_gen)

    @overload
    def predictions(
        self,
        project_id: str,
        asset_id: Optional[str] = None,
        asset_status_in: Optional[List[str]] = None,
        asset_external_id_in: Optional[List[str]] = None,
        author_in: Optional[List[str]] = None,
        created_at: Optional[str] = None,
        created_at_gte: Optional[str] = None,
        created_at_lte: Optional[str] = None,
        fields: Optional[List[str]] = None,
        first: Optional[int] = None,
        honeypot_mark_gte: Optional[float] = None,
        honeypot_mark_lte: Optional[float] = None,
        id_contains: Optional[List[str]] = None,
        label_id: Optional[str] = None,
        skip: int = 0,
        user_id: Optional[str] = None,
        disable_tqdm: bool = False,
        category_search: Optional[str] = None,
        *,
        as_generator: Literal[True],
    ) -> Generator[Dict, None, None]:
        ...

    @overload
    def predictions(
        self,
        project_id: str,
        asset_id: Optional[str] = None,
        asset_status_in: Optional[List[str]] = None,
        asset_external_id_in: Optional[List[str]] = None,
        author_in: Optional[List[str]] = None,
        created_at: Optional[str] = None,
        created_at_gte: Optional[str] = None,
        created_at_lte: Optional[str] = None,
        fields: Optional[List[str]] = None,
        first: Optional[int] = None,
        honeypot_mark_gte: Optional[float] = None,
        honeypot_mark_lte: Optional[float] = None,
        id_contains: Optional[List[str]] = None,
        label_id: Optional[str] = None,
        skip: int = 0,
        user_id: Optional[str] = None,
        disable_tqdm: bool = False,
        category_search: Optional[str] = None,
        *,
        as_generator: Literal[False] = False,
    ) -> List[Dict]:
        ...

    @typechecked
    def predictions(
        self,
        project_id: str,
        asset_id: Optional[str] = None,
        asset_status_in: Optional[List[str]] = None,
        asset_external_id_in: Optional[List[str]] = None,
        author_in: Optional[List[str]] = None,
        created_at: Optional[str] = None,
        created_at_gte: Optional[str] = None,
        created_at_lte: Optional[str] = None,
        fields: Optional[List[str]] = None,
        first: Optional[int] = None,
        honeypot_mark_gte: Optional[float] = None,
        honeypot_mark_lte: Optional[float] = None,
        id_contains: Optional[List[str]] = None,
        label_id: Optional[str] = None,
        skip: int = 0,
        user_id: Optional[str] = None,
        disable_tqdm: bool = False,
        category_search: Optional[str] = None,
        *,
        as_generator: bool = False,
    ) -> Iterable[Dict]:
        # pylint: disable=line-too-long
        """Get prediction labels from a project based on a set of criteria.

        This method is equivalent to the `kili.labels()` method, but it only returns label of type "PREDICTION".

        Args:
            project_id: Identifier of the project.
            asset_id: Identifier of the asset.
            asset_status_in: Returned labels should have a status that belongs to that list, if given.
                Possible choices : `TODO`, `ONGOING`, `LABELED`, `TO REVIEW` or `REVIEWED`
            asset_external_id_in: Returned labels should have an external id that belongs to that list, if given.
            author_in: Returned labels should have been made by authors in that list, if given.
                An author can be designated by the first name, the last name, or the first name + last name.
            created_at: Returned labels should have a label whose creation date is equal to this date.
            created_at_gte: Returned labels should have a label whose creation date is greater than this date.
            created_at_lte: Returned labels should have a label whose creation date is lower than this date.
            fields: All the fields to request among the possible fields for the labels.
                See [the documentation](https://docs.kili-technology.com/reference/graphql-api#label) for all possible fields.
            first: Maximum number of labels to return.
            honeypot_mark_gte: Returned labels should have a label whose honeypot is greater than this number.
            honeypot_mark_lte: Returned labels should have a label whose honeypot is lower than this number.
            id_contains: Filters out labels not belonging to that list. If empty, no filtering is applied.
            label_id: Identifier of the label.
            skip: Number of labels to skip (they are ordered by their date of creation, first to last).
            user_id: Identifier of the user.
            disable_tqdm: If `True`, the progress bar will be disabled
            as_generator: If `True`, a generator on the labels is returned.
            category_search: Query to filter labels based on the content of their jsonResponse

        Returns:
            A result object which contains the query if it was successful, else an error message.

        Examples:
            >>> kili.predictions(project_id=project_id) # returns a list of prediction labels of a project
        """
        if fields is None:
            fields = [
                "author.email",
                "author.id",
                "id",
                "jsonResponse",
                "labelType",
                "modelName",
            ]
        return self.labels(
            project_id=project_id,
            asset_id=asset_id,
            asset_status_in=asset_status_in,
            asset_external_id_in=asset_external_id_in,
            author_in=author_in,
            created_at=created_at,
            created_at_gte=created_at_gte,
            created_at_lte=created_at_lte,
            fields=fields,
            first=first,
            honeypot_mark_gte=honeypot_mark_gte,
            honeypot_mark_lte=honeypot_mark_lte,
            id_contains=id_contains,
            label_id=label_id,
            skip=skip,
            type_in=["PREDICTION"],
            user_id=user_id,
            disable_tqdm=disable_tqdm,
            category_search=category_search,
            as_generator=as_generator,  # type: ignore
        )

    @overload
    def inferences(
        self,
        project_id: str,
        asset_id: Optional[str] = None,
        asset_status_in: Optional[List[str]] = None,
        asset_external_id_in: Optional[List[str]] = None,
        author_in: Optional[List[str]] = None,
        created_at: Optional[str] = None,
        created_at_gte: Optional[str] = None,
        created_at_lte: Optional[str] = None,
        fields: Optional[List[str]] = None,
        first: Optional[int] = None,
        honeypot_mark_gte: Optional[float] = None,
        honeypot_mark_lte: Optional[float] = None,
        id_contains: Optional[List[str]] = None,
        label_id: Optional[str] = None,
        skip: int = 0,
        user_id: Optional[str] = None,
        disable_tqdm: bool = False,
        category_search: Optional[str] = None,
        *,
        as_generator: Literal[True],
    ) -> Generator[Dict, None, None]:
        ...

    @overload
    def inferences(
        self,
        project_id: str,
        asset_id: Optional[str] = None,
        asset_status_in: Optional[List[str]] = None,
        asset_external_id_in: Optional[List[str]] = None,
        author_in: Optional[List[str]] = None,
        created_at: Optional[str] = None,
        created_at_gte: Optional[str] = None,
        created_at_lte: Optional[str] = None,
        fields: Optional[List[str]] = None,
        first: Optional[int] = None,
        honeypot_mark_gte: Optional[float] = None,
        honeypot_mark_lte: Optional[float] = None,
        id_contains: Optional[List[str]] = None,
        label_id: Optional[str] = None,
        skip: int = 0,
        user_id: Optional[str] = None,
        disable_tqdm: bool = False,
        category_search: Optional[str] = None,
        *,
        as_generator: Literal[False] = False,
    ) -> List[Dict]:
        ...

    @typechecked
    def inferences(
        self,
        project_id: str,
        asset_id: Optional[str] = None,
        asset_status_in: Optional[List[str]] = None,
        asset_external_id_in: Optional[List[str]] = None,
        author_in: Optional[List[str]] = None,
        created_at: Optional[str] = None,
        created_at_gte: Optional[str] = None,
        created_at_lte: Optional[str] = None,
        fields: Optional[List[str]] = None,
        first: Optional[int] = None,
        honeypot_mark_gte: Optional[float] = None,
        honeypot_mark_lte: Optional[float] = None,
        id_contains: Optional[List[str]] = None,
        label_id: Optional[str] = None,
        skip: int = 0,
        user_id: Optional[str] = None,
        disable_tqdm: bool = False,
        category_search: Optional[str] = None,
        *,
        as_generator: bool = False,
    ) -> Iterable[Dict]:
        # pylint: disable=line-too-long
        """Get inference labels from a project based on a set of criteria.

        This method is equivalent to the `kili.labels()` method, but it only returns label of type "INFERENCE".

        Args:
            project_id: Identifier of the project.
            asset_id: Identifier of the asset.
            asset_status_in: Returned labels should have a status that belongs to that list, if given.
                Possible choices : `TODO`, `ONGOING`, `LABELED`, `TO REVIEW` or `REVIEWED`
            asset_external_id_in: Returned labels should have an external id that belongs to that list, if given.
            author_in: Returned labels should have been made by authors in that list, if given.
                An author can be designated by the first name, the last name, or the first name + last name.
            created_at: Returned labels should have a label whose creation date is equal to this date.
            created_at_gte: Returned labels should have a label whose creation date is greater than this date.
            created_at_lte: Returned labels should have a label whose creation date is lower than this date.
            fields: All the fields to request among the possible fields for the labels.
                See [the documentation](https://docs.kili-technology.com/reference/graphql-api#label) for all possible fields.
            first: Maximum number of labels to return.
            honeypot_mark_gte: Returned labels should have a label whose honeypot is greater than this number.
            honeypot_mark_lte: Returned labels should have a label whose honeypot is lower than this number.
            id_contains: Filters out labels not belonging to that list. If empty, no filtering is applied.
            label_id: Identifier of the label.
            skip: Number of labels to skip (they are ordered by their date of creation, first to last).
            user_id: Identifier of the user.
            disable_tqdm: If `True`, the progress bar will be disabled
            as_generator: If `True`, a generator on the labels is returned.
            category_search: Query to filter labels based on the content of their jsonResponse

        Returns:
            A result object which contains the query if it was successful, else an error message.

        Examples:
            >>> kili.inferences(project_id=project_id) # returns a list of inference labels of a project
        """
        if fields is None:
            fields = [
                "author.email",
                "author.id",
                "id",
                "jsonResponse",
                "labelType",
                "modelName",
            ]
        return self.labels(
            project_id=project_id,
            asset_id=asset_id,
            asset_status_in=asset_status_in,
            asset_external_id_in=asset_external_id_in,
            author_in=author_in,
            created_at=created_at,
            created_at_gte=created_at_gte,
            created_at_lte=created_at_lte,
            fields=fields,
            first=first,
            honeypot_mark_gte=honeypot_mark_gte,
            honeypot_mark_lte=honeypot_mark_lte,
            id_contains=id_contains,
            label_id=label_id,
            skip=skip,
            type_in=["INFERENCE"],
            user_id=user_id,
            disable_tqdm=disable_tqdm,
            category_search=category_search,
            as_generator=as_generator,  # type: ignore
        )

    @typechecked
    def export_labels_as_df(
        self,
        project_id: str,
        fields: List[str] = [
            "author.email",
            "author.id",
            "createdAt",
            "id",
            "labelType",
        ],
        asset_fields: List[str] = ["externalId"],
    ) -> pd.DataFrame:
        # pylint: disable=line-too-long
        """Get the labels of a project as a pandas DataFrame.

        Args:
            project_id: Identifier of the project
            fields: All the fields to request among the possible fields for the labels.
                See [the documentation](https://docs.kili-technology.com/reference/graphql-api#label) for all possible fields.
            asset_fields: All the fields to request among the possible fields for the assets.
                See [the documentation](https://docs.kili-technology.com/reference/graphql-api#asset) for all possible fields.

        Returns:
            pandas DataFrame containing the labels.
        """

        services.get_project(self.auth, project_id, ["id"])
        assets_gen = AssetQuery(self.auth.client)(
            AssetWhere(project_id=project_id),
            asset_fields + ["labels." + field for field in fields],
            QueryOptions(disable_tqdm=False),
        )
        labels = [
            dict(
                label,
                **{f"asset_{key}": asset[key] for key in asset if key != "labels"},
            )
            for asset in assets_gen
            for label in asset["labels"]
        ]
        labels_df = pd.DataFrame(labels)
        return labels_df

    @typechecked
    def count_labels(
        self,
        project_id: str,
        asset_id: Optional[str] = None,
        asset_status_in: Optional[List[str]] = None,
        asset_external_id_in: Optional[List[str]] = None,
        author_in: Optional[List[str]] = None,
        created_at: Optional[str] = None,
        created_at_gte: Optional[str] = None,
        created_at_lte: Optional[str] = None,
        honeypot_mark_gte: Optional[float] = None,
        honeypot_mark_lte: Optional[float] = None,
        label_id: Optional[str] = None,
        type_in: Optional[List[str]] = None,
        user_id: Optional[str] = None,
        category_search: Optional[str] = None,
        id_contains: Optional[List[str]] = None,
    ) -> int:
        # pylint: disable=line-too-long
        """Get the number of labels for the given parameters.

        Args:
            project_id: Identifier of the project.
            asset_id: Identifier of the asset.
            asset_status_in: Returned labels should have a status that belongs to that list, if given.
                Possible choices : `TODO`, `ONGOING`, `LABELED` or `REVIEWED`
            asset_external_id_in: Returned labels should have an external id that belongs to that list, if given.
            author_in: Returned labels should have been made by authors in that list, if given.
                An author can be designated by the first name, the last name, or the first name + last name.
            created_at: Returned labels should have a label whose creation date is equal to this date.
            created_at_gte: Returned labels should have a label whose creation date is greater than this date.
            created_at_lte: Returned labels should have a label whose creation date is lower than this date.
            honeypot_mark_gte: Returned labels should have a label whose honeypot is greater than this number.
            honeypot_mark_lte: Returned labels should have a label whose honeypot is lower than this number.
            label_id: Identifier of the label.
            type_in: Returned labels should have a label whose type belongs to that list, if given.
            user_id: Identifier of the user.
            category_search: Query to filter labels based on the content of their jsonResponse
            id_contains: Filters out labels not belonging to that list. If empty, no filtering is applied.

        !!! info "Dates format"
            Date strings should have format: "YYYY-MM-DD"

        Returns:
            The number of labels with the parameters provided
        """
        if category_search:
            validate_category_search_query(category_search)

        where = LabelWhere(
            project_id=project_id,
            asset_id=asset_id,
            asset_status_in=asset_status_in,
            asset_external_id_in=asset_external_id_in,
            author_in=author_in,
            created_at=created_at,
            created_at_gte=created_at_gte,
            created_at_lte=created_at_lte,
            honeypot_mark_gte=honeypot_mark_gte,
            honeypot_mark_lte=honeypot_mark_lte,
            id_contains=id_contains,
            label_id=label_id,
            type_in=type_in,
            user_id=user_id,
            category_search=category_search,
        )
        return LabelQuery(self.auth.client).count(where)

    def export_labels(
        self,
        project_id: str,
        filename: str,
        fmt: LabelFormat,
        asset_ids: Optional[List[str]] = None,
        layout: SplitOption = "split",
        single_file: bool = False,
        disable_tqdm: bool = False,
        with_assets: bool = True,
        external_ids: Optional[List[str]] = None,
        annotation_modifier: Optional[CocoAnnotationModifier] = None,
        asset_filter_kwargs: Optional[Dict[str, object]] = None,
    ) -> None:
        # pylint: disable=line-too-long
        """Export the project labels with the requested format into the requested output path.

        Args:
            project_id: Identifier of the project.
            filename: Relative or full path of the archive that will contain
                the exported data.
            fmt: Format of the exported labels.
            asset_ids: Optional list of the assets internal IDs from which to export the labels.
            layout: Layout of the exported files. "split" means there is one folder
                per job, "merged" that there is one folder with every labels.
            single_file: Layout of the exported labels. Single file mode is
                only available for some specific formats (COCO and Kili).
            disable_tqdm: Disable the progress bar if True.
            with_assets: Download the assets in the export.
            external_ids: Optional list of the assets external IDs from which to export the labels.
            annotation_modifier: (For COCO export only) function that takes the COCO annotation, the
                COCO image, and the Kili annotation, and should return an updated COCO annotation.
                This can be used if you want to add a new attribute to the COCO annotation. For
                example, you can add a method that computes if the annotation is a rectangle or not
                and add it to the COCO annotation (see example).
            asset_filter_kwargs: Optional dictionary of arguments to pass to `kili.assets()` in order to filter the assets the labels are exported from. The supported arguments are:

                - `consensus_mark_gte`
                - `consensus_mark_lte`
                - `external_id_strictly_in`
                - `external_id_in`
                - `honeypot_mark_gte`
                - `honeypot_mark_lte`
                - `label_author_in`
                - `label_reviewer_in`
                - `skipped`
                - `status_in`
                - `label_category_search`
                - `created_at_gte`
                - `created_at_lte`
                - `issue_type`
                - `issue_status`
                - `inference_mark_gte`
                - `inference_mark_lte`
                - `metadata_where`

                See the documentation of [`kili.assets()`](https://python-sdk-docs.kili-technology.com/latest/sdk/asset/#kili.queries.asset.__init__.QueriesAsset.assets) for more information.

        !!! Info
            The supported formats are:

            - Yolo V4, V5, V7 for object detection tasks (bounding box).
            - Kili (a.k.a raw) for all tasks.
            - COCO for object detection tasks (bounding box and semantic segmentation).
            - Pascal VOC for object detection tasks (bounding box).

        !!! warning "Cloud storage"
            Export with asset download (`with_assets=True`) is not allowed for projects connected to a cloud storage.
            As they require an access to the assets to read their dimension, the COCO and Pascal VOC formats are not
            allowed in this case.

        !!! Example
            ```python
            kili.export_labels("your_project_id", "export.zip", "yolo_v4")
            ```

        !!! Example
            ```python
            def is_rectangle(coco_annotation, coco_image, kili_annotation):
                is_rectangle = ...
                return {**coco_annotation, "attributes": {"is_rectangle": is_rectangle}}

            kili.export_labels(
                "your_project_id",
                "export.zip",
                "coco",
                annotation_modifier=add_is_rectangle
            )
            ```
        """
        if external_ids is not None and asset_ids is None:
            id_map = infer_ids_from_external_ids(
                auth=self.auth, asset_external_ids=external_ids, project_id=project_id
            )
            asset_ids = [id_map[id] for id in external_ids]

        try:
            services.export_labels(
                self.auth,
                asset_ids=asset_ids,
                project_id=cast(ProjectId, project_id),
                export_type="latest",
                label_format=fmt,
                split_option=layout,
                single_file=single_file,
                output_file=filename,
                disable_tqdm=disable_tqdm,
                log_level="WARNING",
                with_assets=with_assets,
                annotation_modifier=annotation_modifier,
                asset_filter_kwargs=asset_filter_kwargs,
            )
        except NoCompatibleJobError as excp:
            print(str(excp))

count_labels(self, project_id, asset_id=None, asset_status_in=None, asset_external_id_in=None, author_in=None, created_at=None, created_at_gte=None, created_at_lte=None, honeypot_mark_gte=None, honeypot_mark_lte=None, label_id=None, type_in=None, user_id=None, category_search=None, id_contains=None)

Get the number of labels for the given parameters.

Parameters:

Name Type Description Default
project_id str

Identifier of the project.

required
asset_id Optional[str]

Identifier of the asset.

None
asset_status_in Optional[List[str]]

Returned labels should have a status that belongs to that list, if given. Possible choices : TODO, ONGOING, LABELED or REVIEWED

None
asset_external_id_in Optional[List[str]]

Returned labels should have an external id that belongs to that list, if given.

None
author_in Optional[List[str]]

Returned labels should have been made by authors in that list, if given. An author can be designated by the first name, the last name, or the first name + last name.

None
created_at Optional[str]

Returned labels should have a label whose creation date is equal to this date.

None
created_at_gte Optional[str]

Returned labels should have a label whose creation date is greater than this date.

None
created_at_lte Optional[str]

Returned labels should have a label whose creation date is lower than this date.

None
honeypot_mark_gte Optional[float]

Returned labels should have a label whose honeypot is greater than this number.

None
honeypot_mark_lte Optional[float]

Returned labels should have a label whose honeypot is lower than this number.

None
label_id Optional[str]

Identifier of the label.

None
type_in Optional[List[str]]

Returned labels should have a label whose type belongs to that list, if given.

None
user_id Optional[str]

Identifier of the user.

None
category_search Optional[str]

Query to filter labels based on the content of their jsonResponse

None
id_contains Optional[List[str]]

Filters out labels not belonging to that list. If empty, no filtering is applied.

None

Dates format

Date strings should have format: "YYYY-MM-DD"

Returns:

Type Description
int

The number of labels with the parameters provided

Source code in kili/entrypoints/queries/label/__init__.py
@typechecked
def count_labels(
    self,
    project_id: str,
    asset_id: Optional[str] = None,
    asset_status_in: Optional[List[str]] = None,
    asset_external_id_in: Optional[List[str]] = None,
    author_in: Optional[List[str]] = None,
    created_at: Optional[str] = None,
    created_at_gte: Optional[str] = None,
    created_at_lte: Optional[str] = None,
    honeypot_mark_gte: Optional[float] = None,
    honeypot_mark_lte: Optional[float] = None,
    label_id: Optional[str] = None,
    type_in: Optional[List[str]] = None,
    user_id: Optional[str] = None,
    category_search: Optional[str] = None,
    id_contains: Optional[List[str]] = None,
) -> int:
    # pylint: disable=line-too-long
    """Get the number of labels for the given parameters.

    Args:
        project_id: Identifier of the project.
        asset_id: Identifier of the asset.
        asset_status_in: Returned labels should have a status that belongs to that list, if given.
            Possible choices : `TODO`, `ONGOING`, `LABELED` or `REVIEWED`
        asset_external_id_in: Returned labels should have an external id that belongs to that list, if given.
        author_in: Returned labels should have been made by authors in that list, if given.
            An author can be designated by the first name, the last name, or the first name + last name.
        created_at: Returned labels should have a label whose creation date is equal to this date.
        created_at_gte: Returned labels should have a label whose creation date is greater than this date.
        created_at_lte: Returned labels should have a label whose creation date is lower than this date.
        honeypot_mark_gte: Returned labels should have a label whose honeypot is greater than this number.
        honeypot_mark_lte: Returned labels should have a label whose honeypot is lower than this number.
        label_id: Identifier of the label.
        type_in: Returned labels should have a label whose type belongs to that list, if given.
        user_id: Identifier of the user.
        category_search: Query to filter labels based on the content of their jsonResponse
        id_contains: Filters out labels not belonging to that list. If empty, no filtering is applied.

    !!! info "Dates format"
        Date strings should have format: "YYYY-MM-DD"

    Returns:
        The number of labels with the parameters provided
    """
    if category_search:
        validate_category_search_query(category_search)

    where = LabelWhere(
        project_id=project_id,
        asset_id=asset_id,
        asset_status_in=asset_status_in,
        asset_external_id_in=asset_external_id_in,
        author_in=author_in,
        created_at=created_at,
        created_at_gte=created_at_gte,
        created_at_lte=created_at_lte,
        honeypot_mark_gte=honeypot_mark_gte,
        honeypot_mark_lte=honeypot_mark_lte,
        id_contains=id_contains,
        label_id=label_id,
        type_in=type_in,
        user_id=user_id,
        category_search=category_search,
    )
    return LabelQuery(self.auth.client).count(where)

export_labels(self, project_id, filename, fmt, asset_ids=None, layout='split', single_file=False, disable_tqdm=False, with_assets=True, external_ids=None, annotation_modifier=None, asset_filter_kwargs=None)

Export the project labels with the requested format into the requested output path.

Parameters:

Name Type Description Default
project_id str

Identifier of the project.

required
filename str

Relative or full path of the archive that will contain the exported data.

required
fmt typing_extensions.Literal['raw', 'kili', 'yolo_v4', 'yolo_v5', 'yolo_v7', 'coco', 'pascal_voc']

Format of the exported labels.

required
asset_ids Optional[List[str]]

Optional list of the assets internal IDs from which to export the labels.

None
layout typing_extensions.Literal['split', 'merged']

Layout of the exported files. "split" means there is one folder per job, "merged" that there is one folder with every labels.

'split'
single_file bool

Layout of the exported labels. Single file mode is only available for some specific formats (COCO and Kili).

False
disable_tqdm bool

Disable the progress bar if True.

False
with_assets bool

Download the assets in the export.

True
external_ids Optional[List[str]]

Optional list of the assets external IDs from which to export the labels.

None
annotation_modifier Optional[Callable[[Dict, Dict, Dict], Dict]]

(For COCO export only) function that takes the COCO annotation, the COCO image, and the Kili annotation, and should return an updated COCO annotation. This can be used if you want to add a new attribute to the COCO annotation. For example, you can add a method that computes if the annotation is a rectangle or not and add it to the COCO annotation (see example).

None
asset_filter_kwargs Optional[Dict[str, object]]

Optional dictionary of arguments to pass to kili.assets() in order to filter the assets the labels are exported from. The supported arguments are:

  • consensus_mark_gte
  • consensus_mark_lte
  • external_id_strictly_in
  • external_id_in
  • honeypot_mark_gte
  • honeypot_mark_lte
  • label_author_in
  • label_reviewer_in
  • skipped
  • status_in
  • label_category_search
  • created_at_gte
  • created_at_lte
  • issue_type
  • issue_status
  • inference_mark_gte
  • inference_mark_lte
  • metadata_where

See the documentation of kili.assets() for more information.

None

Info

The supported formats are:

  • Yolo V4, V5, V7 for object detection tasks (bounding box).
  • Kili (a.k.a raw) for all tasks.
  • COCO for object detection tasks (bounding box and semantic segmentation).
  • Pascal VOC for object detection tasks (bounding box).

Cloud storage

Export with asset download (with_assets=True) is not allowed for projects connected to a cloud storage. As they require an access to the assets to read their dimension, the COCO and Pascal VOC formats are not allowed in this case.

Example

kili.export_labels("your_project_id", "export.zip", "yolo_v4")

Example

def is_rectangle(coco_annotation, coco_image, kili_annotation):
    is_rectangle = ...
    return {**coco_annotation, "attributes": {"is_rectangle": is_rectangle}}

kili.export_labels(
    "your_project_id",
    "export.zip",
    "coco",
    annotation_modifier=add_is_rectangle
)
Source code in kili/entrypoints/queries/label/__init__.py
def export_labels(
    self,
    project_id: str,
    filename: str,
    fmt: LabelFormat,
    asset_ids: Optional[List[str]] = None,
    layout: SplitOption = "split",
    single_file: bool = False,
    disable_tqdm: bool = False,
    with_assets: bool = True,
    external_ids: Optional[List[str]] = None,
    annotation_modifier: Optional[CocoAnnotationModifier] = None,
    asset_filter_kwargs: Optional[Dict[str, object]] = None,
) -> None:
    # pylint: disable=line-too-long
    """Export the project labels with the requested format into the requested output path.

    Args:
        project_id: Identifier of the project.
        filename: Relative or full path of the archive that will contain
            the exported data.
        fmt: Format of the exported labels.
        asset_ids: Optional list of the assets internal IDs from which to export the labels.
        layout: Layout of the exported files. "split" means there is one folder
            per job, "merged" that there is one folder with every labels.
        single_file: Layout of the exported labels. Single file mode is
            only available for some specific formats (COCO and Kili).
        disable_tqdm: Disable the progress bar if True.
        with_assets: Download the assets in the export.
        external_ids: Optional list of the assets external IDs from which to export the labels.
        annotation_modifier: (For COCO export only) function that takes the COCO annotation, the
            COCO image, and the Kili annotation, and should return an updated COCO annotation.
            This can be used if you want to add a new attribute to the COCO annotation. For
            example, you can add a method that computes if the annotation is a rectangle or not
            and add it to the COCO annotation (see example).
        asset_filter_kwargs: Optional dictionary of arguments to pass to `kili.assets()` in order to filter the assets the labels are exported from. The supported arguments are:

            - `consensus_mark_gte`
            - `consensus_mark_lte`
            - `external_id_strictly_in`
            - `external_id_in`
            - `honeypot_mark_gte`
            - `honeypot_mark_lte`
            - `label_author_in`
            - `label_reviewer_in`
            - `skipped`
            - `status_in`
            - `label_category_search`
            - `created_at_gte`
            - `created_at_lte`
            - `issue_type`
            - `issue_status`
            - `inference_mark_gte`
            - `inference_mark_lte`
            - `metadata_where`

            See the documentation of [`kili.assets()`](https://python-sdk-docs.kili-technology.com/latest/sdk/asset/#kili.queries.asset.__init__.QueriesAsset.assets) for more information.

    !!! Info
        The supported formats are:

        - Yolo V4, V5, V7 for object detection tasks (bounding box).
        - Kili (a.k.a raw) for all tasks.
        - COCO for object detection tasks (bounding box and semantic segmentation).
        - Pascal VOC for object detection tasks (bounding box).

    !!! warning "Cloud storage"
        Export with asset download (`with_assets=True`) is not allowed for projects connected to a cloud storage.
        As they require an access to the assets to read their dimension, the COCO and Pascal VOC formats are not
        allowed in this case.

    !!! Example
        ```python
        kili.export_labels("your_project_id", "export.zip", "yolo_v4")
        ```

    !!! Example
        ```python
        def is_rectangle(coco_annotation, coco_image, kili_annotation):
            is_rectangle = ...
            return {**coco_annotation, "attributes": {"is_rectangle": is_rectangle}}

        kili.export_labels(
            "your_project_id",
            "export.zip",
            "coco",
            annotation_modifier=add_is_rectangle
        )
        ```
    """
    if external_ids is not None and asset_ids is None:
        id_map = infer_ids_from_external_ids(
            auth=self.auth, asset_external_ids=external_ids, project_id=project_id
        )
        asset_ids = [id_map[id] for id in external_ids]

    try:
        services.export_labels(
            self.auth,
            asset_ids=asset_ids,
            project_id=cast(ProjectId, project_id),
            export_type="latest",
            label_format=fmt,
            split_option=layout,
            single_file=single_file,
            output_file=filename,
            disable_tqdm=disable_tqdm,
            log_level="WARNING",
            with_assets=with_assets,
            annotation_modifier=annotation_modifier,
            asset_filter_kwargs=asset_filter_kwargs,
        )
    except NoCompatibleJobError as excp:
        print(str(excp))

export_labels_as_df(self, project_id, fields=['author.email', 'author.id', 'createdAt', 'id', 'labelType'], asset_fields=['externalId'])

Get the labels of a project as a pandas DataFrame.

Parameters:

Name Type Description Default
project_id str

Identifier of the project

required
fields List[str]

All the fields to request among the possible fields for the labels. See the documentation for all possible fields.

['author.email', 'author.id', 'createdAt', 'id', 'labelType']
asset_fields List[str]

All the fields to request among the possible fields for the assets. See the documentation for all possible fields.

['externalId']

Returns:

Type Description
DataFrame

pandas DataFrame containing the labels.

Source code in kili/entrypoints/queries/label/__init__.py
@typechecked
def export_labels_as_df(
    self,
    project_id: str,
    fields: List[str] = [
        "author.email",
        "author.id",
        "createdAt",
        "id",
        "labelType",
    ],
    asset_fields: List[str] = ["externalId"],
) -> pd.DataFrame:
    # pylint: disable=line-too-long
    """Get the labels of a project as a pandas DataFrame.

    Args:
        project_id: Identifier of the project
        fields: All the fields to request among the possible fields for the labels.
            See [the documentation](https://docs.kili-technology.com/reference/graphql-api#label) for all possible fields.
        asset_fields: All the fields to request among the possible fields for the assets.
            See [the documentation](https://docs.kili-technology.com/reference/graphql-api#asset) for all possible fields.

    Returns:
        pandas DataFrame containing the labels.
    """

    services.get_project(self.auth, project_id, ["id"])
    assets_gen = AssetQuery(self.auth.client)(
        AssetWhere(project_id=project_id),
        asset_fields + ["labels." + field for field in fields],
        QueryOptions(disable_tqdm=False),
    )
    labels = [
        dict(
            label,
            **{f"asset_{key}": asset[key] for key in asset if key != "labels"},
        )
        for asset in assets_gen
        for label in asset["labels"]
    ]
    labels_df = pd.DataFrame(labels)
    return labels_df

inferences(self, project_id, asset_id=None, asset_status_in=None, asset_external_id_in=None, author_in=None, created_at=None, created_at_gte=None, created_at_lte=None, fields=None, first=None, honeypot_mark_gte=None, honeypot_mark_lte=None, id_contains=None, label_id=None, skip=0, user_id=None, disable_tqdm=False, category_search=None, *, as_generator=False)

Get inference labels from a project based on a set of criteria.

This method is equivalent to the kili.labels() method, but it only returns label of type "INFERENCE".

Parameters:

Name Type Description Default
project_id str

Identifier of the project.

required
asset_id Optional[str]

Identifier of the asset.

None
asset_status_in Optional[List[str]]

Returned labels should have a status that belongs to that list, if given. Possible choices : TODO, ONGOING, LABELED, TO REVIEW or REVIEWED

None
asset_external_id_in Optional[List[str]]

Returned labels should have an external id that belongs to that list, if given.

None
author_in Optional[List[str]]

Returned labels should have been made by authors in that list, if given. An author can be designated by the first name, the last name, or the first name + last name.

None
created_at Optional[str]

Returned labels should have a label whose creation date is equal to this date.

None
created_at_gte Optional[str]

Returned labels should have a label whose creation date is greater than this date.

None
created_at_lte Optional[str]

Returned labels should have a label whose creation date is lower than this date.

None
fields Optional[List[str]]

All the fields to request among the possible fields for the labels. See the documentation for all possible fields.

None
first Optional[int]

Maximum number of labels to return.

None
honeypot_mark_gte Optional[float]

Returned labels should have a label whose honeypot is greater than this number.

None
honeypot_mark_lte Optional[float]

Returned labels should have a label whose honeypot is lower than this number.

None
id_contains Optional[List[str]]

Filters out labels not belonging to that list. If empty, no filtering is applied.

None
label_id Optional[str]

Identifier of the label.

None
skip int

Number of labels to skip (they are ordered by their date of creation, first to last).

0
user_id Optional[str]

Identifier of the user.

None
disable_tqdm bool

If True, the progress bar will be disabled

False
as_generator bool

If True, a generator on the labels is returned.

False
category_search Optional[str]

Query to filter labels based on the content of their jsonResponse

None

Returns:

Type Description
Iterable[Dict]

A result object which contains the query if it was successful, else an error message.

Examples:

>>> kili.inferences(project_id=project_id) # returns a list of inference labels of a project
Source code in kili/entrypoints/queries/label/__init__.py
@typechecked
def inferences(
    self,
    project_id: str,
    asset_id: Optional[str] = None,
    asset_status_in: Optional[List[str]] = None,
    asset_external_id_in: Optional[List[str]] = None,
    author_in: Optional[List[str]] = None,
    created_at: Optional[str] = None,
    created_at_gte: Optional[str] = None,
    created_at_lte: Optional[str] = None,
    fields: Optional[List[str]] = None,
    first: Optional[int] = None,
    honeypot_mark_gte: Optional[float] = None,
    honeypot_mark_lte: Optional[float] = None,
    id_contains: Optional[List[str]] = None,
    label_id: Optional[str] = None,
    skip: int = 0,
    user_id: Optional[str] = None,
    disable_tqdm: bool = False,
    category_search: Optional[str] = None,
    *,
    as_generator: bool = False,
) -> Iterable[Dict]:
    # pylint: disable=line-too-long
    """Get inference labels from a project based on a set of criteria.

    This method is equivalent to the `kili.labels()` method, but it only returns label of type "INFERENCE".

    Args:
        project_id: Identifier of the project.
        asset_id: Identifier of the asset.
        asset_status_in: Returned labels should have a status that belongs to that list, if given.
            Possible choices : `TODO`, `ONGOING`, `LABELED`, `TO REVIEW` or `REVIEWED`
        asset_external_id_in: Returned labels should have an external id that belongs to that list, if given.
        author_in: Returned labels should have been made by authors in that list, if given.
            An author can be designated by the first name, the last name, or the first name + last name.
        created_at: Returned labels should have a label whose creation date is equal to this date.
        created_at_gte: Returned labels should have a label whose creation date is greater than this date.
        created_at_lte: Returned labels should have a label whose creation date is lower than this date.
        fields: All the fields to request among the possible fields for the labels.
            See [the documentation](https://docs.kili-technology.com/reference/graphql-api#label) for all possible fields.
        first: Maximum number of labels to return.
        honeypot_mark_gte: Returned labels should have a label whose honeypot is greater than this number.
        honeypot_mark_lte: Returned labels should have a label whose honeypot is lower than this number.
        id_contains: Filters out labels not belonging to that list. If empty, no filtering is applied.
        label_id: Identifier of the label.
        skip: Number of labels to skip (they are ordered by their date of creation, first to last).
        user_id: Identifier of the user.
        disable_tqdm: If `True`, the progress bar will be disabled
        as_generator: If `True`, a generator on the labels is returned.
        category_search: Query to filter labels based on the content of their jsonResponse

    Returns:
        A result object which contains the query if it was successful, else an error message.

    Examples:
        >>> kili.inferences(project_id=project_id) # returns a list of inference labels of a project
    """
    if fields is None:
        fields = [
            "author.email",
            "author.id",
            "id",
            "jsonResponse",
            "labelType",
            "modelName",
        ]
    return self.labels(
        project_id=project_id,
        asset_id=asset_id,
        asset_status_in=asset_status_in,
        asset_external_id_in=asset_external_id_in,
        author_in=author_in,
        created_at=created_at,
        created_at_gte=created_at_gte,
        created_at_lte=created_at_lte,
        fields=fields,
        first=first,
        honeypot_mark_gte=honeypot_mark_gte,
        honeypot_mark_lte=honeypot_mark_lte,
        id_contains=id_contains,
        label_id=label_id,
        skip=skip,
        type_in=["INFERENCE"],
        user_id=user_id,
        disable_tqdm=disable_tqdm,
        category_search=category_search,
        as_generator=as_generator,  # type: ignore
    )

labels(self, project_id, asset_id=None, asset_status_in=None, asset_external_id_in=None, author_in=None, created_at=None, created_at_gte=None, created_at_lte=None, fields=['author.email', 'author.id', 'id', 'jsonResponse', 'labelType', 'secondsToLabel'], first=None, honeypot_mark_gte=None, honeypot_mark_lte=None, id_contains=None, label_id=None, skip=0, type_in=None, user_id=None, disable_tqdm=False, category_search=None, output_format='dict', *, as_generator=False)

Get a label list or a label generator from a project based on a set of criteria.

Parameters:

Name Type Description Default
project_id str

Identifier of the project.

required
asset_id Optional[str]

Identifier of the asset.

None
asset_status_in Optional[List[str]]

Returned labels should have a status that belongs to that list, if given. Possible choices : TODO, ONGOING, LABELED, TO REVIEW or REVIEWED.

None
asset_external_id_in Optional[List[str]]

Returned labels should have an external id that belongs to that list, if given.

None
author_in Optional[List[str]]

Returned labels should have been made by authors in that list, if given. An author can be designated by the first name, the last name, or the first name + last name.

None
created_at Optional[str]

Returned labels should have their creation date equal to this date.

None
created_at_gte Optional[str]

Returned labels should have their creation date greater or equal to this date.

None
created_at_lte Optional[str]

Returned labels should have their creation date lower or equal to this date.

None
fields List[str]

All the fields to request among the possible fields for the labels. See the documentation for all possible fields.

['author.email', 'author.id', 'id', 'jsonResponse', 'labelType', 'secondsToLabel']
first Optional[int]

Maximum number of labels to return.

None
honeypot_mark_gte Optional[float]

Returned labels should have a label whose honeypot is greater than this number.

None
honeypot_mark_lte Optional[float]

Returned labels should have a label whose honeypot is lower than this number.

None
id_contains Optional[List[str]]

Filters out labels not belonging to that list. If empty, no filtering is applied.

None
label_id Optional[str]

Identifier of the label.

None
skip int

Number of labels to skip (they are ordered by their date of creation, first to last).

0
type_in Optional[List[str]]

Returned labels should have a label whose type belongs to that list, if given.

None
user_id Optional[str]

Identifier of the user.

None
disable_tqdm bool

If True, the progress bar will be disabled.

False
as_generator bool

If True, a generator on the labels is returned.

False
category_search Optional[str]

Query to filter labels based on the content of their jsonResponse.

None
output_format typing_extensions.Literal['dict', 'parsed_label']

If dict, the output is an iterable of Python dictionaries. If parsed_label, the output is an iterable of parsed labels objects. More information on parsed labels in the documentation.

'dict'

Dates format

Date strings should have format: "YYYY-MM-DD"

Returns:

Type Description
Iterable[Union[Dict, kili.utils.labels.parsing.ParsedLabel]]

A result object which contains the query if it was successful, else an error message.

Examples:

>>> kili.labels(project_id=project_id, fields=['jsonResponse', 'labelOf.externalId']) # returns a list of all labels of a project and their assets external ID
>>> kili.labels(project_id=project_id, fields=['jsonResponse'], as_generator=True) # returns a generator of all labels of a project

How to filter based on label categories

The search query is composed of logical expressions following this format:

[job_name].[category_name].count [comparaison_operator] [value]

where:

  • [job_name] is the name of the job in the interface
  • [category_name] is the name of the category in the interface for this job
  • [comparaison_operator] can be one of: [==, >=, <=, <, >]
  • [value] is an integer that represents the count of such objects of the given category in the label

These operations can be separated by OR and AND operators

Example:

category_search = `JOB_CLASSIF.CATEGORY_A.count > 0`
category_search = `JOB_CLASSIF.CATEGORY_A.count > 0 OR JOB_NER.CATEGORY_B.count > 0`
category_search = `(JOB_CLASSIF.CATEGORY_A.count > 0 OR JOB_NER.CATEGORY_B.count > 0) AND JOB_BBOX.CATEGORY_C.count > 10`
Source code in kili/entrypoints/queries/label/__init__.py
@typechecked
def labels(
    self,
    project_id: str,
    asset_id: Optional[str] = None,
    asset_status_in: Optional[List[str]] = None,
    asset_external_id_in: Optional[List[str]] = None,
    author_in: Optional[List[str]] = None,
    created_at: Optional[str] = None,
    created_at_gte: Optional[str] = None,
    created_at_lte: Optional[str] = None,
    fields: List[str] = [
        "author.email",
        "author.id",
        "id",
        "jsonResponse",
        "labelType",
        "secondsToLabel",
    ],
    first: Optional[int] = None,
    honeypot_mark_gte: Optional[float] = None,
    honeypot_mark_lte: Optional[float] = None,
    id_contains: Optional[List[str]] = None,
    label_id: Optional[str] = None,
    skip: int = 0,
    type_in: Optional[List[str]] = None,
    user_id: Optional[str] = None,
    disable_tqdm: bool = False,
    category_search: Optional[str] = None,
    output_format: Literal["dict", "parsed_label"] = "dict",
    *,
    as_generator: bool = False,
) -> Iterable[Union[Dict, ParsedLabel]]:
    # pylint: disable=line-too-long
    """Get a label list or a label generator from a project based on a set of criteria.

    Args:
        project_id: Identifier of the project.
        asset_id: Identifier of the asset.
        asset_status_in: Returned labels should have a status that belongs to that list, if given.
            Possible choices : `TODO`, `ONGOING`, `LABELED`, `TO REVIEW` or `REVIEWED`.
        asset_external_id_in: Returned labels should have an external id that belongs to that list, if given.
        author_in: Returned labels should have been made by authors in that list, if given.
            An author can be designated by the first name, the last name, or the first name + last name.
        created_at: Returned labels should have their creation date equal to this date.
        created_at_gte: Returned labels should have their creation date greater or equal to this date.
        created_at_lte: Returned labels should have their creation date lower or equal to this date.
        fields: All the fields to request among the possible fields for the labels.
            See [the documentation](https://docs.kili-technology.com/reference/graphql-api#label) for all possible fields.
        first: Maximum number of labels to return.
        honeypot_mark_gte: Returned labels should have a label whose honeypot is greater than this number.
        honeypot_mark_lte: Returned labels should have a label whose honeypot is lower than this number.
        id_contains: Filters out labels not belonging to that list. If empty, no filtering is applied.
        label_id: Identifier of the label.
        skip: Number of labels to skip (they are ordered by their date of creation, first to last).
        type_in: Returned labels should have a label whose type belongs to that list, if given.
        user_id: Identifier of the user.
        disable_tqdm: If `True`, the progress bar will be disabled.
        as_generator: If `True`, a generator on the labels is returned.
        category_search: Query to filter labels based on the content of their jsonResponse.
        output_format: If `dict`, the output is an iterable of Python dictionaries.
            If `parsed_label`, the output is an iterable of parsed labels objects. More information on parsed labels in the [documentation](https://python-sdk-docs.kili-technology.com/latest/sdk/tutorials/label_parsing/).

    !!! info "Dates format"
        Date strings should have format: "YYYY-MM-DD"

    Returns:
        A result object which contains the query if it was successful, else an error message.

    Examples:
        >>> kili.labels(project_id=project_id, fields=['jsonResponse', 'labelOf.externalId']) # returns a list of all labels of a project and their assets external ID
        >>> kili.labels(project_id=project_id, fields=['jsonResponse'], as_generator=True) # returns a generator of all labels of a project

    !!! example "How to filter based on label categories"
        The search query is composed of logical expressions following this format:

            [job_name].[category_name].count [comparaison_operator] [value]
        where:

        - `[job_name]` is the name of the job in the interface
        - `[category_name]` is the name of the category in the interface for this job
        - `[comparaison_operator]` can be one of: [`==`, `>=`, `<=`, `<`, `>`]
        - `[value]` is an integer that represents the count of such objects of the given category in the label

        These operations can be separated by OR and AND operators

        Example:

            category_search = `JOB_CLASSIF.CATEGORY_A.count > 0`
            category_search = `JOB_CLASSIF.CATEGORY_A.count > 0 OR JOB_NER.CATEGORY_B.count > 0`
            category_search = `(JOB_CLASSIF.CATEGORY_A.count > 0 OR JOB_NER.CATEGORY_B.count > 0) AND JOB_BBOX.CATEGORY_C.count > 10`
    """
    if category_search:
        validate_category_search_query(category_search)

    where = LabelWhere(
        project_id=project_id,
        asset_id=asset_id,
        asset_status_in=asset_status_in,
        asset_external_id_in=asset_external_id_in,
        author_in=author_in,
        created_at=created_at,
        created_at_gte=created_at_gte,
        created_at_lte=created_at_lte,
        honeypot_mark_gte=honeypot_mark_gte,
        honeypot_mark_lte=honeypot_mark_lte,
        id_contains=id_contains,
        label_id=label_id,
        type_in=type_in,
        user_id=user_id,
        category_search=category_search,
    )

    post_call_function = None
    if output_format == "parsed_label":
        if "jsonResponse" not in fields:
            raise ValueError(
                "The field 'jsonResponse' is required to parse labels. Please add it to the"
                " 'fields' argument."
            )

        project = next(
            ProjectQuery(self.auth.client)(
                ProjectWhere(project_id=project_id),
                fields=["jsonInterface", "inputType"],
                options=QueryOptions(disable_tqdm=True, first=1, skip=0),
            )
        )
        post_call_function = partial(
            parse_labels,
            json_interface=project["jsonInterface"],
            input_type=project["inputType"],
        )

    disable_tqdm = disable_tqdm_if_as_generator(as_generator, disable_tqdm)
    options = QueryOptions(disable_tqdm, first, skip)
    labels_gen = LabelQuery(self.auth.client)(where, fields, options, post_call_function)

    if as_generator:
        return labels_gen
    return list(labels_gen)

predictions(self, project_id, asset_id=None, asset_status_in=None, asset_external_id_in=None, author_in=None, created_at=None, created_at_gte=None, created_at_lte=None, fields=None, first=None, honeypot_mark_gte=None, honeypot_mark_lte=None, id_contains=None, label_id=None, skip=0, user_id=None, disable_tqdm=False, category_search=None, *, as_generator=False)

Get prediction labels from a project based on a set of criteria.

This method is equivalent to the kili.labels() method, but it only returns label of type "PREDICTION".

Parameters:

Name Type Description Default
project_id str

Identifier of the project.

required
asset_id Optional[str]

Identifier of the asset.

None
asset_status_in Optional[List[str]]

Returned labels should have a status that belongs to that list, if given. Possible choices : TODO, ONGOING, LABELED, TO REVIEW or REVIEWED

None
asset_external_id_in Optional[List[str]]

Returned labels should have an external id that belongs to that list, if given.

None
author_in Optional[List[str]]

Returned labels should have been made by authors in that list, if given. An author can be designated by the first name, the last name, or the first name + last name.

None
created_at Optional[str]

Returned labels should have a label whose creation date is equal to this date.

None
created_at_gte Optional[str]

Returned labels should have a label whose creation date is greater than this date.

None
created_at_lte Optional[str]

Returned labels should have a label whose creation date is lower than this date.

None
fields Optional[List[str]]

All the fields to request among the possible fields for the labels. See the documentation for all possible fields.

None
first Optional[int]

Maximum number of labels to return.

None
honeypot_mark_gte Optional[float]

Returned labels should have a label whose honeypot is greater than this number.

None
honeypot_mark_lte Optional[float]

Returned labels should have a label whose honeypot is lower than this number.

None
id_contains Optional[List[str]]

Filters out labels not belonging to that list. If empty, no filtering is applied.

None
label_id Optional[str]

Identifier of the label.

None
skip int

Number of labels to skip (they are ordered by their date of creation, first to last).

0
user_id Optional[str]

Identifier of the user.

None
disable_tqdm bool

If True, the progress bar will be disabled

False
as_generator bool

If True, a generator on the labels is returned.

False
category_search Optional[str]

Query to filter labels based on the content of their jsonResponse

None

Returns:

Type Description
Iterable[Dict]

A result object which contains the query if it was successful, else an error message.

Examples:

>>> kili.predictions(project_id=project_id) # returns a list of prediction labels of a project
Source code in kili/entrypoints/queries/label/__init__.py
@typechecked
def predictions(
    self,
    project_id: str,
    asset_id: Optional[str] = None,
    asset_status_in: Optional[List[str]] = None,
    asset_external_id_in: Optional[List[str]] = None,
    author_in: Optional[List[str]] = None,
    created_at: Optional[str] = None,
    created_at_gte: Optional[str] = None,
    created_at_lte: Optional[str] = None,
    fields: Optional[List[str]] = None,
    first: Optional[int] = None,
    honeypot_mark_gte: Optional[float] = None,
    honeypot_mark_lte: Optional[float] = None,
    id_contains: Optional[List[str]] = None,
    label_id: Optional[str] = None,
    skip: int = 0,
    user_id: Optional[str] = None,
    disable_tqdm: bool = False,
    category_search: Optional[str] = None,
    *,
    as_generator: bool = False,
) -> Iterable[Dict]:
    # pylint: disable=line-too-long
    """Get prediction labels from a project based on a set of criteria.

    This method is equivalent to the `kili.labels()` method, but it only returns label of type "PREDICTION".

    Args:
        project_id: Identifier of the project.
        asset_id: Identifier of the asset.
        asset_status_in: Returned labels should have a status that belongs to that list, if given.
            Possible choices : `TODO`, `ONGOING`, `LABELED`, `TO REVIEW` or `REVIEWED`
        asset_external_id_in: Returned labels should have an external id that belongs to that list, if given.
        author_in: Returned labels should have been made by authors in that list, if given.
            An author can be designated by the first name, the last name, or the first name + last name.
        created_at: Returned labels should have a label whose creation date is equal to this date.
        created_at_gte: Returned labels should have a label whose creation date is greater than this date.
        created_at_lte: Returned labels should have a label whose creation date is lower than this date.
        fields: All the fields to request among the possible fields for the labels.
            See [the documentation](https://docs.kili-technology.com/reference/graphql-api#label) for all possible fields.
        first: Maximum number of labels to return.
        honeypot_mark_gte: Returned labels should have a label whose honeypot is greater than this number.
        honeypot_mark_lte: Returned labels should have a label whose honeypot is lower than this number.
        id_contains: Filters out labels not belonging to that list. If empty, no filtering is applied.
        label_id: Identifier of the label.
        skip: Number of labels to skip (they are ordered by their date of creation, first to last).
        user_id: Identifier of the user.
        disable_tqdm: If `True`, the progress bar will be disabled
        as_generator: If `True`, a generator on the labels is returned.
        category_search: Query to filter labels based on the content of their jsonResponse

    Returns:
        A result object which contains the query if it was successful, else an error message.

    Examples:
        >>> kili.predictions(project_id=project_id) # returns a list of prediction labels of a project
    """
    if fields is None:
        fields = [
            "author.email",
            "author.id",
            "id",
            "jsonResponse",
            "labelType",
            "modelName",
        ]
    return self.labels(
        project_id=project_id,
        asset_id=asset_id,
        asset_status_in=asset_status_in,
        asset_external_id_in=asset_external_id_in,
        author_in=author_in,
        created_at=created_at,
        created_at_gte=created_at_gte,
        created_at_lte=created_at_lte,
        fields=fields,
        first=first,
        honeypot_mark_gte=honeypot_mark_gte,
        honeypot_mark_lte=honeypot_mark_lte,
        id_contains=id_contains,
        label_id=label_id,
        skip=skip,
        type_in=["PREDICTION"],
        user_id=user_id,
        disable_tqdm=disable_tqdm,
        category_search=category_search,
        as_generator=as_generator,  # type: ignore
    )

Mutations

Set of Label mutations.

Source code in kili/entrypoints/mutations/label/__init__.py
class MutationsLabel:
    """Set of Label mutations."""

    # pylint: disable=too-many-arguments

    def __init__(self, auth: KiliAuth):
        """Initializes the subclass.

        Args:
            auth: KiliAuth object
        """
        self.auth = auth

    @typechecked
    def create_predictions(
        self,
        project_id: str,
        external_id_array: Optional[List[str]] = None,
        model_name_array: Optional[List[str]] = None,
        json_response_array: Optional[List[dict]] = None,
        model_name: Optional[str] = None,
        asset_id_array: Optional[List[str]] = None,
    ) -> Dict:
        # pylint: disable=line-too-long
        """Create predictions for specific assets.

        Args:
            project_id: Identifier of the project.
            external_id_array: The external IDs of the assets for which we want to add predictions.
            model_name_array: Deprecated, use `model_name` instead.
            json_response_array: The predictions are given here. For examples,
                see [the recipe](https://docs.kili-technology.com/recipes/importing-labels-and-predictions).
            model_name: The name of the model that generated the predictions
            asset_id_array: The internal IDs of the assets for which we want to add predictions.

        Returns:
            A result object which indicates if the mutation was successful, or an error message.

        !!! example "Recipe"
            For more detailed examples on how to create predictions, see [the recipe](https://docs.kili-technology.com/recipes/importing-labels-and-predictions).

        !!! warning "model name"
            The use of `model_name_array` is deprecated. Creating predictions from different
            models is not supported anymore. Please use `model_name` argument instead to
            provide the predictions model name.
        """
        if json_response_array is None or len(json_response_array) == 0:
            raise ValueError(
                "json_response_array is empty, you must provide at least one prediction to upload"
            )
        assert_all_arrays_have_same_size(
            [external_id_array, json_response_array, model_name_array, asset_id_array]
        )
        if model_name is None:
            if model_name_array is None:
                raise ValueError("You must provide a model name with the model_name argument ")
            if len(set(model_name_array)) > 1:
                raise ValueError(
                    "Creating predictions from different models is not supported anymore. Separate"
                    " your calls by models."
                )
            warnings.warn(
                (
                    "The use of `model_name_array` is deprecated. Creating predictions from"
                    " different models is not supported anymore. Please use `model_name` argument"
                    " instead to provide the predictions model name."
                ),
                DeprecationWarning,
                stacklevel=1,
            )
            model_name = model_name_array[0]

        labels = [
            {
                "asset_id": asset_id,
                "asset_external_id": asset_external_id,
                "json_response": json_response,
            }
            for (asset_id, asset_external_id, json_response) in list(
                zip(
                    asset_id_array or [None] * len(json_response_array),
                    external_id_array or [None] * len(json_response_array),
                    json_response_array,
                )
            )
        ]
        services.import_labels_from_dict(self.auth, project_id, labels, "PREDICTION", model_name)
        return {"id": project_id}

    @deprecate(
        msg=(
            "append_to_labels method is deprecated. Please use append_labels instead. This new"
            " function allows to import several labels 10 times faster."
        )
    )
    @typechecked
    def append_to_labels(
        self,
        json_response: dict,
        author_id: Optional[str] = None,
        label_asset_external_id: Optional[str] = None,
        label_asset_id: Optional[str] = None,
        label_type: LabelType = "DEFAULT",
        project_id: Optional[str] = None,
        seconds_to_label: Optional[int] = 0,
    ):
        """!!! danger "[DEPRECATED]"
            append_to_labels method is deprecated. Please use append_labels instead.
            This new function allows to import several labels 10 times faster.

        Append a label to an asset.

        Args:
            json_response: Label is given here.
            author_id: ID of the author of the label.
            label_asset_external_id: External identifier of the asset.
            label_asset_id: Identifier of the asset.
            project_id: Identifier of the project.
            label_type: Can be one of `AUTOSAVE`, `DEFAULT`, `PREDICTION`, `REVIEW` or `INFERENCE`.
            seconds_to_label: Time to create the label.

        !!! warning
            Either provide `label_asset_id` or `label_asset_external_id` and `project_id`

        Returns:
            A result object which indicates if the mutation was successful,
                or an error message.

        Examples:
            >>> kili.append_to_labels(label_asset_id=asset_id, json_response={...})
        """
        if author_id is None:
            user = self.auth.get_user()
            author_id = user["id"]

        check_asset_identifier_arguments(
            project_id,
            [label_asset_id] if label_asset_id else None,
            [label_asset_external_id] if label_asset_external_id else None,
        )
        if label_asset_id is None:
            assert label_asset_external_id and project_id
            label_asset_id = infer_ids_from_external_ids(
                self.auth, [label_asset_external_id], project_id
            )[label_asset_external_id]
        variables = {
            "data": {
                "authorID": author_id,
                "jsonResponse": dumps(json_response),
                "labelType": label_type,
                "secondsToLabel": seconds_to_label,
            },
            "where": {"id": label_asset_id},
        }
        result = self.auth.client.execute(GQL_APPEND_TO_LABELS, variables)
        return format_result("data", result, Label)

    @typechecked
    def append_labels(  # pylint: disable=dangerous-default-value
        self,
        asset_id_array: Optional[List[str]] = None,
        json_response_array: List[Dict] = [],
        author_id_array: Optional[List[str]] = None,
        seconds_to_label_array: Optional[List[int]] = None,
        model_name: Optional[str] = None,
        label_type: LabelType = "DEFAULT",
        project_id: Optional[str] = None,
        asset_external_id_array: Optional[List[str]] = None,
        disable_tqdm: bool = False,
    ) -> List:
        """Append labels to assets.

        Args:
            asset_id_array: list of asset internal ids to append labels on.
            json_response_array: list of labels to append.
            author_id_array: list of the author id of the labels.
            seconds_to_label_array: list of times taken to produce the label, in seconds.
            model_name: Only useful when uploading predictions.
                Name of the model when uploading predictions.
            label_type: Can be one of `AUTOSAVE`, `DEFAULT`, `PREDICTION`, `REVIEW` or `INFERENCE`.
            project_id: Identifier of the project.
            asset_external_id_array: list of asset external ids to append labels on.
            disable_tqdm: Disable tqdm progress bar.

        Returns:
            A result object which indicates if the mutation was successful,
                or an error message.

        Examples:
            >>> kili.append_labels(
                    asset_id_array=['cl9wmlkuc00050qsz6ut39g8h', 'cl9wmlkuw00080qsz2kqh8aiy'],
                    json_response_array=[{...}, {...}]
                )
        """
        if len(json_response_array) == 0:
            raise ValueError(
                "json_response_array is empty, you must provide at least one label to upload"
            )
        check_asset_identifier_arguments(project_id, asset_id_array, asset_external_id_array)
        assert_all_arrays_have_same_size(
            [
                seconds_to_label_array,
                author_id_array,
                json_response_array,
                asset_external_id_array,
                asset_id_array,
            ]
        )

        labels = [
            {
                "asset_id": asset_id,
                "asset_external_id": asset_external_id,
                "json_response": json_response,
                "seconds_to_label": seconds_to_label,
                "author_id": author_id,
            }
            for (asset_id, asset_external_id, json_response, seconds_to_label, author_id) in list(
                zip(
                    asset_id_array or [None] * len(json_response_array),
                    asset_external_id_array or [None] * len(json_response_array),
                    json_response_array,
                    seconds_to_label_array or [None] * len(json_response_array),
                    author_id_array or [None] * len(json_response_array),
                )
            )
        ]
        return services.import_labels_from_dict(
            self.auth, project_id, labels, label_type, model_name, disable_tqdm
        )

    @typechecked
    def update_properties_in_label(
        self,
        label_id: str,
        seconds_to_label: Optional[int] = None,
        model_name: Optional[str] = None,
        json_response: Optional[dict] = None,
    ) -> Label:
        """Update properties of a label.

        Args:
            label_id: Identifier of the label
            seconds_to_label: Time to create the label
            model_name: Name of the model
            json_response: The label is given here

        Returns:
            A result object which indicates if the mutation was successful,
                or an error message.

        Examples:
            >>> kili.update_properties_in_label(label_id=label_id, json_response={...})
        """
        formatted_json_response = None if json_response is None else dumps(json_response)
        variables = {
            "labelID": label_id,
            "secondsToLabel": seconds_to_label,
            "modelName": model_name,
            "jsonResponse": formatted_json_response,
        }
        result = self.auth.client.execute(GQL_UPDATE_PROPERTIES_IN_LABEL, variables)
        return format_result("data", result, Label)

    @typechecked
    def create_honeypot(
        self,
        json_response: dict,
        asset_external_id: Optional[str] = None,
        asset_id: Optional[str] = None,
        project_id: Optional[str] = None,
    ) -> Label:
        """Create honeypot for an asset.

        !!! info
            Uses the given `json_response` to create a `REVIEW` label.
            This enables Kili to compute a`honeypotMark`,
            which measures the similarity between this label and other labels.

        Args:
            json_response: The JSON response of the honeypot label of the asset.
            asset_id: Identifier of the asset.
                Either provide `asset_id` or `asset_external_id` and `project_id`.
            asset_external_id: External identifier of the asset.
                Either provide `asset_id` or `asset_external_id` and `project_id`.
            project_id: Identifier of the project.
                Either provide `asset_id` or `asset_external_id` and `project_id`.

        Returns:
            A result object which indicates if the mutation was successful,
                or an error message.
        """
        if asset_id is None:
            if asset_external_id is None or project_id is None:
                raise ValueError(
                    "Either provide `asset_id` or `asset_external_id` and `project_id`."
                )
            asset_id = infer_ids_from_external_ids(self.auth, [asset_external_id], project_id)[
                asset_external_id
            ]

        variables = {
            "data": {"jsonResponse": dumps(json_response)},
            "where": {"id": asset_id},
        }
        result = self.auth.client.execute(GQL_CREATE_HONEYPOT, variables)
        return format_result("data", result, Label)

append_labels(self, asset_id_array=None, json_response_array=[], author_id_array=None, seconds_to_label_array=None, model_name=None, label_type='DEFAULT', project_id=None, asset_external_id_array=None, disable_tqdm=False)

Append labels to assets.

Parameters:

Name Type Description Default
asset_id_array Optional[List[str]]

list of asset internal ids to append labels on.

None
json_response_array List[Dict]

list of labels to append.

[]
author_id_array Optional[List[str]]

list of the author id of the labels.

None
seconds_to_label_array Optional[List[int]]

list of times taken to produce the label, in seconds.

None
model_name Optional[str]

Only useful when uploading predictions. Name of the model when uploading predictions.

None
label_type typing_extensions.Literal['AUTOSAVE', 'DEFAULT', 'PREDICTION', 'REVIEW', 'INFERENCE']

Can be one of AUTOSAVE, DEFAULT, PREDICTION, REVIEW or INFERENCE.

'DEFAULT'
project_id Optional[str]

Identifier of the project.

None
asset_external_id_array Optional[List[str]]

list of asset external ids to append labels on.

None
disable_tqdm bool

Disable tqdm progress bar.

False

Returns:

Type Description
List

A result object which indicates if the mutation was successful, or an error message.

Examples:

>>> kili.append_labels(
        asset_id_array=['cl9wmlkuc00050qsz6ut39g8h', 'cl9wmlkuw00080qsz2kqh8aiy'],
        json_response_array=[{...}, {...}]
    )
Source code in kili/entrypoints/mutations/label/__init__.py
@typechecked
def append_labels(  # pylint: disable=dangerous-default-value
    self,
    asset_id_array: Optional[List[str]] = None,
    json_response_array: List[Dict] = [],
    author_id_array: Optional[List[str]] = None,
    seconds_to_label_array: Optional[List[int]] = None,
    model_name: Optional[str] = None,
    label_type: LabelType = "DEFAULT",
    project_id: Optional[str] = None,
    asset_external_id_array: Optional[List[str]] = None,
    disable_tqdm: bool = False,
) -> List:
    """Append labels to assets.

    Args:
        asset_id_array: list of asset internal ids to append labels on.
        json_response_array: list of labels to append.
        author_id_array: list of the author id of the labels.
        seconds_to_label_array: list of times taken to produce the label, in seconds.
        model_name: Only useful when uploading predictions.
            Name of the model when uploading predictions.
        label_type: Can be one of `AUTOSAVE`, `DEFAULT`, `PREDICTION`, `REVIEW` or `INFERENCE`.
        project_id: Identifier of the project.
        asset_external_id_array: list of asset external ids to append labels on.
        disable_tqdm: Disable tqdm progress bar.

    Returns:
        A result object which indicates if the mutation was successful,
            or an error message.

    Examples:
        >>> kili.append_labels(
                asset_id_array=['cl9wmlkuc00050qsz6ut39g8h', 'cl9wmlkuw00080qsz2kqh8aiy'],
                json_response_array=[{...}, {...}]
            )
    """
    if len(json_response_array) == 0:
        raise ValueError(
            "json_response_array is empty, you must provide at least one label to upload"
        )
    check_asset_identifier_arguments(project_id, asset_id_array, asset_external_id_array)
    assert_all_arrays_have_same_size(
        [
            seconds_to_label_array,
            author_id_array,
            json_response_array,
            asset_external_id_array,
            asset_id_array,
        ]
    )

    labels = [
        {
            "asset_id": asset_id,
            "asset_external_id": asset_external_id,
            "json_response": json_response,
            "seconds_to_label": seconds_to_label,
            "author_id": author_id,
        }
        for (asset_id, asset_external_id, json_response, seconds_to_label, author_id) in list(
            zip(
                asset_id_array or [None] * len(json_response_array),
                asset_external_id_array or [None] * len(json_response_array),
                json_response_array,
                seconds_to_label_array or [None] * len(json_response_array),
                author_id_array or [None] * len(json_response_array),
            )
        )
    ]
    return services.import_labels_from_dict(
        self.auth, project_id, labels, label_type, model_name, disable_tqdm
    )

append_to_labels(self, json_response, author_id=None, label_asset_external_id=None, label_asset_id=None, label_type='DEFAULT', project_id=None, seconds_to_label=0)

[DEPRECATED]

append_to_labels method is deprecated. Please use append_labels instead. This new function allows to import several labels 10 times faster.

Append a label to an asset.

Parameters:

Name Type Description Default
json_response dict

Label is given here.

required
author_id Optional[str]

ID of the author of the label.

None
label_asset_external_id Optional[str]

External identifier of the asset.

None
label_asset_id Optional[str]

Identifier of the asset.

None
project_id Optional[str]

Identifier of the project.

None
label_type typing_extensions.Literal['AUTOSAVE', 'DEFAULT', 'PREDICTION', 'REVIEW', 'INFERENCE']

Can be one of AUTOSAVE, DEFAULT, PREDICTION, REVIEW or INFERENCE.

'DEFAULT'
seconds_to_label Optional[int]

Time to create the label.

0

Warning

Either provide label_asset_id or label_asset_external_id and project_id

Returns:

Type Description

A result object which indicates if the mutation was successful, or an error message.

Examples:

>>> kili.append_to_labels(label_asset_id=asset_id, json_response={...})
Source code in kili/entrypoints/mutations/label/__init__.py
@deprecate(
    msg=(
        "append_to_labels method is deprecated. Please use append_labels instead. This new"
        " function allows to import several labels 10 times faster."
    )
)
@typechecked
def append_to_labels(
    self,
    json_response: dict,
    author_id: Optional[str] = None,
    label_asset_external_id: Optional[str] = None,
    label_asset_id: Optional[str] = None,
    label_type: LabelType = "DEFAULT",
    project_id: Optional[str] = None,
    seconds_to_label: Optional[int] = 0,
):
    """!!! danger "[DEPRECATED]"
        append_to_labels method is deprecated. Please use append_labels instead.
        This new function allows to import several labels 10 times faster.

    Append a label to an asset.

    Args:
        json_response: Label is given here.
        author_id: ID of the author of the label.
        label_asset_external_id: External identifier of the asset.
        label_asset_id: Identifier of the asset.
        project_id: Identifier of the project.
        label_type: Can be one of `AUTOSAVE`, `DEFAULT`, `PREDICTION`, `REVIEW` or `INFERENCE`.
        seconds_to_label: Time to create the label.

    !!! warning
        Either provide `label_asset_id` or `label_asset_external_id` and `project_id`

    Returns:
        A result object which indicates if the mutation was successful,
            or an error message.

    Examples:
        >>> kili.append_to_labels(label_asset_id=asset_id, json_response={...})
    """
    if author_id is None:
        user = self.auth.get_user()
        author_id = user["id"]

    check_asset_identifier_arguments(
        project_id,
        [label_asset_id] if label_asset_id else None,
        [label_asset_external_id] if label_asset_external_id else None,
    )
    if label_asset_id is None:
        assert label_asset_external_id and project_id
        label_asset_id = infer_ids_from_external_ids(
            self.auth, [label_asset_external_id], project_id
        )[label_asset_external_id]
    variables = {
        "data": {
            "authorID": author_id,
            "jsonResponse": dumps(json_response),
            "labelType": label_type,
            "secondsToLabel": seconds_to_label,
        },
        "where": {"id": label_asset_id},
    }
    result = self.auth.client.execute(GQL_APPEND_TO_LABELS, variables)
    return format_result("data", result, Label)

create_honeypot(self, json_response, asset_external_id=None, asset_id=None, project_id=None)

Create honeypot for an asset.

Info

Uses the given json_response to create a REVIEW label. This enables Kili to compute ahoneypotMark, which measures the similarity between this label and other labels.

Parameters:

Name Type Description Default
json_response dict

The JSON response of the honeypot label of the asset.

required
asset_id Optional[str]

Identifier of the asset. Either provide asset_id or asset_external_id and project_id.

None
asset_external_id Optional[str]

External identifier of the asset. Either provide asset_id or asset_external_id and project_id.

None
project_id Optional[str]

Identifier of the project. Either provide asset_id or asset_external_id and project_id.

None

Returns:

Type Description
Label

A result object which indicates if the mutation was successful, or an error message.

Source code in kili/entrypoints/mutations/label/__init__.py
@typechecked
def create_honeypot(
    self,
    json_response: dict,
    asset_external_id: Optional[str] = None,
    asset_id: Optional[str] = None,
    project_id: Optional[str] = None,
) -> Label:
    """Create honeypot for an asset.

    !!! info
        Uses the given `json_response` to create a `REVIEW` label.
        This enables Kili to compute a`honeypotMark`,
        which measures the similarity between this label and other labels.

    Args:
        json_response: The JSON response of the honeypot label of the asset.
        asset_id: Identifier of the asset.
            Either provide `asset_id` or `asset_external_id` and `project_id`.
        asset_external_id: External identifier of the asset.
            Either provide `asset_id` or `asset_external_id` and `project_id`.
        project_id: Identifier of the project.
            Either provide `asset_id` or `asset_external_id` and `project_id`.

    Returns:
        A result object which indicates if the mutation was successful,
            or an error message.
    """
    if asset_id is None:
        if asset_external_id is None or project_id is None:
            raise ValueError(
                "Either provide `asset_id` or `asset_external_id` and `project_id`."
            )
        asset_id = infer_ids_from_external_ids(self.auth, [asset_external_id], project_id)[
            asset_external_id
        ]

    variables = {
        "data": {"jsonResponse": dumps(json_response)},
        "where": {"id": asset_id},
    }
    result = self.auth.client.execute(GQL_CREATE_HONEYPOT, variables)
    return format_result("data", result, Label)

create_predictions(self, project_id, external_id_array=None, model_name_array=None, json_response_array=None, model_name=None, asset_id_array=None)

Create predictions for specific assets.

Parameters:

Name Type Description Default
project_id str

Identifier of the project.

required
external_id_array Optional[List[str]]

The external IDs of the assets for which we want to add predictions.

None
model_name_array Optional[List[str]]

Deprecated, use model_name instead.

None
json_response_array Optional[List[dict]]

The predictions are given here. For examples, see the recipe.

None
model_name Optional[str]

The name of the model that generated the predictions

None
asset_id_array Optional[List[str]]

The internal IDs of the assets for which we want to add predictions.

None

Returns:

Type Description
Dict

A result object which indicates if the mutation was successful, or an error message.

Recipe

For more detailed examples on how to create predictions, see the recipe.

model name

The use of model_name_array is deprecated. Creating predictions from different models is not supported anymore. Please use model_name argument instead to provide the predictions model name.

Source code in kili/entrypoints/mutations/label/__init__.py
@typechecked
def create_predictions(
    self,
    project_id: str,
    external_id_array: Optional[List[str]] = None,
    model_name_array: Optional[List[str]] = None,
    json_response_array: Optional[List[dict]] = None,
    model_name: Optional[str] = None,
    asset_id_array: Optional[List[str]] = None,
) -> Dict:
    # pylint: disable=line-too-long
    """Create predictions for specific assets.

    Args:
        project_id: Identifier of the project.
        external_id_array: The external IDs of the assets for which we want to add predictions.
        model_name_array: Deprecated, use `model_name` instead.
        json_response_array: The predictions are given here. For examples,
            see [the recipe](https://docs.kili-technology.com/recipes/importing-labels-and-predictions).
        model_name: The name of the model that generated the predictions
        asset_id_array: The internal IDs of the assets for which we want to add predictions.

    Returns:
        A result object which indicates if the mutation was successful, or an error message.

    !!! example "Recipe"
        For more detailed examples on how to create predictions, see [the recipe](https://docs.kili-technology.com/recipes/importing-labels-and-predictions).

    !!! warning "model name"
        The use of `model_name_array` is deprecated. Creating predictions from different
        models is not supported anymore. Please use `model_name` argument instead to
        provide the predictions model name.
    """
    if json_response_array is None or len(json_response_array) == 0:
        raise ValueError(
            "json_response_array is empty, you must provide at least one prediction to upload"
        )
    assert_all_arrays_have_same_size(
        [external_id_array, json_response_array, model_name_array, asset_id_array]
    )
    if model_name is None:
        if model_name_array is None:
            raise ValueError("You must provide a model name with the model_name argument ")
        if len(set(model_name_array)) > 1:
            raise ValueError(
                "Creating predictions from different models is not supported anymore. Separate"
                " your calls by models."
            )
        warnings.warn(
            (
                "The use of `model_name_array` is deprecated. Creating predictions from"
                " different models is not supported anymore. Please use `model_name` argument"
                " instead to provide the predictions model name."
            ),
            DeprecationWarning,
            stacklevel=1,
        )
        model_name = model_name_array[0]

    labels = [
        {
            "asset_id": asset_id,
            "asset_external_id": asset_external_id,
            "json_response": json_response,
        }
        for (asset_id, asset_external_id, json_response) in list(
            zip(
                asset_id_array or [None] * len(json_response_array),
                external_id_array or [None] * len(json_response_array),
                json_response_array,
            )
        )
    ]
    services.import_labels_from_dict(self.auth, project_id, labels, "PREDICTION", model_name)
    return {"id": project_id}

update_properties_in_label(self, label_id, seconds_to_label=None, model_name=None, json_response=None)

Update properties of a label.

Parameters:

Name Type Description Default
label_id str

Identifier of the label

required
seconds_to_label Optional[int]

Time to create the label

None
model_name Optional[str]

Name of the model

None
json_response Optional[dict]

The label is given here

None

Returns:

Type Description
Label

A result object which indicates if the mutation was successful, or an error message.

Examples:

>>> kili.update_properties_in_label(label_id=label_id, json_response={...})
Source code in kili/entrypoints/mutations/label/__init__.py
@typechecked
def update_properties_in_label(
    self,
    label_id: str,
    seconds_to_label: Optional[int] = None,
    model_name: Optional[str] = None,
    json_response: Optional[dict] = None,
) -> Label:
    """Update properties of a label.

    Args:
        label_id: Identifier of the label
        seconds_to_label: Time to create the label
        model_name: Name of the model
        json_response: The label is given here

    Returns:
        A result object which indicates if the mutation was successful,
            or an error message.

    Examples:
        >>> kili.update_properties_in_label(label_id=label_id, json_response={...})
    """
    formatted_json_response = None if json_response is None else dumps(json_response)
    variables = {
        "labelID": label_id,
        "secondsToLabel": seconds_to_label,
        "modelName": model_name,
        "jsonResponse": formatted_json_response,
    }
    result = self.auth.client.execute(GQL_UPDATE_PROPERTIES_IN_LABEL, variables)
    return format_result("data", result, Label)

Subscriptions

Set of Label subscriptions.

Source code in kili/entrypoints/subscriptions/label/__init__.py
class SubscriptionsLabel:
    """Set of Label subscriptions."""

    def __init__(self, auth: KiliAuth):
        """Initialize the subclass.

        Args:
            auth: KiliAuth object
        """
        self.auth = auth

    @typechecked
    def label_created_or_updated(
        self, project_id: str, callback: Callable[[str, str], None]
    ) -> SubscriptionGraphQLClient:
        # pylint: disable=line-too-long
        """Subscribe a callback to a project, which is executed when a label is created or updated.

        Args:
            project_id: Identifier of the project
            callback: This function takes as input the id of the asset and its content.

        Returns:
            A subscription client.

        !!! example "Recipe"
            For more detailed examples on how to use Webhooks,
            See [the related recipe](https://github.com/kili-technology/kili-python-sdk/blob/master/recipes/webhooks.ipynb)
        """
        ws_endpoint = self.auth.client.endpoint.replace("http", "ws")
        websocket = SubscriptionGraphQLClient(ws_endpoint)
        headers = {"Accept": "application/json", "Content-Type": "application/json"}
        authorization = f"X-API-Key: {self.auth.api_key}"
        headers["Authorization"] = authorization
        variables = {"projectID": project_id}
        websocket.subscribe(
            GQL_LABEL_CREATED_OR_UPDATED,
            variables=variables,
            callback=callback,
            headers=headers,
            authorization=authorization,
        )
        return websocket

label_created_or_updated(self, project_id, callback)

Subscribe a callback to a project, which is executed when a label is created or updated.

Parameters:

Name Type Description Default
project_id str

Identifier of the project

required
callback Callable[[str, str], NoneType]

This function takes as input the id of the asset and its content.

required

Returns:

Type Description
SubscriptionGraphQLClient

A subscription client.

Recipe

For more detailed examples on how to use Webhooks, See the related recipe

Source code in kili/entrypoints/subscriptions/label/__init__.py
@typechecked
def label_created_or_updated(
    self, project_id: str, callback: Callable[[str, str], None]
) -> SubscriptionGraphQLClient:
    # pylint: disable=line-too-long
    """Subscribe a callback to a project, which is executed when a label is created or updated.

    Args:
        project_id: Identifier of the project
        callback: This function takes as input the id of the asset and its content.

    Returns:
        A subscription client.

    !!! example "Recipe"
        For more detailed examples on how to use Webhooks,
        See [the related recipe](https://github.com/kili-technology/kili-python-sdk/blob/master/recipes/webhooks.ipynb)
    """
    ws_endpoint = self.auth.client.endpoint.replace("http", "ws")
    websocket = SubscriptionGraphQLClient(ws_endpoint)
    headers = {"Accept": "application/json", "Content-Type": "application/json"}
    authorization = f"X-API-Key: {self.auth.api_key}"
    headers["Authorization"] = authorization
    variables = {"projectID": project_id}
    websocket.subscribe(
        GQL_LABEL_CREATED_OR_UPDATED,
        variables=variables,
        callback=callback,
        headers=headers,
        authorization=authorization,
    )
    return websocket