mmm rules

Invocation#

echo-cli mmm rules list
echo-cli mmm rules add --campaign <campaign-id> --metric <metric> --window-days <n> --comparison <above|below> --threshold <n> --action <pause|scale> [--factor <n> --budget-cap <n>] --by <who>
echo-cli mmm rules remove --id <rule-id>
echo-cli mmm rules evaluate

Inputs and output#

list writes rules (id, campaign_id, metric, window_days, comparison, threshold, action, factor, budget_cap, declared_by, declared_at) and actions, newest first (id, rule_id, campaign_id, evaluated_at, value, action, budget_before, budget_after, applied, refusal). add writes the stored rule; remove the rule it removed. evaluate writes evaluations: per rule, rule_id, campaign_id, outcome (applied, refused, not_met, resting or unmeasured), reason, value and the recorded action.

State effect#

The verbs call Echo Web's authenticated /api/analytics/mmm/rules (GET, PUT, DELETE and POST) with ECHO_INTERNAL_BEARER at ECHO_WEB_BASE_URL; the Ad budget rules section of the tracking screen and of Echo Desktop's GEO screen do the same, echo-mcp runs them as echo_budget_rules, echo_budget_rule_add, echo_budget_rule_remove and echo_budget_rules_evaluate, and /api/cron/budget-rules evaluates every rule 23 minutes after each six-hourly paid-ads sync. An evaluation sums the campaign's spend, conversions and conversion value over its last --window-days whole days (UTC) from ad_campaign_metrics; spend is the sum, cost_per_conversion the spend over the conversions and return_on_spend the conversion value over the spend. When the comparison holds, pause sets the campaign PAUSED and scale multiplies its daily budget by --factor, on Meta or Apple Ads through Stado's paid-ads integration, and records it on ad_campaigns. Each evaluation that held is stored in ad_budget_actions, applied or refused; a rule with an action within its window rests, so a window is acted on once. A window day the sync did not report leaves the rule unmeasured with that reason.

Refusals#

• A wrong invocation is refused before anything is sent: "mmm rules takes …; got <word>", "mmm rules <verb> does not take <flag>; …", "<flag> needs a value" and "mmm rules <verb> needs <flag>".
• Echo Web answers a bad request with "campaign_id is required: the synced ad campaign the rule acts on, as echo-cli mmm library lists it", "metric must be one of spend, cost_per_conversion, return_on_spend; got <metric>", "window_days must be a positive whole number: the last whole days the metric is summed over; got <value>", "comparison must be one of above, below; got <word>", "threshold must be a number: the value the metric is compared with; got <value>", "action must be one of pause, scale; got <word>", "a pause rule takes no factor or budget_cap; only a scaling rule changes the budget", "factor must be a positive number: what the daily budget is multiplied by; got <value>", "budget_cap must be a positive number: the highest daily budget the rule may set; got <value>", "declared_by is required: who declares the rule" or "id is required: the rule to remove, as echo-cli mmm rules list shows it"; and not found with "no synced ad campaign has id <id>; echo-cli mmm library lists them" or "no budget rule has id <id>". The command prints Echo Web's sentence and exits 1.
• An evaluation records a refused action, rather than failing, with "campaign <id> has no daily budget to scale", "the scaled daily budget <after> exceeds the rule's cap <cap>", "campaigns on <platform> cannot be changed through Stado's paid-ads integration", "ad account <id> is not active", "ad account <id> declares no currency, which the platform mutation needs" or "the platform refused the change: <cause>".
• With an approval policy on change_ad_campaign (echo-cli approvals policy set --action change_ad_campaign), a rule that holds does not change the campaign: evaluate answers it held and records the action unapplied with "the change waits as approval request <id> (<policy reason>) until echo-cli approvals approve <id> makes it", the rule rests for its window as after any action, and the change is made once a reviewer approves it.