docs: update results example to aggregator v4 format

[RapidPoseidon]

The "Interpreting the Results" page still showed the v3.0.0 results format. This updates it to the current v4.0.0 shape:

• info now carries orderType, name, and instruction (the per-result context field is gone)
• results reference options by full asset URL instead of bare filename
• new assetUrls field documented: maps each option to the Rapidata-hosted copy shown to labelers
• example trimmed to 3 detailed responses (consistent with the intro) with aggregate numbers matching

Docs build verified with uv run --group docs mkdocs build.

🔗 Session: https://session-820df9fa.poseidon.rapidata.internal/

[claude]

Review

Docs-only change updating the COMPARE results example from aggregator v3.0.0 to v4.0.0. Overall this is accurate and well done — verified against the codebase:

Strengths

• The new orderType and assetUrls fields documented here are indeed consumed by src/rapidata/rapidata_client/results/rapidata_results.py (_extract_compare_assets prefers assetUrls, and to_pandas branches on info.orderType), so the example accurately reflects real backend/SDK behavior rather than being purely illustrative.
• The numbers in the example are internally consistent: summedUserScores (2.552) is the exact sum of the three userScores.global values (0.845 + 0.8349 + 0.8721), aggregatedResultsRatios/summedUserScoresRatios correctly compute to 1.0/0.0 given all 3 votes went to the same option, and winner_index/winner line up with the key order in assetUrls/aggregatedResults.
• Renumbering the "Breakdown" list (info → results → summary) to match the reordered JSON (summary moved to the end) is a nice consistency touch.
• Confirms with the PR description: context is indeed gone and options are referenced by full URL rather than bare filename.

Minor nits (non-blocking)

• The added note "demographics ... May be empty if no demographic data was collected for the labeler" is no longer illustrated by the example — all three detailedResults entries now have populated demographics (the old example had one empty {} case). Might be worth keeping one empty-demographics entry in the sample to visually back up that note.
• The example instruction ("Which image shows: 'A small blue book sitting on a large red book.'?") reads more like a classify/identify-style prompt than a typical preference-comparison instruction (e.g. "Which image better matches..."). Not wrong, just slightly inconsistent framing for an orderType: Compare example — worth a tweak if you want the sample to read naturally for a comparison task.

No code changes are involved, so the pyright/black requirements in CLAUDE.md don't apply here. No test coverage concerns since this is a documentation-only change (verified with mkdocs build per the PR description).

[EliasTeikari]

@RapidPoseidon could you leave out the CDN https route and just the file name, this increase better readibility

[RapidPoseidon]

Done in fa6f1be — options now use bare filenames throughout the example (keys, winner, votedFor). I kept the assetUrls values as full URLs since pointing to the Rapidata-hosted copy is that field's purpose.

[claude]

Review: docs update to aggregator v4 format

Nice, focused doc update — the JSON example and the breakdown both changed together and stay internally consistent.

Verified correctness of the example data:

• summedUserScores.flux-1-pro_37_0.jpg (2.552) = sum of the three userScores.global values (0.845 + 0.8349 + 0.8721) ✓
• aggregatedResults (3 votes for flux, 0 for midjourney) matches the 3 detailedResults entries, all votedFor: flux-1-pro_37_0.jpg ✓
• Ratios (0.0 / 1.0) are consistent with the above ✓
• winner_index: 1 / winner: flux-1-pro_37_0.jpg matches summary.B_wins_total: 1 ✓
• Reordering results and summary in the JSON to match the renumbered breakdown (1. info, 2. results, 3. summary) is a nice touch for readability.

Minor observations / suggestions (non-blocking):

1. docs/confidence_stopping.md:112 still shows a results example with "version": "3.0.0". Since this PR is specifically about bringing the results-format docs in line with v4.0.0, it might be worth updating that example too (or filing a follow-up) to avoid two docs pages showing different schema versions for the same concept.
2. The new instruction field is documented as living under info (order-level), while the old context field it replaces was per-result. Worth double-checking that's intentional for tasks where different pairs/comparisons in the same order could have distinct prompts (e.g. multi-prompt validation sets) — if so, might be worth a one-line note clarifying that instruction is the order-level instruction rather than per-comparison context, since a reader skimming quickly could assume it's still per-result.
3. summary.A_wins_total / B_wins_total naming still uses generic "A"/"B" while the example now uses real model filenames — this is pre-existing and not something this PR needs to fix, just flagging since it reads slightly oddly next to the more descriptive new fields.

Other checklist items:

• No code changes, so pyright/black formatting requirements from CLAUDE.md don't apply here.
• Docs-only, single file changed — no test coverage concerns.
• No security implications.

Overall this is a solid, low-risk documentation fix. Approving with only minor optional suggestions above.

