Plan, apply and roll back changes to a production ontology, with a blast radius report and a proof an auditor can re-check.
Rust ai-nativedescription-logicsformal-verificationinfrastructure-as-codeisabelle-languageknowledge-graphleanlean4mcpmcp-serverontologyowlowl2reasoningrustshaclsparqltheorem-proving
#!/usr/bin/env python3
"""
Extract a knowledge graph from the demonstration documents.
Deliberately mirrors the MCP-native convention: this script does NOT reason.
It sends each document to whatever OpenAI-compatible model endpoint is
configured, asks for Turtle constrained to the loaded vocabulary, and then
hands the result to the engine's `onto_vocab_check` for a closed-world
check of every term used.
Terms the model invents are caught there, before anything reaches the store.
That gate is the point: an LLM writes the graph, a deterministic checker
decides whether it is allowed to exist.
Usage:
python3 demo/extract.py # extract + vocab check
python3 demo/extract.py --dry-run # show prompts only
"""
import argparse
import json
import os
import pathlib
import re
import sys
import urllib.request
ROOT = pathlib.Path(__file__).resolve().parent.parent
DOCS = ROOT / "demo" / "documents"
OUT = ROOT / "demo" / "extracted"
ENGINE = os.environ.get("ONTO_ENGINE", "http://127.0.0.1:8137")
LLM_BASE = os.environ.get("ONTO_LLM_BASE_URL", "http://localhost:8081/v1").rstrip("/")
LLM_KEY = os.environ.get("ONTO_LLM_API_KEY", "not-needed")
VOCAB_HINT = """
Classes you may use:
:Document :Specification :ImplementationGuide :ConformanceReport
:Section :Claim :Requirement :ReferenceSource
:Candidate :Dataset :Distribution :Catalog :Publisher :Licence :Theme
:ContactPoint :ConformanceProfile :Frequency :ConformanceGap :ReleaseStage
Object properties you may use:
:hasSection :parentSection :relatedSection :statedIn :aboutEntity
:supersedes :declaresRequirement :requirementOver :blocksReleaseOf :documentsGapIn
Datatype properties you may use:
:docId :classification :aclGroup :sectionNumber :claimText :isMandatory :isBlocking
rdfs:label rdfs:comment
"""
PROMPT = """You are extracting a knowledge graph from a controlled document.
Return ONLY Turtle. No prose, no markdown fences, no explanation.
Use EXACTLY these prefixes:
@prefix : <https://w3id.org/dcat-us-demo#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
STRICT RULE: use ONLY the classes and properties listed below. Do not invent
any term. If something in the document does not fit the vocabulary, omit it.
{vocab}
Extract:
1. One :Document node, IRI :DOC_{docid_safe}, with :docId, rdfs:label,
:classification, :aclGroup, and the most specific document type.
2. A :Section node per numbered section, IRI :SEC_{docid_safe}_<number with dots as underscores>,
with :sectionNumber and rdfs:label, linked by :hasSection from the document.
3. :Claim nodes for assertions that matter to candidate adoption or dataset
classification. Each with :claimText and :statedIn pointing at its section.
4. Where a section states a conformance requirement, a :Requirement node with
:isMandatory and :isBlocking, linked with :declaresRequirement.
5. Where a section records a defect or limitation of a data source, link the
section with :documentsGapIn.
DOCUMENT ID: {docid}
DOCUMENT:
{body}
"""
def rpc(method, params, sid=None, _i=[0]):
_i[0] += 1
headers = {
"Content-Type": "application/json",
"Accept": "application/json, text/event-stream",
}
if sid:
headers["Mcp-Session-Id"] = sid
req = urllib.request.Request(
ENGINE + "/mcp",
data=json.dumps(
{"jsonrpc": "2.0", "id": _i[0], "method": method, "params": params}
).encode(),
headers=headers,
)
r = urllib.request.urlopen(req, timeout=180)
sid2 = r.headers.get("Mcp-Session-Id") or sid
body = r.read().decode().strip()
if body.startswith("{"):
return json.loads(body), sid2
for line in body.split("\n"):
if line.startswith("data:"):
try:
fr = json.loads(line[5:].strip())
if "result" in fr or "error" in fr:
return fr, sid2
except Exception:
pass
return None, sid2
def tool_text(res):
if not res:
return ""
return res.get("result", {}).get("content", [{}])[0].get("text", "")
def new_session():
_, sid = rpc(
"initialize",
{
"protocolVersion": "2025-03-26",
"capabilities": {},
"clientInfo": {"name": "extractor", "version": "1"},
},
)
return sid
# Set once the vocabulary has been loaded, so a session reset can restore it.
_VOCAB_PATH = None
def call_tool(name, arguments, sid):
"""Call an MCP tool, re-initialising if the session has expired.
Extraction turns can take minutes on a local model, which is long enough
for the server to drop the session. A stale session surfaces as a bare
HTTP 404, so treat that as "reconnect and retry once" rather than fatal.
A new session starts with an EMPTY store, so the vocabulary must be
reloaded before retrying. Without this, onto_vocab_check silently reports
"0 declared terms" and checks nothing -- it returns conforms=false with a
warning rather than an error, which is easy to mistake for a failed
extraction when it is actually a failed setup.
"""
try:
res, sid = rpc("tools/call", {"name": name, "arguments": arguments}, sid)
return res, sid
except urllib.error.HTTPError as e:
if e.code != 404:
raise
sid = new_session()
if _VOCAB_PATH:
rpc("tools/call", {"name": "onto_load", "arguments": {
"path": _VOCAB_PATH, "name": "dcat-us-vocab", "force_recompile": True}}, sid)
res, sid = rpc("tools/call", {"name": name, "arguments": arguments}, sid)
return res, sid
def call_model(prompt):
# Discover the served model id: MLX servers reject a mismatched id outright.
model = os.environ.get("ONTO_LLM_MODEL", "")
if not model:
req = urllib.request.Request(
LLM_BASE + "/models", headers={"Authorization": f"Bearer {LLM_KEY}"}
)
model = json.load(urllib.request.urlopen(req, timeout=30))["data"][0]["id"]
req = urllib.request.Request(
LLM_BASE + "/chat/completions",
data=json.dumps(
{
"model": model,
"messages": [{"role": "user", "content": prompt}],
"temperature": 0.2,
"top_p": 0.8,
"max_tokens": 4096,
"chat_template_kwargs": {"enable_thinking": False},
}
).encode(),
headers={
"Content-Type": "application/json",
"Authorization": f"Bearer {LLM_KEY}",
},
)
resp = json.load(urllib.request.urlopen(req, timeout=600))
return resp["choices"][0]["message"]["content"], model
PREFIXES = (
"@prefix : <https://w3id.org/dcat-us-demo#> .\n"
"@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .\n"
"@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .\n"
)
def normalise(text):
"""Recover parseable Turtle from a chatty model response.
Small local models reliably do three things the prompt told them not to:
wrap output in code fences, open with a prose sentence, and omit the
prefix block. None of that changes the extracted CONTENT, so it is
normalised here rather than treated as a failure. Anything that survives
still has to pass onto_vocab_check.
"""
text = re.sub(r"```(?:turtle|ttl)?", "", text).strip()
# Drop any prose preamble. Start at the first @prefix if there is one;
# otherwise at the first line that is unambiguously a SUBJECT, i.e.
# "<iri> a <type>". Matching a bare leading ":token" is wrong: predicate
# continuation lines like ':docId "DOC-114" ;' match it too, and starting
# there silently decapitates the statement and loses its subject.
lines = text.split("\n")
start = None
for i, line in enumerate(lines):
if line.strip().startswith(("@prefix", "@base")):
start = i
break
if start is None:
for i, line in enumerate(lines):
if re.match(r"^\s*:\S+\s+(a|rdf:type)\s", line):
start = i
break
text = "\n".join(lines[start if start is not None else 0 :]).strip()
# Drop any trailing prose after the last statement-terminating line.
lines = text.split("\n")
end = len(lines)
for i in range(len(lines) - 1, -1, -1):
if lines[i].rstrip().endswith((".", ";", ",")):
end = i + 1
break
text = "\n".join(lines[:end]).strip()
if "@prefix :" not in text:
text = PREFIXES + "\n" + text
return text
strip_fences = normalise # keep the call site stable
def main():
ap = argparse.ArgumentParser()
ap.add_argument("--dry-run", action="store_true")
args = ap.parse_args()
OUT.mkdir(parents=True, exist_ok=True)
docs = sorted(DOCS.glob("*.md"))
if not docs:
sys.exit("no documents found")
# Load the vocabulary the extraction will be checked against.
sid = None
if not args.dry_run:
_, sid = rpc(
"initialize",
{
"protocolVersion": "2025-03-26",
"capabilities": {},
"clientInfo": {"name": "extractor", "version": "1"},
},
)
global _VOCAB_PATH
bundle = ROOT / "demo" / "bundle" / "dcat-us-vocab.ttl"
_VOCAB_PATH = str(bundle)
res, sid = call_tool(
"onto_load",
{"path": str(bundle), "name": "dcat-us-vocab", "force_recompile": True},
sid,
)
print(f"vocabulary loaded: {tool_text(res)[:100]}")
for doc in docs:
raw = doc.read_text()
m = re.match(r"^---\n(.*?)\n---\n(.*)$", raw, re.S)
front, body = (m.group(1), m.group(2)) if m else ("", raw)
docid = re.search(r'doc_id:\s*"?([^"\n]+)"?', front)
docid = docid.group(1).strip() if docid else doc.stem
safe = docid.replace("-", "_")
prompt = PROMPT.format(
vocab=VOCAB_HINT, docid=docid, docid_safe=safe, body=front + "\n" + body
)
if args.dry_run:
print(f"--- {docid} prompt {len(prompt)} chars ---")
continue
print(f"\nextracting {docid} ...", flush=True)
# Small models occasionally collapse into repetition. Detect it and
# retry rather than writing degenerate output and calling it a graph.
for attempt in range(1, 4):
content, model = call_model(prompt)
(OUT / f"{docid}.raw.attempt{attempt}.txt").write_text(content)
if re.search(r"(\b\S{1,6}\b[ .]{1,3})\1{15,}", content):
print(f" attempt {attempt}: degenerate repetition, retrying")
continue
ttl = strip_fences(content)
if ":" in ttl and len(ttl) > 200:
break
print(f" attempt {attempt}: output too thin, retrying")
else:
print(f" GAVE UP on {docid} after 3 attempts")
ttl = strip_fences(content)
path = OUT / f"{docid}.ttl"
path.write_text(
f"# Extracted from {doc.name} on 2026-08-10\n"
f"# Model: {model}\n"
f"# Verified with onto_vocab_check. See demo/extracted/REPORT.md\n\n" + ttl
)
print(f" wrote {path.name} ({len(ttl)} chars)")
res, sid = call_tool("onto_validate", {"input": ttl, "inline": True}, sid)
v = tool_text(res)
print(f" syntax : {v[:120]}")
res, sid = call_tool("onto_vocab_check", {"data": ttl, "inline": True}, sid)
print(f" vocab : {tool_text(res)[:400]}")
if __name__ == "__main__":
main()