OKFgraph

Ladybug-backed knowledge graph with Rust-driven Jina v5 embeddings, model-free graph retrieval, and agent-first MCP + CLI surfaces.

OKFgraph is a Python library, CLI (okf), and MCP server (okf-mcp) for building, querying, and maintaining a knowledge graph from Markdown/OKF documents. It combines hybrid semantic search (vector + FTS, RRF-fused), chunk-level retrieval, model-free PPR retrieval that works with no embedding model loaded, structural diffing, scored health checks, and Obsidian-vault compatible wikilinks — in a single LadybugDB file.

Design stance: slim dependencies, no legacy fallbacks. Embeddings run through the embroider Rust wheel (ONNX Runtime, no torch / transformers / optimum anywhere). PDF conversion runs through the bobine Rust engine behind a swappable DocumentConverter seam. What isn't needed isn't installed.

Features

Installation

Requires Python ≥ 3.11. You must pick exactly one ONNX Runtime extra, cpu or gpu:

CPU or GPU?

Not sure? Run nvidia-smi: if it lists a GPU, take [gpu]. After installing, okf doctor shows cuda_usable=True/False. With a GPU present but the CPU runtime installed it adds an ort_gpu_unused note, and --device auto logs a warning when it falls back to CPU. Switching later is safe: the extras conflict, so installing one replaces the other. Vectors made on CPU (FP32) and GPU (FP16) cannot share one graph (the precision pin refuses it), so pick before the first import or plan a reimport.

PyPI

pip install "okfgraph[gpu,pdf]"   # NVIDIA GPU
pip install "okfgraph[cpu,pdf]"   # everything else

From source with uv (no Rust toolchain needed: the embedding engine is the external embroider package). Name every extra in one uv sync: each sync makes the venv exactly what it names, so a later uv sync --extra pdf would uninstall the runtime again.

git clone <repo> && cd OKFgraph
uv sync --extra gpu --extra pdf --extra dev   # NVIDIA GPU
uv sync --extra cpu --extra pdf --extra dev   # everything else

