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 ```