@toloka-platform/sdk 0.1.0-preview.3

package/examples/video-pair-rating/nodes/adjudicate/node.ts

@@ -0,0 +1,162 @@
+import { generation } from "@toloka-platform/sdk";
+
+import { adjudicatedMetrics, disagreedMetrics, prompt, videoA, videoB } from "../../fields";
+
+export const adjudicate = generation("adjudicate", {
+  about: {
+    description:
+      "A senior rater breaks ties on the metrics where the quorum disagreed. Both videos are shown in their original order, never the shuffled one.",
+    projectType: "general",
+  },
+  publicName: "Senior video comparison adjudication",
+  instruction:
+    "You are resolving a disagreement between two raters. Watch both videos in full. For every metric listed as disputed, choose the video that is better on that metric alone, or tie when they are genuinely equal. Judge only the metric named; do not let overall impression carry across metrics.",
+  entities: {
+    input: [
+      {
+        field: prompt,
+        entityType: "PROMPT",
+        description: "The text prompt both videos were generated from.",
+      },
+      {
+        field: videoA,
+        entityType: "VIDEO",
+        description: "First generated video, in original order.",
+      },
+      {
+        field: videoB,
+        entityType: "VIDEO",
+        description: "Second generated video, in original order.",
+      },
+      {
+        field: disagreedMetrics,
+        entityType: "METADATA",
+        description: "Names of the metrics the raters did not agree on.",
+      },
+    ],
+    output: [
+      {
+        field: adjudicatedMetrics,
+        entityType: "JUDGEMENT",
+        jsonPath: "$.adjudicated_metrics",
+        description: "One tiebreaking value per disputed metric, keyed by metric name.",
+      },
+    ],
+  },
+  qualityCriteria: [
+    {
+      id: "b71c9f8e-5d2a-4c31-9f47-2ae6d3c81b04",
+      qualityElement: "Metric isolation",
+      thresholds: {
+        pass: "Each disputed metric is decided on its own evidence, and a tie is used only when the videos are genuinely equal on that metric.",
+        fail: "One overall impression is applied across every metric, or tie is used to avoid deciding.",
+      },
+      targetEntity: adjudicatedMetrics,
+    },
+    {
+      id: "c9a4e217-8b60-4f5d-83ac-1d7f9e402b65",
+      qualityElement: "Completeness",
+      thresholds: {
+        pass: "Every metric listed as disputed receives a decision.",
+        fail: "A disputed metric is left undecided.",
+      },
+      targetEntity: adjudicatedMetrics,
+    },
+  ],
+  ui: {
+    code: "<View.Group><If condition={actions.get('disagreed_metrics', []).includes('image_text_alignment')}><Field.SelectGroup path={'adjudicated_metrics.image_text_alignment'} label={'Imagery matches the prompt'} options={[{ label: 'First video', value: 'video_a' }, { label: 'Second video', value: 'video_b' }, { label: 'Tie', value: 'tie' }]} /></If><If condition={actions.get('disagreed_metrics', []).includes('motion_text_alignment')}><Field.SelectGroup path={'adjudicated_metrics.motion_text_alignment'} label={'Motion matches the prompt'} options={[{ label: 'First video', value: 'video_a' }, { label: 'Second video', value: 'video_b' }, { label: 'Tie', value: 'tie' }]} /></If><If condition={actions.get('disagreed_metrics', []).includes('image_quality')}><Field.SelectGroup path={'adjudicated_metrics.image_quality'} label={'Image quality'} options={[{ label: 'First video', value: 'video_a' }, { label: 'Second video', value: 'video_b' }, { label: 'Tie', value: 'tie' }]} /></If><If condition={actions.get('disagreed_metrics', []).includes('motion_quality')}><Field.SelectGroup path={'adjudicated_metrics.motion_quality'} label={'Motion quality'} options={[{ label: 'First video', value: 'video_a' }, { label: 'Second video', value: 'video_b' }, { label: 'Tie', value: 'tie' }]} /></If><If condition={actions.get('disagreed_metrics', []).includes('subject_background_consistency')}><Field.SelectGroup path={'adjudicated_metrics.subject_background_consistency'} label={'Subject and background consistency'} options={[{ label: 'First video', value: 'video_a' }, { label: 'Second video', value: 'video_b' }, { label: 'Tie', value: 'tie' }]} /></If><If condition={actions.get('disagreed_metrics', []).includes('video_realism')}><Field.SelectGroup path={'adjudicated_metrics.video_realism'} label={'Realism'} options={[{ label: 'First video', value: 'video_a' }, { label: 'Second video', value: 'video_b' }, { label: 'Tie', value: 'tie' }]} /></If></View.Group>",
+    data: '{"prompt":"a red fox crossing a snowy field at dawn","video_a":"https://example.com/video-a.mp4","video_b":"https://example.com/video-b.mp4","disagreed_metrics":["image_quality","motion_quality"]}',
+    preprocess: "return {}",
+    postprocess: "return {};",
+    constants: "{}",
+  },
+  qualityAssurance: {
+    qaMode: "llm_only",
+    llmQaModelId: "gpt-5.4",
+  },
+  onboarding: {
+    enabled: true,
+    steps: [
+      {
+        id: "step-1",
+        blocks: [
+          {
+            id: "block-1",
+            type: "text",
+            content: [
+              {
+                type: "markdown",
+                value:
+                  "You are the tiebreaker. Two raters watched the same pair of generated videos and disagreed on at least one quality metric. Your decision becomes the final value for that metric.",
+              },
+            ],
+          },
+        ],
+      },
+      {
+        id: "step-2",
+        blocks: [
+          {
+            id: "block-2",
+            type: "text",
+            content: [
+              {
+                type: "markdown",
+                value:
+                  "Decide one metric at a time. A video can be sharper and still lose on motion. Reserve tie for cases where you would flip a coin, not for cases you find hard.",
+              },
+            ],
+          },
+        ],
+      },
+      {
+        id: "step-3",
+        blocks: [
+          {
+            id: "block-3",
+            type: "quiz",
+            questions: [
+              {
+                id: "question-1",
+                type: "single-choice",
+                question:
+                  "The first video is visibly sharper, but its subject changes shape halfway through. The disputed metric is motion quality. Which do you pick?",
+                options: [
+                  { value: "video_a", label: "The first video, because it is sharper" },
+                  { value: "video_b", label: "The second video, because its motion is stable" },
+                  { value: "tie", label: "A tie, because each is better in one way" },
+                ],
+                correctAnswer: "video_b",
+                correctAnswerFeedback:
+                  "Correct. Sharpness belongs to image quality; motion quality is judged on motion alone.",
+                incorrectAnswerFeedback:
+                  "Judge the named metric only. Sharpness is image quality, not motion quality.",
+              },
+            ],
+          },
+        ],
+      },
+    ],
+    info: {
+      estimatedTime: "5 minutes",
+      role: "Senior video rater",
+      goal: "Resolve disputed quality metrics between two raters",
+      successCriteria: "Every disputed metric receives an isolated, defensible decision",
+    },
+  },
+  audienceAndPricing: {
+    audienceType: "human",
+    verifiedExperts: true,
+    audience: {
+      languages: { type: "and", values: [{ value: "English" }] },
+      specializations: { type: "and", values: [] },
+      countries: { type: "or", values: [] },
+    },
+    pricePerTask: 0.4,
+    timeForTask: 180,
+    perExpertCapEnabled: false,
+    perExpertCapValue: 1,
+  },
+  reuseAudienceWithNodeId: null,
+  smartSearch: null,
+});

