perf(converter): lazy-import markitdown to cut startup ~24% and enable slim packaging#186
Open
KylinMountain wants to merge 2 commits into
Open
perf(converter): lazy-import markitdown to cut startup ~24% and enable slim packaging#186KylinMountain wants to merge 2 commits into
KylinMountain wants to merge 2 commits into
Conversation
…m packaging markitdown is only used for the non-PDF, non-Markdown ingest branch, but it was imported at module top level — so every `import openkb` eagerly pulled in markitdown → magika → onnxruntime (tens of MB, slow). Move the import into the branch that actually uses it. Effects (measured): - `import openkb.cli` cold start 4.64s → 3.53s (~24% faster); magika / onnxruntime / markitdown no longer load unless an Office-format document is converted. - A packaged (PyInstaller) build can now exclude magika/onnxruntime for a slimmer artifact when Office-format ingest isn't needed. Previously the unconditional module-level markitdown import made magika load-bearing at startup, so excluding it crashed the whole app on launch. markitdown appends warning filters on import but leaves the CLI's front "ignore" filter at index 0, so no re-suppression is needed at the new import site. test_converter patches `markitdown.MarkItDown` (the real attribute the local import binds) instead of the removed `openkb.converter.MarkItDown`. Claude-Session: https://claude.ai/code/session_01KZyUSGAzVL9yxpsWWPv6Y2
Adds a regression test that spawns a fresh interpreter and asserts `import openkb.converter` loads none of markitdown / magika / onnxruntime. This locks in the lazy-import optimization: if a future change reintroduces a module-level markitdown import, startup cost and the slim-packaging benefit regress silently while every functional test still passes. The check runs in a subprocess so it is deterministic regardless of what earlier tests imported into this process's sys.modules. Claude-Session: https://claude.ai/code/session_01KZyUSGAzVL9yxpsWWPv6Y2
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
markitdownwas imported at the top ofopenkb/converter.py, so everyimport openkbeagerly pulled inmarkitdown → magika → onnxruntime(tens ofMB, slow to import) — even for commands that never touch an Office/HTML
document. But markitdown is only used in one branch of
convert_document: thenon-PDF, non-Markdown path. This PR moves the import into that branch.
Changes
openkb/converter.py— importMarkItDownlazily inside the Office-formatbranch instead of at module top level.
tests/test_converter.py— update the mock patch target tomarkitdown.MarkItDown(the attribute the local import binds), and add aregression test that spawns a fresh interpreter and asserts
import openkb.converterloads none of markitdown / magika / onnxruntime.Why it helps (measured)
import openkb.clicold start 4.64s → 3.53s (~24% faster); magika /onnxruntime / markitdown no longer load unless an Office-format document is
actually converted.
uncompressed) for a slimmer artifact when Office ingest isn't required.
Previously the unconditional module-level import made magika load-bearing at
startup, so excluding it crashed the app on launch.
Notes
front
"ignore"filter (set incli.py) at index 0, so no re-suppression isneeded at the new import site — verified empirically and documented in a code
comment.
what earlier tests already imported into
sys.modules. Without it, a futurechange that reintroduces a top-level markitdown import would regress startup
silently while every functional test stays green.
Office/HTML file rather than at startup. In a normal pinned install markitdown
is always present, so this only matters for intentionally-slimmed builds.
Verification
pytest tests/test_converter.py— 29 passed (28 existing + 1 new guard).ruff check/ruff format --check/mypy openkb/converter.pyclean.https://claude.ai/code/session_01KZyUSGAzVL9yxpsWWPv6Y2
Generated by Claude Code