social ab

Invocation#

echo-cli social ab list
echo-cli social ab start --name <name> --hypothesis <text> --a <post-id> --b <post-id> --sigmas <n> --by <who>
echo-cli social ab schedule --id <test-id> --at <time>
echo-cli social ab report --id <test-id>
echo-cli social ab conclude --id <test-id> --conclusion <text> --by <who>
echo-cli social ab remove --id <test-id>
echo-cli social ab send --id <test-id> --arena <arena-id> --category <category-id> --by <who>
echo-cli social ab ranking --id <test-id>

Inputs and output#

list writes every test, newest first: id, name, hypothesis, variant_a, variant_b, sigmas, started_by, started_at, concluded_by, concluded_at and conclusion. start, conclude and remove write the test. schedule writes test_id, same_account, and a and b (post_id, social_account_id, scheduled_at). report writes test, a and b (post_id, platform, status, caption, published_at, views, interactions, rate and unmeasured), difference (b's rate minus a's), low, high, leader (a, b, or null while the interval reaches zero) and unmeasured (why the posts cannot be compared yet, or null). send writes the submission: test_id, arena_id, category_id, submission_id (Preferences' own), items (each post's id to the Preferences item it became), submitted_by and submitted_at. ranking writes { submission, ranking }: the ranking as Preferences answers it now — ready, qualified_comparisons, unranked, winner (its item_id and candidate_id, the post's id, or null) and rows, each item's item_id, candidate_id, score, score_low, score_high, comparisons and wins.

State effect#

The verbs call Echo Web's authenticated /api/analytics/post-tests, and send and ranking /api/analytics/post-tests/rank, with ECHO_INTERNAL_BEARER at ECHO_WEB_BASE_URL; the Post A/B tests and Post tests ranked by people sections of the ecosystem analytics tab and of Echo Desktop's GEO screen do the same, and echo-mcp runs them as echo_post_tests, echo_post_test_start, echo_post_test_schedule, echo_post_test_report, echo_post_test_conclude, echo_post_test_remove and echo_post_test_ranking (sending stays with the CLI and the screens). Tests are stored in post_ab_tests; the posts are the content queue's. schedule sets both variants scheduled in content_posts so neither is favoured by when it went out: at --at both when they are on two accounts; on one account, a at --at and b a week later, the same weekday and hour. Neither is changed unless both are drafts or scheduled and both pass the checks every post going out passes — tagging consent and media rights. A report reads each post's stored post_metrics: interactions are its likes, comments, shares and saves, and the rate is interactions per view. The interval is the difference plus or minus --sigmas standard errors of a difference of two proportions; a post not yet measured, with no views, or measured without one of the counts, leaves the test unmeasured with why. send submits both posts' captions once, as text items, to the Preferences arena and text category named, through Preferences' operator API at PREFERENCES_URL with PREFERENCES_OPERATOR_TOKEN — the generator echo-post-tests, the run the test's id, each post's id its candidate — and keeps the submission in post_test_preference_submissions; ranking reads the ranking from Preferences each time, never stored, so the people's preference sits beside the stored engagement the report compares.

Refusals#

• A wrong invocation is refused before anything is sent: "social ab takes …; got <word>", "social ab <verb> does not take <flag>; …", "<flag> needs a value" and "social ab <verb> needs <flag>".
• Echo Web answers a bad request with "name is required: what the test is called", "hypothesis is required: what the variants differ in and what is expected", "variant_a is required: the queued post that is variant a" (and variant_b), "variant_a and variant_b must be two different posts", "sigmas must be a positive number: how many standard errors the interval of the difference spans; got <value>", "started_by is required: an internal caller has no signed-in user, so it names who is acting" (and concluded_by), "id is required: the post test, as echo-cli social ab list shows it", "conclusion is required: what the test showed, in words", "post test <id> was already concluded by <who> at <time>", "at must be an ISO time: when variant a goes out; got <value>" or "variant <post-id> is <status>; only a draft or scheduled post can be scheduled"; not found with "no queued post has id <id>" or "no post test has id <id>"; and a conflict with "a post test named <name> already exists (<id>)", or with "not scheduled: <handle> …" or "not scheduled: <asset>: <kind> <reference> expired at <time>" when a variant's tag has no consent in force or its media no right in force. The command prints Echo Web's sentence and exits 1.
• send and ranking are refused with "arena_id is required: the Preferences arena the captions go to", "category_id is required: the text category of that arena", "submitted_by is required: …", "post <id> has no caption, so there is nothing to vote on", a conflict with "post test <id> was sent to Preferences as submission <submission> by <who> at <time>", not found with "post test <id> was not sent to Preferences; echo-cli social ab send sends it", and Preferences' own refusal as "Preferences refused <method> <path> (<status>): <its answer>".