package/examples/video-pair-rating/nodes/adjudicate_op/node.ts

@@ -0,0 +1,152 @@
+import { generation } from "@toloka-platform/sdk";
+
+import { opAdjudicatedValue, prompt, videoA, videoB } from "../../fields";
+
+export const adjudicateOp = generation("adjudicate_op", {
+  about: {
+    description:
+      "A senior rater settles overall preference when the quorum vote on it did not converge. Runs only for the overall preference metric, after the per-metric branch has finished.",
+    projectType: "general",
+  },
+  publicName: "Senior overall preference adjudication",
+  instruction:
+    "Two raters disagreed on which video is better overall. Watch both in full and pick the one you would ship, or tie when neither is preferable. Overall preference is a whole-video judgment: weigh how the video reads as a finished result, not any single metric.",
+  entities: {
+    input: [
+      {
+        field: prompt,
+        entityType: "PROMPT",
+        description: "The text prompt both videos were generated from.",
+      },
+      {
+        field: videoA,
+        entityType: "VIDEO",
+        description: "First generated video, in original order.",
+      },
+      {
+        field: videoB,
+        entityType: "VIDEO",
+        description: "Second generated video, in original order.",
+      },
+    ],
+    output: [
+      {
+        field: opAdjudicatedValue,
+        entityType: "SINGLE_LABEL",
+        jsonPath: "$.op_adjudicated_value",
+        description: "The final overall preference: the first video, the second, or a tie.",
+      },
+    ],
+  },
+  qualityCriteria: [
+    {
+      id: "e2f1a7c4-6b93-4d58-8a02-5c7e1b4f9d36",
+      qualityElement: "Whole-video judgment",
+      thresholds: {
+        pass: "The choice reflects the video as a finished result, and a tie is used only when neither would be preferred.",
+        fail: "The choice is driven by one isolated defect or by resolution alone, or tie is used to avoid deciding.",
+      },
+      targetEntity: opAdjudicatedValue,
+    },
+  ],
+  ui: {
+    code: "<Field.SelectGroup path={'op_adjudicated_value'} options={[{ label: 'First video', value: 'video_a' }, { label: 'Second video', value: 'video_b' }, { label: 'Tie', value: 'tie' }]} />",
+    data: '{"prompt":"a red fox crossing a snowy field at dawn","video_a":"https://example.com/video-a.mp4","video_b":"https://example.com/video-b.mp4"}',
+    preprocess: "return {}",
+    postprocess: "return {};",
+    constants: "{}",
+  },
+  qualityAssurance: {
+    qaMode: "llm_only",
+    llmQaModelId: "gpt-5.4",
+  },
+  onboarding: {
+    enabled: true,
+    steps: [
+      {
+        id: "step-1",
+        blocks: [
+          {
+            id: "block-1",
+            type: "text",
+            content: [
+              {
+                type: "markdown",
+                value:
+                  "You decide overall preference when two raters could not agree. Unlike the per-metric task, this is one judgment about the whole video.",
+              },
+            ],
+          },
+        ],
+      },
+      {
+        id: "step-2",
+        blocks: [
+          {
+            id: "block-2",
+            type: "text",
+            content: [
+              {
+                type: "markdown",
+                value:
+                  "A video can lose on a single metric and still be the one you would ship. Weigh the result as a viewer would see it, and use tie only when you genuinely have no preference.",
+              },
+            ],
+          },
+        ],
+      },
+      {
+        id: "step-3",
+        blocks: [
+          {
+            id: "block-3",
+            type: "quiz",
+            questions: [
+              {
+                id: "question-1",
+                type: "single-choice",
+                question:
+                  "The second video has slightly weaker background consistency but matches the prompt closely and reads well end to end. The first ignores half the prompt. Which is preferred overall?",
+                options: [
+                  {
+                    value: "video_a",
+                    label: "The first video, because its background is steadier",
+                  },
+                  { value: "video_b", label: "The second video, because it delivers the prompt" },
+                  { value: "tie", label: "A tie, because each wins on something" },
+                ],
+                correctAnswer: "video_b",
+                correctAnswerFeedback:
+                  "Correct. Overall preference weighs the finished result, and ignoring the prompt is the larger failure.",
+                incorrectAnswerFeedback:
+                  "Overall preference is not the sum of metric wins. A video that ignores the prompt is not the one you would ship.",
+              },
+            ],
+          },
+        ],
+      },
+    ],
+    info: {
+      estimatedTime: "5 minutes",
+      role: "Senior video rater",
+      goal: "Settle overall preference between two generated videos",
+      successCriteria:
+        "A defensible whole-video decision, with tie reserved for genuine indifference",
+    },
+  },
+  audienceAndPricing: {
+    audienceType: "human",
+    verifiedExperts: true,
+    audience: {
+      languages: { type: "and", values: [{ value: "English" }] },
+      specializations: { type: "and", values: [] },
+      countries: { type: "or", values: [] },
+    },
+    pricePerTask: 0.4,
+    timeForTask: 180,
+    perExpertCapEnabled: false,
+    perExpertCapValue: 1,
+  },
+  reuseAudienceWithNodeId: null,
+  smartSearch: null,
+});

