Run this month's recipe tuning now

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

import requests

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

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

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

print(response.text)

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

fetch('https://api.brussle.com/v1/namespaces/{ns}/judgments/{name}/recipe-tuning', 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-tuning",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  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-tuning"

	req, _ := http.NewRequest("POST", 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-tuning")

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

request = Net::HTTP::Post.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"
          }
        ]
      }
    }
  }
}

{
  "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

Run this month's recipe tuning now

Starts this month’s recipe-tuning run of the active version, or returns it: one run per version, engine epoch and calendar month (UTC), whether this or the nightly calibration starts it. The response is the suggestion as it stands, running until the run ends. Runs are never billed. On a template prefix, the template’s judgment, on its tenants’ pooled outcomes.

invalid_request when the version cannot be tuned: a judgment the namespace inherits from a template, a composite, no context recipe, a recipe with nothing to make smaller, or no calibration fit yet (100 outcomes, 20 of each kind). On the Team plan and above: below it, plan_required.

POST

namespaces

{ns}

judgments

{name}

recipe-tuning

Run this month's recipe tuning now

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

import requests

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

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

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

print(response.text)

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

fetch('https://api.brussle.com/v1/namespaces/{ns}/judgments/{name}/recipe-tuning', 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-tuning",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  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-tuning"

	req, _ := http.NewRequest("POST", 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-tuning")

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

request = Net::HTTP::Post.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"
          }
        ]
      }
    }
  }
}

{
  "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.

Headers

Idempotency-Key

string

One key per logical request, reused only on its retries. A key belongs to one request: within your organization, the same method, path, query and body. For 24 hours after a successful response, a request with the key and the same body gets that response back verbatim, with Idempotent-Replayed: true, and runs nothing. Only a successful response is kept, so the retry of a request that failed runs again. While the first request runs or its response is kept, the key with a different request is idempotency_key_reused (422). A request sent while one with its key is still running is rate_limited with Retry-After: 1, without running: retry it to get the first one's response. In the rare case the key can't be checked, the request runs as if it had none.

Required string length: 1 - 255

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 run started, is running, or ended this month.

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

Run this month's recipe tuning now

Authorizations

Headers

Path Parameters

Response