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