ihmt-memory 1.2.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.
- ihmt/__init__.py +134 -0
- ihmt/api.py +166 -0
- ihmt/chunkers/__init__.py +55 -0
- ihmt/chunkers/base.py +297 -0
- ihmt/chunkers/code.py +572 -0
- ihmt/chunkers/generic.py +19 -0
- ihmt/chunkers/narrative.py +142 -0
- ihmt/chunkers/process.py +79 -0
- ihmt/chunkers/temporal.py +187 -0
- ihmt/config.py +161 -0
- ihmt/conflict_resolver.py +468 -0
- ihmt/detectors.py +327 -0
- ihmt/models.py +566 -0
- ihmt/project_index.py +440 -0
- ihmt/recursive_summarizer.py +342 -0
- ihmt/semantic_navigator.py +847 -0
- ihmt/storage.py +589 -0
- ihmt/summarizers.py +264 -0
- ihmt/templates/memory-instructions.md +37 -0
- ihmt/textutils.py +273 -0
- ihmt/universal_ingestor.py +373 -0
- ihmt_launcher.py +54 -0
- ihmt_memory-1.2.0.dist-info/METADATA +609 -0
- ihmt_memory-1.2.0.dist-info/RECORD +28 -0
- ihmt_memory-1.2.0.dist-info/WHEEL +4 -0
- ihmt_memory-1.2.0.dist-info/entry_points.txt +2 -0
- ihmt_memory-1.2.0.dist-info/licenses/LICENSE +21 -0
- mcp_server.py +701 -0
|
@@ -0,0 +1,468 @@
|
|
|
1
|
+
"""Timeline management and contradiction handling.
|
|
2
|
+
|
|
3
|
+
Memory that only ever appends eventually contradicts itself: "I live in Madrid"
|
|
4
|
+
(2024) and "I live in Valencia" (2026) are both in the store, and a naive
|
|
5
|
+
retriever will happily serve either. IHMT resolves this with **recency
|
|
6
|
+
weighting** over a per-attribute timeline:
|
|
7
|
+
|
|
8
|
+
* every dated assertion is kept — nothing is deleted;
|
|
9
|
+
* the most recent value of a ``(subject, attribute)`` pair is ``ACTIVE``;
|
|
10
|
+
* every earlier value becomes ``HISTORICAL``, stamped with ``superseded_by``
|
|
11
|
+
and a ``valid_from``/``valid_to`` interval, so the past stays queryable;
|
|
12
|
+
* whenever a value changes, a transparent notice is produced for the user:
|
|
13
|
+
*"On 2024-03-01 you said ... but on 2026-05-10 you updated to ..."*.
|
|
14
|
+
|
|
15
|
+
Facts arrive either programmatically through :meth:`ConflictResolver.record_fact`
|
|
16
|
+
or by pattern extraction from leaves during ingestion.
|
|
17
|
+
"""
|
|
18
|
+
|
|
19
|
+
from __future__ import annotations
|
|
20
|
+
|
|
21
|
+
import re
|
|
22
|
+
from dataclasses import dataclass
|
|
23
|
+
from typing import Any, Callable, Dict, Iterable, List, Optional, Pattern, Sequence, Tuple
|
|
24
|
+
|
|
25
|
+
from .models import Contradiction, Fact, LeafStatus, MemoryLeaf, NodeNotFoundError
|
|
26
|
+
from .storage import MemoryStore
|
|
27
|
+
from .textutils import (
|
|
28
|
+
date_of,
|
|
29
|
+
normalize,
|
|
30
|
+
short_hash,
|
|
31
|
+
timestamp_sort_key,
|
|
32
|
+
truncate,
|
|
33
|
+
utc_now_iso,
|
|
34
|
+
)
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
@dataclass(frozen=True)
|
|
38
|
+
class FactPattern:
|
|
39
|
+
"""A regex rule that lifts a dated fact out of free text."""
|
|
40
|
+
|
|
41
|
+
attribute: str
|
|
42
|
+
pattern: Pattern[str]
|
|
43
|
+
subject: str = "user"
|
|
44
|
+
group: int = 1
|
|
45
|
+
|
|
46
|
+
def apply(self, text: str) -> List[str]:
|
|
47
|
+
"""Return every value this rule finds in ``text``."""
|
|
48
|
+
return [match.group(self.group).strip() for match in self.pattern.finditer(text) if match.group(self.group)]
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
#: Value-bearing tail of a sentence: stop at punctuation or a clause break.
|
|
52
|
+
_VALUE = r"([^.,;:\n!?]{2,80})"
|
|
53
|
+
|
|
54
|
+
#: Built-in extraction rules (English + Spanish). Extend via
|
|
55
|
+
#: :meth:`ConflictResolver.add_pattern` for a new domain.
|
|
56
|
+
DEFAULT_PATTERNS: Tuple[FactPattern, ...] = (
|
|
57
|
+
FactPattern("location", re.compile(rf"\b(?:vivo|resido|estoy viviendo)\s+en\s+{_VALUE}", re.IGNORECASE)),
|
|
58
|
+
FactPattern("location", re.compile(rf"\bme\s+(?:he\s+)?mudad[oa]\s+a\s+{_VALUE}", re.IGNORECASE)),
|
|
59
|
+
FactPattern("location", re.compile(rf"\bI\s+(?:now\s+)?live\s+in\s+{_VALUE}", re.IGNORECASE)),
|
|
60
|
+
FactPattern("location", re.compile(rf"\bI\s+moved\s+to\s+{_VALUE}", re.IGNORECASE)),
|
|
61
|
+
FactPattern("employer", re.compile(rf"\btrabajo\s+en\s+{_VALUE}", re.IGNORECASE)),
|
|
62
|
+
FactPattern("employer", re.compile(rf"\bI\s+work\s+(?:at|for)\s+{_VALUE}", re.IGNORECASE)),
|
|
63
|
+
FactPattern("stack", re.compile(rf"\b(?:mi|nuestro)\s+stack\s+(?:es|ser[aá])\s+{_VALUE}", re.IGNORECASE)),
|
|
64
|
+
FactPattern("stack", re.compile(rf"\b(?:our|my)\s+stack\s+is\s+{_VALUE}", re.IGNORECASE)),
|
|
65
|
+
FactPattern("stack", re.compile(rf"\bmigra(?:mos|do)\s+(?:el\s+backend\s+)?a\s+{_VALUE}", re.IGNORECASE)),
|
|
66
|
+
FactPattern("stack", re.compile(rf"\bwe\s+migrated\s+to\s+{_VALUE}", re.IGNORECASE)),
|
|
67
|
+
FactPattern("diagnosis", re.compile(rf"^\s*(?:diagn[oó]stico|diagnosis)\s*:\s*{_VALUE}", re.IGNORECASE | re.MULTILINE)),
|
|
68
|
+
FactPattern("treatment", re.compile(rf"^\s*(?:tratamiento|treatment)\s*:\s*{_VALUE}", re.IGNORECASE | re.MULTILINE)),
|
|
69
|
+
FactPattern("medication", re.compile(rf"^\s*(?:medicaci[oó]n|medication)\s*:\s*{_VALUE}", re.IGNORECASE | re.MULTILINE)),
|
|
70
|
+
)
|
|
71
|
+
|
|
72
|
+
#: Rule locating the subject of a clinical record.
|
|
73
|
+
PATIENT_RE = re.compile(r"^\s*(?:paciente|patient)\s*:\s*([^\n,;(]{2,60})", re.IGNORECASE | re.MULTILINE)
|
|
74
|
+
|
|
75
|
+
#: Attributes whose subject is the patient rather than the user.
|
|
76
|
+
CLINICAL_ATTRIBUTES = frozenset({"diagnosis", "treatment", "medication"})
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
class ConflictResolver:
|
|
80
|
+
"""Maintains the fact timeline and reports contradictions.
|
|
81
|
+
|
|
82
|
+
Also acts as the *Timeline Manager*: :meth:`state_at` answers "what was true
|
|
83
|
+
on this date?", while :meth:`active_state` answers "what is true now?".
|
|
84
|
+
"""
|
|
85
|
+
|
|
86
|
+
def __init__(
|
|
87
|
+
self,
|
|
88
|
+
store: MemoryStore,
|
|
89
|
+
*,
|
|
90
|
+
patterns: Optional[Sequence[FactPattern]] = None,
|
|
91
|
+
auto_flag_leaves: bool = True,
|
|
92
|
+
) -> None:
|
|
93
|
+
"""
|
|
94
|
+
Args:
|
|
95
|
+
store: Store whose ``state/facts.json`` is managed.
|
|
96
|
+
patterns: Extraction rules; defaults to :data:`DEFAULT_PATTERNS`.
|
|
97
|
+
auto_flag_leaves: Annotate a leaf's metadata when one of the facts
|
|
98
|
+
it sourced is superseded.
|
|
99
|
+
"""
|
|
100
|
+
self.store = store
|
|
101
|
+
self.patterns: List[FactPattern] = list(patterns if patterns is not None else DEFAULT_PATTERNS)
|
|
102
|
+
self.auto_flag_leaves = auto_flag_leaves
|
|
103
|
+
self._facts: Optional[List[Fact]] = None
|
|
104
|
+
|
|
105
|
+
# ---------------------------------------------------------- persistence
|
|
106
|
+
@property
|
|
107
|
+
def facts(self) -> List[Fact]:
|
|
108
|
+
"""Every fact on the timeline, lazily loaded."""
|
|
109
|
+
if self._facts is None:
|
|
110
|
+
if self.store.config.facts_path.exists():
|
|
111
|
+
payload = self.store.read_json(self.store.config.facts_path)
|
|
112
|
+
self._facts = [Fact.from_dict(item) for item in payload.get("facts", [])]
|
|
113
|
+
else:
|
|
114
|
+
self._facts = []
|
|
115
|
+
return self._facts
|
|
116
|
+
|
|
117
|
+
def save(self) -> None:
|
|
118
|
+
"""Persist the timeline atomically, ordered by key then date."""
|
|
119
|
+
ordered = sorted(self.facts, key=lambda f: (f.key, timestamp_sort_key(f.timestamp), f.fact_id))
|
|
120
|
+
self.store.write_json(
|
|
121
|
+
self.store.config.facts_path,
|
|
122
|
+
{"schema_version": 1, "updated_at": utc_now_iso(), "facts": [f.to_dict() for f in ordered]},
|
|
123
|
+
)
|
|
124
|
+
|
|
125
|
+
def reload(self) -> None:
|
|
126
|
+
"""Drop the cached timeline so the next read comes from disk.
|
|
127
|
+
|
|
128
|
+
Needed by long-lived processes that share a store with other writers.
|
|
129
|
+
"""
|
|
130
|
+
self._facts = None
|
|
131
|
+
|
|
132
|
+
def add_pattern(self, pattern: FactPattern) -> None:
|
|
133
|
+
"""Register an extra extraction rule (e.g. for a new domain)."""
|
|
134
|
+
self.patterns.append(pattern)
|
|
135
|
+
|
|
136
|
+
# -------------------------------------------------------------- recording
|
|
137
|
+
def record_fact(
|
|
138
|
+
self,
|
|
139
|
+
subject: str,
|
|
140
|
+
attribute: str,
|
|
141
|
+
value: str,
|
|
142
|
+
*,
|
|
143
|
+
timestamp: str,
|
|
144
|
+
source_leaf_id: Optional[str] = None,
|
|
145
|
+
domain: str = "general",
|
|
146
|
+
note: str = "",
|
|
147
|
+
) -> Fact:
|
|
148
|
+
"""Add an assertion to the timeline and re-apply recency weighting.
|
|
149
|
+
|
|
150
|
+
Args:
|
|
151
|
+
subject: Who/what the assertion is about (``"user"``, a patient...).
|
|
152
|
+
attribute: The attribute being asserted (``"location"``...).
|
|
153
|
+
value: The asserted value.
|
|
154
|
+
timestamp: When the assertion was made or was true (ISO-8601).
|
|
155
|
+
source_leaf_id: Leaf this came from, if any.
|
|
156
|
+
domain: Domain of the source material.
|
|
157
|
+
note: Free-form annotation.
|
|
158
|
+
|
|
159
|
+
Returns:
|
|
160
|
+
The stored :class:`~ihmt.models.Fact`, already resolved against the
|
|
161
|
+
rest of its timeline.
|
|
162
|
+
"""
|
|
163
|
+
fact = Fact(
|
|
164
|
+
subject=subject.strip() or "user",
|
|
165
|
+
attribute=attribute.strip(),
|
|
166
|
+
value=truncate(value.strip(), 120),
|
|
167
|
+
timestamp=timestamp or utc_now_iso(),
|
|
168
|
+
source_leaf_id=source_leaf_id,
|
|
169
|
+
domain=domain,
|
|
170
|
+
valid_from=timestamp or utc_now_iso(),
|
|
171
|
+
)
|
|
172
|
+
fact.fact_id = f"F-{short_hash(f'{fact.key}|{normalize(fact.value)}|{fact.timestamp}', 10)}"
|
|
173
|
+
|
|
174
|
+
existing = {f.fact_id for f in self.facts}
|
|
175
|
+
if fact.fact_id in existing:
|
|
176
|
+
# Re-ingesting the same material must not duplicate the timeline.
|
|
177
|
+
return next(f for f in self.facts if f.fact_id == fact.fact_id)
|
|
178
|
+
|
|
179
|
+
self.facts.append(fact)
|
|
180
|
+
self._resolve_key(fact.key)
|
|
181
|
+
self.save()
|
|
182
|
+
return fact
|
|
183
|
+
|
|
184
|
+
def extract_from_leaf(self, leaf: MemoryLeaf) -> List[Fact]:
|
|
185
|
+
"""Harvest dated facts from a leaf using the registered patterns.
|
|
186
|
+
|
|
187
|
+
The leaf's own timestamp dates every fact it yields, which is what makes
|
|
188
|
+
recency weighting reflect when something was true rather than when it
|
|
189
|
+
was ingested.
|
|
190
|
+
"""
|
|
191
|
+
patient = PATIENT_RE.search(leaf.content)
|
|
192
|
+
found: List[Fact] = []
|
|
193
|
+
for rule in self.patterns:
|
|
194
|
+
for value in rule.apply(leaf.content):
|
|
195
|
+
subject = rule.subject
|
|
196
|
+
if rule.attribute in CLINICAL_ATTRIBUTES:
|
|
197
|
+
subject = patient.group(1).strip() if patient else "patient"
|
|
198
|
+
found.append(
|
|
199
|
+
self.record_fact(
|
|
200
|
+
subject,
|
|
201
|
+
rule.attribute,
|
|
202
|
+
value,
|
|
203
|
+
timestamp=leaf.timestamp,
|
|
204
|
+
source_leaf_id=leaf.leaf_id,
|
|
205
|
+
domain=leaf.domain,
|
|
206
|
+
)
|
|
207
|
+
)
|
|
208
|
+
return found
|
|
209
|
+
|
|
210
|
+
# -------------------------------------------------------------- timelines
|
|
211
|
+
def _resolve_key(self, key: str) -> None:
|
|
212
|
+
"""Apply recency weighting to one ``(subject, attribute)`` timeline.
|
|
213
|
+
|
|
214
|
+
The newest assertion wins; everything older is demoted to
|
|
215
|
+
``HISTORICAL`` and given the interval during which it held.
|
|
216
|
+
"""
|
|
217
|
+
timeline = sorted(
|
|
218
|
+
(f for f in self.facts if f.key == key),
|
|
219
|
+
key=lambda f: (timestamp_sort_key(f.timestamp), f.fact_id),
|
|
220
|
+
)
|
|
221
|
+
if not timeline:
|
|
222
|
+
return
|
|
223
|
+
|
|
224
|
+
newest = timeline[-1]
|
|
225
|
+
for index, fact in enumerate(timeline):
|
|
226
|
+
if fact is newest:
|
|
227
|
+
fact.status = LeafStatus.ACTIVE
|
|
228
|
+
fact.superseded_by = None
|
|
229
|
+
fact.valid_to = None
|
|
230
|
+
else:
|
|
231
|
+
successor = timeline[index + 1]
|
|
232
|
+
was_active = fact.status is LeafStatus.ACTIVE
|
|
233
|
+
fact.status = LeafStatus.HISTORICAL
|
|
234
|
+
fact.superseded_by = successor.fact_id
|
|
235
|
+
fact.valid_to = successor.timestamp
|
|
236
|
+
if self.auto_flag_leaves and was_active and normalize(fact.value) != normalize(newest.value):
|
|
237
|
+
self._flag_leaf(fact, newest)
|
|
238
|
+
fact.valid_from = fact.valid_from or fact.timestamp
|
|
239
|
+
|
|
240
|
+
def _flag_leaf(self, old: Fact, new: Fact) -> None:
|
|
241
|
+
"""Annotate the source leaf of a superseded fact.
|
|
242
|
+
|
|
243
|
+
The leaf keeps ``status = ACTIVE``: what it says was true *on its own
|
|
244
|
+
date*, and that remains a valid answer to a historical question. What
|
|
245
|
+
changes is that it now carries the notice explaining it has been
|
|
246
|
+
superseded, so a retrieval of it can never silently read as current.
|
|
247
|
+
"""
|
|
248
|
+
if not old.source_leaf_id:
|
|
249
|
+
return
|
|
250
|
+
try:
|
|
251
|
+
leaf = self.store.load_leaf(old.source_leaf_id)
|
|
252
|
+
except NodeNotFoundError:
|
|
253
|
+
return
|
|
254
|
+
notices = list(leaf.extra.get("superseded_facts", []))
|
|
255
|
+
record = {
|
|
256
|
+
"attribute": old.attribute,
|
|
257
|
+
"old_value": old.value,
|
|
258
|
+
"new_value": new.value,
|
|
259
|
+
"superseded_at": new.timestamp,
|
|
260
|
+
"notice": Contradiction(old.subject, old.attribute, old, new).render_notice(),
|
|
261
|
+
}
|
|
262
|
+
if record not in notices:
|
|
263
|
+
notices.append(record)
|
|
264
|
+
leaf.extra["superseded_facts"] = notices
|
|
265
|
+
self.store.save_leaf(leaf)
|
|
266
|
+
|
|
267
|
+
def timeline(self, subject: str, attribute: str) -> List[Fact]:
|
|
268
|
+
"""Every value ``(subject, attribute)`` has held, oldest first."""
|
|
269
|
+
key = f"{normalize(subject)}::{normalize(attribute)}"
|
|
270
|
+
return sorted(
|
|
271
|
+
(f for f in self.facts if f.key == key),
|
|
272
|
+
key=lambda f: (timestamp_sort_key(f.timestamp), f.fact_id),
|
|
273
|
+
)
|
|
274
|
+
|
|
275
|
+
def active_state(self, subject: Optional[str] = None) -> Dict[str, Fact]:
|
|
276
|
+
"""Current value of every attribute, keyed by ``subject::attribute``."""
|
|
277
|
+
wanted = normalize(subject) if subject else None
|
|
278
|
+
return {
|
|
279
|
+
fact.key: fact
|
|
280
|
+
for fact in self.facts
|
|
281
|
+
if fact.status is LeafStatus.ACTIVE and (wanted is None or normalize(fact.subject) == wanted)
|
|
282
|
+
}
|
|
283
|
+
|
|
284
|
+
def state_at(self, when: str, subject: Optional[str] = None) -> Dict[str, Fact]:
|
|
285
|
+
"""What was true at ``when`` — the timeline query.
|
|
286
|
+
|
|
287
|
+
Args:
|
|
288
|
+
when: ISO-8601 instant or date.
|
|
289
|
+
subject: Restrict to one subject.
|
|
290
|
+
|
|
291
|
+
Returns:
|
|
292
|
+
The latest assertion of each attribute that was made at or before
|
|
293
|
+
``when``.
|
|
294
|
+
"""
|
|
295
|
+
cutoff = timestamp_sort_key(when)
|
|
296
|
+
wanted = normalize(subject) if subject else None
|
|
297
|
+
snapshot: Dict[str, Fact] = {}
|
|
298
|
+
for fact in sorted(self.facts, key=lambda f: timestamp_sort_key(f.timestamp)):
|
|
299
|
+
if timestamp_sort_key(fact.timestamp) > cutoff:
|
|
300
|
+
continue
|
|
301
|
+
if wanted is not None and normalize(fact.subject) != wanted:
|
|
302
|
+
continue
|
|
303
|
+
snapshot[fact.key] = fact
|
|
304
|
+
return snapshot
|
|
305
|
+
|
|
306
|
+
# ------------------------------------------------------------- conflicts
|
|
307
|
+
def detect_conflicts(self, *, subject: Optional[str] = None) -> List[Contradiction]:
|
|
308
|
+
"""Every attribute whose value has changed over time.
|
|
309
|
+
|
|
310
|
+
Only genuine changes are reported: repeating the same value at a later
|
|
311
|
+
date is a confirmation, not a contradiction.
|
|
312
|
+
"""
|
|
313
|
+
by_key: Dict[str, List[Fact]] = {}
|
|
314
|
+
for fact in self.facts:
|
|
315
|
+
if subject and normalize(fact.subject) != normalize(subject):
|
|
316
|
+
continue
|
|
317
|
+
by_key.setdefault(fact.key, []).append(fact)
|
|
318
|
+
|
|
319
|
+
conflicts: List[Contradiction] = []
|
|
320
|
+
for timeline in by_key.values():
|
|
321
|
+
ordered = sorted(timeline, key=lambda f: (timestamp_sort_key(f.timestamp), f.fact_id))
|
|
322
|
+
newest = ordered[-1]
|
|
323
|
+
previous = next(
|
|
324
|
+
(f for f in reversed(ordered[:-1]) if normalize(f.value) != normalize(newest.value)),
|
|
325
|
+
None,
|
|
326
|
+
)
|
|
327
|
+
if previous is not None:
|
|
328
|
+
conflicts.append(
|
|
329
|
+
Contradiction(subject=newest.subject, attribute=newest.attribute, old=previous, new=newest)
|
|
330
|
+
)
|
|
331
|
+
return sorted(conflicts, key=lambda c: (c.subject, c.attribute))
|
|
332
|
+
|
|
333
|
+
def notices_for_leaf(self, leaf: MemoryLeaf) -> List[str]:
|
|
334
|
+
"""Transparency notices attached to a retrieved leaf.
|
|
335
|
+
|
|
336
|
+
Returned by the navigator alongside the leaf, so an answer built on
|
|
337
|
+
outdated material always arrives with its correction.
|
|
338
|
+
"""
|
|
339
|
+
notices: List[str] = []
|
|
340
|
+
covered = set()
|
|
341
|
+
for fact in self.facts:
|
|
342
|
+
if fact.source_leaf_id != leaf.leaf_id or fact.status is not LeafStatus.HISTORICAL:
|
|
343
|
+
continue
|
|
344
|
+
current = self.active_state().get(fact.key)
|
|
345
|
+
if current is None or normalize(current.value) == normalize(fact.value):
|
|
346
|
+
continue
|
|
347
|
+
notice = Contradiction(fact.subject, fact.attribute, fact, current).render_notice()
|
|
348
|
+
covered.add((fact.attribute, normalize(fact.value)))
|
|
349
|
+
if notice not in notices:
|
|
350
|
+
notices.append(notice)
|
|
351
|
+
# A correction saved explicitly over this leaf (``supersede_leaf``).
|
|
352
|
+
for item in leaf.extra.get("superseded_by", []):
|
|
353
|
+
notice = str(item.get("notice", ""))
|
|
354
|
+
if notice and notice not in notices:
|
|
355
|
+
notices.append(notice)
|
|
356
|
+
# Notices stamped on the leaf when it was superseded. One already
|
|
357
|
+
# rendered from the live timeline above wins, so a leaf flagged by an
|
|
358
|
+
# older release (with older wording) does not show the change twice.
|
|
359
|
+
for item in leaf.extra.get("superseded_facts", []):
|
|
360
|
+
notice = str(item.get("notice", ""))
|
|
361
|
+
key = (str(item.get("attribute", "")), normalize(str(item.get("old_value", ""))))
|
|
362
|
+
if notice and key not in covered and notice not in notices:
|
|
363
|
+
notices.append(notice)
|
|
364
|
+
return notices
|
|
365
|
+
|
|
366
|
+
# ------------------------------------------------------- leaf succession
|
|
367
|
+
def successors_of(self, leaf: MemoryLeaf) -> List[str]:
|
|
368
|
+
"""Ids of the leaves that supersede ``leaf``, oldest first.
|
|
369
|
+
|
|
370
|
+
Two sources: a fact this leaf asserted whose current value comes from
|
|
371
|
+
another leaf, and an explicit correction recorded by
|
|
372
|
+
:meth:`supersede_leaf`.
|
|
373
|
+
"""
|
|
374
|
+
found: List[str] = []
|
|
375
|
+
active = self.active_state()
|
|
376
|
+
for fact in self.facts:
|
|
377
|
+
if fact.source_leaf_id != leaf.leaf_id or fact.status is not LeafStatus.HISTORICAL:
|
|
378
|
+
continue
|
|
379
|
+
current = active.get(fact.key)
|
|
380
|
+
if (
|
|
381
|
+
current is not None
|
|
382
|
+
and current.source_leaf_id
|
|
383
|
+
and current.source_leaf_id != leaf.leaf_id
|
|
384
|
+
and normalize(current.value) != normalize(fact.value)
|
|
385
|
+
):
|
|
386
|
+
found.append(current.source_leaf_id)
|
|
387
|
+
for item in leaf.extra.get("superseded_by", []):
|
|
388
|
+
if item.get("leaf_id"):
|
|
389
|
+
found.append(str(item["leaf_id"]))
|
|
390
|
+
return list(dict.fromkeys(found))
|
|
391
|
+
|
|
392
|
+
def supersede_leaf(self, old_leaf_id: str, new_leaf_id: str) -> str:
|
|
393
|
+
"""Record that ``new_leaf_id`` corrects ``old_leaf_id``; return the notice.
|
|
394
|
+
|
|
395
|
+
For changes no extraction pattern can see ("version 1.3" became "1.2",
|
|
396
|
+
a decision reversed). Like a superseded fact, the old leaf keeps its
|
|
397
|
+
ACTIVE status and its content; it gains a notice, so retrieving it can
|
|
398
|
+
never read as current, and the navigator puts the correction first.
|
|
399
|
+
|
|
400
|
+
Raises:
|
|
401
|
+
NodeNotFoundError: If either leaf does not exist.
|
|
402
|
+
ValueError: If both ids are the same leaf.
|
|
403
|
+
"""
|
|
404
|
+
if old_leaf_id == new_leaf_id:
|
|
405
|
+
raise ValueError("a memory cannot supersede itself")
|
|
406
|
+
old = self.store.load_leaf(old_leaf_id)
|
|
407
|
+
new = self.store.load_leaf(new_leaf_id)
|
|
408
|
+
notice = (
|
|
409
|
+
f"On {date_of(old.timestamp)} this was saved: '{_gist(old.content)}', "
|
|
410
|
+
f"but on {date_of(new.timestamp)} it was corrected: '{_gist(new.content)}'."
|
|
411
|
+
)
|
|
412
|
+
records = list(old.extra.get("superseded_by", []))
|
|
413
|
+
if not any(r.get("leaf_id") == new_leaf_id for r in records):
|
|
414
|
+
records.append({"leaf_id": new_leaf_id, "superseded_at": new.timestamp, "notice": notice})
|
|
415
|
+
old.extra["superseded_by"] = records
|
|
416
|
+
self.store.save_leaf(old)
|
|
417
|
+
supersedes = list(new.extra.get("supersedes", []))
|
|
418
|
+
if old_leaf_id not in supersedes:
|
|
419
|
+
new.extra["supersedes"] = supersedes + [old_leaf_id]
|
|
420
|
+
self.store.save_leaf(new)
|
|
421
|
+
return notice
|
|
422
|
+
|
|
423
|
+
def report(self, *, subject: Optional[str] = None) -> Dict[str, Any]:
|
|
424
|
+
"""Machine-readable snapshot of state, history and contradictions."""
|
|
425
|
+
conflicts = self.detect_conflicts(subject=subject)
|
|
426
|
+
return {
|
|
427
|
+
"active_state": {k: v.to_dict() for k, v in sorted(self.active_state(subject).items())},
|
|
428
|
+
"conflicts": [c.to_dict() for c in conflicts],
|
|
429
|
+
"notices": [c.render_notice() for c in conflicts],
|
|
430
|
+
"fact_count": len(self.facts),
|
|
431
|
+
}
|
|
432
|
+
|
|
433
|
+
def rebuild(self) -> int:
|
|
434
|
+
"""Re-extract every fact from every leaf on disk.
|
|
435
|
+
|
|
436
|
+
Use after editing extraction rules or restoring leaves from a backup.
|
|
437
|
+
|
|
438
|
+
Returns:
|
|
439
|
+
The number of facts on the timeline afterwards.
|
|
440
|
+
"""
|
|
441
|
+
self._facts = []
|
|
442
|
+
self.save()
|
|
443
|
+
for leaf in self.store.iter_leaves():
|
|
444
|
+
self.extract_from_leaf(leaf)
|
|
445
|
+
return len(self.facts)
|
|
446
|
+
|
|
447
|
+
|
|
448
|
+
_LEADING_DATE_PREFIX = re.compile(r"^\s*\d{4}-\d{1,2}-\d{1,2}(?:\s*\([^)]*\))?\s*[:\-–—]?\s*")
|
|
449
|
+
|
|
450
|
+
|
|
451
|
+
def _gist(content: str, limit: int = 90) -> str:
|
|
452
|
+
"""First line of a memory without its leading date, shortened."""
|
|
453
|
+
first = content.strip().splitlines()[0] if content.strip() else ""
|
|
454
|
+
return truncate(_LEADING_DATE_PREFIX.sub("", first).rstrip(" ."), limit).replace("'", "’")
|
|
455
|
+
|
|
456
|
+
|
|
457
|
+
def summarize_notices(conflicts: Iterable[Contradiction], formatter: Optional[Callable[[Contradiction], str]] = None) -> List[str]:
|
|
458
|
+
"""Render a list of contradictions as user-facing notices."""
|
|
459
|
+
render = formatter or (lambda c: c.render_notice())
|
|
460
|
+
return [render(conflict) for conflict in conflicts]
|
|
461
|
+
|
|
462
|
+
|
|
463
|
+
__all__ = [
|
|
464
|
+
"ConflictResolver",
|
|
465
|
+
"FactPattern",
|
|
466
|
+
"DEFAULT_PATTERNS",
|
|
467
|
+
"summarize_notices",
|
|
468
|
+
]
|