lokf 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (84) hide show
  1. lokf-0.1.0/.github/workflows/docs.yml +50 -0
  2. lokf-0.1.0/.github/workflows/publish.yml +51 -0
  3. lokf-0.1.0/.gitignore +24 -0
  4. lokf-0.1.0/.python-version +1 -0
  5. lokf-0.1.0/LICENSE +26 -0
  6. lokf-0.1.0/PKG-INFO +187 -0
  7. lokf-0.1.0/README.md +155 -0
  8. lokf-0.1.0/SPEC.md +422 -0
  9. lokf-0.1.0/docs/assets/js/cytoscape.min.js +32 -0
  10. lokf-0.1.0/docs/examples.md +69 -0
  11. lokf-0.1.0/docs/getting-started.md +82 -0
  12. lokf-0.1.0/docs/graph.md +338 -0
  13. lokf-0.1.0/docs/guide/concepts.md +66 -0
  14. lokf-0.1.0/docs/guide/markdown-to-rdf.md +63 -0
  15. lokf-0.1.0/docs/guide/relationships.md +41 -0
  16. lokf-0.1.0/docs/guide/types.md +66 -0
  17. lokf-0.1.0/docs/guide/validation.md +53 -0
  18. lokf-0.1.0/docs/hooks/lokf_hooks.py +97 -0
  19. lokf-0.1.0/docs/index.md +93 -0
  20. lokf-0.1.0/docs/reference/api.md +58 -0
  21. lokf-0.1.0/docs/reference/artifacts.md +52 -0
  22. lokf-0.1.0/docs/specification.md +1 -0
  23. lokf-0.1.0/docs/toolkit/agents.md +64 -0
  24. lokf-0.1.0/docs/toolkit/convert.md +80 -0
  25. lokf-0.1.0/docs/toolkit/index.md +144 -0
  26. lokf-0.1.0/docs/toolkit/mcp.md +87 -0
  27. lokf-0.1.0/docs/toolkit/proposer.md +161 -0
  28. lokf-0.1.0/docs/toolkit/query.md +101 -0
  29. lokf-0.1.0/docs/toolkit/serve.md +49 -0
  30. lokf-0.1.0/docs/toolkit/tutorial.md +297 -0
  31. lokf-0.1.0/examples/acme-knowledge/datasets/events.md +14 -0
  32. lokf-0.1.0/examples/acme-knowledge/glossary/active-user.md +17 -0
  33. lokf-0.1.0/examples/acme-knowledge/index.md +34 -0
  34. lokf-0.1.0/examples/acme-knowledge/log.md +7 -0
  35. lokf-0.1.0/examples/acme-knowledge/metrics/weekly-active-users.md +42 -0
  36. lokf-0.1.0/examples/acme-knowledge/playbooks/data-freshness-incident.md +23 -0
  37. lokf-0.1.0/examples/acme-knowledge/services/analytics-api.md +18 -0
  38. lokf-0.1.0/examples/acme-knowledge/tables/user-events.md +36 -0
  39. lokf-0.1.0/examples/acme-knowledge.nt +86 -0
  40. lokf-0.1.0/examples/weekly-active-users.nt +22 -0
  41. lokf-0.1.0/justfile +40 -0
  42. lokf-0.1.0/lokf.context.jsonld +267 -0
  43. lokf-0.1.0/lokf.owl.ttl +1190 -0
  44. lokf-0.1.0/lokf.schema.json +2894 -0
  45. lokf-0.1.0/lokf.shacl.ttl +1682 -0
  46. lokf-0.1.0/lokf.yaml +806 -0
  47. lokf-0.1.0/mkdocs.yml +127 -0
  48. lokf-0.1.0/pyproject.toml +65 -0
  49. lokf-0.1.0/src/lokf/__init__.py +20 -0
  50. lokf-0.1.0/src/lokf/agentskills.py +58 -0
  51. lokf-0.1.0/src/lokf/build.py +155 -0
  52. lokf-0.1.0/src/lokf/cli.py +276 -0
  53. lokf-0.1.0/src/lokf/data/lokf.context.jsonld +267 -0
  54. lokf-0.1.0/src/lokf/data/lokf.yaml +806 -0
  55. lokf-0.1.0/src/lokf/export.py +173 -0
  56. lokf-0.1.0/src/lokf/mcp_server.py +200 -0
  57. lokf-0.1.0/src/lokf/model.py +126 -0
  58. lokf-0.1.0/src/lokf/parse.py +43 -0
  59. lokf-0.1.0/src/lokf/propose.py +344 -0
  60. lokf-0.1.0/src/lokf/rdf.py +125 -0
  61. lokf-0.1.0/src/lokf/schema.py +192 -0
  62. lokf-0.1.0/src/lokf/server.py +215 -0
  63. lokf-0.1.0/src/lokf/skills/author-concept/SKILL.md +126 -0
  64. lokf-0.1.0/src/lokf/skills/build-knowledge-base/SKILL.md +118 -0
  65. lokf-0.1.0/src/lokf/skills/enrich-relations/SKILL.md +95 -0
  66. lokf-0.1.0/src/lokf/skills/publish-graph/SKILL.md +85 -0
  67. lokf-0.1.0/src/lokf/skills/query-knowledge-base/SKILL.md +99 -0
  68. lokf-0.1.0/src/lokf/static/cytoscape.min.js +32 -0
  69. lokf-0.1.0/src/lokf/store.py +207 -0
  70. lokf-0.1.0/tests/test_cli.py +114 -0
  71. lokf-0.1.0/tests/test_export.py +178 -0
  72. lokf-0.1.0/tests/test_hooks.py +23 -0
  73. lokf-0.1.0/tests/test_mcp.py +137 -0
  74. lokf-0.1.0/tests/test_model.py +62 -0
  75. lokf-0.1.0/tests/test_propose.py +270 -0
  76. lokf-0.1.0/tests/test_rdf.py +75 -0
  77. lokf-0.1.0/tests/test_review_fixes.py +119 -0
  78. lokf-0.1.0/tests/test_schema.py +87 -0
  79. lokf-0.1.0/tests/test_security.py +70 -0
  80. lokf-0.1.0/tests/test_server.py +142 -0
  81. lokf-0.1.0/tests/test_skills.py +57 -0
  82. lokf-0.1.0/tests/test_store.py +106 -0
  83. lokf-0.1.0/tests/test_vendored.py +16 -0
  84. lokf-0.1.0/uv.lock +2459 -0
