LOKF toolkit (lokf on PyPI)

Overview

The toolkit is the implementation, not the specification. lokf validate checks frontmatter and bundle shape against the generated JSON Schema. It takes the schema from --schema, else from the [tool.lokf] schema of the nearest pyproject.toml above the bundle, else from a lokf.yaml in the current folder or an ancestor, else from the copy inside the installed package. With --schema <file>.yaml it checks against a domain schema that imports LOKF’s instead, and the extension recipe depends on that flag. From 0.9.0 the package ships its SHACL shapes, and lokf validate --shacl runs them with the [shacl] extra, which the sidecar does not install. So the checks the sidecar runs are lokf validate (JSON Schema), --check-refs and --check-excerpts.

lokf convert projects to RDF as Turtle, N-Triples, JSON-LD, RDF/XML, N3 or TriG, and lokf export writes the four files a bundle publishes, graph.nt among them. lokf serve exposes a SPARQL endpoint, lokf query runs a SPARQL query against the bundle, and lokf mcp serves it over the Model Context Protocol (MCP). From 0.9.0, convert, query, serve and export take --schema as validate does, and project each class and slot a domain schema declares under its own IRI. lokf tables writes CSV, Parquet or SQLite: one table per concept type plus a relations table. For BigQuery or Athena it writes the Parquet and prints the external-table statements that register it.

lokf registry init, add, list and resolve keep a registry of bundles offline. A domain’s federation build registers each member release with lokf registry add and exports it with lokf export (docs/federation.md). The command line also carries new, propose, vocab, adapt and skills, and the package has a [tables] extra, which adds pandas and pyarrow, beside [build]. PyPI lists 0.9.0 as the latest release.

lokf validate --check-refs finds typed-relation targets in the bundle’s own namespace with no matching concept, and leaves targets outside its base_iri alone. This repository’s own just lokf-check-refs recipe calls it, with --check-excerpts, which finds each sources[].excerpt in its local file and counts an excerpt on a URL without fetching it. It takes the relation slots from the schema, so a domain schema’s own slots are covered without the recipe restating a predicate list.

Scaffolded bundles depend on lokf[build]>=0.9.0, a floor and not a pin. Since 0.56.1 they also depend on rust-just==1.47.0, so that uv.lock checks the recipe runner by hash and uv run just runs it. The [build] extra installs the full linkml package: the whole generator suite, not just the runtime. So a scaffolded sidecar already has the LinkML generators for a domain-schema extension, with no extra installation.

Where Python is unavailable, the skills fall back to a structural cross-check against the raw schema, which is not a validation run. They read it from the commit tagged v0.9.0, which matches the lokf floor: raw.githubusercontent.com/nicholsn/lokf/eab5fe35b99e154bec9aabc03656446b891311f8/lokf.yaml. Since 2026-10-05 the URL names that commit, never a tag or main, because a tag can be moved. The pin moves with the floor, so the fallback cross-checks against the schema the installed toolkit enforces. That file is byte-identical to the schema inside the lokf 0.9.0 wheel, which uv sync --locked checks against .lokf/uv.lock wherever Python is present.

ktl-librarian checks the toolkit’s version in a live session. It compares the latest lokf on PyPI with the >= floor in .lokf/pyproject.toml. For a minor or patch release it raises the floor, runs uv sync and validates again. For a major release, or a breaking change in the changelog, it asks the person first. It never bumps linkml on its own.