# gusye1234/nano-graphrag architecture

> Architecture diagram of the GitHub repository gusye1234/nano-graphrag, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gusye1234/nano-graphrag
- Repository: https://github.com/gusye1234/nano-graphrag

## Overview

Below are step-by-step instructions that incorporate the project’s structure and purpose:

##### Project Type and Purpose
- The README and file structure reveal that this is a GraphRAG library – a retrieval-augmented generation solution that uses graph structures to combine entity extraction with LLM and embedding functionalities.
- The project emphasizes using different storage backends (e.g., neo4j, networkx for graphs, hnswlib and nano-vectordb for vector search, and JSON file storage for key-value pairs) and multiple LLM providers (built-in support for OpenAI, Amazon Bedrock, DeepSeek, ollama, etc.). It is designed to be “small, faster, and cleaner” than other implementations.
- Users insert text documents (or batches), which are processed to extract entities and relationships, then stored and later retrieved via different query modes (global, local, naive).

##### Analyzing the File Structure
- The top-level directories (docs, examples, tests, and the core package directory “nano_graphrag”) show:
- Configuration and deployment scripts (.github, .env.example, etc.)
- Documentation (docs folder)
- Example usage and benchmarks (examples folder)
- Core implementation within the “nano_graphrag” directory that contains modules for LLM, operations, splitting/chunking, and various storage implementations under “_storage”
- Tests that cover entity extraction, chunking, graph storage, and integration with external APIs.
- The presence of “entity_extraction”, “_llm”, “_storage”, and others signals a modular architecture where each aspect (LLM integration, text processing, storage) is encapsulated in its own component.

##### Key Components to Capture
a. Main Components:
- Client / User Scripts:
- Represented by the example scripts and notebooks (under examples) that call the GraphRAG API.
- GraphRAG Core Module:
- The central class (in nano_graphrag/graphrag.py) that coordinates operations (insertion, querying, etc.).
- Chunker/Text Splitter:
- Located in nano_graphrag/_splitter.py (and referenced in _op.py) for breaking text into manageable chunks.
- Entity Extraction Module:
- Found in nano_graphrag/entity_extraction/ which extracts entities and relationships from text.
- Storage Components:
- Key-Value Storage: Handles mapping of chunk hashes to content.
- Vector Storage: Manages embeddings (using nano-vectordb, hnswlib, or examples with milvus-lite, faiss).
- Graph Storage: Implements the knowledge graph (using networkx by default, with neo4j as an alternative).
- Embedding and LLM Integration:
- Embedding functions (either built-in using OpenAI or an alternative like sentence-transformers as seen in the examples).
- LLM functions: “best_model_func” and “cheap_model_func” for high-quality and summary responses.
- Prompt Management:
- The prompt templates used to drive entity extraction, community reporting, and responses.

b. Relationships and Interactions:
- The GraphRAG class receives text from the client. It then:
- Uses the chunker to break text into portions.
- Calls the entity extraction module to parse out entities and their relationships.
- Obtains embeddings for chunks using the embedding function.
- Persists these chunks and embedding vectors into appropriate storage (KV, vector, graph storages).
- When a query is issued:
- The system (using QueryParam) decides on the mode (local, global, or naive).
- The vector storage is queried, and the knowledge graph is traversed (via networkx or neo4j) to collect context.
- The LLM is then invoked (using either the “best” high-quality model or a cheaper model) to generate the final answer.
- Responses are post-processed (for instance, converting string outputs into JSON when needed).

c. Architectural Patterns and Design Principles:
- Modularity: Each functionality (chunking, extraction, storage, LLM, embedding) is isolated in its module, enabling easy swapping-out or extension.
- Asynchronous Design: Both synchronous and async methods are provided (method naming convention “a<method_name>”) to improve performance.
- Configurability: Many components (embedding function, storage classes, LLM functions) are injectable into GraphRAG when initializing.
- Extensibility: The architecture supports adding additional storage backends or LLM providers (as seen by examples and the separation between built-in and “examples” implementations).

