Package net.thevpc.naru.ext.models.cache

Class NaruCachePlan

java.lang.Object
net.thevpc.naru.ext.models.cache.NaruCachePlan
All Implemented Interfaces:
NaruCachePlanView
public final class NaruCachePlan extends Object implements NaruCachePlanView
The caching decision for one request: which segments are a continuation of the previously cached prefix, and where a client-controlled cache marker should go.

A plan is computed from the current segments, the persisted baseline and the provider's NaruCachingMode. Providers translate it into their own wire format; the decision itself is made once, in one place.

  • Method Details

    • of

      public static NaruCachePlan of(NaruCacheableContext context, NaruCacheBaseline baseline, String providerName, String modelName, NaruCachingMode mode)
      Decide the plan for a request.

      The only trustworthy inputs are the segments themselves and a baseline that NaruCacheBaseline.matches(java.lang.String, java.lang.String, net.thevpc.naru.api.model.NaruCachingMode) this provider/model/mode. When the baseline is absent, stale, or belongs to a different target, the result is a full miss: every segment is re-sent as fresh content.

    • segmentKeys

      public List<String> segmentKeys()
      The chain for this request, to be stored as the next baseline.

    • segments

      public List<NaruContextSegment> segments()
      Specified by:
      segments in interface NaruCachePlanView

    • mode

      public NaruCachingMode mode()
      Specified by:
      mode in interface NaruCachePlanView

    • validPrefix

      public int validPrefix()
      How many leading segments remain a valid continuation of the cached prefix.

    • divergenceIndex

      public int divergenceIndex()
      First segment index that is not a continuation of the cached prefix. Equal to segmentCount() when nothing diverged.

    • segmentCount

      public int segmentCount()

    • isValid

      public boolean isValid(int i)
      Whether segment i can keep whatever cache state it already had.

    • isCacheHit

      public boolean isCacheHit(int i)
      Whether a cache marker should be attached after segment i.
      Specified by:
      isCacheHit in interface NaruCachePlanView

    • cacheBreakpoints

      public List<Integer> cacheBreakpoints(int maxBreakpoints)
      Indices after which a client-controlled breakpoint should be placed.

      Anthropic accepts at most maxBreakpoints per request, but a request can easily contain more cacheable segments than that (system prompt, tools, per-module indexed context, project files, ...). Dropping the extras has to be done deliberately, because the naive choices are both bad: taking the first N leaves the largest stable blocks uncached, and taking the last N clusters every marker at the volatile tail where the next turn invalidates all of them.

      So the last cacheable segment is always taken — it is the only breakpoint that covers the whole stable prefix, and losing it is the difference between caching everything and caching nothing. The remaining slots go to the most stable remaining candidates: longest declared lifetime first, then largest content.

      Specified by:
      cacheBreakpoints in interface NaruCachePlanView

    • resourcePrefix

      public List<NaruContextSegment> resourcePrefix(List<Integer> breakpoints)
      The stable prefix a stateful provider should freeze into a cached resource: everything up to and including the last chosen breakpoint.

      Everything after that point is sent per-request. Only the part up to the final breakpoint is eligible to become a resource, because a CachedContent resource that includes the volatile tail could never be reused on a later turn.

    • volatileSuffix

      public List<NaruContextSegment> volatileSuffix()
      The segments sent fresh on this request: everything from the first cache miss onwards, plus any segment after the cached prefix that is not itself eligible.

    • toString

      public String toString()
      Overrides:
      toString in class Object