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
5 changes: 5 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/interfaces.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down
16 changes: 16 additions & 0 deletions internal/cli/commands.go
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
137 changes: 137 additions & 0 deletions internal/cli/fit.go
Original file line number Diff line number Diff line change
@@ -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
}
65 changes: 65 additions & 0 deletions internal/cli/fit_test.go
Original file line number Diff line number Diff line change
@@ -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)
}
}
1 change: 1 addition & 0 deletions internal/skill/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
```

Expand Down
Loading