Package com.tnsai.intelligence.rag.binding

Class RagDiagnostics

java.lang.Object

com.tnsai.intelligence.rag.binding.RagDiagnostics

public final class RagDiagnostics
extends Object

Read-only snapshot of what a Role's @Knowledge and @Search declarations resolved to.

RAG fails as plausible-but-worse answers more often than as an exception. This is the question a developer asks after the binding exists: which embedding is actually in use, which SPI providers are installed, and what the corpus looks like. It is not a telemetry surface and does not announce itself.

Stable typed accessors

The following are the supported surface:

• roleClass()
• embeddingType()
• bundledHashFallback() — the question this type exists to answer
• reranker(), queryExpander(), graphStore()
• sources()
• retrieval()

report() is unstable human-readable text for pasting into an issue. Do not parse it.

Binding construction

of(Class) never ingests. It snapshots a binding already in the Role cache, and fails if none exists. Pass ingestIfAbsent=true only when the caller is willing to pay corpus ingest as the price of asking.

Since:

0.15.0

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final record	RagDiagnostics.ProviderStatus	Installed SPI providers for one unbundled seam.
static final record	RagDiagnostics.RetrievalDeclaration	One @Search declaration on the Role.
static final record	RagDiagnostics.SourceSnapshot	Ingest snapshot for one declared knowledge source.

Method Summary

Modifier and Type	Method	Description
boolean	bundledHashFallback()	true when retrieval is using the bundled hash embedding, which ranks by token overlap rather than meaning.
String	embeddingType()	Fully-qualified type of the resolved embedding function, after unwrapping the registry's validating decorator.
RagDiagnostics.ProviderStatus	graphStore()	Installed graph-store providers, or empty when none.
static RagDiagnostics	of(RoleRagBinding binding)	Provider lists are a fresh SPI discovery. They report what RerankerRegistry.discover() and friends find on the classpath now — not the registries this binding actually resolved against.
static RagDiagnostics	of(Class<?> roleClass)	Snapshot of the cached binding for roleClass.
static RagDiagnostics	of(Class<?> roleClass, boolean ingestIfAbsent)	Snapshot of the binding for roleClass.
static RagDiagnostics	of(Class<?> roleClass, List<com.tnsai.rag.KnowledgeSourceConfig> builderSources, boolean ingestIfAbsent)	Snapshot of the binding for roleClass built with builderSources.
RagDiagnostics.ProviderStatus	queryExpander()	Installed query-expander providers, or empty when none.
String	report()	Unstable human-readable text.
RagDiagnostics.ProviderStatus	reranker()	Installed reranker providers, or empty when none.
List<RagDiagnostics.RetrievalDeclaration>	retrieval()	Type-level and method-level @Search declarations on the Role.
Class<?>	roleClass()	Role this snapshot describes.
List<RagDiagnostics.SourceSnapshot>	sources()	Per-source ingest snapshot, in declaration order.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

of

public static RagDiagnostics of(RoleRagBinding binding)

Provider lists are a fresh SPI discovery. They report what RerankerRegistry.discover() and friends find on the classpath now — not the registries this binding actually resolved against. An application that injects its own registries can therefore see names here it does not use, and miss ones it does. Use the package-private overload with explicit ProviderStatus values when the injected registries are in reach.

of

public static RagDiagnostics of(Class<?> roleClass)

Snapshot of the cached binding for roleClass. Does not ingest; fails if RoleRagBinding.forRole(Class) has not run for this Role.

Parameters:

roleClass - Role whose binding to describe

Returns:

diagnostic over the cached binding

of

public static RagDiagnostics of(Class<?> roleClass,
 boolean ingestIfAbsent)

Snapshot of the binding for roleClass.

Parameters:

roleClass - Role whose binding to describe

ingestIfAbsent - true constructs the binding (ingests the corpus) when none is cached. false fails if the Role has not been bound yet

Returns:

diagnostic over the binding

of

public static RagDiagnostics of(Class<?> roleClass,
 List<com.tnsai.rag.KnowledgeSourceConfig> builderSources,
 boolean ingestIfAbsent)

Snapshot of the binding for roleClass built with builderSources.

The binding cache is keyed on the pair, not on the Role alone. An application that binds through RoleRagBinding.forRole(role, sources) has no entry under the empty list, so the no-sources overload cannot find it — it would report "no binding cached" for a Role that is bound and running, and a caller following that advice with ingestIfAbsent=true would build a second, annotation-only binding, pay a full corpus ingest, and then be shown a configuration the application is not using. Pass the same sources here that were passed to forRole.

Parameters:

roleClass - Role whose binding to describe

builderSources - sources the binding was built with; must equal what was passed to RoleRagBinding.forRole

ingestIfAbsent - true constructs the binding (ingests the corpus) when none is cached. false fails if the Role has not been bound with these sources

Returns:

diagnostic over the binding

Since:

0.15.0

roleClass

public Class<?> roleClass()

Role this snapshot describes.

embeddingType

public String embeddingType()

Fully-qualified type of the resolved embedding function, after unwrapping the registry's validating decorator.

bundledHashFallback

public boolean bundledHashFallback()

true when retrieval is using the bundled hash embedding, which ranks by token overlap rather than meaning.

reranker

public RagDiagnostics.ProviderStatus reranker()

Installed reranker providers, or empty when none. Never throws.

queryExpander

public RagDiagnostics.ProviderStatus queryExpander()

Installed query-expander providers, or empty when none. Never throws.

graphStore

public RagDiagnostics.ProviderStatus graphStore()

Installed graph-store providers, or empty when none. Never throws.

sources

public List<RagDiagnostics.SourceSnapshot> sources()

Per-source ingest snapshot, in declaration order.

retrieval

public List<RagDiagnostics.RetrievalDeclaration> retrieval()

Type-level and method-level @Search declarations on the Role. Empty when the Role declares none.

report

public String report()

Unstable human-readable text. Shape and wording may change without notice; use the typed accessors from tests and health endpoints.

Returns:

diagnostic report