scriptoria 0.10.0__tar.gz → 0.11.0__tar.gz

{scriptoria-0.10.0 → scriptoria-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: scriptoria
-Version: 0.10.0
+Version: 0.11.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

{scriptoria-0.10.0 → scriptoria-0.11.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.10.0"
+version = "0.11.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.10.0 → scriptoria-0.11.0}/src/scrip/__init__.py

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

{scriptoria-0.10.0 → scriptoria-0.11.0}/src/scrip/cli.py

@@ -1,7 +1,7 @@
 """Command-line entry point for ``scrip``.
 
-Dispatches to the four subcommands. Logic modules (``graph``, ``anchors``,
-``query``) are imported lazily inside handlers so ``scrip --help`` works even
+Dispatches to the subcommands. Logic modules (``graph``, ``anchors``,
+``query``, ``neighbors``) are imported lazily inside handlers so ``scrip --help`` works even
 before those modules exist, and so importing the CLI never pulls in DuckDB
 unless a query is actually run.
 """
@@ -256,6 +256,25 @@ def cmd_query(args: argparse.Namespace) -> int:
     return 0
 
 
+def cmd_neighbors(args: argparse.Namespace) -> int:
+    from . import neighbors
+
+    root = resolve_root(args.root)
+    result = neighbors.neighborhood(
+        root,
+        args.node,
+        depth=args.depth,
+        kinds=args.kind,
+        direction=args.direction,
+        limit=args.limit,
+    )
+    if args.json:
+        _emit(result)
+    else:
+        neighbors.print_neighborhood(result)
+    return 0
+
+
 def cmd_index(args: argparse.Namespace) -> int:
     from . import embeddings
 
@@ -519,12 +538,13 @@ def cmd_fact_add(args: argparse.Namespace) -> int:
     root = resolve_root(args.root)
     if args.file:
         try:
-            text = Path(args.file).read_text(encoding="utf-8")
+            with Path(args.file).open(encoding="utf-8", newline="\n") as f:
+                proposals = facts.parse_ndjson(f)
         except OSError as e:
             raise errors.UsageError(f"cannot read --file: {e}") from e
     else:
-        text = sys.stdin.read()
-    result = facts.add(root, args.table, facts.parse_ndjson(text))
+        proposals = facts.parse_ndjson(sys.stdin)
+    result = facts.add(root, args.table, proposals)
     if args.json:
         _emit(result)
     else:
@@ -705,6 +725,25 @@ def build_parser() -> argparse.ArgumentParser:
     pq.add_argument("--limit", type=int, help="row limit for a named query")
     pq.set_defaults(func=cmd_query)
 
+    pn = sub.add_parser(
+        "neighbors",
+        parents=[common],
+        help="show one node's edges within N hops of facts/graph.ndjson",
+    )
+    pn.add_argument("node", help="an entity id (entity/<slug>) or any edge src/dst id")
+    pn.add_argument("--depth", type=int, default=1, help="hops to walk, 1-3 (default 1)")
+    pn.add_argument(
+        "--kind", action="append", help="only follow edges of this kind (repeatable)"
+    )
+    pn.add_argument(
+        "--direction",
+        choices=["both", "out", "in"],
+        default="both",
+        help="follow outgoing, incoming, or both (default both)",
+    )
+    pn.add_argument("--limit", type=int, default=50, help="max edges shown (default 50)")
+    pn.set_defaults(func=cmd_neighbors)
+
     pi = sub.add_parser(
         "index",
         parents=[common],

{scriptoria-0.10.0 → scriptoria-0.11.0}/src/scrip/facts.py

@@ -21,7 +21,7 @@ from __future__ import annotations
 
 import json
 import re
-from collections.abc import Iterator
+from collections.abc import Iterable, Iterator
 from datetime import datetime, timezone
 from pathlib import Path
 
@@ -91,15 +91,18 @@ def _iter_lf_lines(text: str) -> Iterator[str]:
         start = end + 1
 
 
-def parse_ndjson(text: str) -> list[dict]:
-    """Parse proposed records (one JSON object per line). Malformed input is a
+def parse_ndjson(source: str | Iterable[str]) -> list[dict]:
+    """Parse proposed records (one JSON object per line). ``source`` is the whole
+    input as a string, or an iterable of lines such as a file opened with
+    ``newline="\n"`` (streamed, never read whole). Malformed input is a
     :class:`DataError` with its line number; an empty input is a usage error."""
     records: list[dict] = []
     # Split on "\n" only, not str.splitlines(): NDJSON records are newline-
     # delimited and may legally contain U+2028/U+2029/NEL inside a JSON string,
     # which splitlines() would wrongly treat as record breaks. trailing \r (from
     # \r\n) and the trailing empty element from a final newline are dropped below.
-    for lineno, raw_line in enumerate(_iter_lf_lines(text), start=1):
+    lines = _iter_lf_lines(source) if isinstance(source, str) else source
+    for lineno, raw_line in enumerate(lines, start=1):
         line = raw_line.strip()
         if not line:
             continue

scriptoria-0.11.0/src/scrip/neighbors.py

@@ -0,0 +1,166 @@
+"""Focused neighborhood views over ``facts/graph.ndjson``.
+
+``scrip query edges`` dumps the whole edge list; past a few dozen edges that is
+the usual unreadable hairball. This module answers the narrower question "what
+is connected to this one node, within N hops?" — deterministic, read-only, and
+read through the same DuckDB lens as ``scrip query`` so the two cannot drift.
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from pathlib import Path
+
+from . import facts_dir
+from . import query as query_mod
+from .errors import DataError, UsageError
+
+MAX_DEPTH = 3
+DIRECTIONS = ("both", "out", "in")
+
+
+def _has_rows(path: Path) -> bool:
+    if not path.exists():
+        return False
+    with path.open(encoding="utf-8") as f:
+        return any(line.strip() for line in f)
+
+
+def _load(root: Path, name: str, fname: str) -> list[dict]:
+    # An absent or empty table is simply no rows: DuckDB has no view for it.
+    if not _has_rows(facts_dir(root) / fname):
+        return []
+    _, rows = query_mod.run(root, name=name)
+    return rows
+
+
+def _node_summary(node: str, entity: dict | None) -> dict:
+    out: dict = {"id": node}
+    if entity:
+        out["name"] = entity.get("name")
+        out["kind"] = entity.get("kind")
+    return out
+
+
+def neighborhood(
+    root: Path,
+    node: str,
+    *,
+    depth: int = 1,
+    kinds: list[str] | None = None,
+    direction: str = "both",
+    limit: int = 50,
+) -> dict:
+    """Return the edges within ``depth`` hops of ``node`` and the nodes they touch
+    (entity name/kind when the node is an entity, else id only).
+
+    Walks breadth-first; each edge is reported once, at the hop it is first
+    reached. Order is deterministic: by hop, then ``src``, ``dst``, ``kind``.
+    ``truncated`` is true when ``limit`` cut edges off."""
+    if not 1 <= depth <= MAX_DEPTH:
+        raise UsageError(f"--depth must be between 1 and {MAX_DEPTH}")
+    if direction not in DIRECTIONS:
+        raise UsageError(f"--direction must be one of: {', '.join(DIRECTIONS)}")
+    if limit < 1:
+        raise UsageError("--limit must be at least 1")
+
+    entities = _load(root, "entities", "entities.ndjson")
+    edges = _load(root, "edges", "graph.ndjson")
+    entity_by_id = {
+        str(e["entity_id"]): e for e in entities if isinstance(e.get("entity_id"), str)
+    }
+    wanted = set(kinds) if kinds else None
+
+    out_adj: dict[str, list[int]] = {}
+    in_adj: dict[str, list[int]] = {}
+    known = set(entity_by_id)
+    for i, e in enumerate(edges):
+        src, dst = str(e.get("src") or ""), str(e.get("dst") or "")
+        known.update((src, dst))
+        if wanted is not None and e.get("kind") not in wanted:
+            continue
+        out_adj.setdefault(src, []).append(i)
+        in_adj.setdefault(dst, []).append(i)
+    if node not in known:
+        raise DataError(f"no such node: {node}")
+
+    seen_edges: set[int] = set()
+    found: list[tuple[int, int]] = []  # (hop, edge index)
+    visited = {node}
+    frontier: deque[tuple[str, int]] = deque([(node, 0)])
+    while frontier:
+        cur, hop = frontier.popleft()
+        if hop == depth:
+            continue
+        steps: list[tuple[int, str]] = []
+        if direction in ("both", "out"):
+            steps += [(i, str(edges[i].get("dst") or "")) for i in out_adj.get(cur, [])]
+        if direction in ("both", "in"):
+            steps += [(i, str(edges[i].get("src") or "")) for i in in_adj.get(cur, [])]
+        for i, other in steps:
+            if i not in seen_edges:
+                seen_edges.add(i)
+                found.append((hop + 1, i))
+            if other not in visited:
+                visited.add(other)
+                frontier.append((other, hop + 1))
+
+    def _key(item: tuple[int, int]) -> tuple:
+        hop, i = item
+        e = edges[i]
+        return (hop, str(e.get("src") or ""), str(e.get("dst") or ""), str(e.get("kind") or ""))
+
+    found.sort(key=_key)
+    truncated = len(found) > limit
+    found = found[:limit]
+
+    out_edges: list[dict] = []
+    touched = {node}
+    for hop, i in found:
+        e = edges[i]
+        rec = {"src": e.get("src"), "dst": e.get("dst"), "kind": e.get("kind"), "hop": hop}
+        for key in ("source_id", "anchor"):
+            if e.get(key):
+                rec[key] = e[key]
+        out_edges.append(rec)
+        touched.update((str(rec["src"]), str(rec["dst"])))
+
+    return {
+        "root": node,
+        "depth": depth,
+        "nodes": [_node_summary(n, entity_by_id.get(n)) for n in sorted(touched)],
+        "edges": out_edges,
+        "truncated": truncated,
+    }
+
+
+def print_neighborhood(result: dict) -> None:
+    names = {n["id"]: n for n in result["nodes"]}
+    root = result["root"]
+
+    def _label(node: str) -> str:
+        ent = names.get(node, {})
+        bits = [ent.get("name") or "", f"({ent['kind']})" if ent.get("kind") else ""]
+        return " ".join(b for b in bits if b)
+
+    print(f"{root}  {_label(root)}".rstrip())
+    rows = []
+    for e in result["edges"]:
+        src, dst = str(e["src"]), str(e["dst"])
+        if src == root:
+            arrow, other = "->", dst
+        elif dst == root:
+            arrow, other = "<-", src
+        else:
+            arrow, other = f"{src} ->", dst
+        cite = f"  [cited {e['source_id']}#{e['anchor']}]" if e.get("anchor") else ""
+        indent = "  " * e["hop"]
+        rows.append(f"{indent}{arrow} {e['kind']}  {other}  {_label(other)}".rstrip() + cite)
+    for line in rows:
+        print(line)
+    n_edges, n_nodes = len(result["edges"]), len(result["nodes"])
+    more = " (truncated; raise --limit)" if result["truncated"] else ""
+    print(
+        f"{n_edges} edge{'s' if n_edges != 1 else ''}, "
+        f"{n_nodes} node{'s' if n_nodes != 1 else ''} (depth {result['depth']}){more}"
+    )

{scriptoria-0.10.0 → scriptoria-0.11.0}/tests/test_fact_cmd.py

@@ -47,32 +47,32 @@ def _run_add(kb, text, *extra):
     return cli.main(["fact", "add", "--file", str(p), "--root", str(kb.root), *extra])
 
 
-def _claims_lines(kb):
-    p = kb.root / "vault" / "facts" / "claims.ndjson"
+def _read_ndjson(p):
+    # Split on "\n" only: splitlines() also breaks on U+2028/U+2029/NEL, which
+    # are legal inside JSON strings and would split one record into fragments.
     if not p.exists():
         return []
-    return [json.loads(s) for s in p.read_text(encoding="utf-8").splitlines() if s.strip()]
+    return [json.loads(s) for s in p.read_text(encoding="utf-8").split("\n") if s.strip()]
+
+
+def _claims_lines(kb):
+    p = kb.root / "vault" / "facts" / "claims.ndjson"
+    return _read_ndjson(p)
 
 
 def _recs_lines(kb):
     p = kb.root / "vault" / "facts" / "reconciliations.ndjson"
-    if not p.exists():
-        return []
-    return [json.loads(s) for s in p.read_text(encoding="utf-8").splitlines() if s.strip()]
+    return _read_ndjson(p)
 
 
 def _graph_lines(kb):
     p = kb.root / "vault" / "facts" / "graph.ndjson"
-    if not p.exists():
-        return []
-    return [json.loads(s) for s in p.read_text(encoding="utf-8").splitlines() if s.strip()]
+    return _read_ndjson(p)
 
 
 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()]
+    return _read_ndjson(p)
 
 
 def _write_ontology(kb, text):
@@ -240,6 +240,20 @@ def test_fact_add_reads_stdin(kb, monkeypatch):
     assert len(_claims_lines(kb)) == 1
 
 
+def test_fact_add_file_streams_crlf_and_u2028(kb):
+    # --file is streamed with newline="\n": CRLF endings are stripped and a raw
+    # U+2028 inside a JSON string does not split the record.
+    kb.add_raw("s", SRC)
+    text = _ndjson(
+        _claim("The quick brown fox jumps over the lazy dog.", object="a\u2028b"),
+        _claim("Caching answers beats recomputing them."),
+    ).replace("\n", "\r\n")
+    assert "\u2028" in text
+    rc = _run_add(kb, text)
+    assert rc == 0
+    assert [c["object"] for c in _claims_lines(kb)] == ["a\u2028b", "o"]
+
+
 def test_fact_add_json_reports_appended_records(kb, capsys):
     kb.add_raw("s", SRC)
     rc = _run_add(
@@ -513,7 +527,7 @@ def test_fact_add_entities_appends_and_conflicts(kb, capsys):
     rc = _run_add(kb, _ndjson(ent), "--table", "entities")
     assert rc == 0
     lines = (kb.root / "vault" / "facts" / "entities.ndjson").read_text(encoding="utf-8")
-    assert json.loads(lines.splitlines()[0])["entity_id"] == "entity/duckdb"
+    assert json.loads(lines.split("\n")[0])["entity_id"] == "entity/duckdb"
 
     # identical record is skipped; a conflicting one (same id, new name) fails
     assert _run_add(kb, _ndjson(ent), "--table", "entities") == 0
@@ -523,7 +537,7 @@ def test_fact_add_entities_appends_and_conflicts(kb, capsys):
     assert rc == 1
     [failure] = json.loads(capsys.readouterr().out)["failures"]
     assert failure["status"] == "ID_CONFLICT"
-    assert len(lines.splitlines()) == 1  # nothing else was appended
+    assert lines.count("\n") == 1  # nothing else was appended
 
 
 def test_fact_add_entities_accept_optional_uri_metadata(kb):
@@ -618,7 +632,7 @@ def test_fact_add_edges_appends_and_skips_duplicates(kb):
     assert _run_add(kb, _ndjson(edge), "--table", "edges") == 0
     assert _run_add(kb, _ndjson(edge), "--table", "edges") == 0
     lines = (kb.root / "vault" / "facts" / "graph.ndjson").read_text(encoding="utf-8")
-    assert len(lines.splitlines()) == 1
+    assert lines.count("\n") == 1
 
 
 # --------------------------------------------------------------------------- #

{scriptoria-0.10.0 → scriptoria-0.11.0}/tests/test_facts.py

@@ -1,3 +1,5 @@
+import io
+
 import pytest
 from scrip.errors import DataError, UsageError
 
@@ -46,3 +48,12 @@ def test_parse_ndjson_reports_line_number_on_bad_json():
 def test_parse_ndjson_empty_is_usage_error():
     with pytest.raises(UsageError):
         facts.parse_ndjson("  \n  \n")
+
+
+def test_parse_ndjson_accepts_line_iterable():
+    # A file opened with newline="\n" yields lines split on "\n" only, so
+    # U+2028 inside a string and \r\n endings parse the same as the str path.
+    text = '{"a": "x\u2028y"}\r\n\r\n{"b": 2}\n'
+    expected = facts.parse_ndjson(text)
+    assert facts.parse_ndjson(io.StringIO(text, newline="\n")) == expected
+    assert expected == [{"a": "x\u2028y"}, {"b": 2}]

scriptoria-0.11.0/tests/test_neighbors_cmd.py

@@ -0,0 +1,139 @@
+"""`scrip neighbors` — a focused, read-only view of one node's edges within N hops
+of facts/graph.ndjson, instead of the whole-graph dump of `scrip query edges`."""
+
+import json
+
+from scrip import cli, neighbors
+
+
+def _write(kb, fname, rows):
+    p = kb.root / "vault" / "facts" / fname
+    p.write_text("".join(json.dumps(r, ensure_ascii=False) + "\n" for r in rows), encoding="utf-8")
+
+
+def _ent(slug, name=None, kind="system"):
+    return {"entity_id": f"entity/{slug}", "name": name or slug.title(), "kind": kind}
+
+
+def _edge(src, dst, kind="depends-on", **kw):
+    return {"src": f"entity/{src}", "dst": f"entity/{dst}", "kind": kind, **kw}
+
+
+def _graph(kb):
+    # a -> b -> c -> d, plus x -> a (incoming), a -alt-> e, and a cycle c -> a.
+    _write(kb, "entities.ndjson", [_ent(s) for s in "abcdex"])
+    _write(
+        kb,
+        "graph.ndjson",
+        [
+            _edge("a", "b"),
+            _edge("b", "c"),
+            _edge("c", "d"),
+            _edge("x", "a", "part-of"),
+            _edge("a", "e", "alternative-to"),
+            _edge("c", "a"),
+        ],
+    )
+
+
+def _pairs(result):
+    return [(e["src"], e["dst"], e["kind"]) for e in result["edges"]]
+
+
+def test_depth_one_both_directions(kb):
+    _graph(kb)
+    r = neighbors.neighborhood(kb.root, "entity/a")
+    assert r["root"] == "entity/a" and r["depth"] == 1 and r["truncated"] is False
+    assert _pairs(r) == [
+        ("entity/a", "entity/b", "depends-on"),
+        ("entity/a", "entity/e", "alternative-to"),
+        ("entity/c", "entity/a", "depends-on"),
+        ("entity/x", "entity/a", "part-of"),
+    ]
+    assert all(e["hop"] == 1 for e in r["edges"])
+    assert [n["id"] for n in r["nodes"]] == [
+        "entity/a", "entity/b", "entity/c", "entity/e", "entity/x",
+    ]
+
+
+def test_depth_two_reaches_second_hop_and_cycle_terminates(kb):
+    _graph(kb)
+    r = neighbors.neighborhood(kb.root, "entity/a", depth=2, direction="out")
+    assert _pairs(r) == [
+        ("entity/a", "entity/b", "depends-on"),
+        ("entity/a", "entity/e", "alternative-to"),
+        ("entity/b", "entity/c", "depends-on"),
+    ]
+    assert [e["hop"] for e in r["edges"]] == [1, 1, 2]
+    # depth 3 closes the c -> a cycle and reaches d, each edge once
+    r3 = neighbors.neighborhood(kb.root, "entity/a", depth=3, direction="out")
+    assert len(_pairs(r3)) == len(set(_pairs(r3))) == 5
+
+
+def test_kind_filter_and_direction_in(kb):
+    _graph(kb)
+    r = neighbors.neighborhood(kb.root, "entity/a", kinds=["part-of"])
+    assert _pairs(r) == [("entity/x", "entity/a", "part-of")]
+    r_in = neighbors.neighborhood(kb.root, "entity/a", direction="in")
+    assert {e["dst"] for e in r_in["edges"]} == {"entity/a"}
+
+
+def test_limit_sets_truncated(kb):
+    _graph(kb)
+    r = neighbors.neighborhood(kb.root, "entity/a", limit=2)
+    assert len(r["edges"]) == 2 and r["truncated"] is True
+
+
+def test_cited_edge_and_non_entity_node(kb):
+    _write(kb, "entities.ndjson", [_ent("a")])
+    _write(
+        kb,
+        "graph.ndjson",
+        [{"src": "entity/a", "dst": "raw/paper", "kind": "cites",
+          "source_id": "raw/paper", "anchor": "qh:ab|loc:0|len:5"}],
+    )
+    r = neighbors.neighborhood(kb.root, "raw/paper")
+    [edge] = r["edges"]
+    assert edge["anchor"] == "qh:ab|loc:0|len:5"
+    assert {"id": "raw/paper"} in r["nodes"]  # not an entity: id only
+
+
+def test_entity_without_edges(kb):
+    _write(kb, "entities.ndjson", [_ent("lonely")])
+    r = neighbors.neighborhood(kb.root, "entity/lonely")
+    assert r["edges"] == [] and [n["id"] for n in r["nodes"]] == ["entity/lonely"]
+
+
+def test_cli_unknown_node_is_data_error(kb, capsys):
+    _graph(kb)
+    assert cli.main(["neighbors", "entity/nope", "--root", str(kb.root)]) == 3
+    assert "no such node: entity/nope" in capsys.readouterr().err
+
+
+def test_cli_empty_facts_is_data_error(kb):
+    assert cli.main(["neighbors", "entity/a", "--root", str(kb.root)]) == 3
+
+
+def test_cli_depth_out_of_range_is_usage_error(kb):
+    _graph(kb)
+    assert cli.main(["neighbors", "entity/a", "--depth", "4", "--root", str(kb.root)]) == 2
+
+
+def test_cli_json_is_stable(kb, capsys):
+    _graph(kb)
+    args = ["neighbors", "entity/a", "--depth", "2", "--json", "--root", str(kb.root)]
+    assert cli.main(args) == 0
+    first = json.loads(capsys.readouterr().out)
+    assert cli.main(args) == 0
+    assert json.loads(capsys.readouterr().out) == first
+    assert set(first) == {"root", "depth", "nodes", "edges", "truncated"}
+
+
+def test_cli_text_output(kb, capsys):
+    _graph(kb)
+    assert cli.main(["neighbors", "entity/a", "--root", str(kb.root)]) == 0
+    out = capsys.readouterr().out.splitlines()
+    assert out[0] == "entity/a  A (system)"
+    assert "  -> depends-on  entity/b  B (system)" in out
+    assert "  <- part-of  entity/x  X (system)" in out
+    assert out[-1] == "4 edges, 5 nodes (depth 1)"

{scriptoria-0.10.0 → scriptoria-0.11.0}/uv.lock

@@ -1141,7 +1141,7 @@ wheels = [
 
 [[package]]
 name = "scriptoria"
-version = "0.10.0"
+version = "0.11.0"
 source = { editable = "." }
 dependencies = [
     { name = "duckdb" },