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
7 changes: 7 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,13 @@ has a matching GitHub release whose body comes from its section below.
`window`, with its hours, whether they are open, and how long until they close or open. An engine shows before its
window opens, and a `berth run --window` lease shows its own hours. The status JSON carries the same rows as
`schedules`, and each lease carries its `window`.
- `berth contract ENGINE` prints one engine's terms in one place: its priority, the VRAM a lease asks for, the last
run's measured peak, the RAM it needs and holds parked, its minimum turn and window, and how long a switch to it
takes from each tier. Each number says whether berth.toml declares it, Berth's default applies, Berth measured
it, or nothing is known. ENGINE can be an `[[engine]]` name, a discovered engine, or a llama-swap model's
`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 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 config check`, `berth config show`,
`berth wire llama-swap`, `berth engine check`, `berth contract ENGINE`, `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
11 changes: 7 additions & 4 deletions internal/broker/footprint.go
Original file line number Diff line number Diff line change
Expand Up @@ -132,15 +132,18 @@ func sizeHuman(n uint64) string {
return fmt.Sprintf("%d MiB", n/gpu.MiB)
}

// footprintStatus is the table as the status reply carries it: the last
// run's peak per engine, sorted by name. b.mu must be held.
// footprintStatus is the table as the status reply carries it: per engine
// key, the last run's peak and the peaks learn_size and RAM figures read,
// sorted by name. A llama-swap model's entry may carry only its own peaks;
// the last-run figure sits on its group's. b.mu must be held.
func (b *Broker) footprintStatus() []proto.EngineFootprint {
out := []proto.EngineFootprint{}
for k, f := range b.footprints {
if f == nil || f.Last == 0 {
if f == nil || f.Last == 0 && f.HotPeak == 0 && f.RAMPeak == 0 && f.ParkedRAM == 0 {
continue
}
out = append(out, proto.EngineFootprint{Engine: k, Bytes: f.Last, Runs: f.Runs, At: f.At})
out = append(out, proto.EngineFootprint{Engine: k, Bytes: f.Last, Runs: f.Runs, At: f.At,
HotPeakBytes: f.HotPeak, RAMPeakBytes: f.RAMPeak, ParkedRAMBytes: f.ParkedRAM})
}
sort.Slice(out, func(i, j int) bool { return out[i].Engine < out[j].Engine })
return out
Expand Down
26 changes: 26 additions & 0 deletions internal/broker/footprint_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -208,3 +208,29 @@ func TestFootprintFoldsAtTheFreeNotTheRelease(t *testing.T) {
t.Fatalf("Footprint(llama) = %d, %v after the free; want %d, true", last, ok, 9*GiB)
}
}

// A llama-swap model's own peak sits on its name's entry, its last run on the
// group's. The status reply carries both, so a reader of the model's name
// (berth contract, learn_size) finds the peak the broker sizes it from.
func TestFootprintStatusCarriesAModelsOwnPeak(t *testing.T) {
b, c, _ := setup(t, procs.Map{101: 100})
l := must(t, acquire(b, Request{Engine: "dirk", Group: "llama-swap", Priority: Foreground}))
l.Attach(100)
c.set(gpu.Proc{PID: 101, Name: "llama-server", Used: 12 * GiB})
b.Tick(context.Background())
l.Release()
c.set()
b.Tick(context.Background())

got := map[string]proto.EngineFootprint{}
for _, f := range b.Status().Footprints {
f.At = time.Time{}
got[f.Engine] = f
}
if f := got["dirk"]; f != (proto.EngineFootprint{Engine: "dirk", HotPeakBytes: 12 * GiB}) {
t.Fatalf("dirk's entry = %+v, want its own 12 GiB peak", f)
}
if f := got["llama-swap"]; f.Bytes != 12*GiB || f.Runs != 1 {
t.Fatalf("llama-swap's entry = %+v, want the last run's 12 GiB", f)
}
}
16 changes: 16 additions & 0 deletions internal/cli/commands.go
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,22 @@ materialised, and the environment that decides which file that is.
},
},
},
{
Name: "contract",
Summary: "one engine's terms: what berth.toml declares and what Berth measured",
Args: "ENGINE [--config PATH] [--costs PATH] [--socket P] [--format F]",
Help: `Print one engine's terms in one place: its priority, the VRAM a lease asks for,
the last run's measured peak, the RAM it needs and holds parked, its minimum
turn and window, and how long a switch to it takes from each tier. Every
number says where it came from: declared in berth.toml, Berth's default,
measured on the card or by the gateway, or unknown.

