# gizai/catalog

Model identities, artifact selection and local readiness.

```gizlang
import * as Catalog from "gizai/catalog";
```

## Types

### `Encoding`

```gizlang
type Encoding = { name: string; encoder: Option<Encoder>; ranker: Option<CrossEncoder>; }
```

A text encoder a server serves (serve): the name requests give it, and its sentence encoder (kind "embed") or its
cross-encoder (kind "rank").

- `name`: `string`
- `encoder`: `_gizlang_sdk_core.Option<M54.Encoder>`
- `ranker`: `_gizlang_sdk_core.Option<M54.CrossEncoder>`

## Functions

### `catalog`

```gizlang
function catalog(): Vec<Entry>
```

The models known by name: the entries of every family, by kind (KINDS), each family's in its order.

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

### `family`

```gizlang
function family(e: Entry): Option<Family>
```

The family of model `e`; none for a Hugging Face repository outside the catalog.

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

### `standard`

```gizlang
function standard(kind: string, memory: i64 = 0): string
```

The name of the catalog's model of `kind` that a caller gets when it names none, on a GPU of `memory` GiB
(memoryOf; 0: none): of the standard models whose `memory` it has, the one that asks the most; else the kind's
first.

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

### `chatModel`

```gizlang
function chatModel(gpu: Option<Gpu>): string
```

The chat model that a caller gets when it names none: $GIZ_AI_MODEL when it is set, else the standard chat model
for the memory of `gpu` (standard; none: the CPU's).

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

### `memoryOf`

```gizlang
function memoryOf(gpu: Option<Gpu>): i64
```

The memory of `gpu` in whole GiB, as `standard` compares it with a model's (0 without a GPU). A card sold as 16 GB
has just under 16 GiB.

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

### `fitted`

```gizlang
function fitted(e: Entry, gpu: Option<Gpu>): Entry
```

Chat model `e` in the formats that `gpu` runs best: a model of 4-bit linears in NVFP4, its head too, where the GPU
multiplies FP4 values (NVIDIA Blackwell, productsOf), else as the catalog has it (codebooks, which every device
reads). Formats named with the model (NAME:FORMAT), a model folder and a GGUF file (its K blocks) stay as they
are.

Effects: fail, alloc.

### `find`

```gizlang
function find(given: string, hub: Option<Hub.Hub> = undefined): Entry throws string
```

The catalog's model of `name` (or of its repository), else the Hugging Face repository `name` ("owner/name", or its
address, Hub.repoOf) as its files make it (fromRepo). A chat model's name may end in ":FORMAT" (Q.parseFormat:
"qwen3.5-0.8b:bf16"): its linears and head in that format. A repository is read in HUB (the models folder by default).

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

### `models`

```gizlang
function models(): Hub.Hub throws string
```

The models folder (Hub.folder), downloads on.

Effects: fail, io, alloc.

### `pull`

```gizlang
function pull(hub: Hub.Hub, name: string): string throws string
```

The model of `name` (find) downloaded and converted, as its first use does (prepared); returns its local folder.

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

### `prepared`

```gizlang
function prepared(hub: Hub.Hub, name: string): void throws string
```

Model `name`'s files fetched once before its first use, with a line that says so: every engine maker, worker and
command calls it, so `here` holds after any use. A model of a folder of its own (local) or of its worker's options
(no repository) has nothing to fetch.

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

### `prepare`

```gizlang
function prepare(hub: Hub.Hub, e: Entry): void throws string
```

Fetches the selected artifact of `e` if its files are missing.

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

### `remove`

```gizlang
function remove(hub: Hub.Hub, name: string): void throws string
```

Removes the files of model `name` (find) from the models folder: its repository and what was converted from it.
A model whose files are a folder of its own, or its worker's, is not the models folder's to remove.

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

### `here`

```gizlang
function here(hub: Hub.Hub, e: Entry): bool
```

Whether the models folder holds model `e` ready: a use downloads and converts nothing.

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

### `encoder`

```gizlang
function encoder(hub: Hub.Hub, name: string, onGpu: bool = true): Encoding throws string
```

The encoder of `name` (find; kind "embed" or "rank"), from its repository's files (LlmEncoders.encoderOf, LlmEncoders.crossEncoderOf),
on the GPU when `onGpu` and there is one.

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

### `text`

```gizlang
function text(hub: Hub.Hub, name: string, onGpu: bool = true, o: LlmEngine.EngineOptions = {}): Model throws string
```

The chat model of `name` (find), on the GPU when `onGpu` and there is one, for engines of options `o` (ready).

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

### `local`

```gizlang
function local(e: Entry): bool
```

Whether model `e` is a folder named by its path (find).

Effects: fail.

