DlightRAG

PyPI CI Ask DeepWiki

DlightRAG is a multimodal RAG service built on LightRAG main. LightRAG owns document parsing, staged ingest, chunks, document status, vectors, and the knowledge graph. DlightRAG adds product-layer metadata governance, PostgreSQL BM25, direct image-vector alignment, answer orchestration, citations, REST, Web, SDK, and MCP interfaces.

Status: Python 3.14. Storage: PostgreSQL 18 with pgvector, Apache AGE, pg_textsearch, and pg_jieba. License: Apache-2.0.

Architecture At A Glance

DlightRAG Architecture 

Clients
  -> REST / Web / MCP / SDK adapters
  -> RAGServiceManager
  -> RAGService
  -> LightRAG main
  -> PostgreSQL 18 storage ecosystem

DlightRAG has one production RAG path: DlightRAG stages sources and metadata, LightRAG performs parser/KG/vector/chunk/doc-status work, and DlightRAG adds metadata filtering, BM25, direct visual retrieval, cited answers, jobs, and interfaces. The full runtime and code-layer view is in docs/architecture.md.

Choose Your Deployment Path

Path Use this when PostgreSQL Parser endpoint Security Start here
Local Docker Developer machine, Web UI, smoke tests Compose PG18 Host-native MinerU-compatible sidecar auth_mode: none on loopback Quick Start
Native API API process runs on host, PostgreSQL stays in Docker Compose PG18 Any reachable MinerU-compatible endpoint Local or explicit auth Native API Variant
Shared service Remote users, agents, team workspace Managed or self-hosted PG18 Official MinerU API or independent parser service simple or jwt PostgreSQL, Configuration, Security
Enterprise Multi-user internal product Managed PG18 Independently operated parser service jwt + JWKS, optional claim access control Security, PostgreSQL, Configuration

Do not install MinerU into the DlightRAG app container. DlightRAG consumes the MinerU-compatible HTTP endpoint that LightRAG expects. On macOS, keep MinerU as a native host process so MLX/MPS acceleration is available. On Linux GPU, run MinerU as an independent service/router or use the official API.

Quick Start

  1. Clone the repo and create a secrets file:
git clone https://github.com/hanlianlu/dlightrag.git
cd dlightrag
cp .env.example .env

Fill secrets in .env:

DLIGHTRAG_LLM__DEFAULT__API_KEY=...
DLIGHTRAG_EMBEDDING__API_KEY=...
DLIGHTRAG_LLM__ROLES__EXTRACT__API_KEY=...
DLIGHTRAG_LLM__ROLES__KEYWORD__API_KEY=...

Normal behavior lives in config.yaml: model names, parser sidecar settings, metadata schema, retrieval breadth, auth mode, Langfuse behavior, and deployment endpoints. Deep config reference is in docs/configuration.md.

  1. Install and start a native MinerU sidecar if one is not already running:
cp .env.mineru.example .env.mineru
make mineru-install
make mineru-api

make mineru-api serves http://127.0.0.1:8210 by default and blocks in the current terminal. Docker Compose does not run MinerU; it maps the host-native endpoint into DlightRAG containers as http://host.docker.internal:8210.

  1. Start DlightRAG and PostgreSQL:
docker compose up -d
docker compose ps
curl http://localhost:8100/health

This starts:

Service Purpose Host port
dlightrag-api REST API + Web UI 127.0.0.1:8100
dlightrag-mcp MCP streamable HTTP server 127.0.0.1:8101
lightrag-gui Upstream LightRAG graph browser 127.0.0.1:9621
postgres PG18 + pgvector + AGE + pg_textsearch + pg_jieba 5432
  1. Open the Web UI:
http://localhost:8100/web/

Upload documents or images from the Files panel, then ask a question.

Native API Variant

Use this when the API process should run on the host while PostgreSQL stays in Docker:

docker compose up -d postgres
uv sync
uv run dlightrag-api

Native runs can ingest host paths directly because the API process sees the same filesystem as your shell.

Use DlightRAG

Web

The Web UI is served by the REST API at /web/. It supports workspace selection, file/folder upload, chat, session image memory, citations, source panels, and semantic highlights.

REST

REST ingest starts durable background jobs. Poll the job endpoint for status.

curl -X POST http://localhost:8100/ingest \
  -H "Content-Type: application/json" \
  -d '{"source_type": "local", "path": "report.pdf"}'

curl http://localhost:8100/ingest/jobs/<job_id>

curl -X POST http://localhost:8100/answer \
  -H "Content-Type: application/json" \
  -d '{"query": "What are the key findings?", "stream": false}'

All SDK, REST, MCP, Web contracts and response shapes are in docs/interfaces.md.

Python SDK

uv add dlightrag

import asyncio
import os

from dlightrag import IngestSpec, RAGServiceManager
from dlightrag.config import DlightragConfig, EmbeddingConfig, LLMConfig, ModelConfig


