Building Graph-Enhanced GenAI Applications with the AWS Labs graphrag-toolkit

The landscape of generative artificial intelligence has evolved past simple text summarization and keyword matching, yet enterprise chatbots continue to struggle with nuanced, multi-layered inquiries. Traditional retrieval-augmented generation (RAG) frameworks rely heavily on vector databases that evaluate semantic similarity in isolated data chunks. While this approach efficiently answers straightforward queries—such as retrieving a company’s standard return policy—it systematically fails when faced with multi-hop questions requiring the synthesis of disparate facts spread across complex documentation. To bridge this architectural gap, developers are increasingly adopting graph-enhanced retrieval methodologies, commonly known as GraphRAG, which combine the structural clarity of knowledge graphs with the generative fluency of large language models.
Addressing the Limitations of Vector-Based Retrieval
Standard vector RAG architectures operate by breaking large documents into smaller text fragments, converting those fragments into numerical embeddings, and storing them in a vector index. When a user submits a query, the system performs a similarity search to find chunks that share the closest semantic distance to the question. However, this mechanism treats every chunk as an independent island, completely ignoring inter-document relationships, causal chains, or shared entity references.
When a query demands the connection of two separate pieces of information that never appear near each other in the source text, vector search fails because it lacks a mechanism to traverse semantic pathways. This is not a limitation that can be resolved simply by expanding the context window or tweaking prompt engineering. It is a structural shortcoming of the retrieval process itself. Multi-hop reasoning requires a system capable of mapping explicit entities and following the explicit relationships that bind them across an entire document repository.
The Convergence of Knowledge Graphs and Generative AI
Industry recognition of this challenge has led to independent innovations across the database sector. Major technology providers, including Neo4j and Oracle, have highlighted the necessity of integrating knowledge graphs into generative AI pipelines. By modeling data as interconnected nodes and edges rather than flat text files, organizations enable AI models to reason over structured facts.
This approach prevents hallucinations by grounding the generation process in verifiable relationships. Rather than forcing an LLM to guess how a warranty policy interacts with international shipping regulations based on isolated text fragments, a graph-enhanced system retrieves the exact structural pathway connecting those concepts. The resulting synergy ensures that the foundational context supplied to the model is both comprehensive and logically coherent.
Introducing the Open-Source graphrag-toolkit
To streamline the development of these advanced architectures, AWS Labs introduced the open-source graphrag-toolkit, licensed under the Apache 2.0 framework. The toolkit is specifically engineered to bridge the gap between unstructured enterprise data and structured graph representations. It comprises two primary components: the lexical-graph framework, designed for automatically building and querying hierarchical knowledge graphs from raw documents, and BYOKG-RAG (Bring Your Own Knowledge Graph), tailored for teams that already maintain structured graph databases.
The design principles behind the lexical-graph model are detailed in academic literature, specifically the research paper titled "Hierarchical Lexical Graph for Enhanced Multi-Hop Retrieval." Furthermore, enterprise adoption is already underway; organizations such as Deloitte have integrated lexical-graph capabilities into production environments, utilizing them within Amazon Neptune-based security intelligence platforms to process complex threat data.
Anatomy of a Lexical Graph: Extraction and Hierarchy
Understanding how the graphrag-toolkit constructs its underlying data structure is essential for building robust applications. According to the toolkit’s technical specifications, a lexical graph organizes ingested content into a six-tier hierarchy: source, chunk, topic, statement, fact, and entity. Unlike conventional vector systems that restrict retrieval to the chunk level, traversal-based queries can hop seamlessly across any of these hierarchical layers.
The pipeline operates through two strictly separated stages: extraction and building. During the extraction phase, raw source documents are ingested, divided into chunks, and processed by a foundation model to identify topics, statements, facts, and entities. The building stage then takes these extracted elements to populate the graph and vector stores. Maintaining these as distinct, resumable pipeline steps allows engineering teams to audit, filter, or pause large-scale ingestion jobs without data loss.
To maintain high extraction fidelity, the toolkit employs a multi-step LLM invocation process for each chunk. The initial pass refines raw text into self-contained propositions, while a secondary pass extracts the structured entities and facts from those cleaned propositions rather than the unstructured source text. This optional preprocessing step measurably improves the quality and precision of the resulting knowledge graph.
Technical Architecture and Stack Flexibility

