Get the cheaper context recipe the outcomes support

curl --request GET \
  --url https://api.brussle.com/v1/namespaces/{ns}/judgments/{name}/recipe-suggestion \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.brussle.com/v1/namespaces/{ns}/judgments/{name}/recipe-suggestion"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.brussle.com/v1/namespaces/{ns}/judgments/{name}/recipe-suggestion', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.brussle.com/v1/namespaces/{ns}/judgments/{name}/recipe-suggestion",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.brussle.com/v1/namespaces/{ns}/judgments/{name}/recipe-suggestion"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.brussle.com/v1/namespaces/{ns}/judgments/{name}/recipe-suggestion")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "version": 2,
  "status": "not_run",
  "reason": "awaiting_run",
  "message": "<string>",
  "headline": "<string>",
  "suggestion": {
    "recipe": {
      "fields": [
        "<string>"
      ],
      "last_n": {},
      "window": {},
      "max_tokens": 2,
      "related": {},
      "previous": {
        "fields": [
          "<string>"
        ],
        "anchor": "<string>"
      }
    },
    "removed": [
      "<string>"
    ],
    "definition": {
      "name": "<string>",
      "question": "<string>",
      "type": "bool",
      "criteria": "<string>",
      "context": {
        "fields": [
          "<string>"
        ],
        "last_n": {},
        "window": {},
        "max_tokens": 2,
        "related": {},
        "previous": {
          "fields": [
            "<string>"
          ],
          "anchor": "<string>"
        }
      },
      "engine": {
        "name": "jev",
        "version": "<string>"
      },
      "horizon": "0s",
      "applies_to": {},
      "thresholds": {},
      "parts": [
        {
          "name": "<string>",
          "question": "<string>"
        }
      ],
      "features": [
        "<string>"
      ],
      "freshness": {
        "policy": "on_read",
        "debounce_ms": 0,
        "interval": "<string>",
        "max_wait_ms": 2,
        "fanout": {
          "scope": {
            "created_within": "<string>",
            "where": {}
          },
          "debounce_ms": 600000,
          "max_wait_ms": 2,
          "rolling_limit": 300000,
          "block_cap": 1000
        }
      },
      "activate": true,
      "confirm": false,
      "use_context": "suggested",
      "dry_run": false
    },
    "unit_reduction": 0.6,
    "cost_per_answer_before": 1,
    "cost_per_answer_after": 1,
    "held_out": {
      "log_loss_before": 1,
      "log_loss_after": 1,
      "accuracy_before": 0.5,
      "accuracy_after": 0.5,
      "interval": {
        "lower": 123,
        "upper": 123
      }
    },
    "labels": 101,
    "engine_version": "<string>",
    "computed_at": "2023-11-07T05:31:56Z"
  },
  "computed_at": "2023-11-07T05:31:56Z",
  "next_run_after": "2023-11-07T05:31:56Z",
  "plan_required": {
    "message": "<string>",
    "capability": "recipe_tuning",
    "required_plan": "team",
    "plan": "developer"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": {
      "reason": "<string>",
      "suggested_context": {
        "recipe": {
          "fields": [
            "<string>"
          ],
          "last_n": {},
          "window": {},
          "max_tokens": 2,
          "related": {},
          "previous": {
            "fields": [
              "<string>"
            ],
            "anchor": "<string>"
          }
        },
        "cost_per_answer": 1,
        "whole_state_cost_per_answer": 1,
        "sampled_documents": 2,
        "excluded": [
          {
            "path": "<string>",
            "reason": "id"
          }
        ]
      }
    }
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": {
      "reason": "<string>",
      "suggested_context": {
        "recipe": {
          "fields": [
            "<string>"
          ],
          "last_n": {},
          "window": {},
          "max_tokens": 2,
          "related": {},
          "previous": {
            "fields": [
              "<string>"
            ],
            "anchor": "<string>"
          }
        },
        "cost_per_answer": 1,
        "whole_state_cost_per_answer": 1,
        "sampled_documents": 2,
        "excluded": [
          {
            "path": "<string>",
            "reason": "id"
          }
        ]
      }
    }
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": {
      "reason": "<string>",
      "suggested_context": {
        "recipe": {
          "fields": [
            "<string>"
          ],
          "last_n": {},
          "window": {},
          "max_tokens": 2,
          "related": {},
          "previous": {
            "fields": [
              "<string>"
            ],
            "anchor": "<string>"
          }
        },
        "cost_per_answer": 1,
        "whole_state_cost_per_answer": 1,
        "sampled_documents": 2,
        "excluded": [
          {
            "path": "<string>",
            "reason": "id"
          }
        ]
      }
    }
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": {
      "reason": "<string>",
      "suggested_context": {
        "recipe": {
          "fields": [
            "<string>"
          ],
          "last_n": {},
          "window": {},
          "max_tokens": 2,
          "related": {},
          "previous": {
            "fields": [
              "<string>"
            ],
            "anchor": "<string>"
          }
        },
        "cost_per_answer": 1,
        "whole_state_cost_per_answer": 1,
        "sampled_documents": 2,
        "excluded": [
          {
            "path": "<string>",
            "reason": "id"
          }
        ]
      }
    }
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": {
      "reason": "<string>",
      "suggested_context": {
        "recipe": {
          "fields": [
            "<string>"
          ],
          "last_n": {},
          "window": {},
          "max_tokens": 2,
          "related": {},
          "previous": {
            "fields": [
              "<string>"
            ],
            "anchor": "<string>"
          }
        },
        "cost_per_answer": 1,
        "whole_state_cost_per_answer": 1,
        "sampled_documents": 2,
        "excluded": [
          {
            "path": "<string>",
            "reason": "id"
          }
        ]
      }
    }
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": {
      "reason": "<string>",
      "suggested_context": {
        "recipe": {
          "fields": [
            "<string>"
          ],
          "last_n": {},
          "window": {},
          "max_tokens": 2,
          "related": {},
          "previous": {
            "fields": [
              "<string>"
            ],
            "anchor": "<string>"
          }
        },
        "cost_per_answer": 1,
        "whole_state_cost_per_answer": 1,
        "sampled_documents": 2,
        "excluded": [
          {
            "path": "<string>",
            "reason": "id"
          }
        ]
      }
    }
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": {
      "reason": "<string>",
      "suggested_context": {
        "recipe": {
          "fields": [
            "<string>"
          ],
          "last_n": {},
          "window": {},
          "max_tokens": 2,
          "related": {},
          "previous": {
            "fields": [
              "<string>"
            ],
            "anchor": "<string>"
          }
        },
        "cost_per_answer": 1,
        "whole_state_cost_per_answer": 1,
        "sampled_documents": 2,
        "excluded": [
          {
            "path": "<string>",
            "reason": "id"
          }
        ]
      }
    }
  }
}

