okf-tools

Tooling for the Open Knowledge Format (OKF), Google Cloud's open standard for markdown-plus-frontmatter knowledge bundles. Serializes concept documents consistently and validates bundles against our strict house profile (4 required frontmatter keys: type, title, description, timestamp).

The import module and CLI are named okf; the distribution is okf-tools.

• okf.render_document(frontmatter, body) - serialize one concept (----delimited YAML frontmatter + body)
• okf.render_index(entries, *, is_root, title) - render a directory index of bulleted links; the root index adds okf_version
• okf.validate_document(text, *, filename, is_root_index=False) - lint one file, returns list[Finding]
• okf.validate_bundle(root) - walk a bundle tree and lint every file; broken cross-links are warnings
• python -m okf validate <bundle-dir-or-file> - human-readable findings (--json for machine output), exit 1 on any error

Pure Python (>=3.11), single dependency pyyaml.

GitHub Action

This repo is also a reusable composite action that validates a bundle in CI. Pin it to a released tag:

- uses: actions/checkout@v4
- uses: IonfarAI/okf-tools@v0.1.0
  with:
    path: .   # bundle directory or a single concept .md file (default ".")

It runs on the runner's preinstalled Python with no setup-python step, imports the linter from source (no build), and installs pyyaml only if the runner does not already have it. Typical added time is a second or two. It fails the job on any error-level finding.

The tag you pin is the linter version the gate applies; v0.1.0 targets OKF profile okf_version 0.1.

Install

pip install "git+https://github.com/IonfarAI/okf-tools@v0.1.0"