# gizai/options

The options of a model: what a person or a program may set on a request of it, read from the model's contract in the catalog (its fields, the allowed values of a field, the range of a number and the defaults). One reading serves the form of a page, the list an Agent or a Desk shows, and the check of a request before it is sent to a provider, so a screen never offers a value the gateway refuses.

```gizlang
import * as Options from "gizai/options";
```

## Types

### `Setting`

```gizlang
type Setting = { name: string; label: string; control: string; values: Vec<string>; ranged: bool; least: f64; most: f64; fallback: string; required: bool; count: i64; numeric: bool; accept: string; }
```

One option of a model: its field `name`, a label, how a form asks for it ("text" a line, "long" a prompt, "select"
one of `values`, "number" within `least`..`most` when `ranged`, "check" a yes or no, "files" up to `count`
files: pictures, videos or sounds, `accept` says which: "image", "video", "audio" or "" any), its default as text
("" none), whether a request must give it, and whether a chosen value is sent as a number (`numeric`).

- `name`: `string`
- `label`: `string`
- `control`: `string`
- `values`: `Vec<string>`
- `ranged`: `bool`
- `least`: `f64`
- `most`: `f64`
- `fallback`: `string`
- `required`: `bool`
- `count`: `i64`
- `numeric`: `bool`
- `accept`: `string`

## Functions

### `hint`

```gizlang
function hint(name: string): string
```

A line of help under the field `name` ("" none).

Effects: fail, read, write, console, io, alloc.

### `first`

```gizlang
function first(o: Setting): bool
```

Whether the option `o` is one a form shows first: what is asked, the input files, and the shape, size, length and
count of the result.

Effects: fail, alloc.

### `label`

```gizlang
function label(name: string): string
```

A field's name as a label: "aspectRatio" is "Aspect ratio".

Effects: fail, read, write, console, io, alloc.

### `shown`

```gizlang
function shown(j: Json): string
```

A JSON scalar as the text a form shows: a string as it is, a number without a needless fraction.

Effects: fail, alloc.

### `optionsOf`

```gizlang
function optionsOf(contract: Json): Vec<Setting>
```

The options of a model with `contract` (a media model's; null gives none), in the contract's order, the prompt
first. A field that has another name shows once.

Effects: fail, read, write, console, io, alloc.

### `isFile`

```gizlang
function isFile(name: string): bool
```

Whether the field `name` holds the address of a file, or a list of them.

Effects: fail, alloc.

### `problems`

```gizlang
function problems(contract: Json, params: Json): Vec<string>
```

What is wrong with the request `params` of a model with `contract`, one sentence for each field ("": nothing): a
value the model does not take, a number outside its range, more files than it takes. A field the contract does not
name is left to the route, which drops what its provider does not take. A model without a contract takes anything.

Effects: fail, read, write, console, io, alloc.

### `request`

```gizlang
function request(settings: Vec<Setting>, fields: (name: string) => string): Json
```

The request made from a form's `fields` (name and text, as posted) for the options `settings`: each option's text
as its JSON value (a number, a yes or no, a list of addresses one a line), an empty field left out.

Effects: fail, read, write, console, io, alloc.

### `accepts`

```gizlang
function accepts(o: Setting, name: string): bool
```

Whether the file option `o` takes a file named `name`, by its extension.

Effects: fail, alloc.

### `accepted`

```gizlang
function accepted(o: Setting): string
```

What the file option `o` takes, in words.

### `described`

```gizlang
function described(contract: Json): Json
```

The options as JSON, for a program (GET /v1/models, an Agent's list, a Desk's form): name, label, control, values,
range, default, required and count.

Effects: fail, read, write, console, io, alloc.

### `union`

```gizlang
function union(contracts: Vec<Json>): Json
```

The contract of a model served by several routes: every field any route takes, the values and files any route
allows, the widest range, and the first default. A request it passes has at least one route to try; the routes
drop what their provider does not take.

Effects: fail, alloc.

### `ofParameters`

```gizlang
function ofParameters(parameters: Vec<string>): Vec<Setting>
```

The options of a language model that takes the request fields `parameters` (the names GET /v1/models lists as
supported_parameters): the ones a person sets, each under the field name a chat request carries. A model whose
fields are unknown gets none; the request itself is not checked, since a chat request passes through.

Effects: fail, read, write, console, io, alloc.

### `listing`

```gizlang
function listing(settings: Vec<Setting>): Json
```

`settings` as JSON, in the form `described` gives.

Effects: fail, alloc.

### `settings`

```gizlang
function settings(listed: Json): Vec<Setting>
```

The options a `listing` holds (what GET /v1/models gives for a model): a program that shows a model's form reads
them back.

Effects: fail, alloc.

