# How to Implement Custom Entity Types in LightRAG Using addon_params

> Easily implement custom entity types in LightRAG by configuring addon_params. Override default taxonomy without modifying core code for flexible data extraction.

- Repository: [✨Data Intelligence Lab@HKU✨/LightRAG](https://github.com/HKUDS/LightRAG)
- Tags: how-to-guide
- Published: 2026-03-23

---

**Configure the `addon_params` dictionary when initializing `LightRAG` or mutate `rag.addon_params["entity_types"]` at runtime to override the default entity extraction taxonomy without modifying core library code.**

LightRAG constructs knowledge graphs by extracting entities from text using a configurable type system. By default, the pipeline recognizes the entity categories defined in `DEFAULT_ENTITY_TYPES` (located in [[`lightrag/constants.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/constants.py)](https://github.com/HKUDS/LightRAG/blob/main/lightrag/constants.py#L28-L41)), but you can customize this list through the `addon_params` configuration to support domain-specific taxonomies like medical diagnoses, legal clauses, or IT infrastructure components.

## How addon_params Drives Entity Extraction

The `LightRAG` class aggregates configuration into a shared `global_config` dictionary during initialization (see `__post_init__` in [[`lightrag/lightrag.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/lightrag.py)](https://github.com/HKUDS/LightRAG/blob/main/lightrag/lightrag.py#L49-L56)). The `addon_params` field is defined as:

```python

# lightrag/lightrag.py

addon_params: dict[str, Any] = field(
    default_factory=lambda: {
        "language": get_env_value(
            "SUMMARY_LANGUAGE", DEFAULT_SUMMARY_LANGUAGE, str
        ),
        "entity_types": get_env_value("ENTITY_TYPES", DEFAULT_ENTITY_TYPES, list),
    }
)

```

When the extraction pipeline runs in [[`lightrag/operate.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/operate.py)](https://github.com/HKUDS/LightRAG/blob/main/lightrag/operate.py#L2834-L2837), it reads from this global configuration:

```python
language = global_config["addon_params"].get("language", DEFAULT_SUMMARY_LANGUAGE)
entity_types = global_config["addon_params"].get(
    "entity_types", DEFAULT_ENTITY_TYPES
)

```

These values are interpolated into the LLM prompt template (lines 3320‑3345 in [`operate.py`](https://github.com/HKUDS/LightRAG/blob/main/operate.py)), where the list is joined into a comma-separated string. The model then returns entities constrained to these specific types, and `_process_extraction_result()` creates graph nodes using the verbatim type labels.

## Three Methods to Configure Custom Entity Types

You can supply custom entity types through three mechanisms, listed here by override precedence (highest to lowest):

### Constructor Parameter (Highest Precedence)

Pass a dictionary to the `addon_params` argument when instantiating `LightRAG`. This completely replaces the default factory values:

```python
from lightrag.lightrag import LightRAG

rag = LightRAG(
    kv_storage="JsonKVStorage",
    vector_storage="NanoVectorDBStorage",
    graph_storage="NetworkXStorage",
    addon_params={
        "entity_types": ["Person", "Organization", "Product", "Vulnerability"],
        "language": "English",
    },
)

```

### Runtime Mutation

Modify the dictionary after construction to change behavior for subsequent ingestion operations:

```python
rag = LightRAG(...)  # initialization

rag.addon_params["entity_types"] = ["Asset", "Risk", "Regulation"]

```

Because `addon_params` resides in the shared `global_config`, changes propagate immediately to all downstream operations including summarization, reranking, and graph storage.

### Environment Variables (Lowest Precedence)

Define `ENTITY_TYPES` in a `.env` file at your project root. The library loads this via `load_dotenv()` in [[`lightrag/api/config.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/api/config.py)](https://github.com/HKUDS/LightRAG/blob/main/lightrag/api/config.py#L47-L51):

```dotenv

# .env

ENTITY_TYPES=Person,Organization,CustomDevice,SecurityPatch

```

Values are parsed as comma-separated strings and automatically injected into the default `addon_params` factory.

## Implementation Examples

### Basic Construction with Custom Types

```python
from lightrag.lightrag import LightRAG

custom_entities = ["MedicalDevice", "Diagnosis", "TreatmentProtocol"]

rag = LightRAG(
    kv_storage="JsonKVStorage",
    vector_storage="NanoVectorDBStorage",
    graph_storage="NetworkXStorage",
    addon_params={"entity_types": custom_entities},
)

```

### Full Ingestion Pipeline

```python
from lightrag.lightrag import LightRAG
from pathlib import Path

rag = LightRAG(
    kv_storage="JsonKVStorage",
    vector_storage="NanoVectorDBStorage",
    graph_storage="NetworkXStorage",
    addon_params={
        "entity_types": ["SoftwareModule", "BugReport", "CodeCommit"],
        "language": "English",
    },
)

# Ingest documents

rag.ingest(Path("./repositories"))

# Query the resulting knowledge graph

results = rag.query("Which SoftwareModule fixes BugReport #442?")

```

### Switching Types for Different Document Sets

```python

# Initial extraction with general types

rag.addon_params["entity_types"] = ["Person", "Company", "Contract"]

# Later, switch to specialized types for technical documentation

rag.addon_params["entity_types"] = ["Server", "Database", "APIEndpoint"]
rag.ingest(Path("./technical_docs"))

```

## Summary

- **`addon_params`** is the configuration gateway for entity type customization in LightRAG, stored in the shared `global_config` dictionary.
- **Override methods**: Constructor argument (highest priority), runtime dictionary mutation, or `.env` file `ENTITY_TYPES` variable (lowest priority).
- **Prompt injection**: The `entity_types` list is rendered into extraction prompts in [`operate.py`](https://github.com/HKUDS/LightRAG/blob/main/operate.py), constraining the LLM to recognize only the specified categories.
- **Persistence**: Custom type labels are stored verbatim in the graph storage backend (Neo4j, NetworkX, etc.), enabling direct querying (e.g., `MATCH (e:CustomDevice)`) without schema migration.

## Frequently Asked Questions

### What is the default list of entity types in LightRAG?

The default taxonomy is defined as `DEFAULT_ENTITY_TYPES` in [[`lightrag/constants.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/constants.py)](https://github.com/HKUDS/LightRAG/blob/main/lightrag/constants.py#L28-L41). Typically includes general categories like "Person", "Organization", "Location", and "Event". You can inspect this constant to see the baseline before customizing.

### Do I need to modify LightRAG source code to add new entity types?

No. The `addon_params` mechanism is designed for runtime configuration. By passing your custom list to the constructor or updating `rag.addon_params["entity_types"]`, you alter the extraction behavior without touching files in the `lightrag/` directory.

### Will changing entity_types affect already extracted entities?

No. The `entity_types` configuration only affects the extraction phase for new documents being ingested. Existing nodes in the knowledge graph retain their original type labels. To reprocess old documents with new types, you must clear the storage and re-run `rag.ingest()`.

### Can I use different entity types for different documents in the same project?

Yes. Because `addon_params` is mutable, you can update `rag.addon_params["entity_types"]` between ingestion batches. Each call to `rag.ingest()` uses the current configuration, allowing you to process legal contracts with one taxonomy and technical manuals with another within the same LightRAG instance.