scriptoria 0.8.1__tar.gz → 0.9.0__tar.gz

{scriptoria-0.8.1 → scriptoria-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scriptoria
-Version: 0.8.1
+Version: 0.9.0
 Summary: Deterministic scriptorium-keeper (the `scrip` CLI): staleness, provenance integrity, and fact queries for an agent-compiled knowledge base
 Project-URL: Homepage, https://github.com/coredipper/scriptorium
 Project-URL: Changelog, https://github.com/coredipper/scriptorium/blob/main/CHANGELOG.md
@@ -54,6 +54,7 @@ uv run --project scrip scrip --help
 | `scrip status` | Report `STALE` / `OK` / `UNCOMPILED` artifacts from the dependency graph. `--no-cache` recomputes from files; `--rebuild-manifest` regenerates the cache. |
 | `scrip verify` | Check every provenance anchor still resolves to text in its source; check referenced sources exist and `claim_id`s are unique. Fails on `BROKEN` and `AMBIGUOUS` by default; `--allow-ambiguous` downgrades `AMBIGUOUS` to a warning. |
 | `scrip query [claims\|entities\|edges\|contradictions\|reconciliations]` | Structured query over `vault/facts/*.ndjson` via DuckDB. `--sql "<duckdb>"`, `--where`, `--limit`. |
+| `scrip ontology` | Validate and summarize optional `vault/ontology.yaml` vocabulary for fact predicates, entity kinds, and edge kinds. |
 | `scrip ingest <url\|file>` | Fetch/read a source and write canonical `vault/raw/<slug>.md` plus sidecar metadata. HTML/PDF need the optional `[ingest]` extra. |
 | `scrip new concept\|entity <slug> --from raw/...` | Scaffold a derived wiki page for the agent to fill. |
 | `scrip anchor "<quote>" --source raw/<slug>` | Mint a content-anchored footnote for a verbatim source quote. |

{scriptoria-0.8.1 → scriptoria-0.9.0}/README.md

@@ -23,6 +23,7 @@ uv run --project scrip scrip --help
 | `scrip status` | Report `STALE` / `OK` / `UNCOMPILED` artifacts from the dependency graph. `--no-cache` recomputes from files; `--rebuild-manifest` regenerates the cache. |
 | `scrip verify` | Check every provenance anchor still resolves to text in its source; check referenced sources exist and `claim_id`s are unique. Fails on `BROKEN` and `AMBIGUOUS` by default; `--allow-ambiguous` downgrades `AMBIGUOUS` to a warning. |
 | `scrip query [claims\|entities\|edges\|contradictions\|reconciliations]` | Structured query over `vault/facts/*.ndjson` via DuckDB. `--sql "<duckdb>"`, `--where`, `--limit`. |
+| `scrip ontology` | Validate and summarize optional `vault/ontology.yaml` vocabulary for fact predicates, entity kinds, and edge kinds. |
 | `scrip ingest <url\|file>` | Fetch/read a source and write canonical `vault/raw/<slug>.md` plus sidecar metadata. HTML/PDF need the optional `[ingest]` extra. |
 | `scrip new concept\|entity <slug> --from raw/...` | Scaffold a derived wiki page for the agent to fill. |
 | `scrip anchor "<quote>" --source raw/<slug>` | Mint a content-anchored footnote for a verbatim source quote. |

{scriptoria-0.8.1 → scriptoria-0.9.0}/pyproject.toml

@@ -2,7 +2,7 @@
 # Distribution name on PyPI is `scriptoria` (scrip/scriptorium were taken); the
 # CLI command and the import package both remain `scrip`.
 name = "scriptoria"
-version = "0.8.1"
+version = "0.9.0"
 description = "Deterministic scriptorium-keeper (the `scrip` CLI): staleness, provenance integrity, and fact queries for an agent-compiled knowledge base"
 readme = "README.md"
 requires-python = ">=3.10"

{scriptoria-0.8.1 → scriptoria-0.9.0}/src/scrip/__init__.py

@@ -13,7 +13,7 @@ from __future__ import annotations
 
 from pathlib import Path
 
-__version__ = "0.8.1"
+__version__ = "0.9.0"
 
 # --- canonical vault layout ------------------------------------------------
 # ``root`` is the repo/instance root: the directory containing ``vault/``.

{scriptoria-0.8.1 → scriptoria-0.9.0}/src/scrip/cli.py

@@ -493,6 +493,25 @@ def cmd_fact_add(args: argparse.Namespace) -> int:
     return 1 if result["failures"] else 0
 
 
+def cmd_ontology(args: argparse.Namespace) -> int:
+    from . import ontology
+
+    root = resolve_root(args.root)
+    ont = ontology.load(root)
+    result = {"path": str(ontology.ontology_path(root).relative_to(root)), **ont.summary()}
+    if args.json:
+        _emit(result)
+    else:
+        state = "active" if ont.active else "not present or empty"
+        print(f"ontology: {state}")
+        if ont.active:
+            print(f"  entity kinds: {', '.join(result['entity_kinds']) or '(none)'}")
+            print(f"  edge kinds: {', '.join(result['edge_kinds']) or '(none)'}")
+            print(f"  claim predicates: {', '.join(result['claim_predicates']) or '(none)'}")
+            print(f"  predicate aliases: {len(result['predicate_aliases'])}")
+    return 0
+
+
 def cmd_ingest(args: argparse.Namespace) -> int:
     from . import ingest, lock
 
@@ -764,6 +783,13 @@ def build_parser() -> argparse.ArgumentParser:
     )
     pfa.set_defaults(func=cmd_fact_add)
 