Outcomes and calibration

Get the cheaper context recipe the outcomes support

The last recipe-tuning run of the active version. Once a version’s calibration is fitted, and then at most every 30 days, a run tests cheaper variants of the recipe against your labelled outcomes, using the contexts already stored with your evaluations, sent to the same engine on the same terms. A smaller recipe is cheaper only where it moves answers to a smaller size class: trimming tokens within a class saves nothing. A variant qualifies only when it is meaningfully cheaper and neither its held-out log loss nor its accuracy is worse beyond noise. suggestion is the cheapest that qualifies, with the exact definition to post as a new version; nothing is applied for you. On a template prefix, the template’s judgment, tuned on its tenants’ pooled outcomes.

On every plan. Below Team the numbers are shown, and recipe, removed and definition are null with plan_required beside them.

GET

namespaces

{ns}

judgments

{name}

recipe-suggestion

Get the cheaper context recipe the outcomes support

curl --request GET \
  --url https://api.brussle.com/v1/namespaces/{ns}/judgments/{name}/recipe-suggestion \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.brussle.com/v1/namespaces/{ns}/judgments/{name}/recipe-suggestion"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.brussle.com/v1/namespaces/{ns}/judgments/{name}/recipe-suggestion', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.brussle.com/v1/namespaces/{ns}/judgments/{name}/recipe-suggestion",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.brussle.com/v1/namespaces/{ns}/judgments/{name}/recipe-suggestion"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.brussle.com/v1/namespaces/{ns}/judgments/{name}/recipe-suggestion")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "version": 2,
  "status": "not_run",
  "reason": "awaiting_run",
  "message": "<string>",
  "headline": "<string>",
  "suggestion": {
    "recipe": {
      "fields": [
        "<string>"
      ],
      "last_n": {},
      "window": {},
      "max_tokens": 2,
      "related": {},
      "previous": {
        "fields": [
          "<string>"
        ],
        "anchor": "<string>"
      }
    },
    "removed": [
      "<string>"
    ],
    "definition": {
      "name": "<string>",
      "question": "<string>",
      "type": "bool",
      "criteria": "<string>",
      "context": {
        "fields": [
          "<string>"
        ],
        "last_n": {},
        "window": {},
        "max_tokens": 2,
        "related": {},
        "previous": {
          "fields": [
            "<string>"
          ],
          "anchor": "<string>"
        }
      },
      "engine": {
        "name": "jev",
        "version": "<string>"
      },
      "horizon": "0s",
      "applies_to": {},
      "thresholds": {},
      "parts": [
        {
          "name": "<string>",
          "question": "<string>"
        }
      ],
      "features": [
        "<string>"
      ],
      "freshness": {
        "policy": "on_read",
        "debounce_ms": 0,
        "interval": "<string>",
        "max_wait_ms": 2,
        "fanout": {
          "scope": {
            "created_within": "<string>",
            "where": {}
          },
          "debounce_ms": 600000,
          "max_wait_ms": 2,
          "rolling_limit": 300000,
          "block_cap": 1000
        }
      },
      "activate": true,
      "confirm": false,
      "use_context": "suggested",
      "dry_run": false
    },
    "unit_reduction": 0.6,
    "cost_per_answer_before": 1,
    "cost_per_answer_after": 1,
    "held_out": {
      "log_loss_before": 1,
      "log_loss_after": 1,
      "accuracy_before": 0.5,
      "accuracy_after": 0.5,
      "interval": {
        "lower": 123,
        "upper": 123
      }
    },
    "labels": 101,
    "engine_version": "<string>",
    "computed_at": "2023-11-07T05:31:56Z"
  },
  "computed_at": "2023-11-07T05:31:56Z",
  "next_run_after": "2023-11-07T05:31:56Z",
  "plan_required": {
    "message": "<string>",
    "capability": "recipe_tuning",
    "required_plan": "team",
    "plan": "developer"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": {
      "reason": "<string>",
      "suggested_context": {
        "recipe": {
          "fields": [
            "<string>"
          ],
          "last_n": {},
          "window": {},
          "max_tokens": 2,
          "related": {},
          "previous": {
            "fields": [
              "<string>"
            ],
            "anchor": "<string>"
          }
        },
        "cost_per_answer": 1,
        "whole_state_cost_per_answer": 1,
        "sampled_documents": 2,
        "excluded": [
          {
            "path": "<string>",
            "reason": "id"
          }
        ]
      }
    }
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": {
      "reason": "<string>",
      "suggested_context": {
        "recipe": {
          "fields": [
            "<string>"
          ],
          "last_n": {},
          "window": {},
          "max_tokens": 2,
          "related": {},
          "previous": {
            "fields": [
              "<string>"
            ],
            "anchor": "<string>"
          }
        },
        "cost_per_answer": 1,
        "whole_state_cost_per_answer": 1,
        "sampled_documents": 2,
        "excluded": [
          {
            "path": "<string>",
            "reason": "id"
          }
        ]
      }
    }
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": {
      "reason": "<string>",
      "suggested_context": {
        "recipe": {
          "fields": [
            "<string>"
          ],
          "last_n": {},
          "window": {},
          "max_tokens": 2,
          "related": {},
          "previous": {
            "fields": [
              "<string>"
            ],
            "anchor": "<string>"
          }
        },
        "cost_per_answer": 1,
        "whole_state_cost_per_answer": 1,
        "sampled_documents": 2,
        "excluded": [
          {
            "path": "<string>",
            "reason": "id"
          }
        ]
      }
    }
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": {
      "reason": "<string>",
      "suggested_context": {
        "recipe": {
          "fields": [
            "<string>"
          ],
          "last_n": {},
          "window": {},
          "max_tokens": 2,
          "related": {},
          "previous": {
            "fields": [
              "<string>"
            ],
            "anchor": "<string>"
          }
        },
        "cost_per_answer": 1,
        "whole_state_cost_per_answer": 1,
        "sampled_documents": 2,
        "excluded": [
          {
            "path": "<string>",
            "reason": "id"
          }
        ]
      }
    }
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": {
      "reason": "<string>",
      "suggested_context": {
        "recipe": {
          "fields": [
            "<string>"
          ],
          "last_n": {},
          "window": {},
          "max_tokens": 2,
          "related": {},
          "previous": {
            "fields": [
              "<string>"
            ],
            "anchor": "<string>"
          }
        },
        "cost_per_answer": 1,
        "whole_state_cost_per_answer": 1,
        "sampled_documents": 2,
        "excluded": [
          {
            "path": "<string>",
            "reason": "id"
          }
        ]
      }
    }
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": {
      "reason": "<string>",
      "suggested_context": {
        "recipe": {
          "fields": [
            "<string>"
          ],
          "last_n": {},
          "window": {},
          "max_tokens": 2,
          "related": {},
          "previous": {
            "fields": [
              "<string>"
            ],
            "anchor": "<string>"
          }
        },
        "cost_per_answer": 1,
        "whole_state_cost_per_answer": 1,
        "sampled_documents": 2,
        "excluded": [
          {
            "path": "<string>",
            "reason": "id"
          }
        ]
      }
    }
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": {
      "reason": "<string>",
      "suggested_context": {
        "recipe": {
          "fields": [
            "<string>"
          ],
          "last_n": {},
          "window": {},
          "max_tokens": 2,
          "related": {},
          "previous": {
            "fields": [
              "<string>"
            ],
            "anchor": "<string>"
          }
        },
        "cost_per_answer": 1,
        "whole_state_cost_per_answer": 1,
        "sampled_documents": 2,
        "excluded": [
          {
            "path": "<string>",
            "reason": "id"
          }
        ]
      }
    }
  }
}

