Consequence-based decision
Weigh consequences, model their overlap and compute expected value for one or more stakeholders. The endpoint runs hundreds of calls to the underlying “raw” Eevo decision model to compare consequences and model their overlap. It then computes expected value separately for each stakeholder you send.
Quick example
Below is a quick example of a consequence-based decision via curl:
curl https://eevo.io/api/v1/cb-decision \
-H "Authorization: Bearer $EEVO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "eevo-1",
"mode": "default",
"context": "Acme Corp found a data-export bug that shows some customers a wrong invoice total. A fix is ready; a log dump that would confirm it arrives in 40 minutes.",
"options": [
{
"id": "A",
"description": "Ship the fix now.",
"consequences": [
{
"id": "a1",
"label": "Wrong totals stop now",
"description": "About 200 customers stop seeing a wrong invoice total 40 minutes sooner.",
"valence": "benefit"
},
{
"id": "a2",
"label": "Invoices to recheck",
"description": "Without the log dump to confirm the fix, about 20 customers get an email asking them to recheck one invoice.",
"valence": "harm"
}
]
},
{
"id": "B",
"description": "Wait for the log dump, then ship.",
"consequences": [
{
"id": "b1",
"label": "40 more minutes of wrong totals",
"description": "About 200 customers keep seeing a wrong invoice total for 40 more minutes.",
"valence": "harm"
}
]
}
],
"stakeholders": [
{
"id": "customers",
"description": "The affected customers",
"values": "Correct invoices, no surprises."
}
]
}'The response:
{
"id": "dec_7b1c0e4f9a2d4c6b8e3f5a1d2c4b6e8f",
"model": "eevo-1.2",
"mode": "default",
"overlap": "correct",
"seed": 20261006,
"results": [
{
"stakeholder": {
"id": "customers",
"description": "The affected customers"
},
"best": "A",
"confidence": 0.99,
"probabilities": {
"A": 0.99,
"B": 0.01
},
"p_best": {
"A": 0.99,
"B": 0.01
},
"p_best_uncorrected": {
"A": 1,
"B": 0
},
"best_uncorrected": "A",
"ev": {
"A": {
"mean": 0.52,
"p10": 0.38,
"p90": 0.63
},
"B": {
"mean": -0.45,
"p10": -0.58,
"p90": -0.33
}
},
"ev_uncorrected": {
"A": {
"mean": 0.87,
"p10": 0.79,
"p90": 0.95
},
"B": {
"mean": -0.81,
"p10": -0.9,
"p90": -0.66
}
},
"harms_benefits": {
"A": {
"harms": {
"mean": 0.18,
"p10": 0.09,
"p90": 0.31
},
"benefits": {
"mean": 0.7,
"p10": 0.6,
"p90": 0.81
}
},
"B": {
"harms": {
"mean": 0.45,
"p10": 0.33,
"p90": 0.58
},
"benefits": {
"mean": 0,
"p10": 0,
"p90": 0
}
}
},
"consequences": [
{
"id": "a1",
"option": "A",
"description": "About 200 customers stop seeing a wrong invoice total 40 minutes sooner.",
"label": "Wrong totals stop now",
"valence": "benefit",
"size": {
"value": 1,
"p10": 0.82,
"p90": 1
},
"counted_share": 0.6,
"overlaps_with": [
{
"with": "b1",
"share": 0.88
}
],
"discounted_by": {
"with": "b1",
"type": "mirror",
"overlap": 0.88,
"share": 0.4,
"absence_p": 0.5
}
},
{
"id": "a2",
"option": "A",
"description": "Without the log dump to confirm the fix, about 20 customers get an email asking them to recheck one invoice.",
"label": "Invoices to recheck",
"valence": "harm",
"size": {
"value": 0.18,
"p10": 0.09,
"p90": 0.31
},
"counted_share": 1,
"overlaps_with": [],
"discounted_by": null
},
{
"id": "b1",
"option": "B",
"description": "About 200 customers keep seeing a wrong invoice total for 40 more minutes.",
"label": "40 more minutes of wrong totals",
"valence": "harm",
"size": {
"value": 0.9,
"p10": 0.74,
"p90": 1
},
"counted_share": 0.56,
"overlaps_with": [
{
"with": "a1",
"share": 0.88
}
],
"discounted_by": {
"with": "a1",
"type": "mirror",
"overlap": 0.88,
"share": 0.44,
"absence_p": 0.5
}
}
],
"overlaps": [
{
"a": "a1",
"b": "b1",
"share": 0.88,
"p": 0.97,
"type": "mirror",
"type_p": 0.95,
"kind": "mirror",
"absence_side": "a1",
"absence_p": 0.5,
"absence": {
"a1": 0.5,
"b1": 0.5
}
}
],
"removed_share": 0.41,
"mc": {
"draws": 1000,
"solved": 1000
},
"records": {
"ratio": 3,
"overlap": 2
}
}
],
"agreement": {
"all_same": true,
"best_by_stakeholder": {
"customers": "A"
}
},
"warnings": [],
"usage": {
"billed_decisions": 1,
"ratio_records": 3,
"overlap_records": 2
},
"cost_usd": 0.15,
"links": {
"view_url": "https://eevo.io/decisions/dec_7b1c0e4f9a2d4c6b8e3f5a1d2c4b6e8f/explicit",
"png_url": "https://eevo.io/api/arvo/decisions/dec_7b1c0e4f9a2d4c6b8e3f5a1d2c4b6e8f/explicit.png"
},
"meta": {
"tau": 0.2,
"draws": 1000,
"ratio_spread_scale": 0.72,
"overlap_model": "eevo-1.2@3dacdbf4",
"correction": {
"mirror": false,
"kept": true
}
},
"notes": "EVs are on each stakeholder's own scale (largest consequence = 1); compare options within a stakeholder, not across stakeholders. Informative, not a recommendation."
}A decision that is still running after about 50 seconds answers 202 instead, with a poll_url to fetch it from (Get a decision).
Request body
application/json- modelstringOptional
The identifier of the Eevo model:
eevo-1(the default when left out), which always points at the latest Eevo-1 version. - modestringOptionalValue
default, which this endpoint always runs; it may be left out. Each option lists its consequences; Eevo sizes them and gives each option’s expected value per stakeholder.defaultDefaultdefault - contextstringRequired
- stakeholdersarray of objectsRequired
- idstringOptional
- descriptionstringRequired
- valuesstringOptional
- optionsarray of objectsRequired
- idstringRequired
An option id: a letter from
AtoH, given to the options in order. - descriptionstringRequired
- consequencesarray of objectsRequired
- idstringOptional
- descriptionstringRequired
- labelstringOptional
- stakeholdersarray of stringsOptional
- valencestring or map of stringsRequired
- benefitGood for the stakeholders it affects.
- harmBad for the stakeholders it affects.
- idstringRequired
- seedintegerOptional
- asyncbooleanOptional
- metadataobjectOptional
5 fields
- conversationobjectOptional
3 fields
- platformstringRequiredOne of
slackteamsgoogle_chatother - channelstringOptional
- thread_urlstringOptional
- platformstringRequired
- issueobjectOptional
4 fields
- trackerstringRequiredOne of
linearjiragithubother - urlstringRequired
- keystringOptional
- titlestringOptional
- trackerstringRequired
- pull_requestobjectOptional
5 fields
- platformstringRequiredOne of
githubgitlabbitbucketazure_devopsother - urlstringRequired
- repostringOptional
- numberintegerOptional
- titlestringOptional
- platformstringRequired
- on_behalf_ofobjectOptional
2 fields
- namestringOptional
- emailstring <email>Optional
- linksarray of objectsOptional
2 fields
- urlstringRequired
- labelstringOptional
- conversationobjectOptional
- revisesstringOptional
- revision_noteobjectOptional
2 fields
- reasonstringOptional
- missedarray of objectsRequired
- kindstringRequired
- contextSomething about the situation.
- consequenceA consequence of an option.
- stakeholderA stakeholder.
- optionAn option.
- size_or_probabilityHow large or how likely a consequence is.
- otherAnything else.
- descriptionstringRequired
- kindstringRequired
- share_with_orgbooleanOptional
Response body
application/json- idstring
Request id, as in the Eevo console decision log.
- modelstring
- modestringValue
default - overlapstring
- correctThe shared part of overlapping consequences is counted once. Every new decision does this.
- reportOverlaps were returned but not applied (older decisions).
- offOverlap was not assessed (older decisions).
- seednumber
- resultsarray of objects
One result per stakeholder, in request order.
- stakeholderobject
- idstring
- descriptionstring
- beststring
The option with the highest expected value for this stakeholder. Takes an option id: a letter from
AtoH, given to the options in order. - confidencenumber
- probabilitiesmap of numbers
P(highest EV) per option.
- evmap of objects
Expected value per option on this stakeholder's own scale, with p10-p90.
- {key}object
- meannumber
- p10number
- p90number
- {key}object
- harms_benefitsmap of objects
Per option, its harms and its benefits each added up (the counted parts, so ev = benefits - harms), each with its own p10-p90.
- {key}object
- harmsobject
- meannumber
- p10number
- p90number
- benefitsobject
- meannumber
- p10number
- p90number
- harmsobject
- {key}object
- consequencesarray of objects
- idstring
- overlapsarray of objects
- astring
- bstring
- sharenumber
- stakeholderobject
- agreementobject
- all_sameboolean
- best_by_stakeholdermap of strings
- {key}string
An option id: a letter from
AtoH, given to the options in order.
- {key}string
- warningsarray of strings
- usageobject
- billed_decisionsnumber
The standard decisions this decision counts as; its price is a multiple of the decision price.
- ratio_recordsnumber
- overlap_recordsnumber
- billed_decisionsnumber
- cost_usdnumber
- linksobject
- view_urlstring
- png_urlstring
- metaobject
- notesstring
- lineageobject
Where the decision sits in its revision chain: the first decision, its number (1 = first) and the one it revises.
- root_idstring
- numbernumber
- previous_idstring
Response body: 202
application/jsonThe decision is still running after about 50 seconds (a model waking from idle takes a few minutes), or async was true. It goes on running and is billed when it completes; poll poll_url (GET /v1/decisions/{id}) every retry_after seconds until status is ok (the answer is in response) or error.
- idstring
- modelstring
- modestring
- statusstring
- progressobject
- doneinteger
- totalinteger
- poll_urlstring
The
GET /v1/decisions/{id}URL to poll. - retry_afterinteger
Seconds to wait between polls.
- lineageobject
Error responses
An error answers with its status and a body with its type and a message. See Errors for the format and every type.
| Status | Title | Description |
|---|---|---|
| 400 | Bad Request | The request is invalid; the message says which field and why. |
| 401 | Unauthorized | No valid API key. |
| 402 | Payment Required | No credit left for the request, or an EU request from an organization that has neither bought credit nor has credit. |
| 403 | Forbidden | Only the person who made the decision, or the API key it was made with, can change who sees it or publish it. |
| 409 | Conflict | The model is not served yet, or the revised decision already has a newer revision. |
| 410 | Gone | No such decision that you can see: none in your organization, or one not shared with you. |
| 429 | Too Many Requests | Rate limit or concurrent request limit reached; retry after Retry-After seconds. |
| 502 | Bad Gateway | The model failed to answer, or the decision could not be completed. Nothing is billed. |
| 503 | Service Unavailable | The model is starting after being idle (`model_warming`), or a request for the EU found no EU server available (`region_unavailable`); retry after Retry-After seconds. Nothing is billed. |