') + ')', 'gi'); if (regex.test(text)) { found = true; var frag = document.createDocumentFragment(); var parts = text.split(regex); parts.forEach(function(part, i) { if (i % 2 === 0) { frag.appendChild(document.createTextNode(part)); } else { var span = document.createElement('span'); span.className = 'userscript-highlight'; span.textContent = part; frag.appendChild(span); } }); node.parentNode.replaceChild(frag, node); } }); } else if (node.nodeType === 1 && node.childNodes) { // element var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT']; if (!skipTags.includes(node.tagName)) { Array.from(node.childNodes).forEach(highlight); } } } highlight(document.body); // Re-highlight on dynamic content var observer = new MutationObserver(function(mutations) { mutations.forEach(function(m) { m.addedNodes.forEach(function(node) { if (node.nodeType === 1 || node.nodeType === 3) highlight(node); }); }); }); observer.observe(document.body, { childList: true, subtree: true }); })(); } } catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + ', 'i'); if (__m === '*' || __re.test(location.href)) { // Strip utm_, fbclid, gclid, etc. from all links on page (function() { var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content', 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid', 'ref', 'ref_src', 'source', 'medium', 'campaign']; function cleanUrl(url) { try { var u = new URL(url, window.location.origin); var changed = false; trackingParams.forEach(function(p) { if (u.searchParams.has(p)) { u.searchParams.delete(p); changed = true; } }); return changed ? u.toString() : url; } catch (e) { return url; } } function cleanLinks() { document.querySelectorAll('a[href]').forEach(function(a) { var clean = cleanUrl(a.href); if (clean !== a.href) a.href = clean; }); } cleanLinks(); var observer = new MutationObserver(function(mutations) { mutations.forEach(function(m) { m.addedNodes.forEach(function(node) { if (node.nodeType === 1) { if (node.tagName === 'A') cleanLinks(); node.querySelectorAll('a[href]').forEach(function(a) { var clean = cleanUrl(a.href); if (clean !== a.href) a.href = clean; }); } }); }); }); observer.observe(document.body, { childList: true, subtree: true }); })(); } } catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); } })(); (function(){ try { var __m = "youtube.com"; var __re = new RegExp('^' + "youtube\\.com" + ', 'i'); if (__m === '*' || __re.test(location.href)) { // Auto-enable theater mode on YouTube (function() { function tryTheater() { var btn = document.querySelector('button[aria-label="Theater mode"], ytd-player #player button[title="Theater mode"]'); if (btn && !btn.classList.contains('activated')) { btn.click(); } } // Try immediately tryTheater(); // Try after navigation (SPA) var lastUrl = location.href; setInterval(function() { if (location.href !== lastUrl) { lastUrl = location.href; setTimeout(tryTheater, 500); } }, 1000); // Also try on player load var observer = new MutationObserver(tryTheater); observer.observe(document.body, { childList: true, subtree: true }); })(); } } catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + ', 'i'); if (__m === '*' || __re.test(location.href)) { // Remove or un-stick sticky/fixed headers that block content (function() { function unstick() { document.querySelectorAll('header, nav, [role="banner"], .header, .navbar, .sticky, .fixed-top, [style*="position: fixed"], [style*="position:sticky"]').forEach(function(el) { if (el.style.position === 'fixed' || el.style.position === 'sticky' || getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') { el.style.position = 'static'; el.style.top = 'auto'; el.style.zIndex = 'auto'; } }); } unstick(); var observer = new MutationObserver(unstick); observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] }); })(); } } catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); } })(); })(); perf(converter): lazy-import markitdown to cut startup ~24% and enable slim packaging by KylinMountain · Pull Request #186 · VectifyAI/OpenKB · GitHub
Skip to content

perf(converter): lazy-import markitdown to cut startup ~24% and enable slim packaging - #186

Merged
KylinMountain merged 3 commits into
mainfrom
claude/project-desktop-compilation-vfd4q7
Jul 20, 2026
Merged

perf(converter): lazy-import markitdown to cut startup ~24% and enable slim packaging#186
KylinMountain merged 3 commits into
mainfrom
claude/project-desktop-compilation-vfd4q7

Conversation

@KylinMountain

@KylinMountainKylinMountain commented Jul 17, 2026

Copy link
Copy Markdown
Collaborator

Summary

markitdown was imported at the top of openkb/converter.py, so every
import openkb eagerly pulled in markitdown → magika → onnxruntime (tens of
MB, slow to import) — even for commands that never touch an Office/HTML
document. But markitdown is only used in one branch of convert_document: the
non-PDF, non-Markdown path. This PR moves the import into that branch.

Changes

  • openkb/converter.py — import MarkItDown lazily inside the Office-format
    branch instead of at module top level.
  • tests/test_converter.py — update the mock patch target to
    markitdown.MarkItDown (the attribute the local import binds), and add a
    regression test that spawns a fresh interpreter and asserts
    import openkb.converter loads none of markitdown / magika / onnxruntime.

Why it helps (measured)

  • import openkb.cli cold start 4.64s → 3.53s (~24% faster); magika /
    onnxruntime / markitdown no longer load unless an Office-format document is
    actually converted.
  • A packaged (PyInstaller) build can drop magika/onnxruntime (~25 MB
    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

  • markitdown appends warning filters when it imports, but leaves the CLI's
    front "ignore" filter (set in cli.py) at index 0, so no re-suppression is
    needed at the new import site — verified empirically and documented in a code
    comment.
  • The new guard test runs in a subprocess so it is deterministic regardless of
    what earlier tests already imported into sys.modules. Without it, a future
    change that reintroduces a top-level markitdown import would regress startup
    silently while every functional test stays green.
  • Behavior change: a missing/broken markitdown now surfaces when converting an
    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.py clean.

https://claude.ai/code/session_01KZyUSGAzVL9yxpsWWPv6Y2

Generated by Claude Code

claudeand others added 3 commits July 17, 2026 16:22
@claude
perf(converter): lazy-import markitdown to cut startup and enable sli…
53740cb
…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
@claude
test(converter): guard that importing converter stays markitdown-free
fb9a6d0
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
@KylinMountain
Merge branch 'main' into claude/project-desktop-compilation-vfd4q7
fa9b7a9
Bring in #189 (Knowledge Workbench frontend) and #191 (openai==2.44.0 pin)
so the lazy-import converter branch is current with main before review.
Claude-Session: https://claude.ai/code/session_01XMxbhmAkxxVV8CFWCZDBaG
@KylinMountain
KylinMountain merged commit 715a623 into mainJul 20, 2026
4 checks passed
@KylinMountain
KylinMountain deleted the claude/project-desktop-compilation-vfd4q7 branch July 20, 2026 14:16
@gwokhougwokhou mentioned this pull request Jul 22, 2026
Open
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@KylinMountain@claude