feat: add spring ai retrieval sidecar

2026-07-05 03:22:03 +08:00
parent 5197712719
commit b9ec07de57
21 changed files with 944 additions and 0 deletions
@@ -0,0 +1,25 @@
+## ADDED Requirements
+
+### 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_knowledge` SHALL 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
@@ -0,0 +1,21 @@
+## ADDED Requirements
+
+### Requirement: Retrieval evaluation SHALL compare current and sidecar retrieval paths
+The retrieval evaluation system SHALL provide an opt-in comparison between the existing retrieval path and the Spring AI sidecar retrieval path.
+
+#### Scenario: Sidecar comparison report
+- **WHEN** sidecar comparison is run for the golden case set
+- **THEN** the report SHALL include per-case current-path top candidates and sidecar top candidates
+- **AND** it SHALL highlight source, breadcrumb, category, rank, and score-label differences
+
+#### Scenario: Offline baseline remains unchanged
+- **WHEN** the fixture-based offline baseline evaluator is run
+- **THEN** it SHALL not require live Milvus, Spring Boot, or Spring AI sidecar configuration
+
+### Requirement: Retrieval evaluation SHALL make sidecar readiness visible
+The sidecar comparison report SHALL show whether the Spring AI sidecar was runnable for the current environment.
+
+#### Scenario: Sidecar unavailable
+- **WHEN** sidecar comparison is requested but the sidecar is disabled or unavailable
+- **THEN** the report SHALL mark sidecar status as unavailable
+- **AND** it SHALL keep current-path baseline results available for review