An input the caller may leave out — defaults

In ai()'s codebook, tone = defaults_to("kind") makes tone an input a caller may leave out: reply(message) sends "kind", as an R function's default argument does, and the call log records the value sent. The model is sent every input, so an input left out is sent with its default. The default is part of the function's interface (ai_interface()), not of what its calls record as data: changing it changes neither the function's signature nor its version, only what a call that leaves the input out sends.

Usage

defaults_to(value, type = NULL)

Arguments

value: The default: one value (a string, a number, TRUE, a date, a one-row tibble for a record, NA or NULL for an optional() type).
type: Its type, as in ai(); or a sentence, words about the type value has. Default: the type of value (text for a string or a date, a whole number for an integer, ...).

Value

A field.

Details

The default must be of the type, as vctrs casts (defaults_to(2.5, integer()) is refused: it would lose the half; so is defaults_to(TRUE, character())), and fit it (a choice()'s default is one of its answers); a function whose default does not fit is refused when it is defined (interface-malformed). Only inputs have defaults.

A call that leaves the input out sends the default exactly as the interface holds it (its JSON), never a copy made through an R type: a record's default that leaves out a member sends it without that member.

Examples

reply <- ai(reply ~ message + tone, "Answer the customer.",
  message = "the customer's own words",
  tone = defaults_to("kind", choice("kind", "brief", "formal")))
reply
#> <ai function> reply ~ message + tone
#>   Answer the customer.
#>   message  text  # the customer's own words
#>   tone     one of kind, brief, formal = "kind"
#>   reply    text
#>   model: gpt-4.1-mini
ai_interface(reply)
#> <interface> Answer the customer.
#>   inputs:
#>     message  {"type":"string"}  # the customer's own words
#>     tone     {"enum":["kind","brief","formal"],"type":"string"}  (optional, default "kind")
#>   outputs:
#>     result   {"type":"string"}
defaults_to(3L, "how many suggestions to give")     # a whole number, described
#> <functai field> whole number  # how many suggestions to give