open source

.understudy-model format

A .understudy-model is a versioned package for task-specific local classifiers. It is normally delivered as a ZIP container named .understudy-model, while ordinary .zip files and unpacked package directories remain valid inputs. Version 1 carries declarative data and weights only; executable code is not part of the package.

Directory layout

example.understudy-model/
├── manifest.json
├── taxonomy.json
├── model/
│   ├── adapter/
│   │   ├── adapter_config.json
│   │   └── adapters.safetensors
│   └── classifier-head.safetensors
└── provenance/                 # optional, still hashed
    └── training-result.json

Inside an archive, the files may be at the archive root or inside one directory ending in .understudy-model. An unpacked input directory must itself end in .understudy-model. Every file other than manifest.jsonmust appear exactly once in the manifest's files array with its relative path, byte count, and SHA-256 digest.

Manifest

manifest.json

{
  "schema_version": "understudy.task_model.v1",
  "id": "support-intent-e4b",
  "version": "1.0.0",
  "name": "Support intent classifier",
  "publisher": "Example Company",
  "runtime": {
    "kind": "mlx_vlm_classifier_v1",
    "base_model": {
      "id": "hf/mlx-community--gemma-4-e4b-it-4bit",
      "loader": "mlx_vlm"
    },
    "adapter_path": "model/adapter",
    "adapter_config_path": "model/adapter/adapter_config.json",
    "classifier_head_path": "model/classifier-head.safetensors"
  },
  "input": {
    "text_columns": ["text", "review"],
    "expected_label_columns": ["label_id"],
    "max_length": 512,
    "prompt_template": "Classify this message.\n\n{text}"
  },
  "scorer": {
    "kind": "hierarchical_taxonomy_v1",
    "taxonomy_path": "taxonomy.json",
    "top_k": 3
  },
  "files": [
    {
      "path": "model/adapter/adapters.safetensors",
      "sha256": "<64 lowercase hexadecimal characters>",
      "bytes": 123456
    }
  ]
}

field	contract
`schema_version`	`understudy.task_model.v1`
`id / version`	Stable package identity. Each value is at most 120 ASCII letters, numbers, dots, dashes, or underscores.
`runtime`	Version 1 requires mlx_vlm_classifier_v1, an mlx_vlm base model, adapter paths, and a safetensors classifier head.
`input`	Accepted source column aliases, maximum input length, and an optional prompt template containing exactly one {text} placeholder.
`scorer`	Version 1 requires hierarchical_taxonomy_v1, a taxonomy JSON path, and top_k from 1 through 20.
`files`	The complete integrity ledger for every package member except manifest.json.

Taxonomy and output

The taxonomy JSON is an object whose paths collection maps each detailed category to its level-one, level-two, and level-three ids and names. The runtime returns the highest-ranked detailed category plus a bounded list of alternatives. The Desktop preview currently displays the winning detailed category, confidence, and elapsed time.

Verification and installation

Archives are bounded to 10,000 entries and 4 GiB expanded size. Duplicate paths, traversal paths, and archived symlinks are rejected.
Absolute paths, parent traversal, and symlinks are rejected.
The declared adapter, adapter configuration, classifier head, and taxonomy must be regular files inside the package.
Every declared file is checked for its exact byte count and SHA-256 digest before installation.
Installation stages a verified copy and renames it atomically into ~/.understudy/models/task-models/<id>/<version>.understudy-model.
Reinstalling identical contents is safe. Reusing the same id and version for different contents is rejected.

Version 1 capabilities

capability	v1 status
Hierarchical single-label classification	Supported
Top-k category alternatives	Supported by the runtime
MLX-VLM base plus adapter and classifier head	Supported
Local single-example preview in Desktop	Supported
Package-provided executable code	Not allowed
Arbitrary Hugging Face or GGUF runtimes	Not part of v1
Silent model download during installation	Not performed

Using a package

If you received a package rather than authored one, follow the Desktop task-model guide.