async def main() -> None:
    workspace = "research_notes"
    config = DlightragConfig(
        workspace=workspace,
        working_dir="./dlightrag_storage/sdk_demo",
        llm=LLMConfig(
            default=ModelConfig(
                provider="openai",
                model="gpt-4.1-mini",
                api_key=os.environ["OPENAI_API_KEY"],
                temperature=0.2,
            )
        ),
        embedding=EmbeddingConfig(
            provider="openai_compatible",
            model="text-embedding-3-large",
            api_key=os.environ["OPENAI_API_KEY"],
            base_url="https://api.openai.com/v1",
            dim=3072,
        ),
    )
    manager = await RAGServiceManager.create(config)
    try:
        await manager.aingest(
            workspace,
            IngestSpec(source_type="local", path="./docs"),
        )
        answer = await manager.aanswer("What are the key findings?", workspace=workspace)
        print(answer.answer)
    finally:
        await manager.close()


asyncio.run(main())

config.yaml is optional for SDK users; constructor values take precedence.

MCP

Use stdio when an agent starts DlightRAG as a subprocess:

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

Use streamable HTTP when multiple clients connect to a running service:

DLIGHTRAG_MCP_TRANSPORT=streamable-http \
DLIGHTRAG_MCP_HOST=127.0.0.1 \
dlightrag-mcp

MCP tools include retrieve, answer, ingest, ingest_job_status, list_files, delete_files, list_workspaces, create_workspace, and delete_workspace.

Core Concepts

Workspaces. A workspace is the primitive isolation unit for indexed data, metadata, jobs, files, and queries. Query calls can target one workspace or federate across multiple workspaces.

Ingestion sources. Local files, Web uploads, S3, Azure Blob, public/signed HTTPS URLs, and SDK AsyncDataSource connectors flow through the same ingest contract. Web and REST uploads are staged under DlightRAG's managed working_dir/inputs/<workspace>/ tree, then copied into the workspace input root as retained local sources. Upload batch staging under __uploads__/ is cleaned by the durable ingest job after the handoff.

Source retention. Remote source files are transient by default for S3, Azure Blob, URL, and SDK connectors. Set retain_remote_source_files: true, or pass retain_source_file: true on one ingest call, when fetched files should be kept under the workspace input root.

Runtime storage. Docker Compose stores working_dir in the dlightrag_data named volume mounted at /app/dlightrag_storage; the host ./dlightrag_storage directory is only used by native, non-Docker runs.

Metadata. Declare filterable custom fields once in configuration. Ingest calls pass values. Request-level metadata is the batch default; manifest or SourceDocument metadata overlays it per document.

Retrieval and answers. DlightRAG uses LightRAG mix as the base retrieval mode, then adds metadata filtering, BM25, optional direct image retrieval, RRF fusion, reranking, answer packing, citations, and optional semantic highlights. The detailed mechanism is in docs/retrieval-answer.md.

Observability. Langfuse tracing is optional. If Langfuse keys are absent, tracing is a no-op. Configuration is documented in docs/configuration.md.

Security Model

Local loopback development can use auth_mode: none. Shared or exposed deployments should enable auth:

Mode Use case
simple One shared bearer token
jwt Externally issued signed tokens
jwt + JWKS OIDC-style issuers with key rotation
jwt + jwt_claims access control Workspace/action permissions from verified claims

DlightRAG verifies bearer tokens and can enforce workspace/action access control. It does not issue OAuth tokens or manage users. Use an external IdP or gateway for login and token issuance. Full guidance is in docs/security.md.

Operations And Development

Offline vector maintenance:

uv run dlightrag-rebuild-vdb --target check
uv run dlightrag-rebuild-vdb --target all --yes

Use docs/operations.md for rebuild and maintenance safety notes.

Development setup:

uv sync
cd frontend && npm ci && cd ..
make hooks

Verification:

make ci          # lint + type-check + architecture + unit tests
make ci-full     # above + integration tests
make ci-e2e      # above + E2E smoke

Frontend checks after editing frontend/:

cd frontend
npm run typecheck
npm run build
npm run lint:css

npm run build writes the browser bundle to src/dlightrag/web/static/generated/; commit those generated files with frontend changes.

Evaluation with RAGAS is documented in docs/evaluation.md.

Documentation Map

License

Apache License 2.0. See LICENSE.

Built by HanlianLyu. Contributions welcome.

Project links

Data verified by PyPI on Jul 7, 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 Jul 7, 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-1.6.1.tar.gz (714.1 kB view details)

Uploaded Source

Built Distribution

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

dlightrag-1.6.1-py3-none-any.whl (372.6 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: dlightrag-1.6.1.tar.gz
  • Upload date:
  • Size: 714.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for dlightrag-1.6.1.tar.gz
Algorithm Hash digest
SHA256 54eab900412754ac6b1a6f1de907ee1547552ae3f9c423782ba914a364242b95
MD5 110d100448944714d624d66b2c6792fe
BLAKE2b-256 341635100326e97fae213ebe8bb7b6490ce470ed1625bc704f691f6f2b5c5b7d

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: dlightrag-1.6.1-py3-none-any.whl
  • Upload date:
  • Size: 372.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for dlightrag-1.6.1-py3-none-any.whl
Algorithm Hash digest
SHA256 5bff948304eb209b9bcdaf5fbf66a70475aa262ed66bb70535fda1fc25429a78
MD5 70aefba51629400a873f8e23175d7953
BLAKE2b-256 2c9be6911f670bfe736f6ebdb4ec21a7e60fddacfb6b9c1c0bc80c932cfd09fd

See more details on using hashes here.

Provenance

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

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

This release

1.6.1 This release

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