v1.5.6: supported chunk-selection diagnostics and applicability of #3887/#3904

[DC-AAIA]

We are investigating a chunk-selection discrepancy on LightRAG v1.5.6, pinned to public commit b33c6b0812cddf39206e48a9810112e51f025274.

The pipeline uses mix, reranking disabled, answer caching disabled and empty conversation history. Additional instructions are supplied through user_prompt; we have not demonstrated a custom system-prompt template. The captured stack includes Langfuse 4.6.1, OpenAI Python 2.36.0 and OpenTelemetry SDK 1.41.1.

For one anonymous document, overview chunk A appears in the final context, while substantive chunks B/C do not. A later read-only inspection confirms B/C currently exist in both chunk KV and VDB storage. We are not treating current storage presence as proof of historical retrieval-candidate membership.

We retained the final rendered context and five exposed chunk contents, which match unchanged. We did not retain candidate scores, ordered graph-source groups, deduplication ownership, merged candidates or per-chunk top-k/budget rejection records. Effective KG pick method, related-chunk quota and source-ID limits were not recorded.

Before adding custom instrumentation, could you clarify:

1. Is there a supported diagnostic API or extension point, in this version or a documented later version, that exposes candidate-to-survivor decisions across graph-source selection, deduplication, merging, top-k and token truncation? We inspected /query/data, context/prompt previews, progress callbacks and existing logs, but did not find a complete per-chunk decision ledger.
2. Is our reading of fix(query): preserve minimum vector chunk quota #3887 correct: with VECTOR active and positive integer settings, the zero-quota trigger is exactly related_chunk_number=1 and quota-stage group_count=1, causing WEIGHT fallback rather than inherent loss of all chunks?
3. Is our reading of fix(query): drop empty entity chunk groups #3904 correct: the entity path retains groups emptied by earlier-entity deduplication, whereas the relation path already filters them; removing those groups changes allocation without changing the union candidate pool, and should be considered together with fix(query): preserve minimum vector chunk quota #3887's quota floor?

We are not asserting that either trigger occurred. We also understand that #3592's final follow-up describes defensive normalization, and that the custom-system-template budgeting fix is not established as applicable to our user_prompt placement.

We seek the supported diagnostic contract and minimum evidence needed to distinguish these mechanisms, rather than a diagnosis inferred from final survivors alone.

[Muguett-DBY]

A partial answer from the pinned v1.5.6 source:

• Your reading of the zero quota is right under the stated positive-integer assumptions. Once the VECTOR branch is entered, the entity path and relation path calculate int(related_chunk_number * group_count / 2). Both inputs must be 1 for that result to be zero. The vector helper then returns an empty selection, and the caller falls back to WEIGHT; that doesn't by itself mean every chunk is lost.
• Your distinction in fix(query): drop empty entity chunk groups #3904 also matches the pinned source: entities retain groups emptied by within-entity deduplication, while relations remove empty groups after excluding entity-selected chunks. Removing the empty entity groups preserves their chunk-ID union but changes the group count used for allocation. The zero-quota floor from fix(query): preserve minimum vector chunk quota #3887 matters when that leaves one group and the limit is one.

For diagnostics, the vector helper's DEBUG message includes num_of_chunks and entity_info_count before its early return. If you have a correlated DEBUG log for the original request, num_of_chunks=0, entity_info_count=1 would be useful evidence for that stage. The fallback warning alone isn't enough: other empty vector selections also produce it. These messages don't provide the missing candidate IDs or individual rejection reasons, and their absence is inconclusive if DEBUG logging wasn't enabled. Review any logs privately, as other messages may contain sensitive content.

I didn't find a complete supported candidate-to-survivor ledger in the code paths I checked, so I can't confirm an extension point. The released v1.5.7 tag also predates both merges; I checked its source and neither change is present there. Please check the actual deployment revision before assuming an upgrade includes them.

I exercised the relevant v1.5.6 functions with synthetic IDs and mocked stores, including the real zero-quota early return; I haven't reproduced your deployment or tested a live vector backend. The retained final context alone still can't establish whether B/C were candidates at the time.

[DC-AAIA]

Thanks @Muguett-DBY for the precise source-based explanation and the suggested DEBUG signature.

We inspected retained records for the original run without changing logging or rerunning retrieval. In the bounded records returned, we did not identify the helper's num_of_chunks=0, entity_info_count=1 DEBUG signature, a source-attributable VECTOR/WEIGHT fallback, or explicitly recorded values for the related selection settings. We therefore have not established that the original request hit this condition.

This is a limitation of the retained evidence, not a negative reproduction or proof that DEBUG was disabled. The available correlation is deployment/time-scoped rather than a per-request helper trace. Aggregate rendering counts are not helper group counts, and a fallback warning alone would not establish the trigger. Current stored-passage availability and final-context coverage do not by themselves identify the historical omission stage, so we are keeping the conditional mechanism separate from a proven root-cause claim.

For the maintainers, the remaining question is the supported diagnostic path:

1. Is there a documented read-only diagnostic API or extension point in pinned v1.5.6 (b33c6b0812cddf39206e48a9810112e51f025274), or a specifically identified later version, that exposes candidate chunk IDs and their disposition through graph-source selection, merge/deduplication, top-k and token-budget admission?
2. If no supported complete ledger is available, what is the recommended minimal way to capture those decisions prospectively without changing retrieval behavior? We would like to use an existing supported facility before proposing any narrowly scoped observe-only instrumentation.

We are not assuming that released v1.5.7 includes #3887/#3904, and have not upgraded, enabled broader logging or rerun the query based on this discussion.