SuperBizAgent-java/openspec/changes/archive/2026-07-05-rag-vectorstore-mainpath-with-sdk-fallback/proposal.md

Why

The previous sidecar change proved the project can normalize Spring AI VectorStore results without changing the Agent tool boundary. The next step is to integrate the official Spring AI Milvus VectorStore into the main retrieval service while preserving the existing Milvus SDK path as a fallback.

What Changes

• Add the official Spring AI Milvus VectorStore starter dependency.
• Configure Spring AI Milvus to reuse the existing collection, field names, embedding dimension, metric type, and connection settings.
• Update VectorSearchService to support selectable retrieval modes: Spring AI VectorStore, SDK, or automatic fallback.
• Preserve the existing searchSimilarDocuments(query, topK, category) API used by lookup_knowledge.
• Keep the current Milvus SDK implementation available and covered by tests.
• Add tests proving SDK fallback is used when VectorStore is unavailable or fails.
• No breaking API changes.

Capabilities

New Capabilities

• None.

Modified Capabilities

• rag-knowledge-retrieval: Add requirements for using Spring AI VectorStore as the preferred retrieval abstraction while preserving SDK fallback and traceable score semantics.
• rag-retrieval-evaluation: Add requirements that the offline baseline remains stable after the retrieval implementation changes.

Impact

• Affects pom.xml, RAG/Milvus configuration, VectorSearchService, and related tests.
• Does not change lookup_knowledge tool signature, evidence block format, document chunking, upload API, or tool_invocation schema.
• Uses Spring AI Milvus integration but keeps the existing Milvus SDK code path for rollback and compatibility.