@bivelio/savings-layer 0.4.29 → 0.4.31

package/dist/index.d.ts

@@ -232,6 +232,20 @@ declare class SavingsLedger {
     providerCached(tokens: number): void;
     /** Record the premium for `tokens` of cache write the provider bills at `multiplier`x on its own. */
     providerCacheWritePremium(tokens: number, multiplier: number, price: CostModel): void;
+    /** Input tokens of calls the provider documents as not billed; already included in `actualInput`. */
+    unbilledInput: number;
+    /** Output tokens of those calls; already included in `actualOutput`. */
+    unbilledOutput: number;
+    /** Provider-cached input tokens of those calls; already included in `providerCachedInput`. */
+    unbilledCachedInput: number;
+    /** True when the answer served is a refusal the provider does not bill: no saving is credited. */
+    servedUnbilledRefusal: boolean;
+    /** Record a call the provider documents as not billed: its tokens stay counted and are priced at 0. */
+    unbilledCall(usage: {
+        inputTokens: number;
+        outputTokens: number;
+        cachedInputTokens?: number;
+    }): void;
     /** Set when an avoided call is valued against the provider counter of an identical call that ran. */
     reference: ReferenceCredit | null;
     /** Set when an avoided cache or coalesced hit could not be valued by reference: why it stays estimated. */
@@ -311,7 +325,7 @@ declare function precioDeLista(model: string, at?: Date | number): CostModel | u
  * on the customer's machine. `test/version-declarada.test.ts` ties this
  * constant to package.json so the two can never drift.
  */
-declare const BV_SALA_VERSION = "0.4.29";
+declare const BV_SALA_VERSION = "0.4.31";
 
 /**
  * Environment-agnostic UUID generation.
@@ -532,7 +546,11 @@ interface OutputContract {
     /** Stable identifier, e.g. "research-answer:v3". */
     contractId: string;
     schema: JsonSchema;
-    /** Hard ceiling on generated tokens. */
+    /**
+     * Hard ceiling on generated tokens for this contract. A free-text request (no
+     * schema) sets its ceiling with {@link SavingsRequest.maxOutputTokens}; when
+     * both are set, the smaller one is sent.
+     */
     maxOutputTokens?: number;
     /** Version marker included in the exact-cache key. */
     version?: string;
@@ -1089,6 +1107,19 @@ interface SavingsRequest {
     /** Sampling controls that participate in the exact-cache key. */
     temperature?: number;
     seed?: number;
+    /**
+     * Hard ceiling on generated tokens for this request, with or without an
+     * output contract. It travels to every adapter: Anthropic `max_tokens`,
+     * Chat Completions `max_completion_tokens` on OpenAI's own API and
+     * `max_tokens` on any other OpenAI-compatible endpoint (see
+     * `OpenAICompatibleOptions.maxTokensParam`). When `response.maxOutputTokens`
+     * is also set, the smaller of the two is sent. Unset, nothing changes.
+     *
+     * It is a limit you set, not a saving: it never raises the estimated output
+     * of an avoided call and is never credited as output avoided. An answer cut
+     * by it (`finishReason: "length"`) is not cached. Must be a positive integer.
+     */
+    maxOutputTokens?: number;
     /** Tokenizer id to cost against; defaults to a model-derived estimate. */
     tokenizer?: string;
     /** Arbitrary structured payload to be serialized into the prompt. */
@@ -1322,11 +1353,12 @@ interface QualityTruncationCheck {
     /** The stop reason exactly as the provider named it; absent when it reported none. */
     finishReason?: string;
     /**
-     * Whether you set the limit (`response.maxOutputTokens`). When false, any
+     * Whether you set the limit (`maxOutputTokens` on the request or on
+     * `response`). When false, any
      * limit that applied was a provider or adapter default.
      */
     capSetByCaller: boolean;
-    /** The limit you set, in output tokens. Present only when `capSetByCaller`. */
+    /** The limit that was sent (the smaller of the two when both were set). Present only when `capSetByCaller`. */
     outputLimit?: number;
 }
 /** How a cache hit matched this request. */
@@ -2226,8 +2258,13 @@ interface SemanticCacheOptions {
      *
      * Pass your own for true semantics; the local one only sees LEXICAL closeness.
      * Either way the deterministic guard below still rejects a candidate whose
-     * numbers, negation or entities differ, so a weaker vector can only cost you a
-     * cache miss — never a wrong answer.
+     * numbers (in digits or spelled out in en/es/ca: "three", "twice", "half"),
+     * negation parity or content words differ beyond its overlap floor. It is a
+     * lexical guard, not a proof: a one-word entity swap in a long query can
+     * still clear the overlap floor, and through 0.4.30 a number written in words
+     * cleared it too (GSM8K: 477 of 564 such variants got their original's
+     * answer). Calibrate on your own traffic before trusting it with answers
+     * that differ by one word.
      */
     embed?: EmbeddingFn;
     /**
@@ -2544,7 +2581,20 @@ interface ToolSelection {
     setIsStable: boolean;
 }
 interface ToolSelectorOptions {
-    /** Max tools to include (schema-token budget guard). */
+    /**
+     * Max tools the selector keeps when it has a SIGNAL to select on: a catalogue
+     * whose tools declare `intents` and/or `risk`, with the router on. Default 8.
+     *
+     * It never truncates a catalogue it cannot rank. A catalogue that declares no
+     * `intents` and no `risk` (the usual case: MCP and OpenAI tool lists) and every
+     * request with `savings: { router: false }` go to the provider WHOLE, exactly as
+     * the caller sent them, and the layer credits nothing for the tool block:
+     * cutting by position left the model unable to call the rest (on BFCL
+     * multi-turn, gpt-4o-mini hit the reference call 8/10 times directly and 1/10
+     * through the layer). When the selector does prune a typed catalogue, the
+     * report's `tool-selector` trace lists what was left out and the SDK warns
+     * (once per process, silenced by `silenceWarnings`).
+     */
     maxTools?: number;
     /** Tokenizer-aware scorer for tie-breaking (optional). */
     scoreIntentMatch?: (text: string, tool: ToolDescriptor) => number;
@@ -2590,16 +2640,9 @@ declare class ToolSelector {
     private readonly freezer;
     constructor(opts?: ToolSelectorOptions);
     /**
-     * Todas las herramientas que pasó el llamante, acotadas SOLO por el
-     * presupuesto de esquema (`maxTools`).
-     *
-     * Se usa cuando el llamante apaga el router (`savings:{router:false}`): sin
-     * clasificación no hay de dónde derivar el riesgo, y filtrar sobre el
-     * `defaultRoute()` tiraba en silencio las herramientas de escritura. Apagar el
-     * router significa "yo elijo las herramientas", así que la relevancia pasa a
-     * ser del llamante — pero el tope de presupuesto NO se levanta: mandar 200
-     * esquemas al proveedor es un 400 seguro y una petición que antes funcionaba
-     * pasaría a fallar en duro.
+     * Every tool the caller passed, as passed: none left out, none credited.
+     * Used when there is no signal to select on (`savings: { router: false }`,
+     * or a catalogue with no `intents` and no `risk`).
      */
     passthrough(tools: ToolDescriptor[] | undefined): ToolSelection;
     select(text: string, tools: ToolDescriptor[] | undefined, execution: ExecutionClass, 
@@ -3000,6 +3043,10 @@ interface ProviderRequest {
     tools?: ToolDescriptor[];
     /** Output contract to enforce via constrained decoding, when available. */
     schema?: JsonSchema;
+    /**
+     * Output cap chosen by the caller: the smaller of `SavingsRequest.maxOutputTokens`
+     * and `response.maxOutputTokens`. Each adapter maps it to its own field.
+     */
     maxOutputTokens?: number;
     temperature?: number;
     seed?: number;
@@ -3189,6 +3236,19 @@ interface ProviderResponse {
      * replayed by reference. `text` and `finishReason` stay what the provider said.
      */
     refusal?: string;
+    /**
+     * True when this answer is a refusal the provider documents as NOT billed:
+     * Anthropic's Messages API refusal that arrives before any output, in a
+     * category its published table marks as not billed (`cyber`,
+     * `general_harms`, or a `null` category). See
+     * https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback
+     * («How refusals are billed»).
+     *
+     * The layer then measures this call at cost 0 and credits no saving on the
+     * request at all (measured, estimated or by reference). Absent means billed
+     * like any other call. Set it only from the provider's own response.
+     */
+    unbilledRefusal?: boolean;
     /**
      * Llamadas a herramienta que pidió el modelo, tal cual las devolvió el
      * proveedor.
@@ -3477,7 +3537,28 @@ interface SavingsLayerConfig {
     provider: Provider;
     tokenizer: TokenizerRegistry;
     exactCache?: ExactCache;
+    /**
+     * WHERE reworded questions are looked up and stored. Giving the layer a cache
+     * does NOT switch it on: a request still has to ask for it with
+     * `savings.semanticCache`, or you set {@link semanticCacheDefault} to ask for
+     * it on every request. A layer that has a cache and a request that neither
+     * asks for it nor turns it off gets a one-time console warning (silenced by
+     * `silenceWarnings`, or by setting `semanticCacheDefault`, `false` included).
+     */
     semanticCache?: InMemorySemanticCache;
+    /**
+     * Default for `savings.semanticCache` on every request of this layer. A
+     * request's own value always wins, `false` included. Unset, the semantic cache
+     * is used only by requests that ask for it.
+     *
+     * OPT-IN, and deliberately a separate field from {@link semanticCache}: the
+     * cache is the backend, this is the decision to serve answers to reworded
+     * questions, which can serve a wrong answer. Prefer it with a cache built with
+     * `calibration`, which serves nothing until your own traffic certifies a
+     * floor. `false` states that you switch it on per request, and silences the
+     * warning about a cache that no request uses.
+     */
+    semanticCacheDefault?: boolean | "safe-only" | "include-agentic";
     singleflight?: Singleflight;
     resolvers?: ResolverRegistry;
     router?: ExecutionRouter;
@@ -3777,6 +3858,17 @@ interface SavingsLayerConfig {
      * it when you have your own observability. Applies to the pipeline, the usage
      * emitter, the revocation poller and the provider adapters shipped in this
      * package alike.
+     *
+     * **One warning is NOT silenced: a rejected renewal credential.** When the
+     * automatic pickup of the renewed license gets HTTP 401, 403 or 404 (the
+     * `serviceAccountKey` was rotated, belongs to another organization, or
+     * `licenseServerUrl` is wrong), the SDK warns even with this flag on. That is
+     * not a degraded saving: the token will not renew and the layer will stop
+     * operating when the grace period ends, and the failure happens inside the SDK
+     * where your own observability cannot see it. It is printed once per status
+     * code per layer, never on every renewal attempt, and it never contains the
+     * key or any part of it. Fix the credential, or turn the pickup off with
+     * {@link licenseRefresh}`.enabled = false`, to make it go away.
      */
     silenceWarnings?: boolean;
     /**
@@ -4549,6 +4641,25 @@ interface OpenAICompatibleOptions {
      * saving. Benchmarks that make real cost claims must set this.
      */
     requireUsage?: boolean;
+    /**
+     * Which Chat Completions field carries the output cap (`maxOutputTokens`).
+     *
+     * Default (undefined): `max_completion_tokens` when `baseUrl` is OpenAI's own
+     * API (https://api.openai.com), `max_tokens` everywhere else. OpenAI
+     * deprecated `max_tokens` when it introduced `max_completion_tokens`
+     * (2024-09-12) and its reasoning models (o-series, gpt-5.x) reject it with a
+     * 400; `max_completion_tokens` is accepted by every current OpenAI chat
+     * model. OpenAI-compatible servers (proxies, self-hosted inference servers,
+     * routers, Azure with an older api-version, a local gateway) understand
+     * `max_tokens`, and some silently IGNORE a field they do not know, which
+     * would drop the cap without an error.
+     *
+     * With the default, a 400/422 that names the field sent as unsupported is
+     * retried once with the other one (it is rejected before any token is
+     * generated, so nothing is billed twice) and the model is remembered. An
+     * explicit value always wins and is never switched.
+     */
+    maxTokensParam?: "max_tokens" | "max_completion_tokens";
 }
 /**
  * ¿Cumple este esquema las reglas del modo `strict` de OpenAI?
@@ -4578,6 +4689,7 @@ declare class OpenAICompatibleProvider implements Provider {
     /** Models of this endpoint already known to reject `response_format`. */
     private readonly sinResponseFormat;
     private streamOptionsRejected;
+    private readonly campoDeTopeAprendido;
     private readonly origen;
     constructor(opts: OpenAICompatibleOptions);
     generate(req: ProviderRequest, options?: ProviderStreamOptions): Promise<ProviderResponse>;
@@ -4591,6 +4703,8 @@ declare class OpenAICompatibleProvider implements Provider {
      * as one text event.
      */
     generateStream(req: ProviderRequest, options?: ProviderStreamOptions): AsyncGenerator<ProviderStreamEvent, void, undefined>;
+    private campoDeTope;
+    private corregirCampoDeTope;
     private enviar;
     private construirCuerpo;
     /** Translate a 2xx endpoint response into the provider-neutral shape. */