Package com.tnsai.intelligence.rag.binding

Class SequentialUnitReader

java.lang.Object
com.tnsai.intelligence.rag.binding.SequentialUnitReader
public final class SequentialUnitReader extends Object
Thread-safe cursor over one source's ingested units in exact ingest order.

Readers are obtained from forTarget(Object, String). The runtime returns the same reader for the same target identity, runtime role class, source, builder-source template, and active KnowledgeScope (or the unscoped global lifetime), so annotation and programmatic calls in one lifetime share position. Distinct templates of that sequential source do not share units. A sibling source's builder override is not a distinct template: forTarget(this, "questions") and an SPI dispatch whose runtime map locates episode share one cursor. Unscoped position is process-local; scoped position ends when its scope closes. A restart begins again at the first unit.

use = SEQUENTIAL dispatch consumes next() before the action body runs. After the last real unit, remaining() is 0 and isExhausted() is still false — the body must return blank so SCOP narrates that unit. The next dispatch's next() is empty, and isExhausted() is then true; that is the signal to return an application sentinel such as DONE. Do not treat remaining() == 0 as DONE: that is the lifecycle signal to stop scheduling further turns.

Since:
0.15.0

  • Method Details

    • forTarget

      public static SequentialUnitReader forTarget(Object target, String source)
      Returns the shared reader for annotation-declared sources on a target.
      Parameters:
      target - object whose cursor identity owns the position
      source - exact, case-sensitive knowledge-source name
      Returns:
      shared target/source reader

    • forTarget

      public static SequentialUnitReader forTarget(Object target, com.tnsai.rag.SequentialConfig config, List<com.tnsai.rag.KnowledgeSourceConfig> builderSources)
      Returns the shared reader using the same builder-source template as an AgentBuilder-backed annotation dispatch.
      Parameters:
      target - object whose cursor identity owns the position
      config - ordered-consumption configuration
      builderSources - builder-declared knowledge sources
      Returns:
      shared target/source reader

    • next

      public Optional<RetrievedDocument> next()
      Atomically consumes the next unit.

      Concurrent callers receive distinct units. Once exhausted, repeated calls remain empty and do not advance or overflow the cursor.

      Returns:
      next unit, or empty after the last unit

    • next

      public Optional<RetrievedDocument> next(com.tnsai.cancellation.CancellationToken cancellation)
      Atomically consumes the next unit unless cancellation is set.
      Parameters:
      cancellation - cooperative cancellation; never null
      Returns:
      next unit, or empty after the last unit

    • size

      public int size()
      Number of ingested units in this snapshot.
      Since:
      0.16.1

    • remaining

      public int remaining()
      Units not yet consumed. After the last delivered unit this is 0 while isExhausted() is still false.
      Since:
      0.16.1

    • isExhausted

      public boolean isExhausted()
      Whether the last next() returned empty.

      True on the dispatch after the last unit (the DONE call), true immediately when the source ingested nothing, and false on the call that delivered the last unit. use = SEQUENTIAL hosts should return their sentinel from this flag, not by counting the file.

      Since:
      0.16.1

    • reset

      public void reset()
      Resets this target/source cursor to the first ingested unit.