Buckette the mascot: a coin purse tied shut with a rope, waving.

buckette®

Bounded, revocable spend limits for your agents and automated systems.

Your code asks buckette before it spends: each spend is applied atomically, on tokens, dollars or any unit you name, and refused if it would go over its limit. Limits split into child buckets, refill on a schedule, and can be frozen or revoked at any time.

Start in the Console Read the guide for agents

The buckette Console's Monitors page: a treemap of a 3,000,000-token monthly allowance split between three workflows (Document pipeline, Ticket triage, Nightly report), beside bars of what each consumed this period, 46% of the allowance in all.
A monthly allowance and how three workflows share it, in the Console's Monitors.
The buckette Console's Buckets page: a monthly allowance with three child buckets, each with tokens and dollars, one open to show its two dimensions locked at 269,270 of 900,000 tokens and 6.88 of 12 USD.
Each workflow has its own bucket, with its own limit on each dimension.

How it works

  1. Create a budget. POST /buckets with a limit of 100,000 tokens, and PUT /buckets/:id/replenish-config to refill it on the 1st of each month.

  2. Ask before each call. Your code posts what the call will cost to /buckets/:id/consume. Later in the month, with 20,000 tokens left:

    curl "$BUCKETTE_URL/buckets/$BUCKET_ID/consume" \
      -H "Authorization: Bearer $BUCKETTE_KEY" \
      -H "Content-Type: application/json" \
      -d '{"crAmounts": {"tokens": 1200},
           "crMode": {"tag": "Strict"}}'

    The tokens are taken, and the answer says what is left:

    {
      "coConsumed": {"tokens": 1200},
      "coProtection": null,
      "coReceipt": null,
      "coRemaining": {"tokens": 18800},
      "tag": "ConsumeSuccess"
    }
  3. Over the limit, it is refused. The same call for 25,000 tokens takes nothing. The answer says how much is missing and when the next refill covers it (eaAtUnix is 1 December, 00:00 UTC):

    {
      "coAvailable": {},
      "coEta": {
        "seDimensions": {
          "tokens": {"eaAtUnix": 1796083200,
                     "eaSeconds": 1339200,
                     "tag": "EtaAt"}
        },
        "seOverall": {"eaAtUnix": 1796083200,
                      "eaSeconds": 1339200,
                      "tag": "EtaAt"}
      },
      "coProtection": null,
      "coShortfall": {"tokens": 6200},
      "tag": "ConsumeShortfall"
    }

Both answers are 200 OK: read tag. Every route is in the guide for agents, and the first steps in Getting started.

Contact Lucas DiCioccio on LinkedIn

Blog

  • A disaster simulator: roll a month of bad nights

    A bad run looks like bad luck; over a month it is a rate. A small simulator plays a month of agent runs twice, with no limit and with a budget per run, so you can see what the loops cost, what the budget saves, and when a budget that is too tight costs more than it saves.

  • The opportunity cost of badly spending

    Budget spent on the wrong run is budget not spent on the right one. Three ways that cost shows up (work that waited, valuable work that was refused, an experiment that never ran) and what buckette's claims, values and auctions do about each.

  • The costs of badly spending

    A bad run of an agent or a pipeline costs tens to thousands of dollars. Four common ways it happens, with illustrative numbers, and what a budget around the run changes.