## Context

The project currently uses `VectorSearchService` to call Milvus directly through the Java SDK. A previous change added a Spring AI `VectorStore` sidecar and normalized its results, but the production path still uses SDK-only retrieval. Spring AI provides an official Milvus VectorStore starter, so the main path can now move to the framework abstraction without deleting the proven SDK implementation.

## Goals / Non-Goals

**Goals:**

- Use official Spring AI Milvus VectorStore integration.
- Keep existing Milvus collection compatibility by configuring field names and embedding dimension.
- Preserve current `VectorSearchService` public API.
- Support retrieval mode selection:
  - `spring-ai`: use VectorStore and fail if unavailable.
  - `sdk`: use existing SDK path.
  - `auto`: try VectorStore, then fall back to SDK.
- Preserve existing score semantics in normalized results by labeling Spring AI scores as `similarity` and SDK scores as `l2_distance`.

**Non-Goals:**

- Do not remove Milvus SDK code.
- Do not migrate document writes/indexing to Spring AI in this change.
- Do not change chunking, metadata shape, or evidence post-processing behavior.
- Do not introduce QueryTransformer, MultiQuery, rerank, or neighbor chunk expansion.

## Decisions

### Decision: VectorSearchService remains the boundary

`LookupKnowledgeTool` will keep calling `VectorSearchService.searchSimilarDocuments(...)`.

Rationale: this protects Agent and AIOps behavior from retrieval implementation churn and keeps the refactor testable.

### Decision: Auto fallback is the default

Configure `retrieval.vector-store.mode=auto` so the system prefers Spring AI VectorStore when available but falls back to the existing SDK path on missing beans or runtime errors.

Rationale: official VectorStore integration may expose schema or scoring differences; fallback keeps the MVP runnable.

### Decision: Existing collection is reused

Spring AI Milvus configuration will map to the current collection:

- id field: `id`
- content field: `content`
- embedding field: `vector`
- metadata field: `metadata`
- embedding dimension: `1024`
- metric type: `L2`

Rationale: this avoids reindexing as part of this change and lets golden cases reveal behavior differences first.

### Decision: SDK indexing remains for now

`VectorIndexService` continues writing to Milvus using SDK.

Rationale: replacing both read and write paths at once would make failures harder to isolate. The current change is read-path migration.

## Risks / Trade-offs

- Spring AI filter syntax may not map perfectly to Milvus JSON metadata filters -> keep SDK fallback and add tests for filter expression creation.
- Spring AI score may be similarity while SDK score is L2 distance -> keep score label explicit.
- Auto-configuration could create a VectorStore bean against an incompatible collection -> make retrieval mode configurable and validate with golden cases.
- Keeping two paths adds temporary complexity -> isolate SDK and VectorStore code paths inside `VectorSearchService`.

## Migration Plan

1. Add Spring AI Milvus starter dependency and configuration.
2. Add retrieval mode properties.
3. Refactor `VectorSearchService` to prefer VectorStore based on mode.
4. Preserve and test SDK fallback.
5. Run targeted tests and the offline RAG baseline.
6. In a later change, decide whether to migrate indexing/writes after read-path behavior is stable.