Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 15 additions & 1 deletion .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,12 @@ permissions:
contents: read

env:
LLAMA_CPP_VERSION: b10603
LLAMA_CPP_VERSION: b10964
LLAMA_CPP_MACOS_ARM64_SHA256: 033c845c1df9bf945ff37bb193238b40910b2244be3e1e637b2ceb5878f1a6f5
LLAMA_CPP_WIN_VULKAN_X64_SHA256: 1ee3ad952f4ba71f438bd6d7bebef19e1c7af04adcaa35d08b4ddabb27d4c642
LLAMA_CPP_WIN_CPU_ARM64_SHA256: 4b6a004b076eea47c318bea35cf1db2ff2bf037738b04645646ae8d7c3159478
LLAMA_CPP_UBUNTU_VULKAN_X64_SHA256: 55d1e58e14c11eedea090bf088fdeefbfe7b4b09ee03bf6dba9834651769afcf
LLAMA_CPP_UBUNTU_VULKAN_ARM64_SHA256: f7864baa0edf5a059fb42c5efb5aceb96075aa1f41e6c3142b71ca69286cb0bb

jobs:
test:
Expand Down Expand Up @@ -90,6 +95,7 @@ jobs:
curl -fL \
"https://github.com/ggml-org/llama.cpp/releases/download/${LLAMA_CPP_VERSION}/llama-${LLAMA_CPP_VERSION}-bin-macos-arm64.tar.gz" \
-o llama.cpp.tar.gz
printf '%s %s\n' "$LLAMA_CPP_MACOS_ARM64_SHA256" llama.cpp.tar.gz | shasum -a 256 -c -
mkdir -p dist/runtime/llama.cpp
tar -xzf llama.cpp.tar.gz -C dist/runtime/llama.cpp --strip-components=1
test -x dist/runtime/llama.cpp/llama-server
Expand Down Expand Up @@ -158,6 +164,9 @@ jobs:
run: |
$url = "https://github.com/ggml-org/llama.cpp/releases/download/$env:LLAMA_CPP_VERSION/llama-$env:LLAMA_CPP_VERSION-bin-win-vulkan-x64.zip"
Invoke-WebRequest -Uri $url -OutFile llama.cpp.zip
if ((Get-FileHash -Algorithm SHA256 llama.cpp.zip).Hash.ToLowerInvariant() -ne $env:LLAMA_CPP_WIN_VULKAN_X64_SHA256) {
throw "llama.cpp archive checksum mismatch"
}
New-Item -ItemType Directory -Force dist/runtime/llama.cpp | Out-Null
Expand-Archive llama.cpp.zip -DestinationPath dist/runtime/llama.cpp
if (-not (Test-Path dist/runtime/llama.cpp/llama-server.exe)) {
Expand Down Expand Up @@ -226,6 +235,9 @@ jobs:
run: |
$url = "https://github.com/ggml-org/llama.cpp/releases/download/$env:LLAMA_CPP_VERSION/llama-$env:LLAMA_CPP_VERSION-bin-win-cpu-arm64.zip"
Invoke-WebRequest -Uri $url -OutFile llama.cpp.zip
if ((Get-FileHash -Algorithm SHA256 llama.cpp.zip).Hash.ToLowerInvariant() -ne $env:LLAMA_CPP_WIN_CPU_ARM64_SHA256) {
throw "llama.cpp archive checksum mismatch"
}
New-Item -ItemType Directory -Force dist/runtime/llama.cpp | Out-Null
Expand-Archive llama.cpp.zip -DestinationPath dist/runtime/llama.cpp
if (-not (Test-Path dist/runtime/llama.cpp/llama-server.exe)) {
Expand Down Expand Up @@ -291,6 +303,7 @@ jobs:
curl -fL \
"https://github.com/ggml-org/llama.cpp/releases/download/${LLAMA_CPP_VERSION}/llama-${LLAMA_CPP_VERSION}-bin-ubuntu-vulkan-x64.tar.gz" \
-o llama.cpp.tar.gz
printf '%s %s\n' "$LLAMA_CPP_UBUNTU_VULKAN_X64_SHA256" llama.cpp.tar.gz | sha256sum -c -
mkdir -p dist/runtime/llama.cpp
tar -xzf llama.cpp.tar.gz -C dist/runtime/llama.cpp --strip-components=1
test -x dist/runtime/llama.cpp/llama-server
Expand Down Expand Up @@ -349,6 +362,7 @@ jobs:
curl -fL \
"https://github.com/ggml-org/llama.cpp/releases/download/${LLAMA_CPP_VERSION}/llama-${LLAMA_CPP_VERSION}-bin-ubuntu-vulkan-arm64.tar.gz" \
-o llama.cpp.tar.gz
printf '%s %s\n' "$LLAMA_CPP_UBUNTU_VULKAN_ARM64_SHA256" llama.cpp.tar.gz | sha256sum -c -
mkdir -p dist/runtime/llama.cpp
tar -xzf llama.cpp.tar.gz -C dist/runtime/llama.cpp --strip-components=1
test -x dist/runtime/llama.cpp/llama-server
Expand Down
152 changes: 115 additions & 37 deletions catalog/catalog.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"schema": 1,
"generated_at": "2026-09-18T22:13:36Z",
"generated_at": "2026-09-18T22:37:04.990204Z",
"models": {
"chatterbox": {
"name": "chatterbox",
Expand Down Expand Up @@ -102,6 +102,44 @@
"q8_0": "~30 GiB"
}
},
"granite-4.2-3b": {
"name": "granite-4.2-3b",
"repo": "ibm-granite/granite-4.2-3b-GGUF",
"files": {
"q4_k_m": "granite-4.2-3b-Q4_K_M.gguf"
},
"revisions": {
"q4_k_m": "c40945d71cd90f249a56985e8155551a9188dc30"
},
"checksums": {
"q4_k_m": "e0406663965846ae22a403456eb826ccce5f450840491f71952f18a7cb78e7d5"
},
"byte_sizes": {
"q4_k_m": 2244011552
},
"contexts": {
"q4_k_m": 8192
},
"kind": "text",
"default": "q4_k_m",
"sizes": {
"q4_k_m": "~2.09 GiB"
},
"memory": {
"q4_k_m": "8 GiB minimum; 16 GiB recommended at 8K context"
},
"gpus": {
"q4_k_m": "CPU or Apple Metal; Vulkan pending qualification"
},
"languages": {
"q4_k_m": "12 languages"
},
"features": {
"q4_k_m": "basic text chat; tools and long context not yet qualified"
},
"license": "Apache-2.0",
"license_url": "https://www.apache.org/licenses/LICENSE-2.0"
},
"krea-2-raw": {
"name": "krea-2-raw",
"repo": "krea/Krea-2-Raw",
Expand Down Expand Up @@ -202,6 +240,44 @@
"2b-fp16": "NVIDIA CUDA, 8 GiB+ VRAM; CPU offload"
}
},
"minicpm5-2b": {
"name": "minicpm5-2b",
"repo": "openbmb/MiniCPM5-2B-GGUF",
"files": {
"q4_k_m": "MiniCPM5-2B-Q4_K_M.gguf"
},
"revisions": {
"q4_k_m": "2079a22f3beaa4e306449978533478fe0522f4b3"
},
"checksums": {
"q4_k_m": "ec2d5801640099e97d8d7e8003ad4d81f336e757811f03a26173dddf386602fd"
},
"byte_sizes": {
"q4_k_m": 1561318368
},
"contexts": {
"q4_k_m": 8192
},
"kind": "text",
"default": "q4_k_m",
"sizes": {
"q4_k_m": "~1.45 GiB"
},
"memory": {
"q4_k_m": "8 GiB minimum; 16 GiB recommended at 8K context"
},
"gpus": {
"q4_k_m": "CPU or Apple Metal; Vulkan pending qualification"
},
"languages": {
"q4_k_m": "English and Chinese"
},
"features": {
"q4_k_m": "basic text chat; tools and long context not yet qualified"
},
"license": "Apache-2.0",
"license_url": "https://www.apache.org/licenses/LICENSE-2.0"
},
"minimax-h3": {
"name": "minimax-h3",
"repo": "Comfy-Org/MiniMax-H3",
Expand Down Expand Up @@ -283,42 +359,6 @@
]
}
},
"granite-4.2-3b": {
"name": "granite-4.2-3b",
"repo": "ibm-granite/granite-4.2-3b-GGUF",
"files": {"q4_k_m": "granite-4.2-3b-Q4_K_M.gguf"},
"revisions": {"q4_k_m": "c40945d71cd90f249a56985e8155551a9188dc30"},
"checksums": {"q4_k_m": "e0406663965846ae22a403456eb826ccce5f450840491f71952f18a7cb78e7d5"},
"byte_sizes": {"q4_k_m": 2244011552},
"contexts": {"q4_k_m": 8192},
"kind": "text",
"default": "q4_k_m",
"sizes": {"q4_k_m": "~2.09 GiB"},
"memory": {"q4_k_m": "8 GiB minimum; 16 GiB recommended at 8K context"},
"gpus": {"q4_k_m": "CPU or Apple Metal; Vulkan pending qualification"},
"languages": {"q4_k_m": "12 languages"},
"features": {"q4_k_m": "basic text chat; tools and long context not yet qualified"},
"license": "Apache-2.0",
"license_url": "https://www.apache.org/licenses/LICENSE-2.0"
},
"minicpm5-2b": {
"name": "minicpm5-2b",
"repo": "openbmb/MiniCPM5-2B-GGUF",
"files": {"q4_k_m": "MiniCPM5-2B-Q4_K_M.gguf"},
"revisions": {"q4_k_m": "2079a22f3beaa4e306449978533478fe0522f4b3"},
"checksums": {"q4_k_m": "ec2d5801640099e97d8d7e8003ad4d81f336e757811f03a26173dddf386602fd"},
"byte_sizes": {"q4_k_m": 1561318368},
"contexts": {"q4_k_m": 8192},
"kind": "text",
"default": "q4_k_m",
"sizes": {"q4_k_m": "~1.45 GiB"},
"memory": {"q4_k_m": "8 GiB minimum; 16 GiB recommended at 8K context"},
"gpus": {"q4_k_m": "CPU or Apple Metal; Vulkan pending qualification"},
"languages": {"q4_k_m": "English and Chinese"},
"features": {"q4_k_m": "basic text chat; tools and long context not yet qualified"},
"license": "Apache-2.0",
"license_url": "https://www.apache.org/licenses/LICENSE-2.0"
},
"phi4-mini": {
"name": "phi4-mini",
"repo": "unsloth/Phi-4-mini-instruct-GGUF",
Expand Down Expand Up @@ -582,6 +622,44 @@
"fp16": "NVIDIA CUDA, 8 GiB+ VRAM"
}
},
"spark-x2.5-4b": {
"name": "spark-x2.5-4b",
"repo": "XHToken/Spark-X2.5-4B-GGUF",
"files": {
"q4_k_m": "Spark-X2.5-4B-Q4_K_M.gguf"
},
"revisions": {
"q4_k_m": "902d865994943ab9235670e24f01846ee06091f2"
},
"checksums": {
"q4_k_m": "adfcfa19a4ed6a5985da8bf565fe15f8e1a7e131d79bae2d19d48d1c40109428"
},
"byte_sizes": {
"q4_k_m": 2600224352
},
"contexts": {
"q4_k_m": 8192
},
"kind": "text",
"default": "q4_k_m",
"sizes": {
"q4_k_m": "~2.42 GiB"
},
"memory": {
"q4_k_m": "8 GiB test target; 16 GiB recommended at 8K context"
},
"gpus": {
"q4_k_m": "CPU or Apple Metal; Vulkan pending qualification"
},
"languages": {
"q4_k_m": "multilingual"
},
"features": {
"q4_k_m": "basic text chat; tools and long context not yet qualified"
},
"license": "Apache-2.0",
"license_url": "https://www.apache.org/licenses/LICENSE-2.0"
},
"stable-video-diffusion": {
"name": "stable-video-diffusion",
"repo": "stabilityai/stable-video-diffusion-img2vid-xt",
Expand Down
2 changes: 1 addition & 1 deletion catalog/catalog.json.sha256
Original file line number Diff line number Diff line change
@@ -1 +1 @@
d91050a9e05f939a2f68471286ea27365e4cf08f5464086ef11090c8015900ce catalog.json
60370f8fe3680b3ca478cf5cb62f6bd4c4af73277d5f0404f7e010fc4ef9378a catalog.json
18 changes: 16 additions & 2 deletions desktop/scripts/prepare-runtime.ts
Original file line number Diff line number Diff line change
@@ -1,12 +1,21 @@
import { mkdir, rm, writeFile } from "node:fs/promises";
import { existsSync } from "node:fs";
import { spawnSync } from "node:child_process";
import { createHash } from "node:crypto";
import os from "node:os";
import path from "node:path";
import { fileURLToPath } from "node:url";
import { verifyBundledRuntime } from "./verify-runtime.ts";

export const LLAMA_CPP_VERSION = "b10603";
export const LLAMA_CPP_VERSION = "b10964";

const runtimeChecksums: Record<string, string> = {
"darwin/arm64": "033c845c1df9bf945ff37bb193238b40910b2244be3e1e637b2ceb5878f1a6f5",
"win32/x64": "1ee3ad952f4ba71f438bd6d7bebef19e1c7af04adcaa35d08b4ddabb27d4c642",
"win32/arm64": "4b6a004b076eea47c318bea35cf1db2ff2bf037738b04645646ae8d7c3159478",
"linux/x64": "55d1e58e14c11eedea090bf088fdeefbfe7b4b09ee03bf6dba9834651769afcf",
"linux/arm64": "f7864baa0edf5a059fb42c5efb5aceb96075aa1f41e6c3142b71ca69286cb0bb",
};

export function llamaRuntimeAsset(
platform: NodeJS.Platform,
Expand Down Expand Up @@ -50,9 +59,14 @@ export async function prepareRuntime(
if (!response.ok) {
throw new Error(`Download ${asset.url} failed: ${response.status} ${response.statusText}`);
}
const archive = Buffer.from(await response.arrayBuffer());
const expected = runtimeChecksums[`${platform}/${arch}`];
if (!expected || createHash("sha256").update(archive).digest("hex") !== expected) {
throw new Error(`llama.cpp archive checksum mismatch for ${platform}/${arch}`);
}
await rm(destination, { recursive: true, force: true });
await mkdir(destination, { recursive: true });
await writeFile(temporary, Buffer.from(await response.arrayBuffer()));
await writeFile(temporary, archive);

const extraction = asset.zip
? spawnSync(
Expand Down
12 changes: 7 additions & 5 deletions docs/guides/choosing-models.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,18 +38,20 @@ Use an 8K–16K context instead of the model's maximum advertised context.

### Compact GGUF models under qualification

`granite-4.2-3b:q4_k_m` (~2.09 GiB) and `minicpm5-2b:q4_k_m`
(~1.45 GiB) use pinned, SHA-256-checked official GGUF artifacts. Both default
`granite-4.2-3b:q4_k_m` (~2.09 GiB), `minicpm5-2b:q4_k_m`
(~1.45 GiB), and `spark-x2.5-4b:q4_k_m` (~2.42 GiB) use pinned,
SHA-256-checked official GGUF artifacts. All three default
to an 8K context to avoid allocating their much larger advertised context
windows on a small machine. The 8 GiB system-memory figure is a conservative
test target, **not a measured minimum**; 16 GiB leaves more room for the OS and
other apps. CPU and Apple Silicon Metal chat have been smoke-tested with the
bundled llama.cpp b10603. Windows/Linux Vulkan, long-context behavior, and
bundled llama.cpp b10964. Windows/Linux Vulkan, long-context behavior, and
structured tool use are not yet qualified, so these are not replacements for
the established starter models above.

To try either model on a supported test machine, run
`tapioca pull granite-4.2-3b` or `tapioca pull minicpm5-2b`, then
To try one on a supported test machine, run
`tapioca pull granite-4.2-3b`, `tapioca pull minicpm5-2b`, or
`tapioca pull spark-x2.5-4b`, then
`tapioca run MODEL`.
Keep `--context 8192` when comparing memory use. The Q4 downloads are pinned
to specific Hugging Face revisions; an invalid cached file is rejected rather
Expand Down
24 changes: 24 additions & 0 deletions internal/catalog/catalog.go
Original file line number Diff line number Diff line change
Expand Up @@ -687,6 +687,30 @@ var builtInModels = map[string]Model{
License: "Apache-2.0",
LicenseURL: "https://www.apache.org/licenses/LICENSE-2.0",
},
"spark-x2.5-4b": {
Name: "spark-x2.5-4b",
Repo: "XHToken/Spark-X2.5-4B-GGUF",
Kind: "text",
Default: "q4_k_m",
Files: map[string]string{
"q4_k_m": "Spark-X2.5-4B-Q4_K_M.gguf",
},
Revisions: map[string]string{
"q4_k_m": "902d865994943ab9235670e24f01846ee06091f2",
},
Checksums: map[string]string{
"q4_k_m": "adfcfa19a4ed6a5985da8bf565fe15f8e1a7e131d79bae2d19d48d1c40109428",
},
ByteSizes: map[string]int64{"q4_k_m": 2600224352},
Contexts: map[string]int{"q4_k_m": 8192},
Sizes: map[string]string{"q4_k_m": "~2.42 GiB"},
Memory: map[string]string{"q4_k_m": "8 GiB test target; 16 GiB recommended at 8K context"},
GPUs: map[string]string{"q4_k_m": "CPU or Apple Metal; Vulkan pending qualification"},
Languages: map[string]string{"q4_k_m": "multilingual"},
Features: map[string]string{"q4_k_m": "basic text chat; tools and long context not yet qualified"},
License: "Apache-2.0",
LicenseURL: "https://www.apache.org/licenses/LICENSE-2.0",
},
"gemma3": {
Name: "gemma3",
Repo: "ggml-org/gemma-3-4b-it-GGUF",
Expand Down
1 change: 1 addition & 0 deletions internal/catalog/catalog_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@ func TestResolvePinnedCompactModels(t *testing.T) {
}{
{"granite-4.2-3b", "ibm-granite/granite-4.2-3b-GGUF", "granite-4.2-3b-Q4_K_M.gguf", "c40945d71cd90f249a56985e8155551a9188dc30", "e0406663965846ae22a403456eb826ccce5f450840491f71952f18a7cb78e7d5", 2244011552},
{"minicpm5-2b", "openbmb/MiniCPM5-2B-GGUF", "MiniCPM5-2B-Q4_K_M.gguf", "2079a22f3beaa4e306449978533478fe0522f4b3", "ec2d5801640099e97d8d7e8003ad4d81f336e757811f03a26173dddf386602fd", 1561318368},
{"spark-x2.5-4b", "XHToken/Spark-X2.5-4B-GGUF", "Spark-X2.5-4B-Q4_K_M.gguf", "902d865994943ab9235670e24f01846ee06091f2", "adfcfa19a4ed6a5985da8bf565fe15f8e1a7e131d79bae2d19d48d1c40109428", 2600224352},
} {
t.Run(tc.ref, func(t *testing.T) {
got, err := ResolveFor(tc.ref, "darwin")
Expand Down
Loading