# Label Studio Python Library

<!-- Note about deprecated version <1 -->
---
> :warning: **Note**<br/>
>
> The version of `label-studio-sdk<1` is deprecated and no longer supported. We recommend updating to the latest version.
> If you still want to use the old version, you can install it with `pip install "label-studio-sdk<1"`.
> OR You can find the branch with the old version by cloning the repository and checking out the branch as follows:
>
> ```sh
> git clone https://github.com/HumanSignal/label-studio-sdk.git
> cd label-studio-sdk
> git checkout previous-version
> ```
> 
> OR you can change your import statements as follows:
> ```python
> from label_studio_sdk import Client
> from label_studio_sdk.data_manager import Filters, Column, Operator, Type
> from label_studio_sdk._legacy import Project
> ```
---

[![fern shield](https://img.shields.io/badge/%F0%9F%8C%BF-SDK%20generated%20by%20Fern-brightgreen)](https://github.com/fern-api/fern)

The Label Studio Python Library provides convenient access to the Label Studio API from applications written in Python.
<!-- End Title  -->

<!-- Outline -->

- [Installation](#installation)
- [Usage](#usage)
- [Examples](#examples)
  - [Get all projects](#get-all-projects)
  - [Create a new project](#create-a-new-project)
  - [Get project by ID](#get-project-by-id)
  - [Update project](#update-project)
  - [Delete project](#delete-project)
  - [Get tasks with annotations and predictions](#get-tasks-with-annotations-and-predictions)
  - [Get task by ID](#get-task-by-id)
  - [Get all annotations for a task](#get-all-annotations-for-a-task)
  - [Create a new task](#create-a-new-task)
  - [Import batch tasks](#import-batch-tasks)
  - [Update task](#update-task)
  - [Delete task](#delete-task)
  - [Create prediction](#create-prediction)
  - [Update prediction](#update-prediction)
  - [Delete prediction](#delete-prediction)
  - [Async client](#async-client)


# Documentation
Explore the Label Studio API documentation [here](https://label-studio.docs.buildwithfern.com/).


<!-- Begin Installation, generated by Fern  -->
# Installation

```sh
pip install --upgrade label-studio-sdk
```
<!-- End Installation  -->

<!-- Begin Usage, generated by Fern  -->
# Usage

```python
from label_studio_sdk.client import LabelStudio

client = LabelStudio(
    api_key="YOUR_API_KEY",
)
```
<!-- End Usage  -->

# Examples

## Get all projects

```python
projects = client.projects.list()
```

## Create a new project

```python
project = client.projects.create(
    name="Project name",
    description="Project description",
    label_config="""
    <View>
        <Image name="image" value="$image" />
        <RectangleLabels name="label" toName="image">
            <Label value="cat" />
            <Label value="dog" />
        </RectangleLabels>
    </View>
    """
)
```

## Get project by ID

```python
project = client.projects.get("PROJECT_ID")
```

## Update project

```python
project = client.projects.update(
    project="PROJECT_ID",
    description="New project description",
)
```

## Delete project

```python
client.projects.delete("PROJECT_ID")
```

## Get tasks with annotations and predictions

```python
tasks = client.tasks.list(project="PROJECT_ID")
```

## Get task by ID

```python
task = client.tasks.get("TASK_ID")
print(task)
```
Task data, annotations and predictions in [Label Studio tasks format](https://labelstud.io/guide/task_format#Label-Studio-JSON-format-of-annotated-tasks):
```json
{
    "id": "TASK_ID",
    "data": {
        "image": "https://example.com/image.jpg",
        "label": "cat"
    },
    "annotations": [],
    "predictions": []
}
```

## Get all annotations for a task

```python
annotations = client.annotations.list(task="TASK_ID")
```

## Create a new task

```python
task = client.tasks.create(
    project="PROJECT_ID",
    data={
        "data": {
            "image": "https://example.com/image.jpg",
            "label": "cat"
        }
    }
)
```

## Import batch tasks

```python
tasks = client.projects.import_tasks(
    project="PROJECT_ID",
    data=[
        {
            "data": {
                "image": "https://example.com/image1.jpg",
                "label": "cat"
            }
        },
        {
            "data": {
                "image": "https://example.com/image2.jpg",
                "label": "dog"
            }
        }
    ]
)
```

## Update task

```python
task = client.tasks.update(
    project="PROJECT_ID",
    task="TASK_ID",
    data={
        "data": {
            "image": "https://example.com/image.jpg",
            "label": "dog"
        }
    }
)
```

## Delete task

```python
client.tasks.delete(project="PROJECT_ID", task="TASK_ID")
```

## Create prediction

```python
prediction = client.predictions.create(
    task="TASK_ID",
    result=[{'from_name': 'bbox', 'to_name': 'image', 'type': 'labels', 'value': {'rectanglelabels': [{'x': 10, 'y': 20, 'width': 30, 'height': 40, 'rectanglelabels': ['cat']}]}}],
    score=0.9,
    model_version='yolov8',
)
```

## Update prediction

```python
prediction = client.predictions.update(
    task="TASK_ID",
    prediction="PREDICTION_ID",
    result=[{'from_name': 'bbox', 'to_name': 'image', 'type': 'labels', 'value': {'rectanglelabels': [{'x': 10, 'y': 20, 'width': 30, 'height': 40, 'rectanglelabels': ['dog']}]}}],
    score=0.8,
    model_version='yolov8',
)
```

## Delete prediction

```python
client.predictions.delete(task="TASK_ID", prediction="PREDICTION_ID")
```

## Async client

```python
from label_studio_sdk.client import AsyncLabelStudio

client = AsyncLabelStudio(
    api_key="YOUR_API_KEY",
)
```

<!-- Begin Status, generated by Fern  -->
# Beta Status

This SDK is in beta, and there may be breaking changes between versions without a major 
version update. Therefore, we recommend pinning the package version to a specific version. 
This way, you can install the same version each time without breaking changes.
<!-- End Status  -->

<!-- Begin Contributing, generated by Fern  -->
# Contributing

While we value open-source contributions to this SDK, this library is generated programmatically. 
Additions made directly to this library would have to be moved over to our generation code, 
otherwise they would be overwritten upon the next generated release. Feel free to open a PR as
 a proof of concept, but know that we will not be able to merge it as-is. We suggest opening 
an issue first to discuss with us!

On the other hand, contributions to the README are always very welcome!
<!-- End Contributing  -->

