54 lines
2.4 KiB
Markdown
54 lines
2.4 KiB
Markdown
## Context
|
|
|
|
The previous change converted L0 into a hint provider and made L0/L1 cooperate. The next step is to stop treating the tool output as an unstructured primary/supplement pair. The Agent can keep receiving compatible fields, but retrieval internals and traces should have structured evidence blocks.
|
|
|
|
This change is a bridge toward later DocumentPostProcessor-style behavior. It should be small enough to archive independently and should not introduce Spring AI dependencies.
|
|
|
|
## Goals / Non-Goals
|
|
|
|
**Goals:**
|
|
|
|
- Add `EvidenceBlock` DTOs to `LookupResult`.
|
|
- Create evidence blocks from L0 matches and L1 results.
|
|
- Deduplicate evidence by stable source key.
|
|
- Capture source, title, breadcrumb, score, retrieval layer, hit reasons, and content preview.
|
|
- Persist evidence blocks and postprocess counts in `tool_invocation.retrieval_details`.
|
|
|
|
**Non-Goals:**
|
|
|
|
- Do not implement neighbor chunk expansion yet.
|
|
- Do not replace primary/supplement output.
|
|
- Do not add cross-encoder or LLM rerank.
|
|
- Do not migrate to Spring AI DocumentPostProcessor yet.
|
|
|
|
## Decisions
|
|
|
|
### Decision: Add evidence blocks while preserving existing result fields
|
|
|
|
`LookupResult` will gain `List<EvidenceBlock> evidenceBlocks`. Existing `primary`, `supplement`, `found`, `relevanceLevel`, and `completenessHint` remain compatible.
|
|
|
|
Rationale: this lets the Agent continue using the current shape while tests and traces begin validating the new evidence model.
|
|
|
|
### Decision: Keep postprocess rule-based
|
|
|
|
The evidence builder will use deterministic rules:
|
|
|
|
- L0 entries become `L0` evidence.
|
|
- L1 candidates become `L1` evidence.
|
|
- Same source key is deduplicated.
|
|
- Hit reasons are collected from L0 hints, L1 rank, category filters, and fallback state.
|
|
|
|
Rationale: this is explainable, cheap, and suitable before introducing framework postprocessors.
|
|
|
|
### Decision: Persist compact evidence summaries
|
|
|
|
`ToolInvocationRecorder` will store compact evidence block metadata, not full content, inside `retrieval_details`.
|
|
|
|
Rationale: `tool_invocation` should remain useful for trace review without duplicating large chunks.
|
|
|
|
## Risks / Trade-offs
|
|
|
|
- Evidence source keys may be imperfect before full metadata normalization -> fall back to file path, metadata, title, then rank.
|
|
- Agent prompts may ignore `evidenceBlocks` initially -> keep primary/supplement compatibility.
|
|
- Adding content previews increases tool output size -> cap evidence content length.
|