cairn-engine 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.
- cairn_engine/__init__.py +97 -0
- cairn_engine/adapters/__init__.py +10 -0
- cairn_engine/adapters/_build.py +87 -0
- cairn_engine/adapters/base.py +78 -0
- cairn_engine/adapters/cypher.py +127 -0
- cairn_engine/adapters/jsonfile.py +122 -0
- cairn_engine/adapters/memory.py +188 -0
- cairn_engine/adapters/sqlite.py +187 -0
- cairn_engine/entity/__init__.py +12 -0
- cairn_engine/entity/bitemporal.py +101 -0
- cairn_engine/entity/crosssystem.py +128 -0
- cairn_engine/entity/model.py +100 -0
- cairn_engine/entity/normalize.py +55 -0
- cairn_engine/entity/ontology.py +366 -0
- cairn_engine/entity/resolve.py +271 -0
- cairn_engine/entity/semantic.py +103 -0
- cairn_engine/entity/traverse.py +107 -0
- cairn_engine/py.typed +0 -0
- cairn_engine-0.1.0.dist-info/METADATA +105 -0
- cairn_engine-0.1.0.dist-info/RECORD +22 -0
- cairn_engine-0.1.0.dist-info/WHEEL +4 -0
- cairn_engine-0.1.0.dist-info/licenses/LICENSE +21 -0
cairn_engine/__init__.py
ADDED
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
"""Cairn — the deterministic entity / world-model engine for AI agents.
|
|
2
|
+
|
|
3
|
+
Resolve messy references to canonical IDs, traverse their relations, and author
|
|
4
|
+
the frozen alias table that makes it all reproducible — storage-agnostic,
|
|
5
|
+
local-first, zero generative-LLM on the hot path.
|
|
6
|
+
|
|
7
|
+
Public API (everything importable straight off `cairn`):
|
|
8
|
+
|
|
9
|
+
HOT PATH (deterministic, offline)
|
|
10
|
+
resolve(query, *, table, ...) -> (resolved, unresolved)
|
|
11
|
+
traverse(canonical_id, *, graph, ...) -> TraversalResult
|
|
12
|
+
traverse_cypher(canonical_id, *, run, ...) -> same, via a graph DB (M2.3)
|
|
13
|
+
compile_traversal(canonical_id, ...) -> CypherQuery (no-query-language)
|
|
14
|
+
as_at(facts, *, valid_as_of, known_as_of) -> point-in-time slice (TH-3)
|
|
15
|
+
supersede(history, new_fact, *, at) -> append-only correction
|
|
16
|
+
|
|
17
|
+
BUILD TIME (offline authoring; human gate mandatory)
|
|
18
|
+
author_from_text(text, *, source, extractor=...)
|
|
19
|
+
dedup_candidates(candidates, ...)
|
|
20
|
+
with_mirror_edges(entities)
|
|
21
|
+
suggest_canonical_id(surface, entity_type)
|
|
22
|
+
dump_entities(entities) / load_entities(text)
|
|
23
|
+
|
|
24
|
+
DATA MODEL (immutable value records — TH-5)
|
|
25
|
+
Entity, Ref, Relation, ResolvedEntity, Candidate, DedupReport,
|
|
26
|
+
TraversalHit, TraversalResult, ResolverConfig
|
|
27
|
+
|
|
28
|
+
CROSS-SYSTEM IDENTITY (M2.4)
|
|
29
|
+
CrossSystemIndex — canonical entity <-> its many system-specific IDs
|
|
30
|
+
|
|
31
|
+
ADAPTERS (storage-agnostic protocols + in-memory implementations)
|
|
32
|
+
AliasTableAdapter, GraphAdapter, InMemoryAliasTable, InMemoryGraph
|
|
33
|
+
|
|
34
|
+
Design foundations: docs/patterns/patterns_entities.yaml (TH-1..TH-5,
|
|
35
|
+
OP-28/34/35) and docs/research/foundations/.
|
|
36
|
+
"""
|
|
37
|
+
|
|
38
|
+
from cairn_engine.adapters.base import AliasTableAdapter, GraphAdapter
|
|
39
|
+
from cairn_engine.adapters.cypher import CypherQuery, CypherRunFn, compile_traversal, traverse_cypher
|
|
40
|
+
from cairn_engine.adapters.jsonfile import dump_entities, load_entities
|
|
41
|
+
from cairn_engine.adapters.memory import InMemoryAliasTable, InMemoryGraph
|
|
42
|
+
from cairn_engine.adapters.sqlite import SqliteAliasTable
|
|
43
|
+
from cairn_engine.entity.bitemporal import as_at, supersede
|
|
44
|
+
from cairn_engine.entity.crosssystem import CrossSystemIndex
|
|
45
|
+
from cairn_engine.entity.model import Entity, Ref, Relation, ResolvedEntity
|
|
46
|
+
from cairn_engine.entity.ontology import (
|
|
47
|
+
Candidate,
|
|
48
|
+
DedupReport,
|
|
49
|
+
author_from_text,
|
|
50
|
+
dedup_candidates,
|
|
51
|
+
find_alias_conflicts,
|
|
52
|
+
suggest_canonical_id,
|
|
53
|
+
with_mirror_edges,
|
|
54
|
+
)
|
|
55
|
+
from cairn_engine.entity.resolve import ArbiterFn, ResolverConfig, resolve
|
|
56
|
+
from cairn_engine.entity.semantic import EmbedderFn, EmbeddingIndex, cosine
|
|
57
|
+
from cairn_engine.entity.traverse import TraversalHit, TraversalResult, traverse
|
|
58
|
+
|
|
59
|
+
__version__ = "0.1.0"
|
|
60
|
+
|
|
61
|
+
__all__ = [
|
|
62
|
+
"AliasTableAdapter",
|
|
63
|
+
"ArbiterFn",
|
|
64
|
+
"Candidate",
|
|
65
|
+
"CrossSystemIndex",
|
|
66
|
+
"CypherQuery",
|
|
67
|
+
"CypherRunFn",
|
|
68
|
+
"DedupReport",
|
|
69
|
+
"EmbedderFn",
|
|
70
|
+
"EmbeddingIndex",
|
|
71
|
+
"Entity",
|
|
72
|
+
"GraphAdapter",
|
|
73
|
+
"InMemoryAliasTable",
|
|
74
|
+
"InMemoryGraph",
|
|
75
|
+
"SqliteAliasTable",
|
|
76
|
+
"Ref",
|
|
77
|
+
"Relation",
|
|
78
|
+
"ResolvedEntity",
|
|
79
|
+
"ResolverConfig",
|
|
80
|
+
"TraversalHit",
|
|
81
|
+
"TraversalResult",
|
|
82
|
+
"__version__",
|
|
83
|
+
"as_at",
|
|
84
|
+
"author_from_text",
|
|
85
|
+
"compile_traversal",
|
|
86
|
+
"cosine",
|
|
87
|
+
"dedup_candidates",
|
|
88
|
+
"dump_entities",
|
|
89
|
+
"find_alias_conflicts",
|
|
90
|
+
"load_entities",
|
|
91
|
+
"resolve",
|
|
92
|
+
"suggest_canonical_id",
|
|
93
|
+
"supersede",
|
|
94
|
+
"traverse",
|
|
95
|
+
"traverse_cypher",
|
|
96
|
+
"with_mirror_edges",
|
|
97
|
+
]
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
"""Storage adapters — the boundary that keeps the core storage-agnostic.
|
|
2
|
+
|
|
3
|
+
The engine core depends only on these Protocols, never on a concrete store
|
|
4
|
+
(`storage_agnostic_core`). An in-memory / YAML / SQLite / graph backend all
|
|
5
|
+
implement the same interface; swapping scale changes the adapter, not call sites.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from cairn_engine.adapters.base import AliasTableAdapter, GraphAdapter
|
|
9
|
+
|
|
10
|
+
__all__ = ["AliasTableAdapter", "GraphAdapter"]
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
"""Shared build-time folding + indexing for alias-table adapters.
|
|
2
|
+
|
|
3
|
+
Both InMemoryAliasTable and SqliteAliasTable call these — so a merge behaves
|
|
4
|
+
identically no matter where the frozen data lives. This IS the storage-agnostic
|
|
5
|
+
guarantee, made concrete: one folding algorithm, N storage backends.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import dataclasses
|
|
11
|
+
from typing import Mapping, Sequence
|
|
12
|
+
|
|
13
|
+
from cairn_engine.entity.model import Entity, Ref, Relation
|
|
14
|
+
from cairn_engine.entity.normalize import normalize
|
|
15
|
+
|
|
16
|
+
__all__ = ["find_root", "fold_entities", "build_indexes"]
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
def find_root(canonical_id: str, merged: Mapping[str, str]) -> str:
|
|
20
|
+
"""Union-Find `find`: follow parent links to the class representative (TH-1)."""
|
|
21
|
+
while canonical_id in merged:
|
|
22
|
+
canonical_id = merged[canonical_id]
|
|
23
|
+
return canonical_id
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def fold_entities(entities: Mapping[str, Entity], merged: Mapping[str, str]) -> list[Entity]:
|
|
27
|
+
"""Fold merged classes into their representatives (OP-35 reference forwarding).
|
|
28
|
+
|
|
29
|
+
The representative absorbs every member's aliases, refs, and relations;
|
|
30
|
+
relation targets are rewritten through find(); self-loops are dropped;
|
|
31
|
+
merged_from records provenance. Deterministic (sorted). Returns the
|
|
32
|
+
class representatives only — merged-away ids are gone from the result.
|
|
33
|
+
"""
|
|
34
|
+
members: dict[str, list[str]] = {}
|
|
35
|
+
for cid in sorted(entities):
|
|
36
|
+
members.setdefault(find_root(cid, merged), []).append(cid)
|
|
37
|
+
|
|
38
|
+
canonical: list[Entity] = []
|
|
39
|
+
for root in sorted(members):
|
|
40
|
+
rep = entities[root]
|
|
41
|
+
aliases: list[str] = list(rep.aliases)
|
|
42
|
+
refs: list[Ref] = list(rep.refs)
|
|
43
|
+
relations: list[Relation] = []
|
|
44
|
+
merged_from: list[str] = list(rep.merged_from)
|
|
45
|
+
for cid in members[root]:
|
|
46
|
+
ent = entities[cid]
|
|
47
|
+
if cid != root:
|
|
48
|
+
merged_from.append(cid)
|
|
49
|
+
aliases.append(ent.label)
|
|
50
|
+
aliases.extend(ent.aliases)
|
|
51
|
+
refs.extend(ent.refs)
|
|
52
|
+
for rel in ent.relations:
|
|
53
|
+
target = find_root(rel.target_id, merged)
|
|
54
|
+
if target == root:
|
|
55
|
+
continue # merged-away edge would self-loop — drop
|
|
56
|
+
relations.append(
|
|
57
|
+
rel if target == rel.target_id else dataclasses.replace(rel, target_id=target)
|
|
58
|
+
)
|
|
59
|
+
canonical.append(
|
|
60
|
+
dataclasses.replace(
|
|
61
|
+
rep,
|
|
62
|
+
aliases=tuple(dict.fromkeys(aliases)),
|
|
63
|
+
refs=tuple(sorted(dict.fromkeys(refs), key=lambda r: (r.doc_id, r.locator or ""))),
|
|
64
|
+
relations=tuple(sorted(dict.fromkeys(relations),
|
|
65
|
+
key=lambda r: (r.predicate, r.target_id))),
|
|
66
|
+
merged_from=tuple(dict.fromkeys(merged_from)),
|
|
67
|
+
)
|
|
68
|
+
)
|
|
69
|
+
return canonical
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
def build_indexes(
|
|
73
|
+
canonical: Sequence[Entity],
|
|
74
|
+
) -> tuple[dict[str, tuple[str, ...]], dict[str, tuple[str, ...]]]:
|
|
75
|
+
"""(exact, normalized) surface -> sorted canonical ids, from folded entities."""
|
|
76
|
+
exact: dict[str, list[str]] = {}
|
|
77
|
+
norm: dict[str, list[str]] = {}
|
|
78
|
+
for ent in canonical:
|
|
79
|
+
for surface in (ent.label, *ent.aliases):
|
|
80
|
+
exact.setdefault(surface, []).append(ent.canonical_id)
|
|
81
|
+
n = normalize(surface)
|
|
82
|
+
if n:
|
|
83
|
+
norm.setdefault(n, []).append(ent.canonical_id)
|
|
84
|
+
return (
|
|
85
|
+
{s: tuple(sorted(set(ids))) for s, ids in exact.items()},
|
|
86
|
+
{s: tuple(sorted(set(ids))) for s, ids in norm.items()},
|
|
87
|
+
)
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
"""Adapter protocols (OP-34, OP-35).
|
|
2
|
+
|
|
3
|
+
Structural typing (typing.Protocol) so any backend can implement these without
|
|
4
|
+
importing Cairn's adapters — keeping the core free of hard storage
|
|
5
|
+
dependencies. Concrete adapters (in-memory, JSON, SQLite, graph) are authored
|
|
6
|
+
per milestone. The protocols are fully typed against the entity model
|
|
7
|
+
(model.py has no adapter imports, so there is no cycle).
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
from typing import Protocol, runtime_checkable
|
|
13
|
+
|
|
14
|
+
from cairn_engine.entity.model import Entity, Ref, Relation, ResolvedEntity
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
@runtime_checkable
|
|
18
|
+
class AliasTableAdapter(Protocol):
|
|
19
|
+
"""Persistence + lookup for the canonical alias table (OP-35).
|
|
20
|
+
|
|
21
|
+
Default serialization by corpus size: in-memory/JSON (<500), SQLite
|
|
22
|
+
(500-50k), Parquet (50k+) — same interface throughout.
|
|
23
|
+
"""
|
|
24
|
+
|
|
25
|
+
def lookup(self, surface: str) -> list[ResolvedEntity]:
|
|
26
|
+
"""Return canonical matches for a surface form (empty list = unresolved)."""
|
|
27
|
+
...
|
|
28
|
+
|
|
29
|
+
def add(self, entity: Entity) -> None:
|
|
30
|
+
"""Add/stage an entity (build-time; staged for review before freezing)."""
|
|
31
|
+
...
|
|
32
|
+
|
|
33
|
+
def merge(self, source_id: str, target_id: str) -> None:
|
|
34
|
+
"""Union two canonical IDs (TH-1): the whole class folds into the
|
|
35
|
+
representative at freeze; records are never deleted."""
|
|
36
|
+
...
|
|
37
|
+
|
|
38
|
+
def normalized_entries(self) -> tuple[tuple[str, tuple[str, ...]], ...]:
|
|
39
|
+
"""The closed world as (normalized_alias, sorted canonical_ids) pairs,
|
|
40
|
+
sorted by alias — the gazetteer the scanner walks. Deterministic order."""
|
|
41
|
+
...
|
|
42
|
+
|
|
43
|
+
def has_id(self, canonical_id: str) -> bool:
|
|
44
|
+
"""True only for RESOLVABLE ids (class representatives) — exactly the
|
|
45
|
+
ids resolve() can return. Merged-away ids are NOT resolvable (use
|
|
46
|
+
has_record for audit-level existence). Closed-world membership oracle."""
|
|
47
|
+
...
|
|
48
|
+
|
|
49
|
+
def has_record(self, canonical_id: str) -> bool:
|
|
50
|
+
"""True for any record ever added, including merged-away ones (audit)."""
|
|
51
|
+
...
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
@runtime_checkable
|
|
55
|
+
class GraphAdapter(Protocol):
|
|
56
|
+
"""Edge/ref source for bounded traversal (OP-34).
|
|
57
|
+
|
|
58
|
+
The CORE owns the BFS algorithm; adapters only serve 1-hop out-edges and
|
|
59
|
+
node-anchored refs. That split keeps the core storage-agnostic — one
|
|
60
|
+
deterministic algorithm, N storage backends. (A backend may later execute
|
|
61
|
+
the same bounded intent in its own query language behind this API — OQ-3.)
|
|
62
|
+
"""
|
|
63
|
+
|
|
64
|
+
def edges(self, entity_id: str) -> tuple[Relation, ...]:
|
|
65
|
+
"""1-hop out-edges (with bitemporal validity) — deterministic order."""
|
|
66
|
+
...
|
|
67
|
+
|
|
68
|
+
def refs(self, entity_id: str) -> tuple[Ref, ...]:
|
|
69
|
+
"""DocumentRefs anchored to the node — deterministic order."""
|
|
70
|
+
...
|
|
71
|
+
|
|
72
|
+
def has_entity(self, entity_id: str) -> bool:
|
|
73
|
+
"""Closed world membership check."""
|
|
74
|
+
...
|
|
75
|
+
|
|
76
|
+
def edge_capable(self) -> bool:
|
|
77
|
+
"""False -> flat mode: traversal degrades to depth-0 refs (OP-34 fallback)."""
|
|
78
|
+
...
|
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
"""openCypher graph-backend adapter (M2.3, OQ-3 for openCypher).
|
|
2
|
+
|
|
3
|
+
`design_principle_no_query_language`: the agent never writes Cypher. Cairn owns
|
|
4
|
+
the bounded-traversal INTENT and compiles it — once, deterministically — into an
|
|
5
|
+
openCypher query; an external graph DB (Neo4j / FalkorDB / Neptune openCypher)
|
|
6
|
+
runs it. Cairn decides WHAT to traverse; the backend executes HOW.
|
|
7
|
+
|
|
8
|
+
`storage_agnostic_core` (SACRED): cairn imports NO database driver. The driver
|
|
9
|
+
enters as a caller-supplied callable `run(query, params) -> rows` — the same
|
|
10
|
+
callable boundary as EmbedderFn / ArbiterFn. This module only EMITS the query
|
|
11
|
+
and MAPS the rows; connecting is the caller's job.
|
|
12
|
+
|
|
13
|
+
Fixed graph schema this compiler targets:
|
|
14
|
+
(:Entity {id})-[edge {valid_from, valid_until, known_from, known_until,
|
|
15
|
+
predicate, weight}]->(:Entity)
|
|
16
|
+
(:Entity)-[:HAS_REF]->(:Ref {doc_id, locator})
|
|
17
|
+
|
|
18
|
+
The result of `traverse_cypher` is identical (same hits, order, scores) to the
|
|
19
|
+
in-memory `traverse` on the same graph — the closure semantics are the same,
|
|
20
|
+
only the executor changed.
|
|
21
|
+
"""
|
|
22
|
+
|
|
23
|
+
from __future__ import annotations
|
|
24
|
+
|
|
25
|
+
from dataclasses import dataclass, field
|
|
26
|
+
from typing import Callable, Iterable, Mapping
|
|
27
|
+
|
|
28
|
+
from cairn_engine.entity.model import Ref
|
|
29
|
+
from cairn_engine.entity.traverse import TraversalHit, TraversalResult
|
|
30
|
+
|
|
31
|
+
__all__ = ["CypherQuery", "CypherRunFn", "compile_traversal", "traverse_cypher"]
|
|
32
|
+
|
|
33
|
+
_MAX_DEPTH = 3
|
|
34
|
+
|
|
35
|
+
# The caller's DB driver boundary: run(query_text, params) -> iterable of rows,
|
|
36
|
+
# each row a mapping with keys entity_id, hop, doc_id, locator.
|
|
37
|
+
CypherRunFn = Callable[[str, Mapping[str, str]], Iterable[Mapping[str, object]]]
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
@dataclass(frozen=True, slots=True)
|
|
41
|
+
class CypherQuery:
|
|
42
|
+
"""A compiled, parametrized openCypher query — pure data, byte-stable."""
|
|
43
|
+
|
|
44
|
+
text: str
|
|
45
|
+
params: Mapping[str, str] = field(default_factory=dict)
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def compile_traversal(
|
|
49
|
+
canonical_id: str,
|
|
50
|
+
*,
|
|
51
|
+
depth: int = 2,
|
|
52
|
+
as_of: str | None = None,
|
|
53
|
+
known_as_of: str | None = None,
|
|
54
|
+
) -> CypherQuery:
|
|
55
|
+
"""Compile a bounded relation closure into one deterministic openCypher query.
|
|
56
|
+
|
|
57
|
+
Bounded variable-length path from the seed (hop 0) out to `depth`; both-axis
|
|
58
|
+
bitemporal edge filter (half-open, None = open) emitted ONLY for the axes
|
|
59
|
+
supplied; shortest hop per node; refs joined via OPTIONAL MATCH. `depth` is
|
|
60
|
+
inlined as a literal (openCypher forbids parametrized `*0..$d`); every user
|
|
61
|
+
string is a $param (injection-safe). Same args -> byte-identical output.
|
|
62
|
+
"""
|
|
63
|
+
if not 0 <= depth <= _MAX_DEPTH:
|
|
64
|
+
raise ValueError(
|
|
65
|
+
f"depth must be in 0..{_MAX_DEPTH} (bounded closure — see TH-4 / OP-34): got {depth}"
|
|
66
|
+
)
|
|
67
|
+
params: dict[str, str] = {"seed": canonical_id}
|
|
68
|
+
edge_predicates: list[str] = []
|
|
69
|
+
if as_of is not None:
|
|
70
|
+
params["as_of"] = as_of
|
|
71
|
+
edge_predicates.append(
|
|
72
|
+
"(r.valid_from IS NULL OR r.valid_from <= $as_of) "
|
|
73
|
+
"AND (r.valid_until IS NULL OR $as_of < r.valid_until)"
|
|
74
|
+
)
|
|
75
|
+
if known_as_of is not None:
|
|
76
|
+
params["known_as_of"] = known_as_of
|
|
77
|
+
edge_predicates.append(
|
|
78
|
+
"(r.known_from IS NULL OR r.known_from <= $known_as_of) "
|
|
79
|
+
"AND (r.known_until IS NULL OR $known_as_of < r.known_until)"
|
|
80
|
+
)
|
|
81
|
+
|
|
82
|
+
lines = [f"MATCH p = (seed:Entity {{id: $seed}})-[rels*0..{depth}]->(n:Entity)"]
|
|
83
|
+
if edge_predicates:
|
|
84
|
+
lines.append(f"WHERE all(r IN rels WHERE {' AND '.join(edge_predicates)})")
|
|
85
|
+
lines += [
|
|
86
|
+
"WITH n, min(length(p)) AS hop",
|
|
87
|
+
"OPTIONAL MATCH (n)-[:HAS_REF]->(ref:Ref)",
|
|
88
|
+
"RETURN n.id AS entity_id, hop, ref.doc_id AS doc_id, ref.locator AS locator",
|
|
89
|
+
"ORDER BY hop, entity_id, doc_id",
|
|
90
|
+
]
|
|
91
|
+
return CypherQuery(text="\n".join(lines), params=params)
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
def traverse_cypher(
|
|
95
|
+
canonical_id: str,
|
|
96
|
+
*,
|
|
97
|
+
run: CypherRunFn,
|
|
98
|
+
depth: int = 2,
|
|
99
|
+
as_of: str | None = None,
|
|
100
|
+
known_as_of: str | None = None,
|
|
101
|
+
) -> TraversalResult:
|
|
102
|
+
"""Compile, execute via the caller's `run`, and map rows to a TraversalResult.
|
|
103
|
+
|
|
104
|
+
Output is sorted (hop, entity_id, doc_id) and scored 1/(1+hop) — identical to
|
|
105
|
+
the in-memory `traverse`, regardless of the order the backend returned rows.
|
|
106
|
+
Ref-less rows (null doc_id) contribute no hit (closed world: no ref, no hit).
|
|
107
|
+
"""
|
|
108
|
+
query = compile_traversal(
|
|
109
|
+
canonical_id, depth=depth, as_of=as_of, known_as_of=known_as_of
|
|
110
|
+
)
|
|
111
|
+
hits: list[TraversalHit] = []
|
|
112
|
+
for row in run(query.text, query.params):
|
|
113
|
+
doc_id = row.get("doc_id")
|
|
114
|
+
if doc_id is None:
|
|
115
|
+
continue
|
|
116
|
+
hop = int(row["hop"]) # type: ignore[call-overload]
|
|
117
|
+
locator = row.get("locator")
|
|
118
|
+
hits.append(
|
|
119
|
+
TraversalHit(
|
|
120
|
+
ref=Ref(doc_id=str(doc_id), locator=None if locator is None else str(locator)),
|
|
121
|
+
entity_id=str(row["entity_id"]),
|
|
122
|
+
hop=hop,
|
|
123
|
+
score=1.0 / (1 + hop),
|
|
124
|
+
)
|
|
125
|
+
)
|
|
126
|
+
hits.sort(key=lambda h: (h.hop, h.entity_id, h.ref.doc_id))
|
|
127
|
+
return TraversalResult(tuple(hits), "graph")
|
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
"""Deterministic JSON serialization of the entity map (M1.3, OP-35 serialization).
|
|
2
|
+
|
|
3
|
+
JSON — not YAML — is the 0.1 format: the stdlib has no yaml module and PyYAML
|
|
4
|
+
would be the core's first hard dependency (zero-dep invariant beats format
|
|
5
|
+
preference; YAML lands later as an opt-in extra). Output is byte-stable:
|
|
6
|
+
sorted keys, fixed separators, entities ordered by canonical_id.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
import json
|
|
12
|
+
from typing import Any
|
|
13
|
+
|
|
14
|
+
from cairn_engine.entity.model import Entity, Ref, Relation
|
|
15
|
+
|
|
16
|
+
__all__ = ["dump_entities", "load_entities"]
|
|
17
|
+
|
|
18
|
+
_SCHEMA_VERSION = 1
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
def dump_entities(entities: tuple[Entity, ...] | list[Entity]) -> str:
|
|
22
|
+
"""Serialize to deterministic JSON (same entities -> same bytes, always).
|
|
23
|
+
|
|
24
|
+
`metadata` must contain JSON-native values only (str/int/float/bool/None,
|
|
25
|
+
lists, string-keyed dicts) — validated here so type-changing round-trips
|
|
26
|
+
(e.g. tuple -> list) fail loudly at dump time instead of corrupting silently.
|
|
27
|
+
"""
|
|
28
|
+
for e in entities:
|
|
29
|
+
_require_json_native(dict(e.metadata), f"{e.canonical_id}.metadata")
|
|
30
|
+
payload: dict[str, Any] = {
|
|
31
|
+
"schema_version": _SCHEMA_VERSION,
|
|
32
|
+
"entities": [_to_dict(e) for e in sorted(entities, key=lambda e: e.canonical_id)],
|
|
33
|
+
}
|
|
34
|
+
return json.dumps(payload, sort_keys=True, indent=2, separators=(",", ": ")) + "\n"
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def _require_json_native(value: Any, where: str) -> None:
|
|
38
|
+
if value is None or isinstance(value, (str, int, float, bool)):
|
|
39
|
+
return
|
|
40
|
+
if isinstance(value, list):
|
|
41
|
+
for i, item in enumerate(value):
|
|
42
|
+
_require_json_native(item, f"{where}[{i}]")
|
|
43
|
+
return
|
|
44
|
+
if isinstance(value, dict):
|
|
45
|
+
for k, v in value.items():
|
|
46
|
+
if not isinstance(k, str):
|
|
47
|
+
raise TypeError(f"non-string metadata key at {where}: {k!r}")
|
|
48
|
+
_require_json_native(v, f"{where}.{k}")
|
|
49
|
+
return
|
|
50
|
+
raise TypeError(
|
|
51
|
+
f"non-JSON-native metadata value at {where}: {type(value).__name__} "
|
|
52
|
+
"(allowed: str/int/float/bool/None, lists, string-keyed dicts)"
|
|
53
|
+
)
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def load_entities(text: str) -> tuple[Entity, ...]:
|
|
57
|
+
"""Inverse of dump_entities: load_entities(dump_entities(x)) == sorted(x)."""
|
|
58
|
+
payload = json.loads(text)
|
|
59
|
+
version = payload.get("schema_version")
|
|
60
|
+
if version != _SCHEMA_VERSION:
|
|
61
|
+
raise ValueError(f"unsupported schema_version: {version!r} (expected {_SCHEMA_VERSION})")
|
|
62
|
+
return tuple(_from_dict(d) for d in payload["entities"])
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
def _to_dict(e: Entity) -> dict[str, Any]:
|
|
66
|
+
return {
|
|
67
|
+
"canonical_id": e.canonical_id,
|
|
68
|
+
"label": e.label,
|
|
69
|
+
"entity_type": e.entity_type,
|
|
70
|
+
"aliases": list(e.aliases),
|
|
71
|
+
"valid_from": e.valid_from,
|
|
72
|
+
"valid_until": e.valid_until,
|
|
73
|
+
"known_from": e.known_from,
|
|
74
|
+
"known_until": e.known_until,
|
|
75
|
+
"source": e.source,
|
|
76
|
+
"description": e.description,
|
|
77
|
+
"merged_from": list(e.merged_from),
|
|
78
|
+
"refs": [{"doc_id": r.doc_id, "locator": r.locator} for r in e.refs],
|
|
79
|
+
"relations": [
|
|
80
|
+
{
|
|
81
|
+
"predicate": r.predicate,
|
|
82
|
+
"target_id": r.target_id,
|
|
83
|
+
"valid_from": r.valid_from,
|
|
84
|
+
"valid_until": r.valid_until,
|
|
85
|
+
"known_from": r.known_from,
|
|
86
|
+
"known_until": r.known_until,
|
|
87
|
+
"weight": r.weight,
|
|
88
|
+
}
|
|
89
|
+
for r in e.relations
|
|
90
|
+
],
|
|
91
|
+
"metadata": dict(e.metadata),
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
def _from_dict(d: dict[str, Any]) -> Entity:
|
|
96
|
+
return Entity(
|
|
97
|
+
canonical_id=d["canonical_id"],
|
|
98
|
+
label=d["label"],
|
|
99
|
+
entity_type=d["entity_type"],
|
|
100
|
+
aliases=tuple(d.get("aliases", ())),
|
|
101
|
+
valid_from=d.get("valid_from"),
|
|
102
|
+
valid_until=d.get("valid_until"),
|
|
103
|
+
known_from=d.get("known_from"),
|
|
104
|
+
known_until=d.get("known_until"),
|
|
105
|
+
source=d.get("source"),
|
|
106
|
+
description=d.get("description"),
|
|
107
|
+
merged_from=tuple(d.get("merged_from", ())),
|
|
108
|
+
refs=tuple(Ref(doc_id=r["doc_id"], locator=r.get("locator")) for r in d.get("refs", ())),
|
|
109
|
+
relations=tuple(
|
|
110
|
+
Relation(
|
|
111
|
+
predicate=r["predicate"],
|
|
112
|
+
target_id=r["target_id"],
|
|
113
|
+
valid_from=r.get("valid_from"),
|
|
114
|
+
valid_until=r.get("valid_until"),
|
|
115
|
+
known_from=r.get("known_from"),
|
|
116
|
+
known_until=r.get("known_until"),
|
|
117
|
+
weight=r.get("weight", 1.0),
|
|
118
|
+
)
|
|
119
|
+
for r in d.get("relations", ())
|
|
120
|
+
),
|
|
121
|
+
metadata=d.get("metadata", {}),
|
|
122
|
+
)
|