package/examples/video-pair-rating/nodes/adjudication_match/node.ts

@@ -0,0 +1,95 @@
+import { code } from "@toloka-platform/sdk";
+import {
+  raterItaVotes,
+  raterIqVotes,
+  raterOpVotes,
+  disagreedMetrics,
+  finalMetrics,
+  needsOverallManual,
+  opNeedsAdjudication,
+  finalOpValue,
+  raterItaMatchesAdjudication,
+  raterIqMatchesAdjudication,
+  raterOpMatchesAdjudication,
+} from "../../fields";
+
+export const adjudicationMatch = code("adjudication_match", {
+  about: {
+    name: "adjudication_match",
+    description:
+      "Computes per-rater matches_adjudication booleans for image_text_alignment, image_quality, and overall preference. Only populated when adjudication actually ran; otherwise null.",
+  },
+  envVars: [],
+  fieldProxies: {
+    input: [
+      { field: raterItaVotes, optional: false },
+      { field: raterIqVotes, optional: false },
+      { field: raterOpVotes, optional: true },
+      { field: disagreedMetrics, optional: false },
+      { field: finalMetrics, optional: false },
+      { field: needsOverallManual, optional: false },
+      { field: opNeedsAdjudication, optional: true },
+      { field: finalOpValue, optional: true },
+    ],
+    output: [
+      { field: raterItaMatchesAdjudication, optional: false },
+      { field: raterIqMatchesAdjudication, optional: false },
+      { field: raterOpMatchesAdjudication, optional: false },
+    ],
+  },
+  code: {
+    code: `from main_types import Inputs, Outputs
+
+
+async def main(inputs: Inputs) -> Outputs:
+    rater_ita_votes = list(inputs.get("rater_ita_votes") or [])
+    rater_iq_votes = list(inputs.get("rater_iq_votes") or [])
+    rater_op_votes = inputs.get("rater_op_votes")
+    disagreed_metrics = list(inputs.get("disagreed_metrics") or [])
+    final_metrics = dict(inputs.get("final_metrics") or {})
+    needs_overall_manual = inputs.get("needs_overall_manual", "false") == "true"
+    op_needs_adjudication_flag = inputs.get("op_needs_adjudication")
+    final_op_value = inputs.get("final_op_value")
+
+    # ITA / IQ: only compute when adjudication resolved a disagreement on
+    # that specific metric — that's when raters actually get graded vs the
+    # senior adjudicator. Otherwise there was no adjudicator verdict to
+    # compare against, so emit null.
+    def _matches(votes, final_value):
+        if final_value is None:
+            return None
+        return [v == final_value for v in votes]
+
+    rater_ita_matches = None
+    if "image_text_alignment" in disagreed_metrics:
+        rater_ita_matches = _matches(
+            rater_ita_votes, final_metrics.get("image_text_alignment")
+        )
+
+    rater_iq_matches = None
+    if "image_quality" in disagreed_metrics:
+        rater_iq_matches = _matches(
+            rater_iq_votes, final_metrics.get("image_quality")
+        )
+
+    # OP: adjudication ran only when the manual OP quorum was invoked AND
+    # the OP adjudicator was called (op_needs_adjudication == 'true').
+    # Otherwise the OP was decided by cascade (no manual raters) or by
+    # manual quorum majority (no adjudicator), so no adjudicator-vs-rater
+    # comparison is possible.
+    rater_op_matches = None
+    if (
+        needs_overall_manual
+        and op_needs_adjudication_flag == "true"
+        and rater_op_votes is not None
+        and final_op_value is not None
+    ):
+        rater_op_matches = [v == final_op_value for v in list(rater_op_votes)]
+
+    return {
+        "rater_ita_matches_adjudication": rater_ita_matches,
+        "rater_iq_matches_adjudication": rater_iq_matches,
+        "rater_op_matches_adjudication": rater_op_matches,
+    }`,
+  },
+});

