Add a provider

A seat is one row in offer: a provider, an optional account scope, and one vendor model id. Adding a seat is a CLI write and a reload, not a code change.

Before you start

• the vendor API key, in a file the gateway user can read (0600);
• the vendor’s own model id, not the public alias;
• the DSN for the gateway database (the CLI takes it as -dsn).

1. Add the offer

The admin surface is acumen offer (cmd/acumen/admin.go:26). One observation, one row:

acumen offer add -dsn "$ACUMEN_DSN" \
  -provider <vendor> -vendor-model <vendor-model-id> \
  -model <public-model> -plan

The pricing switch is exactly one of -free, -plan or -paid; -paid needs -price-in and -price-out in the vendor’s unit (cmd/acumen/admin.go:132-150).

To import a whole vendor catalogue instead, offer sync reads the seat’s model listing and appends what it finds, with -dry-run available to preview:

acumen offer sync -dsn "$ACUMEN_DSN" -provider <vendor> -account <account> -plan -dry-run

2. Wait for the reload

The seat set is re-read every 30 seconds (cmd/acumen/main.go:85, reloadEvery). There is no force command; wait one window instead of restarting the gateway.

3. Prove it answers

curl -sS http://127.0.0.1:4020/v1/chat/completions \
  -H "Authorization: Bearer $ACUMEN_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"<vendor-model-id>","messages":[{"role":"user","content":"ping"}]}'

A 200 with non-empty choices[0].message.content is the proof. A model_no_eligible_seat code means the row did not load or its plan is not usable; upstream_auth means the key file is wrong.

4. Read the first failure

A failing seat is cooled down, not removed. seat_health carries last_error_code, consecutive_failures and cooling_until (internal/store/seathealth.go:31). The cooldown is the plan default: 30 s for a free or subscription seat, 60 s for a prepaid one, because the dispatch path does not parse the vendor’s Retry-After (internal/gateway/cooldown.go).

Rollback

Retire the offer rather than deleting the row, so the observation history stays readable:

acumen offer retire -dsn "$ACUMEN_DSN" -provider <vendor> -vendor-model <vendor-model-id>