lokf 0.1.0__py3-none-any.whl

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.
lokf/__init__.py ADDED
@@ -0,0 +1,20 @@
1
+ """Linked Open Knowledge Format (LOKF) toolkit.
2
+
3
+ The format itself is defined in ``lokf.yaml`` (LinkML); this package provides
4
+ the tooling around it: loading bundles (:func:`load_bundle`), the schema
5
+ vocabulary (:func:`vocabulary`), and the ``lokf-build`` artifact regenerator.
6
+ """
7
+
8
+ from lokf.model import Bundle, Concept, load_bundle
9
+ from lokf.schema import Relation, Vocabulary, load_context, load_schema, vocabulary
10
+
11
+ __all__ = [
12
+ "Bundle",
13
+ "Concept",
14
+ "Relation",
15
+ "Vocabulary",
16
+ "load_bundle",
17
+ "load_context",
18
+ "load_schema",
19
+ "vocabulary",
20
+ ]
lokf/agentskills.py ADDED
@@ -0,0 +1,58 @@
1
+ """Access and install the Claude Code agent skills bundled with LOKF.
2
+
3
+ The skills live under ``lokf/skills/<name>/SKILL.md``, each a directory with a
4
+ ``SKILL.md`` carrying YAML frontmatter (``name``/``description``) and a markdown
5
+ body of instructions that drive the real ``lokf`` CLI. This module locates them
6
+ (zip-safe, like :mod:`lokf.schema`), lists their frontmatter, and copies the
7
+ tree into a project's ``.claude/skills`` so an agent can use them.
8
+ """
9
+ from __future__ import annotations
10
+
11
+ import pathlib
12
+ import shutil
13
+ from importlib import resources
14
+
15
+ import yaml
16
+
17
+
18
+ def skills_dir() -> pathlib.Path:
19
+ """Return the packaged skills directory (``lokf/skills``)."""
20
+ return pathlib.Path(str(resources.files("lokf") / "skills"))
21
+
22
+
23
+ def _frontmatter(skill_md: pathlib.Path) -> dict:
24
+ """Parse the YAML frontmatter block delimited by ``---`` from a SKILL.md."""
25
+ text = skill_md.read_text(encoding="utf-8")
26
+ parts = text.split("---", 2)
27
+ if len(parts) < 3:
28
+ return {}
29
+ return yaml.safe_load(parts[1]) or {}
30
+
31
+
32
+ def list_skills() -> list[tuple[str, str]]:
33
+ """Return ``(name, description)`` from each skill's SKILL.md frontmatter."""
34
+ skills = []
35
+ for skill in sorted(skills_dir().iterdir()):
36
+ md = skill / "SKILL.md"
37
+ if not md.is_file():
38
+ continue
39
+ meta = _frontmatter(md)
40
+ skills.append((meta.get("name", skill.name), meta.get("description", "")))
41
+ return skills
42
+
43
+
44
+ def install(dest: str | pathlib.Path | None = None) -> pathlib.Path:
45
+ """Copy the skills tree into *dest* (default ``.claude/skills``); return it.
46
+
47
+ Parents are created and same-named skills are overwritten in place.
48
+ """
49
+ dest = pathlib.Path(dest) if dest is not None else pathlib.Path(".claude/skills")
50
+ dest.mkdir(parents=True, exist_ok=True)
51
+ for skill in skills_dir().iterdir():
52
+ if not (skill / "SKILL.md").is_file():
53
+ continue
54
+ target = dest / skill.name
55
+ if target.exists():
56
+ shutil.rmtree(target)
57
+ shutil.copytree(skill, target)
58
+ return dest
lokf/build.py ADDED
@@ -0,0 +1,155 @@
1
+ #!/usr/bin/env python3
2
+ """Reproduce every generated LOKF artifact from the single source of truth
3
+ (``lokf.yaml``), then assemble the reference bundle, validate it against the
4
+ schema, and project it to RDF.
5
+
6
+ Run from anywhere inside the repository:
7
+
8
+ uv sync
9
+ uv run lokf-build # or: just build
10
+
11
+ Outputs (regenerated in place):
12
+ lokf.context.jsonld JSON-LD context (+ type->@type, id->@id aliases)
13
+ lokf.schema.json JSON Schema
14
+ lokf.shacl.ttl SHACL shapes
15
+ lokf.owl.ttl OWL ontology
16
+ examples/acme-knowledge.bundle.json assembled bundle (git-ignored)
17
+ examples/acme-knowledge.nt RDF triples for the whole bundle
18
+ examples/weekly-active-users.nt RDF triples for one concept
19
+ """
20
+ from __future__ import annotations
21
+ import json
22
+ import os
23
+ import pathlib
24
+ import shutil
25
+ import subprocess
26
+ import sys
27
+
28
+ from lokf.model import load_bundle
29
+
30
+
31
+ def _find_root() -> pathlib.Path:
32
+ """Locate the repository root from the current directory or any ancestor.
33
+
34
+ Requiring the reference bundle alongside ``lokf.yaml`` prevents the
35
+ generators from writing into an unrelated directory that merely contains
36
+ a file named ``lokf.yaml``.
37
+ """
38
+ cwd = pathlib.Path.cwd()
39
+ for p in (cwd, *cwd.parents):
40
+ if (p / "lokf.yaml").exists() and (p / "examples" / "acme-knowledge" / "index.md").exists():
41
+ return p
42
+ sys.exit(
43
+ "lokf-build must be run from inside the lokf repository "
44
+ "(no ancestor of the current directory contains both lokf.yaml "
45
+ "and examples/acme-knowledge/)"
46
+ )
47
+
48
+
49
+ def run(cmd, **kw):
50
+ """Echo *cmd*, then run it with ``subprocess.run(..., check=True)``."""
51
+ print(" $", " ".join(str(c) for c in cmd))
52
+ return subprocess.run(cmd, check=True, **kw)
53
+
54
+
55
+ def generate(root: pathlib.Path) -> None:
56
+ """Run the four LinkML generators, then publish the authoring context."""
57
+ schema = root / "lokf.yaml"
58
+ print("== generate artifacts from lokf.yaml ==")
59
+ with open(root / "lokf.schema.json", "w") as f:
60
+ run(["gen-json-schema", str(schema)], stdout=f)
61
+ with open(root / "lokf.owl.ttl", "w") as f:
62
+ run(["gen-owl", str(schema)], stdout=f)
63
+ with open(root / "lokf.shacl.ttl", "w") as f:
64
+ run(["gen-shacl", str(schema)], stdout=f)
65
+
66
+ base = root / "lokf.context.base.jsonld"
67
+ with open(base, "w") as f:
68
+ run(["gen-jsonld-context", str(schema)], stdout=f)
69
+ ctx = json.load(open(base))
70
+ # Two standard JSON-LD keyword aliases make unmodified OKF frontmatter
71
+ # behave as Linked Data: `type` designates the RDF class, `id` the subject.
72
+ ctx["@context"]["type"] = "@type"
73
+ ctx["@context"]["id"] = "@id"
74
+ ctx.setdefault("comments", {})["note"] = (
75
+ "Authoring context: `type`->@type and `id`->@id aliased so OKF "
76
+ "frontmatter is valid JSON-LD."
77
+ )
78
+ json.dump(ctx, open(root / "lokf.context.jsonld", "w"), indent=2)
79
+ try:
80
+ os.remove(base) # gitignored intermediate; some filesystems block unlink
81
+ except OSError:
82
+ pass
83
+
84
+ # Refresh the copies packaged with the lokf toolkit so an installed wheel
85
+ # is self-sufficient (see lokf.schema's resolution order). Only when run
86
+ # inside the lokf repo itself: a downstream knowledge repo that satisfies
87
+ # _find_root must not have a src/lokf/ tree planted in it.
88
+ outputs = " -> lokf.context.jsonld, lokf.schema.json, lokf.shacl.ttl, lokf.owl.ttl"
89
+ if (root / "src" / "lokf" / "__init__.py").exists():
90
+ data = root / "src" / "lokf" / "data"
91
+ data.mkdir(parents=True, exist_ok=True)
92
+ shutil.copy(root / "lokf.yaml", data / "lokf.yaml")
93
+ shutil.copy(root / "lokf.context.jsonld", data / "lokf.context.jsonld")
94
+ outputs += " (+ src/lokf/data copies)"
95
+ print(outputs)
96
+
97
+
98
+ def assemble(root: pathlib.Path) -> dict:
99
+ """Assemble all concept files (+ root index.md metadata) into one bundle."""
100
+ b = load_bundle(root / "examples" / "acme-knowledge")
101
+ bundle = dict(b.meta)
102
+ concepts = b.docs() # frontmatter + injected id (no-op where id is explicit)
103
+ bundle["concepts"] = concepts
104
+ json.dump(bundle, open(root / "examples" / "acme-knowledge.bundle.json", "w"), indent=2)
105
+ print(f"== assembled bundle: {len(concepts)} concepts "
106
+ f"({', '.join(c['type'] for c in concepts)}) ==")
107
+ return bundle
108
+
109
+
110
+ def validate(root: pathlib.Path) -> None:
111
+ """Validate the assembled bundle against the schema's ``KnowledgeBundle`` root."""
112
+ print("== validate against JSON Schema ==")
113
+ run(["linkml-validate", "-s", str(root / "lokf.yaml"), "-C", "KnowledgeBundle",
114
+ str(root / "examples" / "acme-knowledge.bundle.json")])
115
+
116
+
117
+ def to_rdf(root: pathlib.Path, bundle: dict) -> None:
118
+ """Project the bundle (and its Metric concept) to N-Triples in ``examples/``."""
119
+ from rdflib import Graph
120
+ ex = root / "examples"
121
+ ctx = json.load(open(root / "lokf.context.jsonld"))["@context"]
122
+
123
+ # Same single-parse projection as lokf.model.Bundle.graph(): the
124
+ # assembled concepts already carry injected ids, so one @graph document
125
+ # (context compiled once) covers the whole bundle.
126
+ whole = Graph()
127
+ whole.parse(
128
+ data=json.dumps({"@context": ctx, "@graph": bundle["concepts"]}),
129
+ format="json-ld",
130
+ )
131
+ whole.serialize(destination=str(ex / "acme-knowledge.nt"), format="nt")
132
+
133
+ metric = next(c for c in bundle["concepts"] if c["type"] == "Metric")
134
+ mdoc = {k: v for k, v in metric.items() if k != "body"}
135
+ mdoc["@context"] = ctx
136
+ mg = Graph()
137
+ mg.parse(data=json.dumps(mdoc), format="json-ld")
138
+ mg.serialize(destination=str(ex / "weekly-active-users.nt"), format="nt")
139
+ print(f"== RDF projection: {len(whole)} triples (bundle), "
140
+ f"{len(mg)} triples (metric) ==")
141
+
142
+
143
+ def main() -> int:
144
+ """Entry point for the ``lokf-build`` console script."""
145
+ root = _find_root()
146
+ generate(root)
147
+ bundle = assemble(root)
148
+ validate(root)
149
+ to_rdf(root, bundle)
150
+ print("\nOK - all artifacts reproduced and validated.")
151
+ return 0
152
+
153
+
154
+ if __name__ == "__main__":
155
+ sys.exit(main())
lokf/cli.py ADDED
@@ -0,0 +1,276 @@
1
+ """The ``lokf`` command-line interface (Typer).
2
+
3
+ lokf convert path/to/concept.md --format ttl # markdown -> RDF
4
+ lokf query examples/acme-knowledge "SELECT ..." # SPARQL over a bundle
5
+ lokf serve examples/acme-knowledge # local SPARQL endpoint + viz
6
+ lokf propose examples/acme-knowledge --apply # typed relations from links
7
+ lokf vocab # the relation vocabulary
8
+ lokf skills # bundled agent skills
9
+ lokf mcp # run the MCP server
10
+ """
11
+ from __future__ import annotations
12
+
13
+ import json
14
+ import sys
15
+ from pathlib import Path
16
+ from typing import Optional
17
+
18
+ import typer
19
+
20
+ app = typer.Typer(
21
+ name="lokf",
22
+ help="LOKF toolkit — author, convert, query, serve, and automate "
23
+ "linked-open knowledge bundles.",
24
+ no_args_is_help=True,
25
+ add_completion=False,
26
+ )
27
+
28
+
29
+ def _err(message: str) -> None:
30
+ typer.echo(message, err=True)
31
+
32
+
33
+ # ---------------------------------------------------------------------------
34
+ # convert
35
+ # ---------------------------------------------------------------------------
36
+ @app.command()
37
+ def convert(
38
+ source: Path = typer.Argument(
39
+ ..., exists=True, help="A concept .md file or a bundle directory."
40
+ ),
41
+ format: str = typer.Option(
42
+ "ttl", "--format", "-f", help="ttl | nt | jsonld | xml | n3 | trig."
43
+ ),
44
+ output: Optional[Path] = typer.Option(
45
+ None, "--output", "-o", help="Write to this file instead of stdout."
46
+ ),
47
+ ) -> None:
48
+ """Convert markdown (a concept or whole bundle) to RDF."""
49
+ from lokf import rdf
50
+
51
+ try:
52
+ data = rdf.serialize(source, format)
53
+ except ValueError as exc:
54
+ _err(str(exc))
55
+ raise typer.Exit(2)
56
+ except OSError as exc:
57
+ _err(f"could not read {source}: {exc}")
58
+ raise typer.Exit(1)
59
+ if output is not None:
60
+ output.write_text(data, encoding="utf-8")
61
+ typer.echo(f"wrote {output}")
62
+ else:
63
+ typer.echo(data, nl=False)
64
+
65
+
66
+ # ---------------------------------------------------------------------------
67
+ # query
68
+ # ---------------------------------------------------------------------------
69
+ @app.command()
70
+ def query(
71
+ source: Path = typer.Argument(
72
+ ..., exists=True, help="A bundle directory or concept file to load."
73
+ ),
74
+ sparql: str = typer.Argument(..., help="A SPARQL query (schema prefixes preset)."),
75
+ format: str = typer.Option(
76
+ "table", "--format", "-f", help="table | json | csv | tsv | ttl (CONSTRUCT)."
77
+ ),
78
+ ) -> None:
79
+ """Run SPARQL over a knowledge base loaded into an in-memory store."""
80
+ from lokf.store import GraphStore, query_form
81
+
82
+ store = GraphStore.from_bundle(source)
83
+ form = query_form(sparql)
84
+ try:
85
+ if form in ("construct", "describe"):
86
+ fmt = "ttl" if format == "table" else format
87
+ typer.echo(store.construct(sparql, fmt=fmt), nl=False)
88
+ elif format == "table":
89
+ _print_rows(store.select(sparql))
90
+ else:
91
+ typer.echo(store.serialize_results(sparql, format).decode("utf-8"), nl=False)
92
+ except Exception as exc: # noqa: BLE001 — surface SPARQL errors to the user
93
+ _err(f"query failed: {exc}")
94
+ raise typer.Exit(1)
95
+
96
+
97
+ def _print_rows(rows: list[dict]) -> None:
98
+ if not rows:
99
+ typer.echo("(no results)")
100
+ return
101
+ cols = list(dict.fromkeys(k for row in rows for k in row))
102
+ widths = {c: max(len(c), *(len(str(r.get(c, ""))) for r in rows)) for c in cols}
103
+ typer.echo(" ".join(c.ljust(widths[c]) for c in cols))
104
+ for row in rows:
105
+ typer.echo(" ".join(str(row.get(c, "")).ljust(widths[c]) for c in cols))
106
+
107
+
108
+ # ---------------------------------------------------------------------------
109
+ # serve
110
+ # ---------------------------------------------------------------------------
111
+ @app.command()
112
+ def serve(
113
+ source: Path = typer.Argument(
114
+ ..., exists=True, help="A bundle directory or concept file to publish."
115
+ ),
116
+ host: str = typer.Option("127.0.0.1", help="Bind host."),
117
+ port: int = typer.Option(8000, help="Bind port."),
118
+ ) -> None:
119
+ """Publish a knowledge base locally: SPARQL endpoint + live graph viz."""
120
+ from lokf.server import serve as run_server
121
+
122
+ run_server(source, host=host, port=port)
123
+
124
+
125
+ # ---------------------------------------------------------------------------
126
+ # propose
127
+ # ---------------------------------------------------------------------------
128
+ @app.command()
129
+ def propose(
130
+ bundle_dir: Path = typer.Argument(
131
+ ..., exists=True, file_okay=False, help="A LOKF bundle directory."
132
+ ),
133
+ apply_: bool = typer.Option(
134
+ False, "--apply", help="Write accepted proposals into frontmatter."
135
+ ),
136
+ min_confidence: float = typer.Option(
137
+ 0.0, "--min-confidence", metavar="F", help="Drop proposals below this."
138
+ ),
139
+ json_: bool = typer.Option(
140
+ False, "--json", help="Emit JSON instead of a table (composes with --apply)."
141
+ ),
142
+ ) -> None:
143
+ """Propose typed relations from markdown links in concept bodies."""
144
+ from lokf.model import load_bundle
145
+ from lokf.propose import apply, proposal_row
146
+ from lokf.propose import propose as propose_relations
147
+ from lokf.schema import vocabulary
148
+
149
+ bundle = load_bundle(bundle_dir)
150
+ if not bundle.concepts:
151
+ _err(f"no concepts found in {bundle_dir}")
152
+ raise typer.Exit(1)
153
+ proposals = [
154
+ p
155
+ for p in propose_relations(bundle, vocabulary())
156
+ if p.confidence >= min_confidence
157
+ ]
158
+ applied: list = []
159
+ if apply_:
160
+ applied = apply(proposals, min_confidence=min_confidence)
161
+ applied_ids = {id(p) for p in applied}
162
+
163
+ if json_:
164
+ ids = applied_ids if apply_ else None
165
+ rows = [proposal_row(p, ids) for p in proposals]
166
+ typer.echo(json.dumps(rows, indent=2))
167
+ return
168
+
169
+ if not proposals:
170
+ typer.echo("no proposals.")
171
+ return
172
+ _print_proposals(proposals)
173
+ if apply_:
174
+ typer.echo("")
175
+ for p in applied:
176
+ typer.echo(f"wrote {p.relation.name} -> {p.target_iri} in {p.source.path}")
177
+ typer.echo(f"applied {len(applied)} of {len(proposals)} proposal(s).")
178
+
179
+
180
+ def _print_proposals(proposals) -> None:
181
+ header = ("SOURCE", "LINK", "PREDICATE", "CONF", "RATIONALE")
182
+ rows = [
183
+ (
184
+ p.source.concept_id,
185
+ p.link.text,
186
+ p.relation.curie,
187
+ f"{p.confidence:.2f}",
188
+ p.rationale,
189
+ )
190
+ for p in proposals
191
+ ]
192
+ widths = [max(len(r[i]) for r in (header, *rows)) for i in range(4)]
193
+ for row in (header, *rows):
194
+ cells = [row[i].ljust(widths[i]) for i in range(4)]
195
+ typer.echo(" ".join([*cells, row[4]]))
196
+
197
+
198
+ # ---------------------------------------------------------------------------
199
+ # vocab
200
+ # ---------------------------------------------------------------------------
201
+ @app.command()
202
+ def vocab(
203
+ json_: bool = typer.Option(False, "--json", help="Emit JSON instead of a table."),
204
+ ) -> None:
205
+ """Show the typed-relation vocabulary derived from the schema."""
206
+ from lokf.schema import vocabulary
207
+
208
+ v = vocabulary()
209
+ relations = sorted(v.relation_types.values(), key=lambda r: r.name)
210
+ if json_:
211
+ typer.echo(json.dumps([r.as_row() for r in relations], indent=2))
212
+ return
213
+ name_w = max(len(r.name) for r in relations)
214
+ curie_w = max(len(r.curie) for r in relations)
215
+ for r in relations:
216
+ key = "slot" if r.is_slot else "rel "
217
+ typer.echo(
218
+ f"{r.name.ljust(name_w)} {key} {r.curie.ljust(curie_w)} {r.description}"
219
+ )
220
+
221
+
222
+ # ---------------------------------------------------------------------------
223
+ # skills
224
+ # ---------------------------------------------------------------------------
225
+ @app.command()
226
+ def skills(
227
+ action: str = typer.Argument("list", help="list | path | install"),
228
+ dest: Optional[Path] = typer.Option(
229
+ None, "--dest", help="Target for `install` (default: .claude/skills)."
230
+ ),
231
+ ) -> None:
232
+ """List, locate, or install the bundled agent skills."""
233
+ from lokf import agentskills
234
+
235
+ if action == "path":
236
+ typer.echo(str(agentskills.skills_dir()))
237
+ elif action == "list":
238
+ for name, summary in agentskills.list_skills():
239
+ typer.echo(f"{name}\t{summary}")
240
+ elif action == "install":
241
+ target = agentskills.install(dest)
242
+ count = len(list(target.glob("*/SKILL.md")))
243
+ typer.echo(f"installed {count} skills into {target}")
244
+ else:
245
+ _err(f"unknown action {action!r}; choose list | path | install")
246
+ raise typer.Exit(2)
247
+
248
+
249
+ # ---------------------------------------------------------------------------
250
+ # mcp
251
+ # ---------------------------------------------------------------------------
252
+ @app.command()
253
+ def mcp() -> None:
254
+ """Run the LOKF MCP server (stdio) so agents can drive the toolkit."""
255
+ from lokf.mcp_server import main as run_mcp
256
+
257
+ run_mcp()
258
+
259
+
260
+ def main(argv: list[str] | None = None) -> int:
261
+ """Programmatic entry point (tests use ``typer.testing.CliRunner``).
262
+
263
+ Runs the app in standalone mode so Typer converts ``typer.Exit`` and
264
+ argument errors into ``SystemExit`` (with a printed message); the code is
265
+ returned here so ``python -m lokf.cli`` and ``sys.exit(main())`` report
266
+ failures correctly instead of always exiting 0.
267
+ """
268
+ try:
269
+ app(args=argv, standalone_mode=True)
270
+ return 0
271
+ except SystemExit as exc:
272
+ return int(exc.code or 0)
273
+
274
+
275
+ if __name__ == "__main__":
276
+ sys.exit(main())