ENGINE is an [[engine]] name, an engine berthd discovered, or a name Berth
measured leases under (a llama-swap model's berth run --as). Read only: it
changes nothing, and without berthd it prints the declared terms.`,
Formats: []Format{FormatHuman, FormatJSON, FormatYAML},
Run: runContract,
},
{
Name: "civitai",
Summary: "search and browse CivitAI, for finding things to pull",
Expand Down
181 changes: 181 additions & 0 deletions internal/cli/contract.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,181 @@
// Copyright 2026 Trevin Tindall (T-Crypt)
// SPDX-License-Identifier: Apache-2.0

package cli

import (
"fmt"
"sort"
"strings"
"text/tabwriter"
"time"

"github.com/T-Crypt/berth/internal/config"
"github.com/T-Crypt/berth/internal/contract"
"github.com/T-Crypt/berth/internal/proto"
"github.com/T-Crypt/berth/internal/server"
"github.com/T-Crypt/berth/internal/swapcost"
)

// contractView is one engine's contract.
type contractView struct {
c contract.Contract
offline string // why berthd gave no status, "" when it did
}

func (v contractView) Data() any { return v.c }

func (v contractView) Human(c *Context, ok bool) error {
k := v.c
where := "not in berth.toml"
if k.InConfig {
where = "in berth.toml"
}
if k.Type != "" {
where = k.Type + ", " + where
}
c.Printf("%s (%s)\n", k.Engine, where)
if v.offline != "" {
c.Bullet("berthd unreachable (%s): measured numbers are unknown", v.offline)
}
tw := tabwriter.NewWriter(c.Out, 0, 4, 2, ' ', 0)
row := func(name, value string, src contract.Source, why string) {
fmt.Fprintf(tw, " %s\t%s\t%s\t%s\n", name, value, src, why)
}
row("priority", k.Priority.Value, k.Priority.Source, "")
row("vram", contractSize(k.VRAM, "whole card"), k.VRAM.Source, k.VRAM.Why)
row("last peak", contractSize(k.LastPeak, "-"), k.LastPeak.Source, k.LastPeak.Why)
row("ram", contractSize(k.RAM, "-"), k.RAM.Source, k.RAM.Why)
row("parked ram", contractSize(k.ParkedRAM, "-"), k.ParkedRAM.Source, k.ParkedRAM.Why)
minTurn := "off"
if k.MinTurn.Seconds > 0 {
minTurn = (time.Duration(k.MinTurn.Seconds) * time.Second).String()
}
row("min turn", minTurn, k.MinTurn.Source, "")
row("window", k.Window.Value, k.Window.Source, "")
for _, s := range k.Switch {
took, why := "-", s.Took.Why
switch s.Took.Source {
case contract.Measured:
took, why = fmt.Sprintf("%.1f s", s.Took.Seconds), fmt.Sprintf("median of %d", s.Samples)
case contract.Default:
took = "0 s"
}
row("switch "+string(s.Tier), took, s.Took.Source, why)
}
return tw.Flush()
}

// contractSize is a contract size for people: MiB, or none when it carries no bytes.
func contractSize(b contract.Bytes, none string) string {
if b.Bytes == 0 {
return none
}
return server.MiB(b.Bytes)
}

func runContract(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 engine's declared terms")
costs := fs.String("costs", defaultStateFile("swapcost.json"), "the gateway's measured switch times")
if code, done := c.ParseInterspersed(fs); done {
return code
}
if len(c.Args) != 1 {
return c.fail(Systemf("berth contract takes one engine name").
WithHint("for example: berth contract comfyui"))
}
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"))
}
var entry *config.Engine
for i := range cfg.Engine {
if cfg.Engine[i].Name == name {
entry = &cfg.Engine[i]
}
}

st, offline := contractStatus(*sock)
if entry == nil && !knownTo(st, name) {
known := knownNames(cfg, st)
e := Failf("no engine named %q in berth.toml or berthd's status", name)
if len(known) > 0 {
e.WithHint("known: %s", strings.Join(known, ", "))
}
return c.fail(e)
}

book, err := swapcost.NewBook(*costs)
if err != nil {
book = nil
}
return c.Write(contractView{c: contract.Build(name, entry, st, book), offline: offline}, nil)
}

// contractStatus is berthd's status, or nil and why when it did not answer.
func contractStatus(sock string) (*proto.Status, string) {
conn, raw, err := server.Dial(sock)
if err != nil {
return nil, err.Error()
}
defer raw.Close()
if err := conn.Send(proto.Msg{Op: proto.OpStatus}); err != nil {
return nil, err.Error()
}
m, err := conn.Recv()
if err != nil {
return nil, err.Error()
}
if m.Status == nil {
return nil, "empty reply"
}
return m.Status, ""
}

// knownTo says whether berthd's status names the engine: discovered, or
// measured under its own name (a llama-swap model).
func knownTo(st *proto.Status, name string) bool {
for _, n := range statusNames(st) {
if n == name {
return true
}
}
return false
}

func statusNames(st *proto.Status) []string {
if st == nil {
return nil
}
var out []string
for _, e := range st.Engines {
out = append(out, e.Name)
}
for _, f := range st.Footprints {
out = append(out, f.Engine)
}
return out
}

func knownNames(cfg config.Config, st *proto.Status) []string {
seen := map[string]bool{}
var out []string
for _, e := range cfg.Engine {
if !seen[e.Name] {
seen[e.Name] = true
out = append(out, e.Name)
}
}
for _, n := range statusNames(st) {
if !seen[n] {
seen[n] = true
out = append(out, n)
}
}
sort.Strings(out)
return out
}
61 changes: 61 additions & 0 deletions internal/cli/contract_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
// Copyright 2026 Trevin Tindall (T-Crypt)
// SPDX-License-Identifier: Apache-2.0

package cli

import (
"encoding/json"
"os"
"path/filepath"
"strings"
"testing"
)

// Without berthd, berth contract still prints what berth.toml declares and
// marks every measured number unknown; a name nobody knows is refused with
// the names that exist.
func TestContractWithoutBerthd(t *testing.T) {
home := isolate(t)
cfg := filepath.Join(home, "berth.toml")
if err := os.WriteFile(cfg, []byte("[[engine]]\nname = \"qwen\"\ntype = \"llamacpp\"\nurl = \"http://127.0.0.1:8080\"\npriority = \"foreground\"\nneeds_mib = 14000\nmin_turn = \"5m\"\n"), 0o600); err != nil {
t.Fatal(err)
}

code, out, errOut := runCLI(t, "contract", "qwen", "--config", cfg, "--format", "json")
if code != 0 {
t.Fatalf("exit %d: %s", code, errOut)
}
var got struct {
InConfig bool `json:"in_config"`
VRAM struct {
Bytes uint64 `json:"bytes"`
Source string `json:"source"`
} `json:"vram"`
LastPeak struct {
Source string `json:"source"`
Why string `json:"why"`
} `json:"last_peak"`
MinTurn struct {
Seconds float64 `json:"seconds"`
Source string `json:"source"`
} `json:"min_turn"`
}
if err := json.Unmarshal([]byte(out), &got); err != nil {
t.Fatalf("%v: %s", err, out)
}
if !got.InConfig || got.VRAM.Bytes != 14000<<20 || got.VRAM.Source != "declared" ||
got.LastPeak.Source != "unknown" || got.LastPeak.Why != "berthd did not answer" ||
got.MinTurn.Seconds != 300 || got.MinTurn.Source != "declared" {
t.Fatalf("contract = %+v", got)
}

code, out, _ = runCLI(t, "contract", "qwen", "--config", cfg)
if code != 0 || !strings.Contains(out, "berthd unreachable") || !strings.Contains(out, "14000 MiB") {
t.Fatalf("human (exit %d):\n%s", code, out)
}

code, _, errOut = runCLI(t, "contract", "nope", "--config", cfg)
if code == 0 || !strings.Contains(errOut, `no engine named "nope"`) || !strings.Contains(errOut, "known: qwen") {
t.Fatalf("unknown name (exit %d): %s", code, errOut)
}
}
4 changes: 3 additions & 1 deletion internal/cli/status.go
Original file line number Diff line number Diff line change
Expand Up @@ -183,7 +183,9 @@ func (v statusView) Human(c *Context, ok bool) error {
// of what a run needs; it is never a reservation.
est := map[string]uint64{}
for _, f := range st.Footprints {
est[f.Engine] = f.Bytes
if f.Bytes > 0 {
est[f.Engine] = f.Bytes
}
}
fmt.Fprint(tw, "\nENGINE\tTYPE\tUP\tMODELS\tDECODE\tPREFILL\tOUT TOKENS\tQUEUE\tEST. VRAM\n")
for _, e := range st.Engines {
Expand Down
Loading
Loading