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

    • undeclared

      public static ChatKnowledgeBinding undeclared(Object exactOwner, String ownerId, String sourceName, int topK, RetrievalEngine.Retriever retriever)
      Creates an exact-owner live binding that no @Knowledge declaration backs, with fail-open, no-cache defaults.

      Such a binding carries knowledge the integration supplies in code, such as an agent's conversation memory. A ChatTurn sent through SCOPBridge.sendToLLM in tnsai-integration searches it beside the owner's other bindings, at most one of them declared, as long as no two of them search the same source name. It is checked against its exact owner only, never against the owner's declarations, so sourceName names the binding's source rather than a declared entry, and the owner may declare no knowledge at all. Its evidence renders under the source name its retriever gives each result; the binding does not replace it with sourceName. ChatKnowledgeBindingValidator refuses it, so an agent, which searches declared knowledge only, does too.

      With a retrieval context, each send refuses the binding, throwing IllegalArgumentException, when its sourceName is the name of any @Knowledge its owner declares, whatever that knowledge's type or use and whether or not it is enabled; without a retrieval context only the owner is checked. A name of the integration's own, such as one under a prefix no declaration uses, keeps the binding usable for every owner class.

      The binding has the default context window of RetrievalConfig.Builder; undeclared(Object, String, String, int, int, RetrievalEngine.Retriever) gives it another. Beside the owner's other bindings each binding's evidence is rendered within its own window, so a turn can carry as many windows of evidence for one owner as the owner has bindings.

      Parameters:
      exactOwner - exact conversation owner object
      ownerId - stable owner identity used in retrieval metadata
      sourceName - source name of the binding, not of its evidence
      topK - maximum evidence count
      retriever - application-owned live retriever
      Returns:
      exact-owner-scoped undeclared live binding
      Since:
      0.18.6
      See Also:

    • undeclared

      public static ChatKnowledgeBinding undeclared(Object exactOwner, String ownerId, String sourceName, int topK, int contextWindow, RetrievalEngine.Retriever retriever)
      undeclared(Object, String, String, int, RetrievalEngine.Retriever) whose evidence is rendered within contextWindow estimated tokens instead of the default window of RetrievalConfig.Builder. The window bounds this binding's evidence only: the owner's other bindings keep their own.
      Parameters:
      exactOwner - exact conversation owner object
      ownerId - stable owner identity used in retrieval metadata
      sourceName - source name of the binding, not of its evidence
      topK - maximum evidence count
      contextWindow - maximum estimated tokens of this binding's evidence in one turn; positive
      retriever - application-owned live retriever
      Returns:
      exact-owner-scoped undeclared live binding
      Throws:
      IllegalArgumentException - if contextWindow is not positive
      Since:
      0.18.6
      See Also:

    • 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

    • isUndeclared

      public boolean isUndeclared()
      Returns whether no @Knowledge declaration backs this binding: whether it was created by undeclared(Object, String, String, int, RetrievalEngine.Retriever).
      Returns:
      true only for an undeclared binding
      Since:
      0.18.6

    • 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.

      The context's turn message, when present, is searched instead of query. It, the conversation identity and the source paths reach the request as its own components, not as metadata filters.

      Parameters:
      query - the user message the provider renders, searched when the context carries no turn message
      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