Skip to main content
A decision is a constrained inference request. You provide context and a question, then define the only outputs your application accepts. Goldenfish returns one of those outputs instead of an unconstrained paragraph.

​
The decision lifecycle

  1. Your application sends input and instruction.
  2. Goldenfish evaluates the request with the selected model.
  3. The model compares the context against either inline choices or a saved catalog.
  4. The response returns the selected choice, confidence, and probabilities.
  5. Your application maps the choice to an action, queue, state, or human review path.

​
Request shape

​
model

The model identifier is a non-empty string. The model is chosen in the request body so the /v1/decisions route remains stable when the catalog of models changes. Use GET /v1/models to discover available identifiers. A revision can be written as a model string such as goldenfish-g1@REVISION when your deployment exposes one.

​
input

The context to classify. Keep it focused on the information needed to make the decision. If the input contains untrusted user content, treat the returned choice as a recommendation that still needs application-level validation.

​
instruction

The question or decision instruction. Phrase it so the expected output is clear and maps to the provided choices.

​
choices or catalog

Send exactly one source of outcomes:
  • choices is an inline array of 2–300 unique, non-empty strings.
  • catalog is the ID of a reusable catalog created through the catalogs API.
The schema rejects requests that send both fields or neither field.

​
Response shape

  • id is the decision identifier and begins with dec_.
  • object is always decision.
  • model records the model used for the result.
  • output.choice is one of the submitted or catalog choices.
  • output.confidence is a number from 0 to 1 for the selected choice.
  • output.probabilities maps each choice string to a number from 0 to 1.
  • usage.input_tokens reports the input token count used for the request.

​
Choosing a fallback policy

Goldenfish gives your application enough information to decide what happens next, but it does not impose a confidence threshold. Common policies include:
  • Accept the choice when confidence is above a threshold you have tested.
  • Route low-confidence decisions to a human queue.
  • Ask for more context when several probabilities are close.
  • Record the full response for offline evaluation, subject to your privacy policy.
Do not compare probabilities from different models as if they were calibrated to the same scale. Evaluate the policy with representative data for the exact model and choices you use.

​
Design good choice sets

  • Make choices mutually exclusive where possible.
  • Use stable machine-readable identifiers rather than long descriptions.
  • Keep labels specific enough that two choices do not mean the same thing.
  • Define an explicit fallback choice when “none of the above” is a valid outcome.
  • Version a catalog when changing its meaning would make historical results ambiguous.