+    po = sub.add_parser(
+        "ontology",
+        parents=[common],
+        help="validate and summarize optional vault/ontology.yaml vocabulary",
+    )
+    po.set_defaults(func=cmd_ontology)
+
     pin = sub.add_parser(
         "ingest",
         parents=[common],

{scriptoria-0.8.1 → scriptoria-0.9.0}/src/scrip/facts.py

@@ -34,6 +34,8 @@ except ImportError:
 
 from . import anchors, facts_dir, lock
 from .errors import DataError, UsageError
+from .ontology import Ontology
+from .ontology import load as load_ontology
 
 _POLARITIES = ("asserts", "denies", "qualifies")
 
@@ -52,7 +54,7 @@ _RECON_OWNED = ("reconciliation_id", "at")
 _CLAIM_REQUIRED = ("quote", "source_id", "subject", "predicate", "object", "polarity", "confidence")
 _CLAIM_ALLOWED = frozenset((*_CLAIM_REQUIRED, "claim_text", "tags"))
 _ENTITY_REQUIRED = ("entity_id", "name", "kind")
-_ENTITY_ALLOWED = frozenset((*_ENTITY_REQUIRED, "tags"))
+_ENTITY_ALLOWED = frozenset((*_ENTITY_REQUIRED, "tags", "uri", "same_as", "external_ids"))
 _EDGE_REQUIRED = ("src", "dst", "kind")
 # An edge may optionally be *cited*: a verbatim ``quote`` + ``source_id`` whose
 # ``anchor`` scrip mints+verifies exactly as for a claim. Bare edges stay
@@ -127,6 +129,26 @@ def _check_tags(rec: dict, index: int) -> None:
         raise DataError(f"record {index}: 'tags' must be a list of strings")
 
 
+def _check_string_list(rec: dict, key: str, index: int) -> None:
+    values = rec.get(key)
+    if values is None:
+        return
+    if not isinstance(values, list) or any(not isinstance(v, str) or not v.strip() for v in values):
+        raise DataError(f"record {index}: '{key}' must be a list of non-empty strings")
+
+
+def _check_string_map(rec: dict, key: str, index: int) -> None:
+    values = rec.get(key)
+    if values is None:
+        return
+    if (
+        not isinstance(values, dict)
+        or any(not isinstance(k, str) or not k.strip() for k in values)
+        or any(not isinstance(v, str) or not v.strip() for v in values.values())
+    ):
+        raise DataError(f"record {index}: '{key}' must be a mapping of strings to strings")
+
+
 def _check_shape(
     rec: dict,
     index: int,
@@ -148,13 +170,14 @@ def _check_shape(
         raise DataError(f"record {index}: missing required field(s): {', '.join(missing)}")
 
 
-def _validate(table: str, rec: dict, index: int) -> None:
+def _validate(table: str, rec: dict, index: int, ont: Ontology) -> None:
     if table == "claims":
         _check_shape(rec, index, _CLAIM_REQUIRED, _CLAIM_ALLOWED)
         # the quote's *emptiness* is a per-record finding, not a schema error
         _check_str(rec, "quote", index, allow_blank=True)
         for key in ("source_id", "subject", "predicate", "object"):
             _check_str(rec, key, index)
+        rec["predicate"] = ont.canonical_claim_predicate(rec["predicate"], index)
         if "claim_text" in rec:
             _check_str(rec, "claim_text", index, allow_blank=True)
         if rec["polarity"] not in _POLARITIES:
@@ -169,14 +192,20 @@ def _validate(table: str, rec: dict, index: int) -> None:
         _check_shape(rec, index, _ENTITY_REQUIRED, _ENTITY_ALLOWED)
         for key in _ENTITY_REQUIRED:
             _check_str(rec, key, index)
+        ont.validate_entity_kind(rec["kind"], index)
         eid = rec["entity_id"]
         if not (eid.startswith("entity/") and _SLUG_RE.fullmatch(eid[len("entity/") :])):
             raise DataError(f"record {index}: entity_id must look like entity/<slug>")
+        if "uri" in rec:
+            _check_str(rec, "uri", index)
+        _check_string_list(rec, "same_as", index)
+        _check_string_map(rec, "external_ids", index)
         _check_tags(rec, index)
     elif table == "edges":
         _check_shape(rec, index, _EDGE_REQUIRED, _EDGE_ALLOWED)
         for key in _EDGE_REQUIRED:
             _check_str(rec, key, index)
+        ont.validate_edge_kind(rec["kind"], index)
         if "quote" in rec or "source_id" in rec:
             # both or neither: a quote needs a source to anchor against
             missing = [k for k in ("quote", "source_id") if k not in rec]
@@ -410,8 +439,9 @@ def add(root: Path, table: str, proposals: list[dict]) -> dict:
     """
     if table not in _FILES:
         raise UsageError(f"unknown facts table: {table}")
+    ont = load_ontology(root)
     for i, rec in enumerate(proposals):
-        _validate(table, rec, i)
+        _validate(table, rec, i, ont)
 
     failures: list[dict] = []
     resolved: list[dict | None] = [None] * len(proposals)
@@ -470,12 +500,16 @@ def add(root: Path, table: str, proposals: list[dict]) -> dict:
                 appended.append(full)
         elif table == "entities":
             def canon(rec: dict) -> dict:
-                return {
+                out = {
                     "entity_id": rec["entity_id"],
                     "name": rec["name"],
                     "kind": rec["kind"],
                     "tags": rec.get("tags") or [],
                 }
+                for key in ("uri", "same_as", "external_ids"):
+                    if key in rec:
+                        out[key] = rec[key]
+                return out
 
             byid = {rec.get("entity_id"): canon(rec) for rec in existing if "entity_id" in rec
                     and isinstance(rec.get("name"), str) and isinstance(rec.get("kind"), str)}

scriptoria-0.9.0/src/scrip/ontology.py

@@ -0,0 +1,162 @@
+"""Optional semantic vocabulary for the facts layer.
+
+The ontology is deliberately small and file-native. If ``vault/ontology.yaml`` is
+absent, facts behave exactly as before. If present, it constrains selected free
+text fields and can canonicalize claim predicates via aliases.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from .errors import DataError
+
+try:
+    from yaml import CSafeLoader as SafeLoader
+except ImportError:
+    from yaml import SafeLoader
+
+_ONTOLOGY_KEYS = frozenset(
+    ("entity_kinds", "edge_kinds", "claim_predicates", "predicate_aliases")
+)
+
+
+@dataclass(frozen=True)
+class Ontology:
+    entity_kinds: frozenset[str] = frozenset()
+    edge_kinds: frozenset[str] = frozenset()
+    claim_predicates: frozenset[str] = frozenset()
+    predicate_aliases: dict[str, str] | None = None
+
+    @property
+    def active(self) -> bool:
+        return bool(
+            self.entity_kinds
+            or self.edge_kinds
+            or self.claim_predicates
+            or self.predicate_aliases
+        )
+
+    def canonical_claim_predicate(self, predicate: str, index: int) -> str:
+        aliases = self.predicate_aliases or {}
+        canonical = aliases.get(predicate, predicate)
+        if self.claim_predicates and canonical not in self.claim_predicates:
+            raise DataError(
+                f"record {index}: predicate {predicate!r} is not in "
+                f"vault/ontology.yaml claim_predicates"
+            )
+        return canonical
+
+    def validate_entity_kind(self, kind: str, index: int) -> None:
+        if self.entity_kinds and kind not in self.entity_kinds:
+            raise DataError(
+                f"record {index}: entity kind {kind!r} is not in "
+                f"vault/ontology.yaml entity_kinds"
+            )
+
+    def validate_edge_kind(self, kind: str, index: int) -> None:
+        if self.edge_kinds and kind not in self.edge_kinds:
+            raise DataError(
+                f"record {index}: edge kind {kind!r} is not in "
+                f"vault/ontology.yaml edge_kinds"
+            )
+
+    def summary(self) -> dict[str, Any]:
+        return {
+            "active": self.active,
+            "entity_kinds": sorted(self.entity_kinds),
+            "edge_kinds": sorted(self.edge_kinds),
+            "claim_predicates": sorted(self.claim_predicates),
+            "predicate_aliases": dict(sorted((self.predicate_aliases or {}).items())),
+        }
+
+
+def ontology_path(root: Path) -> Path:
+    return root / "vault" / "ontology.yaml"
+
+
+def load(root: Path) -> Ontology:
+    path = ontology_path(root)
+    if not path.exists():
+        return Ontology()
+    try:
+        data = yaml.load(path.read_text(encoding="utf-8"), Loader=SafeLoader)
+    except yaml.YAMLError as e:
+        raise DataError(f"invalid vault/ontology.yaml: {e}") from e
+    if data is None:
+        return Ontology()
+    if not isinstance(data, dict):
+        raise DataError("invalid vault/ontology.yaml: expected a mapping")
+    _check_known_keys(data)
+
+    entity_kinds = _string_set(data, "entity_kinds")
+    edge_kinds = _string_set(data, "edge_kinds")
+    claim_predicates = _string_set(data, "claim_predicates")
+    predicate_aliases = _string_map(data, "predicate_aliases")
+    if claim_predicates:
+        for alias, target in predicate_aliases.items():
+            if target not in claim_predicates:
+                raise DataError(
+                    "invalid vault/ontology.yaml: predicate_aliases target "
+                    f"{target!r} for {alias!r} is not in claim_predicates"
+                )
+
+    return Ontology(
+        entity_kinds=frozenset(entity_kinds),
+        edge_kinds=frozenset(edge_kinds),
+        claim_predicates=frozenset(claim_predicates),
+        predicate_aliases=predicate_aliases,
+    )
+
+
+def _check_known_keys(data: dict) -> None:
+    unknown = [key for key in data if not isinstance(key, str) or key not in _ONTOLOGY_KEYS]
+    if unknown:
+        rendered = ", ".join(repr(key) for key in unknown)
+        expected = ", ".join(sorted(_ONTOLOGY_KEYS))
+        raise DataError(
+            f"invalid vault/ontology.yaml: unknown key(s): {rendered}; expected one of: "
+            f"{expected}"
+        )
+
+
+def _string_set(data: dict, key: str) -> set[str]:
+    value = data.get(key, [])
+    if value is None:
+        return set()
+    if not isinstance(value, list):
+        raise DataError(f"invalid vault/ontology.yaml: {key} must be a list of strings")
+    out: set[str] = set()
+    for i, item in enumerate(value):
+        if not isinstance(item, str) or not item.strip():
+            raise DataError(
+                f"invalid vault/ontology.yaml: {key}[{i}] must be a non-empty string"
+            )
+        out.add(item.strip())
+    return out
+
+
+def _string_map(data: dict, key: str) -> dict[str, str]:
+    value = data.get(key, {})
+    if value is None:
+        return {}
+    if not isinstance(value, dict):
+        raise DataError(
+            f"invalid vault/ontology.yaml: {key} must be a mapping of strings to strings"
+        )
+    out: dict[str, str] = {}
+    for raw_k, raw_v in value.items():
+        if not isinstance(raw_k, str) or not raw_k.strip():
+            raise DataError(
+                f"invalid vault/ontology.yaml: {key} keys must be non-empty strings"
+            )
+        if not isinstance(raw_v, str) or not raw_v.strip():
+            raise DataError(
+                f"invalid vault/ontology.yaml: {key}.{raw_k} must be a non-empty string"
+            )
+        out[raw_k.strip()] = raw_v.strip()
+    return out

{scriptoria-0.8.1 → scriptoria-0.9.0}/tests/test_fact_cmd.py

@@ -68,6 +68,17 @@ def _graph_lines(kb):
     return [json.loads(s) for s in p.read_text(encoding="utf-8").splitlines() if s.strip()]
 
 
+def _entities_lines(kb):
+    p = kb.root / "vault" / "facts" / "entities.ndjson"
+    if not p.exists():
+        return []
+    return [json.loads(s) for s in p.read_text(encoding="utf-8").splitlines() if s.strip()]
+
+
+def _write_ontology(kb, text):
+    (kb.root / "vault" / "ontology.yaml").write_text(text, encoding="utf-8")
+
+
 def _two_claims(kb):
     """Seed a contradiction pair to reconcile."""
     kb.add_raw("s", SRC)
@@ -244,6 +255,38 @@ def test_fact_add_json_reports_appended_records(kb, capsys):
     assert rec["anchor"].startswith("qh:")
 
 
+def test_fact_add_ontology_canonicalizes_claim_predicate_aliases(kb):
+    kb.add_raw("s", SRC)
+    _write_ontology(
+        kb,
+        """
+claim_predicates:
+  - caches
+predicate_aliases:
+  p: caches
+""",
+    )
+    rc = _run_add(
+        kb,
+        _ndjson(_claim("Caching answers beats recomputing them.", predicate="p")),
+    )
+    assert rc == 0
+    assert _claims_lines(kb)[0]["predicate"] == "caches"
+
+
+def test_fact_add_ontology_rejects_unknown_claim_predicate(kb):
+    kb.add_raw("s", SRC)
+    _write_ontology(kb, "claim_predicates:\n  - caches\n")
+
+    rc = _run_add(
+        kb,
+        _ndjson(_claim("Caching answers beats recomputing them.", predicate="p")),
+    )
+
+    assert rc == 3
+    assert _claims_lines(kb) == []
+
+
 # --------------------------------------------------------------------------- #
 # All-or-nothing batch + per-record failures (exit 1)
 # --------------------------------------------------------------------------- #
@@ -483,6 +526,93 @@ def test_fact_add_entities_appends_and_conflicts(kb, capsys):
     assert len(lines.splitlines()) == 1  # nothing else was appended
 
 
+def test_fact_add_entities_accept_optional_uri_metadata(kb):
+    ent = {
+        "entity_id": "entity/duckdb",
+        "name": "DuckDB",
+        "kind": "tool",
+        "uri": "https://duckdb.org/",
+        "same_as": ["https://www.wikidata.org/wiki/Q118533698"],
+        "external_ids": {"wikidata": "Q118533698"},
+    }
+
+    assert _run_add(kb, _ndjson(ent), "--table", "entities") == 0
+
+    [stored] = _entities_lines(kb)
+    assert stored["uri"] == "https://duckdb.org/"
+    assert stored["same_as"] == ["https://www.wikidata.org/wiki/Q118533698"]
+    assert stored["external_ids"] == {"wikidata": "Q118533698"}
+
+
+def test_fact_add_ontology_rejects_unknown_entity_kind_and_edge_kind(kb):
+    _write_ontology(
+        kb,
+        """
+entity_kinds:
+  - tool
+edge_kinds:
+  - depends-on
+""",
+    )
+
+    assert (
+        _run_add(
+            kb,
+            _ndjson({"entity_id": "entity/a", "name": "A", "kind": "concept"}),
+            "--table",
+            "entities",
+        )
+        == 3
+    )
+    assert _run_add(kb, _ndjson(_edge(kind="relates-to")), "--table", "edges") == 3
+    assert _run_add(kb, _ndjson(_edge(kind="depends-on")), "--table", "edges") == 0
+
+
+def test_ontology_command_reports_optional_vocabulary(kb, capsys):
+    _write_ontology(
+        kb,
+        """
+entity_kinds:
+  - tool
+edge_kinds:
+  - depends-on
+claim_predicates:
+  - caches
+predicate_aliases:
+  p: caches
+""",
+    )
+
+    assert cli.main(["ontology", "--json", "--root", str(kb.root)]) == 0
+
+    data = json.loads(capsys.readouterr().out)
+    assert data["active"] is True
+    assert data["entity_kinds"] == ["tool"]
+    assert data["edge_kinds"] == ["depends-on"]
+    assert data["claim_predicates"] == ["caches"]
+    assert data["predicate_aliases"] == {"p": "caches"}
+
+
+def test_ontology_rejects_alias_to_unknown_predicate(kb):
+    _write_ontology(
+        kb,
+        """
+claim_predicates:
+  - caches
+predicate_aliases:
+  p: stores
+""",
+    )
+
+    assert cli.main(["ontology", "--root", str(kb.root)]) == 3
+
+
+def test_ontology_rejects_unknown_top_level_key(kb):
+    _write_ontology(kb, "claim_predicate:\n  - caches\n")
+
+    assert cli.main(["ontology", "--root", str(kb.root)]) == 3
+
+
 def test_fact_add_edges_appends_and_skips_duplicates(kb):
     edge = {"src": "entity/duckdb", "dst": "entity/motherduck", "kind": "made-by"}
     assert _run_add(kb, _ndjson(edge), "--table", "edges") == 0

{scriptoria-0.8.1 → scriptoria-0.9.0}/uv.lock

@@ -249,7 +249,7 @@ name = "exceptiongroup"
 version = "1.3.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "typing-extensions", marker = "python_full_version < '3.11'" },
+    { name = "typing-extensions" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/50/79/66800aadf48771f6b62f7eb014e352e5d06856655206165d775e675a02c9/exceptiongroup-1.3.1.tar.gz", hash = "sha256:8b412432c6055b0b7d14c310000ae93352ed6754f70fa8f7c34141f91c4e3219", size = 30371, upload-time = "2025-11-21T23:01:54.787Z" }
 wheels = [
@@ -1141,7 +1141,7 @@ wheels = [
 
 [[package]]
 name = "scriptoria"
-version = "0.8.1"
+version = "0.9.0"
 source = { editable = "." }
 dependencies = [
     { name = "duckdb" },