@bivelio/savings-layer 0.4.30 → 0.4.31

package/dist/index.d.ts

@@ -325,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.30";
+declare const BV_SALA_VERSION = "0.4.31";
 
 /**
  * Environment-agnostic UUID generation.
@@ -546,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;
@@ -1103,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. */
@@ -1336,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. */
@@ -2240,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;
     /**
@@ -2558,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;
@@ -2604,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, 
@@ -3014,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;
@@ -3504,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;
@@ -4587,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?
@@ -4616,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>;
@@ -4629,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. */