# axx models

> Stub embedded models: models whose answers are their mappings

Source: https://axx.nimbusxr.us/next/references/cli/axx-models/

Stub the models apps and services run themselves. A stub's directory has its
model's contract (contract.json, which `axx models contract` writes from the real
model) and its mappings (mappings/*.json); `axx models build` writes the stub, a
model the app's test build or test deployment puts where the app gets the real
one.

```text
Usage:
  axx models [command]

Available Commands:
  build       Build a stub, a model of its contract that answers its mappings
  contract    Write a model's contract, what a stub of it keeps to

Flags:
  -h, --help   help for models

Global Flags:
      --compact         print only what matters (auto-enabled for coding agents)
  -c, --config string   path to axx.yaml (default: search upward from the working directory)
      --json            emit machine-readable JSON (stable envelope)
      --no-color        disable colored output
  -v, --verbose count   increase log verbosity (-v, -vv)

Use "axx models [command] --help" for more information about a command.
```

## axx models build

Build the stub in the directory <stub>, from its contract (contract.json) and
its mappings (mappings/*.json), as a model of the contract's format: the file the
app's test build or test deployment puts where the app gets the real model. Keep
it with the app's sources: it is built the same, bit for bit, on every machine.
A mapping that cannot be used stops the build, named.

```text
Usage:
  axx models build [stub] [flags]

Flags:
      --contract string   the contract file (with --mappings, instead of a stub directory)
  -h, --help              help for build
      --mappings string   the mappings directory (with --contract)
  -o, --out string        the stub's file, like app/src/debug/assets/photo-check.tflite (required)

Global Flags:
      --compact         print only what matters (auto-enabled for coding agents)
  -c, --config string   path to axx.yaml (default: search upward from the working directory)
      --json            emit machine-readable JSON (stable envelope)
      --no-color        disable colored output
  -v, --verbose count   increase log verbosity (-v, -vv)
```

## axx models contract

Read a model and write its contract: its inputs and outputs, its format's
version and its metadata, what an app relies on from the model. A stub keeps to
it, so the app's runtime loads the stub as it loads the model. An input shaped
like an image gets an image layout: check it, and its channels' order (RGB or
BGR) and resizing (center-crop or stretch). A classifier's contract gives its
task and its labels (--task classification --labels labels.txt).

A model the platform gives the app (iOS's Vision, Android's ML Kit, a
browser's Prompt API) has no file to read: name its API instead, and the
contract is the API's (axx models contract ios.vision.text). A labeler's
contract takes the labels its mappings answer (--labels labels.txt).

The project keeps the contract in the stub's directory (contract.json): the
stub is built from it, and no test needs the real model. Models: coreml (.mlmodel, .mlpackage), ctranslate2 (.bin), executorch (.pte), foundation-models (.swift), gguf (.gguf), keras (.keras, .h5), litertlm (.litertlm), mlc (.json, a folder of mlc-chat-config.json), mnn (.mnn), mnn-llm (.json), ncnn (.param), onnx (.onnx), openai-whisper (.pt), openvino (.xml), parakeet (.gguf), piper (.onnx), platform (.axxmodel), pytorch-mobile (.ptl), safetensors (.safetensors, a folder of model.safetensors, a folder of model.safetensors.index.json), savedmodel (.pb, a folder of saved_model.pb), tesseract (.traineddata), tfjs (.json), tflite (.tflite, .lite), torchscript (.pt, .torchscript), whispercpp (.bin). APIs: android.gemini-nano, android.mlkit.image-labeling, android.mlkit.object-detection, android.mlkit.segmentation, android.mlkit.text-recognition, android.speech, ios.foundation-models, ios.private-cloud-compute, ios.speech, ios.vision.animals, ios.vision.classify, ios.vision.humans, ios.vision.person-segmentation, ios.vision.text, macos.foundation-models, macos.private-cloud-compute, macos.speech, macos.vision.animals, macos.vision.classify, macos.vision.humans, macos.vision.person-segmentation, macos.vision.text, web.language-detector, web.language-model, web.proofreader, web.rewriter, web.speech, web.summarizer, web.translator, web.writer, windows.ai.image-description, windows.ai.language-model, windows.ai.object-extractor, windows.ai.text-recognizer, windows.ai.text-rewriter, windows.ai.text-summarizer, windows.ai.text-to-table.

```text
Usage:
  axx models contract <model or API> [flags]

Flags:
  -h, --help                 help for contract
      --input stringArray    an input's type and shape, which the model does not say (a TorchScript module's) or which the app gives otherwise: 'name=type[dims]', like 'images=float32[1,3,224,224]' (? for a dimension of any size; quoted, as shells read [ and ?)
      --labels string        a file of a classifier's labels, one a line, in the order of their scores (a text recognizer's: the characters it reads, its blank an empty line)
  -o, --out string           the contract's file, like models/photo-check/contract.json (default: print it)
      --output stringArray   an output's type and shape, as --input gives an input's
      --task string          what the model's outputs mean: classification, detection, embedding, segmentation, speech-to-text, text-generation, text-recognition, text-to-speech
      --vocab string         a file of a text model's WordPiece vocabulary (BERT's vocab.txt), which the contract carries: its input of tokens' ids is matched by text

Global Flags:
      --compact         print only what matters (auto-enabled for coding agents)
  -c, --config string   path to axx.yaml (default: search upward from the working directory)
      --json            emit machine-readable JSON (stable envelope)
      --no-color        disable colored output
  -v, --verbose count   increase log verbosity (-v, -vv)
```