[EliasTeikari]

@RapidPoseidon change from "orderType" to just "type"

[RapidPoseidon]

Done in 27ce69c — renamed to type in both the example JSON and the field breakdown.

[claude]

Review: docs: update results example to aggregator v4 format

Overview

Updates the "Interpreting the Results" doc from the v3.0.0 result shape to v4.0.0: adds assetUrls, moves context info into info, drops the per-result context field, reorders summary after results, and trims the example to 3 responses. Overall this is a welcome, much-needed docs refresh and the example data is internally consistent (vote counts, ratios, and summed scores all check out).

Bug: field name mismatch (type vs orderType)

• The JSON example (line 12) and its accompanying prose use "type": "Compare", but the actual field returned by the API and consumed by the SDK is orderType — see src/rapidata/rapidata_client/results/rapidata_results.py:45 and :56:

  if self["info"].get("orderType") is None:
      ...
  if self["info"].get("orderType") in ("Compare", "Ranking"):

  The PR description itself even says "info now carries orderType, name, and instruction", which contradicts the type key actually written into the doc. This should be corrected to orderType in both the JSON example and the field description list, otherwise users copying this example will get None/wrong behavior from to_pandas().

Other observations

• The rest of the restructuring (moving summary to the end, adding assetUrls, dropping context) looks accurate and matches the described v4.0.0 shape.
• Nice touch keeping the demographic/user-score numbers internally consistent (e.g., summedUserScores sums to the value shown, aggregatedResults matches the 3 detailed responses).
• Docs-only change, low risk; no code/test coverage concerns beyond the field-name fix above.

Suggested fix

Change "type": "Compare" → "orderType": "Compare" in the JSON example, and update the corresponding bullet under the info field list from `type`: The type of task... to `orderType`: The type of task....

[LinoGiger]

this is not accurately reflecting the result file of the example order? there the question is "Which image matches the description better?" and the context: "A small blue book sitting on a large red book."

[RapidPoseidon]

Done in 00938d5 — the example now mirrors the quickstart order: instruction is "Which image matches the description better?" and the datapoint carries context: "A small blue book sitting on a large red book." (also re-added context to the field breakdown).

[LinoGiger]

please note that they are not encrypted, but assigned a random UUID so they can't be accessed randomly

[RapidPoseidon]

Done in 00938d5 — noted that hosted files aren't encrypted but get a random UUID name so they can't be accessed by guessing URLs.

[claude]

Review: docs: update results example to aggregator v4 format

Docs-only change updating docs/understanding_the_results.md from the v3.0.0 to v4.0.0 results shape (adds assetUrls, new info fields, reorders the breakdown to match the JSON's actual key order, refreshes the example data). Overall a solid, focused update — but there's one field-name discrepancy worth fixing before merge.

Correctness issue: info.type should be info.orderType

The new example and breakdown text introduce a field called type:

"info": {
  ...
  "type": "Compare",

• type: The type of task that was run (e.g. Compare, Classify).

However, the SDK itself reads this value as orderType, not type — see src/rapidata/rapidata_client/results/rapidata_results.py:45 and :56:

if self["info"].get("orderType") is None:
    managed_print("Warning: Results are old and Order type is not specified. ...")
if self["info"].get("orderType") in ("Compare", "Ranking"):
    return self._compare_to_pandas(split_details=split_details)

This is also consistent with the PR description itself, which says "info now carries orderType, name, and instruction" — so the description is correct but the actual doc content drifted to type. Since this doc is the primary reference for what fields users can expect in info, this should be corrected to orderType so it matches both the SDK and the PR's own stated intent.

Minor: PR description vs. diff — context field

The PR description says "the per-result context field is gone," but the diff keeps context in both the JSON example and the breakdown (now described as "present when contexts were provided for the job"). Not necessarily wrong — just flagging the mismatch so it can be confirmed this is the intended current behavior and not a leftover from an earlier draft.

Nice touches

• Reordering the "Breakdown of the Results" list (info → results → summary) to match the actual key order in the JSON example is a good consistency fix.
• The refreshed example data is internally consistent: summedUserScores for flux-1-pro_37_0.jpg (2.552) correctly sums the three detailedResults global scores (0.845 + 0.8349 + 0.8721), and aggregatedResults/ratios agree with the 3 unanimous votes.
• New assetUrls documentation (with the note about random UUID-named hosted files) is a useful, security-conscious addition.

Out of scope but worth knowing

docs/confidence_stopping.md still shows a "version": "3.0.0" example — not touched by this PR, but may be worth a follow-up pass now that the results format has moved to v4.0.0.

Testing

Docs-only change with no code/tests affected; PR description confirms mkdocs build was run successfully, which is the right verification for this kind of change.