##### Specific Elements
- Labels for every component (e.g., “Text Chunker”, “Entity Extractor”, “Embedding Service”, “Graph Storage (NetworkX/Neo4j)”, “LLM Interface”).
- From “Client” to “GraphRAG Core”
- From “GraphRAG” to “Text Chunker” and then “Entity Extraction”
- From generated chunks to the “KV Storage”, “Vector Storage”, and “Graph Storage”
- From “Query Service” to both storage modules and then to the “LLM” for final answer generation
- Internal processing components
- Storage systems (persistent layers)
- External integrations (LLM APIs, embedding providers)
- Annotations highlighting that many of these components support asynchronous operations.

- Chunking/Preprocessing
- Entity Extraction & Prompt Preparation
- Embedding Function
- Next, branch out to three storage components:
- Vector Storage: for embedding indexing (annotate with “nano-vectordb / hnswlib / faiss”)
- Graph Storage: for the relationship network (show alternatives: networkx by default, neo4j optionally)
- Finally, include the “LLM Interface” block that handles query generation using both “best” and “cheap” LLM functions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Layer"
        Client["Client Application (Example Scripts)"] 
    end

    subgraph "Processing Pipeline"
        direction TB
        Core["GraphRAG Core Module"]:::internal
        Chunker["Text Chunker"]:::internal
        Entity["Entity Extraction Module"]:::internal
        Embed["Embedding Service"]:::internal
        Prompt["Prompt Management"]:::internal
    end

    subgraph "Storage Layer"
        direction TB
        KV["KV Storage"]:::storage
        subgraph "Vector Storage"
            direction TB
            V1["HNSWLib Module"]:::storage
            V2["NanoVectordb Module"]:::storage
        end
        subgraph "Graph Storage"
            direction TB
            G1["NetworkX Module"]:::storage
            G2["Neo4j Module"]:::storage
        end
    end

    subgraph "LLM Layer"
        LLMF["LLM Functions"]:::external
    end

    %% Data flow connections
    Client -->|"sends_text"| Core
    Core -->|"chunk_text"| Chunker
    Chunker -->|"split_text"| Entity
    Entity -->|"extract_entities"| Embed
    Embed -->|"compute_embeddings"| Prompt
    Prompt -->|"store_metadata"| KV
    Prompt -->|"store_embeddings"| V1
    Prompt -->|"store_embeddings"| V2
    Prompt -->|"update_graph"| G1
    Prompt -->|"update_graph"| G2

    Client -->|"sends_query"| Core
    Core -->|"query_vector"| V1
    Core -->|"query_graph"| G1
    V1 -->|"context_to_llm"| LLMF
    G1 -->|"context_to_llm"| LLMF
    LLMF -->|"generate_answer"| Core

    %% Click Events with file/directory mappings
    click Client "https://github.com/gusye1234/nano-graphrag/tree/main/examples/"
    click Core "https://github.com/gusye1234/nano-graphrag/blob/main/nano_graphrag/graphrag.py"
    click Chunker "https://github.com/gusye1234/nano-graphrag/blob/main/nano_graphrag/_splitter.py"
    click Entity "https://github.com/gusye1234/nano-graphrag/tree/main/nano_graphrag/entity_extraction/"
    click KV "https://github.com/gusye1234/nano-graphrag/blob/main/nano_graphrag/_storage/kv_json.py"
    click V1 "https://github.com/gusye1234/nano-graphrag/blob/main/nano_graphrag/_storage/vdb_hnswlib.py"
    click V2 "https://github.com/gusye1234/nano-graphrag/blob/main/nano_graphrag/_storage/vdb_nanovectordb.py"
    click G1 "https://github.com/gusye1234/nano-graphrag/blob/main/nano_graphrag/_storage/gdb_networkx.py"
    click G2 "https://github.com/gusye1234/nano-graphrag/blob/main/nano_graphrag/_storage/gdb_neo4j.py"
    click LLMF "https://github.com/gusye1234/nano-graphrag/blob/main/nano_graphrag/_llm.py"
    click Prompt "https://github.com/gusye1234/nano-graphrag/blob/main/nano_graphrag/prompt.py"

    %% Styles
    classDef internal fill:#aqua,stroke:#000,stroke-width:2px;
    classDef storage fill:#f9c,stroke:#000,stroke-width:2px;
    classDef external fill:#fc9,stroke:#000,stroke-width:2px;
```
