Task Annotations

Perform task annotations

---

In order to keep track of each user's work assigned to a task, all the annotations of this user related to this task should be linked to the task ID.

Therefore, when a user creates an annotation, the task ID should be provided as below:

Python

####################################################################################
# In this section, we set the user authentication, app ID, and the details for
# performing task annotations. Change these strings to run your own example.
###################################################################################

USER_ID = 'YOUR_USER_ID_HERE'
# Your PAT (Personal Access Token) can be found in the Account's Security section
PAT = 'YOUR_PAT_HERE'
APP_ID = 'YOUR_APP_ID_HERE'
# Change these to perform your own task annotations
INPUT_ID = 'c99f1b557d1d43d1916b46f8ce4a0487'
CONCEPT_ID_1 = 'tree'
CONCEPT_ID_2 = 'water'
TASK_ID = 'c37aed156e474e03bb5246576d9f48fd'

##########################################################################
# YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
##########################################################################

from clarifai_grpc.channel.clarifai_channel import ClarifaiChannel
from clarifai_grpc.grpc.api import resources_pb2, service_pb2, service_pb2_grpc
from clarifai_grpc.grpc.api.status import status_code_pb2
from google.protobuf.struct_pb2 import Struct

channel = ClarifaiChannel.get_grpc_channel()
stub = service_pb2_grpc.V2Stub(channel)

params = Struct()
params['task_id'] = TASK_ID

metadata = (('authorization', 'Key ' + PAT),)

userDataObject = resources_pb2.UserAppIDSet(user_id=USER_ID, app_id=APP_ID)

post_task_annotations_response = stub.PostAnnotations(
    service_pb2.PostAnnotationsRequest(
        user_app_id=userDataObject,  # The userDataObject is created in the overview and is required when using a PAT
        annotations=[
            resources_pb2.Annotation(
                input_id=INPUT_ID,
                data=resources_pb2.Data(
                    concepts=[
                        resources_pb2.Concept(id=CONCEPT_ID_1, value=1.),  # 1 means true, this concept is present
                        resources_pb2.Concept(id=CONCEPT_ID_2, value=0.)  # 0 means false, this concept is not present
                    ]
                ),
                annotation_info=params
            )
        ]
    ),
    metadata=metadata
)

if post_task_annotations_response.status.code != status_code_pb2.SUCCESS:
    print(post_task_annotations_response.status)
    raise Exception('Post task annotations failed, status: ' + post_task_annotations_response.status.description)

JavaScript (REST)

<!--index.html file-->

<script>
  //////////////////////////////////////////////////////////////////////////////////
  // In this section, we set the user authentication, app ID, and the details for
  // performing task annotations. Change these strings to run your own example.
  /////////////////////////////////////////////////////////////////////////////////

  const USER_ID = "YOUR_USER_ID_HERE";
  // Your PAT (Personal Access Token) can be found in the Account's Security section
  const PAT = "YOUR_PAT_HERE";
  const APP_ID = "YOUR_APP_ID_HERE";
  // Change these to perform your own task annotations
  const INPUT_ID = "c99f1b557d1d43d1916b46f8ce4a0487";
  const CONCEPT_ID_1 = "tree";
  const CONCEPT_ID_2 = "water";
  const TASK_ID = "c37aed156e474e03bb5246576d9f48fd";

  ///////////////////////////////////////////////////////////////////////////////////
  // YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
  ///////////////////////////////////////////////////////////////////////////////////

  const raw = JSON.stringify({
    user_app_id: {
      user_id: USER_ID,
      app_id: APP_ID,
    },
    annotations: [
      {
        input_id: INPUT_ID,
        data: {
          concepts: [
            {
              id: CONCEPT_ID_1,
              value: 1,
            },
            {
              id: CONCEPT_ID_2,
              value: 0,
            },
          ],
        },
        annotation_info: {
          task_id: TASK_ID,
        },
      },
    ],
  });

  const requestOptions = {
    method: "POST",
    headers: {
      Accept: "application/json",
      Authorization: "Key " + PAT,
    },
    body: raw,
  };

  fetch("https://api.clarifai.com/v2/annotations", requestOptions)
    .then((response) => response.text())
    .then((result) => console.log(result))
    .catch((error) => console.log("error", error));
