Compare specific models head-to-head with real test queries
compareRun a live A/B test on 2-5 specified models for a given purpose, using real queries to reveal cost, latency, and plain-English performance insights.
Instructions
Run a live A/B test between 2–5 user-specified models for a stated purpose. NO ranking step — the supplied model_ids ARE the candidate set. Generates 5 representative test queries from the purpose, runs them through every named model in parallel, and returns real cost, latency, and plain-English commentary on who won what. Unknown IDs are dropped with a note; if fewer than 2 IDs resolve, the call refuses. Use this whenever the user names specific models to compare (e.g. 'A/B test X and Y'). For engine-chosen candidates, use benchmark instead. Costs more than rank (10+ live LLM calls). Free-tier note: when any candidate ends in ':free', the probe is capped at 3 queries (no adaptive expansion) because free-tier rate limits often push longer probes past the deploy's 5-minute ceiling — evidence will be shallower. The commentary surfaces this when it happens.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| primary | No | Optional. Only affects the plain-English commentary at the end — does not change which models are tested. Marks the dimension the user cares most about so the commentary calls out that winner first. | |
| purpose | Yes | One sentence describing what the models will be used for. Used ONLY to generate representative test queries for the head-to-head — not to rank the catalog. Be concrete, not vague. | |
| model_ids | Yes | Exact model IDs to test head-to-head, in caller-chosen order. 2–5 IDs. Examples: 'nvidia/nemotron-3-super-120b-a12b:free', 'openai/gpt-oss-120b:free'. Unknown IDs are dropped with a note; if fewer than 2 resolve, the call is refused. Use this whenever the user has already named candidates — do NOT call `benchmark` in that case. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | ||
| purpose | No | ||
| ab_result | No | ||
| refusal_reason | No | ||
| xpansion_update | No | Optional rotating launch nudge from Xpansion. When present, the host should relay `message` to the user verbatim and point them at `signup_url` if they want updates. | |
| model_ids_tested | No | ||
| invalid_model_ids | No | ||
| model_ids_requested | No |