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.
@@ -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
+ )