This article puts the two together. Two LLM calls clean up and multiply the user's question before retrieval. Jev then judges every retrieved chunk before it reaches the prompt. The whole pipeline is one advisor builder.
\n💡 Demo : The complete example is the 05-1-modular-rag module. It sits next to 05-rag, the naive version, so you can diff the two. Every output quoted below is from a live run.
The classic Spring AI RAG demo is a QuestionAnswerAdvisor over a vector store. It embeds the user's text, fetches similar chunks and stuffs them into the prompt. That works on stage and gets shaky in real life, for three reasons:
We will answer exactly that question over a Wikipedia PDF about Hurricane Milton, and fix each problem with one pluggable component.
\nThe RetrievalAugmentationAdvisor, from the spring-ai-rag module, implements the architecture described in Modular RAG: Transforming RAG Systems into LEGO-like Reconfigurable Frameworks. From the outside it is just another advisor: it sits between your prompt and the model, runs the retrieval phases, and appends the result to the user message. The system prompt and the question pass through untouched.
Inside, each phase is a small interface you can swap:
\nPhase\nSpring AI interface\nJob\nUsed in this demo
\nPre-retrieval\nQueryTransformer\nrewrite one query into a better one\nRewriteQueryTransformer
Pre-retrieval\nQueryExpander\nturn one query into several\nMultiQueryExpander
Retrieval\nDocumentRetriever\nfetch documents for one query\nVectorStoreDocumentRetriever
Retrieval\nDocumentJoiner\nmerge the results of all queries\nConcatenationDocumentJoiner (default)
Post-retrieval\nDocumentPostProcessor\nfilter, rerank or compress documents\nJevDocumentFilter, JevDocumentReranker
Generation\nQueryAugmenter\nput context and question into the prompt\nContextualQueryAugmenter
Here is the full flow for one call:
\nThe retrieval branches run in parallel, one per query, and are joined before post-processing. Note one subtle detail: the post-processors and the augmenter see the user's original question, not the rewritten one. The rewrite only exists to improve search.
\nAdd the Spring AI RAG module and the two TypeSafe artifacts from the previous article. Spring AI's BOM manages the first one:
\n\norg.springframework.ai\nspring-ai-rag\n\n\n\norg.springaicommunity\nspring-ai-starter-typesafe\n0.3.0\n\n\n\norg.springaicommunity\ntypesafe-spring-ai\n0.3.0\nThe starter auto-configures a TypeSafeClient bean from your API key:
spring.ai.typesafe.api-key=${TYPESAFE_API_KEY}The demo also uses spring-ai-pdf-document-reader for ingestion and spring-ai-starter-model-transformers for local embeddings.
Ingestion is the same as in any Spring AI RAG application: read the PDF, split it into chunks, store them.
\nvectorStore.add(\nTokenTextSplitter.builder().build().split(\nnew PagePdfDocumentReader(hurricaneDocs).read()));The interesting part is a single builder. Each numbered comment is one brick from the diagram:
\n// Separate builder for the LLM-backed stages, so they don't inherit the main client's advisors\nvar ragClientBuilder = chatClientBuilder.clone();\n\nvar modularRag = RetrievalAugmentationAdvisor.builder()\n// 1. Pre-retrieval: rewrite the chatty question into a search-friendly query\n.queryTransformers(RewriteQueryTransformer.builder()\n.chatClientBuilder(ragClientBuilder)\n.build())\n// 2. Pre-retrieval: expand it into several diverse queries (original included)\n.queryExpander(MultiQueryExpander.builder()\n.chatClientBuilder(ragClientBuilder)\n.numberOfQueries(3)\n.build())\n// 3. Retrieval: similarity search per query; the default joiner dedups the union\n.documentRetriever(VectorStoreDocumentRetriever.builder()\n.vectorStore(vectorStore)\n.similarityThreshold(0.5)\n.topK(4)\n.build())\n// 4. Post-retrieval: Jev drops bad passages, then reranks and keeps the top 3\n.documentPostProcessors(\nJevDocumentFilter.builder(typeSafeClient).build(),\nJevDocumentReranker.builder(typeSafeClient).topK(3).build())\n// 5. Generation: stuff the surviving context into the prompt\n.queryAugmenter(ContextualQueryAugmenter.builder()\n.allowEmptyContext(true)\n.build())\n.taskExecutor(taskExecutor) // see "Things to know" below\n.build();Using it looks like any other advisor:
\nString answer = chatClient.prompt()\n.advisors(modularRag)\n.user("I'm a Florida resident and heard a lot about storms last fall. "\n+ "Did Milton actually make landfall in my state, and where?")\n.call()\n.content();DocumentRetriever and DocumentPostProcessor are both single-method interfaces, so a lambda is enough to log what flows through the pipeline. The demo wraps the retriever and adds two printing post-processors around the Jev stages; that is where the output below comes from.
Both components send one Jev call per passage, with the query and the passage as the state , and turn the answers into a decision.
\nJevDocumentFilter asks four Noul questions about every passage and applies them in order:
Question\nDefault threshold\nOutcome
\ncontains_prompt_injection\nabove 0.70\nexcluded
contradicts_query_premise\nabove 0.70\nkept, tagged CONFLICTING
is_relevant\nbelow 0.45\nexcluded
contains_answer_evidence\nabove 0.55\nkept, otherwise excluded
This is the atomic questions idea from the previous article at work: four narrow questions, four thresholds, one call. Contradicting passages survive on purpose. If the user assumes something false, the model should see the evidence that says so. The classification is stored in the document metadata under jev.classification, and the thresholds are a Policy record you can override.
JevDocumentReranker asks a single question, could this passage answer the query? , sorts by the score and keeps the top K. The score lands in the metadata under jev.rerank.score. Its focus is deliberate: whether the passage states information that answers the query, not merely whether it covers the same subject . That is precisely the gap between similarity and usefulness.
Order matters. Filter first, so the reranker only pays for the survivors.
\nThe rewrite and expansion turned one chatty sentence into four focused searches:
\n[retrieve] Hurricane Milton 2024 Florida landfall location\n[retrieve] Hurricane Milton track path across Florida from Gulf Coast to Atlantic and National Hurricane Center landfall report\n[retrieve] Siesta Key Sarasota County Milton landfall timeline, storm surge, and areas impacted\n[retrieve] Where did Hurricane Milton make landfall in Florida in October 2024 and at what intensityThe joiner merged their results into six unique chunks, all above the 0.5 similarity threshold:
[retrieved] 0.84 Hurricane Milton ...\n[retrieved] 0.72 6. "Hurricane Milton Makes Landfall On Florida's West Coast ...\n[retrieved] 0.70 Hurricane Milton's landfall" (https://www.wesh.com/...\n[retrieved] 0.69 Archived (http ...\n[retrieved] 0.59 /news/tropical-storm-milton-forms-gulf-of-mexico ...\n[retrieved] 0.54 of Key West. [128] Across the state, about 125 homes were d...Four of them are reference-list entries and archive links. They mention Milton a lot and answer nothing. JevDocumentFilter excluded them for lacking answer evidence, and JevDocumentReranker scored the two survivors:
[jev-reranked] 0.97 Hurricane Milton ...\n[jev-reranked] 0.88 6. "Hurricane Milton Makes Landfall On Florida's West Coast ...So topK(3) returned only two chunks, and that is the point. The model got less context, all of it relevant:
Yes. Hurricane Milton made landfall in Florida, near Siesta Key, on the evening of\nOctober 9, 2024. It had weakened to a Category 3 hurricane by then.Vector similarity answers "what is this text about?" . Jev answers "does this text answer the question?" . A RAG pipeline needs both.
\nThe default executor keeps a command-line app alive. RetrievalAugmentationAdvisor runs per-query retrieval on its own thread pool, and those threads are non-daemon. The demo printed its answer and then hung. Passing Spring Boot's auto-configured TaskExecutor through .taskExecutor(...) fixes it, and with spring.threads.virtual.enabled=true you get virtual threads for free.
Newer Claude models reject temperature. The Spring AI docs recommend temperature 0 for query transformers. claude-sonnet-5-5 answers that with HTTP 400, so the demo clones the builder only to keep the main client's advisors out of the rewrite and expand calls.
Both Jev components fail open. If the Jev API is unreachable, passages pass through unscreened or unscored and a warning is logged. Your pipeline degrades to plain modular RAG instead of breaking.
\nEvery brick costs latency. This pipeline adds two LLM calls before retrieval and one Jev call per retrieved chunk after it. Jev calls run four at a time by default (batchOptions(...) changes that), but measure before you ship.
Modular RAG turns retrieval from one opaque advisor into a pipeline you can read, log and swap piece by piece. Here are the important insights:
\nDemo
\n05-1-modular-rag — the code in this article05-rag — the naive QuestionAnswerAdvisor version, for comparisonSpring AI
\nSpring AI TypeSafe
\nRelated Spring AI articles
\n","headings":[{"level":1,"text":"Spring AI Modular RAG and TypeSafe Jev: Retrieve More, Keep Only What Answers","id":"spring-ai-modular-rag-and-typesafe-jev-retrieve-more-keep-only-w"},{"level":2,"text":"Why Naive RAG Falls Short","id":"why-naive-rag-falls-short"},{"level":2,"text":"Modular RAG in Spring AI","id":"modular-rag-in-spring-ai"},{"level":2,"text":"Getting Started","id":"getting-started"},{"level":2,"text":"The Pipeline","id":"the-pipeline"},{"level":2,"text":"Jev in the Post-Retrieval Phase","id":"jev-in-the-post-retrieval-phase"},{"level":2,"text":"A Live Run","id":"a-live-run"},{"level":3,"text":"⚠️ Things to know","id":"things-to-know"},{"level":2,"text":"Conclusion","id":"conclusion"},{"level":2,"text":"Resources","id":"resources"}]}}