Skip to content

Relocate the parse-cancellation vocabulary out of llm_bridge.py (rename LLMBridgeCancelled family) #3611

Description

@danielaskdd

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

  1. 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.
  2. 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.
  3. 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

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requesttrackedIssue is tracked by project

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions