DlightRAG

PyPI CI Ask DeepWiki

DlightRAG is a production multimodal RAG service built on LightRAG. It combines knowledge-graph and vector retrieval with metadata filtering, BM25, visual retrieval, reranking, citations, highlights, and durable agentic answers. The same runtime is available through Web, REST, MCP, and an in-process Python API.

Runtime: Python ≥3.14.7 · PostgreSQL 18 ecosystem · Apache-2.0

LightRAG storage defaults are exactly PGKVStorage, PGVectorStorage, PGTableGraphStorage, and PGDocStatusStorage. Writer deployments may explicitly replace only the vector leg with MilvusVectorDBStorage (including Milvus-compatible Zilliz endpoints) by installing dlightrag[milvus]; reader processes currently remain PostgreSQL-vector-only.

Architecture

DlightRAG system context shown as one black box between browser users, REST and MCP clients, trusted embedding applications, an optional Web identity boundary, external AI, parser, corpus source and Research systems, PostgreSQL, and a shared corpus artifact root

LightRAG supplies graph and vector retrieval. DlightRAG owns product policy, multimodal alignment, durable ingestion and answers, security, storage adapters, and public interfaces. Fast and Research answers share one durable conversation tree; Research adds a per-run workspace, tools, memory, and child agents. See Architecture for module and storage ownership.

Deployment Paths

Path PostgreSQL Parser Security
Local Docker Compose PG18 Self-hosted MinerU by default Loopback, auth_mode: none
Native API Compose or external PG18 Any reachable MinerU or Docling Local or explicit auth
Shared service Managed or self-hosted PG18 Independently operated parser simple or jwt
Enterprise Managed PG18 Independently operated parser JWKS plus claim access control

The parser runs outside the DlightRAG app container. The checked-in Docker configuration uses self-hosted MinerU at http://host.docker.internal:8210. Docling and MinerU cloud remain supported.

Quick Start

Install Docker + Compose, uv, git, and make.

Interactive setup

git clone https://github.com/hanlianlu/dlightrag.git
cd dlightrag
uv run prerequisite_setup.py

The wizard configures models, parser, secrets, and the local stack. It defaults to self-hosted MinerU and is safe to rerun.

Manual setup

git clone https://github.com/hanlianlu/dlightrag.git
cd dlightrag
cp .env.example .env
mkdir -p "${HOME}/.dlightrag/skills"

The last command prepares the default read-only operator Skills bind source; when COMPOSE_GLOBAL_SKILLS_DIR selects another host path, create that directory instead. Add the keys required by your config.yaml model blocks:

DLIGHTRAG_MODELS__CHAT__DEFAULT__API_KEY=...
DLIGHTRAG_MODELS__EMBEDDING__API_KEY=...
DLIGHTRAG_MODELS__CHAT__ROLES__EXTRACT__API_KEY=...
DLIGHTRAG_MODELS__CHAT__ROLES__KEYWORD__API_KEY=...
DLIGHTRAG_MODELS__CHAT__ROLES__QUERY__API_KEY=...
DLIGHTRAG_MODELS__CHAT__ROLES__VLM__API_KEY=...
DLIGHTRAG_MODELS__RERANK__API_KEY=...

Install and start MinerU, then start DlightRAG:

make mineru-install
make mineru-service-install  # installs and starts the background service
curl http://127.0.0.1:8210/health

docker compose up -d
docker compose ps

Open http://localhost:8100/web/. The stack publishes:

Service Address
REST API and Web http://127.0.0.1:8100
MCP streamable HTTP http://127.0.0.1:8101
PostgreSQL 127.0.0.1:5432

Use make mineru-api when the platform cannot install a background user service. To use Docling, replace the MinerU block in config.yaml; a commented example is included there. Parser changes affect only new parses.

Configuration fields and parser operations are documented in Configuration and Operations.

Native API

Run PostgreSQL in Docker and the API on the host:

docker compose up -d postgres
uv sync
DLIGHTRAG_CORPUS__SIDECARS__MINERU__LOCAL_ENDPOINT=http://127.0.0.1:8210 \
  uv run dlightrag-api

The checked-in config is Docker-first, so a native process overrides the parser host alias with loopback. Native managed inputs live under ./dlightrag_storage/inputs/<workspace>.

Use DlightRAG

Web

The Web UI supports workspace and file management, durable Fast and Research conversations, answer attachments, citations, source highlights, child-agent status, and typed Answer Artifacts. Research publishes only workspace roots it explicitly attaches; prose links alone never publish files. English, Chinese, and automatic browser language modes are available under Settings.

