Registry / llm-agents / graph-retriever

graph-retriever

JSON →
library0.8.0pypypi✓ verified 79d ago

Graph Retriever is a Python library that combines unstructured similarity search with structured document traversal to enhance Retrieval-Augmented Generation (RAG) applications. It enables traversing relationships between documents to find more relevant context than simple similarity search alone. The current version is 0.8.0, with minor releases occurring frequently, often driven by integration updates with DataStax Astra DB and other components.

pip install graph-retriever
INSTALL
IMPORT
SIG · GRAPH-RETRIEVER
G
graph-retriever
llm-agentspythonv0.8.0
Install
4.6s avg
Import
Disk
101MB
Pass rate
8/ 10
Env Coverage8 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.8.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
✓ —
✓ 4.8s
py 3.11
✓ —
✓ 4.65s
py 3.12
✓ —
✓ 4.55s
py 3.13
✓ —
✓ 4.55s
py 3.9
✕ build_error
✕ build_error
101MB installed
● package 101MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Content
from graph_retriever import Content
from graph_retriever import GraphRetriever
Node
from graph_retriever import Node
from graph_retriever import GraphRetriever
traverse
from graph_retriever import traverse
from graph_retriever import GraphRetriever

This quickstart demonstrates how to set up `GraphRetriever` with `AstraGraphStore`. It involves initializing an `AstraDB` connection, adding documents and edges to the graph store, defining a retrieval strategy (e.g., BFS), and then using the `GraphRetriever` to fetch relevant documents based on a query, considering both content similarity and graph structure. Ensure `ASTRA_DB_APPLICATION_TOKEN` and `ASTRA_DB_API_ENDPOINT` environment variables are set.

import os from astrapy.db import AstraDB from graph_retriever.graph_retriever import GraphRetriever from graph_retriever.retriever_strategies.graph_traversal import BFSTraversalStrategy from graph_retriever.document import Document from graph_retriever.graph_store.astra_graph_store import AstraGraphStore # Initialize AstraDB connection token = os.environ.get("ASTRA_DB_APPLICATION_TOKEN", "YOUR_ASTRA_DB_APPLICATION_TOKEN") api_endpoint = os.environ.get("ASTRA_DB_API_ENDPOINT", "YOUR_ASTRA_DB_API_ENDPOINT") if not token or not api_endpoint: raise ValueError("Please set ASTRA_DB_APPLICATION_TOKEN and ASTRA_DB_API_ENDPOINT environment variables.") astra_db = AstraDB(token=token, api_endpoint=api_endpoint) # Initialize GraphStore (using a test collection) graph_store = AstraGraphStore(astra_db=astra_db, collection_name="my_rag_collection") # Example documents and edges docs = [ Document(id="doc1", content="Python is a versatile programming language.", metadata={"topic": "programming"}), Document(id="doc2", content="Generative AI models are changing software development.", metadata={"topic": "AI"}), Document(id="doc3", content="Large Language Models (LLMs) are a type of Generative AI.", metadata={"topic": "AI"}) ] graph_store.add_documents(docs) graph_store.add_edge("doc1", "doc2", label="discusses_impact_on") graph_store.add_edge("doc2", "doc3", label="explains") # Initialize Retriever Strategy retriever_strategy = BFSTraversalStrategy(k=2, max_depth=1) # Retrieve 2 nodes, 1 depth # Initialize GraphRetriever # embedding_dimension is required for vector search, ensure it matches your embedding model retriever = GraphRetriever( graph_store=graph_store, retriever_strategy=retriever_strategy, embedding_dimension=1536 # Example: for OpenAI embeddings ) # Example query query_doc = Document(id="query_id", content="What are LLMs?") retrieved_nodes = retriever.get_relevant_documents(query_doc) print("\nRetrieved Nodes:") for node in retrieved_nodes: print(f" ID: {node.id}, Content: {node.content[:50]}...") # Optional: Clean up the collection (uncomment to run) # graph_store.clear_collection()
Debug
Known issues
breakingThe representation of document IDs on edges changed in `v0.6.0`. Previously, `Id()` objects were used; now, string IDs (e.g., `'$id'`) are preferred or required in many contexts.
fix
Update edge creation calls to pass string IDs directly instead of wrapping them in `Id()` objects, especially for system fields like `'$id'`.
affects: >=0.6.0
breakingThe internal design of retriever strategies was significantly refactored in `v0.5.0`, leading to potential changes in constructor parameters for various `RetrieverStrategy` implementations.
fix
Review the documentation or source code for the specific `RetrieverStrategy` class you are using to confirm correct parameter names and types after upgrading to `v0.5.0` or later.
affects: >=0.5.0
gotchaThe `k` parameter, used to specify the number of nodes to retrieve in strategies, was temporarily removed in `v0.5.0` and then restored in `v0.5.1`. This can cause `TypeError` for users on `v0.5.0` and then suddenly work again on `v0.5.1+`.
fix
If encountering issues with the `k` parameter, ensure you are running `v0.5.1` or later. If stuck on `v0.5.0`, remove the `k` parameter from strategy constructors or upgrade.
affects: 0.5.0
gotchaWhile `graph-retriever` itself has minimal direct dependencies, using the `AstraGraphStore` (a common use case) explicitly requires the `astrapy` library, which is not automatically installed with `graph-retriever`.
fix
Ensure you `pip install astrapy` if you plan to use `AstraGraphStore` for connecting to DataStax Astra DB.
affects: All versions
Upgrade
Version history
0.8.0latest on PyPI · released Apr 4, 2025
Audit
Dependencies
astrapyoptionalRequired for using AstraGraphStore, the primary graph store implementation for DataStax Astra DB.
Agent activity
39 hits · last 30 days
node
30
OpenAI (training)
1
Resources