Package net.thevpc.naru.api.model

Record Class NaruContextSegment

java.lang.Object
java.lang.Record
net.thevpc.naru.api.model.NaruContextSegment
Record Components:
id - stable logical identity, e.g. system-prompt, tool-defs, code-context:moduleX. Used for diagnostics and for pairing against persisted state; cache validity is decided by content, never by id.
content - what the segment carries
cacheable - whether this segment is a caching candidate
minLifetime - hint for how long the caller expects this segment to stay stable. Advisory: it never causes NARU to cache a segment the caller marked volatile, and it never rescues one whose content actually changed.
public record NaruContextSegment(String id, NaruSegmentContent content, boolean cacheable, Duration minLifetime) extends Record
One stable-to-volatile slice of the outgoing request context.

Callers build the request as an ordered list of segments, most stable first: system prompt, tool definitions, project/indexed context, older conversation turns, and finally the volatile tail (latest user turn, latest tool results). Marking a segment cacheable() is a claim that its serialized bytes will not change on the next turn.

That claim is the whole basis of every provider's prefix cache, so NARU verifies it rather than trusting it: the caching layer compares canonical() values through a hash chain, precisely because NARU permits mid-history edits and a segment that keeps its own hash can still sit at a different position in the prefix.

  • Constructor Details

    • NaruContextSegment

      public NaruContextSegment(String id, NaruSegmentContent content, boolean cacheable, Duration minLifetime)
      Creates an instance of a NaruContextSegment record class.
      Parameters:
      id - the value for the id record component
      content - the value for the content record component
      cacheable - the value for the cacheable record component
      minLifetime - the value for the minLifetime record component

  • Method Details

    • cacheable

      public static NaruContextSegment cacheable(String id, NaruSegmentContent content)
      A cacheable segment with no particular stability horizon.

    • volatileSegment

      public static NaruContextSegment volatileSegment(String id, NaruSegmentContent content)
      A segment that must be re-sent as fresh content every turn.

    • withCacheable

      public NaruContextSegment withCacheable(boolean newCacheable)

    • canonical

      public String canonical()
      A deterministic textual rendering of exactly the content that will be serialized for this segment.

      Determinism matters more than prettiness: the value feeds a hash chain whose only job is to answer "did this exact prefix change?". Map keys are sorted so two structurally identical segments cannot hash differently because of HashMap iteration order. Fields the serializer would not emit (source, sourceName) are excluded, because they are bookkeeping and must not spuriously invalidate a cache.

      id() is excluded for the same reason. It is a label for diagnostics and for pairing against persisted state, and it is not part of what the provider receives. Hashing it would mean a caller who derives ids dynamically — a counter, a timestamp, a path that moves — misses on every single turn while the bytes on the wire are byte-identical. Excluding it cannot cause a false hit, because the content that follows is exactly what gets sent.

    • toString

      public final String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. Reference components are compared with Objects::equals(Object,Object); primitive components are compared with '=='.
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • id

      public String id()
      Returns the value of the id record component.
      Returns:
      the value of the id record component

    • content

      public NaruSegmentContent content()
      Returns the value of the content record component.
      Returns:
      the value of the content record component

    • cacheable

      public boolean cacheable()
      Returns the value of the cacheable record component.
      Returns:
      the value of the cacheable record component

    • minLifetime

      public Duration minLifetime()
      Returns the value of the minLifetime record component.
      Returns:
      the value of the minLifetime record component