From 0664338977bf11bf85f36f428fddc0d5ef3819f6 Mon Sep 17 00:00:00 2001 From: T-Crypt <132922589+T-Crypt@users.noreply.github.com> Date: Fri, 13 Nov 2026 09:36:36 -0700 Subject: [PATCH] feat(fit): berth fit NAME shows where a request would run and why berth fit ranks what it takes to bring an engine, or every engine that serves a model, up right now: resume from RAM, a free card, a drain of the holder, or blocked by a VM, a cordon or a pinned lease. Each candidate names its reason, its weights' tier and the gateway's measured switch time from that tier, or unknown. It reads the same fit.Rank the gateway picks through, so its answer is the gateway's. --explain lists every candidate. --- CHANGELOG.md | 5 ++ docs/interfaces.md | 2 +- internal/cli/commands.go | 16 +++++ internal/cli/fit.go | 137 +++++++++++++++++++++++++++++++++++++++ internal/cli/fit_test.go | 65 +++++++++++++++++++ internal/skill/SKILL.md | 1 + 6 files changed, 225 insertions(+), 1 deletion(-) create mode 100644 internal/cli/fit.go create mode 100644 internal/cli/fit_test.go diff --git a/CHANGELOG.md b/CHANGELOG.md index fd372db..e6bcd48 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -50,6 +50,11 @@ has a matching GitHub release whose body comes from its section below. `berth run --as` name. Without berthd it prints the declared terms. The status JSON's `footprints` now carry each engine's `hot_peak_vram_bytes`, `ram_peak_bytes` and `parked_ram_bytes`. A llama-swap model whose last-run figure sits on its group's entry is now listed under its own name too. +- `berth fit NAME` says where a request for an engine or a model would run right now and what the start costs. It + ranks each candidate by path: a resume from RAM, a free card, a drain of the holder, or blocked by a VM, a cordon + or a pinned lease. Each candidate names its reason, the tier its weights sit in, and the switch time the gateway + measured from that tier, or unknown. For a model, every engine that serves it is ranked the way the gateway picks + one. `--explain` lists every candidate. It is read only, and the gateway now picks through the same ranking. - `berth wire llama-swap` names each llama-swap group where llama-swap swaps two or more wired models itself. There llama-swap unloads the old model before Berth sees the request, so `min_turn`, the engine ranking and the juggle guard never apply between them. The JSON carries the groups as `swapping`. The llama-swap section of diff --git a/docs/interfaces.md b/docs/interfaces.md index 625c4ea..25a5445 100644 --- a/docs/interfaces.md +++ b/docs/interfaces.md @@ -2,7 +2,7 @@ - **CLI:** one command tree with one output contract. `berth status`, `berth events -f`, `berth run`, `berth hold`, `berth stop`, `berth cordon|uncordon`, `berth notify`, `berth claims`, `berth pull`, `berth verify`, `berth models`, `berth gateway`, - `berth wire llama-swap`, `berth engine check`, `berth contract ENGINE`, `berth config check`, `berth config show`, + `berth wire llama-swap`, `berth engine check`, `berth contract ENGINE`, `berth fit NAME`, `berth config check`, `berth config show`, `berth export`, `berth key`, `berth skill install|show`, `berth update`, `berth version`, and for the node itself `berth daemon`, `berth harbor`, `berth service install|uninstall|status`, `berth reclaim`, `berth resume`, `berth prefetch`, `berth storage`, `berth civitai search|versions` diff --git a/internal/cli/commands.go b/internal/cli/commands.go index 338880c..a1b756a 100644 --- a/internal/cli/commands.go +++ b/internal/cli/commands.go @@ -223,6 +223,22 @@ notify-send, so any desktop or notification daemon shows it. On Windows it is a tray icon whose notifications are Windows' own toasts; a click opens the harbor.`, Run: runNotify, }, + { + Name: "fit", + Summary: "where a request for an engine or model would run now, and what the start costs", + Args: "NAME [--explain] [--config PATH] [--costs PATH] [--socket P] [--format F]", + Help: `Rank what it takes to bring NAME up right now, cheapest first: a resume from +RAM, a free card, a drain of what holds the card, or a wait while a VM, a +cordon or a pinned lease (a game, a hold, a training) keeps it. NAME is an +engine, or a model that engines list in serves; for a model every engine that +serves it is ranked in berth.toml's order, the way the gateway picks one. + +Each candidate names its reason, the tier its weights sit in, and the start +time the gateway measured from that tier, or unknown when it has none. +--explain lists every candidate. Read only: Fit advises, berthd decides.`, + Formats: []Format{FormatHuman, FormatJSON, FormatYAML}, + Run: runFit, + }, { Name: "export", Summary: "dump the harbor's stored history: requests and samples", diff --git a/internal/cli/fit.go b/internal/cli/fit.go new file mode 100644 index 0000000..ae79793 --- /dev/null +++ b/internal/cli/fit.go @@ -0,0 +1,137 @@ +// Copyright 2026 Trevin Tindall (T-Crypt) +// SPDX-License-Identifier: Apache-2.0 + +package cli + +import ( + "fmt" + "slices" + "strings" + "text/tabwriter" + + "github.com/T-Crypt/berth/internal/config" + "github.com/T-Crypt/berth/internal/contract" + "github.com/T-Crypt/berth/internal/fit" + "github.com/T-Crypt/berth/internal/proto" + "github.com/T-Crypt/berth/internal/swapcost" +) + +// fitDoc is berth fit's answer: what Fit would pick for the name, and every +// candidate it ranked, cheapest first. +type fitDoc struct { + Name string `json:"name" yaml:"name"` + Pick fit.Candidate `json:"pick" yaml:"pick"` + Candidates []fit.Candidate `json:"candidates" yaml:"candidates"` +} + +type fitView struct { + doc fitDoc + explain bool + offline string +} + +func (v fitView) Data() any { return v.doc } + +func (v fitView) Human(c *Context, ok bool) error { + p := v.doc.Pick + if p.Engine == v.doc.Name { + c.Printf("%s: %s, %s\n", p.Engine, p.Path, p.Why) + } else { + c.Printf("%s: %s, %s, %s\n", v.doc.Name, p.Engine, p.Path, p.Why) + } + c.Bullet("start %s", startText(p)) + if v.offline != "" { + c.Bullet("berthd unreachable (%s): every card reads as out of reach", v.offline) + } + if !v.explain && len(v.doc.Candidates) < 2 { + return nil + } + tw := tabwriter.NewWriter(c.Out, 0, 4, 2, ' ', 0) + fmt.Fprint(tw, "\nENGINE\tPATH\tTIER\tSTART\tWHY\n") + for _, k := range v.doc.Candidates { + fmt.Fprintf(tw, "%s\t%s\t%s\t%s\t%s\n", k.Engine, k.Path, k.Tier, startText(k), k.Why) + } + return tw.Flush() +} + +// startText is a candidate's start for people: the time and where it came from. +func startText(k fit.Candidate) string { + s := k.Start + if s.Source == contract.Unknown { + return "unknown (" + s.Why + ")" + } + t := fmt.Sprintf("%.1f s %s", s.Seconds, s.Source) + if s.Why != "" { + t += " (" + s.Why + ")" + } + return t +} + +func runFit(c *Context) int { + fs := c.FlagSet() + sock := fs.String("socket", defaultSocket(), "berthd socket ($BERTH_SOCKET)") + cfgPath := fs.String("config", config.DefaultPath(), "berth.toml ($BERTH_CONFIG): the engines and what they serve") + costs := fs.String("costs", defaultStateFile("swapcost.json"), "the gateway's measured switch times") + explain := fs.Bool("explain", false, "list every candidate, cheapest first, with its path and reason") + if code, done := c.ParseInterspersed(fs); done { + return code + } + if len(c.Args) != 1 { + return c.fail(Systemf("berth fit takes one engine or model name"). + WithHint("for example: berth fit comfyui, or berth fit qwen3-30b")) + } + name := c.Args[0] + + cfg, err := config.Load(*cfgPath) + if err != nil { + return c.fail(Systemf("%s: %v", *cfgPath, err).WithHint("run berth config check")) + } + st, offline := contractStatus(*sock) + cands := fitCandidates(cfg, name) + if len(cands) == 0 && st != nil && slices.ContainsFunc(st.Engines, func(e proto.Engine) bool { return e.Name == name }) { + cands = []*config.Engine{{Name: name}} + } + if len(cands) == 0 { + e := Failf("no engine named %q, and none serves it", name) + var known []string + for _, en := range cfg.Engine { + known = append(known, en.Name) + } + if st != nil { + for _, en := range st.Engines { + if !slices.Contains(known, en.Name) { + known = append(known, en.Name) + } + } + } + if len(known) > 0 { + e.WithHint("engines: %s", strings.Join(known, ", ")) + } + return c.fail(e) + } + + book, err := swapcost.NewBook(*costs) + if err != nil { + book = nil + } + ranked := fit.Rank(st, cands, book) + return c.Write(fitView{doc: fitDoc{Name: name, Pick: ranked[0], Candidates: ranked}, explain: *explain, offline: offline}, nil) +} + +// fitCandidates is the engines a name means: the [[engine]] of that name, else +// every engine whose serves lists it, in berth.toml order, which is what the +// gateway ranks for a request naming that model. +func fitCandidates(cfg config.Config, name string) []*config.Engine { + for i := range cfg.Engine { + if cfg.Engine[i].Name == name { + return []*config.Engine{&cfg.Engine[i]} + } + } + var out []*config.Engine + for i := range cfg.Engine { + if slices.Contains(cfg.Engine[i].Serves, name) { + out = append(out, &cfg.Engine[i]) + } + } + return out +} diff --git a/internal/cli/fit_test.go b/internal/cli/fit_test.go new file mode 100644 index 0000000..84f0398 --- /dev/null +++ b/internal/cli/fit_test.go @@ -0,0 +1,65 @@ +// Copyright 2026 Trevin Tindall (T-Crypt) +// SPDX-License-Identifier: Apache-2.0 + +package cli + +import ( + "encoding/json" + "os" + "path/filepath" + "strings" + "testing" +) + +// berth fit for a model ranks every engine that serves it in berth.toml's +// order, against a real berthd; without berthd every card is out of reach; +// a name nothing serves is refused with the engines that exist. +func TestFitAgainstADaemon(t *testing.T) { + home := isolate(t) + sock := startDaemon(t) + cfg := filepath.Join(home, "berth.toml") + toml := "[[engine]]\nname = \"a\"\ntype = \"llamacpp\"\nurl = \"http://127.0.0.1:8080\"\nserves = [\"m\"]\ngpu = \"gpu1\"\n" + + "[[engine]]\nname = \"b\"\ntype = \"llamacpp\"\nurl = \"http://127.0.0.1:8081\"\nserves = [\"m\"]\ngpu = \"gpu0\"\n" + if err := os.WriteFile(cfg, []byte(toml), 0o600); err != nil { + t.Fatal(err) + } + + code, out, errOut := runCLI(t, "fit", "m", "--config", cfg, "--socket", sock, "--format", "json") + if code != 0 { + t.Fatalf("exit %d: %s", code, errOut) + } + var doc struct { + Pick struct { + Engine, Path, Why string + } `json:"pick"` + Candidates []struct { + Engine, Path string + Start struct{ Source string } + } `json:"candidates"` + } + if err := json.Unmarshal([]byte(out), &doc); err != nil { + t.Fatalf("%v: %s", err, out) + } + // a comes first in berth.toml, but its card is not one berthd reports: + // b on the free card wins, and a waits. + if doc.Pick.Engine != "b" || doc.Pick.Path != "free" || doc.Pick.Why != "the card is free" || + len(doc.Candidates) != 2 || doc.Candidates[1].Engine != "a" || doc.Candidates[1].Path != "blocked" || + doc.Candidates[0].Start.Source != "unknown" { + t.Fatalf("fit = %s", out) + } + + code, out, _ = runCLI(t, "fit", "m", "--config", cfg, "--socket", sock) + if code != 0 || !strings.HasPrefix(out, "m: b, free, the card is free\n") || !strings.Contains(out, "ENGINE") { + t.Fatalf("human (exit %d):\n%s", code, out) + } + + code, out, _ = runCLI(t, "fit", "a", "--config", cfg, "--socket", filepath.Join(home, "none.sock")) + if code != 0 || !strings.HasPrefix(out, "a: blocked, berthd did not report the card\n") || !strings.Contains(out, "berthd unreachable") { + t.Fatalf("offline (exit %d):\n%s", code, out) + } + + code, _, errOut = runCLI(t, "fit", "nope", "--config", cfg, "--socket", sock) + if code == 0 || !strings.Contains(errOut, `no engine named "nope", and none serves it`) || !strings.Contains(errOut, "engines: a, b") { + t.Fatalf("unknown (exit %d): %s", code, errOut) + } +} diff --git a/internal/skill/SKILL.md b/internal/skill/SKILL.md index 36de244..f764be6 100644 --- a/internal/skill/SKILL.md +++ b/internal/skill/SKILL.md @@ -19,6 +19,7 @@ berth status --format json | jq '.leases, .waiting, .squatters' berth claims # games and apps Berth holds the card for, or names berth engine check -v # what every engine reports right now berth contract ENGINE # one engine's VRAM, RAM, turn and switch times, each declared, measured or unknown +berth fit MODEL --explain # where a request would run now (resume, free, drain, blocked) and why berth events -f # live: grants, drains, refusals, stowaways ```