---

name: core-rag description: "Use LightRAG as an embedded Python library: construct LightRAG, initialize/finalize storages, insert text or custom KGs, query with QueryParam, configure embeddings/cache/rerank knobs, and avoid async lifecycle misuse." disable-model-invocation: true metadata: disco-role: operating license: MIT

Core LightRAG Embedded Usage

Use this sub-skill when writing or reviewing Python code that imports lightrag directly and drives LightRAG from an application, notebook, script, or test harness.

Route By Task

• Start with API reference for constructor defaults, QueryParam, embedding wrappers, object relationships, and lifecycle method signatures.
• Use workflows for minimal async recipes, insert/query patterns, custom IDs/file paths, custom KG ingestion, cache/rerank toggles, and addon params.
• Use troubleshooting for install/import failures, missing initialization, sync-wrapper misuse in async apps, embedding switches, cache/rerank warnings, and ID/file-path validation issues.
• Run scripts/check_core_api.py when you need a safe local import/signature sanity check that does not call models, services, credentials, or persistent storages.

Boundaries

• This sub-skill owns embedded Python usage of LightRAG, QueryParam, EmbeddingFunc, wrap_embedding_func_with_attrs, ainsert, aquery, ainsert_custom_kg, initialization/finalization, cache/rerank knobs, custom IDs, file paths, and addon_params.
• For document parser engines, filename/process options, multimodal parsing, and advanced chunker strategy selection, route to ../document-pipeline/SKILL.md.
• For storage backend class choices, service configuration, migrations, workspace isolation details, and destructive storage tools, route to ../storage-backends/SKILL.md.
• For provider modules, credentials, role-specific LLM settings, reranker provider bindings, and VLM provider behavior, route to ../llm-providers/SKILL.md.
• For lightrag-server, REST routes, WebUI, auth, deployment, and environment-file orchestration, route to ../api-server/SKILL.md.

Non-Negotiables

• Always call await rag.initialize_storages() after constructing LightRAG and before ainsert, aquery, ainsert_custom_kg, delete, cache, or graph operations.
• Always call await rag.finalize_storages() during cleanup, preferably in finally after successful construction.
• In async applications, call coroutine APIs such as await rag.ainsert(...) and await rag.aquery(...); do not call sync wrappers from a running event loop.
• Keep the embedding function and vector data consistent; changing embedding model or dimension requires rebuilding/clearing vector storage data.
• Do not bake secrets, service URLs, or machine-specific file locations into reusable embedded examples.