REST

Ingestion, Retrieval, and Answer create durable Runs and return 202 Accepted. Corpus mutations require a stable idempotency key.

INGEST_RUN=$(curl -sS -X POST http://localhost:8100/runs/corpus/ingest \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ingest-report-1" \
  -d '{"source_type":"local","path":"report.pdf"}' | jq -r .run_id)
curl "http://localhost:8100/runs/$INGEST_RUN"

RETRIEVAL_RUN=$(curl -sS -X POST http://localhost:8100/retrieve \
  -H "Content-Type: application/json" \
  -d '{"query":"What are the key findings?"}' | jq -r .run_id)
curl "http://localhost:8100/runs/$RETRIEVAL_RUN"

RUN=$(curl -sS -X POST http://localhost:8100/answer \
  -H "Content-Type: application/json" \
  -d '{"query":"What are the key findings?"}' | jq -r .run_id)
curl -N "http://localhost:8100/runs/$RUN/events"
curl "http://localhost:8100/runs/$RUN"

See Interfaces for requests, responses, pagination, SSE, attachments, citations, and all transport contracts.

MCP

For a local stdio client:

{
  "mcpServers": {
    "dlightrag": {
      "command": "uvx",
      "args": ["dlightrag-mcp", "--env-file", "/absolute/path/to/.env"]
    }
  }
}

The Compose stack also exposes streamable HTTP on port 8101. MCP supports durable Retrieval and Answer Runs, steering, follow-up/fork, child status, corpus administration, and capability discovery. The authoritative tool list is in Interfaces.

Python

uv add dlightrag

Create an application with create_application(config), use application.corpus_mutations for durable corpus writes, application.retrieval for durable Retrieval, and application.answers for durable Answers, then call application.aclose(). Complete typed examples are in Interfaces.

Core Concepts

Concept Meaning Reference
Workspace Isolation unit for indexed data, metadata, files, and queries Domain language
Ingestion One durable contract for local files, uploads, object storage, URLs, and SDK sources Interfaces
Retrieval One durable Query-lane Run returning LightRAG mix plus metadata, BM25, visual fusion, and rerank evidence Retrieval and Answer
Run Common durable lifecycle for Retrieval, Answer, and Corpus Mutation across REST, MCP, Web, Python, and evaluation RunRuntime
Answer Run A Query-lane Run that resolves Fast or Research and generates an Answer Retrieval and Answer
Resource Request-local attachment read deterministically or inspected visually on demand Retrieval and Answer
Published Artifact Owner-visible Research output authorized by a settled root attachment and validated at publication Domain language
Source Durable provenance and download contract for an ingested document Interfaces

Security

Loopback development can use access.auth_mode: none. Shared deployments should use a bearer token or externally issued JWT; JWKS and claim-based workspace/action rules are supported. DlightRAG does not issue tokens or replace an ingress WAF, rate limiter, TLS terminator, or identity provider. See Security.

Development

uv sync
npm --prefix frontend ci
make hooks
make ci          # lint, security, format, types, architecture, frontend, unit
make ci-full     # plus integration tests
make ci-e2e      # plus E2E smoke

Use Operations for reset, rebuild, parser, Langfuse, and maintenance runbooks. RAGAS evaluation is documented in Evaluation.

Documentation

Document Owns
Architecture Runtime ownership, flows, storage topology, layering
Domain Language Canonical product vocabulary
Configuration Configuration precedence, fields, defaults, examples
Interfaces Python, REST, MCP, and Web contracts
Retrieval and Answer Retrieval, fusion, rerank, packing, citations, highlights
RunRuntime and Durable Execution Common Query and Corpus Mutation state machine, leases, events, recovery, retention
RunRuntime and Scaling Target Accepted workload model, lane bounds, lifecycle guarantees, and ownership boundary
RunRuntime Slice 6 Validation Failure matrix, reproducible commands, 10k control-plane evidence, accepted bounds, limitations
Security Authentication, authorization, ingress and content boundaries
PostgreSQL PostgreSQL requirements, schema ownership, tuning
Operations Executable runbooks and recovery workflows
Evaluation RAGAS workflow
Web Theme Design Web appearance and interaction decisions

Plans, ADRs, and research notes under docs/ are historical design evidence, not required reading for operating DlightRAG.

License

Apache License 2.0. See LICENSE.

Built by HanlianLyu. Contributions welcome.