Authorizations

Authorization

string

header

required

An organization API key. Keys carry a role (read_write or read_only) and may be restricted to a namespace prefix such as acme/*, or to one namespace such as acme/prod/tenant_1. A prefix matches on a / boundary: acme/prod/tenant_1* covers acme/prod/tenant_1 and everything under acme/prod/tenant_1/, never acme/prod/tenant_12.

Path Parameters

string

required

A namespace name, or a template prefix ending in /*, with any / sent as %2F: acme%2Fprod%2Ftenant_123 or acme%2Fprod%2F*.

A namespace name, or a template prefix: a namespace path ending in /*, such as acme/prod/*, which every namespace under acme/prod/ inherits judgments from. Up to 256 bytes. Never exactly . or .., which a URL path can't carry.

Required string length: 1 - 256

Pattern: ^(?!\.\.?$)[A-Za-z0-9._:/-]+(/\*)?$

name

string

required

A judgment, attribute or threshold name. Names are path segments in field references, so they never contain ..

Required string length: 1 - 128

Pattern: ^[A-Za-z0-9_-]+$

Response

The suggestion, or why there is none; status says which.

The cheaper context recipe a version's outcomes support, from its last recipe-tuning run, or why there is none.

version

integer<int32>

required

Required range: x >= 1

status

enum<string>

required

not_run: no run yet; reason says why.
running: a run is testing smaller recipes.
ready: suggestion holds a cheaper recipe.
none: the last run found none; reason says why.

Available options:

not_run,

running,

ready,

none

reason

enum<string> | null

required

Why there is no suggestion. Not run: awaiting_run (the next calibration run starts it), too_few_outcomes (no calibration fit yet), no_recipe, no_smaller_recipe (nothing to drop or halve, such as a single field), composite, inherited (the template has the suggestion). None: nothing_to_save (every answer is already standard, the smallest size class), no_cheaper_recipe (nothing moves enough answers to a smaller size class to be meaningfully cheaper), accuracy_would_drop, too_few_outcomes, cost_cap (the run stopped at this month's limit) or superseded (the engine's model changed during the run). Null while running and when ready.

Available options:

awaiting_run,

too_few_outcomes,

no_recipe,

composite,

inherited,

nothing_to_save,

no_smaller_recipe,

no_cheaper_recipe,

accuracy_would_drop,

cost_cap,

superseded

message

string

required

What status and reason mean, in a sentence.

headline

string | null

required

One sentence when ready, such as "A context recipe 42% cheaper per answer, with accuracy unchanged within noise on 312 labelled answers."

suggestion

object | null

required

One smaller recipe, measured against the current one on the same labelled answers and engine epoch. Apply it by posting definition as a new version and activating it through its shadow report.

Show child attributes

computed_at

string<date-time> | null

required

When the last run ended. Null before one has.

next_run_after

string<date-time> | null

required

The earliest the nightly calibration starts the next run, 30 days after the last started. Null before one has.

plan_required

object | null

required

Set below Team, where the recipe itself is withheld.

Show child attributes

Namespaces

Documents

Judgments

Outcomes and calibration

Groups

Subscriptions

Jobs

Engines

Organization

Webhooks

Get the cheaper context recipe the outcomes support

Authorizations

Path Parameters

Response