Forge messy documents into knowledge bundles.

okfsmith is an open-source CLI that turns Markdown, PDFs, Office docs, and whole folders into OKF v0.2 knowledge bundles — with trust tiers, source provenance, and a built-in conformance validator your agents can check, not just read.

$ pip install okfsmith

GitHub PyPI Docs

Open source · Apache-2.0 OKF v0.2 native Offline-first ingest

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

What it does

A forge for knowledge, not a black box.

Every concept okfsmith emits carries provenance (sources[]), a trust tier, and lifecycle metadata — and every bundle passes a built-in §11 validator. Here is what ships today.

Incremental sync

okfsmith sync processes only new, changed, renamed, or deleted sources — with --watch, --dry-run, and text or JSON output. Re-ingest without the wait.

Trust tiers & provenance

Every concept carries sources[] citations and a generated / verified trust tier. Answers trace back to the exact document they came from.

Temporal model

Validity and supersession are first-class: concepts expire and get replaced, and --as-of lets you query the bundle as it looked on any date.

One-command MCP server

okfsmith mcp serves any bundle over stdio, SSE, or streamable HTTP — with index, search, get, and neighbors tools, plus traverse and diff.

Eval & CI gating

okfsmith eval runs golden-set Q&A with RAG Triad scores and a retrieval-vs-generation diagnosis — and a --fail-under gate for CI pipelines.

Governed write-back

MCP write tools are trust-tier gated: agents can update the bundle through preview/write/audit flows that respect the same tiers reading does.

Similarity deduplication

The extraction pipeline merges near-duplicate entities with stemmed-token Jaccard similarity — dependency-free, offline, and deterministic. Exact-match precedence is untouched.

Web dashboard

okfsmith dashboard opens a local, token-secured UI: drag-and-drop ingest with live progress, an interactive knowledge graph, grounded chat, validation, and eval.

Grounded chat

okfsmith chat is a REPL over your bundle that answers with [concept-id] citations. No relevant concepts, no invented answer — it stays honest instead.

Quickstart

Sixty seconds to a bundle.

Install, scaffold a bundle, ingest offline, validate, and visualize — then point any MCP-capable agent at it.

          
          terminal
          
$ 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

Init

Scaffold a bundle with index.md and log.md. One command, no config files.

Ingest

Parse PDFs, Markdown, Office docs, or whole folders. --no-llm gives a fast, offline, deterministic first pass.

Validate

Check OKF §11 conformance — hard rules E001–E004 plus advisory lints for dead links, orphans, and stubs.

Serve

One MCP command exposes the bundle to any capable agent, every answer traced to sources[].

Resources

Start where you need to.

Source code, install package, and full command reference — all public, all current.