iText2KG: Incremental Knowledge Graphs Construction Using Large Language Models

🎉 Accepted @ WISE 2024

<img alt="Logo" src="https://github.com/AuvaLab/itext2kg/raw/v1.0.0/docs/logo_white.png" width="300">

Overview

iText2KG is a Python package designed to incrementally construct consistent knowledge graphs with resolved entities and relations by leveraging large language models for entity and relation extraction from text documents. It features zero-shot capability, allowing for knowledge extraction across various domains without specific training. The package includes modules for document distillation, entity extraction, and relation extraction, ensuring resolved and unique entities and relationships. It continuously updates the KG with new documents and integrates them into Neo4j for visual representation.

🔥 News

• [29/07/2025] New Features and Enhanced Capabilities:
• iText2KG_Star: Introduced a simpler and more efficient version of iText2KG that eliminates the separate entity extraction step. Instead of extracting entities and relations separately, iText2KG_Star directly extracts relationships from text, automatically deriving entities from those relationships. This approach is more efficient as it reduces processing time and token consumption and does not need to handle invented/isolated entities.
• Facts-Based KG Construction: Enhanced the framework with facts-based knowledge graph construction using the Document Distiller to extract structured facts from documents, which are then used for incremental KG building. This approach provides more exhaustive and precise knowledge graphs by focusing on factual information extraction.

• Dynamic Knowledge Graphs: iText2KG now supports building dynamic knowledge graphs that evolve over time. By leveraging the incremental nature of the framework and document snapshots with observation dates, users can track how knowledge changes and grows. See example: Dynamic KG Construction. NB: The temporal/logical conflicts resolution is not handled in this version. But you can apply a post processing filter to resolve them

• [19/07/2025] Major Performance and Reliability Updates:

• Asynchronous Architecture: Complete migration to async/await patterns for all core methods (build_graph, extract_entities, extract_relations, etc.) enabling better performance and non-blocking I/O operations with LLM APIs.
• Logging System: Implemented comprehensive logging infrastructure to replace all print statements with structured, configurable logging (DEBUG, INFO, WARNING, ERROR levels) with timestamps and module identification.
• Enhanced Batch Processing: Improved efficiency through async batch processing for multiple document handling and LLM API calls.

• Better Error Handling: Enhanced error handling and retry mechanisms with proper logging for production environments.

• [07/10/2024] Latest features:

• The entire iText2KG code has been refactored by adding data models that describe an Entity, a Relation, and a KnowledgeGraph.
• Each entity is embedded using both its name and label to avoid merging concepts with similar names but different labels. For example, Python:Language and Python:Snake.
  • The weights for entity name embedding and entity label are configurable, with defaults set to 0.4 for the entity label and 0.6 for the entity name.

• A max_tries parameter has been added to the iText2KG.build_graph function for entity and relation extraction to prevent hallucinatory effects in structuring the output. Additionally, a max_tries_isolated_entities parameter has been added to the same method to handle hallucinatory effects when processing isolated entities.

• [17/09/2024] Latest features:

• Now, iText2KG is compatible with all the chat/embeddings models supported by LangChain. For available chat models, refer to the options listed at: https://python.langchain.com/v0.2/docs/integrations/chat/. For embedding models, explore the choices at: https://python.langchain.com/v0.2/docs/integrations/text_embedding/.

• The constructed graph can be expanded by passing the already extracted entities and relationships as arguments to the build_graph function in iText2KG.

• iText2KG is compatible with all Python versions above 3.9.

• [16/07/2024] We have addressed two major LLM hallucination issues related to KG construction with LLMs when passing the entities list and context to the LLM. These issues are:

• The LLM might invent entities that do not exist in the provided entities list. We handled this problem by replacing the invented entities with the most similar ones from the input entities list.

• The LLM might fail to assign a relation to some entities from the input entities list, causing a "forgetting effect." We handled this problem by reprompting the LLM to extract relations for those entities.

Installation

To install iText2KG, ensure you have Python 3.9 or higher installed (required for async/await functionality), then use pip to install:

pip install itext2kg

The Overall Architecture

The iText2KG package consists of four main modules that work together to construct and visualize knowledge graphs from unstructured text. An overview of the overall architecture:

1. Document Distiller: This module processes raw documents and reformulates them into semantic blocks based on a user-defined schema. It improves the signal-to-noise ratio by focusing on relevant information and structuring it in a predefined format.

2. Incremental Entity Extractor: This module extracts unique entities from the semantic blocks and resolves ambiguities to ensure each entity is clearly defined. It uses cosine similarity measures to match local entities with global entities.

3. Incremental Relation Extractor: This module identifies relationships between the extracted entities. It can operate in two modes: using global entities to enrich the graph with potential information or using local entities for more precise relationships.

4. Graph Integrator and Visualization: This module integrates the extracted entities and relationships into a Neo4j database, providing a visual representation of the knowledge graph. It allows for interactive exploration and analysis of the structured data.

The LLM is prompted to extract entities representing one unique concept to avoid semantically mixed entities. The following figure presents the entity and relation extraction prompts using the Langchain JSON Parser. They are categorized as follows: Blue - prompts automatically formatted by Langchain; Regular - prompts we have designed; and Italic - specifically designed prompts for entity and relation extraction. (a) prompts for relation extraction and (b) prompts for entity extraction.

