content rank

Invocation#

echo-cli content rank send --job <thumbnail-job-id> --arena <arena-id> --category <category-id> --by <who>
echo-cli content rank read --job <thumbnail-job-id>

Inputs and output#

send writes the submission: job_id, arena_id, category_id, submission_id (Preferences'), items (each variant id with the Preferences item it became), submitted_by and submitted_at. read writes { submission, ranking }: ranking as Preferences answers it now — ready, qualified_comparisons, unranked, winner (null until declared) and rows, each item_id, candidate_id (the variant's id), score, score_low, score_high, comparisons and wins.

State effect#

The verbs call Echo Web's authenticated /api/analytics/thumbnails/rank with ECHO_INTERNAL_BEARER at ECHO_WEB_BASE_URL; the Thumbnails ranked by people section of the ecosystem's analytics and of Echo Desktop's GEO screen do the same, and echo-mcp runs them as echo_thumbnails_rank_send and echo_thumbnails_rank. send reads each variant of the job (echo-cli content thumbnails make) back from Stado and posts them as one submission to Preferences at Echo Web's PREFERENCES_URL with its PREFERENCES_OPERATOR_TOKEN — generator echo-thumbnails, run the job's id, the manifest digest the sha256 of the variants' ids and objects, each variant's id its candidate — into the --arena's --category, which must hold images. A job is sent once (preference_submissions); read asks Preferences each time and stores nothing. People vote at Preferences; its ranking names a winner only once the vote separates the leader.

Refusals#

• A wrong invocation is refused before anything is sent: "content rank takes send …; read …; got <word>", "content rank <verb> does not take <flag>; it takes …", "<flag> needs a value" and "content rank <verb> needs <flag>".
• Echo Web answers a bad request with "job_id is required: …", "arena_id is required: …", "category_id is required: …" or "submitted_by is required: an internal caller has no signed-in user, so it names who is acting"; not found with "no thumbnail job has id <id>" or "thumbnail job <id> was not sent to Preferences; echo-cli content rank send sends it"; and a conflict with "thumbnail job <id> was sent to Preferences as submission <id> by <who> at <time>". Preferences' own refusal is answered as "Preferences refused <method> <path> (<status>): <its answer>", and a deployment without PREFERENCES_URL or PREFERENCES_OPERATOR_TOKEN answers naming the setting. The command prints Echo Web's sentence and exits 1.