HKUDS/LightRAG v1.5.8rc1 on GitHub

Important Notes

v1.5.8rc1 is a release candidate. Please test it on a copy of your data before upgrading production.

Highlights

1. Configuration storage: LightRAG now remembers which embedding model built your vectors

In earlier releases, changing EMBEDDING_MODEL or EMBEDDING_DIM on an existing deployment failed silently. Depending on the backend, LightRAG either kept the old vectors and returned wrong neighbours, or opened a new, empty vector container (Milvus / Qdrant / PostgreSQL) and served a knowledge graph with no vectors at all.

v1.5.8 adds a configuration storage. It is a small KV namespace (config) that holds each workspace's embedding baselines: for every vector target (entities, relationships, chunks), the embedding space its vectors were written in. Startup checks the baselines against the current embedding configuration. If the space has changed, the server refuses to start and names the target and the way out, instead of serving bad results.

Backends: JsonKVStorage, PGKVStorage, MongoKVStorage and OpenSearchKVStorage, selected with LIGHTRAG_CONFIG_STORAGE. Left unset, it follows LIGHTRAG_KV_STORAGE, so most deployments need no new setting. RedisKVStorage is not admitted, so Redis deployments default to JsonKVStorage, with a startup warning.
No preparation needed. On the first start of v1.5.8, an existing deployment records its baselines on its own. A baseline is recorded only on evidence: an adoption probe re-embeds a few stored records (up to 8 per target) and compares them with the stored vectors, or the container is confirmed empty. A probe that cannot run (for example, the embedding service is down) records nothing and is retried on the next start.
Deployment anchor. The first start also binds the deployment to the configuration container it opened, in WORKING_DIR/config_storage_anchor.json (backend type + container UUID). Every later start refuses a container of another type or another UUID. A changed LIGHTRAG_KV_STORAGE, a different database or a replaced volume therefore no longer silently moves your configuration.
New offline tools:
- lightrag-rebuild-vdb re-embeds a workspace with the current model and records the new baselines. This is the way out after an intentional model change.
- lightrag-migrate-config moves the configuration storage to a backend of another type, for example from JSON files to PostgreSQL.
- lightrag-clear-storage clears a workspace offline, configuration records included.
Several servers, one WORKING_DIR: supported when each server has its own WORKSPACE and port. A second server on the same workspace is refused where the filesystem supports file locks.

For more information, see:

docs/LightRAG-API-Server.md: Configuration Storage Migration Between Backend Types
lightrag/tools/README_REBUILD_VDB.md, README_MIGRATE_CONFIG.md, README_CLEAR_STORAGE.md
docs/design/ConfigurationStorageDesign.md: the design overview

2. Safer graph writes and document deletion

Manual graph edits (create / edit / delete / merge entities and relations, insert_custom_kg) are now serialized against each other and against the ingestion pipeline on NetworkXStorage.
Commit ordering for entity/relation create, edit, merge and rename was reworked to prevent data loss when an operation is interrupted.
Interrupted document deletions are visible and retryable.
New lightrag-repair-chunk-tracking tool removes orphan chunk-tracking rows left behind by an interrupted deletion.

3. PostgreSQL storage defaults

The setup wizard now generates PostgreSQL from the official pgvector/pgvector image and offers PGTableGraphStorage (plain tables, no Apache AGE) for the graph. PGGraphStorage (AGE) and the Redis storages (RedisKVStorage, RedisDocStatusStorage) are deprecated. They keep working and log a warning at startup.

4. Security hardening and new provider