package/examples/video-pair-rating/nodes/assemble/node.ts

@@ -0,0 +1,87 @@
+import { code } from "@toloka-platform/sdk";
+import * as f from "../../fields";
+
+export const assemble = code("assemble", {
+  about: {
+    name: "assemble",
+    description:
+      "Assembles the final JSONL delivery record containing all evaluation results: video identifiers, text prompt, per-metric scores, overall preference, annotator metadata, resolution method, rater vote history, and a UTC timestamp.",
+  },
+  envVars: [],
+  fieldProxies: {
+    input: [
+      { field: f.recordId, optional: false },
+      { field: f.prompt, optional: false },
+      { field: f.videoA, optional: false },
+      { field: f.videoB, optional: false },
+      { field: f.finalMetrics, optional: false },
+      { field: f.overallPreference, optional: false },
+      { field: f.overallPreferenceSource, optional: false },
+      { field: f.resolutionMethod, optional: false },
+      { field: f.annotatorIdAdjudicator, optional: false },
+      { field: f.raterItaVotes, optional: false },
+      { field: f.raterMtaVotes, optional: false },
+      { field: f.raterIqVotes, optional: false },
+      { field: f.raterMqVotes, optional: false },
+      { field: f.raterSbcVotes, optional: false },
+      { field: f.raterVrVotes, optional: false },
+      { field: f.raterOpVotes, optional: true },
+      { field: f.raterDurationSeconds, optional: true },
+      { field: f.raterBothPlayed, optional: true },
+      { field: f.raterItaMatchesAdjudication, optional: false },
+      { field: f.raterIqMatchesAdjudication, optional: false },
+      { field: f.raterOpMatchesAdjudication, optional: false },
+    ],
+    output: [{ field: f.deliveryRecord, optional: false }],
+  },
+  code: {
+    code: `from datetime import datetime, timezone
+from main_types import Inputs, Outputs
+
+
+async def main(inputs: Inputs) -> Outputs:
+    final_metrics = dict(inputs.get("final_metrics") or {})
+
+    delivery = {
+        "record_id": inputs["record_id"],
+        "video_a_url": inputs["video_a"],
+        "video_b_url": inputs["video_b"],
+        "text_prompt": inputs["prompt"],
+        "overall_preference": inputs["overall_preference"],
+        # Enum in {alignment, quality, manual} -- matches spec 01 FIELD-ROW-11.
+        "overall_preference_source": inputs["overall_preference_source"],
+        # Enum in {agreement, adjudication} -- how the OP (or metrics) were resolved.
+        "resolution_method": inputs.get("resolution_method"),
+        "video_image_quality": final_metrics.get("image_quality"),
+        "video_motion_quality": final_metrics.get("motion_quality"),
+        "subject_background_consistency": final_metrics.get(
+            "subject_background_consistency"
+        ),
+        "video_realism": final_metrics.get("video_realism"),
+        "video_image_text_alignment": final_metrics.get("image_text_alignment"),
+        "video_motion_text_alignment": final_metrics.get("motion_text_alignment"),
+        # Platform limitation: rater ids are not surfaced as field proxies
+        # from the quorum node in this pilot. Stubs preserve schema conformance.
+        "annotator_id_1": None,
+        "annotator_id_2": None,
+        "annotator_id_adjudicator": inputs.get("annotator_id_adjudicator"),
+        "timestamp": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+        # Round C -- QA reporting bundle. Client computes kappa / AHT distributions
+        # offline and manually offboards raters via the Toloka console.
+        "rater_ita_votes": list(inputs.get("rater_ita_votes") or []),
+        "rater_mta_votes": list(inputs.get("rater_mta_votes") or []),
+        "rater_iq_votes": list(inputs.get("rater_iq_votes") or []),
+        "rater_mq_votes": list(inputs.get("rater_mq_votes") or []),
+        "rater_sbc_votes": list(inputs.get("rater_sbc_votes") or []),
+        "rater_vr_votes": list(inputs.get("rater_vr_votes") or []),
+        "rater_op_votes": inputs.get("rater_op_votes"),
+        "rater_durations_seconds": inputs.get("rater_duration_seconds"),
+        "rater_both_videos_played": inputs.get("rater_both_played"),
+        "rater_ita_matches_adjudication": inputs.get("rater_ita_matches_adjudication"),
+        "rater_iq_matches_adjudication": inputs.get("rater_iq_matches_adjudication"),
+        "rater_op_matches_adjudication": inputs.get("rater_op_matches_adjudication"),
+    }
+
+    return {"delivery_record": delivery}`,
+  },
+});