</script>

NodeJS

//index.js file

////////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and the details for
// performing task annotations. Change these strings to run your own example.
////////////////////////////////////////////////////////////////////////////////////

const USER_ID = "YOUR_USER_ID_HERE";
// Your PAT (Personal Access Token) can be found in the Account's Security section
const PAT = "YOUR_PAT_HERE";
const APP_ID = "YOUR_APP_ID_HERE";
// Change these to perform your own task annotations
const INPUT_ID = "62bb672ccbdd4e5da55b41209d1a0e9f";
const CONCEPT_ID_1 = "tree";
const CONCEPT_ID_2 = "water";
const TASK_ID = "d0f2fa2b61234d1cb6b66983ea021b5b";

/////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
/////////////////////////////////////////////////////////////////////////////

const { ClarifaiStub, grpc } = require("clarifai-nodejs-grpc");

const stub = ClarifaiStub.grpc();

// This will be used by every Clarifai endpoint call
const metadata = new grpc.Metadata();
metadata.set("authorization", "Key " + PAT);

stub.PostAnnotations(
  {
    user_app_id: {
      user_id: USER_ID,
      app_id: APP_ID,
    },
    annotations: [
      {
        input_id: INPUT_ID,
        data: {
          concepts: [
            {
              id: CONCEPT_ID_1,
              value: 1,
            },
            {
              id: CONCEPT_ID_2,
              value: 0,
            },
          ],
        },
        annotation_info: {
          task_id: TASK_ID,
        },
      },
    ],
  },
  metadata,
  (err, response) => {
    if (err) {
      throw new Error(err);
    }

    if (response.status.code !== 10000) {
      throw new Error(
        "Post annotations failed, status: " + response.status.description
      );
    }
  }
);

Java

package com.clarifai.example;

import com.clarifai.grpc.api.*;
import com.clarifai.channel.ClarifaiChannel;
import com.clarifai.credentials.ClarifaiCallCredentials;
import com.clarifai.grpc.api.status.StatusCode;
import com.google.protobuf.Struct;
import com.google.protobuf.Value;

public class ClarifaiExample {

    //////////////////////////////////////////////////////////////////////////////////
    // In this section, we set the user authentication, app ID, and the details for
    // performing task annotations. Change these strings to run your own example.
    //////////////////////////////////////////////////////////////////////////////////

    static final String USER_ID = "YOUR_USER_ID_HERE";
    //Your PAT (Personal Access Token) can be found in the portal under Authentication	
    static final String PAT = "YOUR_PAT_HERE";
    static final String APP_ID = "YOUR_APP_ID_HERE";
    // Change these to perform your own task annotations  
    static final String INPUT_ID = "c99f1b557d1d43d1916b46f8ce4a0487";
    static final String CONCEPT_ID_1 = "tree";
    static final String CONCEPT_ID_2 = "water";
    static final String TASK_ID = "c37aed156e474e03bb5246576d9f48fd";

    ///////////////////////////////////////////////////////////////////////////////////
    // YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
    ///////////////////////////////////////////////////////////////////////////////////	

    public static void main(String[] args) {

        V2Grpc.V2BlockingStub stub = V2Grpc.newBlockingStub(ClarifaiChannel.INSTANCE.getGrpcChannel())
            .withCallCredentials(new ClarifaiCallCredentials(PAT));
        
        Struct.Builder params = Struct.newBuilder()
                .putFields("task_id", Value.newBuilder().setStringValue(TASK_ID).build());

        MultiAnnotationResponse postAnnotationsResponse = stub.postAnnotations(
            PostAnnotationsRequest.newBuilder()
            .setUserAppId(UserAppIDSet.newBuilder().setUserId(USER_ID).setAppId(APP_ID))
            .addAnnotations(
                Annotation.newBuilder()
                .setInputId(INPUT_ID)
                .setData(
                    Data.newBuilder().addConcepts(
                        Concept.newBuilder()
                        .setId(CONCEPT_ID_1)
                        .setValue(1f) // 1 means true, this concept is present
                        .build()
                    ).addConcepts(
                        Concept.newBuilder()
                        .setId(CONCEPT_ID_2)
                        .setValue(0f) // 0 means false, this concept is not present
                        .build()
                    )
                )
                .setAnnotationInfo(params)               
                .build()
            ).build()
        );

        if (postAnnotationsResponse.getStatus().getCode() != StatusCode.SUCCESS) {
            throw new RuntimeException("Post annotations failed, status: " + postAnnotationsResponse.getStatus());
        }

    }

}

