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.
- agentic_composite_memory/__init__.py +2 -0
- agentic_composite_memory/py.typed +0 -0
- agentic_composite_memory-0.1.0.dist-info/METADATA +167 -0
- agentic_composite_memory-0.1.0.dist-info/RECORD +31 -0
- agentic_composite_memory-0.1.0.dist-info/WHEEL +4 -0
- agentic_composite_memory-0.1.0.dist-info/entry_points.txt +2 -0
- agentic_composite_memory-0.1.0.dist-info/licenses/LICENSE +17 -0
- agentic_memory_sdk/__init__.py +163 -0
- agentic_memory_sdk/adapters/__init__.py +33 -0
- agentic_memory_sdk/adapters/in_memory.py +439 -0
- agentic_memory_sdk/adapters/neo4j_cypher.py +65 -0
- agentic_memory_sdk/adapters/neptune_cypher.py +309 -0
- agentic_memory_sdk/adapters/opensearch_seed.py +322 -0
- agentic_memory_sdk/adapters/postgres_pgvector.py +484 -0
- agentic_memory_sdk/adapters/postgres_unified.py +511 -0
- agentic_memory_sdk/adapters/redis_playbook.py +157 -0
- agentic_memory_sdk/adapters/redis_unified.py +490 -0
- agentic_memory_sdk/adk_integration.py +250 -0
- agentic_memory_sdk/auth.py +380 -0
- agentic_memory_sdk/cli.py +137 -0
- agentic_memory_sdk/governance.py +713 -0
- agentic_memory_sdk/llm_extractors.py +616 -0
- agentic_memory_sdk/models.py +443 -0
- agentic_memory_sdk/ontology_loader.py +189 -0
- agentic_memory_sdk/ports.py +159 -0
- agentic_memory_sdk/py.typed +0 -0
- agentic_memory_sdk/server/__init__.py +4 -0
- agentic_memory_sdk/server/api.py +328 -0
- agentic_memory_sdk/server/main.py +384 -0
- agentic_memory_sdk/server/mcp_server.py +198 -0
- agentic_memory_sdk/service.py +1214 -0
|
@@ -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
|