Skip to content
Merged
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
98 changes: 97 additions & 1 deletion catalog/catalog.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"schema": 1,
"generated_at": "2026-08-23T19:29:49.874922Z",
"generated_at": "2026-09-18T22:42:42.917442Z",
"models": {
"chatterbox": {
"name": "chatterbox",
Expand Down Expand Up @@ -102,6 +102,36 @@
"q8_0": "~30 GiB"
}
},
"granite-4.2": {
"context": 8192,
"name": "granite-4.2",
"repo": "ibm-granite/granite-4.2-3b-GGUF",
"files": {
"3b-q4_k_m": "granite-4.2-3b-Q4_K_M.gguf"
},
"default": "3b-q4_k_m",
"sizes": {
"3b-q4_k_m": "2.09 GiB"
},
"memory": {
"3b-q4_k_m": "8 GiB min; 16 GiB recommended at 8K context"
},
"gpus": {
"3b-q4_k_m": "CPU, Metal, Vulkan"
},
"features": {
"3b-q4_k_m": "Text chat; embedded thinking template; tool calling and FIM not qualified"
},
"downloads": {
"3b-q4_k_m": {
"revision": "47a3d9699d7539606c83943d717fcea7bd9f6a19",
"sha256": "20e436143017578687f7f848225cc6c6038126c84149192229c7dff6e4e0f427",
"size_bytes": 2244012160
}
},
"license": "Apache-2.0",
"license_url": "https://huggingface.co/ibm-granite/granite-4.2-3b"
},
"krea-2-raw": {
"name": "krea-2-raw",
"repo": "krea/Krea-2-Raw",
Expand Down Expand Up @@ -202,6 +232,39 @@
"2b-fp16": "NVIDIA CUDA, 8 GiB+ VRAM; CPU offload"
}
},
"minicpm5-2b": {
"context": 8192,
"name": "minicpm5-2b",
"repo": "openbmb/MiniCPM5-2B-GGUF",
"files": {
"q4_k_m": "MiniCPM5-2B-Q4_K_M.gguf"
},
"default": "q4_k_m",
"sizes": {
"q4_k_m": "~1.45 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": "English and Chinese"
},
"features": {
"q4_k_m": "basic text chat; tools and long context not yet qualified"
},
"downloads": {
"q4_k_m": {
"revision": "2079a22f3beaa4e306449978533478fe0522f4b3",
"sha256": "ec2d5801640099e97d8d7e8003ad4d81f336e757811f03a26173dddf386602fd",
"size_bytes": 1561318368
}
},
"license": "Apache-2.0",
"license_url": "https://huggingface.co/openbmb/MiniCPM5-2B"
},
"minimax-h3": {
"name": "minimax-h3",
"repo": "Comfy-Org/MiniMax-H3",
Expand Down Expand Up @@ -546,6 +609,39 @@
"fp16": "NVIDIA CUDA, 8 GiB+ VRAM"
}
},
"spark-x2.5-4b": {
"context": 8192,
"name": "spark-x2.5-4b",
"repo": "XHToken/Spark-X2.5-4B-GGUF",
"files": {
"q4_k_m": "Spark-X2.5-4B-Q4_K_M.gguf"
},
"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"
},
"downloads": {
"q4_k_m": {
"revision": "902d865994943ab9235670e24f01846ee06091f2",
"sha256": "adfcfa19a4ed6a5985da8bf565fe15f8e1a7e131d79bae2d19d48d1c40109428",
"size_bytes": 2600224352
}
},
"license": "Apache-2.0",
"license_url": "https://huggingface.co/XHToken/Spark-X2.5-4B"
},
"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 @@
932e371becaa8fb7db7e8cbf10235a34e7210b1948d9b2be9ff9f330dc76b752 catalog.json
f2731bfa83561e6dd5d65d55991f90693296e3934c3fc60fd3651730a4c4bae4 catalog.json
29 changes: 27 additions & 2 deletions desktop/scripts/prepare-runtime.test.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
import { describe, expect, it } from "vitest";
import { LLAMA_CPP_VERSION, llamaRuntimeAsset, windowsExtraction } from "./prepare-runtime";
import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
import os from "node:os";
import path from "node:path";
import { describe, expect, it, vi } from "vitest";
import { LLAMA_CPP_VERSION, llamaRuntimeAsset, prepareRuntime, windowsExtraction } from "./prepare-runtime";