Modules and Examples

All the examples are provided in the following jupyter notebooks: - Different LLM Models - Basic usage with various language models - Dynamic Knowledge Graphs - Building evolving KGs with temporal context - Additional examples showcasing facts extraction, iText2KG_Star, and more advanced features

Now, iText2KG is compatible with all language models supported by LangChain.

To use iText2KG, you will need both a chat model and an embeddings model.

For available chat models, refer to the options listed at: https://python.langchain.com/v0.2/docs/integrations/chat/. For embedding models, explore the choices at: https://python.langchain.com/v0.2/docs/integrations/text_embedding/.

Please ensure that you install the necessary package for each chat model before use.

Mistral

For Mistral, please set up your model using the tutorial here: https://python.langchain.com/v0.2/docs/integrations/chat/mistralai/. Similarly, for the embedding model, follow the setup guide here: https://python.langchain.com/v0.2/docs/integrations/text_embedding/mistralai/ .

from langchain_mistralai import ChatMistralAI
from langchain_mistralai import MistralAIEmbeddings

mistral_api_key = "##"
mistral_llm_model = ChatMistralAI(
    api_key = mistral_api_key,
    model="mistral-large-latest",
    temperature=0,
    max_retries=2,
)


mistral_embeddings_model = MistralAIEmbeddings(
    model="mistral-embed",
    api_key = mistral_api_key
)

The Document Distiller module reformulates raw documents into predefined and semantic blocks using LLMs. It utilizes a schema to guide the extraction of specific information from each document.

OpenAI

The same applies for OpenAI.

please setup your model using the tutorial : https://python.langchain.com/v0.2/docs/integrations/chat/openai/ The same for embedding model : https://python.langchain.com/v0.2/docs/integrations/text_embedding/openai/

from langchain_openai import ChatOpenAI, OpenAIEmbeddings

openai_api_key = "##"

openai_llm_model = llm = ChatOpenAI(
    api_key = openai_api_key,
    model="gpt-4o",
    temperature=0,
    max_tokens=None,
    timeout=None,
    max_retries=2,
)

openai_embeddings_model = OpenAIEmbeddings(
    api_key = openai_api_key ,
    model="text-embedding-3-large",
)

The DocumentDistiller

Example

import asyncio
from itext2kg import DocumentDistiller
# You can define a schema or use the predefined ones from schemas.py
from itext2kg.models.schemas import Article

async def main():
    # Initialize the DocumentDistiller with llm model.
    document_distiller = DocumentDistiller(llm_model = openai_llm_model)

    # List of documents to be distilled.
    documents = ["doc1", "doc2", "doc3"]

    # Information extraction query.
    IE_query = '''
    # DIRECTIVES : 
    - Act like an experienced information extractor. 
    - You have a chunk of a scientific paper.
    - If you do not find the right information, keep its place empty.
    '''

    # Distill the documents using the defined query and output data structure.
    # Note: distill() is now async and requires await
    distilled_doc = await document_distiller.distill(documents=documents, IE_query=IE_query, output_data_structure=Article)

    return distilled_doc

# Run the async function
distilled_doc = asyncio.run(main())

The schema depends on the user's specific requirements, as it outlines the essential components to extract or emphasize during the knowledge graph construction. Since there is no universal blueprint for all use cases, its design is subjective and varies by application or context. This flexibility is crucial to making the iText2KG method adaptable across a wide range of scenarios.

You can define a custom schema using pydantic. Some example schemas are available in models/schemas.py. You can use these or create new ones depending on your use-case.

from typing import List, Optional
from pydantic import BaseModel, Field

# Define an Author model with name and affiliation fields.
class Author(BaseModel):
    name: str = Field(description="The name of the author")
    affiliation: str = Field(description="The affiliation of the author")

# Define an Article model with various fields describing a scientific article.
class Article(BaseModel):
    title: str = Field(description="The title of the scientific article")
    authors: List[Author] = Field(description="The list of the article's authors and their affiliation")
    abstract: str = Field(description="The article's abstract")
    key_findings: str = Field(description="The key findings of the article")
    limitation_of_sota: str = Field(description="limitation of the existing work")
    proposed_solution: str = Field(description="The proposed solution in details")
    paper_limitations: str = Field(description="The limitations of the proposed solution of the paper")

Facts-Based Knowledge Graph Construction

For more exhaustive knowledge graphs, you can use facts-based construction by extracting structured facts from documents first, then using these facts for KG building:

import asyncio
from itext2kg import DocumentDistiller
from itext2kg.models.schemas import Facts

async def extract_facts():
    # Initialize the DocumentDistiller
    document_distiller = DocumentDistiller(llm_model=openai_llm_model)

    # Your documents
    documents = ["OpenAI announced ChatGPT agent with new capabilities...", 
                 "The new model can perform complex tasks autonomously..."]

    # Extract facts from each document
    IE_query = '''
    # DIRECTIVES : 
    - Act like an experienced information extractor. 
    - Extract clear, factual statements from the text.
    '''

    facts_list = await asyncio.gather(*[
        document_distiller.distill(
            documents=[doc], 
            IE_query=IE_query, 
            output_data_structure=Facts
        ) for doc in documents
    ])

    return facts_list

# Run the async function
facts = asyncio.run(extract_facts())

Th