PHP

<?php

require __DIR__ . "/vendor/autoload.php";

////////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and details for 
// performing task annotations. Change these strings to run your own example.
////////////////////////////////////////////////////////////////////////////////////

$USER_ID = "YOUR_USER_ID_HERE";
// Your PAT (Personal Access Token) can be found in the Account's Security section
$PAT = "YOUR_PAT_HERE";
$APP_ID = "YOUR_APP_ID_HERE";
// Change these to perform your own task annotations
$INPUT_ID = "62bb672ccbdd4e5da55b41209d1a0e9f";
$CONCEPT_ID_1 = "tree";
$CONCEPT_ID_2 = "water";
$TASK_ID = "d0f2fa2b61234d1cb6b66983ea021b5b";

///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////

use Clarifai\ClarifaiClient;
use Clarifai\Api\PostAnnotationsRequest;
use Clarifai\Api\Annotation;
use Clarifai\Api\Concept;
use Clarifai\Api\Data;
use Clarifai\Api\Status\StatusCode;
use Clarifai\Api\UserAppIDSet;
use Google\Protobuf\Struct;
use Google\Protobuf\Value;

$client = ClarifaiClient::grpc();

$metadata = ["Authorization" => ["Key " . $PAT]];

$userDataObject = new UserAppIDSet([
    "user_id" => $USER_ID,
    "app_id" => $APP_ID
]);

// create Struct instance
$params = new Struct();
$params->getFields()->offsetSet("task_id", (new Value())->setStringValue($TASK_ID));

// Let's make a RPC call to the Clarifai platform. It uses the opened gRPC client channel to communicate a
// request and then wait for the response
[$response, $status] = $client->PostAnnotations(
    // The request object carries the request along with the request status and other metadata related to the request itself
    new PostAnnotationsRequest([
        "user_app_id" => $userDataObject, 
        "annotations" => [
             new Annotation([
                "input_id" => $INPUT_ID,
                "data" => new Data([
                    "concepts" => [
                        new Concept(["id" => $CONCEPT_ID_1, "value" => 1.]),
                        new Concept(["id" => $CONCEPT_ID_2, "value" => 0.])
                    ]
                    ]),
                "annotation_info" => $params
             ])
        ]
    ]),
    $metadata
)->wait();

// A response is returned and the first thing we do is check the status of it
// A successful response will have a status code of 0; otherwise, there is some error
if ($status->code !== 0) {
    throw new Exception("Error: {$status->details}");
}
// In addition to the RPC response status, there is a Clarifai API status that reports if the operation was a success or failure 
// (not just that the communication was successful)
if ($response->getStatus()->getCode() != StatusCode::SUCCESS) {
    print $response->getStatus()->getDetails();
    throw new Exception("Failure response: " . $response->getStatus()->getDescription());
}

?>

cURL

curl -X POST "https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/apps/YOUR_APP_ID_HERE/annotations" \
  -H "Authorization: Key YOUR_PAT_HERE" \
  -H "Content-Type: application/json" \
  -d '{
      "annotations": [
        {
          "input_id": "INPUT_ID_HERE",
          "data": {
            "concepts": [
              {
                "id": "tree",
                "value": 1
              },
              {
                "id": "water",
                "value": 0
              }
            ]
          },
          "annotation_info": {
            "task_id": "TASK_ID_HERE"
          }
        }
      ]
    }'