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

2.8 KiB Raw Blame History