agentic-composite-memory 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,1214 @@
1
+ from __future__ import annotations
2
+
3
+ import asyncio
4
+ import logging
5
+ import uuid
6
+ from dataclasses import dataclass, field
7
+ from typing import Any, Sequence
8
+
9
+ # Graceful import fallback when running outside a Google ADK environment
10
+ try:
11
+ from google.adk.events.event import Event
12
+ from google.adk.memory.base_memory_service import (
13
+ BaseMemoryService,
14
+ SearchMemoryResponse,
15
+ )
16
+ from google.adk.memory.memory_entry import MemoryEntry
17
+ from google.adk.sessions.session import Session
18
+ from google.genai import types
19
+
20
+ HAS_ADK = True
21
+ except ImportError:
22
+ HAS_ADK = False
23
+
24
+ @dataclass
25
+ class _Part:
26
+ text: str | None = None
27
+
28
+ @classmethod
29
+ def from_text(cls, *, text: str) -> "_Part":
30
+ return cls(text=text)
31
+
32
+ @dataclass
33
+ class _Content:
34
+ role: str = "user"
35
+ parts: list[_Part] = field(default_factory=list)
36
+
37
+ class _TypesNamespace:
38
+ Part = _Part
39
+ Content = _Content
40
+
41
+ types = _TypesNamespace() # type: ignore
42
+
43
+ @dataclass
44
+ class Event: # type: ignore
45
+ author: str = "user"
46
+ content: Any = None
47
+
48
+ @dataclass
49
+ class MemoryEntry: # type: ignore
50
+ content: Any
51
+ author: str | None = None
52
+ timestamp: str | None = None
53
+
54
+ @dataclass
55
+ class SearchMemoryResponse: # type: ignore
56
+ memories: list[MemoryEntry] = field(default_factory=list)
57
+
58
+ @dataclass
59
+ class Session: # type: ignore
60
+ id: str
61
+ app_name: str
62
+ user_id: str
63
+ events: list[Event] = field(default_factory=list)
64
+
65
+ class BaseMemoryService: # type: ignore
66
+ pass
67
+
68
+
69
+ from .adapters.redis_playbook import RedisPlaybookAndWorkingAdapter
70
+ from .governance import (
71
+ AsyncCircuitBreaker,
72
+ PIIScrubber,
73
+ PlatformOntologyRegistrar,
74
+ SmartMemoryClassifier,
75
+ TBoxRuntimeValidator,
76
+ TenantRateLimiter,
77
+ TokenBudgetSerializer,
78
+ )
79
+ from .models import (
80
+ EpisodicRecord,
81
+ ExtractionMode,
82
+ GraphEdgeMutation,
83
+ GraphFactReadResult,
84
+ GraphVertexUpsert,
85
+ OntologyAuditLogEntry,
86
+ OutboxOperation,
87
+ PlatformTenantContext,
88
+ PlaybookRecord,
89
+ ReasoningTraceStep,
90
+ RelationRule,
91
+ )
92
+ from .ports import (
93
+ EmbeddingAdapter,
94
+ EpisodicAndSeedStoreAdapter,
95
+ GraphStoreAdapter,
96
+ OntologyExtractorAdapter,
97
+ PlaybookStoreAdapter,
98
+ RegistryStoreAdapter,
99
+ )
100
+
101
+ logger = logging.getLogger(__name__)
102
+
103
+
104
+ class CompositeMemoryService(BaseMemoryService):
105
+ """
106
+ Domain-Agnostic, Multi-Tenant Google ADK `BaseMemoryService` Implementation.
107
+ Unifies:
108
+ - Tier 1: Immutable Episodic Memory
109
+ - Tier 2: Stratified Ontology-Grounded Bi-Temporal Semantic Graph (`t_valid`, `t_invalid`)
110
+ - Tier 3: Procedural Reasoning Traces (`AgentRun -> ToolCall -> Entity`)
111
+ Decouples ADK agents from underlying databases via Hexagonal Ports & Adapters.
112
+ """
113
+
114
+ def __init__(
115
+ self,
116
+ registry_adapter: RegistryStoreAdapter,
117
+ seed_store_adapter: EpisodicAndSeedStoreAdapter,
118
+ graph_adapter: GraphStoreAdapter,
119
+ embedding_adapter: EmbeddingAdapter,
120
+ extractor_adapter: OntologyExtractorAdapter,
121
+ default_tenant_id: str = "t1",
122
+ max_context_tokens: int = 1500,
123
+ graph_timeout_sec: float = 1.5,
124
+ sync_outbox_immediately: bool = False,
125
+ default_extraction_mode: ExtractionMode | str = ExtractionMode.HOT,
126
+ playbook_adapter: PlaybookStoreAdapter | None = None,
127
+ ):
128
+ self.registry = registry_adapter
129
+ self.seed_store = seed_store_adapter
130
+ self.graph = graph_adapter
131
+ self.embedder = embedding_adapter
132
+ self.extractor = extractor_adapter
133
+ self.default_tenant_id = default_tenant_id
134
+ self.max_context_tokens = max_context_tokens
135
+ self.graph_timeout_sec = graph_timeout_sec
136
+ self.sync_outbox_immediately = sync_outbox_immediately
137
+ self.default_extraction_mode = ExtractionMode(default_extraction_mode)
138
+ if playbook_adapter is not None:
139
+ self.playbook_adapter: PlaybookStoreAdapter = playbook_adapter
140
+ elif isinstance(seed_store_adapter, PlaybookStoreAdapter):
141
+ self.playbook_adapter = seed_store_adapter
142
+ else:
143
+ self.playbook_adapter = RedisPlaybookAndWorkingAdapter()
144
+ self.circuit_breaker = AsyncCircuitBreaker(
145
+ failure_threshold=3, recovery_timeout_sec=30.0
146
+ )
147
+ self.rate_limiter = TenantRateLimiter(window_sec=60.0)
148
+ self._outbox_task: asyncio.Task[None] | None = None
149
+ self._outbox_stop_event: asyncio.Event | None = None
150
+
151
+ @classmethod
152
+ def from_postgres_stack(
153
+ cls,
154
+ dsn: str,
155
+ embedding_adapter: EmbeddingAdapter,
156
+ extractor_adapter: OntologyExtractorAdapter,
157
+ auth_provider: Any = None,
158
+ tls_config: Any = None,
159
+ default_tenant_id: str = "t1",
160
+ default_extraction_mode: ExtractionMode | str = ExtractionMode.HOT,
161
+ ) -> "CompositeMemoryService":
162
+ """
163
+ Creates a single-stack Pure PostgreSQL `CompositeMemoryService` where Registry,
164
+ Tier 1 Episodic, Tier 2 Seed + Bi-Temporal Graph, and Tier 3 Playbooks all run
165
+ on PostgreSQL (`PostgresUnifiedAdapter`) with optional enterprise cloud IAM/mTLS auth.
166
+ """
167
+ from .adapters.postgres_unified import PostgresUnifiedAdapter
168
+
169
+ unified = PostgresUnifiedAdapter(
170
+ dsn=dsn,
171
+ auth_provider=auth_provider,
172
+ tls_config=tls_config,
173
+ )
174
+ return cls(
175
+ registry_adapter=unified,
176
+ seed_store_adapter=unified,
177
+ graph_adapter=unified,
178
+ embedding_adapter=embedding_adapter,
179
+ extractor_adapter=extractor_adapter,
180
+ default_tenant_id=default_tenant_id,
181
+ sync_outbox_immediately=True,
182
+ default_extraction_mode=default_extraction_mode,
183
+ playbook_adapter=unified, # type: ignore[arg-type]
184
+ )
185
+
186
+ @classmethod
187
+ def from_redis_stack(
188
+ cls,
189
+ redis_url: str,
190
+ embedding_adapter: EmbeddingAdapter,
191
+ extractor_adapter: OntologyExtractorAdapter,
192
+ auth_provider: Any = None,
193
+ tls_config: Any = None,
194
+ key_prefix: str = "adk_memory",
195
+ default_tenant_id: str = "t1",
196
+ default_extraction_mode: ExtractionMode | str = ExtractionMode.HOT,
197
+ ) -> "CompositeMemoryService":
198
+ """
199
+ Creates a single-stack Pure Redis `CompositeMemoryService` where Registry,
200
+ Tier 1 Episodic, Tier 2 Seed + Bi-Temporal Graph, and Tier 3 Playbooks all run
201
+ on Redis (`RedisUnifiedAdapter`) with optional enterprise cloud IAM/mTLS auth.
202
+ """
203
+ from .adapters.redis_unified import RedisUnifiedAdapter
204
+
205
+ unified = RedisUnifiedAdapter(
206
+ redis_url=redis_url,
207
+ key_prefix=key_prefix,
208
+ auth_provider=auth_provider,
209
+ tls_config=tls_config,
210
+ )
211
+ return cls(
212
+ registry_adapter=unified,
213
+ seed_store_adapter=unified,
214
+ graph_adapter=unified,
215
+ embedding_adapter=embedding_adapter,
216
+ extractor_adapter=extractor_adapter,
217
+ default_tenant_id=default_tenant_id,
218
+ sync_outbox_immediately=True,
219
+ default_extraction_mode=default_extraction_mode,
220
+ playbook_adapter=unified,
221
+ )
222
+
223
+ async def _extract_entities_and_edges(
224
+ self,
225
+ ctx: PlatformTenantContext,
226
+ sanitized_transcript: list[str],
227
+ source_ep_id: str,
228
+ target_episodes: Sequence[EpisodicRecord] | None = None,
229
+ ) -> tuple[list[GraphVertexUpsert], list[GraphEdgeMutation]]:
230
+ """
231
+ Shared extraction helper used by both Hot-Path (`add_events_to_memory`)
232
+ and Batch Sleep-Time Mode (`run_memory_maintenance`).
233
+ """
234
+ vertex_upserts: list[GraphVertexUpsert] = []
235
+ edge_mutations: list[GraphEdgeMutation] = []
236
+ if not sanitized_transcript:
237
+ return vertex_upserts, edge_mutations
238
+
239
+ try:
240
+ raw_extraction = await self.extractor.extract(
241
+ "\n".join(sanitized_transcript), ctx.tbox
242
+ )
243
+ if (
244
+ raw_extraction.is_ephemeral_chitchat
245
+ and not raw_extraction.entities
246
+ and not raw_extraction.facts
247
+ and target_episodes
248
+ ):
249
+ for ep in target_episodes:
250
+ ep.metadata["ephemeral"] = True
251
+ if raw_extraction.classification_reason:
252
+ ep.metadata["ephemeral_reason"] = (
253
+ raw_extraction.classification_reason
254
+ )
255
+
256
+ routed_entities, routed_facts = TBoxRuntimeValidator.validate_and_partition(
257
+ ctx, raw_extraction
258
+ )
259
+
260
+ name_to_vertex_id: dict[str, str] = {}
261
+ for ent, target_ns in routed_entities:
262
+ clean_summary = PIIScrubber.scrub(ent.summary)
263
+ ent_vec = await self.embedder.embed(
264
+ f"{ent.canonical_name}: {clean_summary}"
265
+ )
266
+ existing_vid = await self.seed_store.resolve_existing_vertex_id(
267
+ ctx, ent.entity_class, ent.canonical_name, ent_vec
268
+ )
269
+ vid = existing_vid or GraphVertexUpsert.deterministic_id(
270
+ ctx.tenant_id, target_ns, ent.entity_class, ent.canonical_name
271
+ )
272
+ name_to_vertex_id[ent.canonical_name] = vid
273
+
274
+ vertex_upserts.append(
275
+ GraphVertexUpsert(
276
+ vertex_id=vid,
277
+ tenant_id=ctx.tenant_id,
278
+ namespace=target_ns,
279
+ entity_class=ent.entity_class,
280
+ upper_class=ctx.tbox.resolve_upper_class(ent.entity_class),
281
+ canonical_name=ent.canonical_name,
282
+ summary=clean_summary,
283
+ embedding=ent_vec,
284
+ )
285
+ )
286
+
287
+ for fact, target_ns, is_func in routed_facts:
288
+ src_vid = name_to_vertex_id.get(fact.source_entity)
289
+ tgt_vid = name_to_vertex_id.get(fact.target_entity)
290
+ if not src_vid or not tgt_vid or src_vid == tgt_vid:
291
+ continue
292
+
293
+ edge_mutations.append(
294
+ GraphEdgeMutation(
295
+ edge_id=f"e_{uuid.uuid4().hex[:16]}",
296
+ tenant_id=ctx.tenant_id,
297
+ namespace=target_ns,
298
+ source_vertex_id=src_vid,
299
+ target_vertex_id=tgt_vid,
300
+ predicate=fact.predicate,
301
+ fact_summary=PIIScrubber.scrub(fact.fact_summary),
302
+ is_functional=is_func,
303
+ confidence=fact.confidence,
304
+ source_episode_id=source_ep_id,
305
+ source_app=ctx.app_name,
306
+ user_id=ctx.user_id,
307
+ t_valid=fact.valid_from or GraphEdgeMutation.model_fields["t_valid"].default_factory(), # type: ignore
308
+ )
309
+ )
310
+ except Exception as exc:
311
+ logger.warning(
312
+ "Ontology extraction failed; committing episodic memory only: %s", exc
313
+ )
314
+ return vertex_upserts, edge_mutations
315
+
316
+ def _split_tenant_app(self, app_name: str) -> tuple[str, str]:
317
+ if ":" in app_name:
318
+ t_id, a_name = app_name.split(":", 1)
319
+ return t_id, a_name
320
+ return self.default_tenant_id, app_name
321
+
322
+ # ========================================================================
323
+ # ADK CONTRACT 1: Full Session Ingestion
324
+ # ========================================================================
325
+ async def add_session_to_memory(self, session: Session) -> None:
326
+ await self.add_events_to_memory(
327
+ app_name=session.app_name,
328
+ user_id=session.user_id,
329
+ events=session.events,
330
+ session_id=session.id,
331
+ )
332
+
333
+ # ========================================================================
334
+ # ADK CONTRACT 2: Delta Event Ingestion (Hot-Path OR Sleep-Time Batch Mode)
335
+ # ========================================================================
336
+ async def add_events_to_memory(
337
+ self,
338
+ *,
339
+ app_name: str,
340
+ user_id: str,
341
+ events: Sequence[Event],
342
+ session_id: str | None = None,
343
+ custom_metadata: dict[str, Any] | None = None,
344
+ defer_extraction: bool | None = None,
345
+ extraction_mode: ExtractionMode | str | None = None,
346
+ ) -> None:
347
+ tenant_id, clean_app = self._split_tenant_app(app_name)
348
+ ctx = await self.registry.resolve_context(tenant_id, clean_app, user_id)
349
+
350
+ if not self.rate_limiter.check_and_record(
351
+ ctx.tenant_id, ctx.app_name, max_rpm=ctx.max_rpm
352
+ ):
353
+ raise RuntimeError(
354
+ f"Rate limit exceeded for tenant='{ctx.tenant_id}', app='{ctx.app_name}' (max_rpm={ctx.max_rpm})"
355
+ )
356
+
357
+ if extraction_mode is not None:
358
+ should_defer = ExtractionMode(extraction_mode) == ExtractionMode.SLEEP_TIME
359
+ elif defer_extraction is not None:
360
+ should_defer = defer_extraction
361
+ else:
362
+ should_defer = (
363
+ ctx.tbox.extraction_mode == ExtractionMode.SLEEP_TIME
364
+ or self.default_extraction_mode == ExtractionMode.SLEEP_TIME
365
+ )
366
+
367
+ episodic_records: list[EpisodicRecord] = []
368
+ sanitized_transcript: list[str] = []
369
+
370
+ # 1. Scrub PII/Secrets and embed raw episodic chunks
371
+ prev_text: str | None = None
372
+ for ev in events:
373
+ if not getattr(ev, "content", None) or not getattr(ev.content, "parts", None):
374
+ continue
375
+ raw_text = "\n".join(
376
+ p.text for p in ev.content.parts if getattr(p, "text", None)
377
+ )
378
+ if not raw_text.strip():
379
+ continue
380
+
381
+ clean_text = PIIScrubber.scrub(raw_text)
382
+ vec = await self.embedder.embed(clean_text)
383
+ author = getattr(ev, "author", None) or "agent"
384
+ is_ephemeral = SmartMemoryClassifier.is_ephemeral_turn(
385
+ clean_text, preceding_text=prev_text
386
+ )
387
+ prev_text = clean_text
388
+
389
+ ep_meta = dict(custom_metadata or {})
390
+ if is_ephemeral:
391
+ ep_meta["ephemeral"] = True
392
+ elif should_defer:
393
+ ep_meta["extraction_pending"] = True
394
+
395
+ ep = EpisodicRecord(
396
+ tenant_id=ctx.tenant_id,
397
+ app_name=ctx.app_name,
398
+ user_id=ctx.user_id,
399
+ session_id=session_id or "default_session",
400
+ namespace=ctx.app_private_namespace,
401
+ author=author,
402
+ content_text=clean_text,
403
+ embedding=vec,
404
+ metadata=ep_meta,
405
+ )
406
+ episodic_records.append(ep)
407
+ if not is_ephemeral:
408
+ sanitized_transcript.append(f"{author}: {clean_text}")
409
+
410
+ if not episodic_records:
411
+ return
412
+
413
+ # 2. Hot-Path Mode vs. Sleep-Time Deferred Mode
414
+ vertex_upserts: list[GraphVertexUpsert] = []
415
+ edge_mutations: list[GraphEdgeMutation] = []
416
+
417
+ if sanitized_transcript and not should_defer:
418
+ vertex_upserts, edge_mutations = await self._extract_entities_and_edges(
419
+ ctx=ctx,
420
+ sanitized_transcript=sanitized_transcript,
421
+ source_ep_id=episodic_records[-1].episode_id,
422
+ target_episodes=episodic_records,
423
+ )
424
+
425
+ # 3. Build Transactional Outbox Operation for Graph Store
426
+ outbox_op = None
427
+ if vertex_upserts or edge_mutations:
428
+ outbox_op = OutboxOperation(
429
+ tenant_id=ctx.tenant_id,
430
+ operation_type="UPSERT_GRAPH_BATCH",
431
+ payload={
432
+ "vertices": [
433
+ v.model_dump(exclude={"embedding"}) for v in vertex_upserts
434
+ ],
435
+ "edges": [e.model_dump() for e in edge_mutations],
436
+ },
437
+ )
438
+
439
+ # 4. Atomic ACID Commit to Seed/Episodic Store + Outbox
440
+ await self.seed_store.commit_episodes_and_outbox(
441
+ ctx, episodic_records, vertex_upserts, outbox_op
442
+ )
443
+
444
+ if self.sync_outbox_immediately and outbox_op is not None:
445
+ await self.process_outbox_batch(batch_size=10)
446
+
447
+ # ========================================================================
448
+ # ADK CONTRACT 3: Direct Memory Entry Ingestion
449
+ # ========================================================================
450
+ async def add_memory(
451
+ self,
452
+ *,
453
+ app_name: str,
454
+ user_id: str,
455
+ memories: Sequence[MemoryEntry],
456
+ custom_metadata: dict[str, Any] | None = None,
457
+ ) -> None:
458
+ synthetic_events = [
459
+ Event(author=m.author or "user", content=m.content)
460
+ for m in memories
461
+ if getattr(m, "content", None)
462
+ ]
463
+ await self.add_events_to_memory(
464
+ app_name=app_name,
465
+ user_id=user_id,
466
+ events=synthetic_events,
467
+ custom_metadata=custom_metadata,
468
+ )
469
+
470
+ # ========================================================================
471
+ # ADK CONTRACT 4: Hybrid Read Path with Circuit Breaker & Token Budgeter
472
+ # ========================================================================
473
+ async def search_memory(
474
+ self,
475
+ *,
476
+ app_name: str,
477
+ user_id: str,
478
+ query: str,
479
+ as_of_iso: str | None = None,
480
+ max_hops: int = 2,
481
+ ) -> SearchMemoryResponse:
482
+ tenant_id, clean_app = self._split_tenant_app(app_name)
483
+ ctx = await self.registry.resolve_context(tenant_id, clean_app, user_id)
484
+ q_vec = await self.embedder.embed(query)
485
+
486
+ # 1. Parallel Seed Search (RRF), Verbatim Episodic Search & Semantic Playbook Lookup
487
+ seeds, episodes, matched_playbooks = await asyncio.gather(
488
+ self.seed_store.hybrid_seed_search(ctx, query, q_vec, limit=8),
489
+ self.seed_store.search_episodes(ctx, q_vec, limit=4),
490
+ self.playbook_adapter.match_playbooks(
491
+ ctx.tenant_id, ctx.read_namespaces, q_vec
492
+ ),
493
+ )
494
+
495
+ graph_facts: list[GraphFactReadResult] = []
496
+ degraded_mode = False
497
+
498
+ # 2. Circuit-Breaker Protected Graph Subgraph Traversal
499
+ if seeds and self.circuit_breaker.allow_request():
500
+ try:
501
+ seed_ids = [s.vertex_id for s in seeds]
502
+ graph_facts = await asyncio.wait_for(
503
+ self.graph.expand_active_subgraph(
504
+ ctx, seed_ids, as_of_iso=as_of_iso, max_hops=max_hops, limit=25
505
+ ),
506
+ timeout=self.graph_timeout_sec,
507
+ )
508
+ self.circuit_breaker.record_success()
509
+ except Exception as exc:
510
+ logger.error(
511
+ "Graph adapter failed or timed out; degrading to seed summaries: %s",
512
+ exc,
513
+ )
514
+ self.circuit_breaker.record_failure()
515
+ degraded_mode = True
516
+ elif seeds:
517
+ degraded_mode = True
518
+
519
+ # Edge Case: If Graph is down, synthesize fallback facts from Seed Index summaries
520
+ if degraded_mode and seeds:
521
+ graph_facts = [
522
+ GraphFactReadResult(
523
+ source_name=s.canonical_name,
524
+ source_class=s.entity_class,
525
+ predicate="HAS_SUMMARY",
526
+ target_name=s.entity_class,
527
+ target_class=s.upper_class,
528
+ fact_summary=s.summary,
529
+ t_valid="SEED_CACHE",
530
+ t_invalid="ACTIVE",
531
+ namespace=s.namespace,
532
+ confidence=0.8,
533
+ )
534
+ for s in seeds
535
+ ]
536
+
537
+ # 3. Token-Budgeted Serialization
538
+ graph_block, bounded_episodes = TokenBudgetSerializer.serialize(
539
+ graph_facts,
540
+ episodes,
541
+ max_tokens=self.max_context_tokens,
542
+ degraded_mode=degraded_mode,
543
+ )
544
+
545
+ entries: list[MemoryEntry] = []
546
+ if matched_playbooks:
547
+ pb_lines = ["[MATCHED_PROCEDURAL_PLAYBOOKS]"]
548
+ for pb in matched_playbooks:
549
+ steps_str = " -> ".join(pb.workflow_steps)
550
+ pb_lines.append(
551
+ f"- [{pb.namespace}] Intent='{pb.trigger_intent}' (verified={pb.success_count}x): "
552
+ f"Steps=[{steps_str}] | Resolution: {pb.resolution_summary}"
553
+ )
554
+ entries.append(
555
+ MemoryEntry(
556
+ author="platform_playbook_cache",
557
+ content=types.Content(
558
+ role="user",
559
+ parts=[types.Part.from_text(text="\n".join(pb_lines))],
560
+ ),
561
+ )
562
+ )
563
+ if graph_block:
564
+ entries.append(
565
+ MemoryEntry(
566
+ author="platform_knowledge_graph",
567
+ content=types.Content(
568
+ role="user",
569
+ parts=[types.Part.from_text(text=graph_block)],
570
+ ),
571
+ )
572
+ )
573
+
574
+ for ep in bounded_episodes:
575
+ entries.append(
576
+ MemoryEntry(
577
+ author=ep.author,
578
+ timestamp=ep.created_at.isoformat(),
579
+ content=types.Content(
580
+ role="user",
581
+ parts=[types.Part.from_text(text=ep.content_text)],
582
+ ),
583
+ )
584
+ )
585
+
586
+ return SearchMemoryResponse(memories=entries)
587
+
588
+ # ========================================================================
589
+ # PLATFORM EXTENSIONS: Reasoning Traces, Transactional Outbox & GDPR Purge
590
+ # ========================================================================
591
+ async def record_decision_trace(
592
+ self,
593
+ *,
594
+ app_name: str,
595
+ user_id: str,
596
+ run_id: str,
597
+ session_id: str,
598
+ steps: Sequence[ReasoningTraceStep],
599
+ ) -> None:
600
+ """Records Tier 3 Procedural Reasoning Trace (`AgentRun -> ToolCall -> Entity`)."""
601
+ tenant_id, clean_app = self._split_tenant_app(app_name)
602
+ ctx = await self.registry.resolve_context(tenant_id, clean_app, user_id)
603
+ await self.graph.record_reasoning_trace(ctx, run_id, session_id, steps)
604
+
605
+ async def register_playbook(
606
+ self,
607
+ *,
608
+ app_name: str,
609
+ user_id: str,
610
+ trigger_intent: str,
611
+ workflow_steps: list[str],
612
+ resolution_summary: str,
613
+ share_in_domain: bool = True,
614
+ ) -> PlaybookRecord:
615
+ """
616
+ Caches a proven Tier 3 Agent Playbook in `RedisPlaybookAndWorkingAdapter`
617
+ so future matching intents across the app or domain resolve with sub-5ms recall.
618
+ """
619
+ tenant_id, clean_app = self._split_tenant_app(app_name)
620
+ ctx = await self.registry.resolve_context(tenant_id, clean_app, user_id)
621
+ target_ns = ctx.write_namespace if share_in_domain else ctx.app_private_namespace
622
+ clean_intent = PIIScrubber.scrub(trigger_intent)
623
+ clean_res = PIIScrubber.scrub(resolution_summary)
624
+ vec = await self.embedder.embed(f"{clean_intent}: {clean_res}")
625
+ pb = PlaybookRecord(
626
+ tenant_id=ctx.tenant_id,
627
+ namespace=target_ns,
628
+ app_name=ctx.app_name,
629
+ trigger_intent=clean_intent,
630
+ workflow_steps=list(workflow_steps),
631
+ resolution_summary=clean_res,
632
+ embedding=vec,
633
+ )
634
+ return await self.playbook_adapter.upsert_playbook(pb)
635
+
636
+ async def process_outbox_batch(self, batch_size: int = 25) -> int:
637
+ """Idempotent background relay syncing pending graph mutations to the Graph Adapter."""
638
+ ops = await self.seed_store.fetch_pending_outbox(batch_size=batch_size)
639
+ processed = 0
640
+ for op in ops:
641
+ try:
642
+ if op.operation_type == "UPSERT_GRAPH_BATCH":
643
+ vertices = [
644
+ GraphVertexUpsert(**{**v, "embedding": []})
645
+ for v in op.payload.get("vertices", [])
646
+ ]
647
+ edges = [
648
+ GraphEdgeMutation(**e)
649
+ for e in op.payload.get("edges", [])
650
+ ]
651
+ await self.graph.upsert_vertices_and_bitemporal_edges(
652
+ op.tenant_id, vertices, edges
653
+ )
654
+ await self.seed_store.mark_outbox_processed(op.outbox_id)
655
+ processed += 1
656
+ except Exception as exc:
657
+ logger.error("Outbox op %s failed: %s", op.outbox_id, exc)
658
+ await self.seed_store.mark_outbox_failed(op.outbox_id, str(exc))
659
+ return processed
660
+
661
+ async def start_outbox_worker(
662
+ self, interval_sec: float = 2.0, batch_size: int = 25
663
+ ) -> None:
664
+ """Starts an asynchronous background worker task that continuously drains the transactional outbox."""
665
+ if self._outbox_task is not None and not self._outbox_task.done():
666
+ return
667
+ self._outbox_stop_event = asyncio.Event()
668
+
669
+ async def _worker_loop() -> None:
670
+ while self._outbox_stop_event and not self._outbox_stop_event.is_set():
671
+ try:
672
+ await self.process_outbox_batch(batch_size=batch_size)
673
+ except Exception as exc:
674
+ logger.warning("Background outbox worker iteration error: %s", exc)
675
+ try:
676
+ await asyncio.wait_for(
677
+ self._outbox_stop_event.wait(), timeout=interval_sec
678
+ )
679
+ except asyncio.TimeoutError:
680
+ pass
681
+
682
+ self._outbox_task = asyncio.create_task(_worker_loop())
683
+
684
+ async def stop_outbox_worker(self) -> None:
685
+ """Cleanly stops the background transactional outbox worker."""
686
+ if self._outbox_stop_event is not None:
687
+ self._outbox_stop_event.set()
688
+ if self._outbox_task is not None:
689
+ try:
690
+ await asyncio.wait_for(self._outbox_task, timeout=5.0)
691
+ except (asyncio.TimeoutError, asyncio.CancelledError):
692
+ self._outbox_task.cancel()
693
+ self._outbox_task = None
694
+
695
+ async def purge_user_lineage(self, app_name: str, user_id: str) -> list[str]:
696
+ """Cascading Right-to-be-Forgotten deletion across Episodic, Seed, and Graph stores."""
697
+ tenant_id, clean_app = self._split_tenant_app(app_name)
698
+ ctx = await self.registry.resolve_context(tenant_id, clean_app, user_id)
699
+ purged_episode_ids = await self.seed_store.purge_user_data(ctx)
700
+ await self.graph.purge_episode_lineage(
701
+ ctx.tenant_id, purged_episode_ids, user_id
702
+ )
703
+ return purged_episode_ids
704
+
705
+ async def run_memory_maintenance(
706
+ self,
707
+ *,
708
+ min_episodes_to_compact: int = 4,
709
+ min_overflow_confidence: float = 0.55,
710
+ ) -> dict[str, int]:
711
+ """
712
+ Behind-the-scenes Auto-Summarization & Auto-Cleanup janitor cycle:
713
+ 1. Prunes ephemeral chitchat (`metadata.ephemeral == True`) and expired TTL episodes.
714
+ 2. Compacts verbose multi-turn session episodes (`>= min_episodes_to_compact`) into
715
+ dense `[AUTO_SESSION_SUMMARY]` episodic records with fresh embeddings.
716
+ 3. Cleans up low-confidence quarantined overflow edges (`confidence < min_overflow_confidence`).
717
+ """
718
+ pruned_ephemeral = 0
719
+ compacted_episodes = 0
720
+ summaries_created = 0
721
+ pruned_overflow_edges = 0
722
+ sleep_time_extracted_batches = 0
723
+ sleep_time_extracted_episodes = 0
724
+
725
+ # Supports InMemoryUnifiedAdapter directly and PostgresPgVectorAdapter via SQL maintenance
726
+ if hasattr(self.seed_store, "episodes"):
727
+ from collections import defaultdict
728
+
729
+ episodes_list: list[EpisodicRecord] = getattr(self.seed_store, "episodes")
730
+
731
+ # Step 0: Sleep-Time Batch Ontology Extraction for deferred hot-path episodes!
732
+ pending_by_session: dict[tuple[str, str, str, str], list[EpisodicRecord]] = (
733
+ defaultdict(list)
734
+ )
735
+ for ep in episodes_list:
736
+ if ep.metadata.get("extraction_pending") is True and not ep.metadata.get(
737
+ "ephemeral"
738
+ ):
739
+ pending_by_session[
740
+ (ep.tenant_id, ep.app_name, ep.user_id, ep.session_id)
741
+ ].append(ep)
742
+
743
+ for (t_id, a_name, u_id, _s_id), pending_eps in pending_by_session.items():
744
+ ctx = await self.registry.resolve_context(t_id, a_name, u_id)
745
+ batch_transcript = [
746
+ f"{e.author}: {e.content_text}" for e in pending_eps
747
+ ]
748
+ v_upserts, e_mutations = await self._extract_entities_and_edges(
749
+ ctx=ctx,
750
+ sanitized_transcript=batch_transcript,
751
+ source_ep_id=pending_eps[-1].episode_id,
752
+ target_episodes=pending_eps,
753
+ )
754
+ outbox_op = None
755
+ if v_upserts or e_mutations:
756
+ outbox_op = OutboxOperation(
757
+ tenant_id=ctx.tenant_id,
758
+ operation_type="UPSERT_GRAPH_BATCH",
759
+ payload={
760
+ "vertices": [
761
+ v.model_dump(exclude={"embedding"}) for v in v_upserts
762
+ ],
763
+ "edges": [e.model_dump() for e in e_mutations],
764
+ },
765
+ )
766
+ await self.seed_store.commit_episodes_and_outbox(
767
+ ctx, [], v_upserts, outbox_op
768
+ )
769
+ if self.sync_outbox_immediately and outbox_op is not None:
770
+ await self.process_outbox_batch(batch_size=10)
771
+ for ep in pending_eps:
772
+ ep.metadata.pop("extraction_pending", None)
773
+ sleep_time_extracted_batches += 1
774
+ sleep_time_extracted_episodes += len(pending_eps)
775
+
776
+ kept_episodes: list[EpisodicRecord] = []
777
+ for ep in episodes_list:
778
+ if ep.metadata.get("ephemeral") is True:
779
+ pruned_ephemeral += 1
780
+ else:
781
+ kept_episodes.append(ep)
782
+
783
+ # Group non-summary episodes by (tenant_id, app_name, user_id, session_id)
784
+ from collections import defaultdict
785
+
786
+ groups: dict[tuple[str, str, str, str], list[EpisodicRecord]] = defaultdict(list)
787
+ passthrough: list[EpisodicRecord] = []
788
+ for ep in kept_episodes:
789
+ if ep.metadata.get("is_summary"):
790
+ passthrough.append(ep)
791
+ else:
792
+ groups[(ep.tenant_id, ep.app_name, ep.user_id, ep.session_id)].append(ep)
793
+
794
+ final_episodes: list[EpisodicRecord] = list(passthrough)
795
+ for (t_id, a_name, u_id, s_id), group in groups.items():
796
+ if len(group) >= min_episodes_to_compact:
797
+ bullet_points = " | ".join(
798
+ f"{e.author}: {e.content_text.strip()}" for e in group
799
+ )
800
+ summary_text = f"[AUTO_SESSION_SUMMARY ({len(group)} turns)]: {bullet_points[:600]}"
801
+ sum_vec = await self.embedder.embed(summary_text)
802
+ summary_ep = EpisodicRecord(
803
+ tenant_id=t_id,
804
+ app_name=a_name,
805
+ user_id=u_id,
806
+ session_id=s_id,
807
+ namespace=group[0].namespace,
808
+ author="memory_compactor",
809
+ content_text=summary_text,
810
+ embedding=sum_vec,
811
+ metadata={
812
+ "is_summary": True,
813
+ "compacted_count": len(group),
814
+ "source_episode_ids": [e.episode_id for e in group],
815
+ },
816
+ )
817
+ final_episodes.append(summary_ep)
818
+ compacted_episodes += len(group)
819
+ summaries_created += 1
820
+ else:
821
+ final_episodes.extend(group)
822
+
823
+ setattr(self.seed_store, "episodes", final_episodes)
824
+ elif hasattr(self.seed_store, "_get_pool"):
825
+ from collections import defaultdict
826
+
827
+ pool = await getattr(self.seed_store, "_get_pool")()
828
+ async with pool.acquire() as conn:
829
+ # 1. Prune ephemeral chitchat in PostgreSQL
830
+ del_rows = await conn.fetch(
831
+ """
832
+ DELETE FROM episodic_memories
833
+ WHERE custom_metadata->>'ephemeral' = 'true'
834
+ RETURNING episode_id::text
835
+ """
836
+ )
837
+ pruned_ephemeral += len(del_rows)
838
+
839
+ # 2. Fetch pending Sleep-Time episodes in PostgreSQL
840
+ pending_rows = await conn.fetch(
841
+ """
842
+ SELECT episode_id::text, tenant_id, app_name, user_id, session_id,
843
+ namespace, author, content_text, custom_metadata
844
+ FROM episodic_memories
845
+ WHERE custom_metadata->>'extraction_pending' = 'true'
846
+ ORDER BY created_at ASC
847
+ """
848
+ )
849
+ pg_pending: dict[tuple[str, str, str, str], list[Any]] = defaultdict(list)
850
+ for r in pending_rows:
851
+ pg_pending[
852
+ (r["tenant_id"], r["app_name"], r["user_id"], r["session_id"])
853
+ ].append(r)
854
+
855
+ for (t_id, a_name, u_id, _s_id), rows_group in pg_pending.items():
856
+ ctx = await self.registry.resolve_context(t_id, a_name, u_id)
857
+ batch_transcript = [
858
+ f"{r['author']}: {r['content_text']}" for r in rows_group
859
+ ]
860
+ v_upserts, e_mutations = await self._extract_entities_and_edges(
861
+ ctx=ctx,
862
+ sanitized_transcript=batch_transcript,
863
+ source_ep_id=rows_group[-1]["episode_id"],
864
+ )
865
+ outbox_op = None
866
+ if v_upserts or e_mutations:
867
+ outbox_op = OutboxOperation(
868
+ tenant_id=ctx.tenant_id,
869
+ operation_type="UPSERT_GRAPH_BATCH",
870
+ payload={
871
+ "vertices": [
872
+ v.model_dump(exclude={"embedding"}) for v in v_upserts
873
+ ],
874
+ "edges": [e.model_dump() for e in e_mutations],
875
+ },
876
+ )
877
+ await self.seed_store.commit_episodes_and_outbox(
878
+ ctx, [], v_upserts, outbox_op
879
+ )
880
+ if self.sync_outbox_immediately and outbox_op is not None:
881
+ await self.process_outbox_batch(batch_size=10)
882
+ async with pool.acquire() as conn:
883
+ await conn.execute(
884
+ """
885
+ UPDATE episodic_memories
886
+ SET custom_metadata = custom_metadata - 'extraction_pending'
887
+ WHERE tenant_id = $1 AND episode_id = ANY($2::uuid[])
888
+ """,
889
+ t_id,
890
+ [r["episode_id"] for r in rows_group],
891
+ )
892
+ sleep_time_extracted_batches += 1
893
+ sleep_time_extracted_episodes += len(rows_group)
894
+
895
+ if hasattr(self.graph, "edges"):
896
+ edges_list: list[dict[str, Any]] = getattr(self.graph, "edges")
897
+ kept_edges: list[dict[str, Any]] = []
898
+ for edge in edges_list:
899
+ is_app_overflow = str(edge.get("namespace", "")).startswith("app:") and edge.get("predicate") == "RELATED_TO"
900
+ if is_app_overflow and float(edge.get("confidence", 1.0)) < min_overflow_confidence:
901
+ pruned_overflow_edges += 1
902
+ else:
903
+ kept_edges.append(edge)
904
+ setattr(self.graph, "edges", kept_edges)
905
+
906
+ # Step 4 (Graphiti Gc / Letta Sleep-Time Compute): Synthesize Layer 3 Entity Dossiers
907
+ # Enriches each seed vertex's summary with its active 1-hop relational neighborhood
908
+ synthesized_dossiers = 0
909
+ if hasattr(self.seed_store, "seeds") and hasattr(self.graph, "edges"):
910
+ seeds_dict: dict[tuple[str, str], GraphVertexUpsert] = getattr(
911
+ self.seed_store, "seeds"
912
+ )
913
+ edges_list = getattr(self.graph, "edges")
914
+ from collections import defaultdict
915
+
916
+ active_rels_by_vid: dict[tuple[str, str], list[str]] = defaultdict(list)
917
+ for edge in edges_list:
918
+ if edge.get("t_invalid") != "ACTIVE":
919
+ continue
920
+ t_id = str(edge.get("tenant_id", ""))
921
+ src_vid = str(edge.get("source_vertex_id", ""))
922
+ tgt_vid = str(edge.get("target_vertex_id", ""))
923
+ tgt_seed = seeds_dict.get((t_id, tgt_vid))
924
+ if tgt_seed:
925
+ active_rels_by_vid[(t_id, src_vid)].append(
926
+ f"{edge['predicate']}->{tgt_seed.canonical_name}"
927
+ )
928
+
929
+ for (t_id, vid), rel_strs in active_rels_by_vid.items():
930
+ seed = seeds_dict.get((t_id, vid))
931
+ if seed and rel_strs:
932
+ base_summary = seed.summary.split(" [Dossier:")[0].strip()
933
+ dossier_str = ", ".join(dict.fromkeys(rel_strs[:5]))
934
+ seed.summary = f"{base_summary} [Dossier: {dossier_str}]"
935
+ synthesized_dossiers += 1
936
+
937
+ return {
938
+ "sleep_time_extracted_batches": sleep_time_extracted_batches,
939
+ "sleep_time_extracted_episodes": sleep_time_extracted_episodes,
940
+ "pruned_ephemeral_episodes": pruned_ephemeral,
941
+ "compacted_raw_episodes": compacted_episodes,
942
+ "summaries_created": summaries_created,
943
+ "pruned_low_confidence_overflow_edges": pruned_overflow_edges,
944
+ "synthesized_entity_dossiers": synthesized_dossiers,
945
+ }
946
+
947
+ async def evolve_app_ontology_from_overflow(
948
+ self,
949
+ app_name: str,
950
+ *,
951
+ min_confidence_to_promote: float = 0.75,
952
+ registrar: PlatformOntologyRegistrar | None = None,
953
+ ) -> OntologyAuditLogEntry:
954
+ """
955
+ Bottom-Up Automated Schema Evolution:
956
+ 1. Scans quarantined overflow vertices (`p:CandidateConcept` with `[ProposedClass=...]`)
957
+ and overflow edges (`RELATED_TO` with `[ProposedPredicate=...]`) in `app:{tenant}:{app}`.
958
+ 2. Evaluates candidate classes and predicates using `PlatformOntologyRegistrar` intelligence
959
+ (anchoring classes to Layer 0 `UpperConceptType` and inferring functional/transitive flags).
960
+ 3. Modifies the app's live `CompiledTBox` in the registry (bumping `tbox.version`).
961
+ 4. Promotes the quarantined vertices and edges into `ctx.write_namespace` while keeping
962
+ all original `source_episode_id`, `t_valid`, `t_created`, and `user_id` provenance intact!
963
+ 5. Appends an immutable `OntologyAuditLogEntry` with `source_episode_ids`.
964
+ """
965
+ import re
966
+
967
+ tenant_id, clean_app = self._split_tenant_app(app_name)
968
+ ctx = await self.registry.resolve_context(tenant_id, clean_app, "ontology_steward")
969
+ tbox = ctx.tbox.model_copy(deep=True)
970
+ prev_ver = tbox.version
971
+
972
+ promoted_classes: dict[str, str] = {}
973
+ promoted_relations: dict[str, dict[str, Any]] = {}
974
+ modifications: list[str] = []
975
+ source_ep_ids: set[str] = set()
976
+
977
+ # 1. Inspect quarantined candidate vertices (InMemory OR PostgreSQL + Neo4j)
978
+ if hasattr(self.seed_store, "seeds"):
979
+ seeds_dict: dict[tuple[str, str], GraphVertexUpsert] = getattr(
980
+ self.seed_store, "seeds"
981
+ )
982
+ for (t_id, _vid), seed in seeds_dict.items():
983
+ if t_id != tenant_id or seed.namespace != ctx.app_private_namespace:
984
+ continue
985
+ m = re.search(r"\[ProposedClass=([^\]]+)\]\s*(.*)", seed.summary)
986
+ if m:
987
+ cand_cls, clean_sum = m.group(1).strip(), m.group(2).strip()
988
+ if cand_cls not in tbox.classes:
989
+ parent_upper = PlatformOntologyRegistrar.infer_upper_concept_parent(
990
+ cand_cls
991
+ )
992
+ tbox.classes[cand_cls] = parent_upper
993
+ promoted_classes[cand_cls] = parent_upper
994
+ modifications.append(
995
+ f"Promoted emergent class '{cand_cls}' -> '{parent_upper}' from quarantined overflow"
996
+ )
997
+ # Promote vertex in-place while preserving vertex_id and provenance
998
+ seed.entity_class = cand_cls
999
+ seed.upper_class = tbox.resolve_upper_class(cand_cls)
1000
+ seed.summary = clean_sum
1001
+ seed.namespace = ctx.write_namespace
1002
+ elif hasattr(self.seed_store, "_get_pool"):
1003
+ pool = await getattr(self.seed_store, "_get_pool")()
1004
+ async with pool.acquire() as conn:
1005
+ rows = await conn.fetch(
1006
+ """
1007
+ SELECT neptune_vertex_id, summary_text
1008
+ FROM graph_seed_index
1009
+ WHERE tenant_id = $1 AND namespace = $2 AND summary_text LIKE '[ProposedClass=%'
1010
+ """,
1011
+ tenant_id,
1012
+ ctx.app_private_namespace,
1013
+ )
1014
+ for r in rows:
1015
+ m = re.search(
1016
+ r"\[ProposedClass=([^\]]+)\]\s*(.*)", r["summary_text"]
1017
+ )
1018
+ if m:
1019
+ cand_cls, clean_sum = m.group(1).strip(), m.group(2).strip()
1020
+ if cand_cls not in tbox.classes:
1021
+ parent_upper = PlatformOntologyRegistrar.infer_upper_concept_parent(
1022
+ cand_cls
1023
+ )
1024
+ tbox.classes[cand_cls] = parent_upper
1025
+ promoted_classes[cand_cls] = parent_upper
1026
+ modifications.append(
1027
+ f"Promoted emergent class '{cand_cls}' -> '{parent_upper}' from PostgreSQL quarantined overflow"
1028
+ )
1029
+ upper_c = tbox.resolve_upper_class(cand_cls)
1030
+ await conn.execute(
1031
+ """
1032
+ UPDATE graph_seed_index
1033
+ SET entity_class = $3, upper_class = $4, summary_text = $5, namespace = $6
1034
+ WHERE tenant_id = $1 AND neptune_vertex_id = $2
1035
+ """,
1036
+ tenant_id,
1037
+ r["neptune_vertex_id"],
1038
+ cand_cls,
1039
+ upper_c,
1040
+ clean_sum,
1041
+ ctx.write_namespace,
1042
+ )
1043
+ if hasattr(self.graph, "_run_cypher"):
1044
+ await getattr(self.graph, "_run_cypher")(
1045
+ tenant_id,
1046
+ """
1047
+ MATCH (n:Entity {`~id`: $vid, tenant_id: $tenant_id})
1048
+ SET n.entity_class = $cls, n.upper_class = $ucls, n.summary = $sum, n.namespace = $ns
1049
+ """,
1050
+ {
1051
+ "vid": r["neptune_vertex_id"],
1052
+ "tenant_id": tenant_id,
1053
+ "cls": cand_cls,
1054
+ "ucls": upper_c,
1055
+ "sum": clean_sum,
1056
+ "ns": ctx.write_namespace,
1057
+ },
1058
+ )
1059
+
1060
+ # 2. Inspect quarantined candidate edges (InMemory OR Neo4j Cypher)
1061
+ if hasattr(self.graph, "edges"):
1062
+ edges_list: list[dict[str, Any]] = getattr(self.graph, "edges")
1063
+ for edge in edges_list:
1064
+ if (
1065
+ edge.get("tenant_id") != tenant_id
1066
+ or edge.get("namespace") != ctx.app_private_namespace
1067
+ or float(edge.get("confidence", 0.0)) < min_confidence_to_promote
1068
+ ):
1069
+ continue
1070
+ m = re.search(
1071
+ r"\[ProposedPredicate=([^\]|]+)\|([^\->]+)->([^\]]+)\]\s*(.*)",
1072
+ str(edge.get("fact_summary", "")),
1073
+ )
1074
+ if m:
1075
+ raw_pred, dom_cls, rng_cls, clean_fact = (
1076
+ m.group(1).strip(),
1077
+ m.group(2).strip(),
1078
+ m.group(3).strip(),
1079
+ m.group(4).strip(),
1080
+ )
1081
+ norm_pred = re.sub(r"[\s\-]+", "_", raw_pred.upper())
1082
+ for c_name in (dom_cls, rng_cls):
1083
+ if c_name not in tbox.classes and c_name != "owl:Thing":
1084
+ p_up = PlatformOntologyRegistrar.infer_upper_concept_parent(c_name)
1085
+ tbox.classes[c_name] = p_up
1086
+ promoted_classes[c_name] = p_up
1087
+
1088
+ if norm_pred not in tbox.relations:
1089
+ is_func, is_trans = PlatformOntologyRegistrar.infer_relation_flags(
1090
+ norm_pred
1091
+ )
1092
+ rule = RelationRule(
1093
+ predicate=norm_pred,
1094
+ domain_class=dom_cls if dom_cls in tbox.classes else "owl:Thing",
1095
+ range_class=rng_cls if rng_cls in tbox.classes else "owl:Thing",
1096
+ is_functional=is_func,
1097
+ is_transitive=is_trans,
1098
+ description="Auto-promoted from emergent runtime overflow",
1099
+ )
1100
+ tbox.relations[norm_pred] = rule
1101
+ promoted_relations[norm_pred] = rule.model_dump()
1102
+ modifications.append(
1103
+ f"Promoted emergent relation '{norm_pred}' ({dom_cls} -> {rng_cls}, functional={is_func})"
1104
+ )
1105
+
1106
+ # Promote edge in-place while keeping source_episode_id, t_valid, t_created intact!
1107
+ edge["predicate"] = norm_pred
1108
+ edge["fact_summary"] = clean_fact
1109
+ edge["namespace"] = ctx.write_namespace
1110
+ if edge.get("source_episode_id"):
1111
+ source_ep_ids.add(str(edge["source_episode_id"]))
1112
+ elif hasattr(self.graph, "_run_cypher"):
1113
+ cypher_rows = await getattr(self.graph, "_run_cypher")(
1114
+ tenant_id,
1115
+ """
1116
+ MATCH ()-[r:RELATES {tenant_id: $tenant_id, namespace: $ns}]->()
1117
+ WHERE r.confidence >= $min_conf AND r.fact_summary STARTS WITH '[ProposedPredicate='
1118
+ RETURN r.edge_id AS edge_id, r.fact_summary AS fact_summary, r.source_episode_id AS ep_id
1119
+ """,
1120
+ {
1121
+ "tenant_id": tenant_id,
1122
+ "ns": ctx.app_private_namespace,
1123
+ "min_conf": min_confidence_to_promote,
1124
+ },
1125
+ )
1126
+ for r in cypher_rows:
1127
+ m = re.search(
1128
+ r"\[ProposedPredicate=([^\]|]+)\|([^\->]+)->([^\]]+)\]\s*(.*)",
1129
+ str(r.get("fact_summary", "")),
1130
+ )
1131
+ if m:
1132
+ raw_pred, dom_cls, rng_cls, clean_fact = (
1133
+ m.group(1).strip(),
1134
+ m.group(2).strip(),
1135
+ m.group(3).strip(),
1136
+ m.group(4).strip(),
1137
+ )
1138
+ norm_pred = re.sub(r"[\s\-]+", "_", raw_pred.upper())
1139
+ for c_name in (dom_cls, rng_cls):
1140
+ if c_name not in tbox.classes and c_name != "owl:Thing":
1141
+ p_up = PlatformOntologyRegistrar.infer_upper_concept_parent(
1142
+ c_name
1143
+ )
1144
+ tbox.classes[c_name] = p_up
1145
+ promoted_classes[c_name] = p_up
1146
+ if norm_pred not in tbox.relations:
1147
+ is_func, is_trans = PlatformOntologyRegistrar.infer_relation_flags(
1148
+ norm_pred
1149
+ )
1150
+ rule = RelationRule(
1151
+ predicate=norm_pred,
1152
+ domain_class=dom_cls if dom_cls in tbox.classes else "owl:Thing",
1153
+ range_class=rng_cls if rng_cls in tbox.classes else "owl:Thing",
1154
+ is_functional=is_func,
1155
+ is_transitive=is_trans,
1156
+ description="Auto-promoted from Neo4j emergent runtime overflow",
1157
+ )
1158
+ tbox.relations[norm_pred] = rule
1159
+ promoted_relations[norm_pred] = rule.model_dump()
1160
+ modifications.append(
1161
+ f"Promoted emergent relation '{norm_pred}' ({dom_cls} -> {rng_cls}, functional={is_func})"
1162
+ )
1163
+ await getattr(self.graph, "_run_cypher")(
1164
+ tenant_id,
1165
+ """
1166
+ MATCH ()-[r:RELATES {tenant_id: $tenant_id, edge_id: $edge_id}]->()
1167
+ SET r.predicate = $pred, r.fact_summary = $sum, r.namespace = $ns
1168
+ """,
1169
+ {
1170
+ "tenant_id": tenant_id,
1171
+ "edge_id": r["edge_id"],
1172
+ "pred": norm_pred,
1173
+ "sum": clean_fact,
1174
+ "ns": ctx.write_namespace,
1175
+ },
1176
+ )
1177
+ if r.get("ep_id"):
1178
+ source_ep_ids.add(str(r["ep_id"]))
1179
+
1180
+ if promoted_classes or promoted_relations:
1181
+ parts = (prev_ver.split(".") + ["0", "0"])[:3]
1182
+ try:
1183
+ parts[1] = str(int(parts[1]) + 1)
1184
+ tbox.version = ".".join(parts)
1185
+ except ValueError:
1186
+ tbox.version = f"{prev_ver}-evolved"
1187
+
1188
+ # Persist updated TBox to Registry
1189
+ clean_read_ns = [
1190
+ ns for ns in ctx.read_namespaces if not ns.startswith("user:")
1191
+ ]
1192
+ await self.registry.register_app(
1193
+ tenant_id=tenant_id,
1194
+ app_name=clean_app,
1195
+ read_namespaces=clean_read_ns,
1196
+ write_namespace=ctx.write_namespace,
1197
+ tbox=tbox,
1198
+ )
1199
+
1200
+ audit_entry = OntologyAuditLogEntry(
1201
+ tenant_id=tenant_id,
1202
+ target_id=clean_app,
1203
+ action="AUTO_EVOLVE_FROM_OVERFLOW",
1204
+ previous_version=prev_ver,
1205
+ new_version=tbox.version,
1206
+ added_or_modified_classes=promoted_classes,
1207
+ added_or_modified_relations=promoted_relations,
1208
+ modifications_summary=modifications or ["No eligible overflow candidates met promotion threshold"],
1209
+ triggered_by="overflow_auto_evolution_steward",
1210
+ source_episode_ids=sorted(source_ep_ids),
1211
+ )
1212
+ if registrar is not None:
1213
+ registrar.audit_log.append(audit_entry)
1214
+ return audit_entry