Package com.tnsai.rag

Class ChatKnowledgeBinding

java.lang.Object
com.tnsai.rag.ChatKnowledgeBinding
All Implemented Interfaces:
AutoCloseable
public final class ChatKnowledgeBinding extends Object implements AutoCloseable
Owner-scoped binding between chat grounding and one canonical retrieval engine source.

Applications with live corpora create one binding per conversation owner. Integrations that receive an owner object at dispatch time should use live(Object, String, String, int, RetrievalEngine.Retriever) so the exact owner can be verified without treating display names or identifiers as authority. The owner reference is weak and does not extend the owner's lifecycle. The retriever receives the complete canonical RetrievalRequest; no process-global registry or competing result model is introduced. Provider-backed annotation wiring uses create(String, RetrievalEngine, RetrievalConfig) with the same request path.

invalidate() advances an owner-local revision included in every request cache key. A caller may also supply an application revision in ChatRetrievalContext; live bindings disable framework caching by default so appends within one episode cannot return stale evidence.

Since:
0.13.0

  • Method Details

    • create

      public static ChatKnowledgeBinding create(String ownerId, RetrievalEngine engine, RetrievalConfig config)
      Creates an owner-scoped binding around an existing engine.
      Parameters:
      ownerId - stable conversation-owner identity
      engine - owner-scoped retrieval engine
      config - chat retrieval configuration naming at least one source
      Returns:
      owner-scoped binding

    • create

      public static ChatKnowledgeBinding create(Object exactOwner, String ownerId, RetrievalEngine engine, RetrievalConfig config)
      Creates a binding that can verify one exact owner object by identity.

      The owner is held weakly. isOwnedBy(Object) compares object identity rather than Object.equals(Object) so equal names or identifiers cannot authorize a different owner.

      Parameters:
      exactOwner - exact conversation owner object
      ownerId - stable owner identity used in retrieval metadata
      engine - owner-scoped retrieval engine
      config - chat retrieval configuration naming at least one source
      Returns:
      exact-owner-scoped binding
      Since:
      0.14.0

    • live

      public static ChatKnowledgeBinding live(String ownerId, String sourceName, int topK, RetrievalEngine.Retriever retriever)
      Creates a live-source binding with fail-open, no-cache chat defaults.
      Parameters:
      ownerId - stable conversation-owner identity
      sourceName - name of a declared @Knowledge
      topK - maximum evidence count
      retriever - application-owned live retriever
      Returns:
      owner-scoped live binding

    • live

      public static ChatKnowledgeBinding live(Object exactOwner, String ownerId, String sourceName, int topK, RetrievalEngine.Retriever retriever)
      Creates an exact-owner live binding with fail-open, no-cache defaults.
      Parameters:
      exactOwner - exact conversation owner object
      ownerId - stable owner identity used in retrieval metadata
      sourceName - name of a declared @Knowledge
      topK - maximum evidence count
      retriever - application-owned live retriever
      Returns:
      exact-owner-scoped live binding
      Since:
      0.14.0

    • live

      public static ChatKnowledgeBinding live(String ownerId, String sourceName, int topK, RetrievalEngine.Retriever retriever, Runnable closeAction)
      Creates a live-source binding with an idempotently invoked close action.
      Parameters:
      ownerId - stable conversation-owner identity
      sourceName - name of a declared @Knowledge
      topK - maximum evidence count
      retriever - application-owned live retriever
      closeAction - application resource cleanup
      Returns:
      owner-scoped live binding

    • live

      public static ChatKnowledgeBinding live(Object exactOwner, String ownerId, String sourceName, int topK, RetrievalEngine.Retriever retriever, Runnable closeAction)
      Creates an exact-owner live binding with an idempotent close action.
      Parameters:
      exactOwner - exact conversation owner object
      ownerId - stable owner identity used in retrieval metadata
      sourceName - name of a declared @Knowledge
      topK - maximum evidence count
      retriever - application-owned live retriever
      closeAction - application resource cleanup
      Returns:
      exact-owner-scoped live binding
      Since:
      0.14.0

    • live

      public static ChatKnowledgeBinding live(String ownerId, String sourceName, int topK, KnowledgeBase knowledgeBase)
      Creates a live binding over a KnowledgeBase the application owns and keeps mutating.

      The binding holds the corpus rather than copying it, so documents added after binding are visible to retrieval. Closing the binding does not close the corpus — that stays the application's to manage, which matters when the same corpus is rebound on every message.

      Retrieval is keyword-strategy, fail-open and uncached, matching what KnowledgeBase.search(String, int) actually does. sourceName is stamped on every piece of evidence as provenance and must be the name of the agent's MEMORY chat knowledge, or the agent refuses the binding.

      Parameters:
      ownerId - stable conversation-owner identity
      sourceName - declared chat source name
      topK - maximum evidence count
      knowledgeBase - application-owned corpus
      Returns:
      owner-scoped live binding over the corpus
      Since:
      0.16.0

    • ownerId

      public String ownerId()
      Returns the stable owner identity.

    • isOwnedBy

      public boolean isOwnedBy(Object owner)
      Returns whether this binding was created for the supplied exact owner.

      Bindings created without an exact owner always return false. Identity comparison deliberately ignores equals, display names, and string identifiers.

      Parameters:
      owner - candidate conversation owner
      Returns:
      true only for the exact bound owner object
      Since:
      0.14.0

    • sourceName

      public String sourceName()
      Returns the first canonical source name; see config() for all of them.

    • config

      public RetrievalConfig config()
      Returns the immutable chat retrieval configuration.

    • retrieve

      public RetrievalResult retrieve(String query, ChatRetrievalContext context)
      Retrieves evidence for one outbound chat request.
      Parameters:
      query - original user query
      context - request-local scope and lifecycle context
      Returns:
      canonical retrieval result

    • invalidate

      public long invalidate()
      Advances the owner-local source revision used by subsequent cache keys.
      Returns:
      the new revision

    • revision

      public long revision()
      Returns the current owner-local revision.

    • close

      public void close()
      Closes the owner-scoped engine exactly once.
      Specified by:
      close in interface AutoCloseable