Feature/zvec vector db integration#168
Draft
esafwan wants to merge 8 commits into
Draft
Conversation
Introduce huf/ai/knowledge/embedding.py with LiteLLM-based embedding generation: - get_embedding() for single text embedding - get_embeddings() for batch embedding with auto-chunking - resolve_embedding_config() to read model/provider from Knowledge Source DocType and resolve API keys from AI Provider
Add huf/ai/knowledge/backends/zvec_backend.py implementing the KnowledgeBackend ABC using Zvec (Alibaba Proxima-based engine): - initialize(): create/open .zvec collection with typed schema - add_chunks(): batch-embed text via embedding module, upsert docs - delete_chunks(): filter-based deletion by input_id - search(): embed query + approximate nearest-neighbor search - clear(): drop and recreate collection - get_stats(): doc count and on-disk size Collections stored in /private/files/knowledge/ for portability.
Add huf/ai/knowledge/backends/zvec_llamaindex.py bridging Zvec collections to LlamaIndex's BasePydanticVectorStore interface: - add(): convert LlamaIndex BaseNode to zvec.Doc and upsert - delete(): remove documents by ref_doc_id - query(): translate VectorStoreQuery to zvec.VectorQuery Optional adapter for LlamaIndex pipeline compatibility.
- Register 'zvec' backend type in get_backend() factory - Add 'zvec' option to knowledge_type field in Knowledge Source JSON - Add Vector Settings section with embedding_model, vector_dimension, and embedding_provider fields (visible only when knowledge_type=zvec) - Add validate_zvec_settings() in knowledge_source.py - Update knowledge_source.js: remove sqlite_fts-only restriction, add dynamic field visibility for vector settings
Add _build_backend_config() helper that constructs the config dict for backend.initialize(). For zvec sources it includes embedding_model, vector_dimension, and embedding_provider from the Knowledge Source doc. Used in both process_knowledge_input() and rebuild_knowledge_index().
Zvec is the in-process vector database engine (based on Alibaba Proxima) used by ZvecBackend for portable semantic search.
Alibaba's zvec only ships wheels for Python 3.10-3.12, which conflicts with Frappe 16's Python 3.13+ requirement. Switch to tridz-zvec, a fork of alibaba/zvec at github.com/tridz-dev/zvec that adds cp313 and cp314 wheel targets. The import name (import zvec) is unchanged.
Contributor
Author
TODO before this PR is taken up: align with the HUF knowledge-backend standardSince this PR was opened, HUF adopted the cross-backend contract in PR #280 (pgvector + generic Like #149, zvec has no LlamaIndex integration, so it must justify itself under the portable-exception clause (shareable local file, zero external services) or be dropped in favor of
See the cross-backend audit (A3 / P2 reconcile historical vector backends) and use |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Zvec Portable Vector Database Integration
Summary
This PR integrates Zvec as an in-process, portable vector database for HUF's knowledge system. It sets up the backend infrastructure, adds LlamaIndex adapters, and registers Zvec as a Knowledge Source backend.
Additionally, due to Frappe 16's Python 3.13+ requirements, this PR switches the upstream
zvecdependency to a custom fork (tridz-zvec) that publishes wheels for modern Python versions.Features Added
1. Architectural Additions
2. Zvec Integration
ZvecBackendfor portable and fast local semantic search.VectorStoreadapter for Zvec.3. Build & Dependency Updates
tridz-zvecdependency topyproject.toml.🛠 Why a Custom Fork is Needed (
tridz-zvec)The Problem
zvecpublishes binary wheels only (no source distribution). Sopip install zvecfails outright on Python 3.13+. It’s still an alpha release (0.2.0) and hasn’t shipped wheels for Python 3.13 / 3.14 yet.What’s Actually Blocking Python 3.13+
The C++ core (pybind11 + CMake) is fine, and its dependency
numpy >= 1.23supports Python 3.13+. The blocker is purely inzvec'spyproject.tomlcibuildwheelconfiguration, which purposely stops atcp312-*.See upstream issue: alibaba/zvec#131 (No response yet).
The Solution:
tridz-zvec(TO BE DONE)To unblock development temporarily, a fork under
tridz-dev/zvecwas created and published:pyproject.tomlto build forcp313-*andcp314-*.tridz-zvec.import zvec), but the required package is nowtridz-zvec.Note: Once upstream
alibaba/zvecadds Python 3.13 support, we can switch the dependency name back tozvec.How to Test
Zvecis newly available as a backend vector.ZvecBackend).