6.3 KiB
rag-knowledge-retrieval Specification
Purpose
Define the runtime contract for the explicit lookup_knowledge Agent tool, including how L0 keyword/frontmatter hints cooperate with L1 semantic retrieval while preserving metadata filters, fallback evidence, and traceable retrieval details.
Requirements
Requirement: Knowledge retrieval SHALL keep L0 as a hint provider
The lookup_knowledge retrieval flow SHALL retain L0 keyword/frontmatter matching but use it as domain, entity, and explainability hint data rather than as the sole final retrieval decision.
Scenario: L0 produces traceable hint data
- WHEN L0 matches one or more indexed knowledge entries
- THEN the retrieval flow SHALL expose matched titles, matched keywords, domains or categories, and entity terms as structured hint data
Scenario: L0 does not bypass semantic retrieval by default
- WHEN L0 returns exactly one match
- THEN the retrieval flow SHALL still attempt semantic L1 retrieval unless L1 is unavailable or explicitly disabled by configuration
Requirement: Knowledge retrieval SHALL use L0 domain as optional L1 filter
The retrieval flow SHALL use L0 domain/category information as an optional metadata filter for L1 retrieval when the domain is unambiguous.
Scenario: Single domain filter
- WHEN L0 hint data contains exactly one nonblank domain or category
- THEN the L1 retrieval request SHALL include that category as a metadata filter
Scenario: Ambiguous domain fallback
- WHEN L0 hint data contains zero domains or multiple domains
- THEN the L1 retrieval request SHALL run without an L0-derived category filter
Requirement: Knowledge retrieval SHALL preserve fallback evidence
The retrieval flow SHALL still return useful L0 evidence when L1 produces no usable result.
Scenario: L1 has no results
- WHEN L0 has at least one match and L1 returns no candidates
- THEN the tool SHALL return an L0-based primary result
- AND the relevance assessment SHALL not claim semantic support from L1
Scenario: L1 fails
- WHEN L0 has at least one match and L1 retrieval throws or fails
- THEN the tool SHALL return an L0-based primary result
- AND the tool invocation record SHALL preserve the L0 hint details
Requirement: Knowledge retrieval SHALL persist L0 hints
The system SHALL persist L0 hint details in tool_invocation.retrieval_details for lookup_knowledge calls.
Scenario: Retrieval details include L0 hints
- WHEN a
lookup_knowledgecall records a tool invocation - THEN
retrieval_detailsSHALL include L0 matched keywords, domains, entities, and titles when available
Scenario: Retrieval layer reflects cooperating retrieval
- WHEN both L0 hint data and L1 candidates participate in a lookup
- THEN the recorded retrieval layer SHALL be
L0+L1
Requirement: Knowledge retrieval SHALL return structured evidence blocks
The lookup_knowledge retrieval flow SHALL expose retrieved evidence as structured evidence blocks in addition to the existing compatibility fields.
Scenario: Evidence block contains source metadata
- WHEN a
lookup_knowledgecall returns evidence - THEN each evidence block SHALL include source, title when available, breadcrumb when available, retrieval layer, content, and hit reasons
Scenario: Compatibility fields remain available
- WHEN evidence blocks are returned
- THEN the existing
primaryandsupplementresult fields SHALL remain available when their source evidence exists
Requirement: Knowledge retrieval SHALL deduplicate evidence blocks
The retrieval flow SHALL remove duplicate evidence blocks before returning them to the Agent.
Scenario: Duplicate source deduplication
- WHEN L0 and L1 produce evidence with the same source identity
- THEN the retrieval flow SHALL keep a single evidence block for that source
- AND the evidence block SHALL preserve hit reasons from both retrieval paths when available
Scenario: Postprocess count tracking
- WHEN evidence post-processing completes
- THEN the tool invocation details SHALL record candidate count and final evidence block count
Requirement: Knowledge retrieval SHALL persist evidence block summaries
The system SHALL persist compact evidence block summaries in tool_invocation.retrieval_details.
Scenario: Evidence summaries are persisted
- WHEN a
lookup_knowledgecall records a tool invocation - THEN
retrieval_detailsSHALL include evidence block summaries containing source, title, retrieval layer, score when available, and hit reasons
Scenario: Full content is not duplicated into retrieval details
- WHEN evidence block summaries are persisted
- THEN full evidence content SHALL be omitted or truncated so the trace record remains compact
Requirement: Knowledge retrieval SHALL support a disabled-by-default Spring AI sidecar
The retrieval system SHALL allow a Spring AI VectorStore retrieval path to be wired as a sidecar without changing the default lookup_knowledge runtime path.
Scenario: Sidecar disabled by default
- WHEN the application starts without explicit sidecar enablement
- THEN
lookup_knowledgeSHALL continue using the existing retrieval path - AND Chat and AIOps runtime behavior SHALL not depend on the sidecar
Scenario: Sidecar failure does not break main retrieval
- WHEN the Spring AI sidecar is enabled but cannot initialize or query successfully
- THEN the existing retrieval path SHALL remain usable
- AND the failure SHALL be reported as sidecar status rather than as a main retrieval failure
Requirement: Knowledge retrieval SHALL normalize sidecar results for comparison
The sidecar retrieval path SHALL expose results in a comparable structure aligned with the current retrieval result shape.
Scenario: Comparable result metadata
- WHEN sidecar retrieval returns candidates
- THEN each comparable result SHALL include source or doc id, title when available, breadcrumb when available, category when available, rank, content preview, and the sidecar score label/value
Scenario: Score semantics are explicit
- WHEN current retrieval and sidecar retrieval scores are compared
- THEN the report SHALL label score semantics by path instead of assuming direct numeric equivalence