@@ -0,0 +1,50 @@
1
+ name: docs
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+
8
+ permissions: {}
9
+
10
+ # Cancel superseded PR builds, but never a production Pages deploy mid-flight.
11
+ concurrency:
12
+ group: docs-${{ github.ref }}
13
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
14
+
15
+ jobs:
16
+ build:
17
+ runs-on: ubuntu-latest
18
+ permissions:
19
+ contents: read
20
+ steps:
21
+ - uses: actions/checkout@v4
22
+ with:
23
+ fetch-depth: 0 # full history for git-revision-date-localized
24
+
25
+ - uses: astral-sh/setup-uv@v5
26
+ with:
27
+ enable-cache: true
28
+
29
+ - name: Build site (strict)
30
+ # --only-group: the docs build doesn't need the project or its runtime
31
+ # deps (mkdocstrings reads src/ statically) — 37 packages instead of 107
32
+ run: uv run --locked --only-group docs mkdocs build --strict
33
+
34
+ - uses: actions/upload-pages-artifact@v3
35
+ with:
36
+ path: site
37
+
38
+ deploy:
39
+ if: github.event_name == 'push' && github.ref == 'refs/heads/main'
40
+ needs: build
41
+ runs-on: ubuntu-latest
42
+ permissions:
43
+ pages: write
44
+ id-token: write
45
+ environment:
46
+ name: github-pages
47
+ url: ${{ steps.deployment.outputs.page_url }}
48
+ steps:
49
+ - uses: actions/deploy-pages@v4
50
+ id: deployment
@@ -0,0 +1,51 @@
1
+ name: publish
2
+
3
+ # Publishes to PyPI via Trusted Publishing (OIDC) when a GitHub Release is
4
+ # published — no API token is stored. Configure the trusted publisher once on
5
+ # PyPI: project "lokf", owner "nicholsn", repo "lokf", workflow "publish.yml",
6
+ # environment "pypi".
7
+ on:
8
+ release:
9
+ types: [published]
10
+ workflow_dispatch:
11
+
12
+ permissions: {}
13
+
14
+ jobs:
15
+ build:
16
+ runs-on: ubuntu-latest
17
+ permissions:
18
+ contents: read
19
+ steps:
20
+ - uses: actions/checkout@v4
21
+ - uses: astral-sh/setup-uv@v5
22
+ with:
23
+ enable-cache: true
24
+
25
+ - name: Test (gate the release)
26
+ run: uv run --group dev pytest -q
27
+
28
+ - name: Build sdist + wheel
29
+ run: uv build
30
+
31
+ - uses: actions/upload-artifact@v4
32
+ with:
33
+ name: dist
34
+ path: dist/
35
+
36
+ publish:
37
+ needs: build
38
+ runs-on: ubuntu-latest
39
+ environment:
40
+ name: pypi
41
+ url: https://pypi.org/project/lokf/
42
+ permissions:
43
+ id-token: write # OIDC token for Trusted Publishing
44
+ steps:
45
+ - uses: actions/download-artifact@v4
46
+ with:
47
+ name: dist
48
+ path: dist/
49
+
50
+ - name: Publish to PyPI
51
+ uses: pypa/gh-action-pypi-publish@release/v1
lokf-0.1.0/.gitignore ADDED
@@ -0,0 +1,24 @@
1
+ # Python
2
+ __pycache__/
3
+ *.pyc
4
+ .venv/
5
+ venv/
6
+
7
+ # LinkML / build scratch
8
+ *.err
9
+ lokf.context.base.jsonld
10
+
11
+ # Regenerated by lokf-build (src/lokf/build.py); kept out of source control
12
+ examples/*.bundle.json
13
+ examples/*.bundle.yaml
14
+
15
+ # Git bundle export
16
+ *.bundle
17
+
18
+ # OS / editor cruft
19
+ .DS_Store
20
+ .fuse_hidden*
21
+ *.swp
22
+
23
+ # MkDocs build output
24
+ site/
@@ -0,0 +1 @@
1
+ 3.12
lokf-0.1.0/LICENSE ADDED
@@ -0,0 +1,26 @@
1
+ Linked Open Knowledge Format (LOKF)
2
+ Copyright (c) 2026 Nolan Nichols
3
+
4
+ This work — the LOKF specification, the LinkML schema, the generated artifacts,
5
+ and the examples — is licensed under the Creative Commons Attribution 4.0
6
+ International License (CC BY 4.0).
7
+
8
+ You are free to:
9
+ Share — copy and redistribute the material in any medium or format.
10
+ Adapt — remix, transform, and build upon the material for any purpose,
11
+ even commercially.
12
+
13
+ Under the following terms:
14
+ Attribution — You must give appropriate credit, provide a link to the license,
15
+ and indicate if changes were made. You may do so in any reasonable manner, but
16
+ not in any way that suggests the licensor endorses you or your use.
17
+
18
+ No additional restrictions — You may not apply legal terms or technological
19
+ measures that legally restrict others from doing anything the license permits.
20
+
21
+ Full legal code: https://creativecommons.org/licenses/by/4.0/legalcode
22
+ Human-readable summary: https://creativecommons.org/licenses/by/4.0/
23
+
24
+ "Open Knowledge Format" and "OKF" refer to the format published by Google Cloud
25
+ (github.com/GoogleCloudPlatform/knowledge-catalog). LOKF is an independent,
26
+ unaffiliated profile built upon it.
lokf-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,187 @@
1
+ Metadata-Version: 2.4
2
+ Name: lokf
3
+ Version: 0.1.0
4
+ Summary: Linked Open Knowledge Format (LOKF) — a semantic profile of Google's Open Knowledge Format, defined once in LinkML
5
+ Project-URL: Documentation, https://www.nolan-nichols.com/lokf/
6
+ Project-URL: Repository, https://github.com/nicholsn/lokf
7
+ Project-URL: Issues, https://github.com/nicholsn/lokf/issues
8
+ Author: Nolan Nichols
9
+ License-Expression: CC-BY-4.0
10
+ License-File: LICENSE
11
+ Keywords: dcat,json-ld,knowledge-graph,linkml,mcp,okf,prov,rdf,sparql
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Intended Audience :: Information Technology
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Topic :: Scientific/Engineering :: Information Analysis
20
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
21
+ Classifier: Topic :: Text Processing :: Markup
22
+ Requires-Python: >=3.11
23
+ Requires-Dist: mcp>=1.2
24
+ Requires-Dist: pyoxigraph>=0.4
25
+ Requires-Dist: pyyaml>=6.0
26
+ Requires-Dist: rdflib>=7.0
27
+ Requires-Dist: ruamel-yaml>=0.18
28
+ Requires-Dist: typer>=0.15
29
+ Provides-Extra: build
30
+ Requires-Dist: linkml>=1.8.5; extra == 'build'
31
+ Description-Content-Type: text/markdown
32
+
33
+ # Linked Open Knowledge Format (LOKF) — v0.1
34
+
35
+ A **semantic profile of Google's Open Knowledge Format (OKF)**. LOKF keeps OKF's
36
+ markdown-plus-frontmatter authoring model but binds every concept, field, and
37
+ relationship to **schema.org, W3C DCAT, and W3C PROV-O**, so a bundle of markdown
38
+ files is *also* valid **JSON-LD** that expands losslessly to **RDF**. The format is
39
+ defined once in **LinkML**; the JSON-LD context, JSON Schema, SHACL shapes, and OWL
40
+ ontology are all generated from that single source.
41
+
42
+ > One sentence: *write OKF markdown, get a queryable knowledge graph for free.*
43
+
44
+ **Documentation:** <https://www.nolan-nichols.com/lokf/>
45
+
46
+ ## Why
47
+
48
+ OKF v0.1 is deliberately minimal — the only required field is `type`, links are
49
+ untyped, and there's no shared vocabulary. LOKF adds exactly three things while
50
+ keeping OKF's ergonomics:
51
+
52
+ 1. **Shared meaning** — types and fields map to public ontology terms.
53
+ 2. **Typed relationships** — `dependsOn`, `derivedFrom`, `isPartOf`, … each pinned
54
+ to an RDF predicate, instead of one untyped markdown link.
55
+ 3. **A real graph** — the same bundle is queryable with SPARQL, validatable with
56
+ SHACL, and reason-able with OWL.
57
+
58
+ It stays **bidirectionally compatible**: every LOKF bundle is a valid OKF bundle,
59
+ and every OKF bundle is valid LOKF with default mappings.
60
+
61
+ ## Files
62
+
63
+ | Path | What it is | Hand-edited? |
64
+ |------|------------|:---:|
65
+ | `lokf.yaml` | **The LinkML schema — the single source of truth.** | ✅ edit this |
66
+ | `SPEC.md` | The human-readable specification. | ✅ |
67
+ | `lokf.context.jsonld` | Generated JSON-LD `@context` (+ `type`→`@type`, `id`→`@id` aliases). Attach to concepts to get Linked Data. | ⚙️ generated |
68
+ | `lokf.schema.json` | Generated JSON Schema — validates frontmatter / bundles. | ⚙️ generated |
69
+ | `lokf.shacl.ttl` | Generated SHACL shapes — validates the RDF graph. | ⚙️ generated |
70
+ | `lokf.owl.ttl` | Generated OWL ontology — reasoning & alignment. | ⚙️ generated |
71
+ | `examples/acme-knowledge/` | A conformant 6-concept reference bundle. | ✅ |
72
+ | `examples/*.nt` | RDF triples produced from the example frontmatter. | ⚙️ generated |
73
+
74
+ ## Anatomy of a LOKF concept
75
+
76
+ `metrics/weekly-active-users.md` — ordinary OKF markdown; every key has a defined
77
+ RDF meaning:
78
+
79
+ <!-- --8<-- [start:concept-glance] -->
80
+ ```markdown title="metrics/weekly-active-users.md"
81
+ ---
82
+ type: Metric # -> rdf:type lokf:Metric
83
+ id: https://acme.example/knowledge/metrics/weekly-active-users # -> @id (subject)
84
+ title: Weekly Active Users # -> schema:name
85
+ unit: users # -> schema:unitText
86
+ timestamp: 2026-06-30T12:00:00Z # -> schema:dateModified
87
+ derivedFrom: [ .../tables/user-events ] # -> prov:wasDerivedFrom
88
+ dependsOn: [ .../glossary/active-user ] # -> dcterms:requires
89
+ measures: [ .../glossary/active-user ] # -> lokf:measures
90
+ ---
91
+ # Definition
92
+ Distinct users with a qualifying event in a trailing 7-day window.
93
+ ```
94
+ <!-- --8<-- [end:concept-glance] -->
95
+
96
+ Attach `lokf.context.jsonld` and this expands to RDF triples using
97
+ `schema:`, `prov:`, `dcterms:`, and `lokf:` predicates — no separate file.
98
+
99
+ ## Regenerate the artifacts
100
+
101
+ Everything downstream of `lokf.yaml` is generated. One command reproduces every
102
+ artifact, re-assembles the reference bundle, re-validates it, and re-emits the RDF:
103
+
104
+ ```bash
105
+ uv sync
106
+ just build # == uv run lokf-build
107
+ ```
108
+
109
+ Or run the individual generators by hand:
110
+
111
+ <!-- --8<-- [start:gen-commands] -->
112
+ ```bash
113
+ # JSON-LD context (aliased type->@type, id->@id for authoring)
114
+ uv run gen-jsonld-context lokf.yaml > lokf.context.base.jsonld
115
+ uv run gen-json-schema lokf.yaml > lokf.schema.json
116
+ uv run gen-shacl lokf.yaml > lokf.shacl.ttl
117
+ uv run gen-owl lokf.yaml > lokf.owl.ttl
118
+ ```
119
+ <!-- --8<-- [end:gen-commands] -->
120
+
121
+ The published `lokf.context.jsonld` is the generated context with two standard
122
+ JSON-LD keyword aliases applied so unmodified OKF frontmatter is valid Linked Data:
123
+
124
+ ```python
125
+ import json
126
+ c = json.load(open("lokf.context.base.jsonld"))
127
+ c["@context"]["type"] = "@type" # OKF's required field designates the RDF class
128
+ c["@context"]["id"] = "@id" # the concept IRI is the RDF subject
129
+ json.dump(c, open("lokf.context.jsonld", "w"), indent=2)
130
+ ```
131
+
132
+ ## Validate a bundle
133
+
134
+ <!-- --8<-- [start:validate-bundle] -->
135
+ ```bash
136
+ # `just build` assembles examples/acme-knowledge.bundle.json from the markdown, then:
137
+ uv run linkml-validate -s lokf.yaml -C KnowledgeBundle examples/acme-knowledge.bundle.json
138
+ # -> No issues found
139
+
140
+ # Or validate a single concept against its class
141
+ uv run linkml-validate -s lokf.yaml -C Metric metric.json
142
+ ```
143
+ <!-- --8<-- [end:validate-bundle] -->
144
+
145
+ ## Markdown → RDF in one command
146
+
147
+ The `lokf` CLI projects a concept — or a whole bundle directory — straight to
148
+ RDF. No context wiring, no glue code:
149
+
150
+ <!-- --8<-- [start:quickstart-rdf] -->
151
+ ```bash
152
+ # a single concept -> Turtle on stdout
153
+ uv run lokf convert examples/acme-knowledge/metrics/weekly-active-users.md --format ttl
154
+
155
+ # the same thing behind the just recipe
156
+ just gen-rdf-turtle examples/acme-knowledge/metrics/weekly-active-users.md
157
+ ```
158
+
159
+ `--format` also takes `nt`, `jsonld`, `xml`, `n3`, and `trig`; `--output FILE`
160
+ writes to disk instead of stdout. Point `convert` at the bundle directory
161
+ (`examples/acme-knowledge`) to project all six concepts at once.
162
+
163
+ Prefer to stay in Python? `lokf.rdf.serialize` is the same projection the CLI
164
+ calls:
165
+
166
+ ```python
167
+ from lokf import rdf
168
+
169
+ # a concept file, or the bundle directory — either resolves IRIs correctly
170
+ print(rdf.serialize("examples/acme-knowledge/metrics/weekly-active-users.md", "ttl"))
171
+ ```
172
+ <!-- --8<-- [end:quickstart-rdf] -->
173
+
174
+ This is the whole thesis: OKF authoring in, RDF knowledge graph out.
175
+
176
+ ## Status
177
+
178
+ LOKF v0.1 is a **draft profile** and is **not affiliated with or endorsed by
179
+ Google**. "Open Knowledge Format" / "OKF" refer to the format published by Google
180
+ Cloud (`github.com/GoogleCloudPlatform/knowledge-catalog`); LOKF extends it under
181
+ its open terms.
182
+
183
+ ## License
184
+
185
+ CC-BY-4.0 — see [`LICENSE`](https://github.com/nicholsn/lokf/blob/main/LICENSE).
186
+ It's a spec + vocabulary; if you'd rather put the scripts under a code license,
187
+ swap in MIT or Apache-2.0.
lokf-0.1.0/README.md ADDED
@@ -0,0 +1,155 @@
1
+ # Linked Open Knowledge Format (LOKF) — v0.1
2
+
3
+ A **semantic profile of Google's Open Knowledge Format (OKF)**. LOKF keeps OKF's
4
+ markdown-plus-frontmatter authoring model but binds every concept, field, and
5
+ relationship to **schema.org, W3C DCAT, and W3C PROV-O**, so a bundle of markdown
6
+ files is *also* valid **JSON-LD** that expands losslessly to **RDF**. The format is
7
+ defined once in **LinkML**; the JSON-LD context, JSON Schema, SHACL shapes, and OWL
8
+ ontology are all generated from that single source.
9
+
10
+ > One sentence: *write OKF markdown, get a queryable knowledge graph for free.*
11
+
12
+ **Documentation:** <https://www.nolan-nichols.com/lokf/>
13
+
14
+ ## Why
15
+
16
+ OKF v0.1 is deliberately minimal — the only required field is `type`, links are
17
+ untyped, and there's no shared vocabulary. LOKF adds exactly three things while
18
+ keeping OKF's ergonomics:
19
+
20
+ 1. **Shared meaning** — types and fields map to public ontology terms.
21
+ 2. **Typed relationships** — `dependsOn`, `derivedFrom`, `isPartOf`, … each pinned
22
+ to an RDF predicate, instead of one untyped markdown link.
23
+ 3. **A real graph** — the same bundle is queryable with SPARQL, validatable with
24
+ SHACL, and reason-able with OWL.
25
+
26
+ It stays **bidirectionally compatible**: every LOKF bundle is a valid OKF bundle,
27
+ and every OKF bundle is valid LOKF with default mappings.
28
+
29
+ ## Files
30
+
31
+ | Path | What it is | Hand-edited? |
32
+ |------|------------|:---:|
33
+ | `lokf.yaml` | **The LinkML schema — the single source of truth.** | ✅ edit this |
34
+ | `SPEC.md` | The human-readable specification. | ✅ |
35
+ | `lokf.context.jsonld` | Generated JSON-LD `@context` (+ `type`→`@type`, `id`→`@id` aliases). Attach to concepts to get Linked Data. | ⚙️ generated |
36
+ | `lokf.schema.json` | Generated JSON Schema — validates frontmatter / bundles. | ⚙️ generated |
37
+ | `lokf.shacl.ttl` | Generated SHACL shapes — validates the RDF graph. | ⚙️ generated |
38
+ | `lokf.owl.ttl` | Generated OWL ontology — reasoning & alignment. | ⚙️ generated |
39
+ | `examples/acme-knowledge/` | A conformant 6-concept reference bundle. | ✅ |
40
+ | `examples/*.nt` | RDF triples produced from the example frontmatter. | ⚙️ generated |
41
+
42
+ ## Anatomy of a LOKF concept
43
+
44
+ `metrics/weekly-active-users.md` — ordinary OKF markdown; every key has a defined
45
+ RDF meaning:
46
+
47
+ <!-- --8<-- [start:concept-glance] -->
48
+ ```markdown title="metrics/weekly-active-users.md"
49
+ ---
50
+ type: Metric # -> rdf:type lokf:Metric
51
+ id: https://acme.example/knowledge/metrics/weekly-active-users # -> @id (subject)
52
+ title: Weekly Active Users # -> schema:name
53
+ unit: users # -> schema:unitText
54
+ timestamp: 2026-06-30T12:00:00Z # -> schema:dateModified
55
+ derivedFrom: [ .../tables/user-events ] # -> prov:wasDerivedFrom
56
+ dependsOn: [ .../glossary/active-user ] # -> dcterms:requires
57
+ measures: [ .../glossary/active-user ] # -> lokf:measures
58
+ ---
59
+ # Definition
60
+ Distinct users with a qualifying event in a trailing 7-day window.
61
+ ```
62
+ <!-- --8<-- [end:concept-glance] -->
63
+
64
+ Attach `lokf.context.jsonld` and this expands to RDF triples using
65
+ `schema:`, `prov:`, `dcterms:`, and `lokf:` predicates — no separate file.
66
+
67
+ ## Regenerate the artifacts
68
+
69
+ Everything downstream of `lokf.yaml` is generated. One command reproduces every
70
+ artifact, re-assembles the reference bundle, re-validates it, and re-emits the RDF:
71
+
72
+ ```bash
73
+ uv sync
74
+ just build # == uv run lokf-build
75
+ ```
76
+
77
+ Or run the individual generators by hand:
78
+
79
+ <!-- --8<-- [start:gen-commands] -->
80
+ ```bash
81
+ # JSON-LD context (aliased type->@type, id->@id for authoring)
82
+ uv run gen-jsonld-context lokf.yaml > lokf.context.base.jsonld
83
+ uv run gen-json-schema lokf.yaml > lokf.schema.json
84
+ uv run gen-shacl lokf.yaml > lokf.shacl.ttl
85
+ uv run gen-owl lokf.yaml > lokf.owl.ttl
86
+ ```
87
+ <!-- --8<-- [end:gen-commands] -->
88
+
89
+ The published `lokf.context.jsonld` is the generated context with two standard
90
+ JSON-LD keyword aliases applied so unmodified OKF frontmatter is valid Linked Data:
91
+
92
+ ```python
93
+ import json
94
+ c = json.load(open("lokf.context.base.jsonld"))
95
+ c["@context"]["type"] = "@type" # OKF's required field designates the RDF class
96
+ c["@context"]["id"] = "@id" # the concept IRI is the RDF subject
97
+ json.dump(c, open("lokf.context.jsonld", "w"), indent=2)
98
+ ```
99
+
100
+ ## Validate a bundle
101
+
102
+ <!-- --8<-- [start:validate-bundle] -->
103
+ ```bash
104
+ # `just build` assembles examples/acme-knowledge.bundle.json from the markdown, then:
105
+ uv run linkml-validate -s lokf.yaml -C KnowledgeBundle examples/acme-knowledge.bundle.json
106
+ # -> No issues found
107
+
108
+ # Or validate a single concept against its class
109
+ uv run linkml-validate -s lokf.yaml -C Metric metric.json
110
+ ```
111
+ <!-- --8<-- [end:validate-bundle] -->
112
+
113
+ ## Markdown → RDF in one command
114
+
115
+ The `lokf` CLI projects a concept — or a whole bundle directory — straight to
116
+ RDF. No context wiring, no glue code:
117
+
118
+ <!-- --8<-- [start:quickstart-rdf] -->
119
+ ```bash
120
+ # a single concept -> Turtle on stdout
121
+ uv run lokf convert examples/acme-knowledge/metrics/weekly-active-users.md --format ttl
122
+
123
+ # the same thing behind the just recipe
124
+ just gen-rdf-turtle examples/acme-knowledge/metrics/weekly-active-users.md
125
+ ```
126
+
127
+ `--format` also takes `nt`, `jsonld`, `xml`, `n3`, and `trig`; `--output FILE`
128
+ writes to disk instead of stdout. Point `convert` at the bundle directory
129
+ (`examples/acme-knowledge`) to project all six concepts at once.
130
+
131
+ Prefer to stay in Python? `lokf.rdf.serialize` is the same projection the CLI
132
+ calls:
133
+
134
+ ```python
135
+ from lokf import rdf
136
+
137
+ # a concept file, or the bundle directory — either resolves IRIs correctly
138
+ print(rdf.serialize("examples/acme-knowledge/metrics/weekly-active-users.md", "ttl"))
139
+ ```
140
+ <!-- --8<-- [end:quickstart-rdf] -->
141
+
142
+ This is the whole thesis: OKF authoring in, RDF knowledge graph out.
143
+
144
+ ## Status
145
+
146
+ LOKF v0.1 is a **draft profile** and is **not affiliated with or endorsed by
147
+ Google**. "Open Knowledge Format" / "OKF" refer to the format published by Google
148
+ Cloud (`github.com/GoogleCloudPlatform/knowledge-catalog`); LOKF extends it under
149
+ its open terms.
150
+
151
+ ## License
152
+
153
+ CC-BY-4.0 — see [`LICENSE`](https://github.com/nicholsn/lokf/blob/main/LICENSE).
154
+ It's a spec + vocabulary; if you'd rather put the scripts under a code license,
155
+ swap in MIT or Apache-2.0.