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
38 changes: 37 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:13:36Z",
"models": {
"chatterbox": {
"name": "chatterbox",
Expand Down Expand Up @@ -283,6 +283,42 @@
]
}
},
"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
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
d91050a9e05f939a2f68471286ea27365e4cf08f5464086ef11090c8015900ce catalog.json
19 changes: 19 additions & 0 deletions docs/guides/choosing-models.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,25 @@ video frames, runtime libraries, and other applications consume more memory.

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
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
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
`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
than run.

### Apple Silicon

| Model | Download | Best for |
Expand Down
60 changes: 57 additions & 3 deletions internal/app/app.go
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@ import (
"bufio"
"bytes"
"context"
"crypto/sha256"
"encoding/hex"
"encoding/json"
"errors"
"flag"
Expand Down Expand Up @@ -262,6 +264,9 @@ func pullResolvedWithContext(
}
path := filepath.Join(dir, resolved.Filename)
if _, err := os.Stat(path); err == nil && !force {
if err := verifyModelArtifact(path, resolved); err != nil {
return config.Model{}, fmt.Errorf("cached %s is invalid: %w; run `tapioca pull %s --force` to replace it", resolved.Name, err, resolved.Name)
}
reportPull(report, PullProgress{
Stage: "complete", Message: fmt.Sprintf("%s already exists at %s", resolved.Name, path),
Path: path,
Expand All @@ -282,6 +287,10 @@ func pullResolvedWithContext(
if err := downloadWithContext(ctx, resolved.URL, partial, report); err != nil {
return config.Model{}, err
}
if err := verifyModelArtifact(partial, resolved); err != nil {
_ = os.Remove(partial)
return config.Model{}, fmt.Errorf("downloaded %s failed integrity verification: %w", resolved.Name, err)
}
if err := os.Rename(partial, path); err != nil {
return config.Model{}, err
}
Expand All @@ -292,6 +301,35 @@ func pullResolvedWithContext(
return modelFromResolved(resolved, path), nil
}

func verifyModelArtifact(path string, resolved catalog.Resolved) error {
if resolved.ByteSize == 0 && resolved.SHA256 == "" {
return nil
}
file, err := os.Open(path)
if err != nil {
return err
}
defer file.Close()
info, err := file.Stat()
if err != nil {
return err
}
if resolved.ByteSize > 0 && info.Size() != resolved.ByteSize {
return fmt.Errorf("size %d does not match expected %d bytes", info.Size(), resolved.ByteSize)
}
if resolved.SHA256 != "" {
hash := sha256.New()
if _, err := io.Copy(hash, file); err != nil {
return err
}
actual := hex.EncodeToString(hash.Sum(nil))
if actual != resolved.SHA256 {
return fmt.Errorf("SHA-256 %s does not match expected %s", actual, resolved.SHA256)
}
}
return nil
}

func modelFromResolved(resolved catalog.Resolved, path string) config.Model {
return config.Model{
Name: resolved.Name, Repo: resolved.Repo, Filename: resolved.Filename, Path: path,
Expand Down Expand Up @@ -400,6 +438,14 @@ type serveOptions struct {
verbose bool
}

func defaultContextSize(ref string) int {
resolved, err := catalog.Resolve(ref)
if err == nil && resolved.Context > 0 {
return resolved.Context
}
return 65536
}

func serve(args []string) error {
opts, model, err := parseServe(args)
if err != nil {
Expand All @@ -420,7 +466,7 @@ func parseServe(args []string) (serveOptions, config.Model, error) {
fs.StringVar(&opts.host, "host", "127.0.0.1", "listen host")
fs.IntVar(&opts.port, "port", 11435, "Tapioca API port")
fs.IntVar(&opts.upstreamPort, "upstream-port", 11436, "private llama-server port")
fs.IntVar(&opts.context, "context", 65536, "context window")
fs.IntVar(&opts.context, "context", defaultContextSize(ref), "context window")
fs.StringVar(&opts.llamaServer, "llama-server", "", "path to llama-server")
fs.BoolVar(&opts.verbose, "verbose", false, "show llama.cpp and HTTP request logs")
if err := fs.Parse(args[1:]); err != nil {
Expand Down Expand Up @@ -451,7 +497,7 @@ func run(args []string) error {
ref := args[0]
fs := flag.NewFlagSet("run", flag.ContinueOnError)
port := fs.Int("port", 11435, "Tapioca API port")
contextSize := fs.Int("context", 65536, "context window")
contextSize := fs.Int("context", defaultContextSize(ref), "context window")
llamaServer := fs.String("llama-server", "", "path to llama-server")
verbose := fs.Bool("verbose", false, "show llama.cpp and HTTP request logs")
showThinking := fs.Bool("show-thinking", true, "show the model's reasoning before its answer")
Expand Down Expand Up @@ -655,6 +701,11 @@ func ensureModel(ref string) (config.Model, error) {
if model, ok := registry.Find(ref); ok {
registered = true
if _, err := os.Stat(model.Path); err == nil {
if resolved, err := catalog.Resolve(model.Name); err == nil {
if err := verifyModelArtifact(model.Path, resolved); err != nil {
return config.Model{}, fmt.Errorf("installed %s failed integrity verification: %w; run `tapioca pull %s --force`", model.Name, err, model.Name)
}
}
return model, nil
}
fmt.Printf("%s is registered but unavailable; pulling it again\n", model.Name)
Expand All @@ -676,6 +727,9 @@ func ensureResolvedModel(resolved catalog.Resolved) (config.Model, error) {
}
if model, ok := registry.Find(resolved.Name); ok {
if _, err := os.Stat(model.Path); err == nil {
if err := verifyModelArtifact(model.Path, resolved); err != nil {
return config.Model{}, fmt.Errorf("installed %s failed integrity verification: %w; run `tapioca pull %s --force`", model.Name, err, model.Name)
}
return model, nil
}
fmt.Printf("%s is registered but unavailable; pulling it again\n", model.Name)
Expand Down Expand Up @@ -717,7 +771,7 @@ func launch(args []string) error {
options, clientArgs := splitClientArgs(args[2:])
fs := flag.NewFlagSet("launch", flag.ContinueOnError)
port := fs.Int("port", 11435, "Tapioca API port")
contextSize := fs.Int("context", 65536, "context window")
contextSize := fs.Int("context", defaultContextSize(ref), "context window")
llamaServer := fs.String("llama-server", "", "path to llama-server")
verbose := fs.Bool("verbose", false, "show llama.cpp and HTTP request logs")
if err := fs.Parse(options); err != nil {
Expand Down
120 changes: 120 additions & 0 deletions internal/app/model_integrity_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,120 @@
package app

import (
"context"
"crypto/sha256"
"encoding/hex"
"net/http"
"net/http/httptest"
"os"
"path/filepath"
"strings"
"sync/atomic"
"testing"

"github.com/carlos/tapioca/internal/catalog"
"github.com/carlos/tapioca/internal/config"
)

func TestVerifyModelArtifact(t *testing.T) {
path := filepath.Join(t.TempDir(), "model.gguf")
data := []byte("small test artifact")
if err := os.WriteFile(path, data, 0o600); err != nil {
t.Fatal(err)
}
digest := sha256.Sum256(data)
model := catalog.Resolved{ByteSize: int64(len(data)), SHA256: hex.EncodeToString(digest[:])}
if err := verifyModelArtifact(path, model); err != nil {
t.Fatalf("valid artifact: %v", err)
}
model.ByteSize++
if err := verifyModelArtifact(path, model); err == nil || !strings.Contains(err.Error(), "size") {
t.Fatalf("expected size rejection, got %v", err)
}
model.ByteSize--
model.SHA256 = strings.Repeat("0", 64)
if err := verifyModelArtifact(path, model); err == nil || !strings.Contains(err.Error(), "SHA-256") {
t.Fatalf("expected checksum rejection, got %v", err)
}
}

func TestCompactModelsDefaultToBoundedContext(t *testing.T) {
for _, ref := range []string{"granite-4.2-3b", "minicpm5-2b"} {
if got := defaultContextSize(ref); got != 8192 {
t.Fatalf("%s context = %d, want 8192", ref, got)
}
}
if got := defaultContextSize("glm-4.7-flash"); got != 65536 {
t.Fatalf("existing default context = %d, want 65536", got)
}
}

func TestPullPinnedArtifactAndOfflineCache(t *testing.T) {
t.Setenv("TAPIOCA_HOME", t.TempDir())
data := []byte("small pinned model")
digest := sha256.Sum256(data)
var requests atomic.Int32
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
requests.Add(1)
_, _ = w.Write(data)
}))
defer server.Close()
model := catalog.Resolved{
Name: "pinned-test:q4", Repo: "test/repo", Filename: "test.gguf",
URL: server.URL, SHA256: hex.EncodeToString(digest[:]), ByteSize: int64(len(data)),
}
got, err := pullResolvedWithContext(context.Background(), model, false, nil)
if err != nil {
t.Fatal(err)
}
if got.Path == "" || requests.Load() != 1 {
t.Fatalf("fresh download: path=%q requests=%d", got.Path, requests.Load())
}
server.Close()
if _, err := pullResolvedWithContext(context.Background(), model, false, nil); err != nil {
t.Fatalf("offline cache reuse: %v", err)
}
}

func TestPullRejectsCorruptPinnedArtifact(t *testing.T) {
home := t.TempDir()
t.Setenv("TAPIOCA_HOME", home)
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
_, _ = w.Write([]byte("wrong bytes"))
}))
defer server.Close()
model := catalog.Resolved{
Name: "pinned-test:q4", Repo: "test/repo", Filename: "test.gguf",
URL: server.URL, SHA256: strings.Repeat("0", 64), ByteSize: int64(len("wrong bytes")),
}
if _, err := pullResolvedWithContext(context.Background(), model, false, nil); err == nil ||
!strings.Contains(err.Error(), "integrity verification") {
t.Fatalf("expected integrity error, got %v", err)
}
path := filepath.Join(home, "models", "pinned-test-q4", "test.gguf")
if _, err := os.Stat(path); !os.IsNotExist(err) {
t.Fatalf("corrupt download was installed: %v", err)
}
if _, err := os.Stat(path + ".partial"); !os.IsNotExist(err) {
t.Fatalf("corrupt partial was retained: %v", err)
}
}

func TestInstalledPinnedModelRejectsCorruptionBeforeRun(t *testing.T) {
home := t.TempDir()
t.Setenv("TAPIOCA_HOME", home)
path := filepath.Join(home, "corrupt.gguf")
if err := os.WriteFile(path, []byte("not a pinned artifact"), 0o600); err != nil {
t.Fatal(err)
}
name := "granite-4.2-3b:q4_k_m"
registry := config.Registry{Models: map[string]config.Model{
name: {Name: name, Path: path, Kind: "text"},
}}
if err := registry.Save(); err != nil {
t.Fatal(err)
}
if _, err := ensureModel(name); err == nil || !strings.Contains(err.Error(), "integrity verification") {
t.Fatalf("expected integrity rejection before use, got %v", err)
}
}
Loading