Implementing a graph-enhanced RAG application requires careful consideration of underlying storage and model infrastructure. The graphrag-toolkit offers modular compatibility with several industry-standard databases and vector indices, allowing developers to tailor their deployments to specific cost and performance requirements.
Supported infrastructure components include:
- Graph Stores: Amazon Neptune Database, Amazon Neptune Analytics, Neo4j, and FalkorDB.
- Vector Stores: Amazon Neptune, Amazon OpenSearch Serverless, PostgreSQL with the pgvector extension, and Amazon S3 Vectors.
- Foundation Models: Amazon Bedrock serves as the native model provider, integrating securely via SigV4 request signing and TLS 1.3 protocols.
For development and local testing environments, pairing Neo4j and PostgreSQL with pgvector inside containerized Docker instances offers a zero-infrastructure-cost alternative to cloud-managed services. This local configuration enables rapid prototyping before transitioning workloads to enterprise-grade cloud environments like AWS.
Hands-On Implementation: Building a Multi-Hop Research Assistant
To demonstrate the practical application of the graphrag-toolkit, developers can construct a localized research assistant designed to synthesize information across multiple distinct Wikipedia articles—specifically focusing on complex topics such as human spaceflight, the Artemis program, the International Space Station, and the Commercial Crew Program.
Step 1: Containerized Database Initialization
Using Docker Compose, spin up local instances of Neo4j and PostgreSQL configured with the pgvector extension.
services:
neo4j:
image: neo4j:5
ports:
- "7474:7474"
- "7687:7687"
environment:
- NEO4J_AUTH=neo4j/graphrag-password
postgres:
image: pgvector/pgvector:pg16
ports:
- "5432:5432"
environment:
- POSTGRES_PASSWORD=graphrag-password
- POSTGRES_DB=graphrag
Executing docker compose up -d initializes both databases, exposing Neo4j on port 7687 and PostgreSQL on port 5432.
Step 2: Environment and Dependency Setup
Install the necessary Python packages, ensuring compatibility with Python 3.10 or higher.
pip install graphrag-lexical-graph
pip install psycopg2-binary pgvector
pip install llama-index-readers-web html2text
The graphrag-lexical-graph package provides the core toolkit functionalities, while psycopg2-binary and pgvector facilitate database connectivity for vector embeddings. Web reading utilities are imported via LlamaIndex to ingest source documentation.
Step 3: Graph Extraction and Construction
With the storage layers active, source articles can be ingested, processed, and transformed into a hierarchical lexical graph.
from graphrag_toolkit.lexical_graph import LexicalGraphIndex
from graphrag_toolkit.lexical_graph.storage import GraphStoreFactory, VectorStoreFactory
from llama_index.readers.web import SimpleWebPageReader
neo4j_connection = "neo4j://neo4j:graphrag-password@localhost:7687"
postgres_connection = "postgresql://postgres:graphrag-password@localhost:5432/graphrag"
with (
GraphStoreFactory.for_graph_store(neo4j_connection) as graph_store,
VectorStoreFactory.for_vector_store(
postgres_connection,
index_names=["chunk"],
) as vector_store,
):
graph_index = LexicalGraphIndex(graph_store, vector_store)
docs = SimpleWebPageReader(html_to_text=True).load_data([
"https://en.wikipedia.org/wiki/Artemis_program",
"https://en.wikipedia.org/wiki/International_Space_Station",
"https://en.wikipedia.org/wiki/Commercial_Crew_Program",
])
graph_index.extract_and_build(docs, show_progress=True)
The factory methods automatically detect the database backends based on the connection string schemes. The extract_and_build method executes the entire pipeline utilizing Amazon Bedrock for the underlying LLM calls.
Step 4: Query Execution via Traversal-Based Search
Once the graph is constructed, queries are processed using traversal-based search engines rather than traditional vector similarity alone.
from graphrag_toolkit.lexical_graph import LexicalGraphQueryEngine
query_engine = LexicalGraphQueryEngine.for_traversal_based_search(
graph_store,
vector_store,
versioning=False,
)
response = query_engine.query(
"How does the Commercial Crew Program relate to crew transport "
"for the International Space Station, and how might that "
"connect to Artemis program crew logistics?"
)
print(response)
The query engine leverages initial vector embeddings to identify anchor statements, subsequently traversing the graph’s entity and topic links to assemble a comprehensive context window before generating the final response.
Implications and Future Enterprise Applications
The transition from flat vector search to graph-enhanced retrieval marks a significant maturation in enterprise generative AI. By anchoring LLM generation in explicit, structured relationships, organizations can deploy AI assistants capable of auditing financial records, parsing intricate legal frameworks, and diagnosing complex technical systems with unprecedented accuracy.
As frameworks like the graphrag-toolkit continue to mature—incorporating Model Context Protocol (MCP) server integration, multi-tenancy support, and automated versioning—knowledge graphs will likely become a standard infrastructure requirement for production-grade GenAI deployments. Developers and enterprise architects who master these relational paradigms will be uniquely positioned to build resilient, trustworthy AI systems capable of handling the messy, interconnected realities of enterprise data.







