SuperBizAgent-java/openspec/changes/archive/2026-07-05-rag-vectorstore-mainpath-with-sdk-fallback/specs/rag-knowledge-retrieval/spec.md

ADDED Requirements

Requirement: Knowledge retrieval SHALL prefer Spring AI VectorStore when configured

The retrieval service SHALL support Spring AI VectorStore as the preferred vector retrieval abstraction without changing the lookup_knowledge tool contract.

Scenario: VectorStore mode uses Spring AI

• WHEN retrieval vector store mode is configured as spring-ai
• THEN semantic retrieval SHALL query through Spring AI VectorStore
• AND the returned candidates SHALL be normalized into the existing vector search result shape

Scenario: Auto mode prefers VectorStore

• WHEN retrieval vector store mode is configured as auto
• AND a Spring AI VectorStore bean is available
• THEN semantic retrieval SHALL attempt Spring AI VectorStore before the SDK path

Requirement: Knowledge retrieval SHALL preserve SDK fallback

The retrieval service SHALL keep the existing Milvus SDK retrieval implementation available.

Scenario: SDK mode bypasses VectorStore

• WHEN retrieval vector store mode is configured as sdk
• THEN semantic retrieval SHALL use the existing Milvus SDK path

Scenario: Auto fallback uses SDK

• WHEN retrieval vector store mode is auto
• AND Spring AI VectorStore is unavailable or fails
• THEN semantic retrieval SHALL fall back to the existing Milvus SDK path

Requirement: Knowledge retrieval SHALL keep score semantics explicit

The retrieval service SHALL preserve score semantics when results come from different retrieval implementations.

Scenario: SDK score remains L2 distance

• WHEN a candidate is returned by the SDK path
• THEN its score semantics SHALL remain compatible with existing L2 distance normalization

Scenario: VectorStore score is mapped without changing tool contract

• WHEN a candidate is returned by Spring AI VectorStore
• THEN it SHALL be mapped into the existing result shape
• AND trace or comparison code SHALL be able to distinguish it as a VectorStore similarity score when needed

Requirement: Knowledge retrieval SHALL reuse the existing Milvus collection

Spring AI Milvus integration SHALL be configured to use the existing collection schema unless explicitly changed.

Scenario: Existing field mapping

• WHEN Spring AI Milvus VectorStore is configured
• THEN it SHALL use the existing id, content, vector, and metadata field names
• AND it SHALL use the configured embedding dimension and metric type compatible with existing vectors