85 lines
4.8 KiB
Markdown
85 lines
4.8 KiB
Markdown
# 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_knowledge` call records a tool invocation
|
|
- **THEN** `retrieval_details` SHALL 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_knowledge` call 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 `primary` and `supplement` result 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_knowledge` call records a tool invocation
|
|
- **THEN** `retrieval_details` SHALL 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
|