diff --git a/catalog/catalog.json b/catalog/catalog.json index b86a786..b8ad9e5 100644 --- a/catalog/catalog.json +++ b/catalog/catalog.json @@ -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", @@ -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", diff --git a/catalog/catalog.json.sha256 b/catalog/catalog.json.sha256 index 15d6687..eb9f57b 100644 --- a/catalog/catalog.json.sha256 +++ b/catalog/catalog.json.sha256 @@ -1 +1 @@ -932e371becaa8fb7db7e8cbf10235a34e7210b1948d9b2be9ff9f330dc76b752 catalog.json +d91050a9e05f939a2f68471286ea27365e4cf08f5464086ef11090c8015900ce catalog.json diff --git a/docs/guides/choosing-models.md b/docs/guides/choosing-models.md index 49f8f9b..7547f57 100644 --- a/docs/guides/choosing-models.md +++ b/docs/guides/choosing-models.md @@ -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 | diff --git a/internal/app/app.go b/internal/app/app.go index f37547f..5349e9a 100644 --- a/internal/app/app.go +++ b/internal/app/app.go @@ -4,6 +4,8 @@ import ( "bufio" "bytes" "context" + "crypto/sha256" + "encoding/hex" "encoding/json" "errors" "flag" @@ -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, @@ -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 } @@ -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, @@ -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 { @@ -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 { @@ -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") @@ -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) @@ -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) @@ -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 { diff --git a/internal/app/model_integrity_test.go b/internal/app/model_integrity_test.go new file mode 100644 index 0000000..6f182ad --- /dev/null +++ b/internal/app/model_integrity_test.go @@ -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) + } +} diff --git a/internal/catalog/catalog.go b/internal/catalog/catalog.go index 6c35946..d653b98 100644 --- a/internal/catalog/catalog.go +++ b/internal/catalog/catalog.go @@ -22,6 +22,10 @@ type Model struct { Name string `json:"name"` Repo string `json:"repo,omitempty"` Files map[string]string `json:"files"` + Revisions map[string]string `json:"revisions,omitempty"` + Checksums map[string]string `json:"checksums,omitempty"` + ByteSizes map[string]int64 `json:"byte_sizes,omitempty"` + Contexts map[string]int `json:"contexts,omitempty"` Template string `json:"template,omitempty"` Kind string `json:"kind,omitempty"` Backends map[string]string `json:"backends,omitempty"` @@ -76,6 +80,8 @@ var cachedOverridePath string var safeName = regexp.MustCompile(`^[a-z0-9][a-z0-9._-]*$`) var safeRepoPart = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9._-]*$`) +var sha256Hex = regexp.MustCompile(`^[a-f0-9]{64}$`) +var revisionHex = regexp.MustCompile(`^[a-f0-9]{40}$`) func SetOverridePathForTest(path string) func() { previous := cachedOverridePath @@ -306,7 +312,8 @@ func validateModel(name string, model Model) error { for label, values := range map[string]map[string]string{ "backend": model.Backends, "repository": model.Repos, "size": model.Sizes, "memory": model.Memory, "GPU": model.GPUs, "language": model.Languages, - "feature": model.Features, + "feature": model.Features, "revision": model.Revisions, + "checksum": model.Checksums, } { for variant := range values { if _, ok := model.Files[variant]; !ok { @@ -314,6 +321,35 @@ func validateModel(name string, model Model) error { } } } + for variant, revision := range model.Revisions { + if !revisionHex.MatchString(revision) || model.Files[variant] == "" { + return fmt.Errorf("catalog model %s has invalid revision for %s", name, variant) + } + } + for variant, checksum := range model.Checksums { + if !sha256Hex.MatchString(checksum) || model.Files[variant] == "" { + return fmt.Errorf("catalog model %s has invalid checksum for %s", name, variant) + } + } + for variant, size := range model.ByteSizes { + if _, ok := model.Files[variant]; !ok || size <= 0 || model.Files[variant] == "" { + return fmt.Errorf("catalog model %s has invalid byte size for %s", name, variant) + } + } + for variant, contextSize := range model.Contexts { + if _, ok := model.Files[variant]; !ok || contextSize < 512 || contextSize > 1048576 { + return fmt.Errorf("catalog model %s has invalid context size for %s", name, variant) + } + } + for variant := range model.Files { + hasRevision := model.Revisions[variant] != "" + hasChecksum := model.Checksums[variant] != "" + hasByteSize := model.ByteSizes[variant] > 0 + if (hasRevision || hasChecksum || hasByteSize) && + !(hasRevision && hasChecksum && hasByteSize) { + return fmt.Errorf("catalog model %s requires revision, checksum, and byte size together for %s", name, variant) + } + } for variant, artifacts := range model.Artifacts { if _, ok := model.Files[variant]; !ok { return fmt.Errorf("catalog model %s has artifacts for unknown variant %q", name, variant) @@ -603,6 +639,54 @@ var builtInModels = map[string]Model{ "q5_k_m": "~2.7 GiB", }, }, + "granite-4.2-3b": { + Name: "granite-4.2-3b", + Repo: "ibm-granite/granite-4.2-3b-GGUF", + Kind: "text", + Default: "q4_k_m", + Files: map[string]string{ + "q4_k_m": "granite-4.2-3b-Q4_K_M.gguf", + }, + Revisions: map[string]string{ + "q4_k_m": "c40945d71cd90f249a56985e8155551a9188dc30", + }, + Checksums: map[string]string{ + "q4_k_m": "e0406663965846ae22a403456eb826ccce5f450840491f71952f18a7cb78e7d5", + }, + ByteSizes: map[string]int64{"q4_k_m": 2244011552}, + Contexts: map[string]int{"q4_k_m": 8192}, + Sizes: map[string]string{"q4_k_m": "~2.09 GiB"}, + Memory: map[string]string{"q4_k_m": "8 GiB minimum; 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": "12 languages"}, + 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", + }, + "minicpm5-2b": { + Name: "minicpm5-2b", + Repo: "openbmb/MiniCPM5-2B-GGUF", + Kind: "text", + Default: "q4_k_m", + Files: map[string]string{ + "q4_k_m": "MiniCPM5-2B-Q4_K_M.gguf", + }, + Revisions: map[string]string{ + "q4_k_m": "2079a22f3beaa4e306449978533478fe0522f4b3", + }, + Checksums: map[string]string{ + "q4_k_m": "ec2d5801640099e97d8d7e8003ad4d81f336e757811f03a26173dddf386602fd", + }, + ByteSizes: map[string]int64{"q4_k_m": 1561318368}, + Contexts: map[string]int{"q4_k_m": 8192}, + Sizes: map[string]string{"q4_k_m": "~1.45 GiB"}, + Memory: map[string]string{"q4_k_m": "8 GiB minimum; 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://www.apache.org/licenses/LICENSE-2.0", + }, "gemma3": { Name: "gemma3", Repo: "ggml-org/gemma-3-4b-it-GGUF", @@ -905,6 +989,9 @@ type Resolved struct { Repo string Filename string URL string + SHA256 string + ByteSize int64 + Context int Kind string Backend string Width int @@ -995,7 +1082,11 @@ func ResolveForPlatform(ref, goos, goarch string) (Resolved, error) { } url := "" if filename != "" { - url = "https://huggingface.co/" + repo + "/resolve/main/" + filename + revision := m.Revisions[strings.ToLower(tag)] + if revision == "" { + revision = "main" + } + url = "https://huggingface.co/" + repo + "/resolve/" + revision + "/" + filename } backend := m.Backends[strings.ToLower(tag)] platform := "Windows, macOS, Linux" @@ -1025,6 +1116,9 @@ func ResolveForPlatform(ref, goos, goarch string) (Resolved, error) { Repo: repo, Filename: filename, URL: url, + SHA256: m.Checksums[strings.ToLower(tag)], + ByteSize: m.ByteSizes[strings.ToLower(tag)], + Context: m.Contexts[strings.ToLower(tag)], Kind: m.Kind, Backend: backend, Width: m.Width, diff --git a/internal/catalog/catalog_test.go b/internal/catalog/catalog_test.go index 43a8777..899980d 100644 --- a/internal/catalog/catalog_test.go +++ b/internal/catalog/catalog_test.go @@ -1,6 +1,52 @@ package catalog -import "testing" +import ( + "strings" + "testing" +) + +func TestPinnedArtifactMetadataValidation(t *testing.T) { + model := builtInModels["granite-4.2-3b"] + if err := validateModel(model.Name, model); err != nil { + t.Fatal(err) + } + model.Checksums = map[string]string{"q4_k_m": strings.Repeat("x", 64)} + if err := validateModel(model.Name, model); err == nil { + t.Fatal("invalid checksum was accepted") + } + model = builtInModels["granite-4.2-3b"] + model.Revisions = map[string]string{"q4_k_m": "main"} + if err := validateModel(model.Name, model); err == nil { + t.Fatal("unpinned revision was accepted") + } + model = builtInModels["granite-4.2-3b"] + model.Checksums = nil + if err := validateModel(model.Name, model); err == nil { + t.Fatal("revision without checksum was accepted") + } +} + +func TestResolvePinnedCompactModels(t *testing.T) { + for _, tc := range []struct { + ref, repo, file, revision, checksum string + bytes int64 + }{ + {"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}, + } { + t.Run(tc.ref, func(t *testing.T) { + got, err := ResolveFor(tc.ref, "darwin") + if err != nil { + t.Fatal(err) + } + if got.Kind != "text" || got.Repo != tc.repo || got.Filename != tc.file || got.Context != 8192 || + got.SHA256 != tc.checksum || got.ByteSize != tc.bytes || + got.URL != "https://huggingface.co/"+tc.repo+"/resolve/"+tc.revision+"/"+tc.file { + t.Fatalf("unexpected pinned model: %#v", got) + } + }) + } +} func TestResolveGLM(t *testing.T) { got, err := Resolve("glm-4.7-flash:q8_0")