floe-guard 0.15.0 → 0.15.1

package/README.md

@@ -64,6 +64,24 @@ const adv = guard.advisory();
 const model = adv.nearLimit ? openai("gpt-4o-mini") : openai("gpt-4o");
 ```
 
+## Request-sized estimates
+
+To ensure the ceiling is enforced on the first run or for a call much larger than the previous one, you can price the actual incoming request using `estimateCall()` and pass the estimate to `reserve()` or `check()`:
+
+```ts
+const est = guard.estimateCall("gpt-4o", 12_000, 4_096);
+const handle = guard.reserve(est); // throws BudgetExceeded NOW if this call alone would cross
+try {
+  const response = await callYourLlm({ model: "gpt-4o", ... });
+  guard.settle("gpt-4o", response.usage.promptTokens, response.usage.completionTokens, { reserved: handle });
+} catch (err) {
+  guard.release(handle);
+  throw err;
+}
+```
+
+If the model is unpriceable, `estimateCall()` returns `undefined` and `reserve(undefined)` / `check(undefined)` fall back gracefully to the last-cost prediction.
+
 ## Tool spend under the same ceiling
 
 Paid tool calls (Apollo, Exa, scrapers) burn the same budget as tokens. The

package/dist/adapters/livekit.d.cts

@@ -1,4 +1,4 @@
-import { B as BudgetGuard, a as BudgetExceeded } from '../guard-CJWReYhA.cjs';
+import { B as BudgetGuard, a as BudgetExceeded } from '../guard-B05gDZ3g.cjs';
 
 /**
  * LiveKit Agents adapter (optional peer: `npm i @livekit/agents`).

package/dist/adapters/livekit.d.ts

@@ -1,4 +1,4 @@
-import { B as BudgetGuard, a as BudgetExceeded } from '../guard-CJWReYhA.js';
+import { B as BudgetGuard, a as BudgetExceeded } from '../guard-B05gDZ3g.js';
 
 /**
  * LiveKit Agents adapter (optional peer: `npm i @livekit/agents`).

package/dist/adapters/retell.d.cts

@@ -1,4 +1,4 @@
-import { B as BudgetGuard, a as BudgetExceeded } from '../guard-CJWReYhA.cjs';
+import { B as BudgetGuard, a as BudgetExceeded } from '../guard-B05gDZ3g.cjs';
 
 /**
  * Retell custom-LLM WebSocket adapter (optional peer: the `ws` server your custom

package/dist/adapters/retell.d.ts

@@ -1,4 +1,4 @@
-import { B as BudgetGuard, a as BudgetExceeded } from '../guard-CJWReYhA.js';
+import { B as BudgetGuard, a as BudgetExceeded } from '../guard-B05gDZ3g.js';
 
 /**
  * Retell custom-LLM WebSocket adapter (optional peer: the `ws` server your custom

package/dist/adapters/vapi.d.cts

@@ -1,5 +1,5 @@
-import { B as BudgetGuard, F as FloeGuardError } from '../guard-CJWReYhA.cjs';
-export { a as BudgetExceeded } from '../guard-CJWReYhA.cjs';
+import { B as BudgetGuard, F as FloeGuardError } from '../guard-B05gDZ3g.cjs';
+export { a as BudgetExceeded } from '../guard-B05gDZ3g.cjs';
 
 /**
  * Vapi custom-LLM adapter (no SDK dependency — typed structurally).

package/dist/adapters/vapi.d.ts

@@ -1,5 +1,5 @@
-import { B as BudgetGuard, F as FloeGuardError } from '../guard-CJWReYhA.js';
-export { a as BudgetExceeded } from '../guard-CJWReYhA.js';
+import { B as BudgetGuard, F as FloeGuardError } from '../guard-B05gDZ3g.js';
+export { a as BudgetExceeded } from '../guard-B05gDZ3g.js';
 
 /**
  * Vapi custom-LLM adapter (no SDK dependency — typed structurally).

package/dist/{guard-CJWReYhA.d.cts → guard-B05gDZ3g.d.cts}

@@ -412,6 +412,27 @@ declare class BudgetGuard {
         price?: ManualPrice;
         label?: string;
     }): number;
+    /**
+     * Price the ACTUAL incoming request, for a request-sized {@link reserve} / {@link check}.
+     *
+     * {@link check} and {@link reserve} default to predicting the next call
+     * from the LAST call's cost — which is blind on the first call and wrong
+     * for a call much larger than the previous one. Feed this the request you
+     * are about to send (its real prompt size and output cap) and pass the
+     * result straight through:
+     *
+     *     const est = guard.estimateCall("gpt-4o", promptTokens, maxCompletionTokens);
+     *     const handle = guard.reserve(est);   // blocks NOW if this call alone would cross
+     *
+     * The estimate is worst-case on output (the model may stop well short of
+     * `maxCompletionTokens`); the hold is corrected to actual cost at
+     * {@link settle}. Returns `undefined` when the model is unpriceable — and
+     * `reserve(undefined)` / `check(undefined)` fall back to the last-cost
+     * prediction, so the wiring degrades gracefully instead of failing.
+     */
+    estimateCall(model: string, promptTokens: number, maxCompletionTokens?: number, options?: {
+        price?: ManualPrice;
+    }): number | undefined;
     /**
      * Atomically check the ceiling AND hold a tool call's cost in flight.
      *

package/dist/{guard-CJWReYhA.d.ts → guard-B05gDZ3g.d.ts}

@@ -412,6 +412,27 @@ declare class BudgetGuard {
         price?: ManualPrice;
         label?: string;
     }): number;
+    /**
+     * Price the ACTUAL incoming request, for a request-sized {@link reserve} / {@link check}.
+     *
+     * {@link check} and {@link reserve} default to predicting the next call
+     * from the LAST call's cost — which is blind on the first call and wrong
+     * for a call much larger than the previous one. Feed this the request you
+     * are about to send (its real prompt size and output cap) and pass the
+     * result straight through:
+     *
+     *     const est = guard.estimateCall("gpt-4o", promptTokens, maxCompletionTokens);
+     *     const handle = guard.reserve(est);   // blocks NOW if this call alone would cross
+     *
+     * The estimate is worst-case on output (the model may stop well short of
+     * `maxCompletionTokens`); the hold is corrected to actual cost at
+     * {@link settle}. Returns `undefined` when the model is unpriceable — and
+     * `reserve(undefined)` / `check(undefined)` fall back to the last-cost
+     * prediction, so the wiring degrades gracefully instead of failing.
+     */
+    estimateCall(model: string, promptTokens: number, maxCompletionTokens?: number, options?: {
+        price?: ManualPrice;
+    }): number | undefined;
     /**
      * Atomically check the ceiling AND hold a tool call's cost in flight.
      *

package/dist/index.cjs

@@ -1855,6 +1855,35 @@ var BudgetGuard = class {
       label: options.label
     });
   }
+  /**
+   * Price the ACTUAL incoming request, for a request-sized {@link reserve} / {@link check}.
+   *
+   * {@link check} and {@link reserve} default to predicting the next call
+   * from the LAST call's cost — which is blind on the first call and wrong
+   * for a call much larger than the previous one. Feed this the request you
+   * are about to send (its real prompt size and output cap) and pass the
+   * result straight through:
+   *
+   *     const est = guard.estimateCall("gpt-4o", promptTokens, maxCompletionTokens);
+   *     const handle = guard.reserve(est);   // blocks NOW if this call alone would cross
+   *
+   * The estimate is worst-case on output (the model may stop well short of
+   * `maxCompletionTokens`); the hold is corrected to actual cost at
+   * {@link settle}. Returns `undefined` when the model is unpriceable — and
+   * `reserve(undefined)` / `check(undefined)` fall back to the last-cost
+   * prediction, so the wiring degrades gracefully instead of failing.
+   */
+  estimateCall(model, promptTokens, maxCompletionTokens = 0, options = {}) {
+    let overrides = this.priceOverrides;
+    if (options.price !== void 0) {
+      overrides = { ...overrides ?? {}, [model]: options.price };
+    }
+    const priced = resolvePrice(model, overrides);
+    if (priced === null) {
+      return void 0;
+    }
+    return priceTokens(priced, promptTokens, maxCompletionTokens);
+  }
   /**
    * Atomically check the ceiling AND hold a tool call's cost in flight.
    *