The Ollama-compatible /api/* routes are protected by LIGHTRAG_API_KEY (see Breaking Changes).
PDF extraction runs pypdf in a resource-limited child process.
Streamed error lines no longer echo raw provider exception text.
New openai_responses LLM binding for the OpenAI Responses API.

Breaking Changes

Python 3.11 or later is required. Python 3.10 is no longer supported. The Docker images (Python 3.12) are not affected.
Changing the embedding model on an existing workspace now refuses startup, where it used to serve wrong or empty results. Either restore the previous EMBEDDING_MODEL / EMBEDDING_DIM, or run lightrag-rebuild-vdb to re-embed with the new model.
Changing LIGHTRAG_KV_STORAGE after the first v1.5.8 start is refused while LIGHTRAG_CONFIG_STORAGE is unset, because the configuration storage would silently move with it. Either set LIGHTRAG_CONFIG_STORAGE to the anchored backend explicitly, or move the configuration with lightrag-migrate-config.
Ollama routes require the API key. When LIGHTRAG_API_KEY is set and WHITELIST_PATHS is unset, /api/* requests without the key now get HTTP 403. In Open WebUI, the lightrag:latest model disappears from the list. Fix: enter the key as the API key of the Ollama connection (sent as Authorization: Bearer <key>), or set WHITELIST_PATHS=/health,/api/* to keep the old behaviour.
POST /documents/clear_cache is removed. Use DELETE /documents?clear_llm_cache=true instead. Clearing the LLM cache now happens together with the destructive clear.
Workspace names starting with $ are reserved. The server used to serve WORKSPACE=$team as _team. Set WORKSPACE=_team (the name your data is already stored under), and no data moves.

Upgrade Notes

Back up first, then stop every old instance before starting v1.5.8. That includes all workers, servers sharing the storage, and maintenance tools. The first start creates the configuration container and binds the anchor. Do not do a rolling upgrade that leaves an old writer running.
WORKING_DIR must persist, even if every storage is a database. It now holds config_storage_anchor.json, and for JSON configuration also <workspace>/kv_workspace_config.json. In Docker, keep it on a mounted volume. In Helm, keep persistence.enabled: true. An ephemeral WORKING_DIR loses the anchor and the JSON configuration on every restart. Include it in your backups.
The embedding service must be reachable during the first start, so the adoption probe can record the baselines. Check the startup log for a WARNING that a baseline could not be established. If the start refuses with an embedding-space mismatch, your stored vectors do not match the configured model: fix the configuration, or run lightrag-rebuild-vdb.
Redis users: with LIGHTRAG_KV_STORAGE=RedisKVStorage, the configuration storage defaults to JSON files in WORKING_DIR (see note 2). Redis storage is deprecated; plan a move to PostgreSQL.
PGGraphStorage users: your deployment keeps working, and the wizard keeps the AGE-enabled image for it. To leave AGE, migrate the graph first (python -m lightrag.tools.migrate_graph_storage --apply, no re-indexing needed), then switch to PGTableGraphStorage and the pgvector image.
Optional: to keep the configuration in your database instead of JSON files, run lightrag-migrate-config --target-backend PGKVStorage (or MongoKVStorage / OpenSearchKVStorage) with every server stopped. Then set LIGHTRAG_CONFIG_STORAGE to that backend.
To start over with a new embedding model, use lightrag-clear-storage rather than deleting files by hand. If you do delete files by hand, also remove kv_workspace_config.json and config_storage_anchor.json. Otherwise the recorded baseline refuses the new model.
TOKEN_SECRET should be a random value of at least 32 bytes (for example, openssl rand -hex 32). The upgraded PyJWT warns about shorter secrets.
Streamed error messages are generic. A failure in the middle of a stream on /query/stream, /api/generate or /api/chat now reads Internal server error (error_id: …), and no longer contains the LLM provider's exception text. The stream format is unchanged. Look up the details in the server log by that error_id. A client that parsed provider error text from the stream (for example, to detect rate limits) needs to be updated.

What's New

Add optional kg_extraction_validator hook before merge by @yzxcj797 in #3700
feat(storage): add offline chunk tracking repair tool (#3838 R4) by @danielaskdd in #3859
feat(api): add delete_parsed_files flag to DELETE /documents by @Shizoqua in #3851
feat(k8s): document the single-instance constraint and add a StatefulSet workload switch by @danielaskdd in #3893
feat(storage): serialize admin graph writes against each other and the pipeline (#3899) by @danielaskdd in #3901
perf(opensearch): refresh the KV index only where a search reads it by @danielaskdd in #3927
♻️ refactor(api): fold the LLM cache clear into the destructive clear by @danielaskdd in #3926
perf(mongo): batch edge lookups and index edge endpoints by @AdalbertoDam in #3908
feat: select installed custom chunkers at server startup by @er-s-an in #3869
Add vector-space provenance and embedding-space refusal handling by @danielaskdd in #3986
feat(opensearch): refuse an index built by another embedding model, and stay droppable when refusing by @danielaskdd in #3987
feat(vdb): embedding-space provenance for MongoDB, FAISS and Nano by @danielaskdd in #3988
fix(vdb): a changed embedding space is a typed refusal on Milvus, Qdrant and PostgreSQL by @danielaskdd in #3989
feat(config): record each workspace's embedding baselines in a configuration storage by @danielaskdd in #4011
refactor(config): configuration storage as its own category, retiring the reserved workspace by @danielaskdd in #4025
feat(tools): add lightrag-clear-storage, an offline workspace clear by @danielaskdd in #4039
feat(config): anchor each deployment to its configuration container's identity (1/3) by @danielaskdd in #4065
feat(tools): lightrag-migrate-config, cross-type offline configuration migration (2/3) by @danielaskdd in #4066
feat(setup): report and validate the configuration storage anchor; document it (3/3) by @danielaskdd in #4067
chore(storage): warn at startup that Redis storage is deprecated by @danielaskdd in #4120
feat(llm): add openai_responses binding for the OpenAI Responses API by @YashvantHange in #3701
feat(parser): allow the docling VLM pipeline via env by @lottshin in #4346
perf(redis): count doc statuses from the sidecar instead of a full scan by @danielaskdd in #4401
feat(config): per-workspace JSON configuration snapshots with a root anchor by @danielaskdd in #4107
feat: default PostgreSQL to pgvector, deprecate PGGraphStorage (kept for deployments already on it); guide Step 1 covers the configuration storage by @danielaskdd in #4409

What's Changed

fix(anthropic): mark token-limited responses by @Shizoqua in #3800
docs: add Indonesian README by @Yoruxyv in #3799
fix(hf): avoid caching truncated responses by @Shizoqua in #3803
fix(cache): include system prompt in query cache key by @Shizoqua in #3802
docs: slim AGENTS.md by moving four long contracts into dedicated documents by @danielaskdd in #3814
chore(deps): bump react-router-dom from 7.18.2 to 7.18.3 in /lightrag_webui in the react group by @dependabot[bot] in #3807
chore(deps): bump lucide-react from 1.33.0 to 1.34.0 in /lightrag_webui in the ui-components group by @dependabot[bot] in #3808
chore(deps-dev): bump the build-tools group in /lightrag_webui with 5 updates by @dependabot[bot] in #3809
chore(deps): bump the content-rendering group across 1 directory with 2 updates by @dependabot[bot] in #3810
chore(deps): bump the frontend-minor-patch group across 1 directory with 5 updates by @dependabot[bot] in #3815
fix(chunker): bound V's sentence-embedding requests by item count by @danielaskdd in #3816
fix(webui): confirm document deletion by reading the pipeline level by @danielaskdd in #3818
test(utils): cover normalize_rerank_result by @loseintwilight in #3813
fix(lmdeploy): handle truncated responses by @Shizoqua in #3824
fix: correct copy-pasted help text for --summary-length-recommended by @simpleqt in #3821
fix: correct typos in operator-visible query logs and comments by @simpleqt in #3822
fix: repair broken relative links in k8s deploy guides and workspace test README by @simpleqt in #3819
Clarify Neo4j URI scheme selection and troubleshooting by @danielaskdd in #3829
fix(opensearch): refuse to attach to another workspace's indexes by @danielaskdd in #3828
fix(bedrock): track token usage by @Shizoqua in #3832
fix(anthropic): track token usage by @Shizoqua in #3825
fix: align stale docstring parameter names with actual signatures by @simpleqt in #3820
docs: fix docstring ghosts in parse_args and process_chunks_unified by @simpleqt in #3834
fix: clear chunk tracking on entity and relation deletion by @be-student in #3836
fix(graph): retire chunk-tracking rows only after a merge or rename is durable by @danielaskdd in #3846
fix(markdown): preserve text after HTML tables by @Shizoqua in #3801
fix: make addon parameter updates atomic by @Iams4kura in #3837
fix(graph): reset evidence on explicit creation (#3838 R1) by @danielaskdd in #3856
fix(zhipu): support token_tracker instead of forwarding it to the API by @Shizoqua in #3843
fix(storage): preserve successful NetworkX drops by @be-student in #3853
🐛 fix(kg): report file-backed vector drops by their durable removal by @danielaskdd in #3857
fix(retrieval): preserve candidate order for vector similarity ties by @Anormalm in #3850
fix(utils): validate embedding shape directly, not by element count by @Shizoqua in #3841
fix(storage): make a landed write distinguishable from a failed one (#3838 R2) by @danielaskdd in #3858
fix(parser): preserve text in nested PPTX groups by @er-s-an in #3865
fix(zhipu): run blocking client calls off the event loop by @Shizoqua in #3842
fix(llama_index): fix llm_instance forwarding and blocking embed call by @Shizoqua in #3844
fix(api): prefix Swagger UI asset URLs with ASGI root_path by @AdalbertoDam in #3864
fix(kg): give NetworkX's reload fence a channel the manager cannot lose by @danielaskdd in #3861
fix(milvus): run search/upsert/delete off the event loop thread by @Shizoqua in #3862
fix(kg): extend the reload fence to the vector backends by @danielaskdd in #3867
fix(storage): preserve create_time on KV replacement upserts by @leilei3167 in #3872
Fix commit ordering for entity/relation creation to prevent data loss by @danielaskdd in #3878
fix(zhipu): mark truncated responses by @Shizoqua in #3883
fix(nvidia): enable asymmetric embedding support by @Shizoqua in #3888
Close the three ordering holes left by the entity/relation create-edit rework by @danielaskdd in #3889
fix(milvus): handle concurrent database creation race on first boot by @AdalbertoDam in #3876
Stage aedit_entity's non-rename chunk-tracking row before the node mutation by @danielaskdd in #3892
refactor(networkx): make the recovery reload a process-local flag by @danielaskdd in #3874
Settle aedit_relation's tracking shrink inside a cancellation-deferring region by @danielaskdd in #3897
fix(storage): retry os.replace in atomic_write on Windows NTFS lock c… by @zhiwu215 in #3880
test(pipeline): pin duplicate-document track_id retrievability (#2468) by @TiSsaa in #3900
docs(storage): move the storage contracts out of the docstrings, and drop issue references by @danielaskdd in #3915
build(deps-dev): bump @types/react-dom from 19.2.5 to 19.2.7 in /lightrag_webui in the react group by @dependabot[bot] in #3909
build(deps): bump lucide-react from 1.34.0 to 1.40.0 in /lightrag_webui in the ui-components group by @dependabot[bot] in #3910
build(deps-dev): bump the build-tools group in /lightrag_webui with 3 updates by @dependabot[bot] in #3911
build(deps): bump the frontend-minor-patch group across 1 directory with 6 updates by @dependabot[bot] in #3913
build(deps): bump katex from 0.18.5 to 0.18.7 in /lightrag_webui in the content-rendering group across 1 directory by @dependabot[bot] in #3912
fix(llm): run the llama_index install guard before the import it protects by @danielaskdd in #3925
fix(extraction): attach a cache key to its chunk before writing the row by @danielaskdd in #3916
fix(kg): make the self-loop rule a data invariant, and batch the degree lookups by @danielaskdd in #3929
Fix token truncation to preserve stage-2 reordering in filtered lists by @danielaskdd in #3918
fix(query): preserve minimum vector chunk quota by @Shizoqua in #3887
fix(query): drop empty entity chunk groups by @Solaris-star in #3904
fix(storage): tell a lost reference from a durable one when a chunk commit raises by @danielaskdd in #3932
fix: recognize repeated-letter alpha ordinals (aa, zz, aaa) in smart_heading by @jabrailkhalil in #3905
fix(cache): partition KG answers by chunk selection by @Shizoqua in #3877
fix(merge): make join_unique deterministic so source_id limits keep the chunks they name by @linhongyu510 in #3928
fix(docx): reject out-of-range w:ilvl before it drives an unbounded loop by @Shizoqua in #3936
fix(smart_heading): classify parenthesized Roman list labels by @leilei3167 in #3938
fix(chunker): correct custom-chunker drift diagnostics and selection ergonomics by @danielaskdd in #3941
fix(hf): run generate() and embedding forward pass off the event loop thread by @Shizoqua in #3860
fix(docx): record Roman and ideographTraditional counts past their domain by @RizgarOzan in #3940
fix(kg): floor the merged legacy edge weight to its evidence count by @Shizoqua in #3937
fix(parser/mineru): keep MinerU chart items instead of dropping them by @boeschbenjamin-jpg in #3775
fix(parser/mineru): log items the text fallback drops without a trace by @boeschbenjamin-jpg in #3789
test: clean up HF inference executor fixtures by @danielaskdd in #3947
fix(auth): strip whitespace around AUTH_ACCOUNTS entries by @RizgarOzan in #3944
fix: repair whitespace-class LaTeX escapes in math spans by @danielaskdd in #3946
fix(llm): report LaTeX escape damage followed by a non-ASCII character by @danielaskdd in #3952
fix(milvus): extend event-loop offloading to delete_entity_relation and id lookups by @AdalbertoDam in #3943
fix(milvus): run drop()'s collection rebuild off the event loop thread (stacked on #3943) by @danielaskdd in #3945
fix(parser): retain Markdown table headers in chunk content by @Lu1sDV in #3951
fix(opensearch): let vector reads lift a stale missing-index mark by @danielaskdd in #3954
fix: release admission token after enqueue, before processing by @kokhlo in #3953
fix(chunker): preserve blockids when tail absorption merges trailing blocks by @Shizoqua in #3972
fix(api): require a word boundary after unsuffixed context mode keys by @hxxxi-malog in #3985
fix(parser): emit LaTeX-valid delimiters for Word equations by @RizgarOzan in #3977
fix(markdown): treat an escaped pipe as cell text, not a column separator by @RizgarOzan in #3976
fix(parser): give CJK and fullwidth delimiters their own glyph by @danielaskdd in #3992
fix(kg): reap expired lease before scan job cancel by @Shizoqua in #3994
build(deps): bump the react group in /lightrag_webui with 4 updates by @dependabot[bot] in #3998
build(deps): bump lucide-react from 1.40.0 to 1.44.0 in /lightrag_webui in the ui-components group across 1 directory by @dependabot[bot] in #3999
build(deps-dev): bump the build-tools group across 1 directory with 5 updates by @dependabot[bot] in #4000
build(deps): bump the frontend-minor-patch group across 1 directory with 3 updates by @dependabot[bot] in #4001
build(deps): bump react-dropzone from 19.3.0 to 20.1.0 in /lightrag_webui by @dependabot[bot] in #4002
docs: fix a stale :func: target and a double-space heading by @simpleqt in #4014
fix: correct four misspelled strings in exceptions and logs by @simpleqt in #4013
docs: drop the references to the removed parse_native method by @simpleqt in #4015
fix: pass document context to custom chunkers by @dafyy321-pixel in #4010
fix(memgraph): dedupe get_all_edges and iter_edges by relationship id by @Shizoqua in #3982
fix(neo4j): dedupe get_all_edges and iter_edges by relationship id by @Shizoqua in #3981
test(pipeline): make multimodal fail-fast assertion independent of elapsed time by @danielaskdd in #4024
Update README.md by @chaohuang-ai in #4042
Update README.md by @chaohuang-ai in #4044
fix(tests): stop double-capturing lightrag log records on pytest 9.1 by @YHC66 in #4032
fix(mongo): honor document ID pagination sort by @S0rryHorizon in #4031
fix(chunker): reject overlap >= chunk size by @Shizoqua in #4030
fix(gemini): match real google-genai exception types by @Shizoqua in #4029
fix(azure): forward max_token_size in azure_openai_embed by @Shizoqua in #4027
fix(evaluation): report all-NaN RAGAS cases as failed, not a 0.0 success by @pablo-legeren in #4041
fix(mongo): compare cosine threshold against raw similarity by @Shizoqua in #3956
fix(opensearch): compare cosine threshold against raw similarity by @Shizoqua in #3957
fix(storage): report vector snapshot deletion errors accurately by @danielaskdd in #4036
fix(api): clarify empty vector index startup errors by @danielaskdd in #4037
ci: limit PostgreSQL smoke tests to relevant paths by @danielaskdd in #4038
refactor(config): name the JSON configuration file kv_server_config.json by @danielaskdd in #4053
fix(pipeline): keep a scoped workspace's parser source lookup in its own dir by @danielaskdd in #4096
docs: replace ConfigurationStorage.md with ConfigurationStorageContract.md and slim AGENTS.md by @danielaskdd in #4070
test: remove load sensitivity from cancellation and fork probes by @danielaskdd in #4095
fix(multimodal): bisect row count when trimming oversized tables by @danielaskdd in #4100
test: faster offline suite (env probe, setup CI split, local xdist) by @danielaskdd in #4101
test: faster local test runs (skip tests/setup by default, concurrent RSS children, faster .env generation) by @danielaskdd in #4102
fix(setup): pin configuration storage to readable anchor by @danielaskdd in #4103
fix(config): default Redis deployments to JSON configuration by @danielaskdd in #4104
build(deps): bump react-router-dom from 7.18.3 to 7.18.4 in /lightrag_webui in the react group by @dependabot[bot] in #4089
build(deps): bump the ui-components group in /lightrag_webui with 2 updates by @dependabot[bot] in #4090
build(deps-dev): bump the build-tools group in /lightrag_webui with 2 updates by @dependabot[bot] in #4091
build(deps): bump the frontend-minor-patch group in /lightrag_webui with 3 updates by @dependabot[bot] in #4092
refactor(config): clarify configuration storage anchor filename by @danielaskdd in #4105
fix(milvus): never drop an existing collection in the force-create fallback by @AdalbertoDam in #4146
fix(postgres): filtered vector search returns nothing for a workspace holding a minority of the rows by @ModestXin in #4210
build(deps): bump katex from 0.18.7 to 0.19.0 in /lightrag_webui in the content-rendering group across 1 directory by @dependabot[bot] in #4142
build(deps-dev): bump the build-tools group across 1 directory with 6 updates by @dependabot[bot] in #4234
build(deps): drop redundant pycryptodome dependency by @danielaskdd in #4315
build(deps): update anthropic requirement from <2.0.0,>=0.18.0 to >=0.18.0,<3.0.0 by @dependabot[bot] in #4277
ci(deps): move Dependabot to the uv ecosystem and fail on a stale uv.lock by @danielaskdd in #4316
build(deps): bump spacy-pkuseg from 1.0.1 to 1.0.2 in the python-minor-patch group by @dependabot[bot] in #4295
build(deps): cap spacy at <3.9 and lock to 3.8.18 by @dependabot[bot] in #4296
build(deps): bump the react group across 1 directory with 3 updates by @dependabot[bot] in #4305
build(deps): bump the frontend-minor-patch group across 1 directory with 11 updates by @dependabot[bot] in #4321
build(deps): bump sigstore/cosign-installer from 4.1.2 to 4.1.3 in the github-actions group across 1 directory by @dependabot[bot] in #4313
build(deps-dev): bump the build-tools group across 1 directory with 4 updates by @dependabot[bot] in #4317
build(deps): bump the ui-components group across 1 directory with 15 updates by @dependabot[bot] in #4314
build(deps): bump katex from 0.19.0 to 0.19.1 in /lightrag_webui in the content-rendering group across 1 directory by @dependabot[bot] in #4318
build(deps): bump the llm-providers group with 3 updates by @dependabot[bot] in #4319
build(deps): bump tiktoken from 0.12.0 to 0.14.0 in the data-processing group by @dependabot[bot] in #4320
build(deps): bump the storage group with 5 updates by @dependabot[bot] in #4322
build(deps): bump the web-framework group across 1 directory with 5 updates by @dependabot[bot] in #4323
build(deps): bump the dev-tools group across 1 directory with 4 updates by @dependabot[bot] in #4324
build(deps): declare spacy-pkuseg in the api extra so uv.lock owns it by @danielaskdd in #4325
build(ruff): pin the lint rule set to the former default by @danielaskdd in #4326
test(storage): stop double-capturing Redis deprecation warnings on pytest 9.2 by @danielaskdd in #4327
test: route lightrag records into caplog once, on any pytest version by @danielaskdd in #4328
test(storage): use the shared lightrag log capture in the Redis deprecation test by @danielaskdd in #4329
fix: stop answering when final retrieval evidence is empty by @dakjdakd in #4202
fix(query): return non-streaming answers unmodified in kg_query and naive_query by @Zhuoxi2000 in #4144
fix: close OpenAI clients when pending requests are cancelled by @tuanzirwar in #4137
fix(ollama): retry transient embedding request failures by @Shizoqua in #4139
fix(openai): reraise the provider's error once retries are exhausted by @danielaskdd in #4336
fix(webui): preserve query failure classification across history persistence by @dakjdakd in #4206
fix(webui): send only completed turns as history; make the query draft the single source of truth by @danielaskdd in #4337
fix(tools): let --spacy-install work in uv environments without pip by @danielaskdd in #4344
fix(llm): propagate cancellation from openai streaming mid-COT by @danielaskdd in #4349
fix(postgres): refuse vector index types that cannot hold the embedding dim by @danielaskdd in #4347
fix(docx): log when smart_heading skips a short document by @danielaskdd in #4348
build(deps): bump the web-framework group with 2 updates by @dependabot[bot] in #4339
build(deps): bump ruff from 0.17.3 to 0.17.4 in the dev-tools group by @dependabot[bot] in #4340
fix(setup): offer openai_responses as an LLM provider in the wizard by @danielaskdd in #4350
build(deps): bump the python-minor-patch group with 21 updates by @dependabot[bot] in #4341
fix(tiktoken): default the cache to ~/.tiktoken_cache instead of /tmp by @danielaskdd in #4351
build(deps): bump cryptography from 48.0.1 to 50.0.2 by @dependabot[bot] in #4342
fix(evaluation): cap langchain-community so ragas imports again by @danielaskdd in #4353
build(deps): bump datasets from 4.8.5 to 5.1.0 by @dependabot[bot] in #4343
test: run the 1492 tests that CI's -m offline silently skipped by @danielaskdd in #4355
test: keep every .env out of the test process by @danielaskdd in #4356
test: silence root_path deprecation and unawaited-coroutine warnings by @danielaskdd in #4357
build: raise requires-python to 3.11 and test the floor on pushes by @danielaskdd in #4359
test: restore lightrag.api module identity session-wide by @danielaskdd in #4358
build: bump anyio and grpcio in uv.lock to silence test warnings by @danielaskdd in #4360
test: stop time.sleep mocks from catching other threads; run RAGAS tests separately by @danielaskdd in #4361
fix(vlm): detect JPEG dimensions beyond large metadata segments by @remote-controlled-man in #4354
fix(deps): drop python-jose and bump PyJWT, pyasn1, certifi, setuptools for CVEs by @shaqosano in #4330
fix(llm): retry Zhipu calls on zai-sdk errors, not openai's by @danielaskdd in #4365
fix(auth): use 32-byte JWT secrets in tests and document the length by @danielaskdd in #4367
fix(llm): strip whitespace in role-specific boolean option overrides by @MohammadHijjawi97 in #4311
fix(chunker): handle invalid UTF-8 in optional table headers by @wToTw123 in #4352
fix(chunker): fall back when blocks.jsonl holds invalid UTF-8 by @danielaskdd in #4369
fix: preserve Markdown headings after pipe tables by @LimbC-C in #4363
test: enforce line-for-line alignment of the README translations by @danielaskdd in #4370
fix(llm): strip whitespace in boolean binding-option CLI flags by @danielaskdd in #4371
fix(redis): keep eviction guard active after rejected startup by @remote-controlled-man in #4334
fix(markdown): accept image paths with spaces or balanced parentheses by @danielaskdd in #4372
fix(operate): accept json_repair list replies when parsing keywords by @shaqosano in #4332
fix(api): accept any whitespace after an Ollama query mode prefix by @MohammadHijjawi97 in #4307
fix(neo4j): drop APOC labelFilter so special-character workspaces keep their nodes by @zzjiho in #4310
fix(query): search a mode's own store when its keyword list is empty by @danielaskdd in #4374
fix: reject non-positive embedding_batch_num and max_async values at startup by @danielaskdd in #4376
fix: reject non-positive embedding_batch_num and max_async values at startup by @xiong-wei1 in #4300
fix(parser): recognize entity-only blank HTML table headers by @pengpengyi92 in #4364
fix(chunker): fail the document on a corrupt blocks.jsonl instead of degrading by @danielaskdd in #4377
fix(postgres): load AGE on each graph connection by @its-amann in #4373
fix(postgres): migrate legacy vectors in one verified transaction by @Aurantium-47 in #4368
fix(parser): never index openpyxl formula objects from uncached XLSX cells by @danielaskdd in #4378
fix(parser): preserve uncached XLSX array formulas by @er-s-an in #4197
fix(parser): recover from invalid UTF-8 native image cache manifests by @passionworkeer in #4241
fix(parser): treat invalid UTF-8 MinerU/Docling raw files as stale by @danielaskdd in #4386
fix(parser): keep horizontally merged DOCX cell text once in legacy extraction by @parthchilwerwar in #4385
fix(parser): align DOCX rows that skip grid columns in legacy extraction by @danielaskdd in #4387
chore(deps): raise the python-docx floor to 1.1.2 by @danielaskdd in #4388
fix(extraction): strip
and
from extracted names and descriptions by @parthchilwerwar in #4384
fix(parser): read DOCX content controls and tracked insertions in the legacy extractor by @L4XB in #4094
fix(extraction): keep line breaks in descriptions, collapse whitespace in entity names by @danielaskdd in #4389
fix(postgres): recover the pool after a database outage, with single-flight reconnects by @danielaskdd in #4390
fix(postgres): recover the pool after a database outage by @yarka-guru in #4231
fix: cancel in-flight queue calls when callers abandon them by @remote-controlled-man in #4333
fix: reject blocked queue submissions when shutdown starts by @remote-controlled-man in #4338
fix(pipeline): bound multimodal item concurrency and fail analysis on unexpected item errors by @magicyuan876 in #4245
fix: cancel and drain analyze item tasks when the stage exits early by @danielaskdd in #4391
fix(pipeline): drain stage-owned children when parents are cancelled by @dajiaohuang in #4161
fix(webui): preserve query caret when entering multiline mode by @passionworkeer in #4272
build(deps-dev): bump the build-tools group in /lightrag_webui with 3 updates by @dependabot[bot] in #4380
build(deps): bump the ui-components group across 1 directory with 3 updates by @dependabot[bot] in #4379
build(deps): bump the frontend-minor-patch group across 1 directory with 5 updates by @dependabot[bot] in #4394
build(deps-dev): bump @happy-dom/global-registrator from 20.14.6 to 21.0.1 in /lightrag_webui by @dependabot[bot] in #4383
fix(graph): resolve manual entity names on every graph entry point by @danielaskdd in #4395
fix(extraction): drop the space that removing inner quotes leaves in a name by @parthchilwerwar in #4393
fix(graph): address merge sources and renamed entities by stored name only by @danielaskdd in #4397
fix: keep the embedding queue open when finalize is interrupted by @danielaskdd in #4396
fix(api): stop echoing raw exception text in streamed error lines by @danielaskdd in #4398
fix(tools): migrate smart-heading LLM caches too by @simpleqt in #4255
fix(sidecar): write parse artifacts with LF line endings on every platform by @simpleqt in #4261
fix(parser): stream xlsx via read_only workbooks and release them by @shanning123 in #4303
fix(api): protect the Ollama routes with LIGHTRAG_API_KEY by default by @danielaskdd in #4399
fix: make interrupted document deletions visible and retryable by @Ovi-Poddar in #4312
fix(parser): run pypdf in a resource-limited child process by @danielaskdd in #4400
fix(config): remove false startup refusals found reviewing dev for release by @danielaskdd in #4410
Dummy PR for dev by @danielaskdd in #4406
fix(milvus): read point lookups with Strong consistency by @danielaskdd in #4414
fix(setup): replace removed minio/minio image and bump Milvus to v2.6.27 by @danielaskdd in #4411
fix(docx): honor direct list levels with inherited numbering IDs by @remote-controlled-man in #4402
fix(docx): honor list levels written by a style without a numbering ID by @danielaskdd in #4415
fix: keep empty DOCX cells outside vertical merges by @LimbC-C in #4413
fix(chunker): reject invalid sidecar content fields by @remote-controlled-man in #4405
fix(setup): pin the Redis template to redis:8 by @danielaskdd in #4416
fix(anthropic): avoid multiplying SDK retry attempts by @remote-controlled-man in #4404
fix(docx): align native table rows that skip leading grid columns by @danielaskdd in #4417
fix(docx): read content controls in the native parser, minus TOC and placeholders; mark bibliographies for drop_rf by @danielaskdd in #4418

New Contributors

@Yoruxyv made their first contribution in #3799
@loseintwilight made their first contribution in #3813
@simpleqt made their first contribution in #3821
@be-student made their first contribution in #3836
@Anormalm made their first contribution in #3850
@AdalbertoDam made their first contribution in #3864
@leilei3167 made their first contribution in #3872
@zhiwu215 made their first contribution in #3880
@TiSsaa made their first contribution in #3900
@jabrailkhalil made their first contribution in #3905
@linhongyu510 made their first contribution in #3928
@RizgarOzan made their first contribution in #3940
@boeschbenjamin-jpg made their first contribution in #3775
@Lu1sDV made their first contribution in #3951
@kokhlo made their first contribution in #3953
@hxxxi-malog made their first contribution in #3985
@dafyy321-pixel made their first contribution in #4010
@YHC66 made their first contribution in #4032
@S0rryHorizon made their first contribution in #4031
@pablo-legeren made their first contribution in #4041
@ModestXin made their first contribution in #4210
@dakjdakd made their first contribution in #4202
@Zhuoxi2000 made their first contribution in #4144
@tuanzirwar made their first contribution in #4137
@remote-controlled-man made their first contribution in #4354
@shaqosano made their first contribution in #4330
@MohammadHijjawi97 made their first contribution in #4311
@wToTw123 made their first contribution in #4352
@LimbC-C made their first contribution in #4363
@zzjiho made their first contribution in #4310
@xiong-wei1 made their first contribution in #4300
@its-amann made their first contribution in #4373
@Aurantium-47 made their first contribution in #4368
@lottshin made their first contribution in #4346
@passionworkeer made their first contribution in #4241
@parthchilwerwar made their first contribution in #4385
@L4XB made their first contribution in #4094
@yarka-guru made their first contribution in #4231
@dajiaohuang made their first contribution in #4161
@shanning123 made their first contribution in #4303
@Ovi-Poddar made their first contribution in #4312

Full Changelog: v1.5.7...v1.5.8rc1