Model ID Format

How hali names and identifies models.

---

Canonical model ID

Every model in the hali cache has a canonical four-part identifier:

base:size:variant:quant

Part	Meaning	Examples
base	The model family / architecture	mistral, llama, codellama, phi, gemma
size	Parameter count	7b, 8b, 13b, 34b, 70b
variant	Model variant / fine-tune type	instruct, chat, code, base
quant	Quantization method and bit width	q4_k_m, q5_k_m, q8_0, f16

Examples

mistral:7b:instruct:q4_k_m
llama:8b:instruct:q5_k_m
codellama:13b:code:q4_k_m
phi:3b:chat:q4_k_m
gemma:7b:instruct:q6_k

---

How the ID is derived

hali computes the canonical ID automatically from the HuggingFace repo name and GGUF filename. The parsing is heuristic and handles the most common naming conventions.

From a repo name + filename

Repo:     TheBloke/Mistral-7B-Instruct-v0.2-GGUF
File:     mistral-7b-instruct-v0.2.Q4_K_M.gguf

→ mistral:7b:instruct:q4_k_m

hali extracts:

• base — from the file prefix (before the first -)
• size — from the parameter count (7b, 8b, etc.)
• variant — from known variant words (instruct, chat, code)
• quant — from the quantization suffix (.Q4_K_M, .Q5_K_M, etc.)

Edge cases

If automatic parsing produces a best-guess that's ambiguous, hali uses a slug-based fallback derived from the file name. The canonical ID is always deterministic — the same repo and file always produce the same ID.

---

Quantizations recognized

hali recognizes standard GGUF quantization suffixes:

Suffix	Bits	Size (7B model)	Quality
q2_k	2-bit	~2.8 GB	Minimum viable
q3_k_s	3-bit small	~3.1 GB
q3_k_m	3-bit medium	~3.3 GB
q3_k_l	3-bit large	~3.5 GB
q4_0	4-bit	~3.8 GB
q4_k_s	4-bit K-small	~3.9 GB
q4_k_m	4-bit K-medium	~4.1 GB	Recommended
q5_0	5-bit	~4.4 GB
q5_k_s	5-bit K-small	~4.6 GB
q5_k_m	5-bit K-medium	~4.8 GB
q6_k	6-bit K	~5.4 GB	High quality
q8_0	8-bit	~7.0 GB	Near-lossless
f16	16-bit float	~14.0 GB	Reference (no quantization)

All suffixes are normalized to lowercase in the canonical ID (q4_k_m, not Q4_K_M).

---

Using model IDs with hali commands

hali pull

hali pull mistral:7b:instruct:q4_k_m     # Direct — no prompts
hali pull TheBloke/Mistral-7B-Instruct-v0.2-GGUF   # Repo — pick quantization
hali pull mistral                          # Search — pick repo and quantization

hali export

hali export ollama mistral:7b:instruct:q4_k_m
hali export lmstudio mistral:7b:instruct:q4_k_m
hali export all mistral:7b:instruct:q4_k_m

The canonical ID is always base:size:variant:quant — these are used as-is in commands.

hali list

MODEL ID                                    SIZE        DOWNLOADED
------------------------------------------  ----------  ----------
mistral:7b:instruct:q4_k_m                 4.14 GB     2026-05-23

---

Infohash identity

In addition to the human-readable model ID, every model has a torrent infohash — the BitTorrent identity used for peer discovery and piece verification.

Version	Algorithm	Length	Example
v1	SHA-1	40 hex chars	a3f9c21b4d67e8f01a2b3c4d5e6f7890ab1cd2ef3
v2	SHA-256	64 hex chars	f8c41dc0a13b...

At least one infohash version must be present for registry submission. The canonical hash (used as the primary key in the registry) is v2 if present, otherwise v1.

---

Why the canonical format?

• Unambiguous. mistral:7b:instruct:q4_k_m is exactly one model file. No confusion about which repo or which quantization.
• Deterministic. Two people downloading the same model version produce the same ID. This is the property that makes torrent cross-seeding work.
• Sortable. base:size:variant:quant groups models logically — all Mistral 7B models together, sorted by quantization.
• Scriptable. A predictable format means no parsing surprises in CI pipelines and automation.

---

Storage layout

The model ID maps directly to the cache directory structure:

~/.hali/cache/<base>/<size>-<variant>/<quant>/model.gguf
~/.hali/cache/<base>/<size>-<variant>/<quant>/metadata.json

Example:

~/.hali/cache/mistral/7b-instruct/q4_k_m/model.gguf
~/.hali/cache/mistral/7b-instruct/q4_k_m/metadata.json

metadata.json

{
  "model_id": "mistral:7b:instruct:q4_k_m",
  "hf_repo": "TheBloke/Mistral-7B-Instruct-v0.2-GGUF",
  "hf_revision": "abc123",
  "torrent_infohash": "a3f9c21b4d67...",
  "files": ["mistral-7b-instruct-v0.2.Q4_K_M.gguf"],
  "size": 4368439296,
  "download_at": "2026-05-23T10:00:00Z"
}