(pdf = bobine PDF converter, dev = pytest; drop what you don't need. Bare uv sync installs the core only, with no runtime: the first encode then fails with an install hint.)

Prefer a system-wide ONNX Runtime (conda, distro package, self-built)? Skip both extras and point ORT_DYLIB_PATH at your onnxruntime 1.29 library instead — but never rely on bare OS-loader discovery: a stale system DLL (e.g. in System32) fails the load instead of being used.

Core dependencies are deliberately few: ladybug==0.21.2, embroider>=0.3.2,<0.4 (the shared embedding engine — github.com/opticsWolf/embroider, also used by bobine), onnxruntime==1.29.0 (one pinned ORT binary shared by bobine + embroider; ORT_DYLIB_PATH-overridable), mordant, mcp>=2.0, pydantic, pyyaml, numpy, python-frontmatter, fasteners. There is no torch, no transformers, no optimum, no PDF stack in the core install.

Quick start

okf init --db-path kb.db --bundle-root kb/   # once; persists to okfgraph.toml
okf import --all                             # delta-aware bulk import
okf search "honey badger defense"         # hybrid semantic search
okf search --rank ppr "honey badger"      # same question, no model load
okf read savanna --include context --max-tokens 1500
okf traverse savanna --relationship LINKS_TO --direction BOTH
okf diff                                  # drift: graph vs bundle dir
okf doctor                                # health score + findings
okf lint kb/                               # pre-import gate: frontmatter + links, no model
okf produce --from sqlite --source shop.db --output-dir kb/  # SQLite → bundle (lint pre-flighted)
okf images savanna                        # image assets on one concept
okf image img-1 --output-path asset.png   # fetch one asset

Programmatic usage

from pathlib import Path
from okfgraph import OKFRouter

router = OKFRouter(db_path="kb.db", bundle_root="kb/", embedding_dim=512)

# One vocabulary: every operation lives on the router (24 ops), raises
# OKFError(code) with a stable exit plan, and returns dict/list data.

# Import: whole bundle (delta-aware), one file, or raw reasoning
result = router.import_bundle(None)   # every configured root -> {"concept_ids", "images"}
cid = router.import_file("kb/auth.md", mode="text")["concept_id"]
th = router.ingest("thoughts", thoughts="Session decided X because Y",
                   topic="auth-refactor")["concept_id"]

# Search: hybrid (default), hub-blended, or model-free PPR
hits   = router.search("session auth decisions", limit=5)
hubbed = router.search("session auth decisions", rank="hub")
cold   = router.search("auth refactor", rank="ppr")  # no ONNX load

# Read: full shapes, or a token-budgeted section list
doc     = router.read("auth", include="body")
reading = router.read("auth", include="context", max_tokens=1500)

# Image assets are first-class read ops
imgs = router.list_images(cid)
row = router.get_image(imgs[0]["id"])

# Maintain: drift, health, links
print(router.diff(Path("kb/"))["identical"])   # in sync; differs -> DIFF_DIFFERENT (report on err.data)
print(router.doctor()["report"]["score"])      # 0-100
print(router.doctor(stale_days=365, fix=True))  # repair pass, then re-score
print(router.repair_links())                    # re-point broken links -> {"repaired": n}

# Export: OKF bundle or Obsidian vault
router.export_bundle(Path("out-okf/"))
router.export_bundle(Path("out-vault/"), flavor="obsidian")

router.close()

Ingestion kinds

Params that belong to another kind are refused (BAD_VALUE naming them), not silently dropped.

Frontmatter that matters: title, type, tags, aliases: [...] (wikilink names), id: (stable identity, preserved as uid, written back on export), reviewed: true (immune to doctor --fix). Credentials in resource: URIs are stripped to ***@ at parse time (graphs imported before 0.2.3 keep old values until re-import). Rule of thumb: thoughts > md > pdf — reasoning you already hold beats re-extracting it from files.

CLI reference

Eight verbs mirror the MCP tools; maintenance commands cover the rest. Global flags (--db-path, --bundle-root, --embedding-dim, --model-id, --max-length, …) are documented once in okf --help, accepted everywhere, and usually live in okfgraph.toml. Every command accepts --json (D5): human renderer by default, the result envelope ({ok, op, data, warnings, error}) on stdout with --json. Results always go to stdout and logs to stderr (-q silences logs, never results). Failures print [ERROR] CODE: message (remedy) on stderr (plus the error envelope on stdout under --json) and exit 0 ok / 1 state·outcome / 2 usage. Outcomes (lint errors, diff differences, doctor --strict findings) still render their report before exiting 1. Typed state codes include DB_LOCKED (the db is open in another process — okf commands run one at a time per database; when okf-mcp is serving, query through it), NO_ORT_RUNTIME (no/broken ONNX Runtime), and the pin set. Concurrency: one process per db file; the 0-byte <db>.lock beside it is ladybug's own lock marker and is harmless when no process holds it. A leftover after a crash/kill is indistinguishable from a live hold at first glance — check processes first, then remove by hand if stale (okf doctor reports it; the CLI never auto-deletes). Pin the database in okfgraph.toml (db_path = "kb.db", overridable per-invocation with OKFGRAPH_DB_PATH) so a held-open default can never silently fork a second database. Unexpected failures (INTERNAL) also write the full traceback — with argv, versions and platform — to a crash file (%LOCALAPPDATA%\okfgraph\crash\, else $XDG_STATE_HOME/~/.local/state; OKF_CRASH_DIR overrides, newest 20 kept). The final [ERROR] line names the file, so it survives tail, and --json carries it in error.fields.crash_report. Start-up failures (a broken install, a native DLL, a half-edited checkout) are covered too: the okf launcher enters through okfgraph._entry, which guards the package import itself.

Only commands that embed text (search except --rank ppr, import, ingest) load the model (~30s cold per process); read, traverse, lint, diff, doctor and export never do — batch searches, use okf shell for a warm session, and reach for --rank ppr for topic queries in cold sessions. Omit --bundle-root entirely for file-free mode: thoughts ingest, search, read, traverse, doctor, and export work from the DB alone (file-side ops fail fast naming the missing root). Thought IDs are namespaced (thoughts/<topic>/<ts>_<id>), so a fileless graph exports into a tidy tree.

MCP server

8 tools, MCP ≥ 2.0, stdio transport. Wire once per project with a stable database — --db-path, OKFGRAPH_DB_PATH or [database] db_path in okfgraph.toml; the server refuses to boot without one (CONFIG_INVALID, exit 2) since a temp dir means amnesia every session. --bundle-root defaults to the database's parent directory. First boot creates the schema; pre-approve the ingest / export_bundle / export_concept write tools for knowledge workflows. .mcp.json ships a ready config (uv run --project . okf-mcp). Every tool returns the result envelope ({ok, op, data, warnings, error}); failures raise so the result carries isError: true with the error envelope as text — never a bare traceback.

okf-mcp --db-path ./kb.db --bundle-root ./kb

Verify wiring with any search — an empty graph returns [], which still proves the plumbing works.

Skills

Harness-neutral skill sources live in skills/ (Claude Code auto-loads .claude/skills/<name>/SKILL.md; other harnesses have their own dirs — see docs/harness-integration.md):

• okfgraph-mcp — finding knowledge via MCP tools (pick this or CLI).
• okfgraph-cli — same graph through okf shell commands.
• okfgraph-ingest — feeding discipline: what to store, which kind, converter modes, wikilink/alias conventions. Install alongside either finder when the agent should persist knowledge.

Architecture

                ┌──────────── MCP (8 tools) / CLI (8 verbs + maintenance)
                │                        │
          OKFRouter (facade: owns conn, encoder, lock; thin proxies)
                │
   ┌────────────┼──────────────────────────────────────────┐
   │            │                                          │
Import ──► Embed ──► Search ◄── ranking ──► Export ──► Doctor/Diff
   │         │         │        (seeds+PPR)     │           │
   │         │         │                   links.py        │
Delta ──► Schema ──► ImageAssets ──► Purge ──► Ingest ──► Converters
   │                                                    (bobine seam)
   └──────────────── LadybugDB (graph + vector + FTS, one file) ──┘
                         ▲
              Rust embroider (Jina v5, ORT) — device `auto` (CUDA→FP16 weights
              from the published mirror, CPU→FP32; `--precision` pins it),
              CPU arena off by default (`--cpu-arena` opts in), tokenize
              (ceiling `--max-length`, default 8192, max 32768), last-token
              pool, L2-norm, Matryoshka truncate; precision pinned per graph
              (Meta, fail-closed); numerics pinned by tests/test_parity.py

Components live in okfgraph/components/ (one concern each, dependencies injected): search, ranking (pure seeds + exact PPR), links (pure extraction + name index), import_ (batch/single upsert, delta-aware), export (okf/obsidian flavors), diff (structural compare), doctor (scored scan + safe fixes), embedding (Rust bridge + chunking), converters (DocumentConverter protocol + BobineConverter), image_assets, delta, purge, schema, ingest.

Key design decisions:

• Rust-only embeddings, fail-fast — no Python fallback; a mid-run stack switch would silently mix vector spaces in one index.
• Lazy session init — router construction never downloads the model or builds the ONNX session; first encode opens once (thread-safe), token counting uses a tokenizer-only handle, so PPR search, budgeted reads, diff, and doctor stay cold.
• Last-token pooling (not mean) — required by Jina v5; mean pooling breaks alignment with stored vectors.
• Single pinned ORT (onnxruntime==1.29.0, ORT_DYLIB_PATH-overridable) shared by bobine + embroider.
• Bobine is a plugin, not a dependency — DocumentConverter.convert() is the seam; provider owns its options (routing_mode, extract_images); missing bobine → clear RuntimeError, never a silent fallback path.
• Deterministic by construction — sorted traversal order, fixed PPR constants and accumulation order, golden fixtures under tests/fixtures/ (PPR scores, diff reports, doctor scores, vault round-trips).
• Bundle is source of truth, graph is the index — edit markdown, re-import; verify ingests by searching, since empty [] proves wiring while errors prove broken setup.
• MCP-first surface — CLI mirrors the same verbs; maintenance (diff, doctor) is CLI-only to keep the agent tool surface at 8.

API reference (OKFRouter ops)

One vocabulary of 24 operations on the facade (mixins QueryOps, IngestOps, ExportOps, AdminOps); every failure raises OKFError(code, message, fields?, remedy?) — UsageError (exit 2) for caller mistakes, StateError/OutcomeError (exit 1) for graph state and domain outcomes (the class always follows the code). Outcome errors (DIFF_DIFFERENT, DOCTOR_FINDINGS, LINT_ERRORS) carry the full result on err.data. A passed param the chosen path ignores is refused with BAD_VALUE naming it in fields["ignored"].

Components remain reachable for advanced use (search_engine.search_hybrid, embed_engine.count_tokens, export_mgr, diff_mgr, …); the ops are the stable surface. embed_engine.reconstruct_document(id) stays the ~98% chunk→markdown rebuild.

Testing

uv run --project . pytest tests/ -q        # full suite (model loads; takes a while)
uv run --project . pytest tests/test_ranking.py tests/test_mcp_server.py -q   # fast subset
# Rust unit tests live in the embroider repo:
# https://github.com/opticsWolf/embroider (cargo test --locked)

Golden fixtures under tests/fixtures/ (ppr_graph, diff_a/diff_b, doctor_bundle, obsidian_vault, ppr_bundle) lock deterministic behavior: PPR scores byte-stable across runs, diff reports exact, doctor score pinned (83 on the fixture bundle), obsidian export→import edge-identical. Live suites reuse one class-scoped router each so the ONNX model loads once per class.

Project structure

okfgraph/
├── okfgraph/
│   ├── __init__.py        # ConceptModel, OKFRouter, cli_main
│   ├── models.py          # ConceptModel / ChunkModel / ImageAssetModel (extra frontmatter allowed)
│   ├── settings.py        # okfgraph.toml + env + CLI merge (per-key precedence, config spellings raise)
│   ├── errors.py          # OKFError(code, fields, remedy) + UsageError / StateError / OutcomeError
│   ├── router.py          # OKFRouter facade = OKFRouter(AdminOps, ExportOps, IngestOps, QueryOps)
│   ├── ops/               # the 24-op vocabulary: query.py, ingest.py, export.py, admin.py
│   ├── cli.py             # okf: 8 core verbs + maintenance + images/image, --json (D5/D6)
│   ├── mcp_server.py      # okf-mcp: 8 tools, MCP ≥ 2.0, lifespan-managed router, envelope/_ToolFailure
│   ├── images.py          # IngestMode (text + vision-onnx since 0.8.0), planning helpers
│   ├── security.py        # SSRF/domain guards for remote images
│   └── components/        # ranking, links, search, lint, import_, export, diff, doctor,
│                          # embedding, converters, image_assets, delta, purge, schema, ingest
├── skills/                # okfgraph-mcp, okfgraph-cli, okfgraph-ingest (harness-neutral source)
├── tests/fixtures/        # conformance corpus: ppr, diff, doctor, obsidian, bundles
├── docs/                  # architecture spec (v6.5), converters, chunking, harness guides; archive/ holds completed plans
├── .mcp.json              # ready MCP wiring (uv run --project . okf-mcp)
└── pyproject.toml         # slim core deps + pdf/dev extras

Requirements

Core (uv sync): ladybug==0.21.2, embroider>=0.3.2,<0.4 (PyPI wheels, github.com/opticsWolf/embroider), mordant>=0.9, mcp>=2.0, pydantic>=2, pyyaml>=6, numpy>=1.26, python-frontmatter>=1, fasteners>=0.19. Python ≥ 3.11. Plus exactly one ORT provider: okfgraph[cpu] (onnxruntime==1.29.0) or okfgraph[gpu] (onnxruntime-gpu[cuda,cudnn]==1.29.0) — shared with bobine via ORT_DYLIB_PATH.

• --extra pdf: bobine>=0.6 (default PDF converter).
• --extra dev: pytest>=8.

Model licences

okfgraph's code is Apache-2.0 OR MIT. The model weights it downloads at runtime are not part of this repository and carry their own licences. Check them before any commercial use.

• Every Jina v5 model is non-commercial (CC BY-NC 4.0). okfgraph cannot embed anything without one, so using okfgraph commercially requires a commercial licence from Jina AI (see the model cards).
• PDF tables: bobine fetches SLANet-plus from a repository whose card declares AGPL-3.0. Accepted as a runtime fetch (2026-10-01): weights are downloaded, never redistributed. Review before redistributing a service built on --extra pdf.
• Licences are as declared in each repository's model card when checked (2026-09-27). The model cards are authoritative and can change. This table is a pointer, not legal advice.

License

The code is licensed Apache-2.0 OR MIT (see LICENSE). Downloaded model weights are licensed separately; see Model licences.