Reads a database schema and produces an OKF (Open Knowledge Format) bundle

[Auran0s]

Website

okc reads a database schema and produces an OKF (Open Knowledge Format) bundle — a directory of cross-linked markdown documents that turn your schema into a navigable knowledge graph.

Note

OKF is a specification for representing structured metadata as markdown files with YAML frontmatter. This project implements OKF v0.1.

Features

• Deterministic output — same database, same schema, identical bundle every time
• Multi-backend — introspect SQLite and PostgreSQL databases (with a shared Source interface for adding more)
• Standards-based — generates valid OKF v0.1 documents with type, title, description, resource, tags, and timestamp frontmatter
• Cross-linked — foreign key relationships become navigable markdown links across documents
• Auto-indexed — index.md files are generated for every directory, listing both subdirectories and typed entries
• Zero-config — point it at a database URL and get a bundle; no config files needed

Installation

Install from PyPI:

pip install okc

[ntsarb]

What is the benefit of using OKF over an MCP service that dynamically pulls the information from the Database server?

I've been thinking that the duplication of the information (from the DB schema to the MD files) not only requires additional storage space, but also introduces the need and the cost of keeping them synchronised, as well as the risk of a race condition (the Agent reading an outdated schema after the schema has been updated in the DB and before the change is propagated/synced into the MD file of the OKF).

[thorsti]

Nice work on okc — deterministic output and FK links as the knowledge graph is exactly the kind of producer OKF needs.

I want to pick up @ntsarb's point about synchronization drift, because that's the question that kept me busy: I built a similar tool (Postgres → one OKF concept per table) and made freshness the design center rather than a follow-up problem. Two decisions came out of that:

1. Ownership split between generated and curated content. Structure lives in the frontmatter and is rewritten from the database on every generation. The markdown body is never touched by the tool — it belongs entirely to hand-written knowledge (the "why" that no introspection can produce, e.g. "role_id 999 must stay until issue X is closed"). Because regeneration can't destroy curated content, regenerating often becomes cheap — which is half of the drift answer.

2. Drift as a verifiable CI check, not a maintenance promise. erd2okf check compares the live schema against the committed bundle and exits non-zero on structural drift: table/column add, drop, rename, or a type-class change. Deliberately nothing below type class — varchar(10) → varchar(20) stays green. So green means something defined ("no structurally relevant drift"), not "somebody probably regenerated recently". Generation hangs off the migration (Alembic post-migrate hook); the CI check is the backstop for changes that bypass it.

Repo: https://github.com/thorsti/erd2okf — longer write-up (German): https://hackflei.sh/doku-fur-die-einzigen-die-sie-noch-lesen-agenten-googles-okf/

Open question I'd be curious about from the spec side: is a freshness convention worth defining at the bundle level — some standard way for a producer to say "verified against the source, and here is what 'verified' covers" — so consumers/agents don't have to trust every producer's private definition of up-to-date?