feat: OpenKB MVP — Karpathy's LLM Knowledge Base, powered by PageIndex

[KylinMountain]

Summary

OpenKB — Karpathy's LLM Knowledge Base workflow as a CLI, powered by PageIndex.

Drop documents in. Get an auto-maintained, cross-linked wiki out.

Features

• okb init — Interactive setup
• okb add — Short docs (pymupdf) + long PDFs (PageIndex local/cloud)
• okb query — Streaming Q&A with PageIndex cloud streaming
• okb watch — Auto-compile on file changes
• okb lint — Structural + knowledge health checks
• okb list / status — Knowledge base overview
• Obsidian compatible wiki output

Tech Stack

PageIndex, markitdown, OpenAI Agents SDK, LiteLLM, Click, watchdog

[KylinMountain]

Code review

Found 1 issue:

1. extract_pdf_images and convert_pdf_with_images in images.py open pymupdf documents with explicit .close() instead of context managers. If an exception is raised during page iteration (e.g. corrupt image block, pixmap allocation failure), the PDF file handle leaks. This is the same bug pattern that was already fixed in converter.py:get_pdf_page_count (commit c525455), but images.py was missed. Fix: replace doc = pymupdf.open(...) / doc.close() with with pymupdf.open(...) as doc:.

OpenKB/openkb/images.py

Lines 38 to 74 in 1637697

	doc = pymupdf.open(str(pdf_path))
	for page_idx in range(len(doc)):
	page = doc[page_idx]
	page_num = page_idx + 1
	for block in page.get_text("dict")["blocks"]:
	if block["type"] != 1: # not an image block
	continue
	width = block.get("width", 0)
	height = block.get("height", 0)
	if width < _MIN_IMAGE_DIM or height < _MIN_IMAGE_DIM:
	continue
	image_bytes = block.get("image")
	if not image_bytes:
	continue
	try:
	pix = pymupdf.Pixmap(image_bytes)
	if pix.n > 4:
	pix = pymupdf.Pixmap(pymupdf.csRGB, pix)
	img_counter += 1
	filename = f"p{page_num}_img{img_counter}.png"
	save_path = images_dir / filename
	pix.save(str(save_path))
	pix = None
	except Exception:
	logger.warning("Failed to save image block on page %d", page_num)
	continue
	rel_path = f"images/{doc_name}/{filename}"
	page_images.setdefault(page_num, []).append(rel_path)
	doc.close()
	return page_images

OpenKB/openkb/images.py

Lines 89 to 125 in 1637697

	doc = pymupdf.open(str(pdf_path))
	for page_idx in range(len(doc)):
	page = doc[page_idx]
	page_num = page_idx + 1
	parts.append(f"\n\n<!-- Page {page_num} -->\n")
	for block in page.get_text("dict")["blocks"]:
	if block["type"] == 0: # text block
	lines = []
	for line in block["lines"]:
	spans_text = "".join(span["text"] for span in line["spans"])
	lines.append(spans_text)
	parts.append("\n".join(lines))
	elif block["type"] == 1: # image block
	width = block.get("width", 0)
	height = block.get("height", 0)
	if width < _MIN_IMAGE_DIM or height < _MIN_IMAGE_DIM:
	continue
	image_bytes = block.get("image")
	if not image_bytes:
	continue
	try:
	pix = pymupdf.Pixmap(image_bytes)
	if pix.n > 4:
	pix = pymupdf.Pixmap(pymupdf.csRGB, pix)
	img_counter += 1
	filename = f"p{page_num}_img{img_counter}.png"
	(images_dir / filename).write_bytes(pix.tobytes("png"))
	pix = None
	parts.append(f"\n\n")
	except Exception:
	logger.warning("Failed to save image block on page %d", page_num)
	doc.close()
	return "\n".join(parts)

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[rejojer]

Code review

Found 2 issues:

1. README claims LiteLLM is "pinned to a safe version" but pyproject.toml has no version pin. Line 67 of README.md states LiteLLM is (pinned to a safe version), but pyproject.toml line 17 lists the dependency as bare "litellm" with no version constraint (==, >=, ~=, etc.). Any version -- including potentially insecure ones -- can be installed.

OpenKB/README.md

Lines 66 to 68 in 854294c

	OpenKB comes with [multi-LLM support](https://docs.litellm.ai/docs/providers) (e.g., OpenAI, Claude, Gemini) via [LiteLLM](https://github.com/BerriAI/litellm) (pinned to a [safe version](https://docs.litellm.ai/blog/security-update-march-2026)).

OpenKB/pyproject.toml

Lines 16 to 18 in 854294c

	"watchdog>=3.0",
	"litellm",
	"openai-agents",

2. test_short_pdf_converted_via_markitdown mocks the wrong code path. The test patches openkb.converter.MarkItDown and openkb.converter.pymupdf.open, but converter.py line 99-101 routes short PDFs through convert_pdf_with_images() (from openkb.images), not MarkItDown. The MarkItDown mock is never exercised, and convert_pdf_with_images is not mocked, so the test either fails at runtime or passes for the wrong reasons.

OpenKB/tests/test_converter.py

Lines 83 to 108 in 854294c

	class TestConvertDocumentPdfShort:
	def test_short_pdf_converted_via_markitdown(self, kb_dir, tmp_path):
	"""PDF under threshold is converted with markitdown."""
	src = tmp_path / "short.pdf"
	src.write_bytes(b"%PDF-1.4 fake content")
	fake_result = MagicMock()
	fake_result.text_content = "# Short PDF\n\nConverted content."
	with (
	patch("openkb.converter.pymupdf.open") as mock_mu,
	patch("openkb.converter.MarkItDown") as mock_mid_cls,
	):
	fake_doc = MagicMock()
	fake_doc.page_count = 5 # below default threshold of 20
	fake_doc.__enter__ = MagicMock(return_value=fake_doc)
	fake_doc.__exit__ = MagicMock(return_value=False)
	mock_mu.return_value = fake_doc
	mock_mid_cls.return_value.convert.return_value = fake_result
	result = convert_document(src, kb_dir)
	assert result.skipped is False
	assert result.is_long_doc is False
	assert result.source_path is not None
	assert result.source_path.exists()

OpenKB/openkb/converter.py

Lines 98 to 102 in 854294c

	markdown = copy_relative_images(markdown, src.parent, doc_name, images_dir)
	elif src.suffix.lower() == ".pdf":
	# Use pymupdf dict-mode for PDFs: text + images inline at correct positions
	markdown = convert_pdf_with_images(src, doc_name, images_dir)
	else:

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}