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,<3.15 · PostgreSQL 18 ecosystem · Apache-2.0

Architecture

DlightRAG system context showing browser, REST, MCP, and embedded callers; optional enterprise identity and Web edge boundaries; external integrations; PostgreSQL; and corpus artifacts

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

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. English, Chinese, and automatic browser language modes are available under Settings.

REST

Ingestion creates a background job; answers create durable runs and return 202 Accepted.

JOB=$(curl -sS -X POST http://localhost:8100/ingest \
  -H "Content-Type: application/json" \
  -d '{"source_type":"local","path":"report.pdf"}' | jq -r .job_id)
curl "http://localhost:8100/ingest/jobs/$JOB"

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/answer/$RUN/events"
curl "http://localhost:8100/answer/$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 retrieval, durable answers, steering, follow-up/fork/resume, 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.corpora for ingestion 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, jobs, files, and queries Domain language
Ingestion One durable contract for local files, uploads, object storage, URLs, and SDK sources Interfaces
Retrieval LightRAG mix retrieval plus metadata, BM25, visual fusion, rerank, and packing Retrieval and Answer
Answer run One durable lifecycle shared by REST, MCP, Web, Python, and evaluation Durable Answer Runs
Resource Request-local attachment read deterministically or inspected visually on demand Retrieval and Answer
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
Durable Answer Runs State machine, leases, events, recovery, retention
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 2, 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:
Newer release available (2.0.6)

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 2, 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.15, >=3.14

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.1.tar.gz (6.1 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.1-py3-none-any.whl (6.4 MB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: dlightrag-2.0.1.tar.gz
  • Upload date:
  • Size: 6.1 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.1.tar.gz
Algorithm Hash digest
SHA256 e630f46b59af4c433157106a0ccc8d82e2e55884a3475f4a92264858d8cd83ba
MD5 0bfe520613e6def864b260ece1c43158
BLAKE2b-256 75c0fac496511a3791ad75bf2c99ad46a4c1dd1d04c8599f691e9ce9c26b0998

See more details on using hashes here.

Provenance

The following attestation bundles were made for dlightrag-2.0.1.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.1-py3-none-any.whl.

File metadata

  • Download URL: dlightrag-2.0.1-py3-none-any.whl
  • Upload date:
  • Size: 6.4 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.1-py3-none-any.whl
Algorithm Hash digest
SHA256 bd3fdc1d3316b884cee1d3972f6869340cdee08a26f05a86cee02a977ec2c920
MD5 d67a0620023e6227e3b2b0ffd1a54eea
BLAKE2b-256 4121f04711ad69ae16a1c3eeac60dd434401e9e4e25aa4f9f35e746cba669dcd

See more details on using hashes here.

Provenance

The following attestation bundles were made for dlightrag-2.0.1-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

2.0.6

2 files

2.0.5

2 files

2.0.4

2 files

2.0.3

2 files

2.0.2

2 files

This release

2.0.1 This release

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