Package com.tnsai.rag

Class RetrievalEngine

java.lang.Object
com.tnsai.rag.RetrievalEngine
All Implemented Interfaces:
AutoCloseable
public final class RetrievalEngine extends Object implements AutoCloseable
Agent-scoped retrieval engine shared by chat and action entry points.

This final wrapper owns invariant enforcement and delegates retrieval to an implementation supplied by tnsai-intelligence or another provider. It preserves caller cancellation before and after backend execution, normalizes unexpected failures, and makes lifecycle closure deterministic. Generic backends retain wrapper-enforced deadline checks; policy-aware backends may own them so one injected clock and one failure-policy boundary govern the complete retrieval operation.

Instances are expected to be owned by one configured agent or role and may hold source loaders and caches for that owner. The backend must be safe for concurrent calls. Every request cache and mutable request-scoped store must include the complete RetrievalScope; global caches keyed only by query or source are forbidden. The indexed source corpus is instead owned by the engine lifecycle. A physical remote table/collection may be shared only when its embedding schema is compatible and every read, write, and cleanup remains engine-owner-filtered. Provider-created engines own distinct remote corpus owners, even when document IDs or source names collide. Closing one engine may clear only that engine's owner and must not mutate another live engine's corpus. Lifecycle-owned remote entries carry renewable bounded expiry metadata so a later engine can scavenge data orphaned by a process crash.

Since:
0.13.0

  • Method Details

    • create

      public static RetrievalEngine create(RetrievalEngine.Retriever retriever)
      Creates an engine without lifecycle resources.
      Parameters:
      retriever - retrieval backend
      Returns:
      agent-scoped engine

    • create

      public static RetrievalEngine create(RetrievalEngine.Retriever retriever, Runnable closeAction)
      Creates an engine with an idempotently invoked close action.
      Parameters:
      retriever - retrieval backend
      closeAction - resource cleanup action
      Returns:
      agent-scoped engine

    • retrieve

      public RetrievalResult retrieve(RetrievalRequest request)
      Retrieves evidence for one chat or action invocation.
      Parameters:
      request - common retrieval request
      Returns:
      successful result, including an allowed empty result
      Throws:
      CancellationException - when the caller cancels
      RetrievalException - for deadline, lifecycle, provider, or execution failure

    • close

      public void close()
      Closes engine-owned resources exactly once.
      Specified by:
      close in interface AutoCloseable