Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

Feat/claim decision filter (#21587)

Caobaining184bc1ca4a1a9
diff --git a/internal/agentic_rag/agent.go b/internal/agentic_rag/agent.go
index 84f570ffd7..ab70f87260 100644
--- a/internal/agentic_rag/agent.go
+++ b/internal/agentic_rag/agent.go
@@ -343,6 +343,10 @@ func Run(ctx context.Context, in Input) (string, error) {
convKey = fmt.Sprintf("run-%d", atomic.AddUint64(&runSeq, 1))
}
ctx = WithConversationKey(ctx, convKey)
+ // The turn's compiled-evidence state: the scope claims are looked up in,
+ // the corpus-level existence probe, and the claims already shown. Installed
+ // here so the pre-loop probe and every locate tool share one scope.
+ ctx = withCompiledRun(ctx, in.TenantID, in.DatasetIDs)
// Identity the judge is chosen for: the decision model is configured per chat
// and per tenant in the UI, so the filter has to know which run it is
@@ -385,36 +389,41 @@ func Run(ctx context.Context, in Input) (string, error) {
maxIter := agenticMaxIterations(in.MaxIterations)
- // ONE claim recall per turn, BEFORE the loop, consumed as a control signal
- // rather than as prompt text.
+ // The compiled-evidence probe runs BEFORE the loop: search once, then ask the
+ // model whether the claims COMPILED FROM what that search returned already
+ // answer the question. A refusal falls back to the loop, which is the only
+ // place that decides what to search next.
//
- // A recall that covers the question needs no document and no chunk: the
- // claims carry their own verbatim evidence, so the turn terminates on a
- // single model call over them. Descending the structure again, or reading
- // the raw chunks they were compiled from, could only re-derive what the
- // claims already state - and every additional step is another chance to
- // prune away the branch that holds the answer.
+ // The ordering is the point. The search is the same hybrid chunk retrieval
+ // the locate tools run, so it works identically on a corpus with compiled
+ // artifacts and one without; what differs is only what is offered next. With
+ // claims, the turn can terminate on a single model call over them - the
+ // claims carry their own verbatim evidence, so no raw chunk has to be read.
+ // Without them (or when the model judges them insufficient) the loop runs
+ // exactly as it would have, and the model reads chunks itself.
//
- // A recall that does not cover the question is discarded here. The loop then
- // runs exactly as it would have without the recall, and navigate_structure
- // stays available for the model to call on demand.
+ // The probe is a control signal, not prompt text: an insufficient block is
+ // dropped here rather than pinned into the system instruction, where it
+ // would be re-billed on every call of the turn.
if len(in.Tools) == 0 && !tmpl.strictTools {
- pf := recallCompiledClaims(ctx, in.TenantID, in.DatasetIDs, in.Messages)
- if pf.sufficient {
+ pf := prefetchCompiledEvidence(ctx, in.TenantID, in.DatasetIDs, in.Messages)
+ if len(pf.claims) > 0 {
answer, aerr := answerFromClaims(ctx, synthModelFor(in), tmpl.Content, in.Messages, pf)
switch {
case aerr != nil:
// Falling through keeps the turn answerable: the claims are
// dropped from the registry's numbering (nothing was shown) and
// the loop retrieves what it needs itself.
- common.WarnCtx(ctx, "agentic_rag: claim answer failed; falling back to the loop", zap.Error(aerr))
+ common.WarnCtx(ctx, "agentic_rag: compiled claim answer failed; falling back to the loop", zap.Error(aerr))
case strings.TrimSpace(answer) != "":
// The loop is skipped entirely, so this line is the only record
// that the turn never read a chunk: a review of tool usage must
// be able to tell it from a turn the model gave up on.
common.InfoCtx(ctx, "agentic_rag: answered from compiled claims",
zap.Int("claims", len(pf.claims)),
- zap.Int("docs", len(pf.docs)),
+ zap.Int("chunks", len(pf.chunks)),
+ zap.Strings("docs", claimDocsInOrder(pf.claims)),
+ zap.Int("handles", claimHandleCount(answer)),
zap.Int("answer_bytes", len(answer)))
emit(ctx, in.OnDelta, answer, "")
return answer, nil
@@ -865,9 +874,10 @@ const finalizeTimeout = 90 * time.Second
// this corpus.
const finalizeEvidenceMaxRunes = 40000
-// claimAnswerTimeout bounds the sufficient-claims answer. It is a single
-// non-streaming call over evidence that was already retrieved, so it needs a
-// fraction of the loop's budget - and a hung provider must not eat the turn.
+// claimAnswerTimeout bounds the claims path as a whole: an answer call over
+// evidence that was already retrieved and, only if it produced an answer, its
+// verification. Both are non-streaming and need a fraction of the loop's budget -
+// and a hung provider must not eat the turn.
const claimAnswerTimeout = 90 * time.Second
// synthModelFor picks the model that answers without tools: the caller's
@@ -879,20 +889,27 @@ func synthModelFor(in Input) *models.EinoChatModel {
return in.Model
}
-// claimAnswerPrompt renders the user message of the sufficient-claims answer.
+// claimAnswerPrompt renders the user message of the call that produces a
+// candidate answer from the recalled claims.
//
-// It states the rules the loop would otherwise carry in its system prompt, in
-// the one place they apply: the answer must be built from these claims, each
-// fact line must carry the [ID:n] handle of the passage it came from (the
-// pipeline turns those handles into the reference payload), and nothing may be
-// extrapolated. It deliberately does NOT advertise tools: this call has none, so
-// a model that looks for one would burn its only turn.
+// One call produces it, and the sufficiency judgement is made afterwards, by
+// claimVerifyPrompt, on the answer itself. Judging the page BEFORE answering was
+// measured and rejected: with no answer to commit to, the model answered "is the
+// page enough?" too harshly, refusing five questions whose facts were all on the
+// page (gap_overlap 0.86-1.00), and a refusal is what feeds the loop - q142 cost
+// 12.6k as an answer and 590,139 after a refusal, for the same 4 points. An
+// answer is also the only thing that exposes the failure this corpus produces
+// (the film's release year given as the year of the award), because a page can
+// hold the wrong-looking claim without the answer using it.
//
-// The reply is a JSON verdict, not prose, because the caller has to act on it:
-// "these claims do not answer the question" is a routing decision (fall back to
-// the loop), and reading it reliably out of free text is not possible. A model
-// that cannot answer from the claims says so here instead of shipping a
-// non-answer, which is exactly what a zero-score benchmark run looked like.
+// It carries the rules the loop would otherwise hold in its system prompt: every
+// fact line must be traceable to the claim it came from via its [ID:n] handle
+// (the pipeline turns those handles into the reference payload), and nothing may
+// be extrapolated. A computation must name its inputs: "the last time they beat
+// them" answered from the wrong edition of the same fact is a real error here,
+// and naming the inputs is what makes it visible. It deliberately does NOT
+// advertise tools: this call has none, so a model that looks for one would burn
+// its only turn.
func claimAnswerPrompt(evidence string) string {
var b strings.Builder
b.WriteString("### Compiled evidence retrieved for this question\n")
@@ -900,12 +917,22 @@ func claimAnswerPrompt(evidence string) string {
b.WriteString("the chunk that quote came from, and the passage handle `ref=n` it was shown as.\n\n")
b.WriteString(evidence)
b.WriteString("\n\n### Task\n")
- b.WriteString("Decide whether this evidence answers the question above, then answer from it.\n")
- b.WriteString("- If it does: combine claims where the question needs it, and end every line that states a fact with ")
- b.WriteString("the handle of the claim it came from: `[ID:n]`, where n is that claim's `ref=n` value. Never ")
- b.WriteString("introduce an entity, date or number that no claim states. Write the answer in the user's language.\n")
- b.WriteString("- If it does not (wrong topic, or the specific fact the question asks for is absent): do NOT ")
- b.WriteString("guess and do NOT answer from world knowledge. Report it as not answerable instead.\n")
+ b.WriteString("Answer the question above from these claims.\n")
+ b.WriteString("- End every line that states a fact with the handle of the claim it came from: `[ID:n]`, where n ")
+ b.WriteString("is that claim's `ref=n` value. Never introduce an entity, date or number that no claim states. ")
+ b.WriteString("Write the answer in the user's language.\n")
+ b.WriteString("- Combining claims IS answering: a difference, a count, an age, or a who/which that no single ")
+ b.WriteString("claim states outright is derived from the claims that give its inputs.\n")
+ b.WriteString("- Use the fact the question actually asks for. When the page states several candidates - two ")
+ b.WriteString("editions of an event, a release year and an award year, several people with the same role - pick ")
+ b.WriteString("the one the question names (last, first, most, the award, the time of the battle) instead of the ")
+ b.WriteString("first one you read.\n")
+ b.WriteString("- A count must be taken from the complete list the page gives, not from the entries you happened ")
+ b.WriteString("to read; a difference must name both operands.\n")
+ b.WriteString("- If the answer is computed from claims, finish with one line naming every claim it used: ")
+ b.WriteString("`derived_from: [ID:a], [ID:b]`. A derivation with one input is not a derivation.\n")
+ b.WriteString("- If a fact the answer needs is absent from every claim, do NOT guess and do NOT use world ")
+ b.WriteString("knowledge: report the question as not answerable and name that fact.\n")
b.WriteString("- Do not call tools and do not narrate what you are about to do: this call is the whole ")
b.WriteString("turn, so a plan or a promise to search further is not an answer.\n\n")
b.WriteString("Reply with ONE JSON object and nothing else:\n")
@@ -915,30 +942,85 @@ func claimAnswerPrompt(evidence string) string {
return b.String()
}
-// claimAnswer is the model's verdict on a sufficient-claims recall. answerable
-// false is a real outcome, not an error: it means the gate's relevance floor let
-// through claims that do not actually answer the question, so the caller must
-// fall back to the ordinary loop instead of shipping a non-answer.
+// claimVerifyPrompt renders the user message of the verification call: the one
+// place the question "does this answer the question that was asked?" is decided.
+//
+// It is asked with the answer in hand, which is what makes it tractable, and it
+// is asked about ONE failure mode: the near miss. Both wrong shortcuts measured
+// on this corpus were near misses - the release year given for the year of the
+// award, and an earlier World Series win given for "the last time they beat
+// them" while the page also stated the later one. Neither is detectable by asking
+// whether the page was sufficient, because the page WAS sufficient; the error is
+// in which fact the answer used.
+//
+// It explicitly forbids rewriting the answer or answering the question, so this
+// call stays a check rather than a second opinion that could itself be wrong in
+// a new way.
+func claimVerifyPrompt(evidence, answer string) string {
+ var b strings.Builder
+ b.WriteString("### Compiled evidence that was available\n")
+ b.WriteString(evidence)
+ b.WriteString("\n\n### Candidate answer\n")
+ b.WriteString(answer)
+ b.WriteString("\n\n### Task\n")
+ b.WriteString("Check ONE thing: is this candidate answer the answer to the question that was asked?\n")
+ b.WriteString("- Look for a near miss: a fact about the right subject that answers a DIFFERENT question. The ")
+ b.WriteString("release year instead of the year of the award. An earlier edition of an event when the question ")
+ b.WriteString("says last/latest. One candidate when the question asks for the first, the most, or the one that ")
+ b.WriteString("holds a named office. A namesake instead of the person. If another claim on the page fits the ")
+ b.WriteString("question better than the one the answer used, that is a near miss and the answer is wrong.\n")
+ b.WriteString("- Every date, number, title and entity the answer states must be stated by the claim it cites, ")
+ b.WriteString("or computed from the claims it names. A computation is fine when every input is on the page and ")
+ b.WriteString("the operands named really are those inputs.\n")
+ b.WriteString("- The page is the only source. \"It is well known that\" is not support, and a fact only the ")
+ b.WriteString("answer knows is not evidence.\n")
+ b.WriteString("- Do not rewrite the answer, do not improve it, and do not answer the question yourself. Judge ")
+ b.WriteString("only whether this answer answers this question.\n\n")
+ b.WriteString("Reply with ONE JSON object and nothing else:\n")
+ b.WriteString(`{"supported": true}`)
+ b.WriteString(" or ")
+ b.WriteString(`{"supported": false, "reason": "<wrong attribute, ignored candidate, or unsupported fact>"}`)
+ return b.String()
+}
+
+// claimAnswer is the answer call's reply. answerable=false is not an error: the
+// page may genuinely not hold the asked-for fact, and the caller then runs the
+// ordinary loop instead of shipping a non-answer.
type claimAnswer struct {
answerable bool
answer string
missing string
+ // derivedFrom is the handles the answer says it computed from, when it gave
+ // them as a JSON field rather than as the `derived_from:` line.
+ derivedFrom []string
}
-// parseClaimAnswer reads the JSON verdict. A reply that is not the requested
-// object is reported as not answerable: shipping unparsed prose is how a turn
-// with no retrieval ends up scored zero, and one extra loop is far cheaper.
+// parseClaimAnswer reads the JSON answer. A reply with no answer field is
+// reported as not answerable: shipping unparsed prose is how a turn ends up
+// scored zero, and one extra loop is far cheaper.
func parseClaimAnswer(reply string) claimAnswer {
obj, ok := decodeJSONObject(reply)
if !ok {
return claimAnswer{missing: "model did not return the requested JSON verdict"}
}
- out := claimAnswer{missing: stringFromAny(obj["missing"])}
+ out := claimAnswer{missing: strings.TrimSpace(stringFromAny(obj["missing"]))}
+ if s, ok := obj["answer"].(string); ok {
+ out.answer = strings.TrimSpace(s)
+ }
if v, ok := obj["answerable"].(bool); ok {
out.answerable = v
+ } else {
+ // A model that answers without the flag has still answered. Reading the
+ // missing field as a refusal would hand a usable answer to the loop, which
+ // is the expensive direction of this mistake.
+ out.answerable = out.answer != ""
}
- if s, ok := obj["answer"].(string); ok {
- out.answer = strings.TrimSpace(s)
+ if list, ok := obj["derived_from"].([]any); ok {
+ for _, item := range list {
+ if h := strings.TrimSpace(stringFromAny(item)); h != "" {
+ out.derivedFrom = append(out.derivedFrom, h)
+ }
+ }
}
if out.answerable && out.answer == "" {
out.answerable = false
@@ -946,17 +1028,87 @@ func parseClaimAnswer(reply string) claimAnswer {
return out
}
-// answerFromClaims is the termination of a turn whose pre-loop claim recall
-// already covers the question: ONE model call over the claims, with no tools and
-// therefore no raw-chunk read. It returns ("", nil) when the model judged the
-// claims insufficient, which the caller treats as a reason to run the ordinary
-// loop instead.
+// claimSupport is the verifier's finding on a candidate answer.
+type claimSupport struct {
+ supported bool
+ reason string
+ // parsed records whether the reply was the requested object at all. A reply
+ // that is not is treated as support (see parseClaimSupport) but must stay
+ // visible in the logs, or a prompt regression would look like a clean run.
+ parsed bool
+}
+
+// parseClaimSupport reads the verifier's JSON. A reply that is not the requested
+// object counts as SUPPORTED. The two mistakes are not symmetric: rejecting a
+// good answer hands the question to the loop for 300-600k tokens, while shipping
+// a wrong one costs 2-4 points, so the expensive mistake is the rejection. The
+// caller logs the unparsed case so this default cannot hide one.
+func parseClaimSupport(reply string) claimSupport {
+ obj, ok := decodeJSONObject(reply)
+ if !ok {
+ return claimSupport{supported: true}
+ }
+ v, ok := obj["supported"].(bool)
+ if !ok {
+ return claimSupport{supported: true}
+ }
+ return claimSupport{supported: v, reason: strings.TrimSpace(stringFromAny(obj["reason"])), parsed: true}
+}
+
+// claimHandleCount counts the distinct [ID:n] handles an answer cites.
+func claimHandleCount(answer string) int {
+ return claimDistinctHandles(claimHandleRe.FindAllString(answer, -1))
+}
+
+// claimDerivedInputs returns the handles an answer says it computed from: the
+// JSON field when it gave one, else the `derived_from:` line the prompt asks for
+// inside the answer text.
+func claimDerivedInputs(a claimAnswer) []string {
+ if len(a.derivedFrom) > 0 {
+ return a.derivedFrom
+ }
+ if m := claimDerivedLineRe.FindStringSubmatch(a.answer); m != nil {
+ return claimHandleRe.FindAllString(m[1], -1)
+ }
+ return nil
+}
+
+func claimDistinctHandles(handles []string) int {
+ seen := map[string]struct{}{}
+ for _, h := range handles {
+ seen[h] = struct{}{}
+ }
+ return len(seen)
+}
+
+var (
+ claimHandleRe = regexp.MustCompile(`\[ID:\d+\]`)
+ claimDerivedLineRe = regexp.MustCompile(`(?i)derived_from:\s*([^\n]*)`)
+)
+
+// answerFromClaims is the termination of a turn whose pre-loop compiled
+// prefetch already found claims for the question: an answer call over them, then
+// - only if it produced an answer - a verification call. No tools, so no raw
+// chunk is read either way.
+//
+// The order is deliberate and measured. Verification runs AFTER the answer, not
+// before it: a sufficiency call with no answer in hand refuses pages that hold
+// every needed fact, and each of those refusals costs the loop 300-600k tokens
+// for the same final score. With the answer in hand the check is narrower and
+// cheaper per question (it only runs when there IS an answer), and it can look
+// for the failure that actually happens here: the right subject, the wrong fact
+// (a release year given for an award year, an earlier edition given for "the
+// last time").
+//
+// It returns ("", nil) when no answer survives, which the caller treats as a
+// reason to run the ordinary loop instead - the loop, not this path, decides
+// what to search next.
func answerFromClaims(
ctx context.Context,
m *models.EinoChatModel,
instruction string,
messages []*schema.Message,
- pf claimPrefetch,
+ pf compiledPrefetch,
) (string, error) {
if m == nil || strings.TrimSpace(pf.evidence) == "" {
return "", nil
@@ -969,27 +1121,103 @@ func answerFromClaims(
// The template's instruction goes in as the system message because this path
// bypasses the agent that would otherwise carry it: the answer must keep the
// same shape and language rules as every other answer this template ships.
- req := make([]*schema.Message, 0, len(messages)+2)
- req = append(req, schema.SystemMessage(instruction))
- req = append(req, messages...)
- req = append(req, schema.UserMessage(claimAnswerPrompt(pf.evidence)))
+ ask := func(prompt string) (string, error) {
+ req := make([]*schema.Message, 0, len(messages)+2)
+ req = append(req, schema.SystemMessage(instruction))
+ req = append(req, messages...)
+ req = append(req, schema.UserMessage(prompt))
+ resp, err := m.Generate(ctx, req)
+ if err != nil {
+ return "", err
+ }
+ if resp == nil {
+ return "", nil
+ }
+ return resp.Content, nil
+ }
- resp, err := m.Generate(ctx, req)
+ answerReply, err := ask(claimAnswerPrompt(pf.evidence))
if err != nil {
return "", err
}
- if resp == nil {
+ answer := parseClaimAnswer(answerReply)
+ if !answer.answerable {
+ // gap_overlap splits the two ways a refusal can happen, and it is the only
+ // signal that tells them apart in the logs: a gap whose words ARE on the
+ // page means the model would not use what it had (selection or prompt),
+ // a gap whose words are not means the page never held the fact
+ // (retrieval). Both need different work, and only this number says which.
+ common.InfoCtx(ctx, "agentic_rag: claims judged unanswerable by the model",
+ zap.Int("claims", len(pf.claims)),
+ zap.Int("chunks", len(pf.chunks)),
+ zap.Strings("docs", claimDocsInOrder(pf.claims)),
+ zap.String("missing", truncateForLog(answer.missing, 200)),
+ zap.Float64("gap_overlap", claimGapOverlap(pf.claims, answer.missing)),
+ zap.Int("reply_bytes", len(answerReply)))
return "", nil
}
- verdict := parseClaimAnswer(resp.Content)
- if !verdict.answerable {
- common.InfoCtx(ctx, "agentic_rag: claims judged insufficient by the model",
+ // Deterministic floors, checked before the verifier because they are free.
+ // An answer that cites nothing cannot be resolved into a reference payload,
+ // and an answer that names a derivation but only one input has not derived
+ // anything - both are the shape a near miss takes.
+ handles := claimHandleCount(answer.answer)
+ if handles == 0 {
+ common.InfoCtx(ctx, "agentic_rag: claim answer cites no claim; falling back to the loop",
zap.Int("claims", len(pf.claims)),
- zap.Strings("docs", pf.docs),
- zap.String("missing", truncateForLog(verdict.missing, 200)))
+ zap.Int("answer_bytes", len(answer.answer)))
return "", nil
}
- return verdict.answer, nil
+ if derived := claimDerivedInputs(answer); len(derived) > 0 {
+ if n := claimDistinctHandles(derived); n < 2 {
+ common.InfoCtx(ctx, "agentic_rag: claim answer derives from one claim; falling back to the loop",
+ zap.Int("derived_inputs", n),
+ zap.Int("claims", len(pf.claims)),
+ zap.Int("answer_bytes", len(answer.answer)))
+ return "", nil
+ }
+ }
+
+ verifyReply, err := ask(claimVerifyPrompt(pf.evidence, answer.answer))
+ if err != nil {
+ return "", err
+ }
+ support := parseClaimSupport(verifyReply)
+ if !support.parsed {
+ common.WarnCtx(ctx, "agentic_rag: claim verification reply was not the requested JSON; answer accepted",
+ zap.Int("reply_bytes", len(verifyReply)))
+ }
+ if !support.supported {
+ common.InfoCtx(ctx, "agentic_rag: claim answer rejected by verification; falling back to the loop",
+ zap.String("reason", truncateForLog(support.reason, 200)),
+ zap.Int("handles", handles),
+ zap.Int("claims", len(pf.claims)),
+ zap.Int("answer_bytes", len(answer.answer)))
+ return "", nil
+ }
+ return answer.answer, nil
+}
+
+// claimGapOverlap is the share of the refused gap's content words that the page's
+// claims already state. It is a diagnostic, not a control signal: the refusal
+// still falls back to the loop. See the log line it feeds.
+func claimGapOverlap(claims []claimHit, gap string) float64 {
+ gapTokens := claimTokens(gap)
+ if len(gapTokens) == 0 {
+ return 0
+ }
+ page := make(map[string]struct{}, len(claims)*8)
+ for _, c := range claims {
+ for t := range claimTokens(c.name + " " + c.description + " " + c.quote) {
+ page[t] = struct{}{}
+ }
+ }
+ hit := 0
+ for t := range gapTokens {
+ if _, ok := page[t]; ok {
+ hit++
+ }
+ }
+ return float64(hit) / float64(len(gapTokens))
}
// finalizeAnswer issues a single deterministic synthesis call so a turn that
diff --git a/internal/agentic_rag/claim_filter_live_manual_test.go b/internal/agentic_rag/claim_filter_live_manual_test.go
new file mode 100644
index 0000000000..4bbdc7e84f
--- /dev/null
+++ b/internal/agentic_rag/claim_filter_live_manual_test.go
@@ -0,0 +1,241 @@
+//go:build manual
+
+//
+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+package agentic_rag
+
+import (
+ "bytes"
+ "context"
+ "encoding/json"
+ "fmt"
+ "io"
+ "net/http"
+ "os"
+ "sort"
+ "strings"
+ "testing"
+ "time"
+ "unicode/utf8"
+)
+
+// TestClaimFilterLiveManual is the end-to-end check for the claim exit: real
+// claim rows from a live corpus, the real decision-model API, and the rendered
+// page measured before and after the filter.
+//
+// It spends tokens on the configured decision model, which is what puts it in the
+// manual tier:
+//
+// CLAIM_LIVE_TENANT=<tenant> CLAIM_LIVE_QUESTION="<question>" \
+// RAGFLOW_DECISION_BACKEND=decision-api \
+// RAGFLOW_DECISION_URL=https://api.bamboonode.dev/v1/decisions \
+// RAGFLOW_DECISION_KEY=<key> \
+// RAGFLOW_DECISION_MODEL=startlux-decision-27b-autothink \
+// bash build.sh --test-manual -run ClaimFilterLive -v ./internal/agentic_rag/
+//
+// The probability quartiles are printed because the threshold is model-specific:
+// the shipped 0.30 was fitted on decision-model-preview, and a claim line is far
+// shorter than the passage that threshold was measured on.
+func TestClaimFilterLiveManual(t *testing.T) {
+ tenant := strings.TrimSpace(os.Getenv("CLAIM_LIVE_TENANT"))
+ question := strings.TrimSpace(os.Getenv("CLAIM_LIVE_QUESTION"))
+ if tenant == "" || question == "" {
+ t.Fatal("set CLAIM_LIVE_TENANT and CLAIM_LIVE_QUESTION")
+ }
+ es := liveES{
+ url: liveEnv("CLAIM_LIVE_ES", "http://localhost:1200"),
+ user: liveEnv("CLAIM_LIVE_ES_USER", "elastic"),
+ pass: liveEnv("CLAIM_LIVE_ES_PASS", "infini_rag_flow"),
+ }
+ limit := 12
+ index := "ragflow_" + tenant
+
+ rows := es.search(t, index, map[string]interface{}{
+ "size": limit,
+ "query": map[string]interface{}{"bool": map[string]interface{}{
+ "filter": []interface{}{
+ map[string]interface{}{"term": map[string]interface{}{"entity_type_kwd": "claim"}},
+ map[string]interface{}{"term": map[string]interface{}{"scope_kwd": "doc"}},
+ },
+ }},
+ "_source": []string{"content_with_weight", "source_chunk_ids", "doc_id"},
+ })
+
+ claims := make([]claimHit, 0, len(rows))
+ anchors := make([]string, 0, len(rows))
+ seen := map[string]struct{}{}
+ for _, row := range rows {
+ h, ok := parseClaimHit(row)
+ if !ok {
+ continue
+ }
+ claims = append(claims, h)
+ for _, id := range h.sourceChunkIDs {
+ if _, dup := seen[id]; dup {
+ continue
+ }
+ seen[id] = struct{}{}
+ anchors = append(anchors, id)
+ }
+ }
+ if len(claims) == 0 {
+ t.Fatalf("no usable claim rows under index %s", index)
+ }
+
+ chunkRunes := es.chunkRunes(t, index, anchors)
+
+ ctx := withDecisionScope(WithQuery(context.Background(), question), tenant, "")
+ if !decisionAvailable(ctx) {
+ t.Fatal("decision backend unavailable: set RAGFLOW_DECISION_BACKEND=decision-api and RAGFLOW_DECISION_KEY")
+ }
+
+ // Score first, so the distribution is visible even when the current threshold
+ // keeps everything. filterClaims then re-uses this pass through the judge's
+ // own memo, which is why the second call costs no extra requests.
+ texts := make([]string, 0, len(claims))
+ for _, c := range claims {
+ texts = append(texts, claimJudgeText(c))
+ }
+ judgeStart := time.Now()
+ verdicts := decisionJudge(ctx, question, texts)
+ judgeElapsed := time.Since(judgeStart)
+ probs := make([]float64, 0, len(verdicts))
+ for _, v := range verdicts {
+ if v.Judged {
+ probs = append(probs, v.Probability)
+ }
+ }
+ sort.Float64s(probs)
+
+ before := claimEvidenceBlock(context.Background(), claims)
+ start := time.Now()
+ filtered := filterClaims(ctx, question, claims)
+ elapsed := time.Since(start)
+ after := claimEvidenceBlock(context.Background(), filtered)
+
+ beforeRunes := utf8.RuneCountInString(before)
+ afterRunes := utf8.RuneCountInString(after)
+
+ fmt.Printf("\n=== claim exit, live ===\n")
+ fmt.Printf("question : %s\n", question)
+ fmt.Printf("anchor chunks : %d (raw text %d runes)\n", len(anchors), chunkRunes)
+ fmt.Printf("claims in : %d\n", len(claims))
+ fmt.Printf("claims out : %d (dropped %d, %.0f%%)\n",
+ len(filtered), len(claims)-len(filtered), 100*float64(len(claims)-len(filtered))/float64(len(claims)))
+ fmt.Printf("judged : %d / %d\n", len(probs), len(verdicts))
+ if len(probs) > 0 {
+ fmt.Printf("P(relevant) min : %.3f\n", probs[0])
+ fmt.Printf("P(relevant) p25 : %.3f\n", probs[len(probs)/4])
+ fmt.Printf("P(relevant) median : %.3f\n", probs[len(probs)/2])
+ fmt.Printf("P(relevant) p75 : %.3f\n", probs[3*len(probs)/4])
+ fmt.Printf("P(relevant) max : %.3f\n", probs[len(probs)-1])
+ }
+ fmt.Printf("page runes before : %d\n", beforeRunes)
+ fmt.Printf("page runes after : %d (%.1f%% of before)\n", afterRunes, 100*float64(afterRunes)/float64(beforeRunes))
+ fmt.Printf("claims vs raw text : before %.2fx, after %.2fx of the anchored chunk text\n",
+ float64(beforeRunes)/float64(chunkRunes), float64(afterRunes)/float64(chunkRunes))
+ fmt.Printf("judge wall time : %s (scoring) + %s (filter pass)\n", judgeElapsed, elapsed)
+
+ if len(filtered) > len(claims) {
+ t.Fatalf("filter kept more claims than it was given: %d > %d", len(filtered), len(claims))
+ }
+ if afterRunes > beforeRunes {
+ t.Fatalf("filtered page is larger: %d > %d", afterRunes, beforeRunes)
+ }
+}
+
+func liveEnv(name, def string) string {
+ if v := strings.TrimSpace(os.Getenv(name)); v != "" {
+ return v
+ }
+ return def
+}
+
+// liveES is the smallest read-only client the check needs: it only ever issues
+// _search, so the live corpus is never written.
+type liveES struct {
+ url string
+ user string
+ pass string
+}
+
+func (e liveES) search(t *testing.T, index string, body map[string]interface{}) []map[string]interface{} {
+ t.Helper()
+ raw, err := json.Marshal(body)
+ if err != nil {
+ t.Fatalf("encode search body: %v", err)
+ }
+ req, err := http.NewRequest(http.MethodPost, strings.TrimSuffix(e.url, "/")+"/"+index+"/_search", bytes.NewReader(raw))
+ if err != nil {
+ t.Fatalf("build request: %v", err)
+ }
+ req.Header.Set("Content-Type", "application/json")
+ if e.user != "" {
+ req.SetBasicAuth(e.user, e.pass)
+ }
+ resp, err := (&http.Client{Timeout: 60 * time.Second}).Do(req)
+ if err != nil {
+ t.Fatalf("search %s: %v", index, err)
+ }
+ defer resp.Body.Close()
+ payload, _ := io.ReadAll(resp.Body)
+ if resp.StatusCode != http.StatusOK {
+ t.Fatalf("search %s: %s: %s", index, resp.Status, string(payload))
+ }
+ var out struct {
+ Hits struct {
+ Hits []struct {
+ Score *float64 `json:"_score"`
+ Source map[string]interface{} `json:"_source"`
+ } `json:"hits"`
+ } `json:"hits"`
+ }
+ if err := json.Unmarshal(payload, &out); err != nil {
+ t.Fatalf("decode search response: %v", err)
+ }
+ rows := make([]map[string]interface{}, 0, len(out.Hits.Hits))
+ for _, h := range out.Hits.Hits {
+ row := h.Source
+ if row == nil {
+ row = map[string]interface{}{}
+ }
+ if h.Score != nil {
+ row["_score"] = *h.Score
+ }
+ rows = append(rows, row)
+ }
+ return rows
+}
+
+// chunkRunes is the raw text the claim page is competing with: the anchored
+// chunks the same claims were compiled from.
+func (e liveES) chunkRunes(t *testing.T, index string, ids []string) int {
+ t.Helper()
+ if len(ids) == 0 {
+ return 0
+ }
+ rows := e.search(t, index, map[string]interface{}{
+ "size": len(ids),
+ "query": map[string]interface{}{"terms": map[string]interface{}{"_id": ids}},
+ "_source": []string{"content_with_weight"},
+ })
+ total := 0
+ for _, row := range rows {
+ total += utf8.RuneCountInString(stringFromAny(row["content_with_weight"]))
+ }
+ return total
+}
diff --git a/internal/agentic_rag/compiled_evidence.go b/internal/agentic_rag/compiled_evidence.go
new file mode 100644
index 0000000000..061dde5aad
--- /dev/null
+++ b/internal/agentic_rag/compiled_evidence.go
@@ -0,0 +1,1181 @@
+//
+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+package agentic_rag
+
+// Compiled-evidence-first retrieval.
+//
+// A compiled claim states one atomic proposition plus the verbatim quote it was
+// compiled from, and it names the chunk that quote came from. For a model that
+// only needs the proposition, reading the claim costs a fraction of reading the
+// chunk — and it carries its own evidence, so the answer can cite the source
+// chunk without the chunk ever entering the context.
+//
+// The leg is ANCHORED ON THE SEARCH, not on the question: the ordinary hybrid
+// chunk retrieval runs first, and the claims looked up afterwards are exactly
+// the ones compiled FROM the chunks that search returned. Recalling claims by
+// their own text (the previous design) made the compiled leg a second,
+// independent ranking that could land on a different document than the raw
+// retrieval did; anchoring it to the chunks means the compiled evidence can
+// never be about a document the retrieval rejected.
+//
+// The anchored leg is no longer the ONLY one. A claim is an atomic statement, so
+// its own text is a better query target than the chunk it came from: a chunk is a
+// table or a paragraph whose embedding is diluted by everything else it says.
+// The objection above still holds for a leg that REPLACES the anchor - it would
+// be a second ranking that can land elsewhere - and this leg is kept out of that
+// way: the anchor's claims stay first, the text leg only ADDS claims the anchor
+// did not produce, and a claim both legs found appears once. Measured offline on
+// 20 FRAMES questions, the anchor alone covered 3 gold answers and the union
+// covered 9; the anchor also had one answer the text leg missed, which is why
+// neither leg replaces the other.
+//
+// Two consumers, one rule ("compiled first, raw chunk only when it is not
+// enough"):
+//
+// - the pre-loop probe: one search, an answer call over the claims it found,
+// then a verification of that answer. An answer that survives verification
+// ends the turn without a chunk ever being read; one that does not is dropped
+// and the ordinary loop runs, because a multi-hop question's second fact
+// lives in a document the question's own wording never reaches and the loop
+// is the only place that decides what to search next.
+// - every locate tool result: the claims compiled from THAT result set's
+// chunks are rendered ahead of the hits, so a mid-loop search can be
+// answered without list_chunks. Claims the run has already shown are not
+// repeated.
+//
+// A corpus without compiled claims pays one existence probe and nothing else.
+//
+// Coverage, measured on the FRAMES corpus: of the 68,677 chunks the retrieval
+// can actually return (available_int=1), 51,222 (75%) are referenced by at least
+// one claim, and the compiled rows carry 4-36 claims per chunk. So most hits can
+// be answered from their compiled artifacts, but not all: a run whose
+// covered_chunks/chunks ratio is low is looking at uncompiled chunks, and the raw
+// chunk is the only evidence there is.
+
+import (
+ "context"
+ "fmt"
+ "sort"
+ "strconv"
+ "strings"
+ "sync"
+ "unicode"
+
+ "github.com/cloudwego/eino/schema"
+ "go.uber.org/zap"
+
+ "ragflow/internal/agent/runtime"
+ "ragflow/internal/common"
+ "ragflow/internal/dao"
+ "ragflow/internal/engine"
+ enginetypes "ragflow/internal/engine/types"
+ "ragflow/internal/service/nav"
+ "ragflow/internal/tokenizer"
+)
+
+const (
+ // compiledAnchorTopN is the chunk page the pre-loop probe anchors on. It is
+ // the retrieval's own top-N, not a claim count: the claims come from
+ // whatever these chunks hold.
+ compiledAnchorTopN = 10
+ // compiledClaimsPerChunk sizes ONE claim lookup. It is a query bound, not a
+ // cap on what is shown: a lookup has to name a row count, so it asks for the
+ // most rows a chunk was measured to carry (38) for every chunk it asks
+ // about, and every row that comes back is served. A chunk's claim set is that
+ // chunk's representation - serving a part of it serves a part of the chunk,
+ // and a model that is shown a part cannot judge whether the whole suffices.
+ compiledClaimsPerChunk = 48
+ // claimSearchTopK is the depth of the claim-TEXT leg. Measured offline on the
+ // same 20 FRAMES questions: depth 20 covered 1 gold answer, depth 50 covered 8.
+ // Depth is cheap here because the page is cut down again per line by the
+ // decision filter, so shallow recall is the expensive choice, not deep recall.
+ claimSearchTopK = 50
+ // compiledNoticeShownChunks caps the pointer line that names hits whose
+ // statements this turn already showed. Eight is where the line stays under
+ // ~300 characters: it pays for itself if it averts a single deep read, and it
+ // stops paying once it grows into a second block of text.
+ compiledNoticeShownChunks = 8
+)
+
+// compiledRun is the per-turn compiled-evidence state: the scope claims are
+// looked up in, whether the corpus has any, and what this turn already showed.
+//
+// It is per-run rather than per-tool because the same claim is commonly the
+// compiled artifact of several retrieved chunks, and re-rendering it in a later
+// search result pays for text the model already holds.
+type compiledRun struct {
+ tenantID string
+ datasetIDs []string
+
+ mu sync.Mutex
+ probed bool
+ present bool
+ shown map[string]struct{}
+}
+
+type compiledRunKey struct{}
+
+// withCompiledRun publishes the turn's compiled-evidence state. It is installed
+// once per run by Run so the pre-loop probe and every locate tool share one
+// scope and one "already shown" set.
+func withCompiledRun(ctx context.Context, tenantID string, datasetIDs []string) context.Context {
+ if len(datasetIDs) == 0 {
+ return ctx
+ }
+ return context.WithValue(ctx, compiledRunKey{}, &compiledRun{
+ tenantID: tenantID,
+ datasetIDs: append([]string(nil), datasetIDs...),
+ shown: map[string]struct{}{},
+ })
+}
+
+func compiledRunFrom(ctx context.Context) *compiledRun {
+ r, _ := ctx.Value(compiledRunKey{}).(*compiledRun)
+ return r
+}
+
+// claimsPresent answers the corpus-level gate once per run. The probe is a
+// single existence read, but a run issues several searches, and each one asking
+// the same question would be pure latency.
+func (r *compiledRun) claimsPresent(ctx context.Context) bool {
+ if r == nil {
+ return false
+ }
+ r.mu.Lock()
+ if r.probed {
+ present := r.present
+ r.mu.Unlock()
+ return present
+ }
+ tenant, datasets := r.tenantID, r.datasetIDs
+ r.mu.Unlock()
+
+ present := claimRowsPresent(ctx, tenant, datasets)
+
+ r.mu.Lock()
+ r.probed = true
+ r.present = present
+ r.mu.Unlock()
+ return present
+}
+
+// takeUnseen keeps every claim this run has not shown yet and records them as
+// shown. A claim already served keeps its ref handle in the transcript, so
+// repeating its text adds nothing the model does not have - and a claim the turn
+// has NOT served is part of its chunk, so dropping it would serve half a chunk.
+func (r *compiledRun) takeUnseen(claims []claimHit) []claimHit {
+ out := make([]claimHit, 0, len(claims))
+ r.mu.Lock()
+ defer r.mu.Unlock()
+ if r.shown == nil {
+ r.shown = map[string]struct{}{}
+ }
+ for _, c := range claims {
+ key := claimKey(c)
+ if key == "" {
+ continue
+ }
+ if _, dup := r.shown[key]; dup {
+ continue
+ }
+ r.shown[key] = struct{}{}
+ out = append(out, c)
+ }
+ return out
+}
+
+// claimShown reports whether this turn already put the claim's statement in
+// front of the model. It reads the same set takeUnseen writes.
+func (r *compiledRun) claimShown(c claimHit) bool {
+ if r == nil {
+ return false
+ }
+ key := claimKey(c)
+ if key == "" {
+ return false
+ }
+ r.mu.Lock()
+ defer r.mu.Unlock()
+ _, ok := r.shown[key]
+ return ok
+}
+
+// compiledAnchorSearch is the chunk retrieval the compiled leg hangs off: the
+// same hybrid retriever the search_chunks tool uses, over original document
+// text only. It is a variable so a test can drive the whole strategy without a
+// retrieval backend.
+var compiledAnchorSearch = searchOriginalChunksForQuestion
+
+// searchOriginalChunksForQuestion runs ONE hybrid query over the corpus's
+// ordinary prose chunks. Compiled products are excluded for the same reason the
+// locate tools exclude them: the anchors are the documents, and a claim row
+// that matched the question would make the compiled leg anchor on itself.
+func searchOriginalChunksForQuestion(ctx context.Context, tenantID string, datasetIDs, docScope []string, question string, topN int) []runtime.RetrievalChunk {
+ question = strings.TrimSpace(question)
+ if question == "" || tenantID == "" || len(datasetIDs) == 0 {
+ return nil
+ }
+ svc := runtime.GetRetrievalService()
+ if svc == nil {
+ return nil
+ }
+ if topN <= 0 {
+ topN = compiledAnchorTopN
+ }
+ if len(datasetIDs) > 10 {
+ datasetIDs = datasetIDs[:10]
+ }
+ // Engine context with no per-query timeout: the run-level budget caps the
+ // turn (see runLocateSearch for the same rationale).
+ ectx, ecancel := engineCallContext(ctx)
+ defer ecancel()
+
+ threshold := searchChunksDefaultSimilarityThreshold
+ weight := searchChunksDefaultKeywordsSimilarityWeight
+ chunks, err := svc.Search(ectx, dao.DB, runtime.RetrievalRequest{
+ Query: question,
+ DatasetIDs: datasetIDs,
+ TopN: topN,
+ TopK: topN * 4,
+ SimilarityThreshold: &threshold,
+ KeywordsSimilarityWeight: &weight,
+ DocScope: docScope,
+ TenantID: tenantID,
+ AllowDenseFallback: new(false),
+ SelectFields: grepChunksSelectFields,
+ OnlyOriginalText: true,
+ })
+ if err != nil {
+ common.DebugCtx(ctx, "agentic_rag: compiled evidence anchor search failed",
+ zap.Strings("datasets", datasetIDs), zap.Error(err))
+ return nil
+ }
+ out := make([]runtime.RetrievalChunk, 0, len(chunks))
+ for _, c := range chunks {
+ if c.ID == "" || isGraphChunkContent(c.Content) {
+ continue
+ }
+ out = append(out, c)
+ }
+ return out
+}
+
+// compiledClaimsByChunk reads the claim rows compiled FROM the given chunks. A
+// variable so a test can supply claims without an engine.
+var compiledClaimsByChunk = readCompiledClaimsByChunk
+
+func readCompiledClaimsByChunk(ctx context.Context, tenantID string, datasetIDs, chunkIDs, docScope []string, limit int) []claimHit {
+ if len(chunkIDs) == 0 || len(datasetIDs) == 0 {
+ return nil
+ }
+ de := engine.Get()
+ if de == nil {
+ return nil
+ }
+ filter := map[string]interface{}{
+ "entity_type_kwd": []string{navClaimRowType},
+ "scope_kwd": []string{navClaimDocScope},
+ "source_chunk_ids": chunkIDs,
+ }
+ if len(docScope) > 0 {
+ filter["doc_id"] = docScope
+ }
+ res, err := de.Search(ctx, &enginetypes.SearchRequest{
+ IndexNames: []string{indexNameFor(tenantID, "")},
+ KbIDs: datasetIDs,
+ SelectFields: []string{
+ "content_with_weight", "source_chunk_ids", "entity_type_kwd", "compile_kwd", "doc_id",
+ },
+ Filter: filter,
+ Limit: limit,
+ IncludeUnavailable: true,
+ })
+ if err != nil || res == nil {
+ common.DebugCtx(ctx, "agentic_rag: compiled claim lookup failed",
+ zap.Strings("datasets", datasetIDs), zap.Error(err))
+ return nil
+ }
+ out := make([]claimHit, 0, len(res.Chunks))
+ for _, row := range res.Chunks {
+ if h, ok := parseClaimHit(row); ok {
+ out = append(out, h)
+ }
+ }
+ return out
+}
+
+// claimPageEnabled reports whether the claim page is served. Off means the
+// prefetch serves the retrieved chunks as raw text: the control arm for measuring
+// what the claim artifact is worth, and an escape hatch for a deployment whose
+// ingestion has not compiled claims yet.
+func claimPageEnabled() bool {
+ return envBoolDefault(common.EnvClaimPage, true)
+}
+
+// compiledClaimsForChunks pages the claims compiled FROM a retrieved chunk set.
+//
+// The chunk set is the whole evidence boundary: a claim exists because some
+// chunk stated it, so the page is exactly "the chunks the search returned, and
+// what each of them states". No claim of a chunk the search did not return is
+// offered - that would be evidence the retrieval rejected this turn.
+//
+// The anchor is the retrieval's rank, so the best-ranked chunk's claims come
+// first; within one chunk the claim closest to the question wins. The coverage
+// score ORDERS the claims (those that name the question's own terms lead) rather
+// than dropping any: a chunk's claim set is that chunk's representation, so the
+// page is every claim of every chunk it was asked about. Nothing is capped -
+// dropping a claim would drop part of the chunk it belongs to, and the caller's
+// verdict would then be judging an excerpt rather than the evidence.
+//
+// The second return names the chunks the store HAS claims for. It is not the
+// same as the chunks the page covers: a claim whose statement another chunk
+// already stated is deduped away, and a chunk whose every claim was such a
+// duplicate still has claims - it must not be served as raw text on top of them.
+func compiledClaimsForChunks(ctx context.Context, tenantID string, datasetIDs, chunkIDs []string, question string) ([]claimHit, map[string]struct{}) {
+ if len(chunkIDs) == 0 {
+ return nil, nil
+ }
+ docScope, _ := resolveDocumentScope(ctx, nil)
+ // The pool is sized by the ANCHOR COUNT: the store returns filter hits in its
+ // own order, so the query has to be wide enough to hold every anchor's whole
+ // claim set before the local ranking sees it. Every chunk asked about is
+ // queried and every row that comes back is served - a chunk's claim set is
+ // that chunk's representation, so neither the chunk list nor the row count can
+ // be trimmed without serving a part of a chunk as if it were the whole.
+ pool := len(chunkIDs) * compiledClaimsPerChunk
+ raw := compiledClaimsByChunk(ctx, tenantID, datasetIDs, chunkIDs, docScope, pool)
+ rank := make(map[string]int, len(chunkIDs))
+ for i, id := range chunkIDs {
+ if _, seen := rank[id]; !seen {
+ rank[id] = i
+ }
+ }
+ questionTokens := claimTokens(question)
+ type candidate struct {
+ hit claimHit
+ rank int
+ coverage float64
+ }
+ seen := map[string]struct{}{}
+ hasClaims := make(map[string]struct{}, len(chunkIDs))
+ cands := make([]candidate, 0, len(raw))
+ matched, dropped := 0, 0
+ for _, h := range raw {
+ // Match against EVERY source chunk, and attribute the claim to the
+ // best-ranked one that matched. A claim with no source chunk in the page
+ // is not the compiled artifact of anything the search returned, so it is
+ // dropped rather than appended: the whole point of the anchor is that the
+ // compiled leg cannot speak about a document the retrieval rejected.
+ best, bestID := -1, ""
+ for _, id := range h.sourceChunkIDs {
+ if r, ok := rank[id]; ok && (best < 0 || r < best) {
+ best, bestID = r, id
+ }
+ }
+ if best < 0 {
+ if r, ok := rank[h.chunkID]; ok {
+ best, bestID = r, h.chunkID
+ }
+ }
+ if best < 0 {
+ dropped++
+ continue
+ }
+ // Recorded BEFORE the duplicate check: a chunk whose statements were all
+ // already stated elsewhere still has claims, and must not be served as
+ // raw text on top of them.
+ hasClaims[bestID] = struct{}{}
+ key := claimKey(h)
+ if key == "" {
+ continue
+ }
+ if _, dup := seen[key]; dup {
+ continue
+ }
+ seen[key] = struct{}{}
+ matched++
+ h.chunkID = bestID
+ cands = append(cands, candidate{hit: h, rank: best, coverage: claimCoverage(questionTokens, h)})
+ }
+ common.DebugCtx(ctx, "agentic_rag: chunk-anchored claim lookup",
+ zap.Int("anchors", len(chunkIDs)),
+ zap.Int("rows_returned", len(raw)),
+ zap.Int("rows_on_anchor", matched),
+ zap.Int("rows_dropped", dropped))
+
+ if len(cands) == 0 {
+ return nil, hasClaims
+ }
+ sort.SliceStable(cands, func(i, j int) bool {
+ if cands[i].rank != cands[j].rank {
+ return cands[i].rank < cands[j].rank
+ }
+ if cands[i].coverage != cands[j].coverage {
+ return cands[i].coverage > cands[j].coverage
+ }
+ return cands[i].hit.name < cands[j].hit.name
+ })
+
+ // No budget, no rounds, no window: the page is every claim the chunks above
+ // carry, best-ranked chunk first and closest-to-question first inside it. A
+ // chunk is either on the page whole or not on it at all.
+ kept := make([]claimHit, 0, len(cands))
+ for _, c := range cands {
+ kept = append(kept, c.hit)
+ }
+ // The text leg is a UNION, appended after the anchored claims and deduped
+ // against them: the anchored order is the retrieval's own ranking and stays
+ // authoritative, while a claim only the text leg found is still evidence the
+ // anchor could not reach. hasClaims is deliberately untouched - it names the
+ // chunks the page is responsible for, and a chunk this turn never retrieved is
+ // not one of them.
+ searched := searchClaimsForQuestion(ctx, tenantID, datasetIDs, docScope, question, claimSearchTopK)
+ added := 0
+ for _, c := range searched {
+ key := claimKey(c)
+ if key == "" {
+ continue
+ }
+ if _, dup := seen[key]; dup {
+ continue
+ }
+ seen[key] = struct{}{}
+ kept = append(kept, c)
+ added++
+ }
+ common.DebugCtx(ctx, "agentic_rag: claim page assembled",
+ zap.Int("anchored", len(cands)),
+ zap.Int("searched", len(searched)),
+ zap.Int("search_added", added),
+ zap.Int("kept", len(kept)))
+ // The page is assembled whole and cut per LINE afterwards: a claim is an
+ // atomic statement, so the sufficiency model can be asked about it on its
+ // own, and one the question does not need leaves without taking its
+ // neighbours' text with it. This is the only bound the page has - a chunk's
+ // claim set can cost more than the chunk it stands for.
+ return filterClaims(ctx, question, kept), hasClaims
+}
+
+// claimSearchEnabled gates the claim-text leg. On by default: the leg can only
+// add claims the anchored page did not have, and it degrades to nothing when the
+// deployment has no query-side embedder.
+func claimSearchEnabled() bool {
+ return envBoolDefault(common.EnvClaimSearch, true)
+}
+
+// searchClaimsForQuestion searches the claim rows BY THEIR OWN TEXT, which is the
+// one lookup the anchored leg cannot make: a claim is reachable only through a
+// chunk the retrieval already ranked, so a fact whose chunk ranked eleventh is
+// invisible however well its claim matches the question.
+//
+// Every degraded path returns nil, and nil means "the anchored page stands": no
+// engine, no nav service, no tenant embedder, an engine error. The leg is an
+// extra, never a replacement, so a deployment that cannot embed is byte-for-byte
+// the run it was before this existed.
+func searchClaimsForQuestion(ctx context.Context, tenantID string, datasetIDs, docScope []string, question string, limit int) []claimHit {
+ if limit <= 0 || !claimSearchEnabled() || len(datasetIDs) == 0 || tenantID == "" {
+ return nil
+ }
+ question = strings.TrimSpace(question)
+ if question == "" {
+ return nil
+ }
+ // The tenant's default embedding model decides the column: the rows carry a
+ // vector per model dimension, and addressing a column the rows do not have is
+ // an empty result, not an error.
+ vec := claimQueryVector(ctx, tenantID, question)
+ if len(vec) == 0 {
+ return nil
+ }
+ filter := map[string]interface{}{
+ "entity_type_kwd": []string{navClaimRowType},
+ "scope_kwd": []string{navClaimDocScope},
+ }
+ if len(docScope) > 0 {
+ filter["doc_id"] = docScope
+ }
+ rows, err := claimSearchRows(ctx, &enginetypes.SearchRequest{
+ IndexNames: []string{indexNameFor(tenantID, "")},
+ KbIDs: datasetIDs,
+ SelectFields: []string{
+ "content_with_weight", "source_chunk_ids", "entity_type_kwd", "compile_kwd", "doc_id",
+ },
+ Filter: filter,
+ Limit: limit,
+ IncludeUnavailable: true,
+ MatchExprs: []interface{}{&enginetypes.MatchDenseExpr{
+ VectorColumnName: fmt.Sprintf("q_%d_vec", len(vec)),
+ EmbeddingData: vec,
+ EmbeddingDataType: "float",
+ DistanceType: "cosine",
+ TopN: limit,
+ }},
+ })
+ if err != nil {
+ common.DebugCtx(ctx, "agentic_rag: claim text search failed",
+ zap.Strings("datasets", datasetIDs), zap.Error(err))
+ return nil
+ }
+ out := make([]claimHit, 0, len(rows))
+ for _, row := range rows {
+ if h, ok := parseClaimHit(row); ok {
+ out = append(out, h)
+ }
+ }
+ return out
+}
+
+// claimQueryVector encodes the question with the tenant's default embedding
+// model. It is a seam for the same reason the chunk search is: "nil means the
+// anchored page stands" is the leg's whole contract, and a deployment without a
+// query-side embedder has to be reachable from a unit test.
+var claimQueryVector = encodeClaimQueryVector
+
+// claimSearchRows runs the claim-KNN. A nil engine and an engine error are the
+// same outcome - no extra claims - so neither can fail the page.
+var claimSearchRows = searchClaimRows
+
+func encodeClaimQueryVector(ctx context.Context, tenantID, question string) []float64 {
+ svc := nav.GetNavService()
+ if svc == nil {
+ return nil
+ }
+ return svc.EncodeQueryVector(ctx, tenantID, question)
+}
+
+func searchClaimRows(ctx context.Context, req *enginetypes.SearchRequest) ([]map[string]interface{}, error) {
+ de := engine.Get()
+ if de == nil {
+ return nil, nil
+ }
+ res, err := de.Search(ctx, req)
+ if err != nil || res == nil {
+ return nil, err
+ }
+ return res.Chunks, nil
+}
+
+// compiledPrefetch is the ONE compiled-evidence recall a turn performs before
+// its loop: the claims of the chunks a plain search returns for the question.
+type compiledPrefetch struct {
+ // chunks are the anchor chunks the search returned.
+ chunks []string
+ // claims are their compiled statements, ranked.
+ claims []claimHit
+ // evidence is the rendered claim block, carrying the [ID:n] handles its
+ // source chunks were stamped with. It is rendered only when claims exist,
+ // because rendering is what publishes handles.
+ evidence string
+}
+
+// claimKey is the identity of a claim across result sets: its statement text.
+// Two rows stating the same thing are the same evidence however they were
+// anchored, which is what lets a second sighting be dropped instead of re-billed.
+func claimKey(c claimHit) string {
+ return strings.ToLower(strings.TrimSpace(c.name))
+}
+
+// prefetchCompiledEvidence searches once and returns the compiled artifacts of
+// what the search found. An empty result means the corpus has no compiled
+// claims, or the search found none of them — both leave the ordinary loop as
+// the only path.
+func prefetchCompiledEvidence(ctx context.Context, tenantID string, datasetIDs []string, messages []*schema.Message) compiledPrefetch {
+ question := strings.TrimSpace(lastUserQuestion(messages))
+ if question == "" || len(datasetIDs) == 0 {
+ return compiledPrefetch{}
+ }
+ run := compiledRunFrom(ctx)
+ if run == nil {
+ run = &compiledRun{tenantID: tenantID, datasetIDs: datasetIDs, shown: map[string]struct{}{}}
+ ctx = context.WithValue(ctx, compiledRunKey{}, run)
+ }
+ // A compiled dataset does not imply claims: trees, timelines and mindmaps
+ // all carry compile_kwd but no evidence rows. Probing first keeps the
+ // search and the verdict call off a corpus that can only come back empty.
+ if !run.claimsPresent(ctx) {
+ common.DebugCtx(ctx, "agentic_rag: compiled prefetch skipped",
+ zap.Strings("datasets", datasetIDs),
+ zap.String("reason", "no claim rows in the bound datasets"))
+ return compiledPrefetch{}
+ }
+ docScope, _ := resolveDocumentScope(ctx, nil)
+ // A non-nil EMPTY scope means the turn allows no documents: an empty
+ // docScope reads as "unrestricted" downstream, so stop before the search.
+ if docScope != nil && len(docScope) == 0 {
+ common.DebugCtx(ctx, "agentic_rag: compiled prefetch skipped",
+ zap.Strings("datasets", datasetIDs),
+ zap.String("reason", "no documents in the turn's scope"))
+ return compiledPrefetch{}
+ }
+
+ chunks := compiledAnchorSearch(ctx, tenantID, datasetIDs, docScope, question, compiledAnchorTopN)
+ chunkIDs := make([]string, 0, len(chunks))
+ for _, c := range chunks {
+ if c.ID != "" {
+ chunkIDs = append(chunkIDs, c.ID)
+ }
+ }
+ if len(chunkIDs) == 0 {
+ common.InfoCtx(ctx, "agentic_rag: compiled prefetch found no anchor chunks",
+ zap.String("query", question), zap.Strings("datasets", datasetIDs))
+ return compiledPrefetch{}
+ }
+ // The page is the retrieved chunks' own claims: no document-scoped leg (a
+ // chunk the search did not return is not evidence this turn may offer), and
+ // no cap of any kind - a chunk is on the page whole, with every claim it
+ // carries, or it is not on the page at all.
+ if !claimPageEnabled() {
+ // Control arm: the same retrieval served as raw chunk text instead of its
+ // claims. Only the artifact differs, so a comparison against this page
+ // measures the claim page itself rather than a different search.
+ bareAll := chunksWithoutClaims(chunks, nil)
+ pf := compiledPrefetch{chunks: chunkIDs, evidence: chunksAsEvidence(ctx, bareAll)}
+ common.InfoCtx(ctx, "agentic_rag: claim page disabled, serving chunks as text",
+ zap.String("query", question),
+ zap.Int("chunks", len(chunkIDs)),
+ zap.Int("chunks_as_text", len(bareAll)),
+ zap.Int("evidence_bytes", len(pf.evidence)))
+ return pf
+ }
+ claims, hasClaims := compiledClaimsForChunks(ctx, tenantID, datasetIDs, chunkIDs, question)
+ pf := compiledPrefetch{chunks: chunkIDs, claims: claims}
+ if len(claims) == 0 {
+ common.InfoCtx(ctx, "agentic_rag: compiled prefetch found no claims for the searched chunks",
+ zap.String("query", question),
+ zap.Strings("datasets", datasetIDs),
+ zap.Int("chunks", len(chunkIDs)))
+ return pf
+ }
+ // A retrieved chunk that carries no claims is served as its raw text in the
+ // same page: the verdict is asked whether this evidence answers the question,
+ // and a chunk that silently vanished from the page cannot be part of that
+ // answer. "Claims where they exist, the chunk itself where they do not."
+ bare := chunksWithoutClaims(chunks, hasClaims)
+ pf.evidence = claimEvidenceBlock(ctx, claims)
+ if raw := chunksAsEvidence(ctx, bare); raw != "" {
+ if pf.evidence != "" {
+ pf.evidence += "\n"
+ }
+ pf.evidence += raw
+ }
+ common.InfoCtx(ctx, "agentic_rag: compiled prefetch ready",
+ zap.String("query", question),
+ zap.Strings("datasets", datasetIDs),
+ zap.Int("chunks", len(chunkIDs)),
+ zap.Int("anchor_docs", len(anchorDocsOf(chunks))),
+ zap.Int("chunks_with_claims", len(hasClaims)),
+ zap.Int("chunks_as_text", len(bare)),
+ zap.Int("claims", len(claims)),
+ zap.Strings("docs", claimDocsInOrder(claims)),
+ zap.Int("evidence_bytes", len(pf.evidence)))
+ return pf
+}
+
+// chunksWithoutClaims returns the retrieved chunks the store has no claims for,
+// in retrieval order. It takes the HAS-claims set rather than the surviving page,
+// because a chunk whose every statement was deduped away still carries claims and
+// must not be served as raw text on top of them.
+func chunksWithoutClaims(chunks []runtime.RetrievalChunk, covered map[string]struct{}) []runtime.RetrievalChunk {
+ out := make([]runtime.RetrievalChunk, 0, len(chunks))
+ for _, c := range chunks {
+ if c.ID == "" || strings.TrimSpace(c.Content) == "" {
+ continue
+ }
+ if _, ok := covered[c.ID]; ok {
+ continue
+ }
+ out = append(out, c)
+ }
+ return out
+}
+
+// chunksAsEvidence renders claim-less chunks as their own text, in the same
+// <chunks> shape the deep-read tool uses, so the page reads uniformly. It skips
+// the deep-read sufficiency filter: these chunks ARE part of the page the
+// verdict is about to judge, so nothing may shorten them.
+func chunksAsEvidence(ctx context.Context, chunks []runtime.RetrievalChunk) string {
+ if len(chunks) == 0 {
+ return ""
+ }
+ return renderChunksXML(ctx, "", chunks, "", "")
+}
+
+// anchorDocsOf returns the distinct documents of a retrieved chunk page, in
+// retrieval order. It is the document scope the retrieval accepted, logged so a
+// page that silently collapsed onto fewer documents is visible.
+func anchorDocsOf(chunks []runtime.RetrievalChunk) []string {
+ seen := make(map[string]struct{}, len(chunks))
+ out := make([]string, 0, len(chunks))
+ for _, c := range chunks {
+ id := strings.TrimSpace(c.DocumentID)
+ if id == "" {
+ continue
+ }
+ if _, dup := seen[id]; dup {
+ continue
+ }
+ seen[id] = struct{}{}
+ out = append(out, id)
+ }
+ return out
+}
+
+// coveredAnchorChunks returns the distinct anchor chunks the surviving claims are
+// attributed to. It is the numerator of the strategy's coverage: claims that
+// matched nothing were already dropped, so this is exactly "how many of the
+// retrieved chunks had compiled artifacts".
+func coveredAnchorChunks(claims []claimHit) map[string]struct{} {
+ covered := make(map[string]struct{}, len(claims))
+ for _, c := range claims {
+ if c.chunkID != "" {
+ covered[c.chunkID] = struct{}{}
+ }
+ }
+ return covered
+}
+
+// claimDocsInOrder returns the distinct source documents of a claim set, in
+// first-appearance order, for logging and evidence grouping.
+func claimDocsInOrder(claims []claimHit) []string {
+ seen := map[string]struct{}{}
+ out := make([]string, 0, len(claims))
+ for _, c := range claims {
+ if c.docID == "" {
+ continue
+ }
+ if _, dup := seen[c.docID]; dup {
+ continue
+ }
+ seen[c.docID] = struct{}{}
+ out = append(out, c.docID)
+ }
+ return out
+}
+
+// claimEvidenceBlock renders the recalled claims as answer material, one <doc>
+// element per source document so a multi-document question keeps its provenance
+// and the answer can name which document each fact came from.
+//
+// Claims are grouped by document in first-appearance order rather than emitted in
+// page order: a page mixes claims of the anchored chunks with claims of the same
+// documents' other chunks, so emitting them in page order would open and close the
+// same <doc> element several times.
+func claimEvidenceBlock(ctx context.Context, claims []claimHit) string {
+ order := make([]string, 0, 4)
+ byDoc := make(map[string][]claimHit, 4)
+ for _, c := range claims {
+ if _, ok := byDoc[c.docID]; !ok {
+ order = append(order, c.docID)
+ }
+ byDoc[c.docID] = append(byDoc[c.docID], c)
+ }
+ var b strings.Builder
+ for _, doc := range order {
+ if doc != "" {
+ fmt.Fprintf(&b, "<doc doc_id=\"%s\">\n", xmlEscape(doc))
+ }
+ for _, c := range byDoc[doc] {
+ b.WriteString(claimOutlineLine(ctx, c))
+ b.WriteString("\n")
+ }
+ if doc != "" {
+ b.WriteString("</doc>\n")
+ }
+ }
+ return strings.TrimRight(b.String(), "\n")
+}
+
+// compiledEvidenceNotice renders the claims compiled from ONE locate result
+// set, as the leading block of that tool result.
+//
+// It returns "" for a corpus without claims, for a result set that carries no
+// corpus chunk (web hits), and for a result set whose claims were ALL shown
+// earlier — so a non-compiled corpus pays one cached existence probe per turn and
+// nothing else, and a repeat result pays one pointer line naming the handles it
+// already has.
+func compiledEvidenceNotice(ctx context.Context, tool, query string, hits []snippetHit) string {
+ run := compiledRunFrom(ctx)
+ if run == nil || len(hits) == 0 {
+ return ""
+ }
+ chunkIDs := make([]string, 0, len(hits))
+ for _, h := range hits {
+ if h.web || h.chunk.ID == "" {
+ continue
+ }
+ chunkIDs = append(chunkIDs, h.chunk.ID)
+ }
+ if len(chunkIDs) == 0 {
+ return ""
+ }
+ if !run.claimsPresent(ctx) {
+ return ""
+ }
+ // Rank against the query THIS call just issued, not the turn's question: in a
+ // multi-hop run the second search asks about the link, and ranking its result
+ // set by the final question surfaces exactly the claims the previous notice
+ // already showed - which takeUnseen then drops, leaving the new hits bare.
+ need := strings.TrimSpace(query)
+ if need == "" {
+ need = strings.TrimSpace(intentFrom(ctx))
+ }
+ if need == "" {
+ need = queryFrom(ctx)
+ }
+ // Every hit's every claim, deduped against what this turn already showed. The
+ // result set's size is the retrieval's to decide: a cap here would serve some
+ // chunks as a fragment of themselves, and the model has no way to tell a
+ // chunk's full statement set from the part it was shown.
+ page, _ := compiledClaimsForChunks(ctx, run.tenantID, run.datasetIDs, chunkIDs, need)
+ claims := run.takeUnseen(page)
+ // Hits whose statements an EARLIER result already put in this turn: their text
+ // is in the transcript under a ref handle, so the model needs the handle, not
+ // the chunk. Without this line the result looks claim-less and the only way to
+ // find out what those chunks say is a deep read of text the model already has.
+ shown := shownClaimChunks(ctx, run, page, coveredAnchorChunks(claims))
+ if len(claims) == 0 && len(shown) == 0 {
+ return ""
+ }
+ lines := make([]string, 0, len(claims))
+ for _, c := range claims {
+ lines = append(lines, xmlEscape(claimCompactLine(ctx, c)))
+ }
+ common.InfoCtx(ctx, "agentic_rag: compiled evidence attached to tool result",
+ zap.String("tool", tool),
+ zap.Int("hits", len(hits)),
+ zap.Int("covered_chunks", len(coveredAnchorChunks(claims))),
+ zap.Int("shown_chunks", len(shown)),
+ zap.Int("claims", len(claims)))
+ var b strings.Builder
+ fmt.Fprintf(&b, "<compiled_evidence count=\"%d\">\n", len(claims))
+ if len(lines) > 0 {
+ fmt.Fprintf(&b, "<note>These statements are the compiled artifacts of %d of the %d chunks below: each one is an "+
+ "atomic fact, and ref=n is the handle to cite that source chunk by. "+
+ "If they already state what the question needs, answer from them now and cite their ref handles - do NOT "+
+ "call list_chunks for those chunks. Read a raw chunk only when the fact you need is not stated here, "+
+ "or when that chunk carries no statement above.</note>\n", len(coveredAnchorChunks(claims)), len(chunkIDs))
+ b.WriteString(strings.Join(lines, "\n"))
+ b.WriteString("\n")
+ }
+ if len(shown) > 0 {
+ // Not repeated text - only where the text already is. This is the whole
+ // point of tracking shown claims per chunk instead of only per statement.
+ fmt.Fprintf(&b, "<already_shown>Compiled statements for %d more chunk(s) of this result set were shown "+
+ "earlier in this conversation; cite them by these handles instead of reading the chunks again: %s.</already_shown>\n",
+ len(shown), strings.Join(shown, ", "))
+ }
+ b.WriteString("</compiled_evidence>")
+ return b.String()
+}
+
+// shownClaimChunks names the hits whose compiled statements this turn already
+// showed, as "chunk_id=[ID:n]" pairs, skipping the chunks the fresh block already
+// covers. It is capped so a large result set cannot turn the pointer line into
+// the very cost it exists to avoid.
+func shownClaimChunks(ctx context.Context, run *compiledRun, page []claimHit, covered map[string]struct{}) []string {
+ if run == nil {
+ return nil
+ }
+ reg := evidenceRegistryFrom(ctx)
+ if reg == nil {
+ return nil
+ }
+ seen := make(map[string]struct{}, len(page))
+ out := make([]string, 0, compiledNoticeShownChunks)
+ for _, c := range page {
+ if c.chunkID == "" || len(out) >= compiledNoticeShownChunks {
+ continue
+ }
+ if _, dup := covered[c.chunkID]; dup {
+ continue
+ }
+ if _, dup := seen[c.chunkID]; dup {
+ continue
+ }
+ if !run.claimShown(c) {
+ continue
+ }
+ seen[c.chunkID] = struct{}{}
+ out = append(out, fmt.Sprintf("%s=[ID:%d]", c.chunkID, reg.Stamp(c.chunkID)))
+ }
+ return out
+}
+
+// compiledEvidenceGate is the last station before raw text: a deep read that is
+// about to open these chunks is answered with their compiled artifacts instead,
+// as long as any of those statements is new to this turn.
+//
+// It returns "" - meaning "go ahead and serve the raw text" - when the corpus
+// has no claims, when these chunks carry none, or when everything they carry was
+// already offered earlier in the turn. That last case is the important one: a
+// caller that still asks to read after the statements were put in front of it
+// has judged them insufficient, so withholding the passage a second time would
+// only stall the loop.
+//
+// The note names the way out (raw=true): a gate that does not offer one turns
+// "the claims were not enough" into a dead end, and every line carries its ref
+// handle so an answer given from this block is still citable.
+//
+// It returns the block AND the chunks that block represents, so the caller can
+// serve "claims where they exist, the chunk itself where they do not" in one
+// answer instead of making the model ask twice.
+func compiledEvidenceGate(ctx context.Context, chunkIDs []string) (string, []string) {
+ if len(chunkIDs) == 0 {
+ return "", nil
+ }
+ run := compiledRunFrom(ctx)
+ if run == nil || !run.claimsPresent(ctx) {
+ return "", nil
+ }
+ // Rank against what THIS call needs (its stated intent), not only against the
+ // turn's question: a deep read in the middle of a multi-hop run exists to
+ // fetch a link that is often irrelevant to the final question.
+ need := strings.TrimSpace(intentFrom(ctx))
+ if need == "" {
+ need = queryFrom(ctx)
+ }
+ page, hasClaims := compiledClaimsForChunks(ctx, run.tenantID, run.datasetIDs, chunkIDs, need)
+ claims := run.takeUnseen(page)
+ if len(claims) == 0 {
+ return "", nil
+ }
+ // hasClaims, not the survival set: a chunk whose statement another chunk
+ // already stated is deduped off the page, and serving it as raw text would
+ // repeat what the block above says.
+ coveredSet := hasClaims
+ covered := make([]string, 0, len(coveredSet))
+ for _, id := range chunkIDs {
+ if _, ok := coveredSet[id]; ok {
+ covered = append(covered, id)
+ }
+ }
+ common.InfoCtx(ctx, "agentic_rag: compiled evidence gated a raw read",
+ zap.Strings("chunks", chunkIDs),
+ zap.Int("claims", len(claims)),
+ zap.Int("covered_chunks", len(covered)))
+
+ lines := make([]string, 0, len(claims))
+ for _, c := range claims {
+ lines = append(lines, xmlEscape(claimCompactLine(ctx, c)))
+ }
+ var b strings.Builder
+ fmt.Fprintf(&b, "<compiled_evidence count=\"%d\">\n", len(claims))
+ b.WriteString("<note>These statements are the compiled artifacts of the chunks this call asked to read: each one is an ")
+ b.WriteString("atomic fact, and ref=n is the handle for citing that chunk. ")
+ b.WriteString("No raw text accompanies them. If these statements already state the fact this call needs, answer from them ")
+ b.WriteString("now and cite their ref handles. If the passage itself is genuinely still needed, call list_chunks again ")
+ b.WriteString("with raw=true and the original text is returned.</note>\n")
+ b.WriteString(strings.Join(lines, "\n"))
+ b.WriteString("\n</compiled_evidence>")
+ return b.String(), covered
+}
+
+// Claim row shape, read by the chunk-anchored claim lookup.
+const (
+ // navClaimRowType is the entity_type_kwd every compiler gives its evidence
+ // rows. They deliberately carry no knowledge_graph_kwd and no type_kwd, so
+ // they never show up as artifacts-tree nodes — this filter is the only way
+ // to find them.
+ navClaimRowType = "claim"
+ // navClaimDocScope pins the lookup to doc-level rows: the KB-wide merged
+ // rows written by the Build button carry a doc_id too, and without this
+ // filter they would answer for a single document.
+ navClaimDocScope = "doc"
+ // navClaimEvidenceChars caps the rendered verbatim quote of a claim line.
+ // Generous on purpose: a thin quote makes the answer stage judge the context
+ // insufficient, and one extra re-search turn costs a full prompt — far more
+ // than the extra characters.
+ navClaimEvidenceChars = 1200
+)
+
+// claimHit is one recalled claim row: an atomic proposition plus its verbatim
+// evidence. chunkID is the FIRST source chunk id — the pointer the model feeds
+// to list_chunks when it needs the surrounding passage. docID names the document
+// the claim was compiled from, which is what makes document diversity checkable.
+type claimHit struct {
+ docID string
+ // chunkID is the chunk this claim is ATTRIBUTED to: the source chunk the
+ // caller matched it by, which is not necessarily sourceChunkIDs[0] — a claim
+ // compiled from a multi-chunk passage names several. Rendering and citation
+ // handles use this one.
+ chunkID string
+ // sourceChunkIDs is every chunk the claim was compiled from, as stored. A
+ // chunk-anchored lookup must match against ALL of them: matching only the
+ // first would drop a claim whose first source chunk is not in the retrieved
+ // page while its second is.
+ sourceChunkIDs []string
+ name string
+ description string
+ quote string
+ score float64
+}
+
+// parseClaimHit turns one claim row into a hit. A row that is not a usable
+// claim — bad payload, unnamed, or carrying no chunk pointer — is dropped: a
+// claim the model cannot open is not an answer anchor.
+func parseClaimHit(row map[string]interface{}) (claimHit, bool) {
+ payload, ok := decodeJSONObject(contentWithWeightFromRaw(row))
+ if !ok {
+ return claimHit{}, false
+ }
+ name := strings.TrimSpace(stringFromAny(payload["name"]))
+ if name == "" {
+ return claimHit{}, false
+ }
+ ids := navStringList(row["source_chunk_ids"])
+ if len(ids) == 0 {
+ ids = navStringList(payload["source_chunk_ids"])
+ }
+ if len(ids) == 0 {
+ return claimHit{}, false
+ }
+ docID := strings.TrimSpace(fmt.Sprint(row["doc_id"]))
+ if docID == "<nil>" {
+ docID = ""
+ }
+ return claimHit{
+ docID: docID,
+ chunkID: ids[0],
+ sourceChunkIDs: ids,
+ name: name,
+ description: strings.TrimSpace(stringFromAny(payload["description"])),
+ quote: firstEvidenceQuote(payload["evidence"]),
+ score: floatFromMap(row, "_score"),
+ }, true
+}
+
+// claimTokens returns the set of content tokens of a text, the vocabulary the
+// claim coverage score is measured against. It uses the corpus tokenizer when
+// the pool is up (same analyzer the claim text was indexed with) and falls back
+// to a rune-level splitter, so a deployment without the analyzer still gets a
+// score instead of none. Single-rune tokens are dropped: they are stopwords in
+// alphabetic languages.
+func claimTokens(text string) map[string]struct{} {
+ tokens := map[string]struct{}{}
+ if tok, err := tokenizer.Tokenize(text); err == nil {
+ for _, t := range strings.Fields(strings.ToLower(tok)) {
+ if len([]rune(t)) >= 2 {
+ tokens[t] = struct{}{}
+ }
+ }
+ }
+ if len(tokens) > 0 {
+ return tokens
+ }
+ for _, t := range strings.FieldsFunc(strings.ToLower(text), func(r rune) bool {
+ return !unicode.IsLetter(r) && !unicode.IsDigit(r)
+ }) {
+ if len([]rune(t)) >= 2 {
+ tokens[t] = struct{}{}
+ }
+ }
+ return tokens
+}
+
+// claimCoverage is the share of the question's content tokens this claim states
+// or quotes. It ORDERS a chunk's claims by how close they are to the question
+// being asked; it is not a membership filter, because a chunk's claim set is
+// that chunk's representation and dropping part of it would judge an excerpt.
+func claimCoverage(question map[string]struct{}, c claimHit) float64 {
+ if len(question) == 0 {
+ return 1
+ }
+ text := c.name + " " + c.description + " " + c.quote
+ claim := claimTokens(text)
+ if len(claim) == 0 {
+ return 0
+ }
+ matched := 0
+ for t := range question {
+ if _, ok := claim[t]; ok {
+ matched++
+ }
+ }
+ return float64(matched) / float64(len(question))
+}
+
+// firstEvidenceQuote returns the first non-empty verbatim quote of a claim's
+// evidence list.
+func firstEvidenceQuote(v any) string {
+ list, _ := v.([]any)
+ for _, item := range list {
+ ev, ok := item.(map[string]any)
+ if !ok {
+ continue
+ }
+ if q := strings.TrimSpace(stringFromAny(ev["quote"])); q != "" {
+ return q
+ }
+ }
+ return ""
+}
+
+// stringFromAny reads a scalar as a trimmed string, tolerating the numeric
+// types engines decode JSON numbers into.
+func stringFromAny(v any) string {
+ switch x := v.(type) {
+ case string:
+ return x
+ case fmt.Stringer:
+ return x.String()
+ case nil:
+ return ""
+ default:
+ return fmt.Sprint(x)
+ }
+}
+
+// claimOutlineLine renders one claim hit: the statement, its verbatim evidence,
+// and the chunk pointer that opens the surrounding passage.
+//
+// The line is ANSWER MATERIAL (a claim carries its own evidence, so the model is
+// expected to cite it instead of re-reading the document), which makes the
+// passage handle mandatory: an uncited claim line ships an answer the reference
+// payload cannot resolve. The handle is appended unquoted (`ref=3`) on purpose -
+// claim lines are rendered inside an escaped <structure> text node, where a
+// `ref="3"` attribute would arrive as `ref=&quot;3&quot;`.
+func claimOutlineLine(ctx context.Context, c claimHit) string {
+ line := "- [claim] " + c.name
+ if q := strings.TrimSpace(c.quote); q != "" {
+ line += ` | Evidence: "` + snippetRunes(q, navClaimEvidenceChars) + `"`
+ }
+ if c.chunkID != "" {
+ line += " [chunks: " + c.chunkID + "]"
+ }
+ if n := evidenceRegistryFrom(ctx).Stamp(c.chunkID); n >= 0 {
+ line += " ref=" + strconv.Itoa(n)
+ }
+ return line
+}
+
+// claimCompactLine renders a claim hit as its statement plus the handle to the
+// chunk it came from, and nothing else.
+//
+// It is the line used where claims are re-read on every later call of the turn
+// (a locate result's block, the gate in front of a raw read). The quote and the
+// chunk id are omitted there because both are carried by the handle: the handle
+// resolves to the source chunk, so a quote repeated in the transcript buys
+// nothing the model can act on while costing a line's worth of tokens in every
+// subsequent call. The verdict page - the one call that decides whether the
+// claims are enough - keeps the full form.
+func claimCompactLine(ctx context.Context, c claimHit) string {
+ line := "- [claim] " + c.name
+ if n := evidenceRegistryFrom(ctx).Stamp(c.chunkID); n >= 0 {
+ line += " ref=" + strconv.Itoa(n)
+ }
+ return line
+}
diff --git a/internal/agentic_rag/compiled_evidence_test.go b/internal/agentic_rag/compiled_evidence_test.go
new file mode 100644
index 0000000000..5813fdfa78
--- /dev/null
+++ b/internal/agentic_rag/compiled_evidence_test.go
@@ -0,0 +1,818 @@
+//
+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+package agentic_rag
+
+import (
+ "context"
+ "encoding/json"
+ "errors"
+ "fmt"
+ "strings"
+ "testing"
+
+ "github.com/cloudwego/eino/schema"
+
+ "ragflow/internal/agent/runtime"
+ "ragflow/internal/common"
+ enginetypes "ragflow/internal/engine/types"
+)
+
+// installAnchorSearch replaces the pre-loop chunk search so the strategy can be
+// exercised without a retrieval backend.
+func installAnchorSearch(t *testing.T, fn func(context.Context, string, []string, []string, string, int) []runtime.RetrievalChunk) {
+ t.Helper()
+ prev := compiledAnchorSearch
+ compiledAnchorSearch = fn
+ t.Cleanup(func() { compiledAnchorSearch = prev })
+}
+
+// installClaimLookup replaces the chunk -> claim lookup.
+func installClaimLookup(t *testing.T, fn func(context.Context, string, []string, []string, []string, int) []claimHit) {
+ t.Helper()
+ prev := compiledClaimsByChunk
+ compiledClaimsByChunk = fn
+ t.Cleanup(func() { compiledClaimsByChunk = prev })
+}
+
+func installClaimProbe(t *testing.T, present bool) {
+ t.Helper()
+ prev := claimRowsPresent
+ claimRowsPresent = func(context.Context, string, []string) bool { return present }
+ t.Cleanup(func() { claimRowsPresent = prev })
+}
+
+func chunkPage(ids ...string) []runtime.RetrievalChunk {
+ out := make([]runtime.RetrievalChunk, 0, len(ids))
+ for _, id := range ids {
+ out = append(out, runtime.RetrievalChunk{ID: id, Content: "body of " + id})
+ }
+ return out
+}
+
+func questionMessages(q string) []*schema.Message {
+ return []*schema.Message{{Role: schema.User, Content: q}}
+}
+
+// TestPrefetchSearchesThenLooksUpClaims: the compiled leg is anchored on the
+// search - the lookup is asked about the chunk ids the retrieval returned, in
+// retrieval order, and the rendered block is answer material with handles.
+func TestPrefetchSearchesThenLooksUpClaims(t *testing.T) {
+ installClaimProbe(t, true)
+ var gotChunks []string
+ installAnchorSearch(t, func(_ context.Context, _ string, _ []string, _ []string, q string, _ int) []runtime.RetrievalChunk {
+ if q != "when was Acme founded" {
+ t.Errorf("anchor search query = %q", q)
+ }
+ return chunkPage("c1", "c2")
+ })
+ installClaimLookup(t, func(_ context.Context, _ string, _ []string, chunkIDs, _ []string, limit int) []claimHit {
+ gotChunks = append([]string(nil), chunkIDs...)
+ if limit < len(chunkIDs) {
+ t.Errorf("lookup limit = %d, want at least one row per chunk (%d)", limit, len(chunkIDs))
+ }
+ return []claimHit{
+ {chunkID: "c2", docID: "d2", name: "Acme employs 900 people", quote: "a workforce of 900"},
+ {chunkID: "c1", docID: "d1", name: "Acme was founded in 1994", quote: "Acme, founded in 1994"},
+ }
+ })
+ ctx := WithEvidenceRegistry(context.Background(), NewEvidenceRegistry())
+
+ pf := prefetchCompiledEvidence(ctx, "tenant-1", []string{"kb1"}, questionMessages("when was Acme founded"))
+
+ if len(gotChunks) != 2 || gotChunks[0] != "c1" || gotChunks[1] != "c2" {
+ t.Fatalf("lookup must be asked about the retrieved chunks, got %v", gotChunks)
+ }
+ if len(pf.claims) != 2 {
+ t.Fatalf("claims = %d, want 2", len(pf.claims))
+ }
+ // Anchored ranking: the best-ranked chunk's claim comes first even though the
+ // other claim was returned first by the store.
+ if pf.claims[0].chunkID != "c1" {
+ t.Errorf("claims must follow the retrieval's chunk order, got first %q", pf.claims[0].chunkID)
+ }
+ for _, want := range []string{`doc_id="d1"`, `doc_id="d2"`, "ref=0", "ref=1"} {
+ if !strings.Contains(pf.evidence, want) {
+ t.Errorf("evidence must contain %q, got:\n%s", want, pf.evidence)
+ }
+ }
+ if len(pf.chunks) != 2 {
+ t.Errorf("prefetch must report its anchors, got %v", pf.chunks)
+ }
+}
+
+// TestPrefetchServesDedupedChunksOnlyAsClaims: a chunk whose statement another
+// chunk of the same page already stated is deduped off the claim page, but it
+// still HAS claims - so its raw text must not be appended as if it carried none.
+// Otherwise the same fact is offered twice, once as a statement and once as prose.
+func TestPrefetchServesDedupedChunksOnlyAsClaims(t *testing.T) {
+ installClaimProbe(t, true)
+ installAnchorSearch(t, func(context.Context, string, []string, []string, string, int) []runtime.RetrievalChunk {
+ return chunkPage("c1", "c2")
+ })
+ installClaimLookup(t, func(context.Context, string, []string, []string, []string, int) []claimHit {
+ return []claimHit{
+ {chunkID: "c1", docID: "d1", name: "Acme was founded in 1994", quote: "Acme, founded in 1994"},
+ {chunkID: "c2", docID: "d2", name: "ACME was founded in 1994", quote: "duplicate of c1"},
+ }
+ })
+ ctx := WithEvidenceRegistry(context.Background(), NewEvidenceRegistry())
+
+ pf := prefetchCompiledEvidence(ctx, "tenant-1", []string{"kb1"}, questionMessages("when was Acme founded"))
+
+ if len(pf.claims) != 1 {
+ t.Fatalf("claims = %d, want the deduped page of 1: %+v", len(pf.claims), pf.claims)
+ }
+ if !strings.Contains(pf.evidence, "Acme was founded in 1994") {
+ t.Errorf("the surviving statement must be on the page, got:\n%s", pf.evidence)
+ }
+ for _, body := range []string{"body of c1", "body of c2"} {
+ if strings.Contains(pf.evidence, body) {
+ t.Errorf("chunk %q already has claims and must not be served as raw text:\n%s", body, pf.evidence)
+ }
+ }
+}
+
+// TestPrefetchSkippedWithoutClaimRows: a compiled but claim-less corpus (tree,
+// timeline, mindmap) must not pay for a search or a verdict call.
+func TestPrefetchSkippedWithoutClaimRows(t *testing.T) {
+ installClaimProbe(t, false)
+ installAnchorSearch(t, func(context.Context, string, []string, []string, string, int) []runtime.RetrievalChunk {
+ t.Error("a corpus without claim rows must not be searched")
+ return nil
+ })
+ pf := prefetchCompiledEvidence(context.Background(), "tenant-1", []string{"kb1"}, questionMessages("q"))
+ if len(pf.claims) != 0 || pf.evidence != "" {
+ t.Errorf("claim-less corpus must yield an empty prefetch, got %+v", pf)
+ }
+}
+
+// TestPrefetchEmptyDocumentScopeSkips: a non-nil EMPTY turn scope allows no
+// documents; the retrieval would read it as "unrestricted", so the prefetch must
+// stop before searching.
+func TestPrefetchEmptyDocumentScopeSkips(t *testing.T) {
+ installClaimProbe(t, true)
+ installAnchorSearch(t, func(context.Context, string, []string, []string, string, int) []runtime.RetrievalChunk {
+ t.Error("an empty document scope must stop before the search")
+ return nil
+ })
+ ctx := withDocumentScope(context.Background(), []string{})
+ pf := prefetchCompiledEvidence(ctx, "tenant-1", []string{"kb1"}, questionMessages("q"))
+ if len(pf.claims) != 0 {
+ t.Errorf("empty scope must yield an empty prefetch, got %+v", pf)
+ }
+}
+
+// TestPrefetchWithoutAnchorChunks: a search that finds nothing leaves the loop as
+// the only path, and no verdict call is bought.
+func TestPrefetchWithoutAnchorChunks(t *testing.T) {
+ installClaimProbe(t, true)
+ installAnchorSearch(t, func(context.Context, string, []string, []string, string, int) []runtime.RetrievalChunk {
+ return nil
+ })
+ installClaimLookup(t, func(context.Context, string, []string, []string, []string, int) []claimHit {
+ t.Error("no anchor chunks means no claim lookup")
+ return nil
+ })
+ pf := prefetchCompiledEvidence(context.Background(), "tenant-1", []string{"kb1"}, questionMessages("q"))
+ if len(pf.claims) != 0 || len(pf.chunks) != 0 {
+ t.Errorf("no anchors must yield an empty prefetch, got %+v", pf)
+ }
+}
+
+// TestCompiledClaimsDedupedAndGroupedByAnchor: the page is deduped by
+// statement, every claim of every chunk is kept, and the best-ranked anchor's
+// claims all lead (closest to the question first) before the next anchor's.
+func TestCompiledClaimsDedupedAndGroupedByAnchor(t *testing.T) {
+ installClaimLookup(t, func(context.Context, string, []string, []string, []string, int) []claimHit {
+ return []claimHit{
+ {chunkID: "c2", name: "Acme employs 900 people", quote: "a workforce of 900"},
+ {chunkID: "c1", name: "Acme was founded in 1994", quote: "Acme, founded in 1994"},
+ {chunkID: "c1", name: "acme WAS founded in 1994", quote: "duplicate"},
+ {chunkID: "c1", name: "Acme is based in Zurich", quote: "the Zurich-based firm"},
+ }
+ })
+ claims, _ := compiledClaimsForChunks(context.Background(), "tenant-1", []string{"kb1"}, []string{"c1", "c2"}, "where was Acme founded and when")
+ if len(claims) != 3 {
+ t.Fatalf("claims = %d, want the 3 distinct anchored claims: %+v", len(claims), claims)
+ }
+ if claims[0].name != "Acme was founded in 1994" {
+ t.Errorf("the best-ranked anchor must lead with its best-covering claim, got %q", claims[0].name)
+ }
+ if claims[1].chunkID != "c1" {
+ t.Errorf("the best anchor's remaining claims must stay with it, got %q", claims[1].chunkID)
+ }
+ if claims[2].chunkID != "c2" {
+ t.Errorf("the next anchor's claims must follow the best anchor's, got %q", claims[2].chunkID)
+ }
+}
+
+// TestCompiledClaimsKeepDifferentlyWordedClaim: the anchor chunk is the
+// relevance proof, so a claim that repeats none of the question's terms still
+// shows up - a floor on question-token coverage would empty the page and report
+// "the corpus has no compiled evidence" for a chunk that has it.
+func TestCompiledClaimsKeepDifferentlyWordedClaim(t *testing.T) {
+ installClaimLookup(t, func(context.Context, string, []string, []string, []string, int) []claimHit {
+ return []claimHit{{chunkID: "c1", name: "Something unrelated entirely", quote: "x"}}
+ })
+ claims, _ := compiledClaimsForChunks(context.Background(), "tenant-1", []string{"kb1"}, []string{"c1"}, "when was Acme founded")
+ if len(claims) != 1 {
+ t.Fatalf("the anchored claim must survive regardless of wording, got %+v", claims)
+ }
+}
+
+// TestCompiledClaimsReachSecondHopAnchor: the fact that answers a second hop is
+// often compiled from a mid-ranked chunk, names the second-hop entity rather
+// than the question's terms, and is only the SECOND best-covering claim of that
+// chunk. Nothing is capped, so a mid-ranked anchor's second claim is on the page
+// even when the top three anchors carry eight claims each.
+func TestCompiledClaimsReachSecondHopAnchor(t *testing.T) {
+ // Page assembly only: the judge bound has its own test. A bound this large
+ // keeps the page whole without disabling the env path itself.
+ t.Setenv(common.EnvDecisionClaimJudgeCap, "10000")
+ anchors := []string{"c0", "c1", "c2", "c3", "c4", "c5"}
+ installClaimLookup(t, func(context.Context, string, []string, []string, []string, int) []claimHit {
+ rows := make([]claimHit, 0, 26)
+ // Eight claims on each of the three top anchors: more than any old
+ // per-result budget, exactly as the store returns them.
+ for _, anchor := range []string{"c0", "c1", "c2"} {
+ for i := 0; i < 8; i++ {
+ rows = append(rows, claimHit{
+ chunkID: anchor,
+ name: fmt.Sprintf("The World Series between the Atlanta Braves and Houston Astros reached extra innings in game %d of the %s account", i+1, anchor),
+ quote: "the Braves beat the Astros in the World Series",
+ })
+ }
+ }
+ rows = append(rows,
+ claimHit{
+ chunkID: "c5",
+ name: "Jackie Robinson's last MLB appearance was on October 10, 1956, for the Brooklyn Dodgers.",
+ quote: "Last MLB appearance October 10, 1956, for the Brooklyn Dodgers",
+ },
+ claimHit{
+ chunkID: "c5",
+ name: "Jackie Robinson made his MLB debut on April 15, 1947, for the Brooklyn Dodgers.",
+ quote: "MLB: April 15, 1947, for the Brooklyn Dodgers",
+ })
+ return rows
+ })
+ claims, _ := compiledClaimsForChunks(context.Background(), "tenant-1", []string{"kb1"}, anchors,
+ "As of August 2024, the Atlanta Braves beat the Houston Astros the last time they won the World Series. How many years before this did Jackie Robinson join the Brooklyn Dodgers?")
+ if len(claims) != 26 {
+ t.Fatalf("claims = %d, want every claim of every anchor (26)", len(claims))
+ }
+ found := false
+ for _, c := range claims {
+ if c.chunkID == "c5" && strings.Contains(c.name, "April 15, 1947") {
+ found = true
+ break
+ }
+ }
+ if !found {
+ t.Fatalf("the second-hop anchor #5 must get a slot, got %d claims from %v", len(claims), claimAnchorsOf(claims))
+ }
+}
+
+// TestCompiledEvidenceGateWithholdsRawTextOnce: the first read attempt for a
+// chunk's anchors is answered with its compiled statements (and the way out,
+// raw=true); the same statements are not offered twice, because a caller that
+// asks again has judged them insufficient and must get the passage.
+func TestCompiledEvidenceGateWithholdsRawTextOnce(t *testing.T) {
+ installClaimProbe(t, true)
+ installClaimLookup(t, func(context.Context, string, []string, []string, []string, int) []claimHit {
+ return []claimHit{{chunkID: "c1", docID: "d1", name: "Acme was founded in 1994", quote: "Acme, founded in 1994"}}
+ })
+ ctx := WithEvidenceRegistry(context.Background(), NewEvidenceRegistry())
+ ctx = WithQuery(ctx, "when was Acme founded")
+ ctx = withCompiledRun(ctx, "tenant-1", []string{"kb1"})
+
+ gated, covered := compiledEvidenceGate(ctx, []string{"c1"})
+ if gated == "" {
+ t.Fatal("first read attempt must be answered with compiled evidence")
+ }
+ if len(covered) != 1 || covered[0] != "c1" {
+ t.Errorf("the gate must report the chunks it represented, got %v", covered)
+ }
+ for _, want := range []string{"<compiled_evidence", "Acme was founded in 1994", "raw=true", "ref=0"} {
+ if !strings.Contains(gated, want) {
+ t.Errorf("gate block missing %q:\n%s", want, gated)
+ }
+ }
+ if again, _ := compiledEvidenceGate(ctx, []string{"c1"}); again != "" {
+ t.Fatalf("the same statements must not be offered twice, got:\n%s", again)
+ }
+}
+
+// TestCompiledEvidenceGateEmptyWithoutClaimRows: a corpus without claims pays
+// nothing extra - the read proceeds immediately.
+func TestCompiledEvidenceGateEmptyWithoutClaimRows(t *testing.T) {
+ installClaimProbe(t, false)
+ ctx := withCompiledRun(context.Background(), "tenant-1", []string{"kb1"})
+ if gated, covered := compiledEvidenceGate(ctx, []string{"c1"}); gated != "" || len(covered) != 0 {
+ t.Fatalf("a claim-less corpus must not gate anything, got:\n%s", gated)
+ }
+}
+
+// TestListChunksServesCompiledEvidenceBeforeText: the deep read - the most
+// expensive call in the loop - returns the anchors' compiled statements on the
+// first attempt and the original prose only when the caller asks for raw.
+func TestListChunksServesCompiledEvidenceBeforeText(t *testing.T) {
+ fe := &grepFakeEngine{
+ regexpChunks: []map[string]interface{}{
+ {"id": "c1", "content_with_weight": "prose one", "doc_id": "d1", "docnm_kwd": "doc1", "kb_id": "kb1", "chunk_order_int": float64(0)},
+ },
+ }
+ runtime.SetGrepService(NewGrepAdapter(fe))
+ defer runtime.SetGrepService(nil)
+ stubOwner(t, "kb1")
+
+ installClaimProbe(t, true)
+ installClaimLookup(t, func(context.Context, string, []string, []string, []string, int) []claimHit {
+ return []claimHit{{chunkID: "c1", docID: "d1", name: "Acme was founded in 1994", quote: "Acme, founded in 1994"}}
+ })
+ ctx := WithEvidenceRegistry(context.Background(), NewEvidenceRegistry())
+ ctx = WithQuery(ctx, "when was Acme founded")
+ ctx = withCompiledRun(ctx, "t", []string{"kb1"})
+
+ tool := NewListChunksTool("t", []string{"kb1"})
+ args := `{"doc_id":"d1","anchor_chunk_ids":["c1"],"intent":"founding year of Acme"}`
+
+ gated, err := tool.InvokableRun(ctx, args)
+ if err != nil {
+ t.Fatalf("InvokableRun (gated): %v", err)
+ }
+ if !strings.Contains(gated, "<compiled_evidence") || strings.Contains(gated, "prose one") {
+ t.Fatalf("first call must return statements instead of the passage, got:\n%s", gated)
+ }
+
+ raw, err := tool.InvokableRun(ctx, `{"doc_id":"d1","anchor_chunk_ids":["c1"],"intent":"founding year of Acme","raw":true}`)
+ if err != nil {
+ t.Fatalf("InvokableRun (raw): %v", err)
+ }
+ if !strings.Contains(raw, "prose one") {
+ t.Fatalf("raw=true must return the original text, got:\n%s", raw)
+ }
+}
+
+// claimAnchorsOf lists the anchors a page was spent on, for failure messages.
+func claimAnchorsOf(claims []claimHit) []string {
+ out := make([]string, 0, len(claims))
+ for _, c := range claims {
+ out = append(out, c.chunkID)
+ }
+ return out
+}
+
+// claimRow builds the raw row an engine read returns for a claim: the payload is
+// JSON inside content_with_weight, the source chunk ids are a keyword array.
+func claimRow(name, docID, quote string, chunkIDs ...string) map[string]interface{} {
+ payload := map[string]interface{}{
+ "name": name,
+ "source_chunk_ids": chunkIDs,
+ "evidence": []interface{}{map[string]interface{}{"quote": quote}},
+ }
+ encoded, _ := json.Marshal(payload)
+ ids := make([]interface{}, len(chunkIDs))
+ for i, id := range chunkIDs {
+ ids[i] = id
+ }
+ return map[string]interface{}{
+ "content_with_weight": string(encoded),
+ "source_chunk_ids": ids,
+ "doc_id": docID,
+ }
+}
+
+// TestParseClaimHitKeepsEverySourceChunk: a claim compiled from a multi-chunk
+// passage names all of them, and the anchored lookup has to see all of them.
+func TestParseClaimHitKeepsEverySourceChunk(t *testing.T) {
+ hit, ok := parseClaimHit(claimRow("Acme was founded in 1994", "d1", "Acme, founded in 1994", "c9", "c2"))
+ if !ok {
+ t.Fatal("claim row must parse")
+ }
+ if len(hit.sourceChunkIDs) != 2 || hit.sourceChunkIDs[0] != "c9" || hit.sourceChunkIDs[1] != "c2" {
+ t.Fatalf("sourceChunkIDs = %v, want [c9 c2]", hit.sourceChunkIDs)
+ }
+ if hit.chunkID != "c9" {
+ t.Errorf("default attribution = %q, want the stored first source chunk", hit.chunkID)
+ }
+}
+
+// TestClaimsAttributedToTheMatchedAnchor: the claim is attributed to the anchor
+// it actually matched, not to whichever source chunk happened to be stored first.
+func TestClaimsAttributedToTheMatchedAnchor(t *testing.T) {
+ installClaimLookup(t, func(context.Context, string, []string, []string, []string, int) []claimHit {
+ return []claimHit{{
+ docID: "d1",
+ chunkID: "c9", // NOT in the page
+ sourceChunkIDs: []string{"c9", "c2"},
+ name: "Acme was founded in 1994",
+ quote: "Acme, founded in 1994",
+ }}
+ })
+ claims, _ := compiledClaimsForChunks(context.Background(), "tenant-1", []string{"kb1"}, []string{"c1", "c2"}, "when was Acme founded")
+ if len(claims) != 1 {
+ t.Fatalf("claims = %d, want 1: %+v", len(claims), claims)
+ }
+ if claims[0].chunkID != "c2" {
+ t.Errorf("claim must be attributed to the matched anchor c2, got %q", claims[0].chunkID)
+ }
+}
+
+// TestClaimsOffEveryAnchorAreDropped: a claim compiled from a passage the search
+// did not return is not evidence for what the search found. It must not be
+// appended to the page, however plausible its text looks.
+func TestClaimsOffEveryAnchorAreDropped(t *testing.T) {
+ installClaimLookup(t, func(context.Context, string, []string, []string, []string, int) []claimHit {
+ return []claimHit{
+ {docID: "d2", chunkID: "other", sourceChunkIDs: []string{"other"}, name: "Burj Khalifa is 828 m tall", quote: "828 metres"},
+ {docID: "d1", chunkID: "c1", sourceChunkIDs: []string{"c1"}, name: "Acme was founded in 1994", quote: "Acme, founded in 1994"},
+ }
+ })
+ claims, _ := compiledClaimsForChunks(context.Background(), "tenant-1", []string{"kb1"}, []string{"c1"}, "when was Acme founded")
+ if len(claims) != 1 {
+ t.Fatalf("only the anchored claim may survive, got %+v", claims)
+ }
+ if claims[0].chunkID != "c1" {
+ t.Errorf("surviving claim = %q, want c1", claims[0].chunkID)
+ }
+}
+
+func noticeHits(ids ...string) []snippetHit {
+ out := make([]snippetHit, 0, len(ids))
+ for _, id := range ids {
+ out = append(out, snippetHit{chunk: runtime.RetrievalChunk{ID: id, Content: "body " + id}, snippet: "snip " + id})
+ }
+ return out
+}
+
+// TestCompiledEvidenceNoticeShownOnce: a result set carries its claims the first
+// time, and a later search that returns the same claims does not pay for their
+// text again - it names the handles the turn already holds, so the model neither
+// re-reads the statements nor deep-reads the chunks to see what they said.
+func TestCompiledEvidenceNoticeShownOnce(t *testing.T) {
+ installClaimProbe(t, true)
+ installClaimLookup(t, func(_ context.Context, _ string, _ []string, chunkIDs, _ []string, _ int) []claimHit {
+ return []claimHit{{chunkID: chunkIDs[0], docID: "d1", name: "Acme was founded in 1994", quote: "Acme, founded in 1994"}}
+ })
+ ctx := withCompiledRun(WithQuery(context.Background(), "when was Acme founded"), "tenant-1", []string{"kb1"})
+ ctx = WithEvidenceRegistry(ctx, NewEvidenceRegistry())
+
+ first := compiledEvidenceNotice(ctx, searchChunksToolName, "acme", noticeHits("c1", "c2"))
+ if !strings.Contains(first, "<compiled_evidence count=\"1\">") || !strings.Contains(first, "- [claim] Acme was founded in 1994") {
+ t.Fatalf("first result must carry the compiled claim, got:\n%s", first)
+ }
+ if !strings.Contains(first, "do NOT call list_chunks") {
+ t.Errorf("the block must tell the model it can answer without a deep read, got:\n%s", first)
+ }
+ second := compiledEvidenceNotice(ctx, searchChunksToolName, "acme", noticeHits("c1", "c2"))
+ if strings.Contains(second, "- [claim] Acme was founded in 1994") {
+ t.Errorf("an already shown statement must not be repeated, got:\n%s", second)
+ }
+ if !strings.Contains(second, "<already_shown>") || !strings.Contains(second, "c1=[ID:0]") {
+ t.Errorf("a repeat result must name the handles the turn already holds, got:\n%s", second)
+ }
+}
+
+// TestCompiledEvidenceNoticeSkippedWithoutCorpusClaims: no compiled claims means
+// no block, and the corpus-level probe runs once for the whole turn.
+func TestCompiledEvidenceNoticeSkippedWithoutCorpusClaims(t *testing.T) {
+ probes := 0
+ prev := claimRowsPresent
+ claimRowsPresent = func(context.Context, string, []string) bool { probes++; return false }
+ t.Cleanup(func() { claimRowsPresent = prev })
+ installClaimLookup(t, func(context.Context, string, []string, []string, []string, int) []claimHit {
+ t.Error("a corpus without claims must not be looked up")
+ return nil
+ })
+ ctx := withCompiledRun(context.Background(), "tenant-1", []string{"kb1"})
+
+ for i := 0; i < 3; i++ {
+ if out := compiledEvidenceNotice(ctx, searchChunksToolName, "acme", noticeHits("c1")); out != "" {
+ t.Fatalf("call %d: expected no block, got:\n%s", i, out)
+ }
+ }
+ if probes != 1 {
+ t.Errorf("the corpus probe must run once per turn, ran %d times", probes)
+ }
+}
+
+// TestCompiledEvidenceNoticeWithoutRunScope: a run that published no scope (the
+// pre-loop path builds its own) must not break the locate renderers.
+func TestCompiledEvidenceNoticeWithoutRunScope(t *testing.T) {
+ if out := compiledEvidenceNotice(context.Background(), searchChunksToolName, "acme", noticeHits("c1")); out != "" {
+ t.Errorf("no run scope must yield no block, got:\n%s", out)
+ }
+ web := []snippetHit{{chunk: runtime.RetrievalChunk{ID: "web-1", URL: "https://example.test"}, web: true}}
+ if out := compiledEvidenceNotice(context.Background(), webSearchToolName, "acme", web); out != "" {
+ t.Errorf("web hits have no corpus chunk behind them, got:\n%s", out)
+ }
+}
+
+// TestLocateResultsCarryCompiledEvidenceFirst: the block is rendered AHEAD of the
+// hits it was compiled from, which is the ordering the strategy depends on.
+func TestLocateResultsCarryCompiledEvidenceFirst(t *testing.T) {
+ installClaimProbe(t, true)
+ installClaimLookup(t, func(_ context.Context, _ string, _ []string, chunkIDs, _ []string, _ int) []claimHit {
+ return []claimHit{{chunkID: chunkIDs[0], docID: "d1", name: "Acme was founded in 1994", quote: "Acme, founded in 1994"}}
+ })
+ ctx := withCompiledRun(WithQuery(context.Background(), "when was Acme founded"), "tenant-1", []string{"kb1"})
+ ctx = WithEvidenceRegistry(ctx, NewEvidenceRegistry())
+
+ out := formatLocateResultsXML(ctx, searchChunksToolName, "acme", noticeHits("c1"))
+ claimAt := strings.Index(out, "<compiled_evidence")
+ chunkAt := strings.Index(out, "<chunk ")
+ if claimAt < 0 || chunkAt < 0 {
+ t.Fatalf("result must carry both the block and the hits, got:\n%s", out)
+ }
+ if claimAt > chunkAt {
+ t.Errorf("compiled evidence must precede the raw hits, got:\n%s", out)
+ }
+}
+
+// TestCompiledEvidenceNoticeCoversTheResultSet: a locate result's block is what
+// keeps deep reads out of the turn, so its budget is spent ONE claim per hit
+// across as many hits as it can afford - not two-deep on the top three, which is
+// the shape that left 19 of every 22 hits without a statement.
+func TestCompiledEvidenceNoticeCoversTheResultSet(t *testing.T) {
+ // Page assembly only: the judge bound has its own test. A bound this large
+ // keeps the page whole without disabling the env path itself.
+ t.Setenv(common.EnvDecisionClaimJudgeCap, "10000")
+ installClaimProbe(t, true)
+ installClaimLookup(t, func(_ context.Context, _ string, _ []string, chunkIDs, _ []string, _ int) []claimHit {
+ out := make([]claimHit, 0, len(chunkIDs)*3)
+ for _, id := range chunkIDs {
+ for i := 0; i < 3; i++ {
+ out = append(out, claimHit{
+ chunkID: id,
+ docID: "doc-" + id,
+ name: fmt.Sprintf("%s states fact %d", id, i),
+ quote: fmt.Sprintf("quote from %s", id),
+ })
+ }
+ }
+ return out
+ })
+ ctx := withCompiledRun(WithQuery(context.Background(), "when was Acme founded"), "tenant-1", []string{"kb1"})
+ ctx = WithEvidenceRegistry(ctx, NewEvidenceRegistry())
+ hits := noticeHits("c1", "c2", "c3", "c4", "c5", "c6", "c7", "c8")
+
+ out := compiledEvidenceNotice(ctx, searchChunksToolName, "acme", hits)
+ if out == "" {
+ t.Fatal("the notice must be rendered for a result set with claims")
+ }
+ // Every hit's every claim is on the page: 8 chunks x 3 claims, each line
+ // carrying only the statement and its ref handle.
+ if got := strings.Count(out, "- [claim] "); got != len(hits)*3 {
+ t.Errorf("the block must carry every claim of every hit, got %d lines:\n%s", got, out)
+ }
+ // The coverage it actually achieved is stated, so the model knows which
+ // chunks still have to be read instead of re-reading the covered ones.
+ if !strings.Contains(out, fmt.Sprintf("compiled artifacts of %d of the %d chunks", len(hits), len(hits))) {
+ t.Errorf("the note must report the coverage it achieved, got:\n%s", out)
+ }
+}
+
+// TestCompiledEvidenceNoticeRanksOnThisCall: the anchors keep the retrieval's
+// own order - that ranking IS this call's decision - but WHICH claim of a chunk
+// leads is decided against this call's query, not the turn's question. Ranking on
+// the question would lead a hop-2 search's chunk with the hop-1 statement an
+// earlier notice already showed, and takeUnseen would then drop the whole page.
+func TestCompiledEvidenceNoticeRanksOnThisCall(t *testing.T) {
+ installClaimProbe(t, true)
+ installClaimLookup(t, func(_ context.Context, _ string, _ []string, _ []string, _ []string, _ int) []claimHit {
+ return []claimHit{
+ {chunkID: "c1", docID: "d1", name: "Acme was founded in 1994", quote: "founded in 1994"},
+ {chunkID: "c1", docID: "d1", name: "Acme Trucking Ltd was acquired by Zeta Holdings", quote: "acquired by Zeta Holdings"},
+ }
+ })
+ ctx := withCompiledRun(WithQuery(context.Background(), "when was Acme founded"), "tenant-1", []string{"kb1"})
+ ctx = WithEvidenceRegistry(ctx, NewEvidenceRegistry())
+
+ out := compiledEvidenceNotice(ctx, searchBm25ChunksToolName, "who acquired Acme Trucking Ltd", noticeHits("c1"))
+ zetaAt := strings.Index(out, "Zeta Holdings")
+ foundedAt := strings.Index(out, "founded in 1994")
+ if zetaAt < 0 || foundedAt < 0 {
+ t.Fatalf("both claims belong to the hit and must be offered, got:\n%s", out)
+ }
+ if zetaAt > foundedAt {
+ t.Errorf("the claim matching THIS call must lead, got:\n%s", out)
+ }
+}
+
+// TestPrefetchBoundsThePageToTheJudgeCap: the page is the retrieved chunks' own
+// claims, but one chunk's claim set can outgrow the judge bound - a chunk that
+// states twenty facts is twenty statements handed to a model asked in batches of
+// sixteen, and at a few hundred statements a turn that is dozens of round trips
+// for one retrieval round.
+//
+// So the page is bounded, and the bound is deliberate: it keeps the leading
+// statements plus one row per chunk past it, so no chunk goes voiceless, and
+// drops the tail. Carrying that tail un-judged would put every dropped statement
+// back into the prompt, which is the cost the bound exists to remove.
+func TestPrefetchBoundsThePageToTheJudgeCap(t *testing.T) {
+ t.Setenv(common.EnvDecisionClaimJudgeCap, "16")
+ installClaimProbe(t, true)
+ installAnchorSearch(t, func(context.Context, string, []string, []string, string, int) []runtime.RetrievalChunk {
+ return chunkPage("c1")
+ })
+ installClaimLookup(t, func(context.Context, string, []string, []string, []string, int) []claimHit {
+ rows := make([]claimHit, 0, 20)
+ for i := 0; i < 20; i++ {
+ rows = append(rows, claimHit{
+ chunkID: "c1", docID: "d1",
+ name: fmt.Sprintf("Leonardo completed work %d", i+1),
+ quote: fmt.Sprintf("work %d", i+1),
+ })
+ }
+ return rows
+ })
+ ctx := WithEvidenceRegistry(context.Background(), NewEvidenceRegistry())
+
+ pf := prefetchCompiledEvidence(ctx, "tenant-1", []string{"kb1"}, questionMessages("what did Leonardo work on"))
+ if len(pf.claims) != 16 {
+ t.Fatalf("claims = %d, want the page bounded to the judge cap (16)", len(pf.claims))
+ }
+ if got := strings.Count(pf.evidence, "[claim]"); got != 16 {
+ t.Errorf("evidence lines = %d, want 16", got)
+ }
+}
+
+// TestPrefetchServesClaimlessChunkAsText: an anchor that carries no compiled
+// claims is on the page as its own text. Leaving it out would ask the verdict
+// whether the evidence answers the question while withholding one of the
+// retrieved chunks.
+func TestPrefetchServesClaimlessChunkAsText(t *testing.T) {
+ installClaimProbe(t, true)
+ installAnchorSearch(t, func(context.Context, string, []string, []string, string, int) []runtime.RetrievalChunk {
+ return chunkPage("c1", "c2")
+ })
+ installClaimLookup(t, func(context.Context, string, []string, []string, []string, int) []claimHit {
+ return []claimHit{{chunkID: "c1", docID: "d1", name: "Acme was founded in 1994", quote: "founded in 1994"}}
+ })
+ ctx := WithEvidenceRegistry(context.Background(), NewEvidenceRegistry())
+
+ pf := prefetchCompiledEvidence(ctx, "tenant-1", []string{"kb1"}, questionMessages("when was Acme founded"))
+ if len(pf.claims) != 1 {
+ t.Fatalf("claims = %d, want the one claim c1 carries", len(pf.claims))
+ }
+ if !strings.Contains(pf.evidence, "Acme was founded in 1994") {
+ t.Errorf("claimed chunk must be served as its statements:\n%s", pf.evidence)
+ }
+ if !strings.Contains(pf.evidence, "body of c2") {
+ t.Errorf("claim-less chunk must be served as its text:\n%s", pf.evidence)
+ }
+}
+
+// TestClaimGapOverlap: the diagnostic must separate "the page had it" from "the
+// page never had it", because those two refusals need different work.
+func TestClaimGapOverlap(t *testing.T) {
+ claims := []claimHit{{name: "The locomotive's top speed was 96 km/h", quote: "top speed 96 km/h"}}
+ if got := claimGapOverlap(claims, "the top speed of the locomotive"); got < 0.5 {
+ t.Errorf("a gap the page states must score high, got %.2f", got)
+ }
+ if got := claimGapOverlap(claims, "the boiler pressure of the locomotive"); got >= 0.5 {
+ t.Errorf("a gap the page never states must score low, got %.2f", got)
+ }
+ if got := claimGapOverlap(claims, ""); got != 0 {
+ t.Errorf("an empty gap must score 0, got %.2f", got)
+ }
+}
+
+// installClaimTextSearch replaces the two seams of the claim-TEXT leg: the
+// question embedding and the KNN itself.
+func installClaimTextSearch(
+ t *testing.T,
+ vec func(context.Context, string, string) []float64,
+ rows func(context.Context, *enginetypes.SearchRequest) ([]map[string]interface{}, error),
+) {
+ t.Helper()
+ prevVec, prevRows := claimQueryVector, claimSearchRows
+ claimQueryVector = vec
+ claimSearchRows = rows
+ t.Cleanup(func() { claimQueryVector, claimSearchRows = prevVec, prevRows })
+}
+
+func claimTextOn(t *testing.T) {
+ t.Helper()
+ t.Setenv("RAGFLOW_CLAIM_SEARCH", "1")
+}
+
+// The leg returns the rows it can parse and drops the ones it cannot: a row the
+// model cannot open is not evidence, and a malformed row must not cost the page
+// its neighbours.
+func TestClaimTextLegParsesRowsAndSkipsUnusableOnes(t *testing.T) {
+ claimTextOn(t)
+ installClaimTextSearch(t,
+ func(context.Context, string, string) []float64 { return []float64{0.1, 0.2} },
+ func(context.Context, *enginetypes.SearchRequest) ([]map[string]interface{}, error) {
+ return []map[string]interface{}{
+ claimRow("Acme was founded in 1994", "d1", "Acme, founded in 1994", "c9"),
+ {"content_with_weight": "not a claim payload"},
+ }, nil
+ })
+ got := searchClaimsForQuestion(context.Background(), "tenant-1", []string{"kb1"}, nil, "when was Acme founded", 50)
+ if len(got) != 1 || got[0].name != "Acme was founded in 1994" || got[0].chunkID != "c9" {
+ t.Fatalf("claims = %+v, want the one parseable row", got)
+ }
+}
+
+// No query vector is a deployment without a query-side embedder. The leg must
+// return nothing WITHOUT searching: the anchored page is the whole answer there,
+// and an unembeddable question is not an error to report.
+func TestClaimTextLegDegradesWithoutQueryVector(t *testing.T) {
+ claimTextOn(t)
+ searched := false
+ installClaimTextSearch(t,
+ func(context.Context, string, string) []float64 { return nil },
+ func(context.Context, *enginetypes.SearchRequest) ([]map[string]interface{}, error) {
+ searched = true
+ return nil, nil
+ })
+ got := searchClaimsForQuestion(context.Background(), "tenant-1", []string{"kb1"}, nil, "when was Acme founded", 50)
+ if len(got) != 0 {
+ t.Fatalf("claims = %+v, want none without a vector", got)
+ }
+ if searched {
+ t.Fatal("the engine must not be searched when the question cannot be embedded")
+ }
+}
+
+// An engine error is the same outcome as no vector: the anchored page stands.
+func TestClaimTextLegDegradesOnEngineError(t *testing.T) {
+ claimTextOn(t)
+ installClaimTextSearch(t,
+ func(context.Context, string, string) []float64 { return []float64{0.1, 0.2} },
+ func(context.Context, *enginetypes.SearchRequest) ([]map[string]interface{}, error) {
+ return nil, errors.New("engine down")
+ })
+ if got := searchClaimsForQuestion(context.Background(), "tenant-1", []string{"kb1"}, nil, "q", 50); len(got) != 0 {
+ t.Fatalf("claims = %+v, want none on an engine error", got)
+ }
+}
+
+// installNoDecision keeps the claim filter out of the way of the merge tests.
+func installNoDecision(t *testing.T) {
+ t.Helper()
+ prev := decisionAvailable
+ decisionAvailable = func(context.Context) bool { return false }
+ t.Cleanup(func() { decisionAvailable = prev })
+}
+
+// The text leg is a UNION: the anchored order is authoritative and stays, a
+// claim both legs found appears once, and a claim the text leg adds is served
+// without being booked as a chunk the page is responsible for - the anchor never
+// retrieved its chunk.
+func TestClaimTextLegUnionsOntoAnchoredPage(t *testing.T) {
+ claimTextOn(t)
+ installNoDecision(t)
+ installClaimLookup(t, func(context.Context, string, []string, []string, []string, int) []claimHit {
+ return []claimHit{
+ {chunkID: "c1", name: "Acme was founded in 1994", quote: "q"},
+ {chunkID: "c1", name: "Acme is based in Zurich", quote: "q"},
+ }
+ })
+ installClaimTextSearch(t,
+ func(context.Context, string, string) []float64 { return []float64{0.1, 0.2} },
+ func(context.Context, *enginetypes.SearchRequest) ([]map[string]interface{}, error) {
+ return []map[string]interface{}{
+ claimRow("acme WAS founded in 1994", "d1", "dup", "c1"),
+ claimRow("Acme was acquired by Beta", "d2", "q", "c9"),
+ }, nil
+ })
+ claims, hasClaims := compiledClaimsForChunks(context.Background(), "tenant-1", []string{"kb1"}, []string{"c1"}, "when was Acme founded")
+ if len(claims) != 3 {
+ t.Fatalf("claims = %d, want the 2 anchored + 1 added, deduped: %+v", len(claims), claims)
+ }
+ if claims[0].name != "Acme was founded in 1994" || claims[1].name != "Acme is based in Zurich" {
+ t.Fatalf("the anchored order must lead, got %+v", claims)
+ }
+ if claims[2].name != "Acme was acquired by Beta" || claims[2].chunkID != "c9" {
+ t.Fatalf("the text leg's own claim must be appended, got %+v", claims[2])
+ }
+ for _, c := range claims {
+ if strings.EqualFold(c.name, "acme was founded in 1994") && c.chunkID != "c1" {
+ t.Fatalf("the duplicate must keep the anchored attribution, got %+v", c)
+ }
+ }
+ if _, ok := hasClaims["c9"]; ok {
+ t.Fatal("a chunk the anchor never retrieved must not be booked as covered by the page")
+ }
+ if _, ok := hasClaims["c1"]; !ok {
+ t.Fatal("the anchored chunk must still be booked")
+ }
+}
diff --git a/internal/agentic_rag/compiled_knowledge.go b/internal/agentic_rag/compiled_knowledge.go
index e3fc4b816b..1062c31337 100644
--- a/internal/agentic_rag/compiled_knowledge.go
+++ b/internal/agentic_rag/compiled_knowledge.go
@@ -28,19 +28,19 @@ import (
)
// compiledKnowledgeToolNames are the tools that only make sense on a corpus that
-// has produced knowledge-compilation products (a navigation tree, a compiled
-// structure, a knowledge graph, a per-document panorama). They are INJECTED,
-// never declared in a template's tool list: Run adds them only when the bound
-// datasets actually hold compiled products, so an uncompiled corpus never
-// offers - or pays for - them.
+// has produced knowledge-compilation products (a knowledge graph, a per-document
+// panorama). They are INJECTED, never declared in a template's tool list: Run
+// adds them only when the bound datasets actually hold compiled products, so an
+// uncompiled corpus never offers - or pays for - them.
//
-// The injected set is the whole compiled-knowledge surface on purpose: a tool
-// that is registered but neither declared by a template nor injected here is
-// unreachable at runtime, which is indistinguishable from "the model chose not
-// to use it" unless someone reads the tool list.
+// The navigation tools (navigate_tree / navigate_structure) are deliberately NOT
+// in this set any more. Their claim leg was the only way compiled evidence
+// reached the model, and it required the model to choose them - which the FRAMES
+// runs measured at zero calls per turn. Compiled evidence now travels with the
+// ordinary search results (see compiled_evidence.go), so the navigation route is
+// a second, costlier path to the same facts: it stays registered for templates
+// that declare it explicitly, but it is never injected.
var compiledKnowledgeToolNames = []string{
- navigateTreeToolName,
- navigateStructureToolName,
graphExploreToolName,
graphDocOutlineToolName,
}
diff --git a/internal/agentic_rag/compiled_knowledge_test.go b/internal/agentic_rag/compiled_knowledge_test.go
index c7affed316..2830c65798 100644
--- a/internal/agentic_rag/compiled_knowledge_test.go
+++ b/internal/agentic_rag/compiled_knowledge_test.go
@@ -34,19 +34,24 @@ func TestCompiledKnowledgeSurfaceIsReachable(t *testing.T) {
}
}
- // The per-document panorama belongs to the same corpus products (a `graph`
- // row is written by the compiler, like a navigation tree or an entity row),
- // so it must be injected with the rest rather than left to a template.
+ // The navigation tools stay REGISTERED (a template may declare them) but are
+ // deliberately not injected any more: compiled evidence reaches the model
+ // with the ordinary search results, so navigating the structure is a second,
+ // costlier path to the same facts. A review that expects them injected would
+ // be reading the old contract.
injected := map[string]bool{}
for _, name := range compiledKnowledgeToolNames {
injected[name] = true
}
- for _, name := range []string{
- navigateTreeToolName,
- navigateStructureToolName,
- graphExploreToolName,
- graphDocOutlineToolName,
- } {
+ for _, name := range []string{navigateTreeToolName, navigateStructureToolName} {
+ if injected[name] {
+ t.Errorf("%s must not be injected: compiled evidence travels with search results", name)
+ }
+ if _, ok := reg[name]; !ok {
+ t.Errorf("%s must stay registered so a template can declare it", name)
+ }
+ }
+ for _, name := range []string{graphExploreToolName, graphDocOutlineToolName} {
if !injected[name] {
t.Errorf("%s is never injected: a template that omits it leaves it unreachable", name)
}
@@ -69,8 +74,6 @@ func TestCompiledKnowledgeNamesAreStable(t *testing.T) {
want := []string{
graphDocOutlineToolName,
graphExploreToolName,
- navigateStructureToolName,
- navigateTreeToolName,
}
sort.Strings(want)
if len(got) != len(want) {
diff --git a/internal/agentic_rag/compiled_serve.go b/internal/agentic_rag/compiled_serve.go
new file mode 100644
index 0000000000..c68734ec2b
--- /dev/null
+++ b/internal/agentic_rag/compiled_serve.go
@@ -0,0 +1,533 @@
+//
+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package agentic_rag
+
+import (
+ "context"
+ "fmt"
+ "sort"
+ "strconv"
+ "strings"
+ "time"
+ "unicode/utf8"
+
+ "ragflow/internal/agent/runtime"
+ "ragflow/internal/common"
+ "ragflow/internal/engine"
+ enginetypes "ragflow/internal/engine/types"
+
+ "go.uber.org/zap"
+)
+
+// compiledServeMode selects which corpus text reaches the model after a locate
+// recall: raw chunks (off), compiled products only (only), or compiled products
+// with the raw body available on demand via list_chunks (first).
+type csMode int
+
+const (
+ csOff csMode = iota
+ csOnly
+ csFirst
+)
+
+func compiledServeMode() csMode {
+ switch strings.ToLower(strings.TrimSpace(common.GetEnv(common.EnvCompiledServe))) {
+ case "only":
+ return csOnly
+ case "first":
+ return csFirst
+ default:
+ return csOff
+ }
+}
+
+// compiledServeActive reports whether the locate exit of this tool should serve
+// compiled products instead of the raw snippet. web_search is never in scope
+// (its hits have no corpus document to derive a product from), and an
+// unrecognised tool is never served — the scope is an allowlist.
+func compiledServeActive(tool string) bool {
+ return compiledServeMode() != csOff && compiledServeAppliesTo(tool)
+}
+
+func compiledServeOnlyMode() bool {
+ return compiledServeMode() == csOnly
+}
+
+// compiledServeExcluded lists the tools that must NOT serve compiled products.
+// Every other tool that renders a locate result set is in scope, because the
+// serve point (formatLocateResultsXML) is shared by ALL locate tools: an
+// allowlist would silently skip any chunk-searching tool added later.
+//
+// - list_chunks is the deep-read fallback. Serving claims there would remove
+// the exact place the model goes back to for the raw text.
+// - web_search hits are web pages, not corpus chunks, so they carry no
+// source_chunk_ids to derive a product from.
+// - search_metadata returns document-level records, not passage text.
+// - the graph/navigation tools return structure (nodes, outlines), not chunks.
+var compiledServeExcluded = map[string]bool{
+ listChunksToolName: true,
+ webSearchToolName: true,
+ metadataSearchToolName: true,
+ graphExploreToolName: true,
+ graphDocOutlineToolName: true,
+ navigateTreeToolName: true,
+ navigateStructureToolName: true,
+}
+
+func compiledServeAppliesTo(tool string) bool {
+ if override := strings.TrimSpace(common.GetEnv(common.EnvCompiledServeScope)); override != "" {
+ m := make(map[string]bool, 4)
+ for _, t := range strings.Split(override, ",") {
+ if t = strings.TrimSpace(t); t != "" {
+ m[t] = true
+ }
+ }
+ return m[tool]
+ }
+ return !compiledServeExcluded[tool]
+}
+
+func compiledServeTopN() int {
+ return envIntDefault(common.EnvCompiledServeTopN, 12)
+}
+
+func compiledServeKinds() []string {
+ return nonEmptyStrings(strings.Split(common.GetEnv(common.EnvCompiledServeKinds), ","))
+}
+
+// compiledServeTypes narrows the served rows to these entity_type_kwd values.
+// Empty keeps every type, which is the graph/hypergraph behaviour: those rows
+// carry no entity_type_kwd. Setting TYPES=claim is what makes the same arm serve
+// claims compiled from the recalled chunk instead of abstract graph products.
+func compiledServeTypes() []string {
+ return nonEmptyStrings(strings.Split(common.GetEnv(common.EnvCompiledServeTypes), ","))
+}
+
+// compiledRow is one knowledge-compiled product derived from a recalled chunk.
+type compiledRow struct {
+ id string
+ kind string // compile_kwd (graph/hypergraph/tree/wiki/...)
+ typeName string // payload "type" (person/event/summary/...)
+ name string
+ description string
+ docID string
+ chunkIDs []string // source_chunk_ids — the lineage back to raw chunks
+ mention int // mention_count_int — drives the relevance ordering
+}
+
+// fetchCompiledProductsFn is the seam the rendering path calls. It is a package
+// var (not a direct call) so tests can substitute an engine-free source; the
+// real implementation reads ES/Infinity by source_chunk_ids lineage.
+var fetchCompiledProductsFn = fetchCompiledProducts
+
+// buildCompiledFilter is the lineage query: every compiled row whose
+// source_chunk_ids contains one of the recalled chunk ids, restricted to rows
+// that actually carry compile_kwd (ordinary chunks do not). This is the B design
+// — pure provenance linkage, no keyword/text matching on the compiled text.
+func buildCompiledFilter(chunkIDs, kinds, types []string) map[string]interface{} {
+ f := map[string]interface{}{
+ "exists": "compile_kwd",
+ "source_chunk_ids": chunkIDs,
+ }
+ if len(kinds) > 0 {
+ f["compile_kwd"] = kinds
+ }
+ if len(types) > 0 {
+ // Claim rows share compile_kwd=tree with tree nodes; entity_type_kwd is the
+ // only field that tells them apart, so claim serving is KINDS=tree +
+ // TYPES=claim.
+ f["entity_type_kwd"] = types
+ }
+ return f
+}
+
+func fetchCompiledProducts(ctx context.Context, datasetIDs, chunkIDs []string) []compiledRow {
+ tenantID := decisionScopeFrom(ctx).tenantID
+ de := engine.Get()
+ if de == nil || len(chunkIDs) == 0 {
+ return nil
+ }
+ start := time.Now()
+ res, err := de.Search(ctx, &enginetypes.SearchRequest{
+ IndexNames: []string{indexNameFor(tenantID, "")},
+ KbIDs: datasetIDs,
+ SelectFields: []string{"id", "content_with_weight", "source_chunk_ids", "compile_kwd", "doc_id"},
+ Filter: buildCompiledFilter(chunkIDs, compiledServeKinds(), compiledServeTypes()),
+ Limit: compiledServeTopN() * 4, // overscan so a mention_count sort can trim to top-N
+ // IncludeUnavailable mirrors datasetsHaveCompiledKnowledge: a product the
+ // pipeline hid should still be showable here, and the junk filter below
+ // drops rows that carry no usable content.
+ IncludeUnavailable: true,
+ })
+ if err != nil || res == nil {
+ common.DebugCtx(ctx, "agentic_rag: compiled serve fetch failed",
+ zap.Strings("datasets", datasetIDs), zap.Error(err))
+ return nil
+ }
+ rows := make([]compiledRow, 0, len(res.Chunks))
+ for _, raw := range res.Chunks {
+ if r, ok := parseCompiledRow(raw); ok {
+ rows = append(rows, r)
+ }
+ }
+ sort.SliceStable(rows, func(i, j int) bool {
+ return mentionCountOf(rows[i]) > mentionCountOf(rows[j])
+ })
+ if len(rows) > compiledServeTopN() {
+ rows = rows[:compiledServeTopN()]
+ }
+ common.InfoCtx(ctx, "agentic_rag: compiled serve fetched",
+ zap.Int("rows", len(rows)),
+ zap.Int("chunks", len(chunkIDs)),
+ zap.Duration("latency", time.Since(start)))
+ return rows
+}
+
+// parseCompiledRow turns one compiled row into a hit, dropping junk: rows whose
+// compile_kwd is the "*" placeholder carry no content, and rows whose payload
+// yields neither a name nor a description are unusable anchors.
+func parseCompiledRow(raw map[string]interface{}) (compiledRow, bool) {
+ kind := strings.TrimSpace(fmt.Sprint(raw["compile_kwd"]))
+ if kind == "" || kind == "*" {
+ return compiledRow{}, false
+ }
+ payload, ok := decodeJSONObject(contentWithWeightFromRaw(raw))
+ if !ok || payload == nil {
+ return compiledRow{}, false
+ }
+ name := strings.TrimSpace(stringFromAny(payload["name"]))
+ desc := strings.TrimSpace(stringFromAny(payload["description"]))
+ if name == "" && desc == "" {
+ return compiledRow{}, false
+ }
+ if desc == "" {
+ desc = name
+ }
+ return compiledRow{
+ id: fmt.Sprint(raw["id"]),
+ kind: kind,
+ typeName: strings.TrimSpace(stringFromAny(payload["type"])),
+ name: name,
+ description: desc,
+ docID: strings.TrimSpace(fmt.Sprint(raw["doc_id"])),
+ chunkIDs: navStringList(raw["source_chunk_ids"]),
+ mention: atoiOrZero(fmt.Sprint(raw["mention_count_int"])),
+ }, true
+}
+
+func mentionCountOf(r compiledRow) int {
+ return r.mention
+}
+
+// atoiOrZero parses an ES int field that may arrive as a string; a missing or
+// non-numeric value (the common case for rows never stamped with a count) is 0.
+func atoiOrZero(s string) int {
+ s = strings.TrimSpace(s)
+ if s == "" {
+ return 0
+ }
+ n, err := strconv.Atoi(s)
+ if err != nil {
+ return 0
+ }
+ return n
+}
+
+func compileProductText(p compiledRow) string {
+ t := p.name
+ if p.typeName != "" {
+ t = p.typeName + ": " + p.name
+ }
+ if p.description != "" {
+ if t != "" {
+ t += " — " + p.description
+ } else {
+ t = p.description
+ }
+ }
+ return t
+}
+
+// distinctChunkIDs / distinctDatasetIDs gather the recall scope from locate hits.
+func distinctChunkIDs(hits []snippetHit) []string {
+ seen := make(map[string]bool, len(hits))
+ out := make([]string, 0, len(hits))
+ for _, h := range hits {
+ id := h.chunk.ID
+ if id == "" || seen[id] {
+ continue
+ }
+ seen[id] = true
+ out = append(out, id)
+ }
+ return out
+}
+
+func distinctDatasetIDs(hits []snippetHit) []string {
+ seen := make(map[string]bool, len(hits))
+ out := make([]string, 0, len(hits))
+ for _, h := range hits {
+ id := h.chunk.DatasetID
+ if id == "" || seen[id] {
+ continue
+ }
+ seen[id] = true
+ out = append(out, id)
+ }
+ return out
+}
+
+// tryFormatLocateCompiled serves the compiled products for a locate result set.
+// It returns ok=false when no product was found, so the caller can passthrough
+// the raw snippet (the failure philosophy: never hand the model an empty result
+// that would make it re-search and inflate tokens).
+func tryFormatLocateCompiled(ctx context.Context, tool, query string, hits []snippetHit, notices ...string) (string, bool) {
+ products := fetchCompiledProductsFn(ctx, distinctDatasetIDs(hits), distinctChunkIDs(hits))
+ if len(products) == 0 {
+ return "", false
+ }
+ reg := evidenceRegistryFrom(ctx)
+ compiledCount := make(map[string]int, len(products))
+ for _, p := range products {
+ for _, cid := range p.chunkIDs {
+ compiledCount[cid]++
+ }
+ }
+ mode := compiledServeMode()
+ var b strings.Builder
+ b.WriteString(fmt.Sprintf("<search_results count=\"%d\" query=\"%s\">\n",
+ len(hits), xmlEscape(query)))
+ for _, notice := range notices {
+ b.WriteString(notice)
+ b.WriteString("\n")
+ }
+ for i, h := range hits {
+ c := h.chunk
+ compAttr := ""
+ if n, ok := compiledCount[c.ID]; ok {
+ compAttr = fmt.Sprintf(` compiled="%d"`, n)
+ }
+ // Metadata row only: rank/score/handle, NO <match_snippet> — the raw
+ // text is deliberately withheld; the model reads the compiled block.
+ b.WriteString(fmt.Sprintf(
+ "<chunk rank=\"%d\" chunk_id=\"%s\" doc_id=\"%s\" page_num=\"%d\" chunk_index=\"%d\" dataset_id=\"%s\" doc_name=\"%s\" score=\"%.3f\" chunk_runes=\"%d\"%s>\n",
+ i+1,
+ xmlEscape(c.ID), xmlEscape(c.DocumentID), c.PageNum, c.ChunkIndex,
+ xmlEscape(c.DatasetID), xmlEscape(c.DocumentName), c.Score,
+ utf8.RuneCountInString(c.Content), compAttr,
+ ))
+ b.WriteString("</chunk>\n")
+ }
+ b.WriteString(fmt.Sprintf("<compiled_products count=\"%d\">\n", len(products)))
+ for _, p := range products {
+ text := compileProductText(p)
+ refAttr := ""
+ if n, _ := reg.ServeText(p.id, text); n >= 0 {
+ refAttr = fmt.Sprintf(` ref="%d"`, n)
+ }
+ kind := xmlEscape(p.kind)
+ if kind == "" {
+ kind = "compiled"
+ }
+ b.WriteString(fmt.Sprintf("<product kind=\"%s\" doc_id=\"%s\"%s>%s</product>\n",
+ kind, xmlEscape(p.docID), refAttr, xmlEscape(text)))
+ }
+ b.WriteString("</compiled_products>\n")
+ if mode == csFirst {
+ b.WriteString("<deep_read_hint>If the compiled_products above do not contain the fact you need, read the ORIGINAL chunk that a product was derived from: call list_chunks(doc_id, anchor_chunk_ids=[that chunk_id], number_neighbors=0) — number_neighbors=0 returns EXACTLY that one chunk's original text, NOT the surrounding document (do not expand to the whole article). The chunk handles (chunk_id) and their compiled=\"N\" counts are in the chunk rows above. Only read a chunk whose compiled product failed to answer you.</deep_read_hint>\n")
+ }
+ if len(hits) == 0 {
+ b.WriteString("<hint>0 hits — the corpus may use a different WORD FORM of your terms. Retry with variants before concluding the corpus lacks the answer.</hint>\n")
+ }
+ b.WriteString("</search_results>")
+ return b.String(), true
+}
+
+// CompiledServeChunks applies compiled-serve to the standard (non-agentic)
+// retrieval result that chat_pipeline.go feeds to kbPrompt. It returns the
+// transformed chunk list, or nil when compiled-serve is inactive or no product
+// was found for any recalled chunk (the caller then keeps the raw chunks). The
+// only mode swaps each chunk's model-visible text for its compiled products; the
+// first mode prepends the products and keeps the original text so the model can
+// fall back to the raw chunk.
+func CompiledServeChunks(ctx context.Context, tenantID string, chunks []map[string]interface{}, datasetIDs []string) []map[string]interface{} {
+ mode := compiledServeMode()
+ if mode == csOff || len(chunks) == 0 {
+ return nil
+ }
+ // The standard retrieval path does not publish a decision scope; the compiled
+ // store lookup needs the tenant to resolve the index name.
+ ctx = withDecisionScope(ctx, tenantID, "")
+ chunkIDs := make([]string, 0, len(chunks))
+ for _, c := range chunks {
+ if id := chunkIDOf(c); id != "" {
+ chunkIDs = append(chunkIDs, id)
+ }
+ }
+ products := fetchCompiledProductsFn(ctx, datasetIDs, chunkIDs)
+ if len(products) == 0 {
+ common.InfoCtx(ctx, "agentic_rag: compiled serve (standard) no products",
+ zap.Int("chunks", len(chunkIDs)))
+ return nil
+ }
+ byChunk := map[string][]compiledRow{}
+ for _, p := range products {
+ for _, cid := range p.chunkIDs {
+ byChunk[cid] = append(byChunk[cid], p)
+ }
+ }
+ out := make([]map[string]interface{}, 0, len(chunks))
+ served := 0
+ for _, c := range chunks {
+ id := chunkIDOf(c)
+ nc := shallowCopyChunk(c)
+ prods := byChunk[id]
+ if len(prods) == 0 {
+ out = append(out, c)
+ continue
+ }
+ org := ""
+ if v, _ := c["content_with_weight"].(string); v != "" {
+ org = v
+ } else if v, _ := c["content"].(string); v != "" {
+ org = v
+ }
+ block := renderCompiledProductBlock(ctx, prods, mode)
+ var text string
+ if mode == csOnly {
+ text = block
+ } else {
+ text = block + "\n\n" + org
+ }
+ setChunkModelContent(nc, text)
+ out = append(out, nc)
+ served++
+ }
+ common.InfoCtx(ctx, "agentic_rag: compiled serve (standard) applied",
+ zap.Int("chunks", len(out)), zap.Int("served", served), zap.Int("products", len(products)))
+ return out
+}
+
+func chunkIDOf(c map[string]interface{}) string {
+ if id, _ := c["id"].(string); id != "" {
+ return id
+ }
+ if id, _ := c["chunk_id"].(string); id != "" {
+ return id
+ }
+ return ""
+}
+
+func shallowCopyChunk(c map[string]interface{}) map[string]interface{} {
+ nc := make(map[string]interface{}, len(c))
+ for k, v := range c {
+ nc[k] = v
+ }
+ return nc
+}
+
+func setChunkModelContent(c map[string]interface{}, text string) {
+ c["content_with_weight"] = text
+ c["content"] = text
+}
+
+// renderCompiledProductBlock renders the <compiled_products> block (and, in
+// first mode, the deep-read hint) for a set of products derived from one chunk.
+func renderCompiledProductBlock(ctx context.Context, prods []compiledRow, mode csMode) string {
+ var b strings.Builder
+ reg := evidenceRegistryFrom(ctx)
+ b.WriteString(fmt.Sprintf("<compiled_products count=\"%d\">\n", len(prods)))
+ for _, p := range prods {
+ txt := compileProductText(p)
+ refAttr := ""
+ if n, _ := reg.ServeText(p.id, txt); n >= 0 {
+ refAttr = fmt.Sprintf(` ref="%d"`, n)
+ }
+ kind := xmlEscape(p.kind)
+ if kind == "" {
+ kind = "compiled"
+ }
+ b.WriteString(fmt.Sprintf("<product kind=\"%s\" doc_id=\"%s\"%s>%s</product>\n",
+ kind, xmlEscape(p.docID), refAttr, xmlEscape(txt)))
+ }
+ b.WriteString("</compiled_products>\n")
+ if mode == csFirst {
+ b.WriteString("<deep_read_hint>If the compiled_products above do not contain the fact you need, read the ORIGINAL chunk that a product was derived from: call list_chunks(doc_id, anchor_chunk_ids=[that chunk_id], number_neighbors=0) — number_neighbors=0 returns EXACTLY that one chunk's original text, NOT the surrounding document. Only read a chunk whose compiled product failed to answer you.</deep_read_hint>\n")
+ }
+ return b.String()
+}
+
+// tryFormatChunksCompiled serves the compiled products of the chunks a deep-read
+// just fetched (only mode). A chunk with no compiled derivative keeps its raw
+// content (logged) so the read is never empty; ok=false means the whole set had
+// no derivatives and the caller should serve raw.
+func tryFormatChunksCompiled(ctx context.Context, docID string, chunks []runtime.RetrievalChunk, anchorMeta, notice string) (string, bool) {
+ ds := make([]string, 0, len(chunks))
+ cids := make([]string, 0, len(chunks))
+ seen := make(map[string]bool)
+ for _, c := range chunks {
+ if c.DatasetID != "" && !seen[c.DatasetID] {
+ seen[c.DatasetID] = true
+ ds = append(ds, c.DatasetID)
+ }
+ if c.ID != "" {
+ cids = append(cids, c.ID)
+ }
+ }
+ products := fetchCompiledProductsFn(ctx, ds, cids)
+ if len(products) == 0 {
+ return "", false
+ }
+ byChunk := make(map[string][]compiledRow, len(chunks))
+ for _, p := range products {
+ for _, cid := range p.chunkIDs {
+ byChunk[cid] = append(byChunk[cid], p)
+ }
+ }
+ reg := evidenceRegistryFrom(ctx)
+ var b strings.Builder
+ b.WriteString(fmt.Sprintf("<chunks doc_id=\"%s\" fetched=\"%d\"%s>\n",
+ xmlEscape(docID), len(chunks), anchorMeta))
+ if notice != "" {
+ b.WriteString(fmt.Sprintf("<notice>%s</notice>\n", xmlEscape(notice)))
+ }
+ for _, c := range chunks {
+ b.WriteString(fmt.Sprintf(
+ "<chunk chunk_id=\"%s\" doc_id=\"%s\" page_num=\"%d\" chunk_index=\"%d\" dataset_id=\"%s\" doc_name=\"%s\">\n",
+ xmlEscape(c.ID), xmlEscape(c.DocumentID), c.PageNum, c.ChunkIndex,
+ xmlEscape(c.DatasetID), xmlEscape(c.DocumentName)))
+ if prods := byChunk[c.ID]; len(prods) > 0 {
+ for _, p := range prods {
+ text := compileProductText(p)
+ refAttr := ""
+ if n, _ := reg.ServeText(p.id, text); n >= 0 {
+ refAttr = fmt.Sprintf(` ref="%d"`, n)
+ }
+ kind := xmlEscape(p.kind)
+ if kind == "" {
+ kind = "compiled"
+ }
+ b.WriteString(fmt.Sprintf("<content kind=\"%s\"%s>%s</content>\n", kind, refAttr, xmlEscape(text)))
+ }
+ } else {
+ // No derivative for this chunk: fall back to the raw body.
+ b.WriteString(fmt.Sprintf("<content>%s</content>\n", xmlEscape(c.Content)))
+ }
+ b.WriteString("</chunk>\n")
+ }
+ b.WriteString("</chunks>")
+ return b.String(), true
+}
diff --git a/internal/agentic_rag/compiled_serve_smoke_manual_test.go b/internal/agentic_rag/compiled_serve_smoke_manual_test.go
new file mode 100644
index 0000000000..c8ce3b1f43
--- /dev/null
+++ b/internal/agentic_rag/compiled_serve_smoke_manual_test.go
@@ -0,0 +1,81 @@
+//go:build manual
+
+package agentic_rag
+
+import (
+ "context"
+ "os"
+ "strings"
+ "testing"
+
+ "ragflow/internal/common"
+ "ragflow/internal/engine"
+ "ragflow/internal/server"
+)
+
+// TestCompiledServeSmoke_Manual is a read-only probe against a live document
+// engine: it takes one real chunk id (a chunk that a claim row points at through
+// source_chunk_ids) and asks the compiled-serve path to replace it with the
+// claim. It writes nothing.
+//
+// Run with:
+//
+// SMOKE_TENANT=<tenant> SMOKE_CHUNK=<chunk id> SMOKE_DOC=<doc id> \
+// bash build.sh --test-manual -run TestCompiledServeSmoke_Manual ./internal/agentic_rag
+func TestCompiledServeSmoke_Manual(t *testing.T) {
+ tenantID := os.Getenv("SMOKE_TENANT")
+ chunkID := os.Getenv("SMOKE_CHUNK")
+ docID := os.Getenv("SMOKE_DOC")
+ if tenantID == "" || chunkID == "" {
+ t.Fatal("SMOKE_TENANT and SMOKE_CHUNK are required")
+ }
+
+ t.Setenv("RAGFLOW_COMPILED_SERVE", "only")
+ t.Setenv("RAGFLOW_COMPILED_SERVE_KINDS", "tree")
+ t.Setenv("RAGFLOW_COMPILED_SERVE_TYPES", "claim")
+ t.Setenv("RAGFLOW_COMPILED_SERVE_TOP_N", "5")
+
+ if err := common.InitLogger("info", common.FileOutput{}, ""); err != nil {
+ t.Fatalf("init logger: %v", err)
+ }
+ if err := server.Init(""); err != nil {
+ t.Fatalf("init config: %v", err)
+ }
+ if err := engine.InitDocEngine(context.Background()); err != nil {
+ t.Fatalf("init doc engine: %v", err)
+ }
+
+ chunks := []map[string]interface{}{{
+ "id": chunkID,
+ "doc_id": docID,
+ "content_with_weight": "raw chunk body the compiled path should replace",
+ }}
+
+ out := CompiledServeChunks(context.Background(), tenantID, chunks, []string{})
+ if len(out) == 0 {
+ t.Fatalf("compiled serve returned nothing for chunk %s", chunkID)
+ }
+ for i, c := range out {
+ body := strings.TrimSpace(smokeString(c["content_with_weight"]))
+ if body == "" {
+ body = strings.TrimSpace(smokeString(c["content"]))
+ }
+ t.Logf("served[%d] keys=%d body=%q", i, len(c), smokeTruncate(body, 300))
+ }
+ if len(out) == 1 && smokeString(out[0]["content_with_weight"]) == chunks[0]["content_with_weight"] {
+ t.Fatalf("compiled serve fell back to the raw chunk; no claim product was served")
+ }
+}
+
+func smokeString(v interface{}) string {
+ s, _ := v.(string)
+ return s
+}
+
+func smokeTruncate(s string, n int) string {
+ r := []rune(s)
+ if len(r) <= n {
+ return s
+ }
+ return string(r[:n]) + "..."
+}
diff --git a/internal/agentic_rag/compiled_serve_test.go b/internal/agentic_rag/compiled_serve_test.go
new file mode 100644
index 0000000000..3c2fe63c0a
--- /dev/null
+++ b/internal/agentic_rag/compiled_serve_test.go
@@ -0,0 +1,227 @@
+//
+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package agentic_rag
+
+import (
+ "context"
+ "strings"
+ "testing"
+
+ "ragflow/internal/agent/runtime"
+ "ragflow/internal/common"
+)
+
+// sampleHits builds a locate hit set: chunkA has a compiled derivative, chunkB
+// does not. The raw snippet body must disappear from compiled modes.
+func sampleHits() []snippetHit {
+ return []snippetHit{
+ {chunk: runtime.RetrievalChunk{
+ ID: "chunkA", Content: "raw body for A", DocumentID: "doc1",
+ DatasetID: "kb1", DocumentName: "Doc One", Score: 0.9, ChunkIndex: 0, PageNum: 1,
+ }, snippet: "raw snippet for A"},
+ {chunk: runtime.RetrievalChunk{
+ ID: "chunkB", Content: "raw body for B", DocumentID: "doc1",
+ DatasetID: "kb1", DocumentName: "Doc One", Score: 0.5, ChunkIndex: 1, PageNum: 2,
+ }, snippet: "raw snippet for B"},
+ }
+}
+
+func sampleProducts() []compiledRow {
+ return []compiledRow{
+ {id: "p1", kind: "graph", typeName: "person", name: "Harold Peel",
+ description: "Former Bradford City player", docID: "doc1", chunkIDs: []string{"chunkA"}},
+ {id: "p2", kind: "graph", typeName: "event", name: "1911 Cup Final",
+ description: "Bradford won", docID: "doc1", chunkIDs: []string{"chunkA", "chunkB"}},
+ }
+}
+
+func compiledCtx() context.Context {
+ return WithEvidenceRegistry(context.Background(), NewEvidenceRegistry())
+}
+
+func withFetchFn(t *testing.T, fn func(context.Context, []string, []string) []compiledRow) {
+ t.Helper()
+ saved := fetchCompiledProductsFn
+ fetchCompiledProductsFn = fn
+ t.Cleanup(func() { fetchCompiledProductsFn = saved })
+}
+
+// TestCompiledServeOffIsByteIdentical: the off path (and the only path when no
+// product is found) must serve the raw snippet exactly as today — the branch is a
+// no-op, so the rendered bytes are unchanged.
+func TestCompiledServeOffIsByteIdentical(t *testing.T) {
+ t.Setenv(common.EnvCompiledServe, "off")
+ ctx := compiledCtx()
+ off := formatLocateResultsXML(ctx, searchBm25ChunksToolName, "q", sampleHits())
+
+ t.Setenv(common.EnvCompiledServe, "only")
+ withFetchFn(t, func(context.Context, []string, []string) []compiledRow { return nil })
+ onlyNoProduct := formatLocateResultsXML(ctx, searchBm25ChunksToolName, "q", sampleHits())
+
+ if off != onlyNoProduct {
+ t.Fatalf("off path and only-without-products must be byte-identical:\noff=%s\nonly=%s", off, onlyNoProduct)
+ }
+ if !strings.Contains(off, "<match_snippet>") {
+ t.Errorf("off path must still serve the raw snippet")
+ }
+ if strings.Contains(off, "<compiled_products>") {
+ t.Errorf("off path must not emit compiled products")
+ }
+}
+
+// TestCompiledServeOnlyDropsRawText: only mode serves compiled products and the
+// chunk metadata handles, but withholds the raw snippet/body.
+func TestCompiledServeOnlyDropsRawText(t *testing.T) {
+ t.Setenv(common.EnvCompiledServe, "only")
+ withFetchFn(t, func(context.Context, []string, []string) []compiledRow { return sampleProducts() })
+ out := formatLocateResultsXML(compiledCtx(), searchBm25ChunksToolName, "q", sampleHits())
+
+ if strings.Contains(out, "<match_snippet>") {
+ t.Errorf("only mode must not serve the raw snippet:\n%s", out)
+ }
+ if !strings.Contains(out, "<compiled_products ") {
+ t.Errorf("only mode must emit the compiled_products block:\n%s", out)
+ }
+ if !strings.Contains(out, "<product kind=\"graph\"") {
+ t.Errorf("only mode must render compiled product rows:\n%s", out)
+ }
+ if !strings.Contains(out, "chunk_id=\"chunkA\"") {
+ t.Errorf("only mode must keep the chunk handle for deep-read fallback:\n%s", out)
+ }
+ if !strings.Contains(out, "compiled=\"2\"") {
+ t.Errorf("only mode must annotate each hit with its compiled derivative count:\n%s", out)
+ }
+ if strings.Contains(out, "<deep_read_hint>") {
+ t.Errorf("only mode must not emit the deep_read_hint:\n%s", out)
+ }
+ if strings.Contains(out, "raw body for A") {
+ t.Errorf("only mode must not leak the raw chunk body:\n%s", out)
+ }
+}
+
+// TestCompiledServeFirstKeepsHandlesAndHint: first mode shows compiled products
+// plus the chunk handles and the deep_read_hint, but still withholds the raw snippet.
+func TestCompiledServeFirstKeepsHandlesAndHint(t *testing.T) {
+ t.Setenv(common.EnvCompiledServe, "first")
+ withFetchFn(t, func(context.Context, []string, []string) []compiledRow { return sampleProducts() })
+ out := formatLocateResultsXML(compiledCtx(), grepChunksToolName, "q", sampleHits())
+
+ if strings.Contains(out, "<match_snippet>") {
+ t.Errorf("first mode must not serve the raw snippet:\n%s", out)
+ }
+ if !strings.Contains(out, "<compiled_products ") {
+ t.Errorf("first mode must emit compiled_products:\n%s", out)
+ }
+ if !strings.Contains(out, "<deep_read_hint>") {
+ t.Errorf("first mode must emit the deep_read_hint:\n%s", out)
+ }
+ if !strings.Contains(out, "number_neighbors=0") {
+ t.Errorf("first mode's hint must pin the fallback to the single original chunk (number_neighbors=0):\n%s", out)
+ }
+ if !strings.Contains(out, "chunk_id=\"chunkA\"") {
+ t.Errorf("first mode must keep the chunk handle:\n%s", out)
+ }
+}
+
+// TestCompiledServeFallsBackWhenNoCompiledRows: when no compiled product is found
+// (engine down, or no lineage), the run must passthrough the raw snippet rather
+// than hand the model an empty result — the failure philosophy.
+func TestCompiledServeFallsBackWhenNoCompiledRows(t *testing.T) {
+ t.Setenv(common.EnvCompiledServe, "only")
+ withFetchFn(t, func(context.Context, []string, []string) []compiledRow { return nil })
+ out := formatLocateResultsXML(compiledCtx(), searchBm25ChunksToolName, "q", sampleHits())
+
+ if !strings.Contains(out, "<match_snippet>") {
+ t.Errorf("no-compiled fallback must passthrough the raw snippet:\n%s", out)
+ }
+ if strings.Contains(out, "<compiled_products>") {
+ t.Errorf("no-compiled fallback must not emit an empty compiled block:\n%s", out)
+ }
+}
+
+// TestCompiledServeAppliesToToolScope: web_search is never in scope (no corpus
+// document to derive a product from); the corpus-passage locate tools are.
+func TestCompiledServeAppliesToToolScope(t *testing.T) {
+ t.Setenv(common.EnvCompiledServe, "only")
+ // Tools that must never serve compiled products.
+ for _, tool := range []string{
+ webSearchToolName,
+ listChunksToolName,
+ metadataSearchToolName,
+ graphExploreToolName,
+ graphDocOutlineToolName,
+ navigateTreeToolName,
+ navigateStructureToolName,
+ } {
+ if compiledServeAppliesTo(tool) {
+ t.Errorf("%s must never be in compiled-serve scope", tool)
+ }
+ }
+ // Every chunk-searching tool is in scope — and so is a tool added later:
+ // the scope is an exclusion list, so a new locate tool inherits the arm
+ // instead of silently missing it.
+ for _, tool := range []string{
+ grepChunksToolName,
+ searchBm25ChunksToolName,
+ searchChunksToolName,
+ searchSemanticChunksToolName,
+ "some_future_chunk_tool",
+ } {
+ if !compiledServeAppliesTo(tool) {
+ t.Errorf("%s must be in compiled-serve scope", tool)
+ }
+ }
+
+ t.Setenv(common.EnvCompiledServeScope, "grep_chunks")
+ if !compiledServeAppliesTo(grepChunksToolName) {
+ t.Errorf("scope override must include grep_chunks")
+ }
+ if compiledServeAppliesTo(searchBm25ChunksToolName) {
+ t.Errorf("scope override must exclude search_bm25_chunks")
+ }
+}
+
+// TestCompiledServeRequestShape: the lineage query is pure provenance (B design) —
+// it filters by source_chunk_ids and compile_kwd, with NO MatchExprs on the
+// compiled text, so query-phrasing drift cannot drop a recalled chunk's product.
+func TestCompiledServeRequestShape(t *testing.T) {
+ f := buildCompiledFilter([]string{"c1", "c2"}, nil, nil)
+ if got, _ := f["exists"].(string); got != "compile_kwd" {
+ t.Errorf("filter must require compile_kwd presence, got %v", f["exists"])
+ }
+ if got, _ := f["source_chunk_ids"].([]string); len(got) != 2 {
+ t.Errorf("filter must carry the recalled chunk ids, got %v", f["source_chunk_ids"])
+ }
+ if _, ok := f["compile_kwd"]; ok {
+ t.Errorf("without explicit kinds the filter must not add a compile_kwd terms clause")
+ }
+ if _, ok := f["entity_type_kwd"]; ok {
+ t.Errorf("without explicit types the filter must not add an entity_type_kwd terms clause")
+ }
+
+ f2 := buildCompiledFilter([]string{"c1"}, []string{"tree", "graph"}, nil)
+ if got, _ := f2["compile_kwd"].([]string); len(got) != 2 {
+ t.Errorf("explicit kinds must become a compile_kwd terms clause, got %v", f2["compile_kwd"])
+ }
+
+ // Claim rows carry compile_kwd=tree just like tree nodes, so TYPES is the only
+ // knob that separates them.
+ f3 := buildCompiledFilter([]string{"c1"}, []string{"tree"}, []string{"claim"})
+ got, _ := f3["entity_type_kwd"].([]string)
+ if len(got) != 1 || got[0] != "claim" {
+ t.Errorf("explicit types must become an entity_type_kwd terms clause, got %v", f3["entity_type_kwd"])
+ }
+}
diff --git a/internal/agentic_rag/decision_filter.go b/internal/agentic_rag/decision_filter.go
index 80b2332166..3c5e8a26af 100644
--- a/internal/agentic_rag/decision_filter.go
+++ b/internal/agentic_rag/decision_filter.go
@@ -137,6 +137,10 @@ func envIntDefault(name string, def int) int {
const (
filterSideDeepRead = "deep_read"
filterSideSnippet = "snippet"
+ // filterSideClaim is the third exit: compiled claims, judged one statement at
+ // a time. It is a separate side because the unit is different - a claim is
+ // not a passage, and a threshold fitted on passages is not portable to it.
+ filterSideClaim = "claim"
)
// passage identifies one member of one result set across the filter's layers.
@@ -697,3 +701,215 @@ func exemptFields(p passage, text string) []zap.Field {
zap.Bool("exempt", true),
}
}
+
+// claimFilterEnabled gates the claim exit. On by default, like the other two: the
+// claim page is the one model-visible block with no length bound of its own, so a
+// deployment that only sets RAGFLOW_DECISION_DIR gets the bound as well.
+func claimFilterEnabled() bool {
+ return envBoolDefault(common.EnvDecisionFilterClaim, true)
+}
+
+// claimRelativeFloor is the share of the page's BEST probability a claim must
+// keep before the absolute threshold may drop it. The absolute threshold is
+// fitted on one judge and one passage length; a claim is a short statement, so
+// its probabilities sit lower as a class and the two scales are not comparable.
+// Measured on the Bamboo judge over real claim rows: median 0.113 on a question
+// the page did answer, against a 0.30 absolute threshold - i.e. the absolute
+// threshold alone would have dropped 83% of a page that was mostly on topic.
+const claimRelativeFloor = 0.4
+
+// claimFloorEnabled gates the per-chunk floor and the relative threshold. With it
+// off the exit is the plain absolute gate it was before.
+func claimFloorEnabled() bool {
+ return envBoolDefault(common.EnvDecisionClaimFloor, true)
+}
+
+// claimJudgeCapDefault bounds how many statements ONE claim page may send to the
+// judge. The page itself is unbounded by design - a chunk is on it whole - and
+// that is fine for the prompt but not for the judge: measured over a tag-along
+// debug run, a single page carried 372 statements, which at the judge's batch of
+// 8 is 47 round trips for ONE retrieval round. That is the dominant cost of the
+// turn, and it is what kept tripping the shared-key rate limit, whose breaker
+// then turned the filter off and let the whole page into the prompt (measured:
+// 43k-59k tokens per question against a 197k baseline average for the run).
+const claimJudgeCapDefault = 16
+
+// claimJudgeCap is the per-page judge bound, env-tunable so a deployment with a
+// fast local judge can raise it and one on a rate-limited key can lower it.
+func claimJudgeCap() int {
+ return envIntDefault(common.EnvDecisionClaimJudgeCap, claimJudgeCapDefault)
+}
+
+// claimMinProbDefault is the P(relevant) a statement must reach to survive.
+//
+// It is NOT the passage threshold. A statement is one fact with a short quote -
+// thirty to eighty tokens - while the threshold in RAGFLOW_DECISION_MIN_PROB was
+// calibrated on chunk passages several times that size. Measured on identical
+// irrelevant evidence the two shapes do not even share a scale (the same passage
+// scored 0.0 on one judge and 0.042 on another), so borrowing the passage
+// threshold for statements is how a correctly recalled statement gets dropped:
+// the claim page is exactly where the recall that matters is weakest.
+const claimMinProbDefault = 0.25
+
+// claimMinProb is the statement threshold, env-tunable so the two exits can be
+// tuned against their own evidence instead of a shared guess.
+func claimMinProb() float64 {
+ return envFloatDefault(common.EnvDecisionClaimMinProb, claimMinProbDefault)
+}
+
+// capClaimPage returns the statements a page may send to the judge, in page order:
+// the leading limit entries, plus the first claim of every chunk those entries did
+// not cover. A chunk is on the page because the retrieval ranked it, so it keeps
+// one voice even when all of its claims sit past the bound. Everything else is
+// DROPPED, not carried un-judged: an un-judged tail is exactly what let a page
+// reach 372 statements, and a bound that only bounds the judge still pays the
+// prompt cost of the rest.
+func capClaimPage(claims []claimHit, limit int) []claimHit {
+ if limit <= 0 || len(claims) <= limit {
+ return claims
+ }
+ keep := make([]bool, len(claims))
+ covered := make(map[string]struct{}, limit)
+ for i := 0; i < limit; i++ {
+ keep[i] = true
+ covered[claims[i].chunkID] = struct{}{}
+ }
+ for i := limit; i < len(claims); i++ {
+ id := claims[i].chunkID
+ if _, ok := covered[id]; ok {
+ continue
+ }
+ covered[id] = struct{}{}
+ keep[i] = true
+ }
+ out := make([]claimHit, 0, limit+len(covered))
+ for i, c := range claims {
+ if keep[i] {
+ out = append(out, c)
+ }
+ }
+ return out
+}
+
+// claimJudgeQuoteRunes bounds the verbatim evidence attached to a claim before
+// the model is asked about it. A statement alone is often too terse to judge -
+// "the port closed in 1902" says nothing about whether it answers the question -
+// so the quote travels with it, trimmed: the question is whether the claim earns
+// its line, and a 1200-rune quote costs more to judge than the line it saves.
+const claimJudgeQuoteRunes = 400
+
+// claimJudgeText is the text the filter asks about for one claim: the statement,
+// plus the head of its verbatim evidence when it has one.
+func claimJudgeText(c claimHit) string {
+ text := strings.TrimSpace(c.name)
+ if q := strings.TrimSpace(c.quote); q != "" {
+ text += "\n" + snippetRunes(q, claimJudgeQuoteRunes)
+ }
+ return text
+}
+
+// filterClaims drops the compiled claims the sufficiency model does not find
+// useful for the question this call is asking.
+//
+// The claim page carries no budget of any kind - a chunk is on it whole, with
+// every claim it carries, or not at all - so a chunk with many claims can cost
+// more than the chunk itself. Judging the lines is what bounds that: the page
+// stays whole as an assembly, and the statements the question does not need are
+// removed one at a time.
+//
+// Every degraded path keeps the claim: no model deployed, no question in the
+// context, the exit disabled, a claim the model never ruled on (budget spent,
+// cancelled run, failed forward pass). A filter that cannot run must not cost the
+// page its evidence. The one exception is a page the model judged entirely
+// useless: the single best-ranked claim is kept so the page stays non-empty -
+// an empty page makes the callers serve the raw chunk instead, which is more
+// text than the claim it replaced.
+func filterClaims(ctx context.Context, question string, claims []claimHit) []claimHit {
+ if len(claims) == 0 || !claimFilterEnabled() {
+ return claims
+ }
+ question = strings.TrimSpace(question)
+ // Bound the page BEFORE the judge is consulted, and on every path below it -
+ // including the degraded ones. The page is ordered (chunk rank, then closeness
+ // to the question), so the bound removes the statements furthest from the
+ // question first, and no chunk that made the page is left voiceless.
+ requested := len(claims)
+ claims = capClaimPage(claims, claimJudgeCap())
+ if len(claims) != requested {
+ common.DebugCtx(ctx, "agentic_rag: claim page capped for the judge",
+ zap.Int("claims_in", requested),
+ zap.Int("cap", claimJudgeCap()),
+ zap.Int("claims_kept", len(claims)))
+ }
+ if question == "" || !decisionAvailable(ctx) {
+ return claims
+ }
+ texts := make([]string, len(claims))
+ for i, c := range claims {
+ texts[i] = claimJudgeText(c)
+ }
+ verdicts := decisionJudge(ctx, question, texts)
+ // The floor is per CHUNK: a chunk's claims are one chunk's representation, so
+ // the most question-like statement it produced is kept whatever the absolute
+ // threshold says about it. The relative threshold is the same idea for the
+ // page: a statement close to the page's own best is on topic even when the
+ // absolute scale says otherwise.
+ floor := claimFloorEnabled()
+ best := make(map[string]float64, 8)
+ pageMax := 0.0
+ if floor {
+ for i, c := range claims {
+ if i >= len(verdicts) || !verdicts[i].Judged {
+ continue
+ }
+ p := verdicts[i].Probability
+ if cur, ok := best[c.chunkID]; !ok || p > cur {
+ best[c.chunkID] = p
+ }
+ if p > pageMax {
+ pageMax = p
+ }
+ }
+ }
+ kept := make([]claimHit, 0, len(claims))
+ judged, dropped, floored := 0, 0, 0
+ for i, c := range claims {
+ if i >= len(verdicts) {
+ kept = append(kept, c)
+ continue
+ }
+ v := verdicts[i]
+ if !v.Judged {
+ kept = append(kept, c)
+ continue
+ }
+ judged++
+ p := passage{side: filterSideClaim, tool: "compiled_claim", chunkID: c.chunkID, docID: c.docID, pos: i}
+ logDecision(ctx, p, 0, v)
+ // The statement threshold, not the passage one: v.Useful was computed
+ // against RAGFLOW_DECISION_MIN_PROB, which is calibrated on chunk passages.
+ if v.Probability < claimMinProb() {
+ if floor && pageMax > 0 && (v.Probability >= pageMax*claimRelativeFloor || v.Probability >= best[c.chunkID]) {
+ floored++
+ kept = append(kept, c)
+ continue
+ }
+ dropped++
+ continue
+ }
+ kept = append(kept, c)
+ }
+ if len(kept) == 0 {
+ common.InfoCtx(ctx, "agentic_rag: decision dropped every claim, keeping the best-ranked one",
+ zap.Int("claims_in", len(claims)),
+ zap.Int("judged", judged))
+ return claims[:1]
+ }
+ common.InfoCtx(ctx, "agentic_rag: decision filtered claims",
+ zap.Int("claims_in", len(claims)),
+ zap.Int("judged", judged),
+ zap.Int("dropped", dropped),
+ zap.Int("kept_by_floor", floored),
+ zap.Int("claims_out", len(kept)))
+ return kept
+}
diff --git a/internal/agentic_rag/decision_filter_test.go b/internal/agentic_rag/decision_filter_test.go
index 879ef9c001..2bbf5af68b 100644
--- a/internal/agentic_rag/decision_filter_test.go
+++ b/internal/agentic_rag/decision_filter_test.go
@@ -18,6 +18,7 @@ package agentic_rag
import (
"context"
+ "fmt"
"strings"
"testing"
@@ -97,7 +98,14 @@ func verdictsOf(useful ...bool) func(context.Context, string, []string) []decisi
return func(_ context.Context, _ string, segments []string) []decisionhead.Verdict {
out := make([]decisionhead.Verdict, len(segments))
for i, segment := range segments {
- out[i] = decisionhead.Verdict{Segment: segment, Useful: useful[i], Judged: true}
+ // The claim exit reads Probability, so a stub that only sets Useful would
+ // look like a 0.0 verdict to it. 0.9 clears both thresholds, 0.1 clears
+ // neither.
+ p := 0.1
+ if useful[i] {
+ p = 0.9
+ }
+ out[i] = decisionhead.Verdict{Segment: segment, Useful: useful[i], Judged: true, Probability: p}
}
return out
}
@@ -519,3 +527,225 @@ func TestDroppedSnippetConsumesNoRefHandle(t *testing.T) {
t.Fatalf("count does not reflect the served hits: %q", out)
}
}
+
+// The claim exit judges LINES, not pages: a claim is an atomic statement, so one
+// the question does not need leaves on its own without taking its neighbours with
+// it. This is the only length bound the claim page has.
+func TestClaimFilterDropsUnusefulClaimLines(t *testing.T) {
+ stubDecision(t, wholeText(), verdictsOf(true, false, true))
+ claims := []claimHit{
+ {name: "a", chunkID: "c1"},
+ {name: "b", chunkID: "c1"},
+ {name: "c", chunkID: "c1"},
+ }
+ got := filterClaims(context.Background(), "q", claims)
+ if len(got) != 2 || got[0].name != "a" || got[1].name != "c" {
+ t.Fatalf("kept %+v, want a and c", got)
+ }
+}
+
+func TestClaimFilterPassesThroughWhenDecisionUnavailable(t *testing.T) {
+ stubDecision(t, wholeText(), verdictsOf(false, false))
+ decisionAvailable = func(context.Context) bool { return false }
+ claims := []claimHit{{name: "a"}, {name: "b"}}
+ if got := filterClaims(context.Background(), "q", claims); len(got) != 2 {
+ t.Fatalf("kept %d claims with the judge unavailable, want 2", len(got))
+ }
+}
+
+func TestClaimFilterPassesThroughWhenDisabled(t *testing.T) {
+ t.Setenv(common.EnvDecisionFilterClaim, "0")
+ stubDecision(t, wholeText(), verdictsOf(false, false))
+ claims := []claimHit{{name: "a"}, {name: "b"}}
+ if got := filterClaims(context.Background(), "q", claims); len(got) != 2 {
+ t.Fatalf("kept %d claims with the exit disabled, want 2", len(got))
+ }
+}
+
+// Unjudged is not a verdict: a budget that ran out must not cost the page its
+// evidence.
+func TestClaimFilterKeepsUnjudgedLines(t *testing.T) {
+ stubDecision(t, wholeText(), func(context.Context, string, []string) []decisionhead.Verdict {
+ return []decisionhead.Verdict{{Segment: "a"}, {Segment: "b"}}
+ })
+ claims := []claimHit{{name: "a"}, {name: "b"}}
+ if got := filterClaims(context.Background(), "q", claims); len(got) != 2 {
+ t.Fatalf("kept %d claims, want both unjudged lines kept", len(got))
+ }
+}
+
+// claimPage builds a page whose first `head` statements belong to c1 and whose
+// tail spreads over c2..c4, which is the shape a real page has: one ranked chunk
+// contributing most of the statements and the rest contributing a few.
+func claimPage(head, tail int) []claimHit {
+ out := make([]claimHit, 0, head+tail)
+ for i := 0; i < head; i++ {
+ out = append(out, claimHit{name: fmt.Sprintf("head-%d", i), chunkID: "c1"})
+ }
+ chunks := []string{"c2", "c3", "c4"}
+ for i := 0; i < tail; i++ {
+ out = append(out, claimHit{name: fmt.Sprintf("tail-%d", i), chunkID: chunks[i%len(chunks)]})
+ }
+ return out
+}
+
+// The judge bound is enforced BEFORE the judge is asked: the page is cut to the
+// bound plus one statement per chunk the bound did not cover, and only that many
+// statements are sent. Without this, a 372-statement page is 47 judge round trips
+// for a single retrieval round - the cost that dominated the turn.
+func TestClaimPageCappedBeforeJudge(t *testing.T) {
+ t.Setenv(common.EnvDecisionClaimJudgeCap, "16")
+ var judged int
+ stubDecision(t, wholeText(), func(_ context.Context, _ string, segments []string) []decisionhead.Verdict {
+ judged = len(segments)
+ out := make([]decisionhead.Verdict, len(segments))
+ for i := range segments {
+ out[i] = decisionhead.Verdict{Segment: segments[i], Useful: true, Judged: true, Probability: 0.9}
+ }
+ return out
+ })
+ claims := claimPage(16, 4)
+ got := filterClaims(context.Background(), "q", claims)
+ // 16 leading + c2, c3, c4 (c2 repeats at tail-3 and must not be counted twice).
+ const want = 19
+ if judged != want {
+ t.Fatalf("judged %d statements, want the capped page of %d", judged, want)
+ }
+ if len(got) != want {
+ t.Fatalf("kept %d claims, want %d", len(got), want)
+ }
+ for _, chunk := range []string{"c1", "c2", "c3", "c4"} {
+ found := false
+ for _, c := range got {
+ if c.chunkID == chunk {
+ found = true
+ break
+ }
+ }
+ if !found {
+ t.Fatalf("chunk %s lost its representative: %+v", chunk, got)
+ }
+ }
+}
+
+// A dead judge must still not let an unbounded page into the prompt: the bound is
+// the page's contract, not the judge's convenience.
+func TestClaimPageCappedEvenWhenJudgeUnavailable(t *testing.T) {
+ t.Setenv(common.EnvDecisionClaimJudgeCap, "16")
+ prev := decisionAvailable
+ decisionAvailable = func(context.Context) bool { return false }
+ t.Cleanup(func() { decisionAvailable = prev })
+ got := filterClaims(context.Background(), "q", claimPage(16, 4))
+ if len(got) != 19 {
+ t.Fatalf("kept %d claims with the judge down, want the capped page of 19", len(got))
+ }
+}
+
+// A page inside the bound is passed through untouched - capping must never
+// reorder or drop a small page.
+func TestClaimPageUnderTheCapIsUntouched(t *testing.T) {
+ t.Setenv(common.EnvDecisionClaimJudgeCap, "16")
+ stubDecision(t, wholeText(), verdictsOf(true, true, true))
+ claims := []claimHit{
+ {name: "a", chunkID: "c1"},
+ {name: "b", chunkID: "c2"},
+ {name: "c", chunkID: "c3"},
+ }
+ got := filterClaims(context.Background(), "q", claims)
+ if len(got) != 3 || got[0].name != "a" || got[1].name != "b" || got[2].name != "c" {
+ t.Fatalf("kept %+v, want the page untouched", got)
+ }
+}
+
+// claimProbVerdicts hands every claim line the given probability and judges all
+// of them NOT useful, which is the case the floor exists for: nothing passes the
+// absolute threshold, yet the page still has to hold one statement per chunk.
+func claimProbVerdicts(probs ...float64) func(context.Context, string, []string) []decisionhead.Verdict {
+ return func(_ context.Context, _ string, segments []string) []decisionhead.Verdict {
+ out := make([]decisionhead.Verdict, len(segments))
+ for i := range segments {
+ p := 0.0
+ if i < len(probs) {
+ p = probs[i]
+ }
+ out[i] = decisionhead.Verdict{Segment: segments[i], Useful: false, Judged: true, Probability: p}
+ }
+ return out
+ }
+}
+
+// One statement per CHUNK survives, chosen two ways: the chunk's own best
+// probability (a chunk nobody scored well still gets to speak for itself) and the
+// page-relative threshold (a statement close to the page's best is on topic even
+// when the absolute scale says otherwise). A claim that is neither is dropped.
+func TestClaimFilterKeepsOnePerChunkByFloor(t *testing.T) {
+ t.Setenv(common.EnvDecisionClaimFloor, "1")
+ // pageMax = 0.35, so the relative threshold is 0.14.
+ stubDecision(t, wholeText(), claimProbVerdicts(0.10, 0.05, 0.35))
+ claims := []claimHit{
+ {name: "a", chunkID: "c1"},
+ {name: "b", chunkID: "c1"},
+ {name: "c", chunkID: "c2"},
+ }
+ got := filterClaims(context.Background(), "q", claims)
+ if len(got) != 2 || got[0].name != "a" || got[1].name != "c" {
+ t.Fatalf("kept %+v, want a (c1's best, below the relative threshold) and c (above it)", got)
+ }
+}
+
+// With the floor off the exit is the old absolute one: every line is dropped and
+// the page falls back to its single best-ranked claim.
+func TestClaimFilterWithoutFloorDropsTheWholePage(t *testing.T) {
+ t.Setenv(common.EnvDecisionClaimFloor, "0")
+ stubDecision(t, wholeText(), claimProbVerdicts(0.10, 0.05, 0.20))
+ claims := []claimHit{
+ {name: "a", chunkID: "c1"},
+ {name: "b", chunkID: "c1"},
+ {name: "c", chunkID: "c2"},
+ }
+ got := filterClaims(context.Background(), "q", claims)
+ if len(got) != 1 || got[0].name != "a" {
+ t.Fatalf("kept %+v, want only the best-ranked claim without the floor", got)
+ }
+}
+
+// A statement is not a passage. The claim exit rules on its own threshold because
+// a thirty-token fact and a thousand-token chunk do not share a score scale, and
+// borrowing the passage number is how a correctly recalled statement gets dropped.
+func TestClaimThresholdIsSeparateFromPassageThreshold(t *testing.T) {
+ t.Setenv(common.EnvDecisionMinProb, "0.30")
+ t.Setenv(common.EnvDecisionClaimMinProb, "0.25")
+ stubDecision(t, wholeText(), claimProbVerdicts(0.27))
+ got := filterClaims(context.Background(), "q", []claimHit{{name: "a", chunkID: "c1"}})
+ if len(got) != 1 || got[0].name != "a" {
+ t.Fatalf("kept %+v, want the 0.27 statement kept by the 0.25 claim threshold", got)
+ }
+}
+
+// ...and the defaults are the split the deployment expects: 0.30 for passages,
+// 0.25 for statements.
+func TestClaimMinProbDefaults(t *testing.T) {
+ t.Setenv(common.EnvDecisionMinProb, "")
+ t.Setenv(common.EnvDecisionClaimMinProb, "")
+ if got := claimMinProb(); got != 0.25 {
+ t.Fatalf("claim min prob = %v, want 0.25", got)
+ }
+ if defaultDecisionMinProb != 0.30 {
+ t.Fatalf("passage min prob = %v, want 0.30", defaultDecisionMinProb)
+ }
+}
+
+// A page the model judged entirely useless keeps its best-ranked claim: an empty
+// page makes the callers serve the raw chunk instead, which costs more text than
+// the claim it replaced.
+func TestClaimFilterKeepsBestRankedClaimWhenEveryLineDrops(t *testing.T) {
+ // Floor off: the floor exists to keep something, so the all-dropped fallback is
+ // only observable without it.
+ t.Setenv(common.EnvDecisionClaimFloor, "0")
+ stubDecision(t, wholeText(), verdictsOf(false, false))
+ claims := []claimHit{{name: "a"}, {name: "b"}}
+ got := filterClaims(context.Background(), "q", claims)
+ if len(got) != 1 || got[0].name != "a" {
+ t.Fatalf("kept %+v, want the best-ranked claim only", got)
+ }
+}
diff --git a/internal/agentic_rag/helper.go b/internal/agentic_rag/helper.go
index 9146c25832..0db3ba9a3c 100644
--- a/internal/agentic_rag/helper.go
+++ b/internal/agentic_rag/helper.go
@@ -562,7 +562,22 @@ func formatLocateResultsXML(ctx context.Context, tool, query string, hits []snip
// to every renderer: a locate hit is also how the model learns a document
// exists, and only the corpus-passage tools can pay for that (see
// snippetFilterTools).
+ if compiledServeActive(tool) && len(hits) > 0 {
+ if out, ok := tryFormatLocateCompiled(ctx, tool, query, hits, notices...); ok {
+ return out
+ }
+ common.InfoCtx(ctx, "agentic_rag: compiled serve located no products; passthrough raw",
+ zap.String("tool", tool))
+ }
hits = filterSnippetHits(ctx, tool, hits)
+ // Compiled evidence comes FIRST, ahead of the hits it was compiled from: a
+ // corpus that has claims offers the propositions (plus their verbatim
+ // quotes) before the raw passage, so the model can answer without paying for
+ // a deep read. The block is empty for a corpus without claims, for web hits,
+ // and for claims this turn already showed.
+ if notice := compiledEvidenceNotice(ctx, tool, query, hits); notice != "" {
+ notices = append(notices, notice)
+ }
// Single serve point for every locate tool: one debug line per served chunk
// records exactly what went in front of the model (silent unless the logger
// runs at debug level).
@@ -724,7 +739,22 @@ func formatChunksXML(ctx context.Context, docID string, chunks []runtime.Retriev
// handle, or the model would hold a number for text it never saw. Filtering
// first also makes `fetched` keep its one invariant — it counts the <chunk>
// elements below it.
+ if compiledServeOnlyMode() && len(chunks) > 0 {
+ if out, ok := tryFormatChunksCompiled(ctx, docID, chunks, anchorMeta, notice); ok {
+ return out
+ }
+ common.InfoCtx(ctx, "agentic_rag: compiled deep-read located no products; passthrough raw",
+ zap.String("doc_id", docID))
+ }
chunks = filterChunks(ctx, chunks)
+ return renderChunksXML(ctx, docID, chunks, anchorMeta, notice)
+}
+
+// renderChunksXML renders deep-read passages without the sufficiency filter. It
+// is for the places whose result set IS the evidence the model is being asked to
+// judge - a page that has already been decided must be shown whole, so the
+// filter has no business shortening it.
+func renderChunksXML(ctx context.Context, docID string, chunks []runtime.RetrievalChunk, anchorMeta, notice string) string {
// Deep-read passages are citable too: stamp the same [ID:n] handle the locate
// tools use, so a fact read from the full text can be cited.
reg := evidenceRegistryFrom(ctx)
diff --git a/internal/agentic_rag/tool_list_chunks.go b/internal/agentic_rag/tool_list_chunks.go
index ba0b934db1..33678c6641 100644
--- a/internal/agentic_rag/tool_list_chunks.go
+++ b/internal/agentic_rag/tool_list_chunks.go
@@ -39,12 +39,15 @@ const listChunksToolName = "list_chunks"
const listChunksToolDescription = `Read the full original text of SELECTED chunks from ONE dataset document, in reading order (Deep Read). Coverage is exactly what you request: the anchor_chunk_ids you pass, expanded by number_neighbors when > 0 — not necessarily the whole document. ANCHOR-DRIVEN: you must name chunk_ids seen in locate output.
-Use this AFTER grep_chunks / search_chunks / search_bm25_chunks locate documents: pass their chunk_ids as anchor_chunk_ids to read the complete chunk text — including surrounding context that match snippets and graph triples omit. Deep-reading is MANDATORY before answering and before issuing another search: match snippets and graph triples never carry enough to judge relevance or to cite. Cover a document by chaining anchored calls — each reply's doc_chunks_total tells you what is still uncovered — until the span you need is fetched.
+Use this AFTER grep_chunks / search_chunks / search_bm25_chunks locate documents: pass their chunk_ids as anchor_chunk_ids to read the complete chunk text — including surrounding context that match snippets and graph triples omit. Cover a document by chaining anchored calls — each reply's doc_chunks_total tells you what is still uncovered — until the span you need is fetched.
+
+The FIRST call for a set of anchors returns, for each anchor, its COMPILED statements when that chunk has any — one atomic fact per line, the verbatim quote it was compiled from, and a ref handle for citing the source chunk — and the chunk's original text when it has none. That is the whole of what these chunks state, so judge on it directly: if the statements already state the fact you need, answer from them and cite their ref handles; if not, or you need the surrounding context, call again with raw=true to read the original text of every anchor. Match snippets and graph triples never carry enough to cite on their own.
## Input
- doc_id: REQUIRED — the document id to read (use the doc_id value from locate-tool output).
- anchor_chunk_ids: REQUIRED — one or more chunk_ids from locate output (at most 20). The read covers these chunks (and their neighborhoods, see below).
- number_neighbors (optional, default 0): 0 fetches ONLY the anchored chunks themselves; N>0 centers a window of N chunks before AND after EVERY anchor (overlapping windows merge).
+- raw (optional, default false): false returns each anchor as its compiled statements, or as its text when it has none (see above); true reads the original text of every anchor.
## Output (XML)
Root <chunks> element carries doc_id, fetched, anchored_chunk_ids and number_neighbors; whenever number_neighbors > 0 it also carries doc_chunks_total — the document's total readable-chunk count — so you can tell whether the returned window covered the entire document. Each chunk carries chunk_id/doc_id/page_num/chunk_index/dataset_id/doc_name plus a <content> element with the FULL original text in reading order; doc_name is the doc engine's document name (the docnm field — typically the source file name such as 66090.md). Graph relation/entity chunks are excluded.`
@@ -57,7 +60,11 @@ type listChunksArgs struct {
// question alone, because a necessary middle step of a multi-hop run is
// often irrelevant to the final question while being exactly what the step
// needed. Optional: omitted means the filter falls back to the question.
- Intent string `json:"intent,omitempty"`
+ Intent string `json:"intent,omitempty"`
+ // Raw opts out of the claim-first gate: the caller that has already been
+ // shown the compiled statements of these chunks and still needs the passage
+ // asks again with raw=true.
+ Raw bool `json:"raw,omitempty"`
AnchorChunkIDs []string `json:"anchor_chunk_ids"`
NumberNeighbors int `json:"number_neighbors,omitempty"`
}
@@ -130,6 +137,11 @@ func (l *ListChunksTool) Info(_ context.Context) (*schema.ToolInfo, error) {
"intent": {
"type": "string",
"description": "REQUIRED: what information THIS call needs, in one sentence, e.g. the first name of Sarah Polk's mother, needed to build the final name. Each returned passage is kept or dropped by whether it serves this stated need, so name the fact you are looking for - not the search terms, and not 'relevant information'."
+ },
+ "raw": {
+ "type": "boolean",
+ "description": "false (default): the first call for these anchors returns their COMPILED statements (atomic facts + verbatim quotes + ref handles) instead of the passage. true: read the original text - use it after those statements did not state the fact you need.",
+ "default": false
}
},
"required": ["doc_id", "anchor_chunk_ids", "intent"]
@@ -180,6 +192,31 @@ func (l *ListChunksTool) invokableRun(ctx context.Context, argumentsInJSON strin
listChunksMaxAnchors, len(anchors))
}
+ // Claim-first: a chunk that carries compiled statements is represented by
+ // them, so the read returns those statements instead of the passage. A chunk
+ // that carries none is represented by its text, in the SAME answer - one call
+ // is always enough for "claims where they exist, the chunk itself where they
+ // do not". A caller that finds the statements insufficient re-calls with
+ // raw=true and gets the passage.
+ var claimBlock string
+ readAnchors := anchors
+ if !args.Raw {
+ block, covered := compiledEvidenceGate(ctx, anchors)
+ if block != "" {
+ claimBlock = block
+ readAnchors = anchorsWithout(anchors, covered)
+ if len(readAnchors) == 0 {
+ return claimBlock, nil
+ }
+ }
+ } else {
+ // Paired with the gate's own line, this is the hit/miss ratio of the
+ // claim-first rule: gated reads that were answered from the statements
+ // never reach here, gated reads that were not come back with raw=true.
+ common.InfoCtx(ctx, "agentic_rag: compiled evidence gate overridden",
+ zap.Strings("chunks", anchors))
+ }
+
svc := runtime.GetGrepService()
tenantID := l.tenantID
if svc == nil || tenantID == "" {
@@ -219,9 +256,9 @@ func (l *ListChunksTool) invokableRun(ctx context.Context, argumentsInJSON strin
switch {
case directAnchorsOnly:
- selectIDs = dedupStrings(anchors)
+ selectIDs = dedupStrings(readAnchors)
anchorMeta = fmt.Sprintf(` anchored_chunk_ids=%q number_neighbors="0"`,
- xmlEscape(strings.Join(anchors, ",")))
+ xmlEscape(strings.Join(readAnchors, ",")))
default:
index, err := dr.ListDocumentChunkIndex(ctx, scope)
@@ -238,7 +275,7 @@ func (l *ListChunksTool) invokableRun(ctx context.Context, argumentsInJSON strin
}
var missing []string
mark := make([]bool, len(index))
- for _, a := range anchors {
+ for _, a := range readAnchors {
pos, ok := posOf[a]
if !ok {
missing = append(missing, a)
@@ -249,7 +286,7 @@ func (l *ListChunksTool) invokableRun(ctx context.Context, argumentsInJSON strin
}
}
anchorMeta = fmt.Sprintf(` anchored_chunk_ids=%q doc_chunks_total="%d" number_neighbors="%d"`,
- xmlEscape(strings.Join(anchors, ",")), len(index), nb)
+ xmlEscape(strings.Join(readAnchors, ",")), len(index), nb)
// FAIL FAST on unresolved anchors: an anchor absent from this
// document means the caller cited an id that does not exist here, so
// there is nothing trustworthy to expand a window around. Report it
@@ -261,10 +298,10 @@ func (l *ListChunksTool) invokableRun(ctx context.Context, argumentsInJSON strin
// verified.
if len(missing) > 0 {
common.WarnCtx(ctx, "agentic_rag: list_chunks unresolved anchors",
- zap.String("doc_id", docID), zap.Strings("anchors", anchors),
+ zap.String("doc_id", docID), zap.Strings("anchors", readAnchors),
zap.Strings("missing", missing))
- return formatChunksXML(ctx, docID, nil, anchorMeta,
- unresolvedNotice(missing, len(missing) == len(anchors))), nil
+ return claimBlock + formatChunksXML(ctx, docID, nil, anchorMeta,
+ unresolvedNotice(missing, len(missing) == len(readAnchors))), nil
}
for i, m := range mark {
if m {
@@ -292,12 +329,13 @@ func (l *ListChunksTool) invokableRun(ctx context.Context, argumentsInJSON strin
// caller (the model) needs to SEE the outcome to judge it. Report it
// in-band instead.
common.WarnCtx(ctx, "agentic_rag: list_chunks found no text for the anchors",
- zap.String("doc_id", docID), zap.Strings("anchors", anchors))
- return chunksXMLNoText(docID, anchorMeta, len(selectIDs)), nil
+ zap.String("doc_id", docID), zap.Strings("anchors", readAnchors))
+ return claimBlock + chunksXMLNoText(docID, anchorMeta, len(selectIDs)), nil
}
common.DebugCtx(ctx, "agentic_rag: list_chunks result",
zap.Int("anchors", len(anchors)),
+ zap.Int("read_as_text", len(readAnchors)),
zap.Int("neighbors", nb),
zap.Bool("direct_anchors_only", directAnchorsOnly),
zap.Int("selected", len(selectIDs)),
@@ -307,7 +345,26 @@ func (l *ListChunksTool) invokableRun(ctx context.Context, argumentsInJSON strin
// Only the nb=0 path reaches here: the nb>0 path returns early on
// unresolved anchors, and its empty case is reported by chunksXMLNoText.
- return formatChunksXML(ctx, docID, chunks, anchorMeta, ""), nil
+ return claimBlock + formatChunksXML(ctx, docID, chunks, anchorMeta, ""), nil
+}
+
+// anchorsWithout returns the anchors that are not in keep, preserving order.
+func anchorsWithout(anchors, keep []string) []string {
+ if len(keep) == 0 {
+ return anchors
+ }
+ kept := make(map[string]struct{}, len(keep))
+ for _, id := range keep {
+ kept[id] = struct{}{}
+ }
+ out := make([]string, 0, len(anchors))
+ for _, a := range anchors {
+ if _, ok := kept[a]; ok {
+ continue
+ }
+ out = append(out, a)
+ }
+ return out
}
// resolveDocDatasetID returns the knowledge-base id that owns the given document,
diff --git a/internal/agentic_rag/tool_navigate_structure.go b/internal/agentic_rag/tool_navigate_structure.go
index cedb0fc622..9311ae9866 100644
--- a/internal/agentic_rag/tool_navigate_structure.go
+++ b/internal/agentic_rag/tool_navigate_structure.go
@@ -15,22 +15,14 @@
package agentic_rag
-// navigate_structure: drill into ONE document's compiled structure (the
+// navigate_structure: drill into documents' compiled structure (the
// entity/relation outline built at compile time) and return a query-focused
// <structure_navigation> outline with chunk pointers the model can feed to
// list_chunks.
//
-// Two selection strategies, in priority order:
-//
-// 1. CLAIM recall (flat): the document's claim rows (entity_type_kwd="claim")
-// are atomic propositions carrying their own verbatim evidence, recalled
-// with a hybrid lexical + dense leg fused by reciprocal rank. A hit is
-// already the answer material, so it REPLACES the drill instead of
-// layering on top of it: descending the tree can only re-derive what the
-// claim states, and every descent step is another chance to prune the
-// branch holding the answer.
-// 2. TREE drill-down (fallback): the compiled structure is drilled with a
-// keyword-relevance beam for documents without claim hits.
+// The structure is drilled with a keyword-relevance beam. Claim rows are NOT
+// searched here: retrieval in this package is chunk retrieval, and a chunk's
+// claims are fetched by the chunk, never by querying the claim rows.
//
// Typical use: call navigate_tree first to route to a document, take its
// doc_id, then call navigate_structure with that doc_id to see where the answer
@@ -42,9 +34,7 @@ import (
"fmt"
"slices"
"sort"
- "strconv"
"strings"
- "unicode"
einotool "github.com/cloudwego/eino/components/tool"
"github.com/cloudwego/eino/schema"
@@ -55,15 +45,14 @@ import (
"ragflow/internal/engine"
enginetypes "ragflow/internal/engine/types"
"ragflow/internal/service/nav"
- "ragflow/internal/tokenizer"
)
const navigateStructureToolName = "navigate_structure"
-const navigateStructureToolDescription = `Drill into ONE document's COMPILED STRUCTURE (the entity/relation outline built at compile time) and return a query-focused outline of where the answer sits, with chunk pointers you can pass to list_chunks to deep-read.
-Call it with just a query: it routes the query over the datasets' compiled navigation trees itself and returns the compiled CLAIM evidence of the best-matching documents, so no prior navigate_tree call is needed. To drill ONE document the model already chose, pass the doc_id from a <tree_navigation> result instead; that path returns the document's internal structure (entities and how they relate).
-Returns an XML <structure_navigation> document: one <doc> element per readable structure, each with a <structure> outline. Outline lines are either claim lines "- [claim] <statement> | Evidence: \"<verbatim quote>\" [chunks: c1] ref=3" (the document's compiled atomic propositions recalled for your query, each carrying its own evidence and the handle to cite it by) or structure lines "- name (type): description [chunks: c1,c2]". When claims hit they replace the structure descent outright. Feed the chunk pointers to list_chunks (anchor_chunk_ids).
-An empty result (<structure_navigation count="0" error="...">) means this document has NO compiled structure or claims of the requested kind - the error attribute says which: "route first with navigate_tree" (no doc_id), or "no compiled structure for this kind" (absent in THAT document - fall back to grep_chunks / search_*_chunks; the verdict is per document, so the tool stays available for other documents).`
+const navigateStructureToolDescription = `Drill into documents' COMPILED STRUCTURE (the entity/relation outline built at compile time) and return a query-focused outline of where the answer sits, with chunk pointers you can pass to list_chunks to deep-read.
+Call it with just a query: it routes the query over the datasets' compiled navigation trees itself, so no prior navigate_tree call is needed. To drill ONE document the model already chose, pass the doc_id from a <tree_navigation> result; that path returns the document's internal structure (entities and how they relate).
+Returns an XML <structure_navigation> document: one <doc> element per readable structure, each with a <structure> outline of lines "- name (type): description [chunks: c1,c2]". Feed the chunk pointers to list_chunks (anchor_chunk_ids).
+An empty result (<structure_navigation count="0" error="...">) means the routed documents have NO compiled structure of the requested kind - the error attribute says which: "route first with navigate_tree" (no doc_id), or "no compiled structure for this kind" (absent in THOSE documents - fall back to grep_chunks / search_*_chunks; the verdict is per document, so the tool stays available for other documents).`
// navigateStructureArgs is the JSON the model sends into InvokableRun.
type navigateStructureArgs struct {
@@ -104,63 +93,11 @@ const (
structMaxChunks = 4 // cap on chunk snippets returned in the outline
)
-// Claim/evidence leg (mirroring the harness _STRUCT_CLAIM_* limits).
-const (
- // navClaimRowType is the entity_type_kwd every compiler gives its evidence
- // rows. They deliberately carry no knowledge_graph_kwd and no type_kwd, so
- // they never show up as artifacts-tree nodes — this filter is the only way
- // to find them.
- navClaimRowType = "claim"
- // navClaimDocScope pins recall to doc-level rows: the KB-wide merged rows
- // written by the Build button carry a doc_id too, and without this filter
- // they would answer for a single document.
- navClaimDocScope = "doc"
- // navClaimTopN is the claim count rendered per document.
- navClaimTopN = 8
- // navClaimEvidenceChars caps the rendered verbatim quote. Generous on
- // purpose: a thin quote makes the answer stage judge the context
- // insufficient, and one extra re-search turn costs a full prompt — far more
- // than the extra characters.
- navClaimEvidenceChars = 1200
- // navClaimSufficientHits is the count at which the model may cite the claims
- // without deep-reading chunks. It is a count of RELEVANT hits: both legs
- // apply a relevance floor (below), because a leg with no floor returns a full
- // page for any document and a count over it states nothing.
- navClaimSufficientHits = 3
- // navClaimMinCoverage is the relevance floor applied to every recalled claim:
- // the share of the question's content tokens the claim text must contain.
- // The store's own defaults make a floor mandatory — full-text recall runs at
- // minimum_should_match 0% (one shared token is a hit) and KNN returns the
- // nearest neighbours at any distance — so without it every document yielded a
- // full page for every question. Measured failure: a Mike Tyson question
- // answered from a TV-series document.
- navClaimMinCoverage = 0.3
- // navClaimDenseSimilarity is the dense leg's cosine floor: the paraphrase leg
- // must not hand the fusion rows that are merely nearest, not near.
- navClaimDenseSimilarity = 0.4
- // navClaimMinDocs is the document diversity a sufficient recall needs. One
- // document's claims answer one hop; a multi-document question needs evidence
- // from more than one place, and a single-document recall is exactly what a
- // degenerate router returns for every question.
- navClaimMinDocs = 2
- // navClaimRRFK is the reciprocal-rank-fusion constant. RRF consumes ranks
- // only, so the two legs' scores never have to be comparable — their FLOORS
- // are what decides membership.
- navClaimRRFK = 60
- // navClaimPool is the per-leg candidate pool (mirroring limit = max(top_n, 32)).
- navClaimPool = 32
- // navQueryRouteDocs bounds the documents a query-only call investigates. The
- // two-step contract (navigate_tree -> navigate_structure) is a real adoption
- // barrier: a query-only call removes it, at the cost of claiming over a few
- // routed documents instead of one chosen by the model.
- navQueryRouteDocs = 3
- // navClaimPrefetchTopN bounds the claims the PIPELINE recalls before the
- // loop. It is both a cost bound and an accuracy bound: the block is the whole
- // prompt of the sufficient-claims answer and also what decides that verdict,
- // so a cap below navClaimSufficientHits x navClaimMinDocs could never
- // terminate early.
- navClaimPrefetchTopN = 3 * navClaimTopN
-)
+// navQueryRouteDocs bounds the documents a query-only call investigates. The
+// two-step contract (navigate_tree -> navigate_structure) is a real adoption
+// barrier: a query-only call removes it, at the cost of drilling a few routed
+// documents instead of one chosen by the model.
+const navQueryRouteDocs = 3
// navStructureRoute resolves candidate doc_ids for a query when the caller
// supplied no doc_id. It is the same navigation-tree router navigate_tree uses,
@@ -220,58 +157,6 @@ type chunkWithText struct {
text string
}
-// claimHit is one recalled claim row: an atomic proposition plus its verbatim
-// evidence. chunkID is the FIRST source chunk id — the pointer the model feeds
-// to list_chunks when it needs the surrounding passage. docID names the document
-// the claim was compiled from, which is what makes document diversity checkable.
-type claimHit struct {
- docID string
- chunkID string
- name string
- description string
- quote string
- score float64
-}
-
-// claimReader is the OPTIONAL claim-recall capability of a structureReader. A
-// reader that does not implement it simply has no claim leg, and the drill-down
-// stays the only strategy (the pre-claim behavior).
-type claimReader interface {
- // ReadClaims recalls claim rows of the given compile kinds, hybrid (lexical +
- // dense when qvec is non-empty) fused by reciprocal rank, and returns at most
- // limit hits that clear the relevance floor. A nil/empty docIDs spans the
- // whole dataset, which is what the pre-loop recall uses: it needs no document
- // choice.
- ReadClaims(ctx context.Context, tenantID, kbID string, docIDs, kinds []string, text string, qvec []float64, limit int) ([]claimHit, error)
-}
-
-// claimQueryVector encodes the drill query for the claim dense leg, using the
-// embedder the nav service already resolved for this tenant — the same model
-// that wrote the claim rows' q_<dim>_vec columns.
-//
-// It reads that embedder through the nav service rather than through an injected
-// function: this package already depends on nav for routing, and the service is
-// where tenant-model resolution lives, so a second wiring point in the server
-// bootstrap would only duplicate it. A missing service, an unresolvable model or
-// a panicking encoder all yield nil, which leaves the leg out and recall running
-// on the lexical leg alone — a misconfigured embedder must never take a tool
-// call down.
-func claimQueryVector(ctx context.Context, tenantID, text string) (vec []float64) {
- svc := nav.GetNavService()
- if svc == nil || tenantID == "" || strings.TrimSpace(text) == "" {
- return nil
- }
- defer func() {
- if recover() != nil {
- vec = nil
- }
- }()
- if v := svc.EncodeQueryVector(ctx, tenantID, text); len(v) > 0 {
- return v
- }
- return nil
-}
-
// structureRow is one compiled-structure row: the doc-store fields the structure
// reader reads.
type structureRow struct {
@@ -340,261 +225,6 @@ func (engineStructureReader) ReadStructure(ctx context.Context, tenantID, kbID,
return rows, nil
}
-// ReadClaims is the claim leg: two independent reads over the claim rows of the
-// requested documents — a full-text leg on the tokenized content (exact /
-// proper-noun recall) and a KNN leg on the claim's OWN vector (paraphrase
-// recall) — fused by reciprocal rank. Each leg is one store round-trip.
-//
-// A leg that fails is dropped rather than propagated: without an embedder the
-// lexical leg alone still recalls claims, and a scope with no compiled claims
-// legitimately returns nothing.
-//
-// The RELEVANCE FLOOR is applied here, in Go, to the fused result. The store
-// cannot enforce it: `minimum_should_match` on a multi-field query_string is
-// silently ignored (measured: "100%" still returned 1950 rows for a two-term
-// query), and a KNN similarity cut would only cover the dense leg. Without a
-// floor every document yielded a full page for every question, which is how a
-// Mike Tyson question was answered from a TV-series document.
-func (engineStructureReader) ReadClaims(ctx context.Context, tenantID, kbID string, docIDs, kinds []string, text string, qvec []float64, limit int) ([]claimHit, error) {
- de := engine.Get()
- if de == nil || strings.TrimSpace(text) == "" {
- return nil, nil
- }
- // The caller owns the cap: the per-document tool path asks for navClaimTopN,
- // while the pre-loop recall asks for the corpus-wide budget
- // (navClaimPrefetchTopN). Clamping every caller to the per-document count
- // silently cut that budget to one page, which is too few claims to satisfy
- // the sufficiency gate's document-diversity rule.
- if limit <= 0 {
- limit = navClaimTopN
- }
- pool := limit
- if pool < navClaimPool {
- pool = navClaimPool
- }
- filter := map[string]interface{}{
- "entity_type_kwd": []string{navClaimRowType},
- "scope_kwd": []string{navClaimDocScope},
- }
- if len(docIDs) > 0 {
- filter["doc_id"] = docIDs
- }
- if len(kinds) > 0 {
- filter["compile_kwd"] = kinds
- }
-
- leg := func(exprs []interface{}) []claimHit {
- res, err := de.Search(ctx, &enginetypes.SearchRequest{
- IndexNames: []string{indexNameFor(tenantID, "")},
- KbIDs: []string{kbID},
- SelectFields: []string{
- "content_with_weight", "source_chunk_ids", "entity_type_kwd", "compile_kwd", "doc_id",
- },
- Filter: filter,
- MatchExprs: exprs,
- Limit: pool,
- IncludeUnavailable: true,
- })
- if err != nil {
- common.DebugCtx(ctx, "claim recall: leg failed",
- zap.Strings("doc_ids", docIDs), zap.Error(err))
- return nil
- }
- hits := make([]claimHit, 0, len(res.Chunks))
- for _, row := range res.Chunks {
- if h, ok := parseClaimHit(row); ok {
- hits = append(hits, h)
- }
- }
- return hits
- }
-
- var denseLeg, textLeg []claimHit
- if len(qvec) > 0 {
- denseLeg = leg([]interface{}{&enginetypes.MatchDenseExpr{
- VectorColumnName: fmt.Sprintf("q_%d_vec", len(qvec)),
- EmbeddingData: qvec,
- EmbeddingDataType: "float",
- DistanceType: "cosine",
- TopN: pool,
- ExtraOptions: map[string]interface{}{"similarity": navClaimDenseSimilarity},
- }})
- }
- textLeg = leg([]interface{}{&enginetypes.MatchTextExpr{
- Fields: []string{"content_ltks", "content_sm_ltks"},
- MatchingText: text,
- TopN: pool,
- }})
- if len(denseLeg) == 0 && len(textLeg) == 0 {
- return nil, nil
- }
-
- fused := rrfFuse(navClaimRRFK, pool, denseLeg, textLeg)
- question := claimTokens(text)
- out := make([]claimHit, 0, len(fused))
- for _, h := range fused {
- if claimCoverage(question, h) < navClaimMinCoverage {
- continue
- }
- out = append(out, h)
- if len(out) >= limit {
- break
- }
- }
- return out, nil
-}
-
-// parseClaimHit turns one claim row into a hit. A row that is not a usable
-// claim — bad payload, unnamed, or carrying no chunk pointer — is dropped: a
-// claim the model cannot open is not an answer anchor.
-func parseClaimHit(row map[string]interface{}) (claimHit, bool) {
- payload, ok := decodeJSONObject(contentWithWeightFromRaw(row))
- if !ok {
- return claimHit{}, false
- }
- name := strings.TrimSpace(stringFromAny(payload["name"]))
- if name == "" {
- return claimHit{}, false
- }
- ids := navStringList(row["source_chunk_ids"])
- if len(ids) == 0 {
- ids = navStringList(payload["source_chunk_ids"])
- }
- if len(ids) == 0 {
- return claimHit{}, false
- }
- docID := strings.TrimSpace(fmt.Sprint(row["doc_id"]))
- if docID == "<nil>" {
- docID = ""
- }
- return claimHit{
- docID: docID,
- chunkID: ids[0],
- name: name,
- description: strings.TrimSpace(stringFromAny(payload["description"])),
- quote: firstEvidenceQuote(payload["evidence"]),
- score: floatFromMap(row, "_score"),
- }, true
-}
-
-// claimTokens returns the set of content tokens of a question, used as the
-// denominator of the claim relevance floor. It uses the corpus tokenizer when
-// the pool is up (same analyzer the claim text was indexed with) and falls back
-// to a rune-level splitter, so a deployment without the analyzer still gets a
-// relevance floor instead of none. Single-rune tokens are dropped: they are
-// stopwords in alphabetic languages.
-func claimTokens(text string) map[string]struct{} {
- tokens := map[string]struct{}{}
- if tok, err := tokenizer.Tokenize(text); err == nil {
- for _, t := range strings.Fields(strings.ToLower(tok)) {
- if len([]rune(t)) >= 2 {
- tokens[t] = struct{}{}
- }
- }
- }
- if len(tokens) > 0 {
- return tokens
- }
- for _, t := range strings.FieldsFunc(strings.ToLower(text), func(r rune) bool {
- return !unicode.IsLetter(r) && !unicode.IsDigit(r)
- }) {
- if len([]rune(t)) >= 2 {
- tokens[t] = struct{}{}
- }
- }
- return tokens
-}
-
-// claimCoverage is the share of the question's content tokens this claim states
-// or quotes. It is the floor's only input: a claim that does not repeat any of
-// the question's terms cannot be evidence for it, however highly the store
-// ranked it (ranks are relative, so the top hit of an irrelevant document is
-// still the top hit).
-func claimCoverage(question map[string]struct{}, c claimHit) float64 {
- if len(question) == 0 {
- return 1
- }
- text := c.name + " " + c.description + " " + c.quote
- claim := claimTokens(text)
- if len(claim) == 0 {
- return 0
- }
- matched := 0
- for t := range question {
- if _, ok := claim[t]; ok {
- matched++
- }
- }
- return float64(matched) / float64(len(question))
-}
-
-// firstEvidenceQuote returns the first non-empty verbatim quote of a claim's
-// evidence list.
-func firstEvidenceQuote(v any) string {
- list, _ := v.([]any)
- for _, item := range list {
- ev, ok := item.(map[string]any)
- if !ok {
- continue
- }
- if q := strings.TrimSpace(stringFromAny(ev["quote"])); q != "" {
- return q
- }
- }
- return ""
-}
-
-// rrfFuse merges retrieval legs by RECIPROCAL RANK (k=60 by default). Ranks
-// only, so no similarity threshold has to be calibrated across legs with
-// incomparable score scales; a hit keeps its best raw score for diagnostics.
-func rrfFuse(k, limit int, legs ...[]claimHit) []claimHit {
- if k <= 0 {
- k = navClaimRRFK
- }
- type fused struct {
- hit claimHit
- score float64
- }
- byName := map[string]*fused{}
- var order []string
- for _, leg := range legs {
- for rank, h := range leg {
- key := strings.ToLower(strings.TrimSpace(h.name))
- if key == "" {
- continue
- }
- f, ok := byName[key]
- if !ok {
- byName[key] = &fused{hit: h, score: 1.0 / float64(k+rank+1)}
- order = append(order, key)
- continue
- }
- f.score += 1.0 / float64(k+rank+1)
- if h.score > f.hit.score {
- f.hit = h
- }
- }
- }
- if len(order) == 0 {
- return nil
- }
- sort.SliceStable(order, func(i, j int) bool {
- a, b := byName[order[i]], byName[order[j]]
- if a.score != b.score {
- return a.score > b.score
- }
- return order[i] < order[j]
- })
- if limit > 0 && len(order) > limit {
- order = order[:limit]
- }
- out := make([]claimHit, 0, len(order))
- for _, key := range order {
- out = append(out, byName[key].hit)
- }
- return out
-}
-
// navStringList coerces a doc-store column into a string slice: engines return
// []string, []interface{} or a bare string for the same field.
func navStringList(v any) []string {
@@ -623,54 +253,6 @@ func navStringList(v any) []string {
return nil
}
-// stringFromAny reads a scalar as a trimmed string, tolerating the numeric
-// types engines decode JSON numbers into.
-func stringFromAny(v any) string {
- switch x := v.(type) {
- case string:
- return x
- case fmt.Stringer:
- return x.String()
- case nil:
- return ""
- default:
- return fmt.Sprint(x)
- }
-}
-
-// claimOutlineLine renders one claim hit: the statement, its verbatim evidence,
-// and the chunk pointer that opens the surrounding passage.
-//
-// The line is ANSWER MATERIAL (a claim carries its own evidence, so the model is
-// expected to cite it instead of re-reading the document), which makes the
-// passage handle mandatory: an uncited claim line ships an answer the reference
-// payload cannot resolve. The handle is appended unquoted (`ref=3`) on purpose -
-// claim lines are rendered inside an escaped <structure> text node, where a
-// `ref="3"` attribute would arrive as `ref=&quot;3&quot;`.
-func claimOutlineLine(ctx context.Context, c claimHit) string {
- line := "- [claim] " + c.name
- if q := strings.TrimSpace(c.quote); q != "" {
- line += ` | Evidence: "` + snippetRunes(q, navClaimEvidenceChars) + `"`
- }
- if c.chunkID != "" {
- line += " [chunks: " + c.chunkID + "]"
- }
- if n := evidenceRegistryFrom(ctx).Stamp(c.chunkID); n >= 0 {
- line += " ref=" + strconv.Itoa(n)
- }
- return line
-}
-
-// claimOutline is the claim-first selection: the claims ARE the outline, so
-// nothing is drilled and no chunk snippet is loaded.
-func claimOutline(ctx context.Context, claims []claimHit) string {
- lines := make([]string, 0, len(claims))
- for _, c := range claims {
- lines = append(lines, claimOutlineLine(ctx, c))
- }
- return strings.Join(lines, "\n")
-}
-
// indexNameFor resolves the document/structure search index: the tenant's
// default "ragflow_<tenant_id>" unless a tenant overrides index_name.
func indexNameFor(tenantID, configured string) string {
@@ -1127,36 +709,10 @@ func navigateStructures(ctx context.Context, tenantID string, query string, docI
return strings.Join(parts, "\n")
}
-// navigateClaimsForQuery is the query-only path: it claims over the ROUTED
-// documents and nothing else. No tree read, no drill — a document without claim
-// hits contributes nothing, because this path exists to surface compiled
-// evidence, not to duplicate what the explicit doc_id path already does.
-// limit caps the TOTAL claims rendered across documents (0 = uncapped, the
-// model-invoked behavior). Round-robin across documents rather than first-doc
-// order, so a tight cap still covers every routed document.
-func navigateClaimsForQuery(ctx context.Context, tenantID, query string, docIDs, datasetIDs []string, kind string, limit int, reader structureReader) (string, int) {
- docs, perDoc := recallClaimsForQuery(ctx, tenantID, query, docIDs, datasetIDs, kind, limit, reader)
- var segs []string
- for i, claims := range perDoc {
- if len(claims) == 0 {
- continue
- }
- segs = append(segs, structureDocSegment(docs[i], len(segs)+1, 0, 0, claimOutline(ctx, claims)))
- }
- if len(segs) == 0 {
- return "", 0
- }
- parts := append([]string{
- fmt.Sprintf(`<structure_navigation count="%d" query="%s" kind="%s">`, len(segs), xmlEscape(query), xmlEscape(kind)),
- }, segs...)
- parts = append(parts, "</structure_navigation>")
- return strings.Join(parts, "\n"), len(segs)
-}
-
-// claimKindList flattens the requested compile kinds into the sorted filter the
-// claim reader takes. Claim rows are selected by compile_kwd, so every claim read
-// needs it — the per-document tool path and the corpus-wide pre-loop recall alike.
-func claimKindList(kinds map[string]bool) []string {
+// kindListOf flattens the requested structure kinds into the sorted list the
+// structure reader parses. Rows are selected by compile_kwd, so every read needs
+// it.
+func kindListOf(kinds map[string]bool) []string {
out := make([]string, 0, len(kinds))
for k := range kinds {
out = append(out, k)
@@ -1165,78 +721,14 @@ func claimKindList(kinds map[string]bool) []string {
return out
}
-// recallClaimsForQuery runs the claim leg over the given documents and returns
-// the documents that hit, aligned with their claims. limit caps the TOTAL claims
-// (0 = uncapped); the trim is round-robin, so a tight budget still touches every
-// document instead of being spent on the first one.
-//
-// It is the retrieval half of the per-document tool path; the pre-loop recall
-// reads corpus-wide instead (see recallClaimsAcrossDatasets).
-func recallClaimsForQuery(ctx context.Context, tenantID, query string, docIDs, datasetIDs []string, kind string, limit int, reader structureReader) ([]string, [][]claimHit) {
- kindList := claimKindList(structureKindsFor(kind))
-
- var perDoc [][]claimHit
- var docs []string
- for _, did := range docIDs {
- claims := recallClaimsForDoc(ctx, tenantID, query, did, kindList, datasetIDs, reader)
- if len(claims) == 0 {
- continue
- }
- perDoc = append(perDoc, claims)
- docs = append(docs, did)
- }
- if len(perDoc) == 0 {
- return nil, nil
- }
- if limit > 0 {
- perDoc = trimClaimsRoundRobin(perDoc, limit)
- }
- return docs, perDoc
-}
-
-// trimClaimsRoundRobin keeps at most limit claims in total, taking one per
-// document per round so no document monopolizes a small budget.
-func trimClaimsRoundRobin(perDoc [][]claimHit, limit int) [][]claimHit {
- if limit <= 0 {
- return perDoc
- }
- out := make([][]claimHit, len(perDoc))
- total := 0
- for round := 0; total < limit; round++ {
- progressed := false
- for i := range perDoc {
- if round >= len(perDoc[i]) {
- continue
- }
- out[i] = append(out[i], perDoc[i][round])
- total++
- progressed = true
- if total >= limit {
- break
- }
- }
- if !progressed {
- break
- }
- }
- return out
-}
-
// readStructureDocCore reads ONE document's compiled structure of the requested
// kind and drills it toward the query. It returns the rendered outline, the
// entity/relation counts, and whether the document carried a structure at all.
-//
-// Claim recall runs FIRST and, when it hits, replaces the drill entirely: the
-// claims carry their own evidence, so descending the tree could only re-derive
-// what they already state.
func readStructureDocCore(ctx context.Context, tenantID, query, docID string, kinds map[string]bool, datasetIDs []string, reader structureReader) (string, int, int, bool) {
if query == "" || docID == "" {
return "", 0, 0, false
}
- kindList := claimKindList(kinds)
- if claims := recallClaimsForDoc(ctx, tenantID, query, docID, kindList, datasetIDs, reader); len(claims) > 0 {
- return claimOutline(ctx, claims), 0, 0, true
- }
+ kindList := kindListOf(kinds)
var nodes []structureNode
var rels []structureRel
@@ -1264,41 +756,6 @@ func readStructureDocCore(ctx context.Context, tenantID, query, docID string, ki
return renderTocDrilldown(query, nodes, rels, loader), len(nodes), len(rels), true
}
-// recallClaimsForDoc runs the claim leg across the document's datasets, keeping
-// the fused rank order. Hits are deduped by claim NAME (two datasets cannot both
-// hold the same document, but a reader may return a claim twice) — deliberately
-// NOT by chunk id: several distinct claims commonly come from one chunk, and
-// dropping all but the first would throw evidence away.
-func recallClaimsForDoc(ctx context.Context, tenantID, query, docID string, kindList, datasetIDs []string, reader structureReader) []claimHit {
- cr, ok := reader.(claimReader)
- if !ok {
- return nil
- }
- qvec := claimQueryVector(ctx, tenantID, query)
- var out []claimHit
- seen := map[string]bool{}
- for _, kbID := range datasetIDs {
- hits, err := cr.ReadClaims(ctx, tenantID, kbID, []string{docID}, kindList, query, qvec, navClaimTopN)
- if err != nil {
- common.DebugCtx(ctx, "navigate_structure: claim recall failed",
- zap.String("kb_id", kbID), zap.String("doc_id", docID), zap.Error(err))
- continue
- }
- for _, h := range hits {
- key := strings.ToLower(strings.TrimSpace(h.name))
- if h.chunkID == "" || key == "" || seen[key] {
- continue
- }
- seen[key] = true
- out = append(out, h)
- if len(out) >= navClaimTopN {
- return out
- }
- }
- }
- return out
-}
-
// structureNodeLoader fetches chunk texts by id for the drill-down snippet pass.
func structureNodeLoader(ctx context.Context, tenantID string, ids []string) []chunkWithText {
de := engine.Get()
@@ -1458,7 +915,7 @@ func (g *NavigateStructureTool) Info(_ context.Context) (*schema.ToolInfo, error
},
"doc_id": {
"type": "string",
- "description": "OPTIONAL: the document to drill, taken from a navigate_tree <doc doc_id> result. Omit it to route the query yourself and get compiled claim evidence from the best-matching documents directly (no navigate_tree call needed)."
+ "description": "OPTIONAL: the document to drill, taken from a navigate_tree <doc doc_id> result. Omit it to route the query yourself and drill the best-matching documents' structure directly (no navigate_tree call needed)."
},
"doc_ids": {
"type": "array",
@@ -1500,209 +957,6 @@ func (g *NavigateStructureTool) InvokableRun(ctx context.Context, argumentsInJSO
return guardedToolRun(ctx, navigateStructureToolName, g.invokableRun, argumentsInJSON)
}
-// claimPrefetch is the ONE claim recall a turn performs before its loop, with
-// the verdict the run flow acts on.
-//
-// The recall exists because the compiled tools are injected rather than
-// declared, and a model that prefers one-step keyword search never calls them:
-// in the FRAMES runs every turn was offered navigate_structure and the tool was
-// called zero times. Evidence a model cannot be relied upon to request has to be
-// retrieved by the pipeline, and the claim leg is exactly that - a flat read that
-// needs no document choice.
-//
-// The result is a CONTROL SIGNAL, not prompt text. Claims that answer the
-// question terminate the turn without reading a single raw chunk; a recall that
-// does not cover the question is dropped and the ordinary tool-driven
-// exploration runs. Nothing is appended to the system instruction: a block there
-// is re-billed on every model call of the turn, which is the cost this replaces.
-type claimPrefetch struct {
- docs []string
- claims []claimHit
- // evidence is the rendered claim block, carrying the [ID:n] handles its
- // source chunks were stamped with. It is rendered ONLY for a sufficient
- // recall, because rendering is what publishes handles: a discarded recall
- // must not leave handles behind for passages the model never saw.
- evidence string
- // sufficient is true when claimsAnswerQuestion accepted the recall.
- sufficient bool
-}
-
-// recallCompiledClaims recalls the bound datasets' claims for this turn's
-// question and decides whether they answer it themselves.
-func recallCompiledClaims(ctx context.Context, tenantID string, datasetIDs []string, messages []*schema.Message) claimPrefetch {
- question := strings.TrimSpace(lastUserQuestion(messages))
- if question == "" || len(datasetIDs) == 0 {
- return claimPrefetch{}
- }
- // A compiled dataset does not imply claims: trees, timelines and mindmaps all
- // carry compile_kwd but no evidence rows. Probing first keeps both retrieval
- // legs from running over a corpus that can only come back empty.
- if !claimRowsPresent(ctx, tenantID, datasetIDs) {
- common.DebugCtx(ctx, "agentic_rag: claim recall skipped",
- zap.Strings("datasets", datasetIDs),
- zap.String("reason", "no claim rows in the bound datasets"))
- return claimPrefetch{}
- }
- reader := getStructureReader()
- // NO document routing: the claim leg is a flat, corpus-wide read, which is
- // the whole reason it can run before the loop. Routing first (the nav-tree
- // KNN) reintroduced the document choice this path exists to avoid, and it
- // fails silently where it matters: a dataset whose nav tree holds a handful
- // of rows routes every question to the same one or two documents, and the
- // recall then dutifully returns their claims for every question.
- //
- // The turn's document scope, when set, is still honoured — as a filter on the
- // claim rows themselves.
- docScope, _ := resolveDocumentScope(ctx, nil)
- // A non-nil EMPTY scope means the turn allows no documents. The reader drops
- // its doc_id filter when the scope is empty, so passing one through would read
- // as "unrestricted" and recall the whole dataset — the opposite of the turn's
- // scope. Stop before the read instead.
- if docScope != nil && len(docScope) == 0 {
- common.DebugCtx(ctx, "agentic_rag: claim recall skipped",
- zap.Strings("datasets", datasetIDs),
- zap.String("reason", "no documents in the turn's scope"))
- return claimPrefetch{}
- }
- claims := recallClaimsAcrossDatasets(ctx, tenantID, datasetIDs, docScope, question, navClaimPrefetchTopN, reader)
-
- pf := claimPrefetch{claims: claims, docs: claimDocsInOrder(claims)}
- pf.sufficient = claimsAnswerQuestion(claims, len(pf.docs))
- if !pf.sufficient {
- common.InfoCtx(ctx, "agentic_rag: claim recall insufficient",
- zap.String("query", question),
- zap.Int("claims", len(claims)),
- zap.Int("docs", len(pf.docs)),
- zap.Int("required_claims", navClaimSufficientHits),
- zap.Int("required_docs", navClaimMinDocs))
- return pf
- }
- pf.evidence = claimEvidenceBlock(ctx, claims)
- common.InfoCtx(ctx, "agentic_rag: claim recall sufficient",
- zap.String("query", question),
- zap.Int("claims", len(claims)),
- zap.Strings("docs", pf.docs),
- zap.Int("evidence_bytes", len(pf.evidence)))
- return pf
-}
-
-// recallClaimsAcrossDatasets runs the flat claim recall over every bound
-// dataset and merges the results by claim name, keeping the first (best-ranked)
-// occurrence. Each dataset is one pair of legs; the corpus-wide read is what
-// makes the pre-loop recall independent of any document ranking.
-func recallClaimsAcrossDatasets(ctx context.Context, tenantID string, datasetIDs, docScope []string, query string, limit int, reader structureReader) []claimHit {
- cr, ok := reader.(claimReader)
- if !ok {
- return nil
- }
- kindList := claimKindList(structureKindsFor(""))
- qvec := claimQueryVector(ctx, tenantID, query)
-
- // Group the hits by source document, in ranked order, then take them
- // round-robin. A ranking's top-N is routinely dominated by ONE document, and
- // evidence from a single document cannot answer a multi-document question;
- // taking one claim per document per round is what makes the sufficiency
- // diversity check meaningful instead of accidental.
- var docOrder []string
- byDoc := map[string][]claimHit{}
- seen := map[string]struct{}{}
- for _, kbID := range datasetIDs {
- hits, err := cr.ReadClaims(ctx, tenantID, kbID, docScope, kindList, query, qvec, limit)
- if err != nil {
- common.DebugCtx(ctx, "claim recall: dataset read failed",
- zap.String("kb_id", kbID), zap.Error(err))
- continue
- }
- for _, h := range hits {
- key := strings.ToLower(strings.TrimSpace(h.name))
- if key == "" {
- continue
- }
- if _, dup := seen[key]; dup {
- continue
- }
- seen[key] = struct{}{}
- if _, ok := byDoc[h.docID]; !ok {
- docOrder = append(docOrder, h.docID)
- }
- byDoc[h.docID] = append(byDoc[h.docID], h)
- }
- }
- if len(docOrder) == 0 {
- return nil
- }
- groups := make([][]claimHit, 0, len(docOrder))
- for _, d := range docOrder {
- groups = append(groups, byDoc[d])
- }
- if limit > 0 {
- groups = trimClaimsRoundRobin(groups, limit)
- }
- out := make([]claimHit, 0, limit)
- for _, g := range groups {
- out = append(out, g...)
- }
- return out
-}
-
-// claimDocsInOrder returns the distinct source documents of a claim set, in
-// first-appearance order, for logging and evidence grouping.
-func claimDocsInOrder(claims []claimHit) []string {
- seen := map[string]struct{}{}
- out := make([]string, 0, len(claims))
- for _, c := range claims {
- if c.docID == "" {
- continue
- }
- if _, dup := seen[c.docID]; dup {
- continue
- }
- seen[c.docID] = struct{}{}
- out = append(out, c.docID)
- }
- return out
-}
-
-// claimsAnswerQuestion reports whether a recall covers the question well enough
-// to answer without reading any raw chunk.
-//
-// Two conditions, both necessary:
-// - COUNT: at least navClaimSufficientHits claims. Only meaningful because
-// recall already applied the relevance floor (navClaimMinCoverage), so a hit
-// states something about the question rather than sharing a stopword with it.
-// - DIVERSITY: claims from at least navClaimMinDocs documents. A page of
-// statements from ONE document answers at most one hop, and a single-document
-// recall is also exactly what a broken document ranking produces for every
-// question — the shape of the zero-score run this guard was added for.
-func claimsAnswerQuestion(claims []claimHit, docs int) bool {
- return len(claims) >= navClaimSufficientHits && docs >= navClaimMinDocs
-}
-
-// claimEvidenceBlock renders the recalled claims as answer material, one <doc>
-// element per source document so a multi-document question keeps its provenance
-// and the answer can name which document each fact came from.
-func claimEvidenceBlock(ctx context.Context, claims []claimHit) string {
- var b strings.Builder
- current := ""
- for _, c := range claims {
- if c.docID != current {
- if current != "" {
- b.WriteString("</doc>\n")
- }
- if c.docID != "" {
- fmt.Fprintf(&b, "<doc doc_id=\"%s\">\n", xmlEscape(c.docID))
- }
- current = c.docID
- }
- b.WriteString(claimOutlineLine(ctx, c))
- b.WriteString("\n")
- }
- if current != "" {
- b.WriteString("</doc>\n")
- }
- return strings.TrimRight(b.String(), "\n")
-}
-
func (g *NavigateStructureTool) invokableRun(ctx context.Context, argumentsInJSON string) (string, error) {
var args navigateStructureArgs
if err := json.Unmarshal([]byte(argumentsInJSON), &args); err != nil {
@@ -1741,13 +995,11 @@ func (g *NavigateStructureTool) invokableRun(ctx context.Context, argumentsInJSO
docIDs = []string{args.DocID}
}
// A doc_id is optional: with none, route the query ourselves so the tool is
- // usable in one call. Only CLAIMS are read on this path - the drill needs a
- // document the model actually chose.
+ // usable in one call.
routedByQuery := false
if len(docIDs) == 0 {
// The router ranks the whole bound corpus, so a turn restricted to a set
- // of documents must intersect here - the same rule the pre-loop recall
- // applies to its claim rows.
+ // of documents must intersect here.
docIDs = intersectDocumentScope(ctx, routeDocIDsForQuery(ctx, g.tenantID, text, datasetIDs, navQueryRouteDocs))
if len(docIDs) == 0 {
return navStructEmpty("route first with navigate_tree"), nil
@@ -1758,23 +1010,6 @@ func (g *NavigateStructureTool) invokableRun(ctx context.Context, argumentsInJSO
docIDs = docIDs[:10]
}
- if routedByQuery {
- // 0 = uncapped: the model asked for this call, so its result lands in the
- // history once instead of being re-sent on every turn of the run. The
- // pipeline's own pre-loop recall applies its cap instead.
- out, docs := navigateClaimsForQuery(ctx, g.tenantID, text, docIDs, datasetIDs, args.Kind, 0, reader)
- common.InfoCtx(ctx, "agentic_rag: navigate_structure (query route)",
- zap.String("query", query),
- zap.Int("datasets", len(datasetIDs)),
- zap.Strings("routed", docIDs),
- zap.Int("docs_with_claims", docs),
- zap.Int("out_bytes", len(out)))
- if docs == 0 {
- return navStructEmpty("no claim hits in the routed documents; fall back to search_chunks or list_chunks"), nil
- }
- return out, nil
- }
-
out := navigateStructures(ctx, g.tenantID, text, docIDs, datasetIDs, args.Kind, reader)
// Per-call INFO: the tool-usage gate (kg_tool_calls) is read off the server
// log, so a graph tool that rendered a structure without leaving a line here
@@ -1783,6 +1018,7 @@ func (g *NavigateStructureTool) invokableRun(ctx context.Context, argumentsInJSO
zap.String("query", query),
zap.Int("datasets", len(datasetIDs)),
zap.Int("docs", len(docIDs)),
+ zap.Bool("routed_by_query", routedByQuery),
zap.Strings("names", docIDs),
zap.Int("out_bytes", len(out)))
return out, nil
diff --git a/internal/agentic_rag/tool_navigate_structure_test.go b/internal/agentic_rag/tool_navigate_structure_test.go
index 9fd0e10fa9..cb7dfb4f28 100644
--- a/internal/agentic_rag/tool_navigate_structure_test.go
+++ b/internal/agentic_rag/tool_navigate_structure_test.go
@@ -18,11 +18,8 @@ package agentic_rag
import (
"context"
"encoding/json"
- "sort"
"strings"
"testing"
-
- "github.com/cloudwego/eino/schema"
)
// fakeStructureReader returns canned compiled-structure rows per document.
@@ -41,75 +38,6 @@ func installFakeStructureReader(t *testing.T, r structureReader) {
t.Cleanup(func() { setStructureReader(prev) })
}
-// fakeClaimStructureReader is a structureReader that also carries a claim leg:
-// structure rows and claim hits are canned separately, so a test can prove
-// which strategy actually rendered the outline.
-type fakeClaimStructureReader struct {
- fakeStructureReader
- claims map[string][]claimHit
- // gotQVec captures the vector the tool handed to the claim leg.
- gotQVec *[]float64
-}
-
-func (f fakeClaimStructureReader) ReadClaims(_ context.Context, _ string, _ string, docIDs, _ []string, _ string, qvec []float64, limit int) ([]claimHit, error) {
- if f.gotQVec != nil {
- *f.gotQVec = qvec
- }
- // nil/empty docIDs is the corpus-wide read: every canned document, in stable
- // order so a test asserts on a deterministic page.
- requested := docIDs
- if len(requested) == 0 {
- for docID := range f.claims {
- requested = append(requested, docID)
- }
- sort.Strings(requested)
- }
- var hits []claimHit
- for _, docID := range requested {
- for _, h := range f.claims[docID] {
- if h.docID == "" {
- h.docID = docID
- }
- hits = append(hits, h)
- }
- }
- // Spread a cap across the requested documents rather than truncating in
- // document order: the ranked reader interleaves documents, so truncating by
- // document would model a reader this codebase does not have.
- if limit > 0 && len(hits) > limit {
- var byDoc [][]claimHit
- for _, docID := range requested {
- var group []claimHit
- for _, h := range hits {
- if h.docID == docID {
- group = append(group, h)
- }
- }
- if len(group) > 0 {
- byDoc = append(byDoc, group)
- }
- }
- var spread []claimHit
- for round := 0; len(spread) < limit; round++ {
- progressed := false
- for _, group := range byDoc {
- if round < len(group) {
- spread = append(spread, group[round])
- progressed = true
- if len(spread) == limit {
- break
- }
- }
- }
- if !progressed {
- break
- }
- }
- hits = spread
- }
- return hits, nil
-}
-
func claimRowJSON(name, desc, quote, chunkID string) structureRow {
content, _ := json.Marshal(map[string]any{
"type": "claim",
@@ -368,140 +296,6 @@ func TestBuildTocTreeAndOutline(t *testing.T) {
// --- Claim/evidence leg ---
-// TestNavigateStructureClaimLegReplacesDrill pins claim-first: a claim hit takes
-// over the selection, so the tree is NOT descended even when structure rows
-// exist for the same document.
-func TestNavigateStructureClaimLegReplacesDrill(t *testing.T) {
- installFakeStructureReader(t, fakeClaimStructureReader{
- fakeStructureReader: fakeStructureReader{byDoc: map[string][]structureRow{
- "d1": {graphRow()},
- }},
- claims: map[string][]claimHit{
- "d1": {{
- chunkID: "c9",
- name: "Paris is the capital of France",
- description: "capital city",
- quote: "Paris is the capital of France.",
- score: 0.8,
- }},
- },
- })
-
- out, err := NewNavigateStructureTool("tenant-1", []string{"kb1"}).
- InvokableRun(context.Background(), `{"query":"capital of France","doc_id":"d1"}`)
- if err != nil {
- t.Fatalf("InvokableRun: %v", err)
- }
- for _, want := range []string{
- `<structure_navigation count="1" query="capital of France" kind="">`,
- `<doc rank="1" doc_id="d1"`,
- // The outline is escaped as a whole, so the quote's own quotes ship as
- // &quot; (the same escaping the harness applies).
- `- [claim] Paris is the capital of France | Evidence: &quot;Paris is the capital of France.&quot; [chunks: c9]`,
- `</structure>`,
- } {
- if !strings.Contains(out, want) {
- t.Errorf("output must contain %q, got:\n%s", want, out)
- }
- }
- if strings.Contains(out, "Alpha (section)") {
- t.Errorf("a claim hit must replace the drill, so no structure node may render, got:\n%s", out)
- }
-}
-
-// TestNavigateStructureRendersEveryClaim: the tool renders the claims it recalled,
-// with no self-declared sufficiency verdict - whether a claim set is enough to
-// answer from is decided by the pipeline's pre-loop recall, not by a marker the
-// model has to interpret (and which could never agree with that gate's
-// document-diversity rule).
-func TestNavigateStructureRendersEveryClaim(t *testing.T) {
- hits := []claimHit{
- {chunkID: "c1", name: "claim one", quote: "q1"},
- {chunkID: "c2", name: "claim two", quote: "q2"},
- {chunkID: "c3", name: "claim three", quote: "q3"},
- }
- installFakeStructureReader(t, fakeClaimStructureReader{
- fakeStructureReader: fakeStructureReader{byDoc: map[string][]structureRow{}},
- claims: map[string][]claimHit{"d1": hits},
- })
-
- out, err := NewNavigateStructureTool("tenant-1", []string{"kb1"}).
- InvokableRun(context.Background(), `{"query":"claims","doc_id":"d1"}`)
- if err != nil {
- t.Fatalf("InvokableRun: %v", err)
- }
- if got := strings.Count(out, "- [claim] "); got != len(hits) {
- t.Errorf("rendered %d claim lines, want %d:\n%s", got, len(hits), out)
- }
-}
-
-// TestNavigateStructureClaimOnlyDocumentIsNotNoStructure: a document whose
-// compiler wrote claims but no tree nodes still renders — counting only entities
-// would report "no compiled structure" and throw the evidence away.
-func TestNavigateStructureClaimOnlyDocumentIsNotNoStructure(t *testing.T) {
- installFakeStructureReader(t, fakeClaimStructureReader{
- fakeStructureReader: fakeStructureReader{byDoc: map[string][]structureRow{}},
- claims: map[string][]claimHit{"d1": {
- {chunkID: "c1", name: "only claim", quote: "only quote"},
- }},
- })
-
- out, err := NewNavigateStructureTool("tenant-1", []string{"kb1"}).
- InvokableRun(context.Background(), `{"query":"only","doc_id":"d1"}`)
- if err != nil {
- t.Fatalf("InvokableRun: %v", err)
- }
- if !strings.Contains(out, `count="1"`) {
- t.Fatalf("a claim-only document must still render, got:\n%s", out)
- }
- if strings.Contains(out, "no compiled structure") {
- t.Errorf("claim-only document must not report no_structure, got:\n%s", out)
- }
-}
-
-// TestNavigateStructureClaimLegReceivesQueryVector: the tool must hand the nav
-// service's query vector to the claim leg (the dense half of hybrid recall), and
-// must pass nothing when no service is installed.
-func TestNavigateStructureClaimLegReceivesQueryVector(t *testing.T) {
- var got []float64
- installFakeStructureReader(t, fakeClaimStructureReader{
- fakeStructureReader: fakeStructureReader{byDoc: map[string][]structureRow{}},
- claims: map[string][]claimHit{"d1": {{chunkID: "c1", name: "n", quote: "q"}}},
- gotQVec: &got,
- })
- installFakeNavService(t, fakeNavService{
- encode: func(context.Context, string, string) []float64 { return []float64{0.25, 0.5} },
- })
-
- if _, err := NewNavigateStructureTool("tenant-1", []string{"kb1"}).
- InvokableRun(context.Background(), `{"query":"q","doc_id":"d1"}`); err != nil {
- t.Fatalf("InvokableRun: %v", err)
- }
- if len(got) != 2 || got[0] != 0.25 {
- t.Errorf("claim leg received qvec %v, want the service's vector", got)
- }
-
- installFakeNavService(t, nil)
- if _, err := NewNavigateStructureTool("tenant-1", []string{"kb1"}).
- InvokableRun(context.Background(), `{"query":"q","doc_id":"d1"}`); err != nil {
- t.Fatalf("InvokableRun: %v", err)
- }
- if len(got) != 0 {
- t.Errorf("without a nav service the claim leg must run lexical-only, got qvec %v", got)
- }
-}
-
-// TestClaimQueryVectorSwallowsPanic: a misconfigured embedder degrades recall to
-// the lexical leg; it must never take the tool call down.
-func TestClaimQueryVectorSwallowsPanic(t *testing.T) {
- installFakeNavService(t, fakeNavService{
- encode: func(context.Context, string, string) []float64 { panic("boom") },
- })
- if vec := claimQueryVector(context.Background(), "tenant-1", "q"); vec != nil {
- t.Errorf("a panicking encoder must yield no vector, got %v", vec)
- }
-}
-
func TestParseClaimHitReadsEvidenceAndPointer(t *testing.T) {
row := map[string]interface{}{
"content_with_weight": claimRowJSON("Paris is the capital", "capital city", "Paris is the capital of France.", "c9").Content,
@@ -533,52 +327,6 @@ func TestParseClaimHitReadsEvidenceAndPointer(t *testing.T) {
}
}
-// TestRRFFuseMergesLegsByRank: RRF consumes ranks only, so a hit found by both
-// legs outranks one found by a single leg, and the fused list is capped.
-func TestRRFFuseMergesLegsByRank(t *testing.T) {
- dense := []claimHit{{name: "both", chunkID: "c1", score: 0.9}, {name: "only dense", chunkID: "c2", score: 0.8}}
- text := []claimHit{{name: "only text", chunkID: "c3", score: 11}, {name: "both", chunkID: "c1", score: 3}}
-
- fused := rrfFuse(navClaimRRFK, 0, dense, text)
- if len(fused) != 3 {
- t.Fatalf("fused %d hits, want 3: %+v", len(fused), fused)
- }
- if fused[0].name != "both" {
- t.Errorf("the hit found by BOTH legs must rank first, got %+v", fused)
- }
- // A fused hit keeps the best raw score across the legs that found it; the
- // legs' scales are incomparable, which is exactly why fusion uses ranks.
- if fused[0].score != 3 {
- t.Errorf("a fused hit keeps its best raw score, got %v", fused[0].score)
- }
- if len(fused) != 3 || fused[1].name != "only text" || fused[2].name != "only dense" {
- t.Errorf("single-leg hits must follow the double-leg hit, got %+v", fused)
- }
- if capped := rrfFuse(navClaimRRFK, 2, dense, text); len(capped) != 2 {
- t.Errorf("limit must cap the fused list, got %d", len(capped))
- }
-}
-
-// TestClaimRecallKeepsDistinctClaimsFromOneChunk: several facts commonly come
-// from the same passage, so dedupe must be by claim, not by chunk id.
-func TestClaimRecallKeepsDistinctClaimsFromOneChunk(t *testing.T) {
- installFakeStructureReader(t, fakeClaimStructureReader{
- fakeStructureReader: fakeStructureReader{byDoc: map[string][]structureRow{}},
- claims: map[string][]claimHit{"d1": {
- {chunkID: "c1", name: "Acme was founded in 1994", quote: "Acme, founded in 1994"},
- {chunkID: "c1", name: "Acme is based in Zurich", quote: "the Zurich-based firm"},
- }},
- })
- out, err := NewNavigateStructureTool("tenant-1", []string{"kb1"}).
- InvokableRun(context.Background(), `{"query":"Acme","doc_id":"d1"}`)
- if err != nil {
- t.Fatalf("InvokableRun: %v", err)
- }
- if got := strings.Count(out, "- [claim] "); got != 2 {
- t.Errorf("both claims from the shared chunk must render, got %d:\n%s", got, out)
- }
-}
-
// TestClaimOutlineLineShape pins the claim line the model reads.
func TestClaimOutlineLineShape(t *testing.T) {
got := claimOutlineLine(context.Background(), claimHit{name: "Acme was founded in 1994", quote: "Acme, founded in 1994, ...", chunkID: "c1"})
@@ -623,58 +371,6 @@ func installFakeStructureRoute(t *testing.T, docs [][2]string) {
t.Cleanup(func() { navStructureRoute = prev })
}
-// TestNavigateStructureQueryOnlyRoutesAndClaims: without a doc_id the tool routes
-// the query itself and returns compiled claim evidence - this is what makes the
-// tool callable in one step, without a prior navigate_tree.
-func TestNavigateStructureQueryOnlyRoutesAndClaims(t *testing.T) {
- installFakeStructureRoute(t, [][2]string{{"d1", "Alpha"}})
- installFakeStructureReader(t, fakeClaimStructureReader{
- fakeStructureReader: fakeStructureReader{byDoc: map[string][]structureRow{}},
- claims: map[string][]claimHit{"d1": {{
- chunkID: "c1",
- name: "Acme was founded in 1994",
- quote: "Acme, founded in 1994",
- }}},
- })
-
- out, err := NewNavigateStructureTool("tenant-1", []string{"kb1"}).
- InvokableRun(context.Background(), `{"query":"when was Acme founded"}`)
- if err != nil {
- t.Fatalf("InvokableRun: %v", err)
- }
- for _, want := range []string{
- `count="1"`,
- `doc_id="d1"`,
- `- [claim] Acme was founded in 1994 | Evidence: &quot;Acme, founded in 1994&quot; [chunks: c1]`,
- } {
- if !strings.Contains(out, want) {
- t.Errorf("output must contain %q, got:\n%s", want, out)
- }
- }
- if strings.Contains(out, "route first with navigate_tree") {
- t.Errorf("a routed query must not ask for navigate_tree, got:\n%s", out)
- }
-}
-
-// TestNavigateStructureQueryOnlyNoClaimsIsAHint: routing that reaches documents
-// with no claims says so instead of pretending the corpus has no structure.
-func TestNavigateStructureQueryOnlyNoClaimsIsAHint(t *testing.T) {
- installFakeStructureRoute(t, [][2]string{{"d1", "Alpha"}})
- installFakeStructureReader(t, fakeClaimStructureReader{
- fakeStructureReader: fakeStructureReader{byDoc: map[string][]structureRow{}},
- claims: map[string][]claimHit{},
- })
-
- out, err := NewNavigateStructureTool("tenant-1", []string{"kb1"}).
- InvokableRun(context.Background(), `{"query":"nothing here"}`)
- if err != nil {
- t.Fatalf("InvokableRun: %v", err)
- }
- if !strings.Contains(out, `count="0"`) || !strings.Contains(out, "no claim hits") {
- t.Errorf("expected a claim-miss hint, got:\n%s", out)
- }
-}
-
// TestNavigateStructureQueryOnlyNoRouteKeepsTheOldHint: when routing finds nothing
// at all, the tool still tells the model to route with navigate_tree.
func TestNavigateStructureQueryOnlyNoRouteKeepsTheOldHint(t *testing.T) {
@@ -691,258 +387,139 @@ func TestNavigateStructureQueryOnlyNoRouteKeepsTheOldHint(t *testing.T) {
}
}
-// TestRecallCompiledClaimsSufficient: enough distinct claims, from more than one
-// document, make the turn answerable without reading a single raw chunk - and
-// the evidence they carry is rendered WITH the handles the answer must cite.
-func TestRecallCompiledClaimsSufficient(t *testing.T) {
- stubClaimProbe(t, true)
- installFakeStructureReader(t, fakeClaimStructureReader{
- fakeStructureReader: fakeStructureReader{byDoc: map[string][]structureRow{}},
- claims: map[string][]claimHit{
- "d1": {
- {chunkID: "c1", name: "Acme was founded in 1994", quote: "Acme, founded in 1994"},
- {chunkID: "c1", name: "Acme is based in Zurich", quote: "the Zurich-based firm"},
- },
- "d2": {
- {chunkID: "c2", name: "Acme employs 900 people", quote: "a workforce of 900"},
- },
- },
- })
- msgs := []*schema.Message{{Role: schema.User, Content: "when was Acme founded"}}
- ctx := WithEvidenceRegistry(context.Background(), NewEvidenceRegistry())
- pf := recallCompiledClaims(ctx, "tenant-1", []string{"kb1"}, msgs)
-
- if !pf.sufficient {
- t.Fatalf("3 claims over 2 documents must be sufficient, got %d claims over %v", len(pf.claims), pf.docs)
- }
- if len(pf.claims) != 3 || len(pf.docs) != 2 {
- t.Fatalf("recall = %d claims over %v, want 3 over 2 documents", len(pf.claims), pf.docs)
- }
- if !strings.Contains(pf.evidence, `doc_id="d1"`) || !strings.Contains(pf.evidence, `doc_id="d2"`) ||
- !strings.Contains(pf.evidence, "- [claim] Acme was founded in 1994") {
- t.Errorf("evidence must carry both docs and their claims, got:\n%s", pf.evidence)
- }
- for _, want := range []string{"ref=0", "ref=1"} {
- if !strings.Contains(pf.evidence, want) {
- t.Errorf("evidence must publish %q so the answer can cite it, got:\n%s", want, pf.evidence)
+// TestClaimAnswerPromptCarriesEvidenceAndCitationRule pins what the answer call
+// depends on: the evidence itself, the rule that turns each fact line into a
+// resolvable reference, and the two answer rules this corpus needs - pick the
+// candidate the question names, and name the inputs of a computation.
+func TestClaimAnswerPromptCarriesEvidenceAndCitationRule(t *testing.T) {
+ evidence := "- [claim] Acme was founded in 1994 [chunks: c1] ref=0"
+ prompt := claimAnswerPrompt(evidence)
+ for _, want := range []string{
+ evidence, "[ID:n]", "ref=n", "Do not call tools", `"answer"`,
+ "the one the question names (last, first, most",
+ "derived_from", "A derivation with one input is not a derivation",
+ "complete list", `"answerable": false`,
+ } {
+ if !strings.Contains(prompt, want) {
+ t.Errorf("claim answer prompt must contain %q, got:\n%s", want, prompt)
}
}
}
-// TestRecallCompiledClaimsSingleDocumentIsNotSufficient: one document's claims
-// answer one hop at most. This is also the exact shape a broken document ranking
-// produces for every question, so the gate must refuse it.
-func TestRecallCompiledClaimsSingleDocumentIsNotSufficient(t *testing.T) {
- stubClaimProbe(t, true)
- installFakeStructureReader(t, fakeClaimStructureReader{
- fakeStructureReader: fakeStructureReader{byDoc: map[string][]structureRow{}},
- claims: map[string][]claimHit{"d1": {
- {chunkID: "c1", name: "Acme was founded in 1994", quote: "Acme, founded in 1994"},
- {chunkID: "c1", name: "Acme is based in Zurich", quote: "the Zurich-based firm"},
- {chunkID: "c2", name: "Acme employs 900 people", quote: "a workforce of 900"},
- }},
- })
- msgs := []*schema.Message{{Role: schema.User, Content: "when was Acme founded"}}
- pf := recallCompiledClaims(context.Background(), "tenant-1", []string{"kb1"}, msgs)
- if pf.sufficient {
- t.Fatalf("claims from one document must not terminate the turn, got %d claims over %v", len(pf.claims), pf.docs)
- }
- if pf.evidence != "" {
- t.Errorf("an insufficient recall must not render evidence, got:\n%s", pf.evidence)
- }
-}
-
-// TestRecallCompiledClaimsEmptyDocumentScopeSkipsRecall: a non-nil EMPTY scope
-// means the turn allows no documents. The reader treats an empty docIDs slice as
-// "the whole dataset", so the recall must stop before the read instead of
-// widening the turn's scope to everything.
-func TestRecallCompiledClaimsEmptyDocumentScopeSkipsRecall(t *testing.T) {
- stubClaimProbe(t, true)
- installFakeStructureReader(t, fakeClaimStructureReader{
- fakeStructureReader: fakeStructureReader{byDoc: map[string][]structureRow{}},
- claims: map[string][]claimHit{
- "d1": {{chunkID: "c1", name: "Acme was founded in 1994", quote: "Acme, founded in 1994"}},
- "d2": {{chunkID: "c2", name: "Acme employs 900 people", quote: "a workforce of 900"}},
- },
- })
- msgs := []*schema.Message{{Role: schema.User, Content: "when was Acme founded"}}
- ctx := withDocumentScope(context.Background(), []string{})
- pf := recallCompiledClaims(ctx, "tenant-1", []string{"kb1"}, msgs)
- if len(pf.claims) != 0 || pf.sufficient || pf.evidence != "" {
- t.Fatalf("an empty document scope must skip the recall, got %d claims (sufficient=%v, evidence=%q)",
- len(pf.claims), pf.sufficient, pf.evidence)
- }
-}
-
-// TestRecallCompiledClaimsInsufficientIsDropped: a recall below the sufficiency
-// count must not reach the model - neither as evidence nor as published handles
-// for passages it never saw.
-func TestRecallCompiledClaimsInsufficientIsDropped(t *testing.T) {
- stubClaimProbe(t, true)
- installFakeStructureRoute(t, [][2]string{{"d1", "Alpha"}})
- installFakeStructureReader(t, fakeClaimStructureReader{
- fakeStructureReader: fakeStructureReader{byDoc: map[string][]structureRow{}},
- claims: map[string][]claimHit{"d1": {{
- chunkID: "c1",
- name: "Acme was founded in 1994",
- quote: "Acme, founded in 1994",
- }}},
- })
- msgs := []*schema.Message{{Role: schema.User, Content: "when was Acme founded"}}
- registry := NewEvidenceRegistry()
- pf := recallCompiledClaims(WithEvidenceRegistry(context.Background(), registry), "tenant-1", []string{"kb1"}, msgs)
- if pf.sufficient {
- t.Fatalf("1 claim must not be sufficient (%d required)", navClaimSufficientHits)
- }
- if pf.evidence != "" {
- t.Errorf("an insufficient recall must not render evidence, got:\n%s", pf.evidence)
- }
- if got := len(registry.IDs()); got != 0 {
- t.Errorf("a dropped recall must not publish handles, got %d", got)
- }
-}
-
-// TestRecallCompiledClaimsSkipsEmptyHits: nothing matched, so nothing is
-// offered - the loop runs exactly as it would without the recall.
-func TestRecallCompiledClaimsSkipsEmptyHits(t *testing.T) {
- stubClaimProbe(t, true)
- installFakeStructureRoute(t, [][2]string{{"d1", "Alpha"}})
- installFakeStructureReader(t, fakeClaimStructureReader{
- fakeStructureReader: fakeStructureReader{byDoc: map[string][]structureRow{}},
- claims: map[string][]claimHit{},
- })
- msgs := []*schema.Message{{Role: schema.User, Content: "nothing here"}}
- pf := recallCompiledClaims(context.Background(), "tenant-1", []string{"kb1"}, msgs)
- if pf.sufficient || pf.evidence != "" || len(pf.claims) != 0 {
- t.Errorf("an empty recall must yield an empty verdict, got %+v", pf)
- }
-}
-
-// stubClaimProbe drives the claim-prefetch gate without an engine.
-func stubClaimProbe(t *testing.T, present bool) {
- t.Helper()
- prev := claimRowsPresent
- claimRowsPresent = func(context.Context, string, []string) bool { return present }
- t.Cleanup(func() { claimRowsPresent = prev })
-}
-
-// claimsPerDoc builds n distinct claims for one document.
-func claimsPerDoc(docID string, n int) []claimHit {
- out := make([]claimHit, 0, n)
- for i := 0; i < n; i++ {
- out = append(out, claimHit{
- chunkID: docID + "-c" + string(rune('a'+i)),
- name: docID + " claim " + string(rune('a'+i)),
- quote: "quote",
- })
- }
- return out
-}
-
-// TestRecallCapsClaims: the recall block is the whole prompt of the answer call,
-// so it honours its cap - and the cap is spread across documents, not spent on
-// the first one.
-func TestRecallCapsClaims(t *testing.T) {
- stubClaimProbe(t, true)
- docs := []string{"d1", "d2", "d3", "d4"}
- claims := map[string][]claimHit{}
- for _, d := range docs {
- claims[d] = claimsPerDoc(d, 8)
- }
- installFakeStructureReader(t, fakeClaimStructureReader{
- fakeStructureReader: fakeStructureReader{byDoc: map[string][]structureRow{}},
- claims: claims,
- })
- msgs := []*schema.Message{{Role: schema.User, Content: "acme"}}
- pf := recallCompiledClaims(context.Background(), "tenant-1", []string{"kb1"}, msgs)
- if got := strings.Count(pf.evidence, "- [claim] "); got != navClaimPrefetchTopN {
- t.Errorf("recall rendered %d claims, want the cap %d:\n%s", got, navClaimPrefetchTopN, pf.evidence)
- }
- for _, docID := range docs {
- if !strings.Contains(pf.evidence, `doc_id="`+docID+`"`) {
- t.Errorf("the cap must be spread across documents, %s missing:\n%s", docID, pf.evidence)
+// TestClaimVerifyPromptTargetsNearMisses: the verifier exists to catch the two
+// measured wrong shortcuts, both of which were "right subject, wrong fact". It
+// must name that failure, must not become a second answerer, and must carry both
+// the page and the candidate.
+func TestClaimVerifyPromptTargetsNearMisses(t *testing.T) {
+ evidence := "- [claim] The King's Speech was released in 2010 [chunks: c1] ref=0"
+ answer := "Colin Firth received his first Academy Award in 2010. [ID:0]"
+ prompt := claimVerifyPrompt(evidence, answer)
+ for _, want := range []string{
+ evidence, answer, "near miss", "release year", "last/latest",
+ "Do not rewrite the answer", `"supported": false`, "The page is the only source",
+ } {
+ if !strings.Contains(prompt, want) {
+ t.Errorf("claim verify prompt must contain %q, got:\n%s", want, prompt)
}
}
}
-// TestClaimAnswerPromptCarriesEvidenceAndCitationRule pins what the
-// sufficient-claims answer depends on: the evidence itself, the rule that turns
-// each fact line into a resolvable reference, and the refusal path - a model that
-// narrates instead of answering must have an explicit way to say so, because the
-// caller falls back to the loop on it.
-func TestClaimAnswerPromptCarriesEvidenceAndCitationRule(t *testing.T) {
- evidence := "- [claim] Acme was founded in 1994 [chunks: c1] ref=0"
- prompt := claimAnswerPrompt(evidence)
- for _, want := range []string{evidence, "[ID:n]", "ref=n", "Do not call tools", `"answerable"`} {
- if !strings.Contains(prompt, want) {
- t.Errorf("claim answer prompt must contain %q, got:\n%s", want, prompt)
+// TestClaimHandleCount backs the floor a derived answer has to clear: distinct
+// handles only, so repeating one claim three times cannot pass as a derivation.
+func TestClaimHandleCount(t *testing.T) {
+ cases := []struct {
+ answer string
+ want int
+ }{
+ {"no handles at all", 0},
+ {"1994 [ID:0]", 1},
+ {"1994 [ID:0] and 56 years later [ID:0]", 1},
+ {"1967 minus 56 = 1911 [ID:1][ID:3]", 2},
+ {"[ID:7], [ID:11], [ID:7]", 2},
+ }
+ for _, c := range cases {
+ if got := claimHandleCount(c.answer); got != c.want {
+ t.Errorf("claimHandleCount(%q) = %d, want %d", c.answer, got, c.want)
}
}
}
-// TestParseClaimAnswer: the verdict decides control flow, so both the refusal and
-// the malformed-reply cases must fall back rather than ship prose.
+// TestParseClaimAnswer: only an explicit answerable answer may produce text, and
+// a reply with no answer field is not one - shipping prose is the zero-score
+// failure mode. The refusal keeps its named gap for the gap_overlap diagnostic.
func TestParseClaimAnswer(t *testing.T) {
ok := parseClaimAnswer(`{"answerable": true, "answer": "1994 [ID:0]"}`)
- if !ok.answerable || ok.answer != "1994 [ID:0]" {
- t.Errorf("answerable verdict parsed as %+v", ok)
+ if !ok.answerable || ok.answer != "1994 [ID:0]" || ok.missing != "" {
+ t.Errorf("answer parsed as %+v", ok)
}
no := parseClaimAnswer(`{"answerable": false, "missing": "the founding year"}`)
if no.answerable || no.missing != "the founding year" {
t.Errorf("refusal parsed as %+v", no)
}
- // A model that narrates instead of answering must NOT be shipped as the
- // answer: that is the zero-score failure mode.
narrated := parseClaimAnswer("I need to research who Brian Bergstein is. Let me search for this information.")
if narrated.answerable || narrated.answer != "" {
t.Errorf("narrated reply must be treated as not answerable, got %+v", narrated)
}
- // "answerable" without an answer is not an answer.
empty := parseClaimAnswer(`{"answerable": true, "answer": " "}`)
if empty.answerable {
t.Errorf("empty answer must be not answerable, got %+v", empty)
}
+ // An answer without the flag is still an answer: treating it as a refusal
+ // would hand a usable answer to the loop.
+ noFlag := parseClaimAnswer(`{"answer": "1994 [ID:0]"}`)
+ if !noFlag.answerable || noFlag.answer != "1994 [ID:0]" {
+ t.Errorf("answer without the flag parsed as %+v", noFlag)
+ }
+ // derived_from as a JSON list is read as-is.
+ derived := parseClaimAnswer(`{"answerable": true, "answer": "1994 [ID:0]", "derived_from": ["[ID:0]", "[ID:1]"]}`)
+ if got := claimDerivedInputs(derived); len(got) != 2 {
+ t.Errorf("derived_from list parsed as %+v", got)
+ }
}
-// TestQueryOnlyToolCallIsUncapped: a model-invoked call is not capped - the model
-// asked for it and its result lands in the history once.
-func TestQueryOnlyToolCallIsUncapped(t *testing.T) {
- installFakeStructureRoute(t, [][2]string{{"d1", "A"}, {"d2", "B"}})
- installFakeStructureReader(t, fakeClaimStructureReader{
- fakeStructureReader: fakeStructureReader{byDoc: map[string][]structureRow{}},
- claims: map[string][]claimHit{
- "d1": claimsPerDoc("d1", 5),
- "d2": claimsPerDoc("d2", 5),
- },
- })
- out, err := NewNavigateStructureTool("tenant-1", []string{"kb1"}).
- InvokableRun(context.Background(), `{"query":"acme"}`)
- if err != nil {
- t.Fatalf("InvokableRun: %v", err)
+// TestClaimDerivedInputs: the prompt asks for a `derived_from:` line inside the
+// answer, so the floor has to read both forms - otherwise a derivation written as
+// prose would slip past the "at least two inputs" check.
+func TestClaimDerivedInputs(t *testing.T) {
+ asLine := parseClaimAnswer(`{"answerable": true, "answer": "5 + 6 = 11 [ID:0] [ID:1]\nderived_from: [ID:0], [ID:1]"}`)
+ if got := claimDerivedInputs(asLine); len(got) != 2 {
+ t.Errorf("derived_from line parsed as %+v", got)
+ }
+ // The JSON field wins over the line when both are present.
+ both := parseClaimAnswer(`{"answerable": true, "answer": "x [ID:0]\nderived_from: [ID:5]", "derived_from": ["[ID:0]", "[ID:1]", "[ID:2]"]}`)
+ if got := claimDerivedInputs(both); len(got) != 3 {
+ t.Errorf("json field must take precedence, got %+v", got)
}
- if got := strings.Count(out, "- [claim] "); got != 10 {
- t.Errorf("a model-invoked call must not be capped, got %d claims:\n%s", got, out)
+ plain := parseClaimAnswer(`{"answerable": true, "answer": "1994 [ID:0]"}`)
+ if got := claimDerivedInputs(plain); len(got) != 0 {
+ t.Errorf("a direct answer names no inputs, got %+v", got)
+ }
+ // Repeating one handle is one input, not two.
+ repeated := parseClaimAnswer(`{"answerable": true, "answer": "x [ID:0]\nderived_from: [ID:0], [ID:0]"}`)
+ if got := claimDistinctHandles(claimDerivedInputs(repeated)); got != 1 {
+ t.Errorf("repeated handle counted as %d inputs, want 1", got)
}
}
-// TestRecallSkippedWithoutClaimRows: a compiled but claim-less dataset (a tree
-// or timeline) must not pay for a routing call and two retrieval legs.
-func TestRecallSkippedWithoutClaimRows(t *testing.T) {
- stubClaimProbe(t, false)
- installFakeStructureRoute(t, [][2]string{{"d1", "A"}})
- installFakeStructureReader(t, fakeClaimStructureReader{
- fakeStructureReader: fakeStructureReader{byDoc: map[string][]structureRow{}},
- // Claims exist in the fake store on purpose: the gate must win, otherwise
- // this test would pass for the wrong reason.
- claims: map[string][]claimHit{"d1": {{
- chunkID: "c1",
- name: "Acme was founded in 1994",
- quote: "Acme, founded in 1994",
- }}},
- })
- msgs := []*schema.Message{{Role: schema.User, Content: "when was Acme founded"}}
- pf := recallCompiledClaims(context.Background(), "tenant-1", []string{"kb1"}, msgs)
- if pf.sufficient || pf.evidence != "" || len(pf.claims) != 0 {
- t.Errorf("no claim rows must disable the recall, got %+v", pf)
+// TestParseClaimSupport: a rejection needs an explicit `supported: false`; every
+// other reply counts as support, because refusing a good answer hands the
+// question to the loop for 300-600k tokens. The unparsed case stays visible
+// through parsed=false so that default cannot mask a prompt regression.
+func TestParseClaimSupport(t *testing.T) {
+ ok := parseClaimSupport(`{"supported": true}`)
+ if !ok.supported || !ok.parsed || ok.reason != "" {
+ t.Errorf("support parsed as %+v", ok)
+ }
+ no := parseClaimSupport(`{"supported": false, "reason": "2010 is the release year, not the award year"}`)
+ if no.supported || !no.parsed || !strings.Contains(no.reason, "release year") {
+ t.Errorf("rejection parsed as %+v", no)
+ }
+ narrated := parseClaimSupport("This looks right to me.")
+ if !narrated.supported || narrated.parsed {
+ t.Errorf("unparsed reply must fail open and be flagged, got %+v", narrated)
+ }
+ missingField := parseClaimSupport(`{"verdict": "ok"}`)
+ if !missingField.supported || missingField.parsed {
+ t.Errorf("reply without a supported field must fail open, got %+v", missingField)
}
}
diff --git a/internal/common/environments.go b/internal/common/environments.go
index c5025a0b21..6c1e737cd7 100644
--- a/internal/common/environments.go
+++ b/internal/common/environments.go
@@ -347,6 +347,35 @@ const (
// only RAGFLOW_DECISION_DIR keeps filtering deep reads and nothing else.
EnvDecisionFilterDeepRead = "RAGFLOW_DECISION_FILTER_DEEP_READ"
EnvDecisionFilterSnippet = "RAGFLOW_DECISION_FILTER_SNIPPET"
+ // EnvClaimSearch switches the claim-text retrieval leg: claim rows are searched
+ // by their own text and the hits are UNIONED onto the anchored page. Off means
+ // the page is the anchored claims only, which is the pre-existing behaviour.
+ EnvClaimSearch = "RAGFLOW_CLAIM_SEARCH"
+ // EnvClaimPage switches the claim evidence page itself. Off means the
+ // prefetch serves the retrieved chunks as raw text instead of their claims:
+ // the control arm for measuring what the claim artifact is worth, and an
+ // escape hatch for a deployment whose ingestion has not compiled claims yet.
+ EnvClaimPage = "RAGFLOW_CLAIM_PAGE"
+ // EnvDecisionClaimFloor switches the claim exit's per-chunk floor and relative
+ // threshold. On by default: the absolute threshold was fitted on a different
+ // judge, so a correctly recalled claim can sit below it and be dropped.
+ EnvDecisionClaimFloor = "RAGFLOW_DECISION_CLAIM_FLOOR"
+ // EnvDecisionClaimJudgeCap bounds how many statements ONE claim page may send
+ // to the judge. Unset means the built-in bound. The page is unbounded by
+ // design; the judge cannot afford to be, and a rate-limited key trips its
+ // breaker long before a 300-statement page is scored.
+ EnvDecisionClaimJudgeCap = "RAGFLOW_DECISION_CLAIM_JUDGE_CAP"
+ // EnvDecisionClaimMinProb is the P(relevant) a compiled statement must reach to
+ // survive the claim exit. It is separate from EnvDecisionMinProb because a
+ // statement is a single fact with a short quote, not a passage: the judge scores
+ // the two shapes on different scales, so one threshold for both either drops
+ // recalled statements or keeps noise.
+ EnvDecisionClaimMinProb = "RAGFLOW_DECISION_CLAIM_MIN_PROB"
+ // EnvDecisionFilterClaim switches the filter's third exit: compiled claims,
+ // judged one statement at a time. On by default because the claim page is the
+ // only model-visible block with no length bound of its own - a chunk's claim
+ // set can cost more than the chunk it stands for, and this is what bounds it.
+ EnvDecisionFilterClaim = "RAGFLOW_DECISION_FILTER_CLAIM"
// EnvDecisionSnippetTools replaces the snippet filter's TOOL scope (comma
// separated). Unset means the corpus-passage locate tools only;
// search_metadata is never in scope because it returns no passages.
@@ -451,6 +480,46 @@ const (
// question and below every runaway one, so it bounds the tail without
// touching the body of the distribution.
EnvAgenticTokenBudget = "RAGFLOW_AGENTIC_TOKEN_BUDGET"
+
+ // EnvCompiledServe switches the corpus-passage SERVE PATH: after a locate
+ // recall (grep/bm25/semantic/search_chunks) the model is normally shown the
+ // recalled chunk's raw text; this knob replaces that text with the corpus's
+ // KNOWLEDGE-COMPILED products (entity/relation descriptions, RAPTOR tree
+ // summaries, …) that are DERIVED FROM those chunks via source_chunk_ids
+ // lineage.
+ //
+ // - "off" (default): unchanged behaviour — raw snippet/body is served,
+ // the decision sufficiency filter runs as configured.
+ // - "only" : locate exit serves compiled products only (raw snippet is
+ // withheld); the deep-read exit (list_chunks) also serves the requested
+ // chunks' compiled products. A chunk with no compiled derivative falls
+ // back to its raw text (logged) so the run never sees an empty result.
+ // - "first" : locate exit serves compiled products PLUS the chunk handles
+ // and a deep-read hint — the model reads the compiled products first and
+ // falls back to list_chunks (raw body, decision filter as baseline) only
+ // when it needs more. The deep-read exit is unchanged.
+ EnvCompiledServe = "RAGFLOW_COMPILED_SERVE"
+ // EnvCompiledServeTopN caps how many compiled products one locate/deep-read
+ // result set may present. Default 12: a compiled product is one
+ // entity/summary paragraph, far shorter than a chunk, so a dozen fit in the
+ // space of one or two raw passages.
+ EnvCompiledServeTopN = "RAGFLOW_COMPILED_SERVE_TOP_N"
+ // EnvCompiledServeKinds restricts which compile_kwd kinds are served
+ // (comma-separated). Unset means every present kind except the "*" junk rows
+ // and dataset_nav metadata; per-run kinds are probed from the bound datasets
+ // by the compiled-knowledge tools, but here we keep it explicit so an arm can
+ // be narrowed (e.g. "tree,graph") without a recompile.
+ EnvCompiledServeKinds = "RAGFLOW_COMPILED_SERVE_KINDS"
+ // EnvCompiledServeTypes restricts the served rows to these entity_type_kwd
+ // values. Claim rows carry compile_kwd=tree exactly like tree nodes, so KINDS
+ // alone cannot separate them; TYPES=claim is what turns this path into claim
+ // serving. Unset keeps every type, i.e. the previous behaviour.
+ EnvCompiledServeTypes = "RAGFLOW_COMPILED_SERVE_TYPES"
+ // EnvCompiledServeScope overrides which locate tools feed compiled products
+ // (comma-separated tool names). Unset = the corpus-passage locate tools only;
+ // web_search is NEVER in scope because its hits carry no corpus document with
+ // a source_chunk_ids linkage.
+ EnvCompiledServeScope = "RAGFLOW_COMPILED_SERVE_SCOPE"
)
// EnvLLMHTTPResponseHeaderTimeout bounds how long an outbound provider call may
diff --git a/internal/service/chat_pipeline.go b/internal/service/chat_pipeline.go
index b1dc975df9..17a54b33fb 100644
--- a/internal/service/chat_pipeline.go
+++ b/internal/service/chat_pipeline.go
@@ -853,6 +853,15 @@ func (s *ChatPipelineService) AsyncChat(
// Sub-steps: empty_response check → formatPrompt → citationPrompt →
// messageFitIn (95% token budget) → multimodal conversion → adjust max_tokens.
// If no knowledges and empty_response is configured, yield it and return.
+ // Compiled-serve: swap/extend the retrieved chunk text with knowledge-compiled
+ // products when enabled. Mirrors the agentic locate exit for the standard
+ // (reasoning level 1-4) retrieval path. No-op when inactive or no products
+ // were found for the recalled chunks.
+ if rawChunks, ok := kbinfos["chunks"].([]map[string]interface{}); ok && len(rawChunks) > 0 {
+ if served := agentic_rag.CompiledServeChunks(ctx, chat.TenantID, rawChunks, kbIDStrings(kbs)); served != nil {
+ kbinfos["chunks"] = served
+ }
+ }
knowledges = s.kbPrompt(kbinfos, modelMaxTokens)
common.Info("Phase 10: Build LLM Request")
common.Debug("Knowledge prompt",
diff --git a/internal/service/chat_session.go b/internal/service/chat_session.go
index 1a8c70b744..42a4055d5c 100644
--- a/internal/service/chat_session.go
+++ b/internal/service/chat_session.go
@@ -1494,6 +1494,8 @@ func accumulateNonStreamAnswer(resultChan <-chan AsyncChatResult) map[string]int
var audioBinary interface{}
var prompt string
var createdAt float64
+ var usage *ChatTurnUsage
+ var elapsedMs float64
for result := range resultChan {
if result.Final {
// The final event carries the complete (decorated) answer;
@@ -1505,6 +1507,8 @@ func accumulateNonStreamAnswer(resultChan <-chan AsyncChatResult) map[string]int
audioBinary = result.AudioBinary
prompt = result.Prompt
createdAt = result.CreatedAt
+ usage = result.Usage
+ elapsedMs = result.ElapsedMs
} else if result.Answer != "" {
answer.WriteString(result.Answer)
}
@@ -1524,6 +1528,14 @@ func accumulateNonStreamAnswer(resultChan <-chan AsyncChatResult) map[string]int
if createdAt != 0 {
ans["created_at"] = createdAt
}
+ // The SSE final event carries the turn's cost; the non-stream reply has to
+ // carry it too, or a caller comparing runs has no way to read it at all.
+ if usage != nil {
+ ans["usage"] = usage
+ }
+ if elapsedMs > 0 {
+ ans["elapsed_ms"] = elapsedMs
+ }
return ans
}