From 9e25bd90b7c59cc7089e0783012c70d2d969f272 Mon Sep 17 00:00:00 2001 From: pirumpi Date: Fri, 18 Sep 2026 16:39:20 -0600 Subject: [PATCH] Add pinned Spark X2.5 GGUF with llama.cpp b10964 --- .github/workflows/build.yml | 16 ++- catalog/catalog.json | 152 ++++++++++++++++++++++------- catalog/catalog.json.sha256 | 2 +- desktop/scripts/prepare-runtime.ts | 18 +++- docs/guides/choosing-models.md | 12 ++- internal/catalog/catalog.go | 24 +++++ internal/catalog/catalog_test.go | 1 + 7 files changed, 179 insertions(+), 46 deletions(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index e62bcea..ebcbcca 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -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: @@ -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 @@ -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)) { @@ -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)) { @@ -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 @@ -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 diff --git a/catalog/catalog.json b/catalog/catalog.json index b8ad9e5..88c3563 100644 --- a/catalog/catalog.json +++ b/catalog/catalog.json @@ -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", @@ -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", @@ -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", @@ -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", @@ -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", diff --git a/catalog/catalog.json.sha256 b/catalog/catalog.json.sha256 index eb9f57b..2d358a9 100644 --- a/catalog/catalog.json.sha256 +++ b/catalog/catalog.json.sha256 @@ -1 +1 @@ -d91050a9e05f939a2f68471286ea27365e4cf08f5464086ef11090c8015900ce catalog.json +60370f8fe3680b3ca478cf5cb62f6bd4c4af73277d5f0404f7e010fc4ef9378a catalog.json diff --git a/desktop/scripts/prepare-runtime.ts b/desktop/scripts/prepare-runtime.ts index 818b2eb..74905e2 100644 --- a/desktop/scripts/prepare-runtime.ts +++ b/desktop/scripts/prepare-runtime.ts @@ -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 = { + "darwin/arm64": "033c845c1df9bf945ff37bb193238b40910b2244be3e1e637b2ceb5878f1a6f5", + "win32/x64": "1ee3ad952f4ba71f438bd6d7bebef19e1c7af04adcaa35d08b4ddabb27d4c642", + "win32/arm64": "4b6a004b076eea47c318bea35cf1db2ff2bf037738b04645646ae8d7c3159478", + "linux/x64": "55d1e58e14c11eedea090bf088fdeefbfe7b4b09ee03bf6dba9834651769afcf", + "linux/arm64": "f7864baa0edf5a059fb42c5efb5aceb96075aa1f41e6c3142b71ca69286cb0bb", +}; export function llamaRuntimeAsset( platform: NodeJS.Platform, @@ -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( diff --git a/docs/guides/choosing-models.md b/docs/guides/choosing-models.md index 7547f57..6eaf4c9 100644 --- a/docs/guides/choosing-models.md +++ b/docs/guides/choosing-models.md @@ -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 diff --git a/internal/catalog/catalog.go b/internal/catalog/catalog.go index d653b98..002eb62 100644 --- a/internal/catalog/catalog.go +++ b/internal/catalog/catalog.go @@ -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", diff --git a/internal/catalog/catalog_test.go b/internal/catalog/catalog_test.go index 899980d..ad78d48 100644 --- a/internal/catalog/catalog_test.go +++ b/internal/catalog/catalog_test.go @@ -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")