okfsmith

Forge messy documents into OKF v0.2 knowledge bundles.

okfsmith is a Python CLI that ingests PDFs, markdown, wiki dumps, and Notion exports and emits spec-conformant OKF v0.2 bundles: markdown files with YAML frontmatter, plus reserved index.md and log.md. Every concept carries provenance (sources[]), a trust tier, and lifecycle metadata, and every bundle is checked by a built-in §11 validator. Serve it to your agents with one MCP command.

60-second quickstart

pip install okfsmith

okfsmith init ./kb
okfsmith ingest ./kb notes/ report.pdf --no-llm   # offline first pass
okfsmith validate ./kb
okfsmith graph ./kb --format html   # writes ./kb/viz.html — open in a browser

Point any MCP-capable agent at the bundle:

pip install "okfsmith[mcp]"
okfsmith mcp ./kb

Tools exposed: eight read tools (index, list, search, get, neighbors, traverse, provenance, diff) plus four governed write-back tools (preview_write_concept, write_concept, update_concept, audit_log) — every answer traces back to sources[] in the bundle, and every write lands unverified, validator-gated, provenance-stamped, and audit-logged.

⭐ If okfsmith helped you, a star means a lot — it helps other developers find the project.

Why okfsmith

Clean markdown already has good OKF tooling. The messy middle — 200-page PDFs with broken reading order, sprawling Notion exports, wiki dumps — is where knowledge usually lives, and that’s what okfsmith ingests first:

parse → section → extract → link → emit → validate → serve

• Tiered parsing, free first. Tier 1 is local and keyless: LiteParse for PDFs, stdlib parsing for markdown/text. Office formats (.docx, .pptx, .xlsx) via the optional okfsmith[office] extra; Docling OCR sidecar via okfsmith[ocr] for scanned pages. PyMuPDF is deliberately avoided (AGPL).
• Two extraction modes. --no-llm writes one draft concept per section — fast, offline, deterministic. With an LLM (Ollama by default, or an