grafeo-langchain 0.1.0__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.
- grafeo_langchain-0.1.0/.claude/.archive/grafeo-langchain.md +875 -0
- grafeo_langchain-0.1.0/.claude/ARCHITECTURE.md +75 -0
- grafeo_langchain-0.1.0/.claude/CLAUDE.md +95 -0
- grafeo_langchain-0.1.0/.claude/CODE_STYLE.md +77 -0
- grafeo_langchain-0.1.0/.claude/ROADMAP.md +32 -0
- grafeo_langchain-0.1.0/.claude/settings.local.json +24 -0
- grafeo_langchain-0.1.0/.claude/todo/phase-1-core.md +727 -0
- grafeo_langchain-0.1.0/.claude/todo/phase-2-polish.md +100 -0
- grafeo_langchain-0.1.0/.claude/todo/phase-3-advanced.md +88 -0
- grafeo_langchain-0.1.0/.github/workflows/ci.yml +30 -0
- grafeo_langchain-0.1.0/.github/workflows/pypi.yml +18 -0
- grafeo_langchain-0.1.0/.gitignore +39 -0
- grafeo_langchain-0.1.0/.pre-commit-config.yaml +7 -0
- grafeo_langchain-0.1.0/CONTRIBUTING.md +39 -0
- grafeo_langchain-0.1.0/LICENSE +201 -0
- grafeo_langchain-0.1.0/PKG-INFO +135 -0
- grafeo_langchain-0.1.0/README.md +113 -0
- grafeo_langchain-0.1.0/examples/basic_graph_store.py +68 -0
- grafeo_langchain-0.1.0/examples/graph_vector_rag.py +88 -0
- grafeo_langchain-0.1.0/pyproject.toml +66 -0
- grafeo_langchain-0.1.0/src/grafeo_langchain/__init__.py +13 -0
- grafeo_langchain-0.1.0/src/grafeo_langchain/graph_document.py +41 -0
- grafeo_langchain-0.1.0/src/grafeo_langchain/graph_store.py +146 -0
- grafeo_langchain-0.1.0/src/grafeo_langchain/graph_vector_store.py +269 -0
- grafeo_langchain-0.1.0/tests/__init__.py +0 -0
- grafeo_langchain-0.1.0/tests/conftest.py +46 -0
- grafeo_langchain-0.1.0/tests/test_graph_store.py +170 -0
- grafeo_langchain-0.1.0/tests/test_graph_vector_store.py +180 -0
- grafeo_langchain-0.1.0/tests/test_integration.py +66 -0
- grafeo_langchain-0.1.0/uv.lock +1044 -0
|
@@ -0,0 +1,875 @@
|
|
|
1
|
+
# grafeo-langchain
|
|
2
|
+
|
|
3
|
+
> LangChain GraphStore and GraphVectorStore backed by GrafeoDB — graph-enhanced retrieval in a single embedded file.
|
|
4
|
+
|
|
5
|
+
## Overview
|
|
6
|
+
|
|
7
|
+
A LangChain community integration that implements both `GraphStore` (for knowledge graph storage) and `GraphVectorStore` (for combined vector + graph retrieval) using GrafeoDB. This gives LangChain applications native graph traversal, multi-hop retrieval, and vector similarity search — all without running a separate database server.
|
|
8
|
+
|
|
9
|
+
## Why
|
|
10
|
+
|
|
11
|
+
- LangChain's `GraphVectorStore` combines vector search with graph traversal — exactly what Grafeo does natively
|
|
12
|
+
- Existing graph integrations (Neo4j, FalkorDB) require a running server — Grafeo is embedded
|
|
13
|
+
- The `langchain-graph-retriever` package adds traversal strategies (BFS, MMR) that benefit from a real graph engine
|
|
14
|
+
- One `.db` file replaces Neo4j server + separate vector store
|
|
15
|
+
|
|
16
|
+
## Repository
|
|
17
|
+
|
|
18
|
+
```
|
|
19
|
+
grafeo-langchain/
|
|
20
|
+
├── pyproject.toml
|
|
21
|
+
├── src/
|
|
22
|
+
│ └── grafeo_langchain/
|
|
23
|
+
│ ├── __init__.py # exports all public classes
|
|
24
|
+
│ ├── graph_store.py # GraphStore implementation
|
|
25
|
+
│ ├── graph_vector_store.py # GraphVectorStore implementation
|
|
26
|
+
│ └── graph_document.py # helpers for GraphDocument conversion
|
|
27
|
+
├── tests/
|
|
28
|
+
│ ├── conftest.py
|
|
29
|
+
│ ├── test_graph_store.py
|
|
30
|
+
│ ├── test_graph_vector_store.py
|
|
31
|
+
│ └── test_retriever.py
|
|
32
|
+
├── examples/
|
|
33
|
+
│ ├── basic_graph_store.py
|
|
34
|
+
│ ├── graph_vector_rag.py
|
|
35
|
+
│ ├── graph_retriever_traversal.py
|
|
36
|
+
│ └── hybrid_search.py
|
|
37
|
+
├── .github/
|
|
38
|
+
│ └── workflows/
|
|
39
|
+
│ └── ci.yml
|
|
40
|
+
└── README.md
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## Tooling
|
|
44
|
+
|
|
45
|
+
| Tool | Purpose |
|
|
46
|
+
|------|---------|
|
|
47
|
+
| **uv** | Package management, virtual environments, lockfile |
|
|
48
|
+
| **ruff** | Linting + formatting |
|
|
49
|
+
| **ty** | Type checking |
|
|
50
|
+
| **pytest** | Testing |
|
|
51
|
+
| **prek** | Git hooks for ruff + ty (pre-commit in Rust) |
|
|
52
|
+
|
|
53
|
+
## pyproject.toml
|
|
54
|
+
|
|
55
|
+
```toml
|
|
56
|
+
[project]
|
|
57
|
+
name = "grafeo-langchain"
|
|
58
|
+
version = "0.1.0"
|
|
59
|
+
description = "LangChain graph store and vector store backed by GrafeoDB embedded graph database"
|
|
60
|
+
readme = "README.md"
|
|
61
|
+
license = "Apache-2.0"
|
|
62
|
+
requires-python = ">=3.12"
|
|
63
|
+
authors = [{ name = "GrafeoDB" }]
|
|
64
|
+
keywords = ["langchain", "graph-store", "graph-rag", "grafeo", "knowledge-graph", "vector-search"]
|
|
65
|
+
classifiers = [
|
|
66
|
+
"Development Status :: 3 - Alpha",
|
|
67
|
+
"Intended Audience :: Developers",
|
|
68
|
+
"Topic :: Scientific/Engineering :: Artificial Intelligence",
|
|
69
|
+
"Topic :: Database :: Database Engines/Servers",
|
|
70
|
+
]
|
|
71
|
+
|
|
72
|
+
dependencies = [
|
|
73
|
+
"grafeo>=0.4",
|
|
74
|
+
"langchain-core>=0.3,<1",
|
|
75
|
+
]
|
|
76
|
+
|
|
77
|
+
[project.optional-dependencies]
|
|
78
|
+
retriever = ["langchain-graph-retriever>=0.3"]
|
|
79
|
+
|
|
80
|
+
[build-system]
|
|
81
|
+
requires = ["hatchling"]
|
|
82
|
+
build-backend = "hatchling.build"
|
|
83
|
+
|
|
84
|
+
[tool.hatch.build.targets.wheel]
|
|
85
|
+
packages = ["src/grafeo_langchain"]
|
|
86
|
+
|
|
87
|
+
# ── Ruff ──────────────────────────────────────────────────────────────
|
|
88
|
+
[tool.ruff]
|
|
89
|
+
target-version = "py312"
|
|
90
|
+
line-length = 100
|
|
91
|
+
|
|
92
|
+
[tool.ruff.lint]
|
|
93
|
+
select = ["E", "F", "W", "I", "UP", "B", "SIM", "RUF"]
|
|
94
|
+
|
|
95
|
+
# ── Ty ────────────────────────────────────────────────────────────────
|
|
96
|
+
[tool.ty]
|
|
97
|
+
python-version = "3.12"
|
|
98
|
+
|
|
99
|
+
# ── Pytest ────────────────────────────────────────────────────────────
|
|
100
|
+
[tool.pytest.ini_options]
|
|
101
|
+
testpaths = ["tests"]
|
|
102
|
+
|
|
103
|
+
# ── UV ────────────────────────────────────────────────────────────────
|
|
104
|
+
[tool.uv]
|
|
105
|
+
dev-dependencies = [
|
|
106
|
+
"pytest>=8",
|
|
107
|
+
"ruff>=0.11",
|
|
108
|
+
"ty>=0.1",
|
|
109
|
+
"langchain>=0.3",
|
|
110
|
+
"langchain-graph-retriever>=0.3",
|
|
111
|
+
]
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
## Interface Contracts
|
|
115
|
+
|
|
116
|
+
### 1. `GraphStore` — Knowledge graph storage
|
|
117
|
+
|
|
118
|
+
LangChain's `GraphStore` (from `langchain_community.graphs.graph_store`) is the base class for graph databases that store knowledge triples extracted by LLMs.
|
|
119
|
+
|
|
120
|
+
```python
|
|
121
|
+
class GraphStore(ABC):
|
|
122
|
+
"""Abstract class for graph stores."""
|
|
123
|
+
|
|
124
|
+
@property
|
|
125
|
+
@abstractmethod
|
|
126
|
+
def get_schema(self) -> str:
|
|
127
|
+
"""Return the schema of the graph store as a string."""
|
|
128
|
+
|
|
129
|
+
@property
|
|
130
|
+
@abstractmethod
|
|
131
|
+
def get_structured_schema(self) -> dict[str, Any]:
|
|
132
|
+
"""Return the structured schema of the graph store."""
|
|
133
|
+
|
|
134
|
+
@abstractmethod
|
|
135
|
+
def query(self, query: str, params: dict | None = None) -> list[dict[str, Any]]:
|
|
136
|
+
"""Query the graph store with a graph query language statement."""
|
|
137
|
+
|
|
138
|
+
@abstractmethod
|
|
139
|
+
def refresh_schema(self) -> None:
|
|
140
|
+
"""Refresh the schema of the graph store."""
|
|
141
|
+
|
|
142
|
+
def add_graph_documents(
|
|
143
|
+
self,
|
|
144
|
+
graph_documents: list[GraphDocument],
|
|
145
|
+
include_source: bool = False,
|
|
146
|
+
) -> None:
|
|
147
|
+
"""Add graph documents to the store. Default: NotImplementedError."""
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
### 2. `GraphVectorStore` — Vector + graph hybrid retrieval
|
|
151
|
+
|
|
152
|
+
LangChain's `GraphVectorStore` (from `langchain_core.graph_vectorstores`) combines a vector store with explicit document-to-document links for graph-enhanced retrieval.
|
|
153
|
+
|
|
154
|
+
```python
|
|
155
|
+
class GraphVectorStore(VectorStore):
|
|
156
|
+
"""Vector store with graph connections between documents.
|
|
157
|
+
|
|
158
|
+
Documents can be linked via metadata edges. Retrieval first finds
|
|
159
|
+
similar documents by vector, then traverses links to find
|
|
160
|
+
graph-connected documents.
|
|
161
|
+
"""
|
|
162
|
+
|
|
163
|
+
# Inherits from VectorStore:
|
|
164
|
+
# add_documents(documents, **kwargs) -> list[str]
|
|
165
|
+
# add_texts(texts, metadatas, **kwargs) -> list[str]
|
|
166
|
+
# similarity_search(query, k, **kwargs) -> list[Document]
|
|
167
|
+
# similarity_search_by_vector(embedding, k, **kwargs) -> list[Document]
|
|
168
|
+
|
|
169
|
+
# Additional graph methods:
|
|
170
|
+
def add_documents(
|
|
171
|
+
self,
|
|
172
|
+
documents: list[Document],
|
|
173
|
+
ids: list[str] | None = None,
|
|
174
|
+
**kwargs,
|
|
175
|
+
) -> list[str]:
|
|
176
|
+
"""Add documents with optional graph links in metadata."""
|
|
177
|
+
|
|
178
|
+
def similarity_search(
|
|
179
|
+
self,
|
|
180
|
+
query: str,
|
|
181
|
+
k: int = 4,
|
|
182
|
+
**kwargs,
|
|
183
|
+
) -> list[Document]:
|
|
184
|
+
"""Find similar documents, then optionally traverse graph links."""
|
|
185
|
+
|
|
186
|
+
def traversal_search(
|
|
187
|
+
self,
|
|
188
|
+
query: str,
|
|
189
|
+
k: int = 4,
|
|
190
|
+
depth: int = 1,
|
|
191
|
+
**kwargs,
|
|
192
|
+
) -> list[Document]:
|
|
193
|
+
"""Vector search + multi-hop graph traversal."""
|
|
194
|
+
|
|
195
|
+
def mmr_traversal_search(
|
|
196
|
+
self,
|
|
197
|
+
query: str,
|
|
198
|
+
k: int = 4,
|
|
199
|
+
depth: int = 2,
|
|
200
|
+
fetch_k: int = 100,
|
|
201
|
+
lambda_mult: float = 0.5,
|
|
202
|
+
**kwargs,
|
|
203
|
+
) -> list[Document]:
|
|
204
|
+
"""MMR-diversified graph traversal search."""
|
|
205
|
+
|
|
206
|
+
def as_retriever(self, **kwargs) -> GraphRetriever:
|
|
207
|
+
"""Create a GraphRetriever from this store."""
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
### 3. `GraphDocument` — LLM-extracted graph data
|
|
211
|
+
|
|
212
|
+
```python
|
|
213
|
+
# langchain_core.documents.base
|
|
214
|
+
class GraphDocument(BaseModel):
|
|
215
|
+
"""A document with extracted graph structure."""
|
|
216
|
+
nodes: list[Node]
|
|
217
|
+
relationships: list[Relationship]
|
|
218
|
+
source: Document
|
|
219
|
+
|
|
220
|
+
class Node(BaseModel):
|
|
221
|
+
id: str
|
|
222
|
+
type: str = "Node"
|
|
223
|
+
properties: dict[str, Any] = {}
|
|
224
|
+
|
|
225
|
+
class Relationship(BaseModel):
|
|
226
|
+
source: Node
|
|
227
|
+
target: Node
|
|
228
|
+
type: str
|
|
229
|
+
properties: dict[str, Any] = {}
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
## Implementation
|
|
233
|
+
|
|
234
|
+
### GrafeoGraphStore
|
|
235
|
+
|
|
236
|
+
```python
|
|
237
|
+
# src/grafeo_langchain/graph_store.py
|
|
238
|
+
"""GrafeoDB-backed GraphStore for LangChain."""
|
|
239
|
+
|
|
240
|
+
from __future__ import annotations
|
|
241
|
+
|
|
242
|
+
from typing import Any
|
|
243
|
+
|
|
244
|
+
import grafeo
|
|
245
|
+
from langchain_core.documents import Document
|
|
246
|
+
from langchain_core.documents.base import Node, Relationship, GraphDocument
|
|
247
|
+
|
|
248
|
+
|
|
249
|
+
class GrafeoGraphStore:
|
|
250
|
+
"""LangChain GraphStore backed by GrafeoDB.
|
|
251
|
+
|
|
252
|
+
Stores knowledge graph triples extracted by LLMs as native
|
|
253
|
+
Grafeo nodes and edges. Supports direct GQL/Cypher queries.
|
|
254
|
+
|
|
255
|
+
Args:
|
|
256
|
+
db_path: Path to persistent database file. None = in-memory.
|
|
257
|
+
"""
|
|
258
|
+
|
|
259
|
+
def __init__(self, db_path: str | None = None) -> None:
|
|
260
|
+
self._db_path = db_path
|
|
261
|
+
if db_path:
|
|
262
|
+
self._db = grafeo.GrafeoDB(db_path)
|
|
263
|
+
else:
|
|
264
|
+
self._db = grafeo.GrafeoDB()
|
|
265
|
+
|
|
266
|
+
if not self._db.has_property_index("node_id"):
|
|
267
|
+
self._db.create_property_index("node_id")
|
|
268
|
+
|
|
269
|
+
self._schema: dict[str, Any] | None = None
|
|
270
|
+
|
|
271
|
+
@property
|
|
272
|
+
def client(self) -> grafeo.GrafeoDB:
|
|
273
|
+
"""Return the underlying GrafeoDB instance."""
|
|
274
|
+
return self._db
|
|
275
|
+
|
|
276
|
+
@property
|
|
277
|
+
def get_schema(self) -> str:
|
|
278
|
+
"""Return the graph schema as a string for LLM prompts."""
|
|
279
|
+
schema = self.get_structured_schema
|
|
280
|
+
parts = []
|
|
281
|
+
if schema.get("labels"):
|
|
282
|
+
parts.append(f"Node labels: {', '.join(schema['labels'])}")
|
|
283
|
+
if schema.get("edge_types"):
|
|
284
|
+
parts.append(f"Relationship types: {', '.join(schema['edge_types'])}")
|
|
285
|
+
if schema.get("property_keys"):
|
|
286
|
+
parts.append(f"Properties: {', '.join(schema['property_keys'])}")
|
|
287
|
+
return "\n".join(parts) if parts else "Empty graph"
|
|
288
|
+
|
|
289
|
+
@property
|
|
290
|
+
def get_structured_schema(self) -> dict[str, Any]:
|
|
291
|
+
"""Return the structured graph schema."""
|
|
292
|
+
if self._schema is None:
|
|
293
|
+
self.refresh_schema()
|
|
294
|
+
return self._schema or {}
|
|
295
|
+
|
|
296
|
+
def query(self, query: str, params: dict | None = None) -> list[dict[str, Any]]:
|
|
297
|
+
"""Execute a GQL/Cypher query and return results as dicts.
|
|
298
|
+
|
|
299
|
+
Grafeo natively supports GQL (ISO standard) and Cypher (openCypher).
|
|
300
|
+
|
|
301
|
+
Examples:
|
|
302
|
+
store.query("MATCH (n:Person) RETURN n.name, n.age")
|
|
303
|
+
store.query("MATCH (a)-[:KNOWS]->(b) RETURN a.name, b.name")
|
|
304
|
+
"""
|
|
305
|
+
result = self._db.execute(query)
|
|
306
|
+
return [row for row in result]
|
|
307
|
+
|
|
308
|
+
def refresh_schema(self) -> None:
|
|
309
|
+
"""Refresh the cached schema from the database."""
|
|
310
|
+
self._schema = self._db.schema()
|
|
311
|
+
|
|
312
|
+
def add_graph_documents(
|
|
313
|
+
self,
|
|
314
|
+
graph_documents: list[GraphDocument],
|
|
315
|
+
include_source: bool = False,
|
|
316
|
+
) -> None:
|
|
317
|
+
"""Add LLM-extracted graph documents to the store.
|
|
318
|
+
|
|
319
|
+
Each GraphDocument contains nodes and relationships extracted
|
|
320
|
+
from a source document by an LLM (e.g. via LLMGraphTransformer).
|
|
321
|
+
|
|
322
|
+
Args:
|
|
323
|
+
graph_documents: List of GraphDocument objects with nodes and relationships.
|
|
324
|
+
include_source: If True, also store the source document text as a node
|
|
325
|
+
and link extracted entities to it.
|
|
326
|
+
"""
|
|
327
|
+
for graph_doc in graph_documents:
|
|
328
|
+
source_gid = None
|
|
329
|
+
|
|
330
|
+
# Optionally store the source document
|
|
331
|
+
if include_source and graph_doc.source:
|
|
332
|
+
source_gid = self._upsert_source_node(graph_doc.source)
|
|
333
|
+
|
|
334
|
+
# Upsert all nodes
|
|
335
|
+
node_id_map: dict[str, int] = {}
|
|
336
|
+
for node in graph_doc.nodes:
|
|
337
|
+
gid = self._upsert_node(node)
|
|
338
|
+
node_id_map[node.id] = gid
|
|
339
|
+
|
|
340
|
+
# Link to source document
|
|
341
|
+
if source_gid is not None:
|
|
342
|
+
self._db.create_edge(
|
|
343
|
+
source_id=gid,
|
|
344
|
+
target_id=source_gid,
|
|
345
|
+
edge_type="MENTIONED_IN",
|
|
346
|
+
)
|
|
347
|
+
|
|
348
|
+
# Upsert all relationships
|
|
349
|
+
for rel in graph_doc.relationships:
|
|
350
|
+
src_gid = node_id_map.get(rel.source.id)
|
|
351
|
+
tgt_gid = node_id_map.get(rel.target.id)
|
|
352
|
+
|
|
353
|
+
if src_gid is None:
|
|
354
|
+
src_gid = self._upsert_node(rel.source)
|
|
355
|
+
node_id_map[rel.source.id] = src_gid
|
|
356
|
+
if tgt_gid is None:
|
|
357
|
+
tgt_gid = self._upsert_node(rel.target)
|
|
358
|
+
node_id_map[rel.target.id] = tgt_gid
|
|
359
|
+
|
|
360
|
+
edge_type = rel.type.replace(" ", "_").replace("-", "_").upper()
|
|
361
|
+
self._db.create_edge(
|
|
362
|
+
source_id=src_gid,
|
|
363
|
+
target_id=tgt_gid,
|
|
364
|
+
edge_type=edge_type,
|
|
365
|
+
properties=rel.properties,
|
|
366
|
+
)
|
|
367
|
+
|
|
368
|
+
self._schema = None # Invalidate cache
|
|
369
|
+
|
|
370
|
+
def _upsert_node(self, node: Node) -> int:
|
|
371
|
+
"""Insert or find a graph node, returning the Grafeo node ID."""
|
|
372
|
+
matches = self._db.find_nodes_by_property("node_id", node.id)
|
|
373
|
+
if matches:
|
|
374
|
+
# Update properties on existing node
|
|
375
|
+
for key, value in node.properties.items():
|
|
376
|
+
self._db.set_node_property(matches[0], key, value)
|
|
377
|
+
return matches[0]
|
|
378
|
+
|
|
379
|
+
label = node.type.replace(" ", "_").replace("-", "_")
|
|
380
|
+
if not label.isidentifier():
|
|
381
|
+
label = "Node"
|
|
382
|
+
|
|
383
|
+
props = {"node_id": node.id, **node.properties}
|
|
384
|
+
created = self._db.create_node(labels=[label], properties=props)
|
|
385
|
+
return created.id
|
|
386
|
+
|
|
387
|
+
def _upsert_source_node(self, doc: Document) -> int:
|
|
388
|
+
"""Store a source document as a node."""
|
|
389
|
+
doc_id = doc.metadata.get("id", str(hash(doc.page_content[:200])))
|
|
390
|
+
matches = self._db.find_nodes_by_property("node_id", f"source_{doc_id}")
|
|
391
|
+
if matches:
|
|
392
|
+
return matches[0]
|
|
393
|
+
|
|
394
|
+
props = {
|
|
395
|
+
"node_id": f"source_{doc_id}",
|
|
396
|
+
"text": doc.page_content[:5000], # Cap text length
|
|
397
|
+
**{k: v for k, v in doc.metadata.items() if isinstance(v, (str, int, float, bool))},
|
|
398
|
+
}
|
|
399
|
+
created = self._db.create_node(labels=["SourceDocument"], properties=props)
|
|
400
|
+
return created.id
|
|
401
|
+
|
|
402
|
+
def close(self) -> None:
|
|
403
|
+
"""Close the database."""
|
|
404
|
+
self._db.close()
|
|
405
|
+
```
|
|
406
|
+
|
|
407
|
+
### GrafeoGraphVectorStore
|
|
408
|
+
|
|
409
|
+
```python
|
|
410
|
+
# src/grafeo_langchain/graph_vector_store.py
|
|
411
|
+
"""GrafeoDB-backed GraphVectorStore for LangChain."""
|
|
412
|
+
|
|
413
|
+
from __future__ import annotations
|
|
414
|
+
|
|
415
|
+
from typing import Any, Iterable
|
|
416
|
+
|
|
417
|
+
import grafeo
|
|
418
|
+
from langchain_core.documents import Document
|
|
419
|
+
from langchain_core.embeddings import Embeddings
|
|
420
|
+
from langchain_core.vectorstores import VectorStore
|
|
421
|
+
|
|
422
|
+
|
|
423
|
+
# Metadata key for explicit graph links between documents
|
|
424
|
+
_LINK_KEY = "__graph_links__"
|
|
425
|
+
|
|
426
|
+
|
|
427
|
+
class GrafeoGraphVectorStore(VectorStore):
|
|
428
|
+
"""Combined vector + graph store backed by GrafeoDB.
|
|
429
|
+
|
|
430
|
+
Documents are stored as nodes with embedding vectors for similarity
|
|
431
|
+
search. Documents can be explicitly linked to each other via metadata,
|
|
432
|
+
enabling graph-enhanced retrieval patterns.
|
|
433
|
+
|
|
434
|
+
The key insight: after vector search finds seed documents, graph
|
|
435
|
+
traversal discovers related documents that may not be semantically
|
|
436
|
+
similar but are structurally connected.
|
|
437
|
+
|
|
438
|
+
Args:
|
|
439
|
+
db_path: Path to persistent database. None = in-memory.
|
|
440
|
+
embedding: LangChain Embeddings instance for encoding text.
|
|
441
|
+
embedding_dimensions: Vector dimensionality.
|
|
442
|
+
"""
|
|
443
|
+
|
|
444
|
+
def __init__(
|
|
445
|
+
self,
|
|
446
|
+
embedding: Embeddings,
|
|
447
|
+
db_path: str | None = None,
|
|
448
|
+
embedding_dimensions: int = 1536,
|
|
449
|
+
) -> None:
|
|
450
|
+
self._embedding = embedding
|
|
451
|
+
self._db_path = db_path
|
|
452
|
+
self._dims = embedding_dimensions
|
|
453
|
+
|
|
454
|
+
if db_path:
|
|
455
|
+
self._db = grafeo.GrafeoDB(db_path)
|
|
456
|
+
else:
|
|
457
|
+
self._db = grafeo.GrafeoDB()
|
|
458
|
+
|
|
459
|
+
if not self._db.has_property_index("doc_id"):
|
|
460
|
+
self._db.create_property_index("doc_id")
|
|
461
|
+
|
|
462
|
+
self._index_created = False
|
|
463
|
+
|
|
464
|
+
@property
|
|
465
|
+
def embeddings(self) -> Embeddings:
|
|
466
|
+
return self._embedding
|
|
467
|
+
|
|
468
|
+
def _ensure_index(self) -> None:
|
|
469
|
+
if not self._index_created:
|
|
470
|
+
try:
|
|
471
|
+
self._db.create_vector_index(
|
|
472
|
+
label="Document",
|
|
473
|
+
property="embedding",
|
|
474
|
+
dimensions=self._dims,
|
|
475
|
+
metric="cosine",
|
|
476
|
+
)
|
|
477
|
+
except Exception:
|
|
478
|
+
pass
|
|
479
|
+
self._index_created = True
|
|
480
|
+
|
|
481
|
+
# ─── VectorStore interface ────────────────────────────────────────
|
|
482
|
+
|
|
483
|
+
def add_texts(
|
|
484
|
+
self,
|
|
485
|
+
texts: Iterable[str],
|
|
486
|
+
metadatas: list[dict] | None = None,
|
|
487
|
+
ids: list[str] | None = None,
|
|
488
|
+
**kwargs: Any,
|
|
489
|
+
) -> list[str]:
|
|
490
|
+
"""Add texts with embeddings and optional graph links."""
|
|
491
|
+
texts_list = list(texts)
|
|
492
|
+
metadatas = metadatas or [{} for _ in texts_list]
|
|
493
|
+
ids = ids or [str(i) for i in range(len(texts_list))]
|
|
494
|
+
|
|
495
|
+
# Embed all texts
|
|
496
|
+
embeddings = self._embedding.embed_documents(texts_list)
|
|
497
|
+
self._ensure_index()
|
|
498
|
+
|
|
499
|
+
created_ids: list[str] = []
|
|
500
|
+
for text, meta, doc_id, emb in zip(texts_list, metadatas, ids, embeddings):
|
|
501
|
+
# Extract graph links from metadata
|
|
502
|
+
links = meta.pop(_LINK_KEY, [])
|
|
503
|
+
|
|
504
|
+
props: dict[str, Any] = {
|
|
505
|
+
"doc_id": doc_id,
|
|
506
|
+
"text": text,
|
|
507
|
+
"embedding": emb,
|
|
508
|
+
}
|
|
509
|
+
# Store safe metadata as properties
|
|
510
|
+
for k, v in meta.items():
|
|
511
|
+
if isinstance(v, (str, int, float, bool)):
|
|
512
|
+
props[k] = v
|
|
513
|
+
|
|
514
|
+
node = self._db.create_node(labels=["Document"], properties=props)
|
|
515
|
+
|
|
516
|
+
# Create explicit graph links
|
|
517
|
+
for link in links:
|
|
518
|
+
target_matches = self._db.find_nodes_by_property("doc_id", link.get("target_id", ""))
|
|
519
|
+
edge_type = link.get("type", "LINKS_TO")
|
|
520
|
+
for target_gid in target_matches:
|
|
521
|
+
self._db.create_edge(
|
|
522
|
+
source_id=node.id,
|
|
523
|
+
target_id=target_gid,
|
|
524
|
+
edge_type=edge_type,
|
|
525
|
+
properties=link.get("properties", {}),
|
|
526
|
+
)
|
|
527
|
+
|
|
528
|
+
created_ids.append(doc_id)
|
|
529
|
+
|
|
530
|
+
return created_ids
|
|
531
|
+
|
|
532
|
+
def similarity_search_by_vector(
|
|
533
|
+
self,
|
|
534
|
+
embedding: list[float],
|
|
535
|
+
k: int = 4,
|
|
536
|
+
**kwargs: Any,
|
|
537
|
+
) -> list[Document]:
|
|
538
|
+
"""Find k most similar documents by vector."""
|
|
539
|
+
self._ensure_index()
|
|
540
|
+
|
|
541
|
+
results = self._db.vector_search(
|
|
542
|
+
label="Document",
|
|
543
|
+
property="embedding",
|
|
544
|
+
query=embedding,
|
|
545
|
+
k=k,
|
|
546
|
+
)
|
|
547
|
+
|
|
548
|
+
docs = []
|
|
549
|
+
for node_id, distance in results:
|
|
550
|
+
node = self._db.get_node(node_id)
|
|
551
|
+
if node is None:
|
|
552
|
+
continue
|
|
553
|
+
props = node.properties()
|
|
554
|
+
text = props.pop("text", "")
|
|
555
|
+
props.pop("embedding", None)
|
|
556
|
+
doc_id = props.pop("doc_id", str(node_id))
|
|
557
|
+
docs.append(Document(
|
|
558
|
+
page_content=text,
|
|
559
|
+
metadata={"id": doc_id, "score": 1.0 - distance, **props},
|
|
560
|
+
))
|
|
561
|
+
return docs
|
|
562
|
+
|
|
563
|
+
def similarity_search(
|
|
564
|
+
self,
|
|
565
|
+
query: str,
|
|
566
|
+
k: int = 4,
|
|
567
|
+
**kwargs: Any,
|
|
568
|
+
) -> list[Document]:
|
|
569
|
+
"""Embed query text and find similar documents."""
|
|
570
|
+
embedding = self._embedding.embed_query(query)
|
|
571
|
+
return self.similarity_search_by_vector(embedding, k=k, **kwargs)
|
|
572
|
+
|
|
573
|
+
# ─── Graph-enhanced retrieval ─────────────────────────────────────
|
|
574
|
+
|
|
575
|
+
def traversal_search(
|
|
576
|
+
self,
|
|
577
|
+
query: str,
|
|
578
|
+
k: int = 4,
|
|
579
|
+
depth: int = 1,
|
|
580
|
+
**kwargs: Any,
|
|
581
|
+
) -> list[Document]:
|
|
582
|
+
"""Vector search + graph traversal.
|
|
583
|
+
|
|
584
|
+
First finds seed documents by vector similarity, then traverses
|
|
585
|
+
graph links to discover connected documents up to `depth` hops.
|
|
586
|
+
"""
|
|
587
|
+
# Phase 1: Vector search for seed documents
|
|
588
|
+
seeds = self.similarity_search(query, k=k)
|
|
589
|
+
if not seeds:
|
|
590
|
+
return seeds
|
|
591
|
+
|
|
592
|
+
# Phase 2: Graph traversal from seed nodes
|
|
593
|
+
seen_ids: set[str] = {doc.metadata.get("id", "") for doc in seeds}
|
|
594
|
+
traversed: list[Document] = list(seeds)
|
|
595
|
+
|
|
596
|
+
for doc in seeds:
|
|
597
|
+
doc_id = doc.metadata.get("id", "")
|
|
598
|
+
if not doc_id:
|
|
599
|
+
continue
|
|
600
|
+
|
|
601
|
+
# Multi-hop traversal via GQL
|
|
602
|
+
result = self._db.execute(
|
|
603
|
+
f"MATCH (src {{doc_id: '{doc_id}'}})-[*1..{depth}]->(neighbor:Document) "
|
|
604
|
+
f"RETURN neighbor LIMIT {k * 2}"
|
|
605
|
+
)
|
|
606
|
+
for node in result.nodes():
|
|
607
|
+
props = node.properties()
|
|
608
|
+
nid = props.get("doc_id", str(node.id))
|
|
609
|
+
if nid in seen_ids:
|
|
610
|
+
continue
|
|
611
|
+
seen_ids.add(nid)
|
|
612
|
+
|
|
613
|
+
text = props.pop("text", "")
|
|
614
|
+
props.pop("embedding", None)
|
|
615
|
+
props.pop("doc_id", None)
|
|
616
|
+
traversed.append(Document(
|
|
617
|
+
page_content=text,
|
|
618
|
+
metadata={"id": nid, "source": "graph_traversal", **props},
|
|
619
|
+
))
|
|
620
|
+
|
|
621
|
+
return traversed[:k * 2] # Return up to 2x k (seeds + traversed)
|
|
622
|
+
|
|
623
|
+
def mmr_traversal_search(
|
|
624
|
+
self,
|
|
625
|
+
query: str,
|
|
626
|
+
k: int = 4,
|
|
627
|
+
depth: int = 2,
|
|
628
|
+
fetch_k: int = 100,
|
|
629
|
+
lambda_mult: float = 0.5,
|
|
630
|
+
**kwargs: Any,
|
|
631
|
+
) -> list[Document]:
|
|
632
|
+
"""MMR-diversified graph traversal.
|
|
633
|
+
|
|
634
|
+
Uses Maximal Marginal Relevance to balance relevance and diversity
|
|
635
|
+
among the vector search + graph traversal results.
|
|
636
|
+
"""
|
|
637
|
+
# Phase 1: Get a large candidate set via traversal
|
|
638
|
+
candidates = self.traversal_search(query, k=fetch_k, depth=depth)
|
|
639
|
+
if len(candidates) <= k:
|
|
640
|
+
return candidates
|
|
641
|
+
|
|
642
|
+
# Phase 2: MMR re-ranking
|
|
643
|
+
query_embedding = self._embedding.embed_query(query)
|
|
644
|
+
candidate_embeddings: list[list[float]] = []
|
|
645
|
+
for doc in candidates:
|
|
646
|
+
doc_id = doc.metadata.get("id", "")
|
|
647
|
+
matches = self._db.find_nodes_by_property("doc_id", doc_id)
|
|
648
|
+
if matches:
|
|
649
|
+
node = self._db.get_node(matches[0])
|
|
650
|
+
emb = node.get("embedding") if node else None
|
|
651
|
+
if emb:
|
|
652
|
+
candidate_embeddings.append(emb)
|
|
653
|
+
continue
|
|
654
|
+
# Fallback: re-embed
|
|
655
|
+
candidate_embeddings.append(self._embedding.embed_query(doc.page_content[:500]))
|
|
656
|
+
|
|
657
|
+
# Greedy MMR selection
|
|
658
|
+
selected_indices = _mmr_select(
|
|
659
|
+
query_embedding=query_embedding,
|
|
660
|
+
candidate_embeddings=candidate_embeddings,
|
|
661
|
+
k=k,
|
|
662
|
+
lambda_mult=lambda_mult,
|
|
663
|
+
)
|
|
664
|
+
return [candidates[i] for i in selected_indices]
|
|
665
|
+
|
|
666
|
+
# ─── Utilities ────────────────────────────────────────────────────
|
|
667
|
+
|
|
668
|
+
@classmethod
|
|
669
|
+
def from_texts(
|
|
670
|
+
cls,
|
|
671
|
+
texts: list[str],
|
|
672
|
+
embedding: Embeddings,
|
|
673
|
+
metadatas: list[dict] | None = None,
|
|
674
|
+
db_path: str | None = None,
|
|
675
|
+
**kwargs: Any,
|
|
676
|
+
) -> GrafeoGraphVectorStore:
|
|
677
|
+
"""Create a store from texts."""
|
|
678
|
+
store = cls(embedding=embedding, db_path=db_path, **kwargs)
|
|
679
|
+
store.add_texts(texts, metadatas=metadatas)
|
|
680
|
+
return store
|
|
681
|
+
|
|
682
|
+
@classmethod
|
|
683
|
+
def from_documents(
|
|
684
|
+
cls,
|
|
685
|
+
documents: list[Document],
|
|
686
|
+
embedding: Embeddings,
|
|
687
|
+
db_path: str | None = None,
|
|
688
|
+
**kwargs: Any,
|
|
689
|
+
) -> GrafeoGraphVectorStore:
|
|
690
|
+
"""Create a store from LangChain Documents."""
|
|
691
|
+
texts = [doc.page_content for doc in documents]
|
|
692
|
+
metadatas = [doc.metadata for doc in documents]
|
|
693
|
+
return cls.from_texts(texts, embedding, metadatas=metadatas, db_path=db_path, **kwargs)
|
|
694
|
+
|
|
695
|
+
def close(self) -> None:
|
|
696
|
+
"""Close the database."""
|
|
697
|
+
self._db.close()
|
|
698
|
+
|
|
699
|
+
|
|
700
|
+
def _mmr_select(
|
|
701
|
+
query_embedding: list[float],
|
|
702
|
+
candidate_embeddings: list[list[float]],
|
|
703
|
+
k: int,
|
|
704
|
+
lambda_mult: float,
|
|
705
|
+
) -> list[int]:
|
|
706
|
+
"""Maximal Marginal Relevance selection."""
|
|
707
|
+
import numpy as np
|
|
708
|
+
|
|
709
|
+
query = np.array(query_embedding)
|
|
710
|
+
candidates = np.array(candidate_embeddings)
|
|
711
|
+
|
|
712
|
+
# Cosine similarity: query vs all candidates
|
|
713
|
+
query_norm = query / (np.linalg.norm(query) + 1e-10)
|
|
714
|
+
cand_norms = candidates / (np.linalg.norm(candidates, axis=1, keepdims=True) + 1e-10)
|
|
715
|
+
query_sims = cand_norms @ query_norm
|
|
716
|
+
|
|
717
|
+
selected: list[int] = []
|
|
718
|
+
remaining = set(range(len(candidates)))
|
|
719
|
+
|
|
720
|
+
for _ in range(min(k, len(candidates))):
|
|
721
|
+
best_idx = -1
|
|
722
|
+
best_score = -float("inf")
|
|
723
|
+
|
|
724
|
+
for idx in remaining:
|
|
725
|
+
relevance = query_sims[idx]
|
|
726
|
+
|
|
727
|
+
# Max similarity to already-selected docs
|
|
728
|
+
if selected:
|
|
729
|
+
selected_vecs = cand_norms[selected]
|
|
730
|
+
redundancy = float(np.max(selected_vecs @ cand_norms[idx]))
|
|
731
|
+
else:
|
|
732
|
+
redundancy = 0.0
|
|
733
|
+
|
|
734
|
+
score = lambda_mult * relevance - (1 - lambda_mult) * redundancy
|
|
735
|
+
if score > best_score:
|
|
736
|
+
best_score = score
|
|
737
|
+
best_idx = idx
|
|
738
|
+
|
|
739
|
+
if best_idx >= 0:
|
|
740
|
+
selected.append(best_idx)
|
|
741
|
+
remaining.discard(best_idx)
|
|
742
|
+
|
|
743
|
+
return selected
|
|
744
|
+
```
|
|
745
|
+
|
|
746
|
+
### `__init__.py`
|
|
747
|
+
|
|
748
|
+
```python
|
|
749
|
+
# src/grafeo_langchain/__init__.py
|
|
750
|
+
from grafeo_langchain.graph_store import GrafeoGraphStore
|
|
751
|
+
from grafeo_langchain.graph_vector_store import GrafeoGraphVectorStore
|
|
752
|
+
|
|
753
|
+
__all__ = ["GrafeoGraphStore", "GrafeoGraphVectorStore"]
|
|
754
|
+
```
|
|
755
|
+
|
|
756
|
+
## Usage Examples
|
|
757
|
+
|
|
758
|
+
### Basic GraphStore with LLMGraphTransformer
|
|
759
|
+
|
|
760
|
+
```python
|
|
761
|
+
from langchain_openai import ChatOpenAI
|
|
762
|
+
from langchain_experimental.graph_transformers import LLMGraphTransformer
|
|
763
|
+
from langchain_core.documents import Document
|
|
764
|
+
|
|
765
|
+
from grafeo_langchain import GrafeoGraphStore
|
|
766
|
+
|
|
767
|
+
# 1. Extract knowledge graph from documents
|
|
768
|
+
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
|
|
769
|
+
transformer = LLMGraphTransformer(llm=llm)
|
|
770
|
+
|
|
771
|
+
documents = [
|
|
772
|
+
Document(page_content="Alice works at Microsoft. Bob works at Google. Alice knows Bob."),
|
|
773
|
+
]
|
|
774
|
+
graph_documents = transformer.convert_to_graph_documents(documents)
|
|
775
|
+
|
|
776
|
+
# 2. Store in Grafeo
|
|
777
|
+
store = GrafeoGraphStore(db_path="./knowledge.db")
|
|
778
|
+
store.add_graph_documents(graph_documents, include_source=True)
|
|
779
|
+
|
|
780
|
+
# 3. Query directly
|
|
781
|
+
results = store.query("MATCH (p:Person)-[:WORKS_AT]->(c) RETURN p.node_id, c.node_id")
|
|
782
|
+
for row in results:
|
|
783
|
+
print(row)
|
|
784
|
+
|
|
785
|
+
# 4. Check schema
|
|
786
|
+
print(store.get_schema)
|
|
787
|
+
# Node labels: Person, Organization, SourceDocument
|
|
788
|
+
# Relationship types: WORKS_AT, KNOWS, MENTIONED_IN
|
|
789
|
+
```
|
|
790
|
+
|
|
791
|
+
### GraphVectorStore with traversal
|
|
792
|
+
|
|
793
|
+
```python
|
|
794
|
+
from langchain_openai import OpenAIEmbeddings
|
|
795
|
+
|
|
796
|
+
from grafeo_langchain import GrafeoGraphVectorStore
|
|
797
|
+
|
|
798
|
+
embeddings = OpenAIEmbeddings(model="text-embedding-3-small")
|
|
799
|
+
|
|
800
|
+
# Create store with documents and explicit links
|
|
801
|
+
store = GrafeoGraphVectorStore(
|
|
802
|
+
embedding=embeddings,
|
|
803
|
+
db_path="./doc_graph.db",
|
|
804
|
+
embedding_dimensions=1536,
|
|
805
|
+
)
|
|
806
|
+
|
|
807
|
+
# Add documents with graph links in metadata
|
|
808
|
+
store.add_texts(
|
|
809
|
+
texts=[
|
|
810
|
+
"Python is a programming language created by Guido van Rossum.",
|
|
811
|
+
"Guido van Rossum also created the ABC programming language.",
|
|
812
|
+
"ABC influenced the design of Python.",
|
|
813
|
+
],
|
|
814
|
+
metadatas=[
|
|
815
|
+
{"id": "python", "__graph_links__": [{"target_id": "abc", "type": "INFLUENCED_BY"}]},
|
|
816
|
+
{"id": "guido"},
|
|
817
|
+
{"id": "abc", "__graph_links__": [{"target_id": "python", "type": "INFLUENCED"}]},
|
|
818
|
+
],
|
|
819
|
+
ids=["python", "guido", "abc"],
|
|
820
|
+
)
|
|
821
|
+
|
|
822
|
+
# Vector search only
|
|
823
|
+
docs = store.similarity_search("What programming languages exist?", k=2)
|
|
824
|
+
|
|
825
|
+
# Vector + graph traversal
|
|
826
|
+
docs = store.traversal_search("What programming languages exist?", k=4, depth=2)
|
|
827
|
+
|
|
828
|
+
# MMR-diversified graph traversal
|
|
829
|
+
docs = store.mmr_traversal_search("programming history", k=4, depth=2, lambda_mult=0.7)
|
|
830
|
+
```
|
|
831
|
+
|
|
832
|
+
### With langchain-graph-retriever
|
|
833
|
+
|
|
834
|
+
```python
|
|
835
|
+
from langchain_graph_retriever import GraphRetriever
|
|
836
|
+
from langchain_graph_retriever.strategies import Eager
|
|
837
|
+
|
|
838
|
+
from grafeo_langchain import GrafeoGraphVectorStore
|
|
839
|
+
|
|
840
|
+
store = GrafeoGraphVectorStore(embedding=embeddings, db_path="./graph.db")
|
|
841
|
+
|
|
842
|
+
# Create retriever with BFS traversal strategy
|
|
843
|
+
retriever = GraphRetriever(
|
|
844
|
+
store=store,
|
|
845
|
+
edges=[("entity", "RELATES_TO")],
|
|
846
|
+
strategy=Eager(k=5, start_k=2, depth=3),
|
|
847
|
+
)
|
|
848
|
+
|
|
849
|
+
docs = retriever.invoke("Tell me about AI research")
|
|
850
|
+
```
|
|
851
|
+
|
|
852
|
+
## Mapping: LangChain → Grafeo
|
|
853
|
+
|
|
854
|
+
| LangChain concept | Grafeo representation |
|
|
855
|
+
|---|---|
|
|
856
|
+
| `Node(id="alice", type="Person")` | `(:Person {node_id: "alice"})` |
|
|
857
|
+
| `Relationship(source, target, type="KNOWS")` | `(alice)-[:KNOWS]->(bob)` |
|
|
858
|
+
| `GraphDocument.source` | `(:SourceDocument {text: "...", node_id: "source_..."})` |
|
|
859
|
+
| `Document` (in GraphVectorStore) | `(:Document {doc_id: "...", text: "...", embedding: [...]})` |
|
|
860
|
+
| `__graph_links__` metadata | Grafeo edges between Document nodes |
|
|
861
|
+
| `store.query("MATCH ...")` | `db.execute("MATCH ...")` |
|
|
862
|
+
| `traversal_search(depth=2)` | `MATCH (n)-[*1..2]->(m)` variable-length path |
|
|
863
|
+
| Vector similarity search | `db.vector_search(label, property, query, k)` |
|
|
864
|
+
|
|
865
|
+
## Key Differentiators
|
|
866
|
+
|
|
867
|
+
| Feature | Neo4j GraphStore | Grafeo GraphStore |
|
|
868
|
+
|---|---|---|
|
|
869
|
+
| Requires server | Yes (Docker/Cloud) | **No** (embedded, pip install) |
|
|
870
|
+
| GraphStore | Yes | **Yes** |
|
|
871
|
+
| GraphVectorStore | Community package | **Built-in** (native HNSW) |
|
|
872
|
+
| Query language | Cypher | **GQL + Cypher + Gremlin** |
|
|
873
|
+
| Graph algorithms | GDS plugin ($$$) | **Built-in** (PageRank, Louvain, ...) |
|
|
874
|
+
| Deployment | Docker container | **Single .db file** |
|
|
875
|
+
| Offline/edge | No | **Yes** |
|