feat(vector): add save/load persistence to VectorRetriever

  Add VectorRetriever.save() and VectorRetriever.load() for FAISS-backed
  file persistence. save() writes the vector index and a .registry JSON
  sidecar; load() restores both. InMemoryVectorStore raises
  NotImplementedError. Add 3 tests (save/load roundtrip, registry
  integrity, InMemory raises).

Author: seyoung4503

src/lang2sql/components/retrieval/vector.py

@@ -168,6 +168,78 @@ def add(self, chunks: list[IndexedChunk]) -> None:
         self._vectorstore.upsert(ids, vectors)
         self._registry.update({c["chunk_id"]: c for c in chunks})
 
+    # ── Persistence ──────────────────────────────────────────────────
+
+    def save(self, path: str) -> None:
+        """벡터 인덱스와 registry를 path에 저장.
+
+        FAISSVectorStore처럼 save()를 지원하는 store에서만 동작한다.
+        InMemoryVectorStore 등 save()가 없는 store는 NotImplementedError.
+
+        저장 파일:
+            {path}          — FAISSVectorStore 벡터 인덱스
+            {path}.meta     — chunk_id 순서 목록 (FAISSVectorStore 내부)
+            {path}.registry — registry JSON
+        """
+        import json
+        import pathlib
+
+        save_fn = getattr(self._vectorstore, "save", None)
+        if save_fn is None:
+            raise NotImplementedError(
+                f"{type(self._vectorstore).__name__} does not support save(). "
+                "Use FAISSVectorStore for file-based persistence."
+            )
+        save_fn(path)
+        pathlib.Path(path + ".registry").write_text(
+            json.dumps(self._registry), encoding="utf-8"
+        )
+
+    @classmethod
+    def load(
+        cls,
+        path: str,
+        *,
+        embedding: EmbeddingPort,
+        top_n: int = 5,
+        score_threshold: float = 0.0,
+        name: Optional[str] = None,
+        hook: Optional[TraceHook] = None,
+    ) -> "VectorRetriever":
+        """저장된 인덱스와 registry를 복원해 VectorRetriever를 반환.
+
+        save()로 저장한 path를 그대로 전달한다.
+        embedding은 쿼리 시 embed_query()에 사용되므로 반드시 전달해야 한다.
+
+        Args:
+            path:            save() 시 사용한 경로.
+            embedding:       EmbeddingPort 구현체.
+            top_n:           최대 반환 스키마/컨텍스트 수. 기본 5.
+            score_threshold: 이 점수 이하는 결과에서 제외. 기본 0.0.
+        """
+        import json
+        import pathlib
+
+        from ...integrations.vectorstore.faiss_ import FAISSVectorStore
+
+        registry_path = pathlib.Path(path + ".registry")
+        if not registry_path.exists():
+            raise FileNotFoundError(f"Registry file not found: {registry_path}")
+
+        store = FAISSVectorStore.load(path)
+        registry = json.loads(registry_path.read_text(encoding="utf-8"))
+        return cls(
+            vectorstore=store,
+            embedding=embedding,
+            registry=registry,
+            top_n=top_n,
+            score_threshold=score_threshold,
+            name=name,
+            hook=hook,
+        )
+
+    # ── Core retrieval ────────────────────────────────────────────────
+
     def _run(self, query: str) -> RetrievalResult:
         """
         Args:

tests/test_components_vector_retriever.py

@@ -502,3 +502,74 @@ def test_catalog_chunker_split_batch():
     by_chunk = [c for entry in CATALOG for c in chunker.chunk(entry)]
 
     assert [c["chunk_id"] for c in by_split] == [c["chunk_id"] for c in by_chunk]
+
+
+# ---------------------------------------------------------------------------
+# 20-22. VectorRetriever save / load (FAISS 필요)
+# ---------------------------------------------------------------------------
+
+faiss = pytest.importorskip("faiss", reason="faiss-cpu not installed")
+
+
+class FakeEmbeddingFAISS:
+    """FAISS L2 정규화에서 zero-vector 오류가 안 나도록 비영벡터를 반환."""
+
+    def _vec(self, text: str) -> list[float]:
+        # 텍스트별로 구별 가능한 비영벡터
+        h = abs(hash(text)) % 900 + 100
+        return [h * 0.001, 1.0, 1.0, 1.0]
+
+    def embed_query(self, text: str) -> list[float]:
+        return self._vec(text)
+
+    def embed_texts(self, texts: list[str]) -> list[list[float]]:
+        return [self._vec(t) for t in texts]
+
+
+def test_save_and_load_returns_same_results(tmp_path):
+    """save → load 후 동일 쿼리에 동일 스키마가 반환된다."""
+    path = str(tmp_path / "catalog")
+    embedding = FakeEmbeddingFAISS()
+
+    from lang2sql.integrations.vectorstore.faiss_ import FAISSVectorStore
+
+    store = FAISSVectorStore(index_path=path + ".faiss")
+    chunks = CatalogChunker().split(CATALOG)
+    original = VectorRetriever.from_chunks(chunks, embedding=embedding, vectorstore=store)
+    original.save(path)
+
+    loaded = VectorRetriever.load(path, embedding=embedding)
+    result = loaded.run("주문 정보")
+
+    assert len(result.schemas) > 0
+    assert result.schemas[0]["name"] == original.run("주문 정보").schemas[0]["name"]
+
+
+def test_load_registry_intact(tmp_path):
+    """load 후 registry의 키·값이 원본과 동일하다."""
+    path = str(tmp_path / "catalog")
+    embedding = FakeEmbeddingFAISS()
+
+    from lang2sql.integrations.vectorstore.faiss_ import FAISSVectorStore
+
+    store = FAISSVectorStore(index_path=path + ".faiss")
+    chunks = CatalogChunker().split(CATALOG)
+    original = VectorRetriever.from_chunks(chunks, embedding=embedding, vectorstore=store)
+    original.save(path)
+
+    loaded = VectorRetriever.load(path, embedding=embedding)
+
+    assert set(loaded._registry.keys()) == set(original._registry.keys())
+    for chunk_id, chunk in original._registry.items():
+        assert loaded._registry[chunk_id]["text"] == chunk["text"]
+        assert loaded._registry[chunk_id]["source_id"] == chunk["source_id"]
+
+
+def test_save_raises_for_inmemory():
+    """InMemoryVectorStore는 save()를 지원하지 않아 NotImplementedError가 발생한다."""
+    embedding = FakeEmbeddingFAISS()
+    chunks = CatalogChunker().split(CATALOG)
+    retriever = VectorRetriever.from_chunks(chunks, embedding=embedding)  # InMemory 기본값
+
+    with pytest.raises(NotImplementedError, match="does not support save"):
+        retriever.save("/tmp/should_not_exist")