fix(vector-store): address Milvus review feedback

zc277584121 · zc277584121 · commit 21a30768dd1a · 2026-07-25T00:39:57.000Z
diff --git a/.env.template b/.env.template
@@ -331,7 +331,7 @@ VECTOR_STORE_MIGRATED=false
 # VECTOR_STORE_MILVUS_URI=./milvus.db
 # VECTOR_STORE_MILVUS_TOKEN=
 # VECTOR_STORE_MILVUS_DB_NAME=
-# VECTOR_STORE_MILVUS_CONSISTENCY_LEVEL=
+# VECTOR_STORE_MILVUS_CONSISTENCY_LEVEL=Session
 
 # Reconciliation interval for background sync (default: 5 minutes)
 # VECTOR_STORE_RECONCILIATION_INTERVAL_SECONDS=300
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ### Added
 
+- Milvus vector store backend with Milvus Lite defaults, configurable server or Zilliz Cloud connectivity, and session-consistent reads (#876)
 - `api_request_duration_seconds` Prometheus histogram tracking per-route request latency, labeled by method and endpoint (#837)
 - LLM `provider_params` passthroughs (`extra_body` / `extra_headers` / `extra_query`) are now forwarded to the underlying provider transport across all backends, with shape validation that rejects non-mapping values (#821)
 - `structured_output_mode` model-config option to use `json_object` mode for OpenAI-compatible providers that lack native Structured Outputs support (used by the deriver) (#820)
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -244,6 +244,7 @@ src/
 ├── vector_store/        # Optional external vector stores (pgvector is default,
 │   │                    #   implemented via MessageEmbedding/Document in models+crud)
 │   ├── lancedb.py
+│   ├── milvus.py
 │   └── turbopuffer.py
 ├── telemetry/           # Observability
 │   ├── emitter.py        # CloudEvents emitter
@@ -286,7 +287,7 @@ src/
 5. **Provider-agnostic LLM layer** (`src/llm/`): all model calls go through `honcho_llm_call()`. Backends (`anthropic`, `gemini`, `openai`) sit behind a registry; per-agent `MODEL_CONFIG` with fallback chains is resolved at call time.
 6. **Dialectic reasoning tiers**: 5 levels (`minimal` → `max`); each level has its own model config and tool set (`minimal` uses a reduced toolset).
 7. **Hybrid search**: Postgres FTS (GIN index on `to_tsvector('english', content)`) + vector similarity (HNSW on `MessageEmbedding.embedding`). `MessageEmbedding` is a separate table from `Message` with its own `sync_state` so embedding is decoupled from message creation.
-8. **Pluggable external vector stores**: defaults to pgvector inline; can swap to turbopuffer or lancedb (`VECTOR_STORE_*` config; `src/vector_store/`).
+8. **Pluggable external vector stores**: defaults to pgvector inline; can swap to turbopuffer, lancedb, or milvus (`VECTOR_STORE_*` config; `src/vector_store/`).
 9. **Composite-FK multi-tenancy**: `workspace_name` participates in nearly every composite FK. Cross-workspace data leakage is structurally impossible at the schema level.
 10. **Scoped Authentication**: JWTs can be scoped to workspace, peer, or session level.
 11. **Batch Operations**: Bulk message creation up to 100 messages per request.
diff --git a/config.toml.example b/config.toml.example
@@ -287,5 +287,5 @@ LANCEDB_PATH = "./lancedb_data"
 MILVUS_URI = "./milvus.db"
 # MILVUS_TOKEN = ""
 # MILVUS_DB_NAME = ""
-# MILVUS_CONSISTENCY_LEVEL = "Session"
+MILVUS_CONSISTENCY_LEVEL = "Session"
 RECONCILIATION_INTERVAL_SECONDS = 300
diff --git a/docs/changelog/introduction.mdx b/docs/changelog/introduction.mdx
@@ -30,6 +30,7 @@ Welcome to the Honcho changelog! This section documents all notable changes to t
         <Update label="v3.0.11 (Current)">
         ### Added
 
+        - Milvus vector store backend with Milvus Lite defaults, configurable server or Zilliz Cloud connectivity, and session-consistent reads (#876)
         - `api_request_duration_seconds` Prometheus histogram tracking per-route request latency, labeled by method and endpoint (#837)
         - LLM `provider_params` passthroughs (`extra_body` / `extra_headers` / `extra_query`) are now forwarded to the underlying provider transport across all backends, with shape validation that rejects non-mapping values (#821)
         - `structured_output_mode` model-config option to use `json_object` mode for OpenAI-compatible providers that lack native Structured Outputs support (used by the deriver) (#820)
diff --git a/docs/v3/contributing/changing-embeddings.mdx b/docs/v3/contributing/changing-embeddings.mdx
@@ -57,6 +57,6 @@ If you are using `text-embedding-3-large` but truncating to 1536 (the default),
 
 For this case, either set `EMBEDDING_VECTOR_DIMENSIONS=1536` explicitly (so `auto` knows the operator opted in), or set `EMBEDDING_MODEL_CONFIG__DIMENSIONS_MODE=always`.
 
-## Backend swap (turbopuffer ↔ lancedb ↔ pgvector) is a different operation
+## Backend swap (turbopuffer ↔ lancedb ↔ milvus ↔ pgvector) is a different operation
 
 Switching the *storage backend* at constant dim/model — for example moving from pgvector to Turbopuffer — is supported via `src/reconciler/sync_vectors.py` and `VECTOR_STORE_MIGRATED`. That flow is unchanged by the embedding-pipeline work and is documented separately. It is **not** the destroy + rebuild path described above.
diff --git a/docs/v3/contributing/configuration.mdx b/docs/v3/contributing/configuration.mdx
@@ -282,7 +282,7 @@ Existing deployments at 1536 with `text-embedding-3-small` need no action — st
 
 The script refuses to ALTER tables that already contain non-null embeddings. To switch dim or model on a populated deployment, stand up a new deployment at the new configuration and migrate data out of band; there is no in-place re-embedding affordance. See [Changing Embeddings](./changing-embeddings) for the destroy + rebuild recipe and the same-dim model-swap caveat.
 
-External vector stores (Turbopuffer, LanceDB) do not need bootstrap setup. Namespaces are per-workspace and lazy-created on first write at whatever dim the embedding client returns. Use `--report` to inventory the existing namespaces against the configured dim:
+External vector stores (Turbopuffer, LanceDB, Milvus) do not need bootstrap setup. Namespaces are per-workspace and lazy-created on first write at whatever dim the embedding client returns. Use `--report` to inventory the existing namespaces against the configured dim:
 
 ```bash
 uv run python scripts/configure_embeddings.py --report
@@ -292,7 +292,7 @@ The startup validator at `src/startup/embedding_validator.py` enforces the dim i
 
 `VECTOR_STORE_DIMENSIONS` is **deprecated**. `EMBEDDING_VECTOR_DIMENSIONS` is the single source of truth; setting `VECTOR_STORE_DIMENSIONS` explicitly emits a startup warning and is otherwise ignored. The field will be removed in a future release; drop it from your `.env` to silence the warning.
 
-The `VECTOR_STORE_MIGRATED` flag still exists and still controls dual-write / cutover semantics for legacy tenants moving between storage backends (pgvector ↔ turbopuffer ↔ lancedb). It is unrelated to dimension configuration after this release.
+The `VECTOR_STORE_MIGRATED` flag still exists and still controls dual-write / cutover semantics for legacy tenants moving between storage backends (pgvector ↔ turbopuffer ↔ lancedb ↔ milvus). It is unrelated to dimension configuration after this release.
 
 ### Feature-Specific Model Configuration
 
@@ -565,7 +565,7 @@ VECTOR_STORE_LANCEDB_PATH=./lancedb_data
 VECTOR_STORE_MILVUS_URI=./milvus.db
 VECTOR_STORE_MILVUS_TOKEN=
 VECTOR_STORE_MILVUS_DB_NAME=
-VECTOR_STORE_MILVUS_CONSISTENCY_LEVEL=
+VECTOR_STORE_MILVUS_CONSISTENCY_LEVEL=Session
 ```
 
 ## Monitoring
@@ -711,6 +711,7 @@ ENABLED = false
 [vector_store]
 TYPE = "pgvector"
 MILVUS_URI = "./milvus.db"
+MILVUS_CONSISTENCY_LEVEL = "Session"
 
 [sentry]
 ENABLED = false
diff --git a/scripts/configure_embeddings.py b/scripts/configure_embeddings.py
@@ -16,9 +16,9 @@
 Existing 1536 deployments need no action — step 2 is a no-op when settings
 already match the schema.
 
-This script never creates or modifies external-store namespaces. Turbopuffer
-and LanceDB namespaces are per-workspace and lazy-created on first write by
-application code; their dim is implicitly pinned at that point. Use
+This script never creates or modifies external-store namespaces. Turbopuffer,
+LanceDB, and Milvus namespaces are per-workspace and lazy-created on first write
+by application code; their dim is implicitly pinned at that point. Use
 ``--report`` to enumerate existing namespaces against the configured dim.
 """
 
diff --git a/src/config.py b/src/config.py
@@ -1378,7 +1378,7 @@ class VectorStoreSettings(HonchoSettings):
     MILVUS_DB_NAME: str | None = None
     MILVUS_CONSISTENCY_LEVEL: (
         Literal["Strong", "Session", "Bounded", "Eventually"] | None
-    ) = None
+    ) = "Session"
 
     RECONCILIATION_INTERVAL_SECONDS: Annotated[int, Field(default=300, gt=0)] = (
         300  # 5 minutes
diff --git a/src/vector_store/milvus.py b/src/vector_store/milvus.py
@@ -11,6 +11,8 @@
 import logging
 import re
 from collections.abc import Callable, Sequence
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as package_version
 from typing import Any, ParamSpec, TypeVar, cast
 
 from pymilvus import DataType, MilvusClient
@@ -46,6 +48,16 @@
 _UNSAFE_COLLECTION_CHARS = re.compile(r"[^A-Za-z0-9_]")
 
 
+def _uses_lite_3_cosine_distance(uri: str) -> bool:
+    """Return whether the client uses Milvus Lite 3.0 distance semantics."""
+    if "://" in uri:
+        return False
+    try:
+        return package_version("milvus-lite") in {"3.0", "3.0.0"}
+    except PackageNotFoundError:
+        return False
+
+
 class MilvusVectorStore(VectorStore):
     """
     Milvus implementation of the VectorStore interface.
@@ -364,6 +376,10 @@ async def query(
             "limit": top_k,
             "search_params": {"metric_type": DISTANCE_METRIC},
         }
+        if settings.VECTOR_STORE.MILVUS_CONSISTENCY_LEVEL:
+            search_kwargs["consistency_level"] = (
+                settings.VECTOR_STORE.MILVUS_CONSISTENCY_LEVEL
+            )
         if output_fields is not None:
             search_kwargs["output_fields"] = output_fields
 
@@ -399,11 +415,16 @@ async def query(
 
     def _hit_cosine_distance(self, hit: dict[str, Any]) -> float:
         """Return Honcho cosine distance from a Milvus search hit."""
-        if "distance" in hit:
-            return float(hit["distance"])
-        if "score" in hit:
-            return 1.0 - float(hit["score"])
-        return 0.0
+        if "distance" not in hit:
+            return 0.0
+
+        raw_distance = float(hit["distance"])
+        # Milvus Lite 3.0 reports COSINE distance while Milvus server and
+        # Zilliz Cloud report COSINE similarity. Keep this workaround scoped
+        # to the affected Lite release: https://github.com/milvus-io/milvus-lite/issues/343
+        if _uses_lite_3_cosine_distance(settings.VECTOR_STORE.MILVUS_URI):
+            return raw_distance
+        return 1.0 - raw_distance
 
     def _output_fields(self, include_attributes: bool | list[str]) -> list[str] | None:
         """Translate Honcho projection settings to Milvus output fields."""
diff --git a/tests/conftest.py b/tests/conftest.py
@@ -80,8 +80,6 @@ def emit(self, record: logging.LogRecord):
     "tests/alembic/",
     "tests/unified/",
     "tests/live_llm/",
-    # Vector-store provider tests exercise SDK behavior directly and do not need DB setup.
-    "tests/vector_store/",
     # Pure llm unit tests should stay isolated from the broader app/runtime fixtures.
     "tests/llm/",
     # LLM transport tests mock providers directly and don't need database/runtime setup.
diff --git a/tests/llm/test_model_config.py b/tests/llm/test_model_config.py
@@ -324,9 +324,9 @@ def test_app_settings_explicit_vector_store_dimensions_warns_and_overrides() ->
     messages = [
         str(w.message) for w in captured if issubclass(w.category, DeprecationWarning)
     ]
-    assert any("VECTOR_STORE_DIMENSIONS is deprecated" in m for m in messages), (
-        f"expected deprecation warning, got {messages!r}"
-    )
+    assert any(
+        "VECTOR_STORE_DIMENSIONS is deprecated" in m for m in messages
+    ), f"expected deprecation warning, got {messages!r}"
     assert settings.EMBEDDING.VECTOR_DIMENSIONS == 2048
     assert settings.VECTOR_STORE.DIMENSIONS == 2048, (
         "EMBEDDING.VECTOR_DIMENSIONS should always overwrite the operator-supplied "
diff --git a/tests/vector_store/test_milvus.py b/tests/vector_store/test_milvus.py
@@ -5,11 +5,10 @@
 import logging
 import re
 from pathlib import Path
-from typing import Any, cast
 
 import pytest
 
-from src.config import settings
+from src.config import VectorStoreSettings, settings
 from src.vector_store import VectorRecord
 from src.vector_store.milvus import (
     MAX_COLLECTION_NAME_LENGTH,
@@ -24,27 +23,9 @@ def _helper_store() -> MilvusVectorStore:
     return object.__new__(MilvusVectorStore)
 
 
-class _ScoreOnlySearchClient:
-    def has_collection(self, *, collection_name: str) -> bool:
-        assert collection_name
-        return True
-
-    def search(self, **kwargs: Any) -> list[list[dict[str, Any]]]:
-        assert kwargs["search_params"] == {"metric_type": "COSINE"}
-        return [
-            [
-                {
-                    "id": "vec_close",
-                    "score": 0.9,
-                    "entity": {"message_id": "msg_1"},
-                },
-                {
-                    "id": "vec_far",
-                    "score": 0.2,
-                    "entity": {"message_id": "msg_2"},
-                },
-            ]
-        ]
+def test_default_consistency_level_is_session() -> None:
+    consistency_field = VectorStoreSettings.model_fields["MILVUS_CONSISTENCY_LEVEL"]
+    assert consistency_field.default == "Session"
 
 
 def test_collection_name_is_valid_stable_and_bounded() -> None:
@@ -96,23 +77,20 @@ def test_projection_settings_map_to_milvus_output_fields() -> None:
     ]
 
 
-@pytest.mark.asyncio
-async def test_query_converts_milvus_score_to_cosine_distance(
+def test_cosine_distance_normalizes_real_milvus_distance_field(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
-    monkeypatch.setattr(settings.EMBEDDING, "VECTOR_DIMENSIONS", 4)
+    def milvus_lite_version(_: str) -> str:
+        return "3.0"
+
     store = _helper_store()
-    store.client = cast(Any, _ScoreOnlySearchClient())
 
-    results = await store.query(
-        "honcho.msg.test",
-        [1.0, 0.0, 0.0, 0.0],
-        max_distance=0.5,
-    )
+    monkeypatch.setattr(settings.VECTOR_STORE, "MILVUS_URI", "./milvus.db")
+    monkeypatch.setattr("src.vector_store.milvus.package_version", milvus_lite_version)
+    assert store._hit_cosine_distance({"distance": 0.0}) == 0.0  # pyright: ignore[reportPrivateUsage]
 
-    assert [result.id for result in results] == ["vec_close"]
-    assert abs(results[0].score - 0.1) < 1e-12
-    assert results[0].metadata == {"message_id": "msg_1"}
+    monkeypatch.setattr(settings.VECTOR_STORE, "MILVUS_URI", "http://localhost:19530")
+    assert store._hit_cosine_distance({"distance": 1.0}) == 0.0  # pyright: ignore[reportPrivateUsage]
 
 
 @pytest.mark.asyncio
@@ -124,7 +102,7 @@ async def test_milvus_lite_round_trip(
     )
     monkeypatch.setattr(settings.VECTOR_STORE, "MILVUS_TOKEN", None)
     monkeypatch.setattr(settings.VECTOR_STORE, "MILVUS_DB_NAME", None)
-    monkeypatch.setattr(settings.VECTOR_STORE, "MILVUS_CONSISTENCY_LEVEL", "Strong")
+    monkeypatch.setattr(settings.VECTOR_STORE, "MILVUS_CONSISTENCY_LEVEL", "Session")
     monkeypatch.setattr(settings.EMBEDDING, "VECTOR_DIMENSIONS", 4)
 
     store = MilvusVectorStore()
