langchain-memvid 0.0.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,28 @@
1
+ BSD 3-Clause License
2
+
3
+ Copyright (c) 2025, Dawid Ciepiela
4
+
5
+ Redistribution and use in source and binary forms, with or without
6
+ modification, are permitted provided that the following conditions are met:
7
+
8
+ 1. Redistributions of source code must retain the above copyright notice, this
9
+ list of conditions and the following disclaimer.
10
+
11
+ 2. Redistributions in binary form must reproduce the above copyright notice,
12
+ this list of conditions and the following disclaimer in the documentation
13
+ and/or other materials provided with the distribution.
14
+
15
+ 3. Neither the name of the copyright holder nor the names of its
16
+ contributors may be used to endorse or promote products derived from
17
+ this software without specific prior written permission.
18
+
19
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
20
+ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
22
+ DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
23
+ FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24
+ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
25
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
26
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
27
+ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
@@ -0,0 +1,176 @@
1
+ Metadata-Version: 2.4
2
+ Name: langchain-memvid
3
+ Version: 0.0.1
4
+ Summary: Langchain implementation for Memvid
5
+ Author-email: Dawid Ciepiela <71898979+sarumaj@users.noreply.github.com>
6
+ License: BSD-3-Clause
7
+ Classifier: Programming Language :: Python :: 3.12
8
+ Classifier: License :: OSI Approved :: BSD License
9
+ Classifier: Operating System :: OS Independent
10
+ Requires-Python: >=3.12
11
+ Description-Content-Type: text/markdown
12
+ License-File: LICENSE
13
+ Requires-Dist: faiss-cpu==1.11.0
14
+ Requires-Dist: langchain-core==0.3.58
15
+ Requires-Dist: nest_asyncio==1.6.0
16
+ Requires-Dist: qrcode[pil]==8.2
17
+ Requires-Dist: opencv-contrib-python==4.11.0.86
18
+ Requires-Dist: opencv-python==4.11.0.86
19
+ Requires-Dist: orjson==3.10.18
20
+ Requires-Dist: pydantic==2.11.7
21
+ Requires-Dist: msgpack==1.1.1
22
+ Requires-Dist: msgpack-numpy==0.4.8
23
+ Requires-Dist: tqdm==4.67.1
24
+ Provides-Extra: test
25
+ Requires-Dist: pytest==8.0.0; extra == "test"
26
+ Provides-Extra: pdf
27
+ Requires-Dist: pypdf==5.6.0; extra == "pdf"
28
+ Provides-Extra: epub
29
+ Requires-Dist: beautifulsoup4==4.13.4; extra == "epub"
30
+ Requires-Dist: ebooklib==0.18; extra == "epub"
31
+ Provides-Extra: all
32
+ Requires-Dist: opencv-contrib-python==4.11.0.86; extra == "all"
33
+ Requires-Dist: opencv-python==4.11.0.86; extra == "all"
34
+ Requires-Dist: pypdf==5.6.0; extra == "all"
35
+ Requires-Dist: beautifulsoup4==4.13.4; extra == "all"
36
+ Requires-Dist: ebooklib==0.18; extra == "all"
37
+ Requires-Dist: pytest==8.0.0; extra == "all"
38
+ Dynamic: license-file
39
+
40
+ [![release](https://github.com/sarumaj/langchain-memvid/actions/workflows/release.yml/badge.svg)](https://github.com/sarumaj/langchain-memvid/actions/workflows/release.yml)
41
+ [![GitHub Release](https://img.shields.io/github/v/release/sarumaj/langchain-memvid?logo=github)](https://github.com/sarumaj/langchain-memvid/releases/latest)
42
+ [![Libraries.io dependency status for GitHub repo](https://img.shields.io/librariesio/github/sarumaj/langchain-memvid)](https://github.com/sarumaj/langchain-memvid/blob/main/pyproject.toml)
43
+
44
+ ---
45
+
46
+ # Langchain Memvid
47
+
48
+ A Langchain implementation for Memvid, enabling efficient video-based document storage and retrieval using vector embeddings.
49
+
50
+ ## Overview
51
+
52
+ Langchain Memvid is a powerful tool that combines the capabilities of Langchain with video-based document storage. It allows you to store text chunks in video frames using QR codes and retrieve them efficiently using vector similarity search. This approach provides a unique way to store and retrieve information while maintaining visual accessibility.
53
+
54
+ ## Features
55
+
56
+ - **Vector Store Integration**: Seamless integration with Langchain's vector store interface
57
+ - **Video-based Storage**: Store text chunks in video frames using QR codes
58
+ - **Efficient Retrieval**: Fast similarity search using FAISS indexing
59
+ - **Flexible Configuration**: Customizable settings for encoding, indexing, and retrieval
60
+ - **Multiple Embedding Models**: Support for various embedding models through Langchain
61
+ - **Granular Control**: Access to low-level components for fine-tuned control
62
+
63
+ ## Installation
64
+
65
+ ```bash
66
+ pip install langchain-memvid
67
+ ```
68
+
69
+ Optional dependencies:
70
+ ```bash
71
+ # For testing
72
+ pip install langchain-memvid[test]
73
+
74
+ # For PDF support
75
+ pip install langchain-memvid[pdf]
76
+
77
+ # For EPUB support
78
+ pip install langchain-memvid[epub]
79
+
80
+ # For all features
81
+ pip install langchain-memvid[all]
82
+ ```
83
+
84
+ ## Quick Start
85
+
86
+ ```python
87
+ from langchain_huggingface import HuggingFaceEmbeddings
88
+ from langchain_memvid import VectorStore, VectorStoreConfig
89
+
90
+ # Initialize vector store
91
+ vs_cfg = VectorStoreConfig()
92
+ embeddings = HuggingFaceEmbeddings()
93
+ vs = VectorStore(
94
+ video_file="output.mp4",
95
+ index_file="index.json",
96
+ embedding=embeddings,
97
+ config=vs_cfg
98
+ )
99
+
100
+ # Add text chunks
101
+ chunks = ["Important fact 1", "Important fact 2", "Historical event details"]
102
+ vs.add_texts(chunks)
103
+
104
+ # Search for similar content
105
+ results = vs.similarity_search("machine learning algorithms", top_k=3)
106
+ ```
107
+
108
+ ## Advanced Usage
109
+
110
+ For more granular control, you can use the individual components:
111
+
112
+ ```python
113
+ from langchain_memvid.index import IndexManager, IndexConfig
114
+ from langchain_memvid.retriever import Retriever, RetrieverConfig
115
+ from langchain_memvid.encoder import Encoder, EncoderConfig
116
+
117
+ # Initialize components
118
+ config = IndexConfig(index_type="Flat")
119
+ embeddings = HuggingFaceEmbeddings()
120
+ index_manager = IndexManager(config=config, embeddings=embeddings)
121
+
122
+ # Add and search chunks
123
+ chunks = ["text chunk 1", "text chunk 2"]
124
+ frame_numbers = [1, 2]
125
+ chunk_ids = index_manager.add_chunks(chunks, frame_numbers)
126
+ results = index_manager.search("query", top_k=5)
127
+
128
+ # Encode to video
129
+ enc_cfg = EncoderConfig()
130
+ encoder = Encoder(enc_cfg, index_manager)
131
+ encoder.add_chunks(chunks)
132
+ encoder.build_video(output_file="output.mp4", index_file="index.json")
133
+
134
+ # Retrieve from video
135
+ ret_cfg = RetrieverConfig()
136
+ retriever = Retriever("output.mp4", "index.json", ret_cfg, index_manager)
137
+ results = retriever.search_with_metadata("query", top_k=3)
138
+ ```
139
+
140
+ ## Requirements
141
+
142
+ - Python >= 3.12
143
+ - OpenCV
144
+ - FAISS
145
+ - Langchain
146
+ - Other dependencies as specified in pyproject.toml
147
+
148
+ ## License
149
+
150
+ This project is licensed under the BSD-3-Clause License - see the LICENSE file for details.
151
+
152
+ ## License Notices
153
+
154
+ This project uses several open-source libraries:
155
+
156
+ - FAISS is licensed under the Apache License 2.0
157
+ - OpenCV is licensed under the Apache License 2.0
158
+ - Langchain is licensed under the MIT License
159
+ - QRCode is licensed under the BSD License
160
+ - Pydantic is licensed under the MIT License
161
+ - Other dependencies are licensed under MIT, Apache 2.0, or AGPL-3.0
162
+
163
+ Full license texts for all dependencies are included in the `licenses` directory of this project. Each license file is named according to the project it belongs to (e.g., `licenses/faiss.txt`, `licenses/opencv.txt`, etc.).
164
+
165
+ For the original license texts and more information, please refer to the respective projects' repositories.
166
+
167
+ ## Acknowledgments
168
+
169
+ - [Langchain](https://github.com/langchain-ai/langchain) for providing the framework and tools for building LLM applications
170
+ - [Memvid](https://github.com/Olow304/memvid) for the original video-based document storage concept
171
+ - [FAISS](https://github.com/facebookresearch/faiss) for efficient similarity search
172
+ - [OpenCV](https://opencv.org/) for video processing capabilities
173
+ - [QRCode](https://github.com/lincolnloop/python-qrcode) for QR code generation
174
+ - [Pydantic](https://github.com/pydantic/pydantic) for data validation
175
+ - [BeautifulSoup4](https://www.crummy.com/software/BeautifulSoup/) for HTML parsing
176
+ - [EbookLib](https://github.com/aerkalov/ebooklib) for EPUB handling
@@ -0,0 +1,137 @@
1
+ [![release](https://github.com/sarumaj/langchain-memvid/actions/workflows/release.yml/badge.svg)](https://github.com/sarumaj/langchain-memvid/actions/workflows/release.yml)
2
+ [![GitHub Release](https://img.shields.io/github/v/release/sarumaj/langchain-memvid?logo=github)](https://github.com/sarumaj/langchain-memvid/releases/latest)
3
+ [![Libraries.io dependency status for GitHub repo](https://img.shields.io/librariesio/github/sarumaj/langchain-memvid)](https://github.com/sarumaj/langchain-memvid/blob/main/pyproject.toml)
4
+
5
+ ---
6
+
7
+ # Langchain Memvid
8
+
9
+ A Langchain implementation for Memvid, enabling efficient video-based document storage and retrieval using vector embeddings.
10
+
11
+ ## Overview
12
+
13
+ Langchain Memvid is a powerful tool that combines the capabilities of Langchain with video-based document storage. It allows you to store text chunks in video frames using QR codes and retrieve them efficiently using vector similarity search. This approach provides a unique way to store and retrieve information while maintaining visual accessibility.
14
+
15
+ ## Features
16
+
17
+ - **Vector Store Integration**: Seamless integration with Langchain's vector store interface
18
+ - **Video-based Storage**: Store text chunks in video frames using QR codes
19
+ - **Efficient Retrieval**: Fast similarity search using FAISS indexing
20
+ - **Flexible Configuration**: Customizable settings for encoding, indexing, and retrieval
21
+ - **Multiple Embedding Models**: Support for various embedding models through Langchain
22
+ - **Granular Control**: Access to low-level components for fine-tuned control
23
+
24
+ ## Installation
25
+
26
+ ```bash
27
+ pip install langchain-memvid
28
+ ```
29
+
30
+ Optional dependencies:
31
+ ```bash
32
+ # For testing
33
+ pip install langchain-memvid[test]
34
+
35
+ # For PDF support
36
+ pip install langchain-memvid[pdf]
37
+
38
+ # For EPUB support
39
+ pip install langchain-memvid[epub]
40
+
41
+ # For all features
42
+ pip install langchain-memvid[all]
43
+ ```
44
+
45
+ ## Quick Start
46
+
47
+ ```python
48
+ from langchain_huggingface import HuggingFaceEmbeddings
49
+ from langchain_memvid import VectorStore, VectorStoreConfig
50
+
51
+ # Initialize vector store
52
+ vs_cfg = VectorStoreConfig()
53
+ embeddings = HuggingFaceEmbeddings()
54
+ vs = VectorStore(
55
+ video_file="output.mp4",
56
+ index_file="index.json",
57
+ embedding=embeddings,
58
+ config=vs_cfg
59
+ )
60
+
61
+ # Add text chunks
62
+ chunks = ["Important fact 1", "Important fact 2", "Historical event details"]
63
+ vs.add_texts(chunks)
64
+
65
+ # Search for similar content
66
+ results = vs.similarity_search("machine learning algorithms", top_k=3)
67
+ ```
68
+
69
+ ## Advanced Usage
70
+
71
+ For more granular control, you can use the individual components:
72
+
73
+ ```python
74
+ from langchain_memvid.index import IndexManager, IndexConfig
75
+ from langchain_memvid.retriever import Retriever, RetrieverConfig
76
+ from langchain_memvid.encoder import Encoder, EncoderConfig
77
+
78
+ # Initialize components
79
+ config = IndexConfig(index_type="Flat")
80
+ embeddings = HuggingFaceEmbeddings()
81
+ index_manager = IndexManager(config=config, embeddings=embeddings)
82
+
83
+ # Add and search chunks
84
+ chunks = ["text chunk 1", "text chunk 2"]
85
+ frame_numbers = [1, 2]
86
+ chunk_ids = index_manager.add_chunks(chunks, frame_numbers)
87
+ results = index_manager.search("query", top_k=5)
88
+
89
+ # Encode to video
90
+ enc_cfg = EncoderConfig()
91
+ encoder = Encoder(enc_cfg, index_manager)
92
+ encoder.add_chunks(chunks)
93
+ encoder.build_video(output_file="output.mp4", index_file="index.json")
94
+
95
+ # Retrieve from video
96
+ ret_cfg = RetrieverConfig()
97
+ retriever = Retriever("output.mp4", "index.json", ret_cfg, index_manager)
98
+ results = retriever.search_with_metadata("query", top_k=3)
99
+ ```
100
+
101
+ ## Requirements
102
+
103
+ - Python >= 3.12
104
+ - OpenCV
105
+ - FAISS
106
+ - Langchain
107
+ - Other dependencies as specified in pyproject.toml
108
+
109
+ ## License
110
+
111
+ This project is licensed under the BSD-3-Clause License - see the LICENSE file for details.
112
+
113
+ ## License Notices
114
+
115
+ This project uses several open-source libraries:
116
+
117
+ - FAISS is licensed under the Apache License 2.0
118
+ - OpenCV is licensed under the Apache License 2.0
119
+ - Langchain is licensed under the MIT License
120
+ - QRCode is licensed under the BSD License
121
+ - Pydantic is licensed under the MIT License
122
+ - Other dependencies are licensed under MIT, Apache 2.0, or AGPL-3.0
123
+
124
+ Full license texts for all dependencies are included in the `licenses` directory of this project. Each license file is named according to the project it belongs to (e.g., `licenses/faiss.txt`, `licenses/opencv.txt`, etc.).
125
+
126
+ For the original license texts and more information, please refer to the respective projects' repositories.
127
+
128
+ ## Acknowledgments
129
+
130
+ - [Langchain](https://github.com/langchain-ai/langchain) for providing the framework and tools for building LLM applications
131
+ - [Memvid](https://github.com/Olow304/memvid) for the original video-based document storage concept
132
+ - [FAISS](https://github.com/facebookresearch/faiss) for efficient similarity search
133
+ - [OpenCV](https://opencv.org/) for video processing capabilities
134
+ - [QRCode](https://github.com/lincolnloop/python-qrcode) for QR code generation
135
+ - [Pydantic](https://github.com/pydantic/pydantic) for data validation
136
+ - [BeautifulSoup4](https://www.crummy.com/software/BeautifulSoup/) for HTML parsing
137
+ - [EbookLib](https://github.com/aerkalov/ebooklib) for EPUB handling
@@ -0,0 +1,61 @@
1
+ [build-system]
2
+ requires = ["setuptools>=42", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "langchain-memvid"
7
+ version = "0.0.1"
8
+ description = "Langchain implementation for Memvid"
9
+ requires-python = ">=3.12"
10
+ authors = [
11
+ { name="Dawid Ciepiela", email="71898979+sarumaj@users.noreply.github.com" }
12
+ ]
13
+ readme = "README.md"
14
+ license = { text = "BSD-3-Clause" }
15
+ classifiers = [
16
+ "Programming Language :: Python :: 3.12",
17
+ "License :: OSI Approved :: BSD License",
18
+ "Operating System :: OS Independent"
19
+ ]
20
+ dependencies = [
21
+ "faiss-cpu==1.11.0",
22
+ "langchain-core==0.3.58",
23
+ "nest_asyncio==1.6.0",
24
+ "qrcode[pil]==8.2",
25
+ "opencv-contrib-python==4.11.0.86",
26
+ "opencv-python==4.11.0.86",
27
+ "orjson==3.10.18",
28
+ "pydantic==2.11.7",
29
+ "msgpack==1.1.1",
30
+ "msgpack-numpy==0.4.8",
31
+ "tqdm==4.67.1"
32
+ ]
33
+
34
+ [project.optional-dependencies]
35
+ test = [
36
+ "pytest==8.0.0"
37
+ ]
38
+ pdf = [
39
+ "pypdf==5.6.0"
40
+ ]
41
+ epub = [
42
+ "beautifulsoup4==4.13.4",
43
+ "ebooklib==0.18"
44
+ ]
45
+ all = [
46
+ "opencv-contrib-python==4.11.0.86",
47
+ "opencv-python==4.11.0.86",
48
+ "pypdf==5.6.0",
49
+ "beautifulsoup4==4.13.4",
50
+ "ebooklib==0.18",
51
+ "pytest==8.0.0"
52
+ ]
53
+
54
+ [tool.setuptools.packages.find]
55
+ where = ["src"]
56
+ exclude = ["tests*", "nb*"]
57
+
58
+ [tool.pytest.ini_options]
59
+ pythonpath = ["src"]
60
+ testpaths = ["tests"]
61
+ addopts = ["-v"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,17 @@
1
+ from .vectorstore import VectorStore, VectorStoreConfig
2
+ from .retriever import Retriever, RetrieverConfig
3
+ from .encoder import Encoder, EncoderConfig
4
+ from .index import IndexManager, IndexConfig
5
+
6
+ __all__ = [
7
+ k for k, v in globals().items() if v in (
8
+ VectorStore,
9
+ Retriever,
10
+ Encoder,
11
+ IndexManager,
12
+ IndexConfig,
13
+ RetrieverConfig,
14
+ EncoderConfig,
15
+ VectorStoreConfig
16
+ )
17
+ ]
@@ -0,0 +1,86 @@
1
+ """
2
+ Configuration for Memvid.
3
+
4
+ Original source: https://github.com/Olow304/memvid/blob/main/memvid/config.py
5
+ """
6
+
7
+ from typing import TypedDict, Optional, Dict, Any
8
+
9
+
10
+ class VideoCodecConfig(TypedDict):
11
+ """Video codec configuration parameters."""
12
+ video_fps: int
13
+ frame_width: int
14
+ frame_height: int
15
+ video_preset: str
16
+ video_crf: int
17
+ pix_fmt: str
18
+ video_file_type: str
19
+ video_profile: str
20
+ extra_ffmpeg_args: Optional[str]
21
+
22
+
23
+ # Common video parameters
24
+ COMMON_PARAMS: Dict[str, Any] = {
25
+ "frame_height": 256,
26
+ "frame_width": 256,
27
+ "pix_fmt": "yuv420p",
28
+ }
29
+
30
+ # Common x265 parameters for still image optimization
31
+ STILL_IMAGE_PARAMS: str = (
32
+ "keyint=1:tune=stillimage:no-scenecut:strong-intra-smoothing:"
33
+ "constrained-intra:rect:amp"
34
+ )
35
+
36
+ MP4V_PARAMETERS: VideoCodecConfig = {
37
+ "video_file_type": "mp4",
38
+ "video_fps": 15,
39
+ "video_crf": 18, # Constant Rate Factor (0-51, lower = better quality)
40
+ "video_preset": "medium", # ultrafast, superfast, veryfast, faster, fast, medium
41
+ "video_profile": "high", # baseline, main, high (baseline for max compatibility)
42
+ "extra_ffmpeg_args": "-x265-params keyint=1:tune=stillimage",
43
+ **COMMON_PARAMS,
44
+ }
45
+
46
+ H265_PARAMETERS: VideoCodecConfig = {
47
+ "video_file_type": "mkv", # AKA HEVC
48
+ "video_fps": 30,
49
+ "video_crf": 28,
50
+ "video_preset": "slower",
51
+ "video_profile": "mainstillpicture",
52
+ "extra_ffmpeg_args": f"-x265-params {STILL_IMAGE_PARAMS}",
53
+ **COMMON_PARAMS,
54
+ }
55
+
56
+ H264_PARAMETERS: VideoCodecConfig = {
57
+ "video_file_type": "mkv", # AKA AVC
58
+ "video_fps": 30,
59
+ "video_crf": 28,
60
+ "video_preset": "slower",
61
+ "video_profile": "main",
62
+ "extra_ffmpeg_args": f"-x265-params {STILL_IMAGE_PARAMS}",
63
+ **COMMON_PARAMS,
64
+ }
65
+
66
+ AV1_PARAMETERS: VideoCodecConfig = {
67
+ "video_file_type": "mkv",
68
+ "video_crf": 28,
69
+ "video_fps": 60,
70
+ "frame_height": 720,
71
+ "frame_width": 720,
72
+ "video_preset": "slower",
73
+ "video_profile": "mainstillpicture",
74
+ "extra_ffmpeg_args": "-x265-params keyint=1:tune=stillimage",
75
+ "pix_fmt": "yuv420p",
76
+ }
77
+
78
+ # Video codec configuration parameters
79
+ CODEC_PARAMETERS: Dict[str, VideoCodecConfig] = {
80
+ "mp4v": MP4V_PARAMETERS,
81
+ "h265": H265_PARAMETERS,
82
+ "h264": H264_PARAMETERS,
83
+ "avc": H264_PARAMETERS,
84
+ "av1": AV1_PARAMETERS,
85
+ "hevc": H265_PARAMETERS
86
+ }