agentfootprint/dist/types/cache/cacheStrategyFor.d.ts

The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.

/**
 * cacheStrategyFor — the cache strategy for a provider, chosen from what the
 * provider DECLARES (`LLMProvider.promptCaching`), never from its name.
 *
 * Pattern: Strategy, selected by capability. The provider adapter declares
 *          how its wire caches (`'breakpoints'` | `'automatic'` | absent);
 *          this function maps the declaration to the one strategy that
 *          serves it.
 * Role:    the ONE place an agent's cache strategy is chosen (`Agent`, and a
 *          skill brain whose provider differs from the agent's).
 *
 * Why not by name: the name is a label, and labels get rewritten. The
 * registry this replaces keyed strategies by `provider.name`, so every
 * decorator that renamed its provider — `withRetry` (`anthropic+retry`),
 * `withFallback` (`a|b`), an application's own routing wrapper
 * (`my-app/anthropic`) — silently fell through to the no-op strategy: no
 * cache markers, every call at full input price, and nothing in the run to
 * say why. A wrapper that forwards the declaration (the library's three
 * decorators do) caches exactly like the adapter it wraps.
 *
 * @example
 * ```ts
 * import { cacheStrategyFor } from 'agentfootprint/cache';
 * import { withRetry } from 'agentfootprint/resilience';
 * import { anthropic } from 'agentfootprint/providers';
 *
 * cacheStrategyFor(withRetry(anthropic())).name; // 'breakpoints'
 * cacheStrategyFor({ name: 'x', complete }).name; // 'none' — nothing declared
 * ```
 */
import type { LLMProvider } from '../provider-contract/types.js';
import type { CacheStrategy, PromptCaching } from './types.js';
/**
 * The strategy that serves `provider`'s declared prompt caching for `model`.
 * Static declarations keep the one-argument form. For a model-aware adapter,
 * pass its model (including its own supported shorthand); omitting it selects
 * no caching rather than guessing a model.
 *
 * @throws TypeError when the declaration is malformed (an unknown `mode`, a
 *   `maxBreakpoints` that is not a positive integer, a non-boolean
 *   `reportsUsage`) — refused at agent build, by provider name. A typo that
 *   quietly fell back to "no caching" would be the very failure this
 *   function exists to end.
 */
export declare function cacheStrategyFor(provider: Pick<LLMProvider, 'name' | 'promptCaching'>, model?: string): CacheStrategy;
/** Resolve the provider's one declaration for this model. An omitted model
 * cannot establish a model-aware capability, so it fails closed. Static
 * declarations retain the existing one-argument behavior.
 *
 * Use this reader instead of accessing `provider.promptCaching.mode`: the
 * port also permits a model function. No resolver is duplicated in adapters.
 *
 * @example
 * ```ts
 * import { promptCachingFor } from 'agentfootprint/cache';
 * const declaration = promptCachingFor(provider, model);
 * if (declaration?.mode === 'breakpoints') console.log(declaration.maxBreakpoints);
 * ```
 */
export declare function promptCachingFor(provider: Pick<LLMProvider, 'name' | 'promptCaching'>, model?: string): PromptCaching | undefined;
//# sourceMappingURL=cacheStrategyFor.d.ts.map