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.
Files changed (30) hide show
  1. grafeo_langchain-0.1.0/.claude/.archive/grafeo-langchain.md +875 -0
  2. grafeo_langchain-0.1.0/.claude/ARCHITECTURE.md +75 -0
  3. grafeo_langchain-0.1.0/.claude/CLAUDE.md +95 -0
  4. grafeo_langchain-0.1.0/.claude/CODE_STYLE.md +77 -0
  5. grafeo_langchain-0.1.0/.claude/ROADMAP.md +32 -0
  6. grafeo_langchain-0.1.0/.claude/settings.local.json +24 -0
  7. grafeo_langchain-0.1.0/.claude/todo/phase-1-core.md +727 -0
  8. grafeo_langchain-0.1.0/.claude/todo/phase-2-polish.md +100 -0
  9. grafeo_langchain-0.1.0/.claude/todo/phase-3-advanced.md +88 -0
  10. grafeo_langchain-0.1.0/.github/workflows/ci.yml +30 -0
  11. grafeo_langchain-0.1.0/.github/workflows/pypi.yml +18 -0
  12. grafeo_langchain-0.1.0/.gitignore +39 -0
  13. grafeo_langchain-0.1.0/.pre-commit-config.yaml +7 -0
  14. grafeo_langchain-0.1.0/CONTRIBUTING.md +39 -0
  15. grafeo_langchain-0.1.0/LICENSE +201 -0
  16. grafeo_langchain-0.1.0/PKG-INFO +135 -0
  17. grafeo_langchain-0.1.0/README.md +113 -0
  18. grafeo_langchain-0.1.0/examples/basic_graph_store.py +68 -0
  19. grafeo_langchain-0.1.0/examples/graph_vector_rag.py +88 -0
  20. grafeo_langchain-0.1.0/pyproject.toml +66 -0
  21. grafeo_langchain-0.1.0/src/grafeo_langchain/__init__.py +13 -0
  22. grafeo_langchain-0.1.0/src/grafeo_langchain/graph_document.py +41 -0
  23. grafeo_langchain-0.1.0/src/grafeo_langchain/graph_store.py +146 -0
  24. grafeo_langchain-0.1.0/src/grafeo_langchain/graph_vector_store.py +269 -0
  25. grafeo_langchain-0.1.0/tests/__init__.py +0 -0
  26. grafeo_langchain-0.1.0/tests/conftest.py +46 -0
  27. grafeo_langchain-0.1.0/tests/test_graph_store.py +170 -0
  28. grafeo_langchain-0.1.0/tests/test_graph_vector_store.py +180 -0
  29. grafeo_langchain-0.1.0/tests/test_integration.py +66 -0
  30. 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** |