From ae8fe985b484f6cca42a575f41d7c96d7ace6075 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 00:55:16 +0530 Subject: [PATCH] Add advanced-rag module: Easy RAG, query compression and expansion, routing, minScore, content injection, chat-memory cost and sources, each with a captured transcript Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_017ic4b85ApxQRK2Z8yuzC5r --- README.md | 3 + advanced-rag/output/01-easy-rag.txt | 35 ++ advanced-rag/output/02-naive-follow-up.txt | 12 + advanced-rag/output/03-compression.txt | 83 +++ advanced-rag/output/04-expansion.txt | 62 +++ advanced-rag/output/05-routing.txt | 23 + advanced-rag/output/06-injection.txt | 42 ++ advanced-rag/output/07-min-score.txt | 51 ++ advanced-rag/output/08-full-pipeline.txt | 34 ++ advanced-rag/output/09-loader-trap.txt | 3 + advanced-rag/output/10-sources.txt | 4 + advanced-rag/output/11-defaults.txt | 4 + advanced-rag/pom.xml | 63 +++ .../lc4j/advancedrag/KnowledgeBase.java | 46 ++ .../ankurm/lc4j/advancedrag/Pipelines.java | 109 ++++ .../lc4j/advancedrag/ScriptedChatModel.java | 63 +++ .../lc4j/advancedrag/SourcedAssistant.java | 8 + .../lc4j/advancedrag/SupportAssistant.java | 6 + .../resources/kb/engineering/deployments.txt | 7 + .../resources/kb/engineering/rate-limits.txt | 7 + .../resources/kb/engineering/webhooks.txt | 7 + .../resources/kb/support/account-security.txt | 7 + .../resources/kb/support/hardware-returns.txt | 7 + .../resources/kb/support/refund-policy.txt | 7 + .../lc4j/advancedrag/AdvancedRagTest.java | 478 ++++++++++++++++++ .../ankurm/lc4j/advancedrag/Transcript.java | 23 + pom.xml | 1 + 27 files changed, 1195 insertions(+) create mode 100644 advanced-rag/output/01-easy-rag.txt create mode 100644 advanced-rag/output/02-naive-follow-up.txt create mode 100644 advanced-rag/output/03-compression.txt create mode 100644 advanced-rag/output/04-expansion.txt create mode 100644 advanced-rag/output/05-routing.txt create mode 100644 advanced-rag/output/06-injection.txt create mode 100644 advanced-rag/output/07-min-score.txt create mode 100644 advanced-rag/output/08-full-pipeline.txt create mode 100644 advanced-rag/output/09-loader-trap.txt create mode 100644 advanced-rag/output/10-sources.txt create mode 100644 advanced-rag/output/11-defaults.txt create mode 100644 advanced-rag/pom.xml create mode 100644 advanced-rag/src/main/java/com/ankurm/lc4j/advancedrag/KnowledgeBase.java create mode 100644 advanced-rag/src/main/java/com/ankurm/lc4j/advancedrag/Pipelines.java create mode 100644 advanced-rag/src/main/java/com/ankurm/lc4j/advancedrag/ScriptedChatModel.java create mode 100644 advanced-rag/src/main/java/com/ankurm/lc4j/advancedrag/SourcedAssistant.java create mode 100644 advanced-rag/src/main/java/com/ankurm/lc4j/advancedrag/SupportAssistant.java create mode 100644 advanced-rag/src/main/resources/kb/engineering/deployments.txt create mode 100644 advanced-rag/src/main/resources/kb/engineering/rate-limits.txt create mode 100644 advanced-rag/src/main/resources/kb/engineering/webhooks.txt create mode 100644 advanced-rag/src/main/resources/kb/support/account-security.txt create mode 100644 advanced-rag/src/main/resources/kb/support/hardware-returns.txt create mode 100644 advanced-rag/src/main/resources/kb/support/refund-policy.txt create mode 100644 advanced-rag/src/test/java/com/ankurm/lc4j/advancedrag/AdvancedRagTest.java create mode 100644 advanced-rag/src/test/java/com/ankurm/lc4j/advancedrag/Transcript.java diff --git a/README.md b/README.md index 813ea83..23cca14 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,7 @@ the same facts, so the build fails when a claim stops being true. | `ai-services` | LangChain4j AI Services with Spring Boot 4: Declarative LLM Interfaces | prompt templates, chat memory, tools, RAG, and the `@MemoryId` trap | | `spring-boot-ai-service` | same post | `@AiService` on Spring Boot 4.1.1 with the 1.22.0-beta32 starter | | `agentic` | Agentic Workflows with LangChain4j: Sequential, Parallel, Loop and Supervisor Agents | the five workflow builders, state passing by key, supervisor JSON, error recovery | +| `advanced-rag` | Advanced RAG with LangChain4j: Query Transformation, Routing and Easy RAG | Easy RAG, query compression and expansion, query routing, minScore, content injection, chat-memory cost, `Result.sources()` | ## Versions (verified on Maven Central, 2026-10-11) @@ -20,6 +21,8 @@ the same facts, so the build fails when a claim stops being true. | JDK | 25 LTS | | | JUnit | 6.1.3 | | +`advanced-rag` is built against LangChain4j **1.23.0** (`langchain4j-easy-rag` and the bundled bge-small embeddings are `1.23.0-beta33`, published to Maven Central on 2026-10-28; neither has a GA release). It overrides the 1.22.0 BOM above for that module only. + ## Run ```bash diff --git a/advanced-rag/output/01-easy-rag.txt b/advanced-rag/output/01-easy-rag.txt new file mode 100644 index 0000000..9266d6b --- /dev/null +++ b/advanced-rag/output/01-easy-rag.txt @@ -0,0 +1,35 @@ +Easy RAG ingestion of kb/ (6 files) + segments stored: 6 + +Retrieved for "How long are webhooks retried?": + 0.873 webhooks.txt + 0.820 refund-policy.txt + 0.811 account-security.txt + +User message the LLM actually received: +How long are webhooks retried? + +Answer using the following information: +Acme Cloud Webhooks + +Every webhook delivery is signed. The signature is sent in the X-Acme-Signature header and is an HMAC-SHA256 of the raw request body using your endpoint secret. Reject any delivery whose signature does not match. + +If your endpoint does not answer with a 2xx status within 10 seconds, the delivery is retried up to 8 times with exponential backoff. The retries are spread over 24 hours. After the last failed attempt the endpoint is marked as failing and an email is sent to the organisation owner. + +Deliveries can arrive more than once and out of order, so handlers must be idempotent. Use the event id to deduplicate. + +Acme Cloud Refund Policy + +Annual plans can be refunded in full within 30 days of purchase. Monthly plans can be refunded within 7 days of the first charge. After those windows, no refund is issued, but you can cancel at any time and keep access until the end of the paid period. + +Once a refund is approved, it takes 5 to 10 business days to appear on your card statement. The time depends on your bank, not on Acme Cloud. Refunds always go back to the original payment method; we cannot pay them out to a different card. + +If a refund does not show up after 10 business days, contact support with the invoice number so we can send you the acquirer reference number. + +Acme Cloud Account Security + +Password reset links expire after 30 minutes and can be used only once. If a link has expired, request a new one from the sign-in page. + +Two-factor authentication is mandatory for organisation owners. Supported methods are authenticator apps and hardware security keys. SMS codes are not supported. + +SSO via SAML 2.0 is available on the Business plan. After SSO is enforced, password sign-in is disabled for every member except the organisation owner, who keeps a break-glass login. diff --git a/advanced-rag/output/02-naive-follow-up.txt b/advanced-rag/output/02-naive-follow-up.txt new file mode 100644 index 0000000..ded2c0e --- /dev/null +++ b/advanced-rag/output/02-naive-follow-up.txt @@ -0,0 +1,12 @@ +Turn 1: "What is the refund window for annual plans?" +Turn 2 (follow-up): "How long does it take to show up?" + +Naive RAG searches with the follow-up exactly as typed: + 0.821 hardware-returns.txt + 0.817 deployments.txt + 0.816 refund-policy.txt + +Searching with a self-contained rewrite instead ("How long does a refund for an annual plan take to show up on my card?"): + 0.918 refund-policy.txt + 0.857 hardware-returns.txt + 0.795 deployments.txt diff --git a/advanced-rag/output/03-compression.txt b/advanced-rag/output/03-compression.txt new file mode 100644 index 0000000..8653e73 --- /dev/null +++ b/advanced-rag/output/03-compression.txt @@ -0,0 +1,83 @@ +Rewriter LLM calls after turn 1: 0 +Rewriter LLM calls after turn 2: 1 + +Prompt CompressingQueryTransformer sent to the rewriter on turn 2: +Read and understand the conversation between the User and the AI. Then, analyze the new query from the User. Identify all relevant details, terms, and context from both the conversation and the new query. Reformulate this query into a clear, concise, and self-contained format suitable for information retrieval. + +Conversation: +User: What is the refund window for annual plans? + +Answer using the following information: +Acme Cloud Refund Policy + +Annual plans can be refunded in full within 30 days of purchase. Monthly plans can be refunded within 7 days of the first charge. After those windows, no refund is issued, but you can cancel at any time and keep access until the end of the paid period. + +Once a refund is approved, it takes 5 to 10 business days to appear on your card statement. The time depends on your bank, not on Acme Cloud. Refunds always go back to the original payment method; we cannot pay them out to a different card. + +If a refund does not show up after 10 business days, contact support with the invoice number so we can send you the acquirer reference number. + +Acme Edge Box Hardware Returns + +The Acme Edge Box can be returned within 45 days of delivery if it is in its original packaging. Request a return label from the support portal; the label is valid for 14 days. + +After our warehouse receives the box, the refund is processed within 3 business days. It then follows the normal card timeline of 5 to 10 business days. + +Boxes that arrive damaged or with missing power adapters are inspected first, which can add up to 5 business days. + +Acme Cloud Deployments + +A standard deployment takes about 4 minutes from push to live. The first 5 percent of traffic goes to the new version as a canary for 2 minutes before the rest is shifted. + +A rollback takes about 30 seconds because the previous version stays warm for one hour after every deployment. After that hour, a rollback is a normal 4 minute deployment of the older build. + +Deployments are blocked automatically when the error rate of the canary is more than 2 percent above the baseline. +AI: (scripted answer) + +User query: How long does it take to show up? + +It is very important that you provide only reformulated query and nothing else! Do not prepend a query with anything! + +User message the answering LLM received on turn 2: +How long does it take to show up? + +Answer using the following information: +Acme Cloud Refund Policy + +Annual plans can be refunded in full within 30 days of purchase. Monthly plans can be refunded within 7 days of the first charge. After those windows, no refund is issued, but you can cancel at any time and keep access until the end of the paid period. + +Once a refund is approved, it takes 5 to 10 business days to appear on your card statement. The time depends on your bank, not on Acme Cloud. Refunds always go back to the original payment method; we cannot pay them out to a different card. + +If a refund does not show up after 10 business days, contact support with the invoice number so we can send you the acquirer reference number. + +Acme Edge Box Hardware Returns + +The Acme Edge Box can be returned within 45 days of delivery if it is in its original packaging. Request a return label from the support portal; the label is valid for 14 days. + +After our warehouse receives the box, the refund is processed within 3 business days. It then follows the normal card timeline of 5 to 10 business days. + +Boxes that arrive damaged or with missing power adapters are inspected first, which can add up to 5 business days. + +Acme Cloud Deployments + +A standard deployment takes about 4 minutes from push to live. The first 5 percent of traffic goes to the new version as a canary for 2 minutes before the rest is shifted. + +A rollback takes about 30 seconds because the previous version stays warm for one hour after every deployment. After that hour, a rollback is a normal 4 minute deployment of the older build. + +Deployments are blocked automatically when the error rate of the canary is more than 2 percent above the baseline. + +Rewriter prompt size in characters, turn 2 / 3 / 4: 2256 / 3998 / 5748 + +With storeRetrievedContentInChatMemory(false), turn 2 / 3 / 4: 565 / 616 / 675 + +Prompt sent to the rewriter on turn 2 with storeRetrievedContentInChatMemory(false): +Read and understand the conversation between the User and the AI. Then, analyze the new query from the User. Identify all relevant details, terms, and context from both the conversation and the new query. Reformulate this query into a clear, concise, and self-contained format suitable for information retrieval. + +Conversation: +User: What is the refund window for annual plans? +AI: (scripted answer) + +User query: How long does it take to show up? + +It is very important that you provide only reformulated query and nothing else! Do not prepend a query with anything! + +User message the answering LLM still received on turn 4 (augmented: true) diff --git a/advanced-rag/output/04-expansion.txt b/advanced-rag/output/04-expansion.txt new file mode 100644 index 0000000..40be257 --- /dev/null +++ b/advanced-rag/output/04-expansion.txt @@ -0,0 +1,62 @@ +=== Case 1: a query whose wording misses the document === +Original query: I shipped a bad release, can I undo it? +Single-query top 3: + 0.807 hardware-returns.txt + 0.790 webhooks.txt + 0.780 refund-policy.txt + +Queries produced: 3 + + "How can I revert a faulty release?" + 0.798 deployments.txt + 0.781 hardware-returns.txt + 0.779 refund-policy.txt + + "Is it possible to roll back a bad deployment?" + 0.858 deployments.txt + 0.779 webhooks.txt + 0.776 refund-policy.txt + + "What is the way to reverse a release that went wrong?" + 0.788 deployments.txt + 0.779 refund-policy.txt + 0.774 hardware-returns.txt + +After DefaultContentAggregator (reciprocal rank fusion): 4 unique segments, in this order: + deployments.txt + refund-policy.txt + hardware-returns.txt + webhooks.txt + +=== Case 2: a query that was already fine === +Original query: How do I get my money back? +Single-query top 3: + 0.852 refund-policy.txt + 0.804 hardware-returns.txt + 0.763 webhooks.txt + +Queries produced: 3 + + "What is the process for requesting a refund?" + 0.866 refund-policy.txt + 0.818 hardware-returns.txt + 0.787 webhooks.txt + + "How can I be reimbursed for a purchase?" + 0.852 refund-policy.txt + 0.805 hardware-returns.txt + 0.764 webhooks.txt + + "Steps to cancel and receive a refund" + 0.872 refund-policy.txt + 0.817 hardware-returns.txt + 0.797 webhooks.txt + +After DefaultContentAggregator (reciprocal rank fusion): 3 unique segments, in this order: + refund-policy.txt + hardware-returns.txt + webhooks.txt + +Prompt ExpandingQueryTransformer sent to the expander: +Generate 3 different versions of a provided user query. Each version should be worded differently, using synonyms or alternative sentence structures, but they should all retain the original meaning. These versions will be used to retrieve relevant documents. It is very important to provide each query version on a separate line, without enumerations, hyphens, or any additional formatting! +User query: I shipped a bad release, can I undo it? diff --git a/advanced-rag/output/05-routing.txt b/advanced-rag/output/05-routing.txt new file mode 100644 index 0000000..b74e67b --- /dev/null +++ b/advanced-rag/output/05-routing.txt @@ -0,0 +1,23 @@ +Query: How long are webhooks retried? + +Searching the single merged store: + 0.873 webhooks.txt + 0.820 refund-policy.txt + 0.811 account-security.txt + +Prompt LanguageModelQueryRouter sent to the router LLM: +Based on the user query, determine the most suitable data source(s) to retrieve relevant information from the following options: +1: Billing, refunds, hardware returns and account security for customers +2: API rate limits, deployments and webhooks for developers +It is very important that your answer consists of either a single number or multiple numbers separated by commas and nothing else! +User query: How long are webhooks retried? + +Router LLM answered "2" -> retrievers chosen: 1 + 0.873 webhooks.txt + 0.802 deployments.txt + 0.786 rate-limits.txt + +Router LLM answered "The engineering one, I think.": + default fallback strategy -> retrievers chosen: 0 + ROUTE_TO_ALL -> retrievers chosen: 2 + FAIL -> java.lang.RuntimeException: java.lang.NumberFormatException: For input string: "The engineering one" diff --git a/advanced-rag/output/06-injection.txt b/advanced-rag/output/06-injection.txt new file mode 100644 index 0000000..a56b275 --- /dev/null +++ b/advanced-rag/output/06-injection.txt @@ -0,0 +1,42 @@ +Default injector: +How long are webhooks retried? + +Answer using the following information: +Acme Cloud Webhooks + +Every webhook delivery is signed. The signature is sent in the X-Acme-Signature header and is an HMAC-SHA256 of the raw request body using your endpoint secret. Reject any delivery whose signature does not match. + +If your endpoint does not answer with a 2xx status within 10 seconds, the delivery is retried up to 8 times with exponential backoff. The retries are spread over 24 hours. After the last failed attempt the endpoint is marked as failing and an email is sent to the organisation owner. + +Deliveries can arrive more than once and out of order, so handlers must be idempotent. Use the event id to deduplicate. + +Acme Cloud Refund Policy + +Annual plans can be refunded in full within 30 days of purchase. Monthly plans can be refunded within 7 days of the first charge. After those windows, no refund is issued, but you can cancel at any time and keep access until the end of the paid period. + +Once a refund is approved, it takes 5 to 10 business days to appear on your card statement. The time depends on your bank, not on Acme Cloud. Refunds always go back to the original payment method; we cannot pay them out to a different card. + +If a refund does not show up after 10 business days, contact support with the invoice number so we can send you the acquirer reference number. + +Custom template + metadataKeysToInclude(["file_name"]): +How long are webhooks retried? + +Answer ONLY from the sources below. If they do not contain the answer, say you do not know. + +content: Acme Cloud Webhooks + +Every webhook delivery is signed. The signature is sent in the X-Acme-Signature header and is an HMAC-SHA256 of the raw request body using your endpoint secret. Reject any delivery whose signature does not match. + +If your endpoint does not answer with a 2xx status within 10 seconds, the delivery is retried up to 8 times with exponential backoff. The retries are spread over 24 hours. After the last failed attempt the endpoint is marked as failing and an email is sent to the organisation owner. + +Deliveries can arrive more than once and out of order, so handlers must be idempotent. Use the event id to deduplicate. +file_name: webhooks.txt + +content: Acme Cloud Refund Policy + +Annual plans can be refunded in full within 30 days of purchase. Monthly plans can be refunded within 7 days of the first charge. After those windows, no refund is issued, but you can cancel at any time and keep access until the end of the paid period. + +Once a refund is approved, it takes 5 to 10 business days to appear on your card statement. The time depends on your bank, not on Acme Cloud. Refunds always go back to the original payment method; we cannot pay them out to a different card. + +If a refund does not show up after 10 business days, contact support with the invoice number so we can send you the acquirer reference number. +file_name: refund-policy.txt diff --git a/advanced-rag/output/07-min-score.txt b/advanced-rag/output/07-min-score.txt new file mode 100644 index 0000000..8138ac7 --- /dev/null +++ b/advanced-rag/output/07-min-score.txt @@ -0,0 +1,51 @@ +Off-topic: What is the capital of France? +minScore 0.0 (default): + 0.696 deployments.txt + 0.670 rate-limits.txt + 0.669 account-security.txt +minScore 0.75: + (nothing) + +Message sent to the LLM with minScore 0.0: +What is the capital of France? + +Answer using the following information: +Acme Cloud Deployments + +A standard deployment takes about 4 minutes from push to live. The first 5 percent of traffic goes to the new version as a canary for 2 minutes before the rest is shifted. + +A rollback takes about 30 seconds because the previous version stays warm for one hour after every deployment. After that hour, a rollback is a normal 4 minute deployment of the older build. + +Deployments are blocked automatically when the error rate of the canary is more than 2 percent above the baseline. + +Acme Cloud API Rate Limits + +Every API key is limited to 600 requests per minute, with a burst allowance of 100 requests per second. Requests over the limit receive HTTP 429 with a Retry-After header giving the number of seconds to wait. + +Limits are per key, not per organisation, so a noisy integration cannot starve the others. Batch endpoints count as one request regardless of how many items they contain. + +To raise a limit, open a ticket with the key id and the peak traffic you expect. Increases are applied within one business day. + +Acme Cloud Account Security + +Password reset links expire after 30 minutes and can be used only once. If a link has expired, request a new one from the sign-in page. + +Two-factor authentication is mandatory for organisation owners. Supported methods are authenticator apps and hardware security keys. SMS codes are not supported. + +SSO via SAML 2.0 is available on the Business plan. After SSO is enforced, password sign-in is disabled for every member except the organisation owner, who keeps a break-glass login. + +Message sent to the LLM with minScore 0.75: +What is the capital of France? + +On-topic: How long does a refund take to show up on my card? +minScore 0.0: + 0.906 refund-policy.txt + 0.868 hardware-returns.txt + 0.782 webhooks.txt +minScore 0.75: + 0.906 refund-policy.txt + 0.868 hardware-returns.txt + 0.782 webhooks.txt +minScore 0.85: + 0.906 refund-policy.txt + 0.868 hardware-returns.txt diff --git a/advanced-rag/output/08-full-pipeline.txt b/advanced-rag/output/08-full-pipeline.txt new file mode 100644 index 0000000..01177e5 --- /dev/null +++ b/advanced-rag/output/08-full-pipeline.txt @@ -0,0 +1,34 @@ +LLM calls per turn (compress + route + answer): + turn 1 rewriter=0 router=1 answer=1 + turn 2 rewriter=1 router=1 answer=1 + +User message the answering LLM received on turn 2: +How long does it take to show up? + +Answer using the following information: +content: Acme Cloud Refund Policy + +Annual plans can be refunded in full within 30 days of purchase. Monthly plans can be refunded within 7 days of the first charge. After those windows, no refund is issued, but you can cancel at any time and keep access until the end of the paid period. + +Once a refund is approved, it takes 5 to 10 business days to appear on your card statement. The time depends on your bank, not on Acme Cloud. Refunds always go back to the original payment method; we cannot pay them out to a different card. + +If a refund does not show up after 10 business days, contact support with the invoice number so we can send you the acquirer reference number. +file_name: refund-policy.txt + +content: Acme Edge Box Hardware Returns + +The Acme Edge Box can be returned within 45 days of delivery if it is in its original packaging. Request a return label from the support portal; the label is valid for 14 days. + +After our warehouse receives the box, the refund is processed within 3 business days. It then follows the normal card timeline of 5 to 10 business days. + +Boxes that arrive damaged or with missing power adapters are inspected first, which can add up to 5 business days. +file_name: hardware-returns.txt + +content: Acme Cloud Account Security + +Password reset links expire after 30 minutes and can be used only once. If a link has expired, request a new one from the sign-in page. + +Two-factor authentication is mandatory for organisation owners. Supported methods are authenticator apps and hardware security keys. SMS codes are not supported. + +SSO via SAML 2.0 is available on the Business plan. After SSO is enforced, password sign-in is disabled for every member except the organisation owner, who keeps a break-glass login. +file_name: account-security.txt diff --git a/advanced-rag/output/09-loader-trap.txt b/advanced-rag/output/09-loader-trap.txt new file mode 100644 index 0000000..e9eed8f --- /dev/null +++ b/advanced-rag/output/09-loader-trap.txt @@ -0,0 +1,3 @@ +loadDocuments("kb") -> 0 documents +loadDocumentsRecursively("kb") -> 6 documents +ingest(flat, store) -> java.lang.IllegalArgumentException: segments cannot be null or empty diff --git a/advanced-rag/output/10-sources.txt b/advanced-rag/output/10-sources.txt new file mode 100644 index 0000000..1d2f917 --- /dev/null +++ b/advanced-rag/output/10-sources.txt @@ -0,0 +1,4 @@ +answer: (scripted answer) +sources: + 0.873 webhooks.txt + 0.820 refund-policy.txt diff --git a/advanced-rag/output/11-defaults.txt b/advanced-rag/output/11-defaults.txt new file mode 100644 index 0000000..d276d94 --- /dev/null +++ b/advanced-rag/output/11-defaults.txt @@ -0,0 +1,4 @@ +EmbeddingStoreContentRetriever.DEFAULT_MAX_RESULTS = 3 +EmbeddingStoreContentRetriever.DEFAULT_MIN_SCORE = 0.0 +ExpandingQueryTransformer.DEFAULT_N = 3 +LanguageModelQueryRouter.FallbackStrategy = [DO_NOT_ROUTE, ROUTE_TO_ALL, FAIL] diff --git a/advanced-rag/pom.xml b/advanced-rag/pom.xml new file mode 100644 index 0000000..29ff077 --- /dev/null +++ b/advanced-rag/pom.xml @@ -0,0 +1,63 @@ + + + 4.0.0 + + + com.ankurm.langchain4j + langchain4j-demo + 1.0.0 + + + advanced-rag + + + + 1.23.0 + 1.23.0-beta33 + + + + + + + dev.langchain4j + langchain4j-bom + ${lc4j.rag.version} + pom + import + + + + + + + dev.langchain4j + langchain4j + + + + dev.langchain4j + langchain4j-easy-rag + ${lc4j.rag.beta.version} + + + org.slf4j + slf4j-simple + ${slf4j.version} + test + + + org.junit.jupiter + junit-jupiter + test + + + org.assertj + assertj-core + ${assertj.version} + test + + + diff --git a/advanced-rag/src/main/java/com/ankurm/lc4j/advancedrag/KnowledgeBase.java b/advanced-rag/src/main/java/com/ankurm/lc4j/advancedrag/KnowledgeBase.java new file mode 100644 index 0000000..3bb3379 --- /dev/null +++ b/advanced-rag/src/main/java/com/ankurm/lc4j/advancedrag/KnowledgeBase.java @@ -0,0 +1,46 @@ +package com.ankurm.lc4j.advancedrag; + +import dev.langchain4j.data.document.Document; +import dev.langchain4j.data.document.loader.ClassPathDocumentLoader; +import dev.langchain4j.data.segment.TextSegment; +import dev.langchain4j.model.embedding.EmbeddingModel; +import dev.langchain4j.model.embedding.onnx.bgesmallenv15q.BgeSmallEnV15QuantizedEmbeddingModel; +import dev.langchain4j.store.embedding.EmbeddingStore; +import dev.langchain4j.store.embedding.EmbeddingStoreIngestor; +import dev.langchain4j.store.embedding.IngestionResult; +import dev.langchain4j.store.embedding.inmemory.InMemoryEmbeddingStore; + +import java.util.List; + +/** + * Easy RAG in one class: load files from the classpath, let EmbeddingStoreIngestor split and embed + * them with the defaults the langchain4j-easy-rag module registers, and keep the vectors in memory. + */ +public final class KnowledgeBase { + + /** The same quantized bge-small model Easy RAG picks by default. Created once: loading the ONNX model is slow. */ + public static final EmbeddingModel EMBEDDING_MODEL = new BgeSmallEnV15QuantizedEmbeddingModel(); + + private final EmbeddingStore store = new InMemoryEmbeddingStore<>(); + private final IngestionResult ingestion; + + private KnowledgeBase(String classpathDir) { + List documents = ClassPathDocumentLoader.loadDocumentsRecursively(classpathDir); + // The static ingest(documents, store) is the "Easy RAG" call: no splitter, no embedding model + // configured here. It finds a splitter through a service-provider file in the easy-rag jar and an + // embedding model through one in the bge-small jar. + this.ingestion = EmbeddingStoreIngestor.ingest(documents, store); + } + + public static KnowledgeBase load(String classpathDir) { + return new KnowledgeBase(classpathDir); + } + + public EmbeddingStore store() { + return store; + } + + public IngestionResult ingestion() { + return ingestion; + } +} diff --git a/advanced-rag/src/main/java/com/ankurm/lc4j/advancedrag/Pipelines.java b/advanced-rag/src/main/java/com/ankurm/lc4j/advancedrag/Pipelines.java new file mode 100644 index 0000000..6cc5f9c --- /dev/null +++ b/advanced-rag/src/main/java/com/ankurm/lc4j/advancedrag/Pipelines.java @@ -0,0 +1,109 @@ +package com.ankurm.lc4j.advancedrag; + +import dev.langchain4j.data.segment.TextSegment; +import dev.langchain4j.memory.chat.MessageWindowChatMemory; +import dev.langchain4j.model.chat.ChatModel; +import dev.langchain4j.rag.DefaultRetrievalAugmentor; +import dev.langchain4j.rag.RetrievalAugmentor; +import dev.langchain4j.rag.content.injector.ContentInjector; +import dev.langchain4j.rag.content.retriever.ContentRetriever; +import dev.langchain4j.rag.content.retriever.EmbeddingStoreContentRetriever; +import dev.langchain4j.rag.query.router.LanguageModelQueryRouter; +import dev.langchain4j.rag.query.router.QueryRouter; +import dev.langchain4j.rag.query.transformer.CompressingQueryTransformer; +import dev.langchain4j.rag.query.transformer.ExpandingQueryTransformer; +import dev.langchain4j.rag.query.transformer.QueryTransformer; +import dev.langchain4j.service.AiServices; +import dev.langchain4j.store.embedding.EmbeddingStore; + +import java.util.LinkedHashMap; +import java.util.Map; + +/** Small builders so each demo reads as "what is different from the previous one". */ +public final class Pipelines { + + private Pipelines() { + } + + /** A retriever over one store. maxResults 3 and minScore 0 are the library defaults, made explicit. */ + public static ContentRetriever retriever(EmbeddingStore store, int maxResults, double minScore) { + return EmbeddingStoreContentRetriever.builder() + .embeddingStore(store) + .embeddingModel(KnowledgeBase.EMBEDDING_MODEL) + .maxResults(maxResults) + .minScore(minScore) + .build(); + } + + /** Naive RAG: the user's message, as typed, is the search query. */ + public static SupportAssistant naive(ChatModel answerModel, ContentRetriever retriever) { + return AiServices.builder(SupportAssistant.class) + .chatModel(answerModel) + .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) + .contentRetriever(retriever) + .build(); + } + + /** Advanced RAG: every stage of the pipeline is a plug-in point on the augmentor. */ + public static SupportAssistant advanced(ChatModel answerModel, RetrievalAugmentor augmentor) { + return AiServices.builder(SupportAssistant.class) + .chatModel(answerModel) + .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) + .retrievalAugmentor(augmentor) + .build(); + } + + /** + * Same as advanced(), but chat memory keeps the user's own message instead of the message with retrieved + * text injected. The LLM still receives the augmented message for the current turn. + */ + public static SupportAssistant advancedLeanMemory(ChatModel answerModel, RetrievalAugmentor augmentor) { + return AiServices.builder(SupportAssistant.class) + .chatModel(answerModel) + .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) + .retrievalAugmentor(augmentor) + .storeRetrievedContentInChatMemory(false) + .build(); + } + + /** Returning Result is what makes the retrieved Content available as result.sources(). */ + public static SourcedAssistant sourced(ChatModel answerModel, ContentRetriever retriever) { + return AiServices.builder(SourcedAssistant.class) + .chatModel(answerModel) + .contentRetriever(retriever) + .build(); + } + + public static RetrievalAugmentor compressing(ChatModel rewriter, ContentRetriever retriever) { + return DefaultRetrievalAugmentor.builder() + .queryTransformer(new CompressingQueryTransformer(rewriter)) + .contentRetriever(retriever) + .build(); + } + + public static RetrievalAugmentor expanding(ChatModel expander, int n, ContentRetriever retriever) { + return DefaultRetrievalAugmentor.builder() + .queryTransformer(new ExpandingQueryTransformer(expander, n)) + .contentRetriever(retriever) + .build(); + } + + /** Numbering in the router prompt follows map iteration order, so the map must be ordered. */ + public static QueryRouter router(ChatModel routerModel, ContentRetriever support, ContentRetriever engineering) { + Map options = new LinkedHashMap<>(); + options.put(support, "Billing, refunds, hardware returns and account security for customers"); + options.put(engineering, "API rate limits, deployments and webhooks for developers"); + return LanguageModelQueryRouter.builder() + .chatModel(routerModel) + .retrieverToDescription(options) + .build(); + } + + public static RetrievalAugmentor full(QueryTransformer transformer, QueryRouter router, ContentInjector injector) { + return DefaultRetrievalAugmentor.builder() + .queryTransformer(transformer) + .queryRouter(router) + .contentInjector(injector) + .build(); + } +} diff --git a/advanced-rag/src/main/java/com/ankurm/lc4j/advancedrag/ScriptedChatModel.java b/advanced-rag/src/main/java/com/ankurm/lc4j/advancedrag/ScriptedChatModel.java new file mode 100644 index 0000000..1971288 --- /dev/null +++ b/advanced-rag/src/main/java/com/ankurm/lc4j/advancedrag/ScriptedChatModel.java @@ -0,0 +1,63 @@ +package com.ankurm.lc4j.advancedrag; + +import dev.langchain4j.data.message.AiMessage; +import dev.langchain4j.data.message.ChatMessage; +import dev.langchain4j.model.chat.ChatModel; +import dev.langchain4j.model.chat.request.ChatRequest; +import dev.langchain4j.model.chat.response.ChatResponse; + +import java.util.ArrayList; +import java.util.List; +import java.util.function.Function; + +/** + * A deterministic stand-in for a real LLM. It lets every example run offline and lets the + * tests assert exactly which messages LangChain4j sent, which is the thing worth looking at. + * Swap it for OpenAiChatModel (or any other ChatModel) and the AI Service code does not change. + */ +public class ScriptedChatModel implements ChatModel { + + private final Function script; + private final List requests = new ArrayList<>(); + + public ScriptedChatModel(Function script) { + this.script = script; + } + + @Override + public ChatResponse doChat(ChatRequest request) { + requests.add(request); + return ChatResponse.builder().aiMessage(script.apply(request)).build(); + } + + /** Every request this model has received, oldest first. */ + public List requests() { + return requests; + } + + public ChatRequest lastRequest() { + return requests.get(requests.size() - 1); + } + + /** Renders the messages of a request as one line per message, for transcripts. */ + public static String render(List messages) { + StringBuilder sb = new StringBuilder(); + for (ChatMessage m : messages) { + sb.append(m.type()).append(": ").append(text(m)).append('\n'); + } + return sb.toString(); + } + + private static String text(ChatMessage m) { + return switch (m) { + case dev.langchain4j.data.message.SystemMessage s -> s.text(); + case dev.langchain4j.data.message.UserMessage u -> u.singleText(); + case AiMessage a -> a.hasToolExecutionRequests() + ? "tool calls " + a.toolExecutionRequests().stream() + .map(r -> r.name() + r.arguments()).toList() + : a.text(); + case dev.langchain4j.data.message.ToolExecutionResultMessage t -> t.text(); + default -> m.toString(); + }; + } +} diff --git a/advanced-rag/src/main/java/com/ankurm/lc4j/advancedrag/SourcedAssistant.java b/advanced-rag/src/main/java/com/ankurm/lc4j/advancedrag/SourcedAssistant.java new file mode 100644 index 0000000..6574829 --- /dev/null +++ b/advanced-rag/src/main/java/com/ankurm/lc4j/advancedrag/SourcedAssistant.java @@ -0,0 +1,8 @@ +package com.ankurm.lc4j.advancedrag; + +import dev.langchain4j.service.Result; + +/** Wrapping the return type in Result tells AI Services to hand back the retrieved sources with the answer. */ +public interface SourcedAssistant { + Result chat(String message); +} diff --git a/advanced-rag/src/main/java/com/ankurm/lc4j/advancedrag/SupportAssistant.java b/advanced-rag/src/main/java/com/ankurm/lc4j/advancedrag/SupportAssistant.java new file mode 100644 index 0000000..37c86ea --- /dev/null +++ b/advanced-rag/src/main/java/com/ankurm/lc4j/advancedrag/SupportAssistant.java @@ -0,0 +1,6 @@ +package com.ankurm.lc4j.advancedrag; + +/** The AI Service the demos talk to. RAG is attached when it is built, not declared here. */ +public interface SupportAssistant { + String chat(String message); +} diff --git a/advanced-rag/src/main/resources/kb/engineering/deployments.txt b/advanced-rag/src/main/resources/kb/engineering/deployments.txt new file mode 100644 index 0000000..b017fda --- /dev/null +++ b/advanced-rag/src/main/resources/kb/engineering/deployments.txt @@ -0,0 +1,7 @@ +Acme Cloud Deployments + +A standard deployment takes about 4 minutes from push to live. The first 5 percent of traffic goes to the new version as a canary for 2 minutes before the rest is shifted. + +A rollback takes about 30 seconds because the previous version stays warm for one hour after every deployment. After that hour, a rollback is a normal 4 minute deployment of the older build. + +Deployments are blocked automatically when the error rate of the canary is more than 2 percent above the baseline. diff --git a/advanced-rag/src/main/resources/kb/engineering/rate-limits.txt b/advanced-rag/src/main/resources/kb/engineering/rate-limits.txt new file mode 100644 index 0000000..62157f2 --- /dev/null +++ b/advanced-rag/src/main/resources/kb/engineering/rate-limits.txt @@ -0,0 +1,7 @@ +Acme Cloud API Rate Limits + +Every API key is limited to 600 requests per minute, with a burst allowance of 100 requests per second. Requests over the limit receive HTTP 429 with a Retry-After header giving the number of seconds to wait. + +Limits are per key, not per organisation, so a noisy integration cannot starve the others. Batch endpoints count as one request regardless of how many items they contain. + +To raise a limit, open a ticket with the key id and the peak traffic you expect. Increases are applied within one business day. diff --git a/advanced-rag/src/main/resources/kb/engineering/webhooks.txt b/advanced-rag/src/main/resources/kb/engineering/webhooks.txt new file mode 100644 index 0000000..6e16f0a --- /dev/null +++ b/advanced-rag/src/main/resources/kb/engineering/webhooks.txt @@ -0,0 +1,7 @@ +Acme Cloud Webhooks + +Every webhook delivery is signed. The signature is sent in the X-Acme-Signature header and is an HMAC-SHA256 of the raw request body using your endpoint secret. Reject any delivery whose signature does not match. + +If your endpoint does not answer with a 2xx status within 10 seconds, the delivery is retried up to 8 times with exponential backoff. The retries are spread over 24 hours. After the last failed attempt the endpoint is marked as failing and an email is sent to the organisation owner. + +Deliveries can arrive more than once and out of order, so handlers must be idempotent. Use the event id to deduplicate. diff --git a/advanced-rag/src/main/resources/kb/support/account-security.txt b/advanced-rag/src/main/resources/kb/support/account-security.txt new file mode 100644 index 0000000..c960e2a --- /dev/null +++ b/advanced-rag/src/main/resources/kb/support/account-security.txt @@ -0,0 +1,7 @@ +Acme Cloud Account Security + +Password reset links expire after 30 minutes and can be used only once. If a link has expired, request a new one from the sign-in page. + +Two-factor authentication is mandatory for organisation owners. Supported methods are authenticator apps and hardware security keys. SMS codes are not supported. + +SSO via SAML 2.0 is available on the Business plan. After SSO is enforced, password sign-in is disabled for every member except the organisation owner, who keeps a break-glass login. diff --git a/advanced-rag/src/main/resources/kb/support/hardware-returns.txt b/advanced-rag/src/main/resources/kb/support/hardware-returns.txt new file mode 100644 index 0000000..709bd35 --- /dev/null +++ b/advanced-rag/src/main/resources/kb/support/hardware-returns.txt @@ -0,0 +1,7 @@ +Acme Edge Box Hardware Returns + +The Acme Edge Box can be returned within 45 days of delivery if it is in its original packaging. Request a return label from the support portal; the label is valid for 14 days. + +After our warehouse receives the box, the refund is processed within 3 business days. It then follows the normal card timeline of 5 to 10 business days. + +Boxes that arrive damaged or with missing power adapters are inspected first, which can add up to 5 business days. diff --git a/advanced-rag/src/main/resources/kb/support/refund-policy.txt b/advanced-rag/src/main/resources/kb/support/refund-policy.txt new file mode 100644 index 0000000..aeaf2e0 --- /dev/null +++ b/advanced-rag/src/main/resources/kb/support/refund-policy.txt @@ -0,0 +1,7 @@ +Acme Cloud Refund Policy + +Annual plans can be refunded in full within 30 days of purchase. Monthly plans can be refunded within 7 days of the first charge. After those windows, no refund is issued, but you can cancel at any time and keep access until the end of the paid period. + +Once a refund is approved, it takes 5 to 10 business days to appear on your card statement. The time depends on your bank, not on Acme Cloud. Refunds always go back to the original payment method; we cannot pay them out to a different card. + +If a refund does not show up after 10 business days, contact support with the invoice number so we can send you the acquirer reference number. diff --git a/advanced-rag/src/test/java/com/ankurm/lc4j/advancedrag/AdvancedRagTest.java b/advanced-rag/src/test/java/com/ankurm/lc4j/advancedrag/AdvancedRagTest.java new file mode 100644 index 0000000..b01abb9 --- /dev/null +++ b/advanced-rag/src/test/java/com/ankurm/lc4j/advancedrag/AdvancedRagTest.java @@ -0,0 +1,478 @@ +package com.ankurm.lc4j.advancedrag; + +import dev.langchain4j.data.document.Document; +import dev.langchain4j.data.document.loader.ClassPathDocumentLoader; +import dev.langchain4j.data.message.AiMessage; +import dev.langchain4j.data.message.ChatMessage; +import dev.langchain4j.data.message.UserMessage; +import dev.langchain4j.data.segment.TextSegment; +import dev.langchain4j.model.chat.request.ChatRequest; +import dev.langchain4j.rag.content.Content; +import dev.langchain4j.rag.content.ContentMetadata; +import dev.langchain4j.rag.content.aggregator.DefaultContentAggregator; +import dev.langchain4j.rag.content.injector.DefaultContentInjector; +import dev.langchain4j.rag.content.retriever.ContentRetriever; +import dev.langchain4j.rag.content.retriever.EmbeddingStoreContentRetriever; +import dev.langchain4j.rag.query.Query; +import dev.langchain4j.rag.query.router.LanguageModelQueryRouter; +import dev.langchain4j.rag.query.transformer.CompressingQueryTransformer; +import dev.langchain4j.rag.query.transformer.ExpandingQueryTransformer; +import dev.langchain4j.model.input.PromptTemplate; +import dev.langchain4j.store.embedding.EmbeddingSearchRequest; +import dev.langchain4j.store.embedding.EmbeddingStoreIngestor; +import dev.langchain4j.store.embedding.inmemory.InMemoryEmbeddingStore; +import org.junit.jupiter.api.BeforeAll; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.TestMethodOrder; +import org.junit.jupiter.api.MethodOrderer; + +import java.util.ArrayList; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; +import java.util.stream.Collectors; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.assertj.core.api.Assertions.assertThatThrownBy; + +/** + * Each test writes the transcript the post quotes and asserts the same facts, so a figure in the post + * that stops being true fails the build. The answering LLM, the query rewriter, the expander and the + * router are all ScriptedChatModel instances; retrieval is REAL (in-process bge-small embeddings). + */ +@TestMethodOrder(MethodOrderer.MethodName.class) +class AdvancedRagTest { + + static KnowledgeBase all; + static KnowledgeBase support; + static KnowledgeBase engineering; + + static final String FOLLOW_UP = "How long does it take to show up?"; + static final String REWRITTEN = "How long does a refund for an annual plan take to show up on my card?"; + + @BeforeAll + static void load() { + all = KnowledgeBase.load("kb"); + support = KnowledgeBase.load("kb/support"); + engineering = KnowledgeBase.load("kb/engineering"); + } + + // ---------- helpers ---------- + + static ScriptedChatModel answerer() { + return new ScriptedChatModel(r -> AiMessage.from("(scripted answer)")); + } + + static String file(Content c) { + return c.textSegment().metadata().getString("file_name"); + } + + static double score(Content c) { + return (Double) c.metadata().get(ContentMetadata.SCORE); + } + + static String lines(List contents) { + StringBuilder sb = new StringBuilder(); + for (Content c : contents) { + sb.append(String.format(" %.3f %s%n", score(c), file(c))); + } + return sb.toString(); + } + + static String userText(ChatRequest request) { + List ms = request.messages(); + return ((UserMessage) ms.get(ms.size() - 1)).singleText(); + } + + static int segmentCount(KnowledgeBase kb) { + return ((InMemoryEmbeddingStore) kb.store()) + .search(EmbeddingSearchRequest.builder() + .queryEmbedding(KnowledgeBase.EMBEDDING_MODEL.embed("anything").content()) + .maxResults(1000).minScore(0.0).build()) + .matches().size(); + } + + // ---------- 1. Easy RAG ---------- + + @Test + void t01_easyRag() { + ContentRetriever retriever = Pipelines.retriever(all.store(), 3, 0.0); + ScriptedChatModel model = answerer(); + SupportAssistant assistant = Pipelines.naive(model, retriever); + + assistant.chat("How long are webhooks retried?"); + String sent = userText(model.lastRequest()); + + StringBuilder t = new StringBuilder(); + t.append("Easy RAG ingestion of kb/ (6 files)\n"); + t.append(" segments stored: ").append(segmentCount(all)).append('\n'); + t.append("\nRetrieved for \"How long are webhooks retried?\":\n"); + t.append(lines(retriever.retrieve(Query.from("How long are webhooks retried?")))); + t.append("\nUser message the LLM actually received:\n").append(sent).append('\n'); + Transcript.write("01-easy-rag.txt", t.toString()); + + assertThat(segmentCount(all)).isEqualTo(6); + assertThat(sent).startsWith("How long are webhooks retried?"); + assertThat(sent).contains("Answer using the following information:"); + assertThat(model.requests()).hasSize(1); + } + + // ---------- 2. The follow-up problem ---------- + + @Test + void t02_naiveFollowUp() { + ContentRetriever retriever = Pipelines.retriever(all.store(), 3, 0.0); + List naive = retriever.retrieve(Query.from(FOLLOW_UP)); + List good = retriever.retrieve(Query.from(REWRITTEN)); + + StringBuilder t = new StringBuilder(); + t.append("Turn 1: \"What is the refund window for annual plans?\"\n"); + t.append("Turn 2 (follow-up): \"").append(FOLLOW_UP).append("\"\n"); + t.append("\nNaive RAG searches with the follow-up exactly as typed:\n").append(lines(naive)); + t.append("\nSearching with a self-contained rewrite instead (\"").append(REWRITTEN).append("\"):\n") + .append(lines(good)); + Transcript.write("02-naive-follow-up.txt", t.toString()); + + assertThat(file(naive.get(0))).isEqualTo("hardware-returns.txt"); + assertThat(naive.stream().map(AdvancedRagTest::file)).contains("deployments.txt", "refund-policy.txt"); + assertThat(file(good.get(0))).isEqualTo("refund-policy.txt"); + } + + // ---------- 3. Compression ---------- + + @Test + void t03_compression() { + ContentRetriever retriever = Pipelines.retriever(all.store(), 3, 0.0); + ScriptedChatModel rewriter = new ScriptedChatModel(r -> AiMessage.from(REWRITTEN)); + ScriptedChatModel model = answerer(); + SupportAssistant assistant = Pipelines.advanced(model, Pipelines.compressing(rewriter, retriever)); + + assistant.chat("What is the refund window for annual plans?"); + int rewriterCallsAfterTurn1 = rewriter.requests().size(); + assistant.chat(FOLLOW_UP); + int rewriterCallsAfterTurn2 = rewriter.requests().size(); + + String rewriterPrompt = userText(rewriter.lastRequest()); + String sent = userText(model.lastRequest()); + + // Keep talking, and watch how big the rewriter's prompt gets. + assistant.chat("And for monthly plans?"); + assistant.chat("Can it go to a different card?"); + List sizes = rewriter.requests().stream().map(r -> userText(r).length()).toList(); + + StringBuilder t = new StringBuilder(); + t.append("Rewriter LLM calls after turn 1: ").append(rewriterCallsAfterTurn1).append('\n'); + t.append("Rewriter LLM calls after turn 2: ").append(rewriterCallsAfterTurn2).append('\n'); + t.append("\nPrompt CompressingQueryTransformer sent to the rewriter on turn 2:\n").append(rewriterPrompt).append('\n'); + t.append("\nUser message the answering LLM received on turn 2:\n").append(sent).append('\n'); + t.append("\nRewriter prompt size in characters, turn 2 / 3 / 4: ") + .append(sizes.get(0)).append(" / ").append(sizes.get(1)).append(" / ").append(sizes.get(2)).append('\n'); + + // The same four turns again, with storeRetrievedContentInChatMemory(false) + ScriptedChatModel leanRewriter = new ScriptedChatModel(r -> AiMessage.from(REWRITTEN)); + ScriptedChatModel leanModel = answerer(); + SupportAssistant lean = Pipelines.advancedLeanMemory(leanModel, Pipelines.compressing(leanRewriter, retriever)); + lean.chat("What is the refund window for annual plans?"); + lean.chat(FOLLOW_UP); + String leanPrompt = userText(leanRewriter.lastRequest()); + lean.chat("And for monthly plans?"); + lean.chat("Can it go to a different card?"); + List leanSizes = leanRewriter.requests().stream().map(r -> userText(r).length()).toList(); + t.append("\nWith storeRetrievedContentInChatMemory(false), turn 2 / 3 / 4: ") + .append(leanSizes.get(0)).append(" / ").append(leanSizes.get(1)).append(" / ").append(leanSizes.get(2)).append('\n'); + t.append("\nPrompt sent to the rewriter on turn 2 with storeRetrievedContentInChatMemory(false):\n").append(leanPrompt).append('\n'); + t.append("\nUser message the answering LLM still received on turn 4 (augmented: ") + .append(userText(leanModel.lastRequest()).contains("Answer using the following information:")).append(")\n"); + Transcript.write("03-compression.txt", t.toString()); + assertThat(leanPrompt).doesNotContain("Answer using the following information:"); + assertThat(leanSizes.get(2)).isLessThan(sizes.get(0)); + assertThat(userText(leanModel.lastRequest())).contains("Answer using the following information:"); + + assertThat(rewriterCallsAfterTurn1).isZero(); + assertThat(rewriterCallsAfterTurn2).isEqualTo(1); + assertThat(rewriterPrompt).contains("User query: " + FOLLOW_UP); + // chat memory holds the AUGMENTED message, so the previous turn's retrieved text is in the rewriter prompt + assertThat(rewriterPrompt).contains("Answer using the following information:"); + assertThat(sent).startsWith(FOLLOW_UP); // the user's own words go to the answering LLM, not the rewrite + assertThat(sent.indexOf("Refund Policy")).isLessThan(sent.indexOf("Hardware Returns")); + assertThat(sizes).hasSize(3).isSorted(); + assertThat(sizes.get(2)).isGreaterThan(sizes.get(0)); + } + + // ---------- 4. Expansion ---------- + + private record Expansion(List single, List variants, Map> perVariant, + List fused, String prompt) { + } + + private static Expansion expand(String original, String... scriptedVariants) { + ContentRetriever retriever = Pipelines.retriever(all.store(), 3, 0.0); + ScriptedChatModel expander = new ScriptedChatModel(r -> AiMessage.from(String.join("\n", scriptedVariants))); + List variants = new ArrayList<>(new ExpandingQueryTransformer(expander, scriptedVariants.length) + .transform(Query.from(original))); + Map> perVariant = new LinkedHashMap<>(); + Map>> forAggregator = new LinkedHashMap<>(); + for (Query q : variants) { + List hits = retriever.retrieve(q); + perVariant.put(q, hits); + forAggregator.put(q, List.of(hits)); + } + List fused = new DefaultContentAggregator().aggregate(forAggregator); + return new Expansion(retriever.retrieve(Query.from(original)), variants, perVariant, fused, + userText(expander.lastRequest())); + } + + private static void describe(StringBuilder t, String original, Expansion e) { + t.append("Original query: ").append(original).append('\n'); + t.append("Single-query top 3:\n").append(lines(e.single())); + t.append("\nQueries produced: ").append(e.variants().size()).append('\n'); + e.perVariant().forEach((q, hits) -> t.append("\n \"").append(q.text()).append("\"\n") + .append(lines(hits).replaceAll("(?m)^", " "))); + t.append("\nAfter DefaultContentAggregator (reciprocal rank fusion): ").append(e.fused().size()) + .append(" unique segments, in this order:\n"); + e.fused().forEach(c -> t.append(" ").append(file(c)).append('\n')); + } + + @Test + void t04_expansion() { + String vague = "I shipped a bad release, can I undo it?"; + Expansion helps = expand(vague, + "How can I revert a faulty release?", + "Is it possible to roll back a bad deployment?", + "What is the way to reverse a release that went wrong?"); + + String clear = "How do I get my money back?"; + Expansion noGain = expand(clear, + "What is the process for requesting a refund?", + "How can I be reimbursed for a purchase?", + "Steps to cancel and receive a refund"); + + StringBuilder t = new StringBuilder(); + t.append("=== Case 1: a query whose wording misses the document ===\n"); + describe(t, vague, helps); + t.append("\n=== Case 2: a query that was already fine ===\n"); + describe(t, clear, noGain); + t.append("\nPrompt ExpandingQueryTransformer sent to the expander:\n").append(helps.prompt()).append('\n'); + Transcript.write("04-expansion.txt", t.toString()); + + // Case 1: the right document is not in the single-query top 3, but it is in the fused result + assertThat(helps.single().stream().map(AdvancedRagTest::file)).doesNotContain("deployments.txt"); + assertThat(helps.fused().stream().map(AdvancedRagTest::file)).contains("deployments.txt"); + // Case 2: same three documents either way + assertThat(noGain.fused().stream().map(AdvancedRagTest::file)) + .containsExactlyInAnyOrderElementsOf(noGain.single().stream().map(AdvancedRagTest::file).toList()); + assertThat(helps.fused().stream().map(AdvancedRagTest::file).distinct()).hasSameSizeAs(helps.fused()); + } + + // ---------- 5. Routing ---------- + + @Test + void t05_routing() { + ContentRetriever sup = Pipelines.retriever(support.store(), 3, 0.0); + ContentRetriever eng = Pipelines.retriever(engineering.store(), 3, 0.0); + String q = "How long are webhooks retried?"; + + ScriptedChatModel routerModel = new ScriptedChatModel(r -> AiMessage.from("2")); + var router = Pipelines.router(routerModel, sup, eng); + var routed = new ArrayList<>(router.route(Query.from(q))); + + ScriptedChatModel garbage = new ScriptedChatModel(r -> AiMessage.from("The engineering one, I think.")); + var defaultFallback = new ArrayList<>(Pipelines.router(garbage, sup, eng).route(Query.from(q))); + + Map opts = new LinkedHashMap<>(); + opts.put(sup, "support"); + opts.put(eng, "engineering"); + var failing = LanguageModelQueryRouter.builder().chatModel(garbage).retrieverToDescription(opts) + .fallbackStrategy(LanguageModelQueryRouter.FallbackStrategy.FAIL).build(); + var routeAll = LanguageModelQueryRouter.builder().chatModel(garbage).retrieverToDescription(opts) + .fallbackStrategy(LanguageModelQueryRouter.FallbackStrategy.ROUTE_TO_ALL).build(); + + ContentRetriever merged = Pipelines.retriever(all.store(), 3, 0.0); + StringBuilder t = new StringBuilder(); + t.append("Query: ").append(q).append('\n'); + t.append("\nSearching the single merged store:\n").append(lines(merged.retrieve(Query.from(q)))); + t.append("\nPrompt LanguageModelQueryRouter sent to the router LLM:\n").append(userText(routerModel.lastRequest())).append('\n'); + t.append("\nRouter LLM answered \"2\" -> retrievers chosen: ").append(routed.size()).append('\n'); + t.append(lines(routed.get(0).retrieve(Query.from(q)))); + t.append("\nRouter LLM answered \"The engineering one, I think.\":\n"); + t.append(" default fallback strategy -> retrievers chosen: ").append(defaultFallback.size()).append('\n'); + t.append(" ROUTE_TO_ALL -> retrievers chosen: ").append(routeAll.route(Query.from(q)).size()).append('\n'); + String failMsg; + try { + failing.route(Query.from(q)); + failMsg = "no exception"; + } catch (RuntimeException e) { + failMsg = e.getClass().getName() + ": " + e.getMessage(); + } + t.append(" FAIL -> ").append(failMsg).append('\n'); + Transcript.write("05-routing.txt", t.toString()); + + assertThat(routed).containsExactly(eng); + assertThat(merged.retrieve(Query.from(q)).stream().map(AdvancedRagTest::file)) + .contains("refund-policy.txt"); // support filler in the merged store + assertThat(eng.retrieve(Query.from(q)).stream().map(AdvancedRagTest::file)) + .doesNotContain("refund-policy.txt", "account-security.txt"); + assertThat(userText(routerModel.lastRequest())).contains("1: ").contains("2: "); + assertThat(routeAll.route(Query.from(q))).hasSize(2); + assertThat(failMsg).isNotEqualTo("no exception"); + } + + // ---------- 6. Content injection ---------- + + @Test + void t06_injection() { + ContentRetriever retriever = Pipelines.retriever(all.store(), 2, 0.0); + String q = "How long are webhooks retried?"; + + ScriptedChatModel plain = answerer(); + Pipelines.naive(plain, retriever).chat(q); + + var injector = DefaultContentInjector.builder() + .promptTemplate(PromptTemplate.from( + "{{userMessage}}\n\nAnswer ONLY from the sources below. If they do not contain the answer, say you do not know.\n\n{{contents}}")) + .metadataKeysToInclude(List.of("file_name")) + .build(); + ScriptedChatModel custom = answerer(); + var augmentor = dev.langchain4j.rag.DefaultRetrievalAugmentor.builder() + .contentRetriever(retriever).contentInjector(injector).build(); + Pipelines.advanced(custom, augmentor).chat(q); + + StringBuilder t = new StringBuilder(); + t.append("Default injector:\n").append(userText(plain.lastRequest())).append('\n'); + t.append("\nCustom template + metadataKeysToInclude([\"file_name\"]):\n").append(userText(custom.lastRequest())).append('\n'); + Transcript.write("06-injection.txt", t.toString()); + + assertThat(userText(plain.lastRequest())).doesNotContain("file_name"); + assertThat(userText(custom.lastRequest())).contains("file_name: webhooks.txt").contains("Answer ONLY"); + } + + // ---------- 7. minScore ---------- + + @Test + void t07_minScore() { + String offTopic = "What is the capital of France?"; + String onTopic = "How long does a refund take to show up on my card?"; + ContentRetriever open = Pipelines.retriever(all.store(), 3, 0.0); + ContentRetriever strict = Pipelines.retriever(all.store(), 3, 0.75); + ContentRetriever stricter = Pipelines.retriever(all.store(), 3, 0.85); + + ScriptedChatModel openModel = answerer(); + Pipelines.naive(openModel, open).chat(offTopic); + ScriptedChatModel strictModel = answerer(); + Pipelines.naive(strictModel, strict).chat(offTopic); + + StringBuilder t = new StringBuilder(); + t.append("Off-topic: ").append(offTopic).append('\n'); + t.append("minScore 0.0 (default):\n").append(lines(open.retrieve(Query.from(offTopic)))); + t.append("minScore 0.75:\n").append(lines(strict.retrieve(Query.from(offTopic)))).append(" (nothing)\n"); + t.append("\nMessage sent to the LLM with minScore 0.0:\n").append(userText(openModel.lastRequest())).append('\n'); + t.append("\nMessage sent to the LLM with minScore 0.75:\n").append(userText(strictModel.lastRequest())).append('\n'); + t.append("\nOn-topic: ").append(onTopic).append('\n'); + t.append("minScore 0.0:\n").append(lines(open.retrieve(Query.from(onTopic)))); + t.append("minScore 0.75:\n").append(lines(strict.retrieve(Query.from(onTopic)))); + t.append("minScore 0.85:\n").append(lines(stricter.retrieve(Query.from(onTopic)))); + Transcript.write("07-min-score.txt", t.toString()); + + assertThat(open.retrieve(Query.from(offTopic))).hasSize(3); + assertThat(strict.retrieve(Query.from(offTopic))).isEmpty(); + assertThat(userText(strictModel.lastRequest())).isEqualTo(offTopic); + assertThat(strict.retrieve(Query.from(onTopic)).stream().map(AdvancedRagTest::file)).contains("webhooks.txt"); + assertThat(stricter.retrieve(Query.from(onTopic)).stream().map(AdvancedRagTest::file)) + .containsExactly("refund-policy.txt", "hardware-returns.txt"); + } + + // ---------- 8. The whole pipeline and what it costs ---------- + + @Test + void t08_fullPipelineCost() { + ContentRetriever sup = Pipelines.retriever(support.store(), 3, 0.75); + ContentRetriever eng = Pipelines.retriever(engineering.store(), 3, 0.75); + ScriptedChatModel rewriter = new ScriptedChatModel(r -> AiMessage.from(REWRITTEN)); + ScriptedChatModel routerModel = new ScriptedChatModel(r -> AiMessage.from("1")); + ScriptedChatModel model = answerer(); + + var injector = DefaultContentInjector.builder().metadataKeysToInclude(List.of("file_name")).build(); + var augmentor = Pipelines.full(new CompressingQueryTransformer(rewriter), + Pipelines.router(routerModel, sup, eng), injector); + SupportAssistant assistant = Pipelines.advancedLeanMemory(model, augmentor); + + List rows = new ArrayList<>(); + String[] turns = {"What is the refund window for annual plans?", FOLLOW_UP}; + int r0 = 0, o0 = 0, a0 = 0; + for (int i = 0; i < turns.length; i++) { + assistant.chat(turns[i]); + rows.add(String.format("turn %d rewriter=%d router=%d answer=%d", i + 1, + rewriter.requests().size() - r0, routerModel.requests().size() - o0, model.requests().size() - a0)); + r0 = rewriter.requests().size(); + o0 = routerModel.requests().size(); + a0 = model.requests().size(); + } + StringBuilder t = new StringBuilder("LLM calls per turn (compress + route + answer):\n"); + rows.forEach(r -> t.append(" ").append(r).append('\n')); + t.append("\nUser message the answering LLM received on turn 2:\n").append(userText(model.lastRequest())).append('\n'); + Transcript.write("08-full-pipeline.txt", t.toString()); + + assertThat(rows).containsExactly( + "turn 1 rewriter=0 router=1 answer=1", + "turn 2 rewriter=1 router=1 answer=1"); + assertThat(userText(model.lastRequest())).contains("file_name: refund-policy.txt"); + } + + // ---------- 10. Sources for citations ---------- + + @Test + void t10_sources() { + ContentRetriever retriever = Pipelines.retriever(all.store(), 2, 0.0); + var result = Pipelines.sourced(answerer(), retriever).chat("How long are webhooks retried?"); + StringBuilder t = new StringBuilder("answer: " + result.content() + "\nsources:\n"); + for (Content c : result.sources()) { + t.append(String.format(" %.3f %s%n", score(c), file(c))); + } + Transcript.write("10-sources.txt", t.toString()); + + assertThat(result.sources()).hasSize(2); + assertThat(file(result.sources().get(0))).isEqualTo("webhooks.txt"); + } + + // ---------- 11. Library defaults the post quotes ---------- + + @Test + void t11_defaults() { + Query q = Query.from("x"); + int maxResults = EmbeddingStoreContentRetriever.DEFAULT_MAX_RESULTS.apply(q); + double minScore = EmbeddingStoreContentRetriever.DEFAULT_MIN_SCORE.apply(q); + String t = "EmbeddingStoreContentRetriever.DEFAULT_MAX_RESULTS = " + maxResults + "\n" + + "EmbeddingStoreContentRetriever.DEFAULT_MIN_SCORE = " + minScore + "\n" + + "ExpandingQueryTransformer.DEFAULT_N = " + ExpandingQueryTransformer.DEFAULT_N + "\n" + + "LanguageModelQueryRouter.FallbackStrategy = " + + java.util.Arrays.toString(LanguageModelQueryRouter.FallbackStrategy.values()) + "\n"; + Transcript.write("11-defaults.txt", t); + + assertThat(maxResults).isEqualTo(3); + assertThat(minScore).isZero(); + assertThat(ExpandingQueryTransformer.DEFAULT_N).isEqualTo(3); + } + + // ---------- 9. The loader trap ---------- + + @Test + void t09_loaderTrap() { + List flat = ClassPathDocumentLoader.loadDocuments("kb"); + List deep = ClassPathDocumentLoader.loadDocumentsRecursively("kb"); + String failure; + try { + EmbeddingStoreIngestor.ingest(flat, new InMemoryEmbeddingStore<>()); + failure = "no exception"; + } catch (RuntimeException e) { + failure = e.getClass().getName() + ": " + e.getMessage(); + } + String t = "loadDocuments(\"kb\") -> " + flat.size() + " documents\n" + + "loadDocumentsRecursively(\"kb\") -> " + deep.size() + " documents\n" + + "ingest(flat, store) -> " + failure + "\n"; + Transcript.write("09-loader-trap.txt", t); + + assertThat(flat).isEmpty(); + assertThat(deep).hasSize(6); + assertThat(failure).contains("segments cannot be null or empty"); + } +} diff --git a/advanced-rag/src/test/java/com/ankurm/lc4j/advancedrag/Transcript.java b/advanced-rag/src/test/java/com/ankurm/lc4j/advancedrag/Transcript.java new file mode 100644 index 0000000..871e65a --- /dev/null +++ b/advanced-rag/src/test/java/com/ankurm/lc4j/advancedrag/Transcript.java @@ -0,0 +1,23 @@ +package com.ankurm.lc4j.advancedrag; + +import java.io.IOException; +import java.nio.file.Files; +import java.nio.file.Path; + +/** Writes what a test observed to output/NN-name.txt so every figure in the post comes from a file. */ +final class Transcript { + + private static final Path DIR = Path.of("output"); + + private Transcript() { + } + + static void write(String name, String content) { + try { + Files.createDirectories(DIR); + Files.writeString(DIR.resolve(name), content); + } catch (IOException e) { + throw new IllegalStateException(e); + } + } +} diff --git a/pom.xml b/pom.xml index b07d161..b4f8e5b 100644 --- a/pom.xml +++ b/pom.xml @@ -13,6 +13,7 @@ ai-services spring-boot-ai-service agentic + advanced-rag