DOCSEARCHbyAlgolia
Submit Docs

AWS GraphRAG Toolkit

repository·main·Indexed 19 days ago

https://github.com/awslabs/graphrag-toolkit

A Python-based suite of tools for building advanced Retrieval Augmented Generation (RAG) applications using graph structures. It includes the graphrag-byokg library (v3.18.1) for Bring Your Own Knowledge Graph (BYOKG) RAG, supporting Amazon Neptune Analytics, Neptune Database, and local stores. The toolkit features a multi-strategy retrieval approach—including agentic, scoring-based, path-based, and Cypher-based retrieval—and provides a hybrid development environment integrating Amazon Bedrock, S3, Neo4j, and PostgreSQL with pgvector.

Tokens
149.9K
Snippets
361
Records
502
Agent score
64%

What's inside graphrag-toolkit

  1. Overview of the GraphRAG Toolkit

    main

    The graphrag-toolkit is a collection of Python tools designed for building graph-enhanced Generative AI applications. It primarily consists of two major components:

    1. Lexical Graph: A framework for automating the construction of a hierarchical lexical graph from unstructured data. It allows you to compose question-answering strategies that query this graph to answer user questions.
    2. BYOKG-RAG (Bring Your Own Knowledge Graph): A Knowledge Graph Question Answering (KGQA) approach that combines Large Language Models (LLMs) with existing structured knowledge graphs, allowing users to perform complex queries over their own data.

    For detailed documentation and getting started, visit the official GraphRAG Toolkit Docs.

  2. Overview of the byokg-rag framework

    main

    The byokg-rag library is a framework for Knowledge Graph Question Answering (KGQA). It allows developers to combine Large Language Models (LLMs) with existing knowledge graphs to perform complex reasoning and question answering.

    It relies on two primary backend systems:

    1. Graph Store: Manages the knowledge graph data structure and provides interfaces for traversal and querying (e.g., Amazon Neptune).
    2. Foundation Model Provider: Hosts the LLMs used for entity linking, question understanding, and answer generation (e.g., Amazon Bedrock using BedrockGenerator).

  3. What is the lexical-graph library?

    main

    The graphrag-lexical-graph library is a framework designed to automate the construction of a hierarchical lexical graph from unstructured data.

    A hierarchical lexical graph is a graph structure that represents textual elements at multiple levels of granularity extracted from source documents. The toolkit allows you to compose question-answering strategies that query this graph to answer user questions.

  4. Overview of GraphRAG Toolkit capabilities

    main

    The GraphRAG Toolkit provides three primary capabilities for building graph-enhanced generative AI applications:

    • Lexical Graph: Automates the construction of hierarchical lexical graphs from unstructured documents for semantic-guided or traversal-based retrieval.
    • BYOKG-RAG (Bring Your Own Knowledge Graph): Allows you to plug an existing knowledge graph into a multi-strategy KGQA (Knowledge Graph Question Answering) pipeline without requiring re-extraction.
    • Pluggable Storage: Supports multiple backends for graph and vector storage:
      • Graph stores: Amazon Neptune (DB and Analytics), Neo4j, FalkorDB.
      • Vector stores: Neptune, OpenSearch, Postgres, S3 Vectors.

  5. Overview of Graph Retrievers in BYOKG-RAG

    main

    Graph retrievers in the BYOKG-RAG component implement different strategies for finding relevant information within a knowledge graph. All retrievers implement the GRetriever interface.

    Available strategies include:

    • Entity Linker: Connects natural language entities to specific graph nodes.
    • Agentic Retriever: Uses an LLM to perform iterative, dynamic graph exploration.
    • Graph Scoring Retriever: Uses multi-hop traversal combined with scoring and reranking.
    • Path Retriever: Focuses on finding and verbalizing paths (e.g., shortest paths or metapaths) between entities.
    • Graph Query Retriever: Executes structured graph queries and returns verbalized results.

  6. How StreamingJSONLReaderProvider works for large files

    main

    The StreamingJSONLReaderProvider is designed for memory-efficient processing of large JSONL files. Unlike the standard JSONReaderProvider, it processes files line-by-line with constant memory usage.

    Key Features

    • Memory Efficient: Processes files line-by-line.
    • Batch Processing: Yields documents in configurable batches via lazy_load_data.
    • S3 Support: Works with local files and S3 URIs.
    • Flexible Text Extraction: Can extract text from a specific field or use the entire JSON object.
    • Error Handling: strict_mode allows you to either raise errors on invalid lines or skip them.

    Metadata

    Each document includes:

    • file_path: Original source path (local or S3)
    • source: "local_file" or "s3"
    • line_number: 1-based line number
    • document_type: "jsonl"
    • Any additional fields from metadata_fn

  7. How the LexicalGraph indexing process works

    main

    Indexing in the Lexical Graph consists of two distinct stages: Extract and Build. These stages can be run together for continuous ingestion or separately for decoupled workflows.

    1. Extract Stage

    This stage transforms unstructured documents into structured metadata. It follows a three-step process:

    1. Chunking: Source documents are broken into chunks.
    2. Proposition Extraction (Optional): An LLM extracts simple propositions from chunks to 'clean' content (e.g., resolving pronouns, replacing acronyms). These are stored under the aws::graph::propositions metadata key.
    3. Entity/Topic Extraction (Mandatory): An LLM extracts entities, relations, topics, statements, and facts from the propositions (or raw text). These are stored under the aws::graph::topics metadata key.

    2. Build Stage

    This stage processes the LlamaIndex nodes emitted during extraction. It breaks them down into a stream of individual source, chunk, topic, statement, and fact nodes. Graph construction and vector indexing handlers then use these nodes to populate the backend graph and vector stores.

    Each node contains an aws::graph::index metadata item used for vector indexing (currently applied to chunk and statement nodes).

  8. Understand the BYOKG-RAG system components

    main

    The BYOKG-RAG system is composed of four main functional areas:

    1. ByoKGQueryEngine: The core orchestrator that implements iterative retrieval by combining multi-strategy and Cypher-based approaches.
    2. KG Linkers: Components like KGLinker (base class) and CypherKGLinker that map natural language queries to graph entities and relationships.
    3. Graph Retrievers: Specialized retrieval modules including:
      • AgenticRetriever: LLM-guided iterative exploration.
      • PathRetriever: Multi-hop reasoning via entity relationship paths.
      • GraphQueryRetriever: Direct Cypher query execution.
      • Rerankers: BGE-based semantic reranking.
    4. Graph Store: Manages the knowledge graph data structure and connectivity, supporting multiple backends (including local stores for development and Neptune for production).

  9. How Reader Providers work in GraphRAG Toolkit

    main

    The GraphRAG Toolkit uses a unified system of Reader Providers to ingest documents from diverse sources (files, databases, APIs, cloud storage) through a consistent interface.

    Core Abstractions

    • ReaderProvider: The abstract base class. All concrete readers implement the read(input_source) method, which returns a list of Document objects.
    • BaseReaderProvider: A base implementation that provides compatibility with both the GraphRAG ReaderProvider and LlamaIndex BaseReader interfaces.
    • LlamaIndexReaderProviderBase: A wrapper used to adapt existing LlamaIndex readers to the GraphRAG system.
    • ValidatedReaderProviderBase: An extension of the LlamaIndex wrapper that adds validation for inputs, outputs, and configurations.

    Configuration Pattern

    Every reader provider is paired with a specific configuration class (e.g., PDFReaderConfig, WebReaderConfig). These classes use Python dataclasses to define and validate the parameters required for a specific data source.

  10. How indexing works in byokg-rag

    main

    Indexing in byokg-rag enables entity linking by mapping natural language mentions to knowledge graph nodes. The system uses three complementary index types to match user queries to graph entities with varying degrees of precision and semantic understanding:

    1. Dense Index: Uses embeddings for semantic similarity matching. It captures meaning and context, allowing matches even when wording differs from the graph labels.
    2. Fuzzy String Index: Uses approximate string matching (Levenshtein distance) to handle typos, abbreviations, and minor spelling differences. It is fast and requires no external dependencies.
    3. Graph-store Index: Stores embeddings directly within the graph database (specifically Amazon Neptune Analytics), providing a unified storage layer for both graph structure and semantic embeddings.

    For most applications, it is recommended to start with a fuzzy string index and add semantic indexes (Dense or Graph-store) only if performance testing shows poor entity linking.

  11. How ByoKGQueryEngine works

    main

    The ByoKGQueryEngine is the central orchestrator for Bring Your Own Knowledge Graph (BYOKG) RAG. It coordinates graph connectors, retrievers, and LLMs to transform natural language questions into answers using graph data.

    It operates using two primary retrieval modes:

    1. Cypher-based retrieval: Uses a CypherKGLinker to generate and execute direct Cypher queries.
    2. Multi-strategy retrieval: Uses a KGLinker to perform iterative retrieval through agentic exploration (triplets), path finding (metapaths), and structured queries.

    The engine can run these modes independently or combine them, attempting Cypher-based retrieval first and falling back to multi-strategy retrieval if necessary.

    # Example of combining both approaches
query_engine = ByoKGQueryEngine(
    graph_store=graph_store,
    kg_linker=kg_linker,
    cypher_kg_linker=cypher_linker
)

# The engine will first try Cypher-based retrieval, then fall back to multi-strategy retrieval
context = query_engine.query(question)

  12. Understand the Summarisation tier: Facts, Statements, and Topics

    main

    The Summarisation tier provides the semantic hierarchy used for retrieval:

    Facts

    Summarize a single unit of meaning. There are two types:

    • SPO (Subject-Predicate-Object): Connected to both subject and object entities.
    • SPC (Subject-Predicate-Complement): Connected to a subject entity only (e.g., Neptune Analytics PURPOSE analyze graph data).
    • Facts provide connectivity across different sources. A single fact node can represent a piece of information mentioned in multiple documents.

    Statements

    The primary context unit for the LLM. Statements are connected transitively via facts and topics. They may also include inlined 'contextual details' (triplet-like data that lacks entity relations).

    Topics

    A theme or area of focus scoped to an individual source document. Topics provide connectivity between relevant chunks within a single source and act as document-level summaries.