Summary
PR #3605 promoted the LLMBridgeCancelled exception family and the normalize_cancel_events / first_cancellation helpers into the repo-wide "a blocking parse wait was cancelled" vocabulary (its docstring now says so explicitly), and gave them their second and third non-LLM consumers. The vocabulary itself, however, still lives in lightrag/parser/llm_bridge.py — an LLM-named module — and the class names still say "LLMBridge". This is follow-up naming/placement work, deliberately kept out of the security PR (it touches pipeline.py, which that PR's diff otherwise never does).
Why it matters
lightrag/pipeline.py keys its cancelled-vs-FAILED document classification on LLMBridgePipelineCancelled (the except near the parse dispatch, ~line 4441). Any blocking parse path that wants cancellation treatment must raise from this family — raising anything else silently records the document as FAILED instead of cancelled.
A contributor adding cancellation to the next blocking path (e.g. the MinerU/Docling result downloads tracked in #3610, or docx work) has no reason to look inside llm_bridge.py for the exception contract of a non-LLM code path. PR #3605 mitigated discoverability with a docstring; relocation is the durable fix.
Proposed change
- Create
lightrag/parser/cancellation.py holding:
- the exception family (renamed to match its actual role, e.g.
ParseCancelled / ParsePipelineCancelled / ParseShutdown);
normalize_cancel_events and first_cancellation.
- Update all importers directly —
lightrag/pipeline.py, lightrag/parser/native_base.py, lightrag/parser/llm_bridge.py, lightrag/parser/markdown/parser.py, and tests. These are internal APIs (underscore-free but unexported/undocumented), and per this repo's convention internal refactors do not leave deprecation shims or re-exports behind — no llm_bridge aliases.
SyncLLMBridge itself stays in llm_bridge.py and imports the vocabulary from the new module.
Sequencing
Blocked on PR #3605 merging — that PR touches llm_bridge.py and markdown/parser.py, so doing this move in parallel guarantees conflicts. Branch off main after the merge.
Context
Summary
PR #3605 promoted the
LLMBridgeCancelledexception family and thenormalize_cancel_events/first_cancellationhelpers into the repo-wide "a blocking parse wait was cancelled" vocabulary (its docstring now says so explicitly), and gave them their second and third non-LLM consumers. The vocabulary itself, however, still lives inlightrag/parser/llm_bridge.py— an LLM-named module — and the class names still say "LLMBridge". This is follow-up naming/placement work, deliberately kept out of the security PR (it touchespipeline.py, which that PR's diff otherwise never does).Why it matters
lightrag/pipeline.pykeys its cancelled-vs-FAILED document classification onLLMBridgePipelineCancelled(theexceptnear the parse dispatch, ~line 4441). Any blocking parse path that wants cancellation treatment must raise from this family — raising anything else silently records the document as FAILED instead of cancelled.A contributor adding cancellation to the next blocking path (e.g. the MinerU/Docling result downloads tracked in #3610, or docx work) has no reason to look inside
llm_bridge.pyfor the exception contract of a non-LLM code path. PR #3605 mitigated discoverability with a docstring; relocation is the durable fix.Proposed change
lightrag/parser/cancellation.pyholding:ParseCancelled/ParsePipelineCancelled/ParseShutdown);normalize_cancel_eventsandfirst_cancellation.lightrag/pipeline.py,lightrag/parser/native_base.py,lightrag/parser/llm_bridge.py,lightrag/parser/markdown/parser.py, and tests. These are internal APIs (underscore-free but unexported/undocumented), and per this repo's convention internal refactors do not leave deprecation shims or re-exports behind — nollm_bridgealiases.SyncLLMBridgeitself stays inllm_bridge.pyand imports the vocabulary from the new module.Sequencing
Blocked on PR #3605 merging — that PR touches
llm_bridge.pyandmarkdown/parser.py, so doing this move in parallel guarantees conflicts. Branch offmainafter the merge.Context