describe("llama.cpp runtime assets", () => {
it("passes Windows archive paths as data, including spaces and shell metacharacters", () => {
Expand All @@ -26,4 +29,26 @@ describe("llama.cpp runtime assets", () => {
"No bundled llama.cpp runtime",
);
});

it("preserves an existing runtime if the replacement archive fails verification", async () => {
const root = await mkdtemp(path.join(os.tmpdir(), "tapioca-runtime-test-"));
const runtime = path.join(root, "runtime", "llama.cpp");
const executable = path.join(runtime, "llama-server");
await mkdir(runtime, { recursive: true });
await writeFile(executable, "existing runtime");
await writeFile(path.join(runtime, "tapioca-runtime-version.txt"), "b10603\n");
const fetchMock = vi.fn().mockResolvedValue({
ok: true,
arrayBuffer: async () => new TextEncoder().encode("invalid archive").buffer,
});
vi.stubGlobal("fetch", fetchMock);
try {
await expect(prepareRuntime(root, "darwin", "arm64")).rejects.toThrow("checksum mismatch");
expect(fetchMock).toHaveBeenCalledOnce();
expect(await readFile(executable, "utf8")).toBe("existing runtime");
} finally {
vi.unstubAllGlobals();
await rm(root, { recursive: true, force: true });
}
});
});
28 changes: 23 additions & 5 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 { mkdir, readFile, 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 windowsExtraction(archive: string, destination: string) {
return {
Expand Down Expand Up @@ -46,21 +55,28 @@ export async function prepareRuntime(
platform: NodeJS.Platform = process.platform,
arch: NodeJS.Architecture = process.arch,
): Promise<string> {
const destination = path.resolve(desktopRoot, "runtime", "llama.cpp");
try {
const preparedVersion = await readFile(path.join(destination, "tapioca-runtime-version.txt"), "utf8");
if (preparedVersion.trim() !== LLAMA_CPP_VERSION) throw new Error("llama.cpp runtime is outdated");
return verifyBundledRuntime(desktopRoot, platform);
} catch {
// Download below.
}
const asset = llamaRuntimeAsset(platform, arch);
const destination = path.resolve(desktopRoot, "runtime", "llama.cpp");
const temporary = path.join(os.tmpdir(), `tapioca-${asset.filename}`);
const response = await fetch(asset.url, { redirect: "follow" });
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 windows = windowsExtraction(temporary, destination);
const extraction = asset.zip
Expand All @@ -79,7 +95,9 @@ export async function prepareRuntime(
if (extraction.status !== 0) {
throw new Error(`Extracting llama.cpp failed with exit code ${extraction.status}`);
}
return verifyBundledRuntime(desktopRoot, platform);
const runtimePath = verifyBundledRuntime(desktopRoot, platform);
await writeFile(path.join(destination, "tapioca-runtime-version.txt"), `${LLAMA_CPP_VERSION}\n`);
return runtimePath;
}

const invoked = process.argv[1] ? path.resolve(process.argv[1]) : "";
Expand Down
11 changes: 11 additions & 0 deletions docs/guides/choosing-models.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,17 @@ video frames, runtime libraries, and other applications consume more memory.

Use an 8K–16K context instead of the model's maximum advertised context.

### Compact models under qualification

`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 files and default to an
8K context. The 8 GiB memory figure is a test target, **not a measured
minimum**; 16 GiB leaves room for the operating system and other apps.
Both passed basic CPU and Apple Silicon Metal chat tests with bundled
llama.cpp b10964. Windows/Linux Vulkan, long context, and structured tool use
are not yet qualified. Try `tapioca pull minicpm5-2b` or
`tapioca pull spark-x2.5-4b`, then `tapioca run MODEL`.

### Apple Silicon

| Model | Download | Best for |
Expand Down
2 changes: 2 additions & 0 deletions internal/catalog/catalog.go
Original file line number Diff line number Diff line change
Expand Up @@ -399,6 +399,8 @@ func validRelativePath(value string) bool {

var builtInModels = map[string]Model{
"granite-4.2": graniteModel(),
"minicpm5-2b": miniCPM5Model(),
"spark-x2.5-4b": sparkX25Model(),
"chatterbox": {
Name: "chatterbox",
Repo: "ResembleAI/chatterbox",
Expand Down
39 changes: 39 additions & 0 deletions internal/catalog/compact_models.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
package catalog

func miniCPM5Model() Model {
return Model{
Name: "minicpm5-2b", Context: 8192,
Repo: "openbmb/MiniCPM5-2B-GGUF", Default: "q4_k_m",
Files: map[string]string{"q4_k_m": "MiniCPM5-2B-Q4_K_M.gguf"},
Downloads: map[string]Download{"q4_k_m": {
Revision: "2079a22f3beaa4e306449978533478fe0522f4b3",
SHA256: "ec2d5801640099e97d8d7e8003ad4d81f336e757811f03a26173dddf386602fd",
SizeBytes: 1561318368,
}},
Sizes: map[string]string{"q4_k_m": "~1.45 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": "English and Chinese"},
Features: map[string]string{"q4_k_m": "basic text chat; tools and long context not yet qualified"},
License: "Apache-2.0", LicenseURL: "https://huggingface.co/openbmb/MiniCPM5-2B",
}
}

func sparkX25Model() Model {
return Model{
Name: "spark-x2.5-4b", Context: 8192,
Repo: "XHToken/Spark-X2.5-4B-GGUF", Default: "q4_k_m",
Files: map[string]string{"q4_k_m": "Spark-X2.5-4B-Q4_K_M.gguf"},
Downloads: map[string]Download{"q4_k_m": {
Revision: "902d865994943ab9235670e24f01846ee06091f2",
SHA256: "adfcfa19a4ed6a5985da8bf565fe15f8e1a7e131d79bae2d19d48d1c40109428",
SizeBytes: 2600224352,
}},
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://huggingface.co/XHToken/Spark-X2.5-4B",
}
}
26 changes: 26 additions & 0 deletions internal/catalog/compact_models_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
package catalog

import "testing"

func TestPinnedCompactModels(t *testing.T) {
for _, tc := range []struct {
ref, repo, file, revision, checksum string
bytes int64
}{
{"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) {
resolved, err := ResolveForPlatform(tc.ref, "darwin", "arm64")
if err != nil {
t.Fatal(err)
}
if resolved.Kind != "" || resolved.Repo != tc.repo || resolved.Filename != tc.file ||
resolved.SizeBytes != tc.bytes || resolved.SHA256 != tc.checksum ||
resolved.URL != "https://huggingface.co/"+tc.repo+"/resolve/"+tc.revision+"/"+tc.file ||
DefaultContext(tc.ref) != 8192 {
t.Fatalf("unexpected compact model: %#v", resolved)
}
})
}
}
Loading