Project links

Data verified by PyPI on Sep 9, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for fumoffu from gravatar.com fumoffu

Credits

Maintainer: HanlianLyu, hllyu

GitHub Statistics

Data verified by PyPI on Sep 9, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.14

Provides Extra

milvus

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

dlightrag-2.0.6.tar.gz (6.3 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

dlightrag-2.0.6-py3-none-any.whl (6.6 MB view details)

Uploaded Python 3

File details

Details for the file dlightrag-2.0.6.tar.gz.

File metadata

  • Download URL: dlightrag-2.0.6.tar.gz
  • Upload date:
  • Size: 6.3 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for dlightrag-2.0.6.tar.gz
Algorithm Hash digest
SHA256 83257e153ffc6f5ee5de0fc511f4fa34d8cfc4aa7ca00c292bb602025fafc353
MD5 bf0cdb9749cdb4837350433a0411db5f
BLAKE2b-256 8e2c4b01b98b8255faaa7a34a0ce4e2dcf9832f42925180ff90100819946bb65

See more details on using hashes here.

Provenance

The following attestation bundles were made for dlightrag-2.0.6.tar.gz:

Publisher: publish.yml on hanlianlu/DlightRAG

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file dlightrag-2.0.6-py3-none-any.whl.

File metadata

  • Download URL: dlightrag-2.0.6-py3-none-any.whl
  • Upload date:
  • Size: 6.6 MB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for dlightrag-2.0.6-py3-none-any.whl
Algorithm Hash digest
SHA256 02fafe0c0844e7ba43a702638c44281a624ac0766b90ef4df78e3c69cad7a3dc
MD5 8e1a5a8663bee8b4ccf3f71d1f145ee1
BLAKE2b-256 402d4218e13844c7319564cde64056c4531d94ee29cb3525912e32a3d6705d45

See more details on using hashes here.

Provenance

The following attestation bundles were made for dlightrag-2.0.6-py3-none-any.whl:

Publisher: publish.yml on hanlianlu/DlightRAG

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

2.0.6 This release

2 files

2.0.5

2 files

2.0.4

2 files

2.0.3

2 files

2.0.2

2 files

2.0.1

2 files

2.0.0

2 files

1.9.0

2 files

1.8.9

2 files

1.8.8

2 files

1.8.7

2 files

1.8.6

2 files

1.8.5

2 files

1.8.0

2 files

1.7.21

2 files

1.7.20

2 files

1.7.19

2 files

1.7.18

2 files

1.7.17

2 files

1.7.16

2 files

1.7.15

2 files

1.7.14

2 files

1.7.13

2 files

1.7.12

2 files

1.7.11

2 files

1.7.10

2 files

1.7.8

2 files

1.7.7

2 files

1.7.6

2 files

1.7.5

2 files

1.7.4

2 files

1.7.3

2 files

1.7.2

2 files

1.7.1

2 files

1.7.0

2 files

1.6.8

2 files

1.6.7

2 files

1.6.6

2 files

1.6.5

2 files

1.6.4

2 files

1.6.3

2 files

1.6.2

2 files

1.6.1

2 files

1.6.0

2 files

1.5.20

2 files

1.5.19

2 files

1.5.18

2 files

1.5.17

2 files

1.5.16

2 files

1.5.15

2 files

1.5.14

2 files

1.5.13

2 files

1.5.12

2 files

1.5.11

2 files

1.5.10

2 files

1.5.9

2 files

1.5.8

2 files

1.5.7

2 files

1.5.6

2 files

1.5.4

2 files

1.5.3

2 files

1.5.1

2 files

1.4.0

2 files

1.3.6

2 files

1.3.5

2 files

1.3.4

2 files

1.3.3

2 files

1.3.1

2 files

1.3.0

2 files

1.2.9

2 files

1.2.8

2 files

1.2.7

2 files

1.2.6

2 files

1.2.5

2 files

1.2.4.1

2 files

1.2.4

2 files

1.2.3

2 files

1.2.2.2

2 files

1.2.2.1

2 files

1.2.2

2 files

1.2.1.1

2 files

1.2.1

2 files

1.2.0.1

2 files

1.2.0

2 files

1.1.6.7

2 files

1.1.6.5

2 files

1.1.6.3

2 files

1.1.6.1

2 files

1.1.6

2 files

1.1.4

2 files

1.1.3

2 files

1.1.0

2 files

1.0.0

2 files

0.2.6

2 files

0.2.4

2 files

0.2.3

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page