# gizai:family

the contract between the host (gizai:ai and `giz ai`) and a model family. A family is a folder ai/models/NAME whose family.giz gives `family()`: the models it serves (Entry), and what it does with them: their files (fetch, here), an image engine (image), a video engine (video), a speech-to-text engine (transcriber) and a worker (worker). The host names no model: gizai:models/registry lists the family of every folder, and `giz ai registry` writes that list again from the folders.

```gizlang
import * as Family from "gizai:family";
```

## Types

### `Entry`

```gizlang
type Entry = { name: string; repo: string; kind: string; bits: Bits; about: string; standard?: bool; }
```

A model by name: its Hugging Face repository ("" when its worker reads its files from its options), its kind
("text": a chat model, "embed": a sentence encoder, "rank": a cross-encoder, which gizai:llm runs; or "image",
"video", "speech", "transcription", "talking-head"), the bits of its linears (an image model's: 8, or 4 for INT4;
an encoder's are as stored), what it is, and whether it is the model of its kind that a caller gets when it names
none.

- `name`: `string`
- `repo`: `string`
- `kind`: `string`
- `bits`: `_gizlang_lib_ai__llm__convert.Bits`
- `about`: `string`
- `standard`: `_gizlang_sdk_core.Option<bool>`

### `Options`

```gizlang
type Options = { names: Vec<string>; values: Vec<string>; }
```

The flags of a command line with their values ("" for a flag without one).

- `names`: `Vec<string>`
- `values`: `Vec<string>`

### `Family`

```gizlang
type Family = { entries: Vec<Entry>; options?: Vec<string>; fetch?: (hub: Hub.Hub, e: Entry) => Result<string, string>; here?: (hub: Hub.Hub, e: Entry) => bool; image?: (hub: Hub.Hub, e: Entry, gpu: Gpu) => Result<Painter, string>; video?: (hub: Hub.Hub, e: Entry, gpu: Gpu) => Result<Filmer, string>; transcriber?: (hub: Hub.Hub, e: Entry) => Result<Transcriber, string>; worker?: (sys: System, hub: Hub.Hub, e: Entry, o: Options, place: Place) => Result<i64, string>; }
```

A model family. Every field but `entries` is optional:
- `options`: the flags its worker takes a value for ("--files").
- `fetch`: downloads (and converts) model `e` into the models folder, as its first use does; returns its folder.
  Without it a chat model or an encoder is fetched as gizai:llm reads it; another kind has nothing to fetch.
- `here`: whether the models folder holds `e` ready. Without it, as `fetch`.
- `image`: the image engine of `e` on `gpu` (gizai:tasks/image). A family with it serves image.generate jobs.
- `video`: the video engine of `e` on `gpu` (gizai:tasks/video).
- `transcriber`: the speech-to-text engine of `e` (gizai:tasks/transcription), its files fetched first.
- `worker`: serves `e` as giz's inference worker at `place` with the command line's options; returns when it
  stops.

- `entries`: `Vec<M20.Entry>`
- `options`: `_gizlang_sdk_core.Option<Vec<string>>`
- `fetch`: `_gizlang_sdk_core.Option<(hub: gizlang_hub.Hub, e: M20.Entry) => _gizlang_sdk_core.Result<string, string>>`
- `here`: `_gizlang_sdk_core.Option<(hub: gizlang_hub.Hub, e: M20.Entry) => bool>`
- `image`: `_gizlang_sdk_core.Option<(hub: gizlang_hub.Hub, e: M20.Entry, gpu: M10.Gpu) => _gizlang_sdk_core.Result<_gizlang_lib_ai__tasks__image.Painter, string>>`
- `video`: `_gizlang_sdk_core.Option<(hub: gizlang_hub.Hub, e: M20.Entry, gpu: M10.Gpu) => _gizlang_sdk_core.Result<_gizlang_lib_ai__tasks__video.Filmer, string>>`
- `transcriber`: `_gizlang_sdk_core.Option<(hub: gizlang_hub.Hub, e: M20.Entry) => _gizlang_sdk_core.Result<_gizlang_lib_ai__tasks__transcription.Transcriber, string>>`
- `worker`: `_gizlang_sdk_core.Option<(sys: gizlang_system.System, hub: gizlang_hub.Hub, e: M20.Entry, o: M20.Options, place: M22.Place) => _gizlang_sdk_core.Result<i64, string>>`

## Functions

### `chat`

```gizlang
function chat(name: string, repo: string, layers: i64, head: i64, about: string): Entry
```

A chat model of gizai:llm: its linears and its head in `layers` and `head` bits.

### `encoding`

```gizlang
function encoding(name: string, repo: string, kind: string, about: string): Entry
```

A text encoder of gizai:llm (kind "embed" or "rank"), its linears as stored.

## Methods

### `Options.text`

```gizlang
function Options.text(self: Options, name: string, otherwise: string): string
```

The value of flag `name`, else `otherwise`.

Effects: fail.

### `Options.number`

```gizlang
function Options.number(self: Options, name: string, otherwise: i64): i64 throws string
```

The whole number of flag `name`, else `otherwise`; an error where its value is not one.

Effects: fail.