Annotations SDK Reference - Orq.ai Documentation

Annotations

Create an Annotation

Attach one or more annotations to a specific span. A standard annotation references a human review by key and supplies a value. A correction references an existing evaluator output by parent_annotation_id and supplies the corrected value, validated against that evaluator’s output schema.

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY"),
) as orq:

    orq.annotations.create(trace_id="<id>", span_id="<id>", annotations=[{"key": "quality", "value": "good"}])

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  await orq.annotations.create({
    traceId: "<id>",
    spanId: "<id>",
    requestBody: {
      annotations: [{ key: "quality", value: "good" }],
    },
  });

}

run();

Show Parameters

{
    "trace_id": str,  # required
    "span_id": str,  # required
    "annotations": List[Union[Annotations1, Annotations2]],  # required
    "metadata": {  # optional
        "identity_id": Optional[str],
    },
}

{
  traceId: string;  // required
  spanId: string;  // required
  requestBody: {  // required
    annotations: (Annotations1 | Annotations2)[];  // required
    metadata?: {
      identityId?: string;
    };
  };
}

Show Variant types

Annotations1

{
    "key": str,
    "value": Union[str, float, bool, List[str]],
}

{
  key: string;
  value: string | number | boolean | string[];
}

Annotations2

{
    "parent_annotation_id": str,
    "value": Union[str, float, bool, List[str]],
    "explanation": Optional[str],
}

{
  parentAnnotationId: string;
  value: string | number | boolean | string[];
  explanation?: string;
}

Delete an Annotation

Remove one or more annotations from a specific span by their evaluator keys, or remove corrections by the eval ids of their parent annotations.

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY"),
) as orq:

    orq.annotations.delete(trace_id="<id>", span_id="<id>", keys=["quality"])

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  await orq.annotations.delete({
    traceId: "<id>",
    spanId: "<id>",
    requestBody: {
      keys: ["quality"],
    },
  });

}

run();

Show Parameters

{
    "trace_id": str,  # required
    "span_id": str,  # required
    "keys": List[str],  # optional
    "parent_annotation_ids": List[str],  # optional
    "metadata": {  # optional
        "identity_id": Optional[str],
    },
}

{
  traceId: string;  // required
  spanId: string;  // required
  requestBody: {  // required
    keys?: string[];
    parentAnnotationIds?: string[];
    metadata?: {
      identityId?: string;
    };
  };
}