---

name: lightrag description: "Use LightRAG as a graph-based RAG framework: embedded Python APIs, document ingestion, storage backends, LLM/provider wiring, FastAPI/WebUI operation, and troubleshooting." disable-model-invocation: true metadata: disco-role: operating license: MIT

LightRAG Repo Skill

Use this skill for tasks involving LightRAG, the lightrag-hku Python package, its graph-based RAG APIs, document parsing pipeline, storage backends, model/provider bindings, REST API server, or WebUI.

Start Here

• Install the base package for embedded Python work: pip install lightrag-hku.
• Install API/upload/parser support for server work: pip install "lightrag-hku[api]".
• Use the offline/storage/provider extras only when the task needs those optional backends: offline-storage, offline-llm, offline, evaluation, or observability.
• Verify the installed package without model calls or services: python scripts/check_lightrag_install.py from this skill directory.
• Read repo provenance before deciding whether this skill is stale for a current checkout.
• Read troubleshooting for cross-cutting install/import, initialization, optional dependency, credential, storage, parser, and server failures.

Route By Task

• Embedded Python LightRAG construction, QueryParam, async lifecycle, text/custom-KG insertion, querying, embeddings, cache, and rerank knobs: use core-rag.
• File/text ingestion internals, parser routing, filename hints, process options, chunk strategies, sidecars, doc status, and pipeline concurrency/refusal semantics: use document-pipeline.
• KV/vector/graph/doc-status storage class selection, external storage services, workspace isolation, migrations, vector rebuilds, cache cleanup, and destructive storage preconditions: use storage-backends.
• LLM, embedding, VLM, role-specific model routing, provider bindings, asymmetric embeddings, rerank provider setup, credentials, service URLs, and model-cache behavior: use llm-providers.
• lightrag-server, lightrag-gunicorn, REST/Ollama-compatible routes, auth/JWT, .env configuration, setup wizard outputs, Docker/offline deployment, and React WebUI operations: use api-server.

Core Decision Points

• Choose embedded Python when integrating LightRAG inside an application, notebook, worker, or test harness.
• Choose the API server/WebUI route when the user needs uploads, REST routes, browser UI, auth, or Ollama-compatible endpoints.
• Choose document-pipeline guidance when the problem names parser engines, LIGHTRAG_PARSER, process_options, chunking selectors F/R/V/P, parsed sidecars, scan/upload/delete conflicts, or doc-status rows.
• Choose storage-backends guidance when the problem names JsonKVStorage, PGVectorStorage, Neo4JStorage, Qdrant, Redis, MongoDB, OpenSearch, workspace isolation, vector dimensions, or rebuild/cache tools.
• Choose llm-providers guidance when the problem names OpenAI, Ollama, Azure OpenAI, Gemini, Bedrock, Anthropic, VoyageAI, Zhipu, VLM, rerank, role-specific LLMs, or embedding prefixes.

Minimal Embedded Pattern

import asyncio
from lightrag import LightRAG, QueryParam

async def main():
    rag = LightRAG(
        working_dir="./rag_storage",
        llm_model_func=your_llm_func,
        embedding_func=your_embedding_func,
    )
    await rag.initialize_storages()
    try:
        await rag.ainsert("LightRAG builds a graph from documents.")
        result = await rag.aquery("What does LightRAG build?", param=QueryParam(mode="mix"))
        print(result)
    finally:
        await rag.finalize_storages()

asyncio.run(main())

Non-Negotiables

• Always initialize storages before ainsert, aquery, graph, delete, or cache operations; always finalize storages during cleanup.
• Do not call synchronous wrappers from an already running event loop; use async methods in async apps.
• Keep embedding model, embedding dimension, and existing vector storage aligned; changing embeddings requires rebuilding or clearing vector data.
• Treat optional provider/storage/parser services as explicit dependencies; do not assume API keys, databases, parser services, or local model servers exist.
• Do not run destructive storage tools, document clear/delete operations, or graph mutations while ingestion or another writer is active for the same workspace.
• Keep public examples free of secrets, machine-specific paths, local environment names, and original source-checkout dependencies.