AbstractMemory 0.3.2__py3-none-any.whl → 0.4.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.
- abstractmemory/__init__.py +16 -0
- abstractmemory/graph/__init__.py +60 -0
- abstractmemory/graph/backend.py +117 -0
- abstractmemory/graph/graph.py +1363 -0
- abstractmemory/graph/lancedb_backend.py +580 -0
- abstractmemory/graph/provenance.py +323 -0
- abstractmemory/graph/revisions.py +239 -0
- abstractmemory/in_memory_store.py +84 -21
- abstractmemory/journal.py +5 -4
- abstractmemory/journal_sqlite.py +46 -20
- abstractmemory/journal_sqlite_rows.py +4 -1
- abstractmemory/lancedb_store.py +5 -0
- abstractmemory/sleep_cadence.py +240 -24
- abstractmemory/sqlite_store.py +493 -56
- abstractmemory/store_tuning.py +71 -0
- abstractmemory/vector_matrix.py +434 -0
- {abstractmemory-0.3.2.dist-info → abstractmemory-0.4.0.dist-info}/METADATA +20 -3
- {abstractmemory-0.3.2.dist-info → abstractmemory-0.4.0.dist-info}/RECORD +20 -12
- {abstractmemory-0.3.2.dist-info → abstractmemory-0.4.0.dist-info}/WHEEL +0 -0
- {abstractmemory-0.3.2.dist-info → abstractmemory-0.4.0.dist-info}/licenses/LICENSE +0 -0
abstractmemory/__init__.py
CHANGED
|
@@ -168,6 +168,15 @@ from .spreading import SpreadParams
|
|
|
168
168
|
from .sqlite_store import SQLiteTripleStore, read_embedding_pin
|
|
169
169
|
from .store import TripleQuery, TripleStore
|
|
170
170
|
from .system import MemorySystem
|
|
171
|
+
from .graph import (
|
|
172
|
+
InvalidSourceRef,
|
|
173
|
+
MemoryGraph,
|
|
174
|
+
Provenance,
|
|
175
|
+
ProvenanceRequired,
|
|
176
|
+
Revision,
|
|
177
|
+
RevisionOp,
|
|
178
|
+
SourceRef,
|
|
179
|
+
)
|
|
171
180
|
|
|
172
181
|
__all__ = [
|
|
173
182
|
"ALIAS_OVERLAP_FLOOR",
|
|
@@ -205,12 +214,14 @@ __all__ = [
|
|
|
205
214
|
"IDENTITY_SCOPE_PENDING_RULING",
|
|
206
215
|
"InMemoryJournal",
|
|
207
216
|
"InMemoryTripleStore",
|
|
217
|
+
"InvalidSourceRef",
|
|
208
218
|
"KIND_RANKS",
|
|
209
219
|
"LanceDBTripleStore",
|
|
210
220
|
"MANIFEST_VERSION",
|
|
211
221
|
"MECHANICAL_DIGEST_METHODS",
|
|
212
222
|
"MEMORY_RECORD_KINDS",
|
|
213
223
|
"MemoryEvent",
|
|
224
|
+
"MemoryGraph",
|
|
214
225
|
"MemoryHandle",
|
|
215
226
|
"MemoryJournal",
|
|
216
227
|
"MemoryRecordInput",
|
|
@@ -222,6 +233,8 @@ __all__ = [
|
|
|
222
233
|
"ProbeBudget",
|
|
223
234
|
"ProbeHit",
|
|
224
235
|
"ProbeResult",
|
|
236
|
+
"Provenance",
|
|
237
|
+
"ProvenanceRequired",
|
|
225
238
|
"RECENT_RECORDS_DEFAULT_LIMIT",
|
|
226
239
|
"REDIGESTION_PROTECTED_KINDS",
|
|
227
240
|
"REFLECTION_FORM_KINDS",
|
|
@@ -230,6 +243,8 @@ __all__ = [
|
|
|
230
243
|
"ReconstructionResult",
|
|
231
244
|
"ReconstructionTrace",
|
|
232
245
|
"RedigestionCandidate",
|
|
246
|
+
"Revision",
|
|
247
|
+
"RevisionOp",
|
|
233
248
|
"SELF_FRACTION_FLOOR",
|
|
234
249
|
"SHARED_VULNERABILITY_STATEMENT",
|
|
235
250
|
"SQLiteJournal",
|
|
@@ -237,6 +252,7 @@ __all__ = [
|
|
|
237
252
|
"ScopeBinding",
|
|
238
253
|
"SituateBudget",
|
|
239
254
|
"SleepTuning",
|
|
255
|
+
"SourceRef",
|
|
240
256
|
"SpreadParams",
|
|
241
257
|
"Stimulus",
|
|
242
258
|
"TextEmbedder",
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
"""abstractmemory.graph: the one write path of a mind (ADR 0003).
|
|
2
|
+
|
|
3
|
+
Typed ledger provenance (`SourceRef`, `Provenance`), the revision as the unit of change (`Revision`, `RevisionOp`),
|
|
4
|
+
and `MemoryGraph`: atomic, idempotent revision apply with mandatory grounded provenance, plus the reads `history`,
|
|
5
|
+
`sources_of`, `derived_from_source`, the lossless change feed `revisions(after=)` and `replay_into`.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from .backend import GraphBackend, GraphTx, backend_for, register_backend, registered_backends
|
|
9
|
+
from .graph import (
|
|
10
|
+
ADOPTING_CAUSES,
|
|
11
|
+
DEFAULT_READ_LIMIT,
|
|
12
|
+
DEFAULT_REVISION_PAGE,
|
|
13
|
+
DIGEST_PREDICATE,
|
|
14
|
+
MAX_LINEAGE_VISITS,
|
|
15
|
+
MAX_READ_LIMIT,
|
|
16
|
+
MemoryGraph,
|
|
17
|
+
)
|
|
18
|
+
from .provenance import (
|
|
19
|
+
LEGACY_KEYS,
|
|
20
|
+
PROVENANCE_KEYS,
|
|
21
|
+
SOURCE_KINDS,
|
|
22
|
+
SYNTHETIC_RUN_ID_PREFIXES,
|
|
23
|
+
InvalidSourceRef,
|
|
24
|
+
Provenance,
|
|
25
|
+
ProvenanceRequired,
|
|
26
|
+
SourceRef,
|
|
27
|
+
is_synthetic_run_id,
|
|
28
|
+
)
|
|
29
|
+
from . import lancedb_backend # noqa: F401 registers the LanceDB connector (lancedb itself is imported lazily)
|
|
30
|
+
from .revisions import CLOSE_KINDS, REVISION_CAUSES, REVISION_OPS, Revision, RevisionOp, RevisionResult
|
|
31
|
+
|
|
32
|
+
__all__ = [
|
|
33
|
+
"GraphBackend",
|
|
34
|
+
"GraphTx",
|
|
35
|
+
"backend_for",
|
|
36
|
+
"register_backend",
|
|
37
|
+
"registered_backends",
|
|
38
|
+
"ADOPTING_CAUSES",
|
|
39
|
+
"CLOSE_KINDS",
|
|
40
|
+
"DEFAULT_READ_LIMIT",
|
|
41
|
+
"DEFAULT_REVISION_PAGE",
|
|
42
|
+
"DIGEST_PREDICATE",
|
|
43
|
+
"LEGACY_KEYS",
|
|
44
|
+
"MAX_LINEAGE_VISITS",
|
|
45
|
+
"MAX_READ_LIMIT",
|
|
46
|
+
"PROVENANCE_KEYS",
|
|
47
|
+
"REVISION_CAUSES",
|
|
48
|
+
"REVISION_OPS",
|
|
49
|
+
"SOURCE_KINDS",
|
|
50
|
+
"SYNTHETIC_RUN_ID_PREFIXES",
|
|
51
|
+
"InvalidSourceRef",
|
|
52
|
+
"MemoryGraph",
|
|
53
|
+
"Provenance",
|
|
54
|
+
"ProvenanceRequired",
|
|
55
|
+
"Revision",
|
|
56
|
+
"RevisionOp",
|
|
57
|
+
"RevisionResult",
|
|
58
|
+
"SourceRef",
|
|
59
|
+
"is_synthetic_run_id",
|
|
60
|
+
]
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
"""The connector contract of a mind (ADR 0003 decision 3): `MemoryGraph` is the ONLY manipulation surface of a mind;
|
|
2
|
+
every store is a CONNECTOR behind it that implements the operations below and keeps their invariants. Changing the
|
|
3
|
+
database of a mind means writing a connector, never touching `MemoryGraph` or its callers.
|
|
4
|
+
|
|
5
|
+
A connector is a `GraphBackend` (what the graph reads and how it opens a transaction) whose `transaction()` yields a
|
|
6
|
+
`GraphTx` (what one revision reads and writes while it applies). `MemoryGraph(store, journal)` picks the connector
|
|
7
|
+
registered for the store's class (`register_backend`). The conformance suite every connector must pass is
|
|
8
|
+
`tests/test_graph_conformance.py`; a connector that cannot keep an invariant marks that case `xfail(strict=True)`
|
|
9
|
+
there with the reason, and the ADR lists it.
|
|
10
|
+
|
|
11
|
+
INVARIANTS a connector keeps:
|
|
12
|
+
- ATOMICITY: the writes of one `transaction()` become visible together or not at all; an exception inside the
|
|
13
|
+
`with` block leaves nothing behind (no triple, window change, history, provenance, derivation or revision row).
|
|
14
|
+
- ORDER: `insert_revision` allocates `seq` = the previous head + 1 inside the transaction, and transactions of one
|
|
15
|
+
mind are serialized, so commit order is seq order (the change feed is lossless).
|
|
16
|
+
- IDENTITY: an assertion id is written once (`insert_assertions` skips ids already stored); a (memory, ref key)
|
|
17
|
+
provenance row and a (memory, parent) derivation row are written once, the first one winning.
|
|
18
|
+
- READS ARE BOUNDED: every read that returns rows takes a `limit` (or is bounded by one revision's ops).
|
|
19
|
+
- OPENING IS A READ: constructing a connector over an up-to-date mind writes nothing.
|
|
20
|
+
"""
|
|
21
|
+
|
|
22
|
+
from __future__ import annotations
|
|
23
|
+
|
|
24
|
+
from typing import (TYPE_CHECKING, Any, Callable, ContextManager, Dict, Iterable, List, Optional, Protocol,
|
|
25
|
+
Sequence, Tuple, Type, runtime_checkable)
|
|
26
|
+
|
|
27
|
+
if TYPE_CHECKING: # pragma: no cover
|
|
28
|
+
from ..journal import ClosureRecord
|
|
29
|
+
from ..models import TripleAssertion
|
|
30
|
+
from .provenance import SourceRef
|
|
31
|
+
from .revisions import Revision
|
|
32
|
+
|
|
33
|
+
Window = Tuple[Optional[str], Optional[str]] # (valid_from, valid_until)
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
@runtime_checkable
|
|
37
|
+
class GraphTx(Protocol):
|
|
38
|
+
"""One revision's reads and writes, inside one atomic transaction of the connector."""
|
|
39
|
+
|
|
40
|
+
# -- reads (they see this transaction's own earlier writes) --
|
|
41
|
+
def revision_seq(self, rid: str) -> Optional[int]: ...
|
|
42
|
+
def memory_known(self, mid: str) -> bool: ... # asserted through the graph (a history 'asserted' event)
|
|
43
|
+
def closing_revision(self, mid: str) -> Optional[str]: ...
|
|
44
|
+
def open_same_claim(self, a: "TripleAssertion") -> Optional[str]: ... # a held OPEN memory with a's identity
|
|
45
|
+
def digest_assertion_for(self, graph_id: str) -> Optional[str]: ...
|
|
46
|
+
def existing_ids(self, ids: Sequence[str]) -> set: ...
|
|
47
|
+
def stored(self, aid: str) -> "TripleAssertion": ...
|
|
48
|
+
def window(self, aid: str) -> Optional[Window]: ...
|
|
49
|
+
|
|
50
|
+
# -- writes --
|
|
51
|
+
def write_pin(self, pin: Optional[Dict[str, Any]]) -> None: ...
|
|
52
|
+
def insert_assertions(self, rows: List[Any]) -> None: ... # rows from GraphBackend.prepare_rows
|
|
53
|
+
def set_provenance(self, aid: str, provenance: Dict[str, Any]) -> None: ...
|
|
54
|
+
def end_row(self, aid: str, until: str) -> bool: ...
|
|
55
|
+
def narrow_row(self, aid: str, until: str) -> bool: ... # narrow_assertion semantics (ValueError on open)
|
|
56
|
+
def write_closure(self, closure: "ClosureRecord") -> bool: ... # True when it rides this transaction
|
|
57
|
+
def add_history(self, mid: str, event: str, at: str, rid: str, detail: Dict[str, Any]) -> None: ...
|
|
58
|
+
def add_source(self, mid: str, ref: "SourceRef", rid: str, owner: Optional[str], via: str = ...) -> None: ...
|
|
59
|
+
def add_derivation(self, mid: str, from_id: str, rid: str) -> None: ...
|
|
60
|
+
def insert_revision(self, rev: "Revision", journal_applied: bool) -> int: ...
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
@runtime_checkable
|
|
64
|
+
class GraphBackend(Protocol):
|
|
65
|
+
"""A mind's connector: transactions plus the bounded reads `MemoryGraph` serves."""
|
|
66
|
+
|
|
67
|
+
def prepare_rows(self, assertions: List["TripleAssertion"]) -> Tuple[List[Any], Optional[Dict[str, Any]], bool]:
|
|
68
|
+
"""Embed and shape rows BEFORE the transaction: (rows, embedding pin to write in it or None, first-write)."""
|
|
69
|
+
...
|
|
70
|
+
|
|
71
|
+
def transaction(self) -> ContextManager[GraphTx]: ...
|
|
72
|
+
|
|
73
|
+
# -- reads --
|
|
74
|
+
def applied_seq(self, rid: str) -> Optional[int]: ...
|
|
75
|
+
def resolve(self, mid: str) -> Optional[str]: ...
|
|
76
|
+
def history(self, mid: str, limit: int) -> List[Dict[str, Any]]: ...
|
|
77
|
+
def sources(self, mid: str, limit: int) -> List[Tuple["SourceRef", str, str]]: ... # (ref, via, revision id)
|
|
78
|
+
def parents(self, mid: str, limit: int) -> List[str]: ...
|
|
79
|
+
def children(self, fid: str, limit: int) -> List[str]: ...
|
|
80
|
+
def with_ref(self, ref: "SourceRef", limit: int) -> List[str]: ...
|
|
81
|
+
def names_ref(self, ref: "SourceRef", owners: List[str]) -> bool: ...
|
|
82
|
+
def revisions_page(self, after: int, limit: int) -> List[Tuple[int, "Revision"]]: ...
|
|
83
|
+
def log_head(self) -> int: ...
|
|
84
|
+
def logged_outcome(self, rid: str) -> Tuple[Optional[str], List[Tuple[str, str]]]: ...
|
|
85
|
+
|
|
86
|
+
# -- off-transaction journal and crash repair --
|
|
87
|
+
def pending_journal(self, limit: int) -> List["Revision"]: ...
|
|
88
|
+
def closed_payload(self, aid: str, rid: str) -> Optional[Dict[str, Any]]: ...
|
|
89
|
+
def mark_journal_applied(self, rid: str) -> None: ...
|
|
90
|
+
def repair_projections(self) -> int:
|
|
91
|
+
"""Finish revisions a crash left half-projected (a connector without cross-table transactions writes its
|
|
92
|
+
log first); 0 for a connector whose transactions are atomic."""
|
|
93
|
+
...
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
BackendFactory = Callable[[Any, Any], GraphBackend]
|
|
97
|
+
_REGISTRY: List[Tuple[Type[Any], BackendFactory]] = []
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
def register_backend(store_class: Type[Any], factory: BackendFactory) -> None:
|
|
101
|
+
"""Make `MemoryGraph(store, journal)` use `factory(store, journal)` for stores of `store_class` (the most
|
|
102
|
+
recently registered matching class wins)."""
|
|
103
|
+
_REGISTRY.insert(0, (store_class, factory))
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
def backend_for(store: Any, journal: Any) -> GraphBackend:
|
|
107
|
+
for store_class, factory in _REGISTRY:
|
|
108
|
+
if isinstance(store, store_class):
|
|
109
|
+
return factory(store, journal)
|
|
110
|
+
raise NotImplementedError(
|
|
111
|
+
f"MemoryGraph: no connector is registered for {type(store).__name__} "
|
|
112
|
+
f"(registered: {[c.__name__ for c, _ in _REGISTRY]}); see abstractmemory.graph.backend"
|
|
113
|
+
)
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
def registered_backends() -> List[Type[Any]]:
|
|
117
|
+
return [c for c, _ in _REGISTRY]
|