Package com.tnsai.intelligence.rag

package com.tnsai.intelligence.rag
RAG (Retrieval-Augmented Generation) strategy SPI.

Provides a pluggable RAGStrategy interface with six built-in implementations:

Graph retrieval uses the vendor-neutral GraphStoreProvider SPI. Providers supply seed and adjacency data while the framework owns traversal depth, cycle handling, path scoring, ranking, and provenance. When tnsai-tools is installed, live KnowledgeTools triples are that seed and adjacency data through KnowledgeToolsGraphStoreProvider; kg_add_triple is not a second graph. Graph retrieval never falls back to vector retrieval. Because the provider is selected by the annotation and the installed classpath rather than by request data, missing or ambiguous graph capability is a configuration error: it fails the action at dispatch time, above the @Search.onFailure guard, so no policy can turn it into an empty result or a stale cache entry. Only failures the provider raises while traversing are routed through the configured retrieval failure policy.

Hierarchical retrieval uses child semantic hits only as selectors, then expands canonical parent relationships from HierarchyMetadata. Flat indexes remain explicit in result provenance. A malformed hierarchy — a duplicate ID, a dangling parent, a cycle — is a configuration fault and fails the action above the @Search.onFailure guard, so no failure policy can turn it into a silently ungrounded action; retrieval never silently degrades to plain vector results.

Temporal retrieval keeps semantic relevance dominant while applying an exponential freshness component. Loaders supply canonical timestamps through TemporalMetadata. Undated documents receive a conservative relevance floor and small future-clock skew is clamped with provenance. A duplicate entry ID or an unparseable timestamp is configuration, so TemporalIndex.validate() rejects it at strategy-selection time, above @Search.onFailure; only clock-relative faults, such as a timestamp beyond the tolerated future skew, reach the guard. It never silently degrades to vector results.

RAGPipeline orchestrates the full flow: preprocess query, retrieve documents, rerank, and format context for LLM injection.

Query-aware reranking is provided by the Reranker SPI. The framework ships the provider boundary but no built-in cross-encoder implementation. Provider modules register supported model identifiers through ServiceLoader. Because the model identifier is annotation configuration rather than request data, an unavailable or ambiguous model is a configuration error: it fails the action at dispatch time instead of silently keeping the original order or dropping the retrieved context. Only failures the provider raises while ranking are routed through the configured retrieval failure policy.

Action-level retrieval results can be cached with @Search(cache = true, cacheTTL = ...). Each Role binding owns a bounded in-memory cache. Keys contain a digest rather than raw query text, and cached documents are defensively copied across callers.

A binding — its loaded documents, its indexes, and that cache — is built once per Role class per JVM and kept for the process lifetime, so cacheTTL is not what governs corpus freshness: an expired entry is recomputed against the same immutable index and yields the same documents. When every corpus owned by a Role changes, call RoleRagBinding.invalidate(Class). When exactly one canonical source changes, call RoleRagBinding.invalidate(Class, String); ranked bindings containing that source rebuild while sibling bindings and sibling sequential cursors retain identity and position. The next dispatch performs the re-read. Nothing re-reads sources on its own.

Strategies are discoverable via ServiceLoader using the META-INF/services/com.tnsai.intelligence.rag.RAGStrategy SPI registration.

Since:
0.2.4