feat(vector-store): add optional Milvus backend

[zc277584121]

Summary

• Add a semantic vector store backend selector while keeping Qdrant as the default.
• Add an optional Milvus backend using pymilvus MilvusClient with explicit schema creation, upsert, delete, verify, and search support.
• Document Milvus Lite and self-hosted open-source Milvus endpoint configuration for semantic vectors.

Closes #758

Testing

• uv run --with ruff ruff check codebase_rag/vector_store.py codebase_rag/utils/dependencies.py codebase_rag/tests/test_vector_store.py codebase_rag/tests/test_vector_store_batch.py codebase_rag/tests/conftest.py codebase_rag/config.py codebase_rag/constants/providers.py codebase_rag/logs.py codebase_rag/mcp/server.py
• uv run --with ruff ruff format --check codebase_rag/vector_store.py codebase_rag/utils/dependencies.py codebase_rag/tests/test_vector_store.py codebase_rag/tests/test_vector_store_batch.py codebase_rag/tests/conftest.py codebase_rag/config.py codebase_rag/constants/providers.py codebase_rag/logs.py codebase_rag/mcp/server.py
• uv run --with 'qdrant-client>=1.9.0' --with 'pymilvus[milvus-lite]>=3.0.0' --extra test pytest codebase_rag/tests/test_vector_store.py codebase_rag/tests/test_vector_store_batch.py
• uv run --with 'qdrant-client>=1.9.0' --with 'pymilvus[milvus-lite]>=3.0.0' --extra test pytest codebase_rag/tests/test_graph_updater_embeddings.py codebase_rag/tests/test_mcp_server.py

[gemini-code-assist]

Code Review

This pull request adds support for Milvus (including Milvus Lite) as an alternative semantic vector store backend alongside Qdrant. It introduces a common VectorStore protocol, implements MilvusVectorStore, updates configuration and dependency management, and adds corresponding tests and documentation. The review feedback highlights three key improvements: making the milvus-lite version check more robust, adding a guard to prevent a potential IndexError when processing empty search results, and skipping a Milvus-specific test when the optional pymilvus dependency is not installed.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[greptile-apps]

Greptile Summary

This PR adds an optional Milvus backend for semantic vector storage while keeping Qdrant as the default. The main changes are:

• Adds backend selection through CGR_VECTOR_STORE_BACKEND.
• Implements Milvus client setup, schema validation, upsert, delete, verification, and search support.
• Adds a milvus optional dependency extra and includes it in CI setup.
• Updates tests and docs for Milvus Lite and self-hosted Milvus endpoints.

Confidence Score: 5/5

Safe to merge with minimal risk.

The updated code keeps Qdrant as the default, gates Milvus behind backend-specific dependency checks, and includes focused tests for the new backend behavior.

No files require special attention.

T-Rex Logs

What T-Rex did

• A targeted pytest run and cmake checks were attempted, but progress was blocked by a missing cmake for pymgclient.
• A Milvus Lite runtime harness was generated from vector_store_milvus_lite_harness.py to enable the closest-feasible no-sync vector-store validation.
• The Milvus Lite runtime proof completed successfully, performing upsert, search, delete, verify, and cleanup, and exited with code 0.
• Lint and format checks on changed files completed, with ruff and ruff-format exiting code 0.

_{Ran code and verified through T-Rex}

Important Files Changed

Filename	Overview
codebase_rag/vector_store.py	Refactors vector storage behind Qdrant and Milvus backend implementations with shared lifecycle, upsert, delete, verify, and search APIs.
codebase_rag/utils/dependencies.py	Adds backend-aware semantic dependency checks for Qdrant or Milvus.
codebase_rag/config.py	Adds typed vector-store backend selection and Milvus connection/schema settings.
pyproject.toml	Adds the optional Milvus extra using pymilvus with milvus-lite support.
codebase_rag/tests/test_vector_store.py	Extends vector store tests to cover backend selection, Milvus client setup, score workaround, and roundtrip behavior.
.github/workflows/ci.yml	Adds the Milvus extra to CI dependency installation for lint, unit, and integration jobs.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
participant Caller as Embedding/Search caller
participant Deps as Dependency checks
participant Store as vector_store facade
participant Qdrant as QdrantVectorStore
participant Milvus as MilvusVectorStore

Caller->>Deps: has_semantic_dependencies()
Deps-->>Caller: selected backend dependencies available
Caller->>Store: store/search/verify/delete
Store->>Store: read VECTOR_STORE_BACKEND
alt "backend == qdrant"
    Store->>Qdrant: delegate operation
    Qdrant->>Qdrant: get_qdrant_client()
else "backend == milvus"
    Store->>Milvus: delegate operation
    Milvus->>Milvus: get_milvus_client()
    Milvus->>Milvus: ensure/validate collection schema
end
Store-->>Caller: operation result

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
participant Caller as Embedding/Search caller
participant Deps as Dependency checks
participant Store as vector_store facade
participant Qdrant as QdrantVectorStore
participant Milvus as MilvusVectorStore

Caller->>Deps: has_semantic_dependencies()
Deps-->>Caller: selected backend dependencies available
Caller->>Store: store/search/verify/delete
Store->>Store: read VECTOR_STORE_BACKEND
alt "backend == qdrant"
    Store->>Qdrant: delegate operation
    Qdrant->>Qdrant: get_qdrant_client()
else "backend == milvus"
    Store->>Milvus: delegate operation
    Milvus->>Milvus: get_milvus_client()
    Milvus->>Milvus: ensure/validate collection schema
end
Store-->>Caller: operation result

Loading

_{Reviews (4): Last reviewed commit: "refactor(deps): split pymilvus into a de..." | Re-trigger Greptile}

[zc277584121]

@vitali87 I opened the scoped PR based on #758 and kept Qdrant as the default. The docs only mention Milvus Lite and self-hosted open-source Milvus endpoint, following your scope note. I also fixed the inline comment marker flagged by review and reran ruff on the touched file.

[zc277584121]

Synced this branch with upstream/main at f381c55 and resolved the uv.lock conflict while preserving both the upstream dependency updates and the Milvus optional dependency.

Local checks:

• uv lock --check
• uv run --frozen ruff check .
• uv run --frozen ruff format --check .
• Milvus Lite and Qdrant vector-store tests: 35 passed
• git diff --check

The PR is mergeable again. The full type-check job remains delegated to CI because the local base environment does not include the complete semantic extra.

[vitali87]

Maintainer update: merged current main into the branch (regenerated uv.lock for the auto version bumps) and made the optional backend imports ty-clean, since the type check would have failed CI (cast(Any, None) fallbacks so the guarded call sites pass while the module-level bindings your tests patch stay intact). Also approved the workflow runs, so CI is now actually running on this PR.

[vitali87]

@greptile review

[vitali87]

@greptile review

[vitali87]

On the type-safety note in the review summary: the Any/cast fallbacks at the optional-import boundary are deliberate. The alternatives each break something real: None fallbacks with ignore markers fail the repo's ty hook at every guarded call site (call-non-callable), and moving the imports inside the functions would break the test suite's module-attribute patching (patch("codebase_rag.vector_store.QdrantClient")). The call sites are runtime-guarded by has_qdrant_client/has_pymilvus gates in _get_vector_store and the client constructors, so the untyped window is confined to the two conditional import blocks. Leaving as is.

[vitali87]

Second maintainer update per review discussion: pymilvus[milvus-lite] moved out of the shared semantic extra into a dedicated milvus extra, so Qdrant users no longer download the embedded server. Docs and CI installs updated accordingly (install with code-graph-rag[semantic,milvus] for the Milvus backend).

[vitali87]

@greptile review