British Aristocracy ChatBot

British Aristocracy ChatBot is an advanced Retrieval-Augmented Generation (RAG) system built entirely on a Knowledge Graph architecture. Instead of relying on traditional vector similarity search, this project leverages Neo4j and Google Gemini to deeply understand and navigate the complex web of lineages, marriages, and estates of the British Aristocracy. Users can interact with the system using natural language. The system dynamically translates these questions into precise database queries, navigates the historical graph, and synthesizes accurate, fact-based answers while completely eliminating AI hallucination.

Overview

GraphRAG: The British Aristocracy Explorer acts as an autonomous, graph-driven agent that interacts with complex historical data exactly like a researcher would: by navigating lineages, resolving identity overlaps, and reasoning over deep relationships. Powered by Neo4j and Google Gemini, this project bridges the gap between natural language processing and deterministic graph database execution.

Key Features:

• Intelligent Text-to-Cypher Translation: Instead of relying on traditional vector similarity search, the agent dynamically translates natural language into precise Cypher queries based on the injected graph schema. This guarantees relationship-aware data retrieval and eliminates the hallucination risks inherent to standard RAG setups.
• Autonomous Self-Correction Loop: The core engine implements a strict generation-and-validation cycle. If an initial Cypher query produces a database syntax error, the agent catches the exception, injects the error log into the context, and automatically reprompts the LLM to fix its own code before the user even notices.
• The "Judge" Entity Resolution: Historical data is notoriously ambiguous (e.g., multiple generations sharing the exact same name and title). When encountering overlapping identities or merged nodes, a secondary LLM agent acts as a "Judge." It evaluates the raw graph output, detects data inconsistencies, and provides fact-grounded clarifications rather than blindly guessing.
• Rate-Aware Asynchronous Pipeline: Built on FastAPI, the system manages API constraints intelligently. It utilizes exponential backoff to naturally handle LLM rate limits (HTTP 429 errors), ensuring the application remains stable and gracefully degrades during high-load scenarios without crashing the execution thread.

Prerequisites

Prior to deployment, ensure your host system meets the following requirements:

1. Software Requirements

• Docker Engine (v20.10.0 or higher)
• Docker Compose (v2.0.0 or higher)

2. API Credentials: A valid Google Gemini API Key.

Installation

1. Clone the Repository

https://github.com/lilkhoa/GraphRAG-History-Project.git
cd GraphRAG-History-Project

2. Set Up Environment Variables Create a .env file in the root directory of the project and populate it using the provided .env.example template.

3. Build and Initialize Containers

docker compose up -d --build

4. Access the Application

Once the deployment process completes and the containers reach a healthy state, the following interfaces will be available on your host machine:

• Web Application (Chat UI & Data Inspector): http://localhost:8000
• Neo4j Browser (Database Administration): http://localhost:7474

5. Stop the Application To halt the execution and remove the active containers, run the following command. Note that the graph data is persistently mounted to the ./neo4j_data volume and will not be lost.

docker compose down

Usage

Once the system is operational, users can interact with the knowledge graph through the integrated web interface. The application is designed to handle natural language queries of varying complexity, translating them into graph traversals.

1. Accessing the Interface

Open a web browser and navigate to http://localhost:8000. The interface consists of a primary chat arena and a technical inspector panel.

2. Submitting Queries

The system supports different levels of logical graph traversal. Below are examples of query types designed to test the system's capabilities:

• Entity Extraction (Single Node): "Who is the 2nd Duke of Westminster?" Purpose: Tests basic text-to-Cypher translation and node property retrieval.

• Multi-hop Traversal (Edge Navigation): "Who did the 2nd Duke of Westminster marry, and what properties did he own?" Purpose: Evaluates the LLM's ability to navigate relationship schemas (e.g., MARRIED_TO, OWNS) and join multiple nodes.

3. Auditing the Execution

Upon submitting a query, developers can observe the right-hand Inspector Panel. It dynamically updates to display:

• Cypher Query: The exact database command generated by the Retriever LLM and executed against Neo4j.
• Graph Context: The raw JSON payload returned by the database. This allows users to verify that the Generator LLM's final natural language response is strictly grounded in the retrieved facts.

4. Direct Database Access

For manual graph exploration and schema validation, navigate to the Neo4j Browser at http://localhost:7474. Authenticate using the credentials defined in your .env file to execute raw Cypher queries directly against the dataset.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Made by lilkhoa.