Package net.thevpc.naru.api.model

Enum Class NaruCachingMode

java.lang.Object
java.lang.Enum<NaruCachingMode>
net.thevpc.naru.api.model.NaruCachingMode
All Implemented Interfaces:
Serializable, Comparable<NaruCachingMode>, Constable
public enum NaruCachingMode extends Enum<NaruCachingMode>
How a provider exposes prompt caching, which determines what a caching client must do to get a cache hit.

These are genuinely different mechanisms, not variations of one. The mode decides both the wire format and how invalidation is computed, so it is modelled explicitly rather than inferred from the provider name.

  • Nested Class Summary

    Nested classes/interfaces inherited from class java.lang.Enum

    Enum.EnumDesc<E extends Enum<E>>

  • Enum Constant Summary

    Enum Constants
    Enum Constant
    Description
    AUTOMATIC_PREFIX
    The provider caches a literal byte-prefix of the request transparently, with no client-side breakpoint API.
    EXPLICIT_INLINE
    The provider accepts inline cache-control breakpoints that the caller places on specific content blocks (Anthropic cache_control).
    EXPLICIT_RESOURCE
    The provider caches context in a separately created, immutable, server-side resource with its own lifecycle and TTL (Gemini CachedContent), referenced by id from generation requests.
    NONE
    No caching concept at the API level.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    isClientControlled()
    Whether a cache hit is expressed by the caller sending a marker, as opposed to happening implicitly for a matching prefix.
    boolean
    isStateful()
    Whether this mode keeps server-side state that must be tracked, expired and eventually deleted.
    static NaruCachingMode
    valueOf(String name)
    Returns the enum constant of this class with the specified name.
    static NaruCachingMode[]
    values()
    Returns an array containing the constants of this enum class, in the order they are declared.

    Methods inherited from class java.lang.Enum

    clone, compareTo, describeConstable, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

    Methods inherited from class java.lang.Object

    getClass, notify, notifyAll, wait, wait, wait

  • Enum Constant Details

    • NONE

      public static final NaruCachingMode NONE
      No caching concept at the API level. The full context is re-sent and re-billed every turn. Local providers (Ollama) land here: the server may reuse a KV cache internally per connection, but there is nothing the client can address or rely on.

    • AUTOMATIC_PREFIX

      public static final NaruCachingMode AUTOMATIC_PREFIX
      The provider caches a literal byte-prefix of the request transparently, with no client-side breakpoint API. NARU's only job is to keep the prefix byte-identical across turns; the provider does the rest. Most OpenAI-compatible backends behave this way.

      Consequence: because the match is positional, a mid-history edit invalidates everything from the edit point onward even though the segments themselves are unchanged. That cost is inherent to the mechanism, not a defect in NARU.

    • EXPLICIT_INLINE

      public static final NaruCachingMode EXPLICIT_INLINE
      The provider accepts inline cache-control breakpoints that the caller places on specific content blocks (Anthropic cache_control). NARU decides where the breakpoints go; the request is otherwise unchanged. Each call is stateless, so history mutation needs no server-side state management beyond re-placing the breakpoints.

    • EXPLICIT_RESOURCE

      public static final NaruCachingMode EXPLICIT_RESOURCE
      The provider caches context in a separately created, immutable, server-side resource with its own lifecycle and TTL (Gemini CachedContent), referenced by id from generation requests.

      This is the most demanding mode: the resource cannot be patched, so a divergence point that falls inside an already-cached prefix forces the whole resource to be discarded and recreated.

  • Method Details

    • values

      public static NaruCachingMode[] values()
      Returns an array containing the constants of this enum class, in the order they are declared.
      Returns:
      an array containing the constants of this enum class, in the order they are declared

    • valueOf

      public static NaruCachingMode valueOf(String name)
      Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)
      Parameters:
      name - the name of the enum constant to be returned.
      Returns:
      the enum constant with the specified name
      Throws:
      IllegalArgumentException - if this enum class has no constant with the specified name
      NullPointerException - if the argument is null

    • isClientControlled

      public boolean isClientControlled()
      Whether a cache hit is expressed by the caller sending a marker, as opposed to happening implicitly for a matching prefix. Inline modes must do real work at serialization time; automatic and NONE do not.

    • isStateful

      public boolean isStateful()
      Whether this mode keeps server-side state that must be tracked, expired and eventually deleted. Only resource mode does.