package/examples/video-pair-rating/nodes/cascade/node.ts

@@ -0,0 +1,166 @@
+import { code } from "@toloka-platform/sdk";
+import * as f from "../../fields";
+
+export const cascade = code("cascade", {
+  about: {
+    name: "cascade",
+    description:
+      "Un-swaps each rater per-metric vote back to canonical video_a/video_b/tie labels using the swap flag. Computes per-metric majority agreement and flags metrics requiring adjudication. Applies a deterministic Overall Preference cascade: image-text alignment decides first, then image quality, falling back to manual review.",
+  },
+  envVars: [],
+  fieldProxies: {
+    input: [
+      { field: f.swap, optional: false },
+      { field: f.imageTextAlignment, optional: false },
+      { field: f.motionTextAlignment, optional: false },
+      { field: f.imageQuality, optional: false },
+      { field: f.motionQuality, optional: false },
+      { field: f.subjectBackgroundConsistency, optional: false },
+      { field: f.videoRealism, optional: false },
+    ],
+    output: [
+      { field: f.perMetricResolved, optional: false },
+      { field: f.needsAdjudication, optional: false },
+      { field: f.disagreedTask, optional: false },
+      { field: f.disagreedMetrics, optional: false },
+      { field: f.opValueOrNull, optional: false },
+      { field: f.opSource, optional: false },
+      { field: f.needsOverallManual, optional: false },
+      { field: f.raterItaVotes, optional: false },
+      { field: f.raterMtaVotes, optional: false },
+      { field: f.raterIqVotes, optional: false },
+      { field: f.raterMqVotes, optional: false },
+      { field: f.raterSbcVotes, optional: false },
+      { field: f.raterVrVotes, optional: false },
+    ],
+  },
+  code: {
+    code: `from main_types import Inputs, Outputs
+
+METRICS_TASK_A = ["image_text_alignment", "motion_text_alignment"]
+METRICS_TASK_B = [
+    "image_quality",
+    "motion_quality",
+    "subject_background_consistency",
+    "video_realism",
+]
+PER_METRIC_FIELDS = METRICS_TASK_A + METRICS_TASK_B
+
+
+def _unswap(val: str, swap: bool) -> str:
+    """Translate 'video_1'/'video_2' back to 'video_a'/'video_b'.
+    Pass-through for 'tie' and 'none' (labels that don't reference position)."""
+    if val in ("tie", "none"):
+        return val
+    if swap:
+        return "video_a" if val == "video_2" else "video_b"
+    return "video_a" if val == "video_1" else "video_b"
+
+
+async def main(inputs: Inputs) -> Outputs:
+    swap: bool = bool(inputs["swap"])
+
+    raw_by_metric = {
+        "image_text_alignment": list(inputs["image_text_alignment"]),
+        "motion_text_alignment": list(inputs["motion_text_alignment"]),
+        "image_quality": list(inputs["image_quality"]),
+        "motion_quality": list(inputs["motion_quality"]),
+        "subject_background_consistency": list(inputs["subject_background_consistency"]),
+        "video_realism": list(inputs["video_realism"]),
+    }
+
+    unswapped = {
+        metric: [_unswap(v, swap) for v in votes]
+        for metric, votes in raw_by_metric.items()
+    }
+
+    per_metric_resolved = {}
+    disagreed_metrics = []
+    for metric in PER_METRIC_FIELDS:
+        votes = unswapped[metric]
+        counts = {}
+        for v in votes:
+            counts[v] = counts.get(v, 0) + 1
+        n = len(votes)
+        threshold = (n // 2) + 1
+        winner = None
+        for opt, c in counts.items():
+            if c >= threshold:
+                winner = opt
+                break
+        if winner is not None:
+            per_metric_resolved[metric] = winner
+        else:
+            disagreed_metrics.append(metric)
+
+    needs_adjudication = len(disagreed_metrics) > 0
+
+    dis_a = any(m in METRICS_TASK_A for m in disagreed_metrics)
+    dis_b = any(m in METRICS_TASK_B for m in disagreed_metrics)
+    if dis_a and dis_b:
+        disagreed_task = "both"
+    elif dis_a:
+        disagreed_task = "task_a"
+    elif dis_b:
+        disagreed_task = "task_b"
+    else:
+        disagreed_task = "none"
+
+    # Overall Preference cascade with the new op_source enum
+    #   {alignment, quality, manual}.
+    # Tier 1: image_text_alignment resolved & is video_a/video_b -> alignment.
+    # Tier 2: image_quality resolved & is video_a/video_b (NOT tie, NOT none) -> quality.
+    # Otherwise: manual.
+    op_value_or_null = None
+    op_source = "manual"
+    needs_overall_manual = "true"
+
+    ita = per_metric_resolved.get("image_text_alignment")
+    iq = per_metric_resolved.get("image_quality")
+
+    if ita in ("video_a", "video_b"):
+        op_value_or_null = ita
+        op_source = "alignment"
+        needs_overall_manual = "false"
+    elif iq in ("video_a", "video_b"):
+        op_value_or_null = iq
+        op_source = "quality"
+        needs_overall_manual = "false"
+    else:
+        # Neither cascade tier resolved to a winner. If either tier is still
+        # unresolved (pending adjudication), the merge step re-runs the cascade
+        # against final_metrics -- flag no-manual so adjudicator has a chance
+        # to settle it first.
+        pending_cascade = (
+            "image_text_alignment" in disagreed_metrics
+            or "image_quality" in disagreed_metrics
+        )
+        if pending_cascade:
+            needs_overall_manual = "false"
+            op_source = "manual"
+            op_value_or_null = None
+        else:
+            # Both cascade tiers resolved but neither picked a winner:
+            # ita=='tie' and iq in {'tie','none'}. Route to manual quorum.
+            needs_overall_manual = "true"
+            op_source = "manual"
+            op_value_or_null = None
+
+    return {
+        "per_metric_resolved": per_metric_resolved,
+        "needs_adjudication": "true" if needs_adjudication else "false",
+        "disagreed_task": disagreed_task,
+        "disagreed_metrics": disagreed_metrics,
+        "op_value_or_null": op_value_or_null,
+        "op_source": op_source,
+        "needs_overall_manual": needs_overall_manual,
+        # Round C: forward un-swapped rater votes for QA reporting.
+        "rater_ita_votes": unswapped["image_text_alignment"],
+        "rater_mta_votes": unswapped["motion_text_alignment"],
+        "rater_iq_votes": unswapped["image_quality"],
+        "rater_mq_votes": unswapped["motion_quality"],
+        "rater_sbc_votes": unswapped["subject_background_consistency"],
+        "rater_vr_votes": unswapped["video_realism"],
+    }`,
+  },
+});