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,443 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import hashlib
|
|
4
|
+
import uuid
|
|
5
|
+
from datetime import datetime, timezone
|
|
6
|
+
from enum import Enum
|
|
7
|
+
from typing import Any, Literal
|
|
8
|
+
|
|
9
|
+
from pydantic import BaseModel, Field
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
class UpperConceptType(str, Enum):
|
|
13
|
+
"""Layer 0 Platform Upper Ontology classes mandatory for all apps."""
|
|
14
|
+
|
|
15
|
+
ACTOR = "p:Actor"
|
|
16
|
+
OBJECT = "p:Object"
|
|
17
|
+
EVENT = "p:Event"
|
|
18
|
+
CONCEPT = "p:Concept"
|
|
19
|
+
PREFERENCE = "p:UserPreference"
|
|
20
|
+
CANDIDATE = "p:CandidateConcept"
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
class MemoryScope(str, Enum):
|
|
24
|
+
"""
|
|
25
|
+
Smart memory sharing & visibility scope determined during extraction/classification:
|
|
26
|
+
- AUTO: Inferred automatically from TBox class, confidence, and app governance tier
|
|
27
|
+
- EPHEMERAL: Short-lived chitchat/acknowledgment; skipped from graph & pruned in cleanup
|
|
28
|
+
- USER_GLOBAL: Shared across ALL agent apps for the SAME `user_id` (`user:{tenant}:{user_id}`)
|
|
29
|
+
- APP_PRIVATE: Isolated to a single agent app (`app:{tenant}:{app}`)
|
|
30
|
+
- DOMAIN_SHARED: Shared across all apps and users subscribed to the same domain (`domain:{tenant}:{domain}`)
|
|
31
|
+
- TENANT_GLOBAL: Shared across all apps and users in the tenant (`global:{tenant}:core`)
|
|
32
|
+
"""
|
|
33
|
+
|
|
34
|
+
AUTO = "auto"
|
|
35
|
+
EPHEMERAL = "ephemeral"
|
|
36
|
+
USER_GLOBAL = "user_global"
|
|
37
|
+
APP_PRIVATE = "app_private"
|
|
38
|
+
DOMAIN_SHARED = "domain_shared"
|
|
39
|
+
TENANT_GLOBAL = "tenant_global"
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
class GovernanceTier(str, Enum):
|
|
43
|
+
"""Progressive governance tiers scaling strictness with blast radius."""
|
|
44
|
+
|
|
45
|
+
TIER0_AUTO = "tier0_auto" # Zero-config, app-private only
|
|
46
|
+
TIER1_APP_TYPED = "tier1_app_typed" # Custom app schema, app-private
|
|
47
|
+
TIER2_DOMAIN_SHARED = "tier2_domain_shared" # Shared domain pack + app overflow
|
|
48
|
+
TIER3_ENTERPRISE_CORE = "tier3_enterprise_core" # Read-only reference data for agents
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
class ExtractionMode(str, Enum):
|
|
52
|
+
"""
|
|
53
|
+
Controls when LLM ontology extraction & graph mutation occur:
|
|
54
|
+
- HOT: Extracts entities and bi-temporal facts immediately during `add_events_to_memory`.
|
|
55
|
+
- SLEEP_TIME: Hot path (<10ms, zero LLM cost) only scrubs PII and embeds raw episodes
|
|
56
|
+
with `extraction_pending=True`; `run_memory_maintenance()` batch-extracts the knowledge
|
|
57
|
+
graph asynchronously every N turns or during idle sleep-time compute windows.
|
|
58
|
+
"""
|
|
59
|
+
|
|
60
|
+
HOT = "hot"
|
|
61
|
+
SLEEP_TIME = "sleep_time"
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
class RelationRule(BaseModel):
|
|
65
|
+
"""TBox relationship predicate definition with domain, range, and cardinality rules."""
|
|
66
|
+
|
|
67
|
+
predicate: str
|
|
68
|
+
domain_class: str = "owl:Thing"
|
|
69
|
+
range_class: str = "owl:Thing"
|
|
70
|
+
is_functional: bool = False # True = at most 1 active target (triggers bi-temporal invalidation)
|
|
71
|
+
is_transitive: bool = False # True = transitive closure traversal supported
|
|
72
|
+
description: str = ""
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
class DomainPackSpec(BaseModel):
|
|
76
|
+
"""Layer 1 Federated Domain Pack published by domain stewards (e.g., payments@v2.1)."""
|
|
77
|
+
|
|
78
|
+
pack_id: str # e.g., "payments@v2.1"
|
|
79
|
+
domain_name: str # e.g., "payments"
|
|
80
|
+
version: str = "1.0.0"
|
|
81
|
+
classes: dict[str, str] = Field(
|
|
82
|
+
default_factory=dict,
|
|
83
|
+
description="Mapping of class_name -> parent_class_name (e.g., {'Microservice': 'p:Object'})",
|
|
84
|
+
)
|
|
85
|
+
disjoint_classes: list[tuple[str, str]] = Field(default_factory=list)
|
|
86
|
+
relations: dict[str, RelationRule] = Field(default_factory=dict)
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
class AppMemoryManifest(BaseModel):
|
|
90
|
+
"""
|
|
91
|
+
Developer-facing Ontology-as-Code registration manifest for any ADK agent app.
|
|
92
|
+
Supports zero-config (Tier 0), app-scoped Pydantic types (Tier 1), and shared Domain Packs (Tier 2).
|
|
93
|
+
"""
|
|
94
|
+
|
|
95
|
+
tenant_id: str
|
|
96
|
+
app_name: str
|
|
97
|
+
governance_tier: GovernanceTier = GovernanceTier.TIER0_AUTO
|
|
98
|
+
subscribed_domain_packs: list[str] = Field(default_factory=list)
|
|
99
|
+
custom_classes: dict[str, str] = Field(
|
|
100
|
+
default_factory=dict,
|
|
101
|
+
description="App-local classes mapped to UpperConceptType or parent class",
|
|
102
|
+
)
|
|
103
|
+
custom_relations: list[RelationRule] = Field(default_factory=list)
|
|
104
|
+
allow_emergent_overflow: bool = True
|
|
105
|
+
min_domain_confidence: float = Field(default=0.85, ge=0.0, le=1.0)
|
|
106
|
+
extraction_mode: ExtractionMode = ExtractionMode.HOT
|
|
107
|
+
max_rpm: int = 600
|
|
108
|
+
max_active_vertices: int = 500_000
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
def _default_layer0_relations() -> dict[str, RelationRule]:
|
|
112
|
+
"""
|
|
113
|
+
Battle-tested Layer 0 Universal Relations active out-of-the-box for every agent
|
|
114
|
+
(even in Zero-Config TIER0_AUTO mode without any Domain Pack).
|
|
115
|
+
"""
|
|
116
|
+
return {
|
|
117
|
+
"RELATED_TO": RelationRule(
|
|
118
|
+
predicate="RELATED_TO",
|
|
119
|
+
domain_class="owl:Thing",
|
|
120
|
+
range_class="owl:Thing",
|
|
121
|
+
is_functional=False,
|
|
122
|
+
description="General associative link or quarantined overflow relation",
|
|
123
|
+
),
|
|
124
|
+
"PREFERS": RelationRule(
|
|
125
|
+
predicate="PREFERS",
|
|
126
|
+
domain_class="owl:Thing",
|
|
127
|
+
range_class="owl:Thing",
|
|
128
|
+
is_functional=False,
|
|
129
|
+
description="User-scoped preference shared across apps for the same user",
|
|
130
|
+
),
|
|
131
|
+
"HAS_STATUS": RelationRule(
|
|
132
|
+
predicate="HAS_STATUS",
|
|
133
|
+
domain_class="owl:Thing",
|
|
134
|
+
range_class="p:Concept",
|
|
135
|
+
is_functional=True,
|
|
136
|
+
description="Current lifecycle status (functional: supersedes prior status)",
|
|
137
|
+
),
|
|
138
|
+
"ASSIGNED_TO": RelationRule(
|
|
139
|
+
predicate="ASSIGNED_TO",
|
|
140
|
+
domain_class="owl:Thing",
|
|
141
|
+
range_class="p:Actor",
|
|
142
|
+
is_functional=True,
|
|
143
|
+
description="Current primary assignee/owner (functional: supersedes prior assignee)",
|
|
144
|
+
),
|
|
145
|
+
"OWNED_BY": RelationRule(
|
|
146
|
+
predicate="OWNED_BY",
|
|
147
|
+
domain_class="owl:Thing",
|
|
148
|
+
range_class="p:Actor",
|
|
149
|
+
is_functional=True,
|
|
150
|
+
description="Primary owning team or actor (functional)",
|
|
151
|
+
),
|
|
152
|
+
"LOCATED_IN": RelationRule(
|
|
153
|
+
predicate="LOCATED_IN",
|
|
154
|
+
domain_class="owl:Thing",
|
|
155
|
+
range_class="p:Object",
|
|
156
|
+
is_functional=True,
|
|
157
|
+
description="Primary location or deployment environment (functional)",
|
|
158
|
+
),
|
|
159
|
+
"DEPENDS_ON": RelationRule(
|
|
160
|
+
predicate="DEPENDS_ON",
|
|
161
|
+
domain_class="owl:Thing",
|
|
162
|
+
range_class="owl:Thing",
|
|
163
|
+
is_functional=False,
|
|
164
|
+
is_transitive=True,
|
|
165
|
+
description="Upstream dependency (transitive across multi-hop chains)",
|
|
166
|
+
),
|
|
167
|
+
"PART_OF": RelationRule(
|
|
168
|
+
predicate="PART_OF",
|
|
169
|
+
domain_class="owl:Thing",
|
|
170
|
+
range_class="owl:Thing",
|
|
171
|
+
is_functional=False,
|
|
172
|
+
is_transitive=True,
|
|
173
|
+
description="Compositional hierarchy (transitive)",
|
|
174
|
+
),
|
|
175
|
+
"CAUSED_BY": RelationRule(
|
|
176
|
+
predicate="CAUSED_BY",
|
|
177
|
+
domain_class="p:Event",
|
|
178
|
+
range_class="owl:Thing",
|
|
179
|
+
is_functional=False,
|
|
180
|
+
description="Root-cause causal link from an Event to an Object/Event/Actor",
|
|
181
|
+
),
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
|
|
185
|
+
class CompiledTBox(BaseModel):
|
|
186
|
+
"""Compiled Terminological Box governing an app's runtime extraction and SHACL-lite validation."""
|
|
187
|
+
|
|
188
|
+
version: str = "1.0.0"
|
|
189
|
+
governance_tier: GovernanceTier = GovernanceTier.TIER0_AUTO
|
|
190
|
+
extraction_mode: ExtractionMode = ExtractionMode.HOT
|
|
191
|
+
allow_emergent_overflow: bool = True
|
|
192
|
+
min_domain_confidence: float = 0.85
|
|
193
|
+
classes: dict[str, str] = Field(
|
|
194
|
+
default_factory=lambda: {c.value: "owl:Thing" for c in UpperConceptType}
|
|
195
|
+
)
|
|
196
|
+
disjoint_classes: list[tuple[str, str]] = Field(default_factory=list)
|
|
197
|
+
relations: dict[str, RelationRule] = Field(default_factory=_default_layer0_relations)
|
|
198
|
+
|
|
199
|
+
def is_subclass_of(self, child_cls: str, target_parent_cls: str) -> bool:
|
|
200
|
+
"""Checks RDFS subClassOf hierarchy transitively (e.g. Microservice -> SoftwareAsset -> Asset -> p:Object)."""
|
|
201
|
+
if target_parent_cls in ("owl:Thing", child_cls):
|
|
202
|
+
return True
|
|
203
|
+
visited: set[str] = set()
|
|
204
|
+
curr = child_cls
|
|
205
|
+
while curr in self.classes and curr not in visited:
|
|
206
|
+
visited.add(curr)
|
|
207
|
+
parent = self.classes[curr]
|
|
208
|
+
if parent == target_parent_cls or parent == "owl:Thing" and target_parent_cls == "owl:Thing":
|
|
209
|
+
return True
|
|
210
|
+
curr = parent
|
|
211
|
+
return False
|
|
212
|
+
|
|
213
|
+
def resolve_upper_class(self, cls_name: str) -> str:
|
|
214
|
+
"""Resolves the root Layer 0 UpperConceptType for any class in the hierarchy."""
|
|
215
|
+
upper_values = {c.value for c in UpperConceptType}
|
|
216
|
+
if cls_name in upper_values:
|
|
217
|
+
return cls_name
|
|
218
|
+
visited: set[str] = set()
|
|
219
|
+
curr = cls_name
|
|
220
|
+
while curr in self.classes and curr not in visited:
|
|
221
|
+
visited.add(curr)
|
|
222
|
+
parent = self.classes[curr]
|
|
223
|
+
if parent in upper_values:
|
|
224
|
+
return parent
|
|
225
|
+
curr = parent
|
|
226
|
+
return UpperConceptType.CONCEPT.value
|
|
227
|
+
|
|
228
|
+
|
|
229
|
+
class PlatformTenantContext(BaseModel):
|
|
230
|
+
"""Resolved security, namespace, and ontology context for a single ADK invocation."""
|
|
231
|
+
|
|
232
|
+
tenant_id: str
|
|
233
|
+
app_name: str
|
|
234
|
+
user_id: str
|
|
235
|
+
app_private_namespace: str
|
|
236
|
+
write_namespace: str
|
|
237
|
+
read_namespaces: list[str]
|
|
238
|
+
tbox: CompiledTBox
|
|
239
|
+
max_rpm: int = 600
|
|
240
|
+
max_active_vertices: int = 500_000
|
|
241
|
+
|
|
242
|
+
@property
|
|
243
|
+
def user_private_namespace(self) -> str:
|
|
244
|
+
"""Cross-app user namespace (`user:{tenant_id}:{user_id}`) shared across apps for this specific user."""
|
|
245
|
+
return f"user:{self.tenant_id}:{self.user_id}"
|
|
246
|
+
|
|
247
|
+
|
|
248
|
+
class EpisodicRecord(BaseModel):
|
|
249
|
+
"""Tier 1 Immutable Episodic Memory record."""
|
|
250
|
+
|
|
251
|
+
episode_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
|
|
252
|
+
tenant_id: str
|
|
253
|
+
app_name: str
|
|
254
|
+
user_id: str
|
|
255
|
+
session_id: str
|
|
256
|
+
namespace: str
|
|
257
|
+
author: str
|
|
258
|
+
content_text: str
|
|
259
|
+
embedding: list[float] = Field(default_factory=list)
|
|
260
|
+
created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
|
|
261
|
+
metadata: dict[str, Any] = Field(default_factory=dict)
|
|
262
|
+
|
|
263
|
+
|
|
264
|
+
class ExtractedEntity(BaseModel):
|
|
265
|
+
"""Candidate entity extracted from conversation or tool output."""
|
|
266
|
+
|
|
267
|
+
canonical_name: str = Field(description="Normalized canonical entity name")
|
|
268
|
+
entity_class: str = Field(description="Target Ontology TBox class name")
|
|
269
|
+
summary: str = Field(description="1-2 sentence atomic description of the entity")
|
|
270
|
+
confidence: float = Field(default=0.9, ge=0.0, le=1.0)
|
|
271
|
+
scope: MemoryScope = Field(
|
|
272
|
+
default=MemoryScope.AUTO,
|
|
273
|
+
description="Target sharing scope (auto, user_global, app_private, domain_shared)",
|
|
274
|
+
)
|
|
275
|
+
|
|
276
|
+
|
|
277
|
+
class ExtractedFact(BaseModel):
|
|
278
|
+
"""Candidate relationship fact extracted from conversation or tool output."""
|
|
279
|
+
|
|
280
|
+
source_entity: str
|
|
281
|
+
source_class: str
|
|
282
|
+
predicate: str
|
|
283
|
+
target_entity: str
|
|
284
|
+
target_class: str
|
|
285
|
+
fact_summary: str
|
|
286
|
+
confidence: float = Field(default=0.9, ge=0.0, le=1.0)
|
|
287
|
+
valid_from: str | None = None
|
|
288
|
+
scope: MemoryScope = Field(
|
|
289
|
+
default=MemoryScope.AUTO,
|
|
290
|
+
description="Target sharing scope (auto, user_global, app_private, domain_shared)",
|
|
291
|
+
)
|
|
292
|
+
|
|
293
|
+
|
|
294
|
+
class ExtractionPayload(BaseModel):
|
|
295
|
+
"""
|
|
296
|
+
Complete structured output from an OntologyExtractorAdapter.
|
|
297
|
+
Combines LLM-based turn classification (`is_ephemeral_chitchat`) with
|
|
298
|
+
scoped entity and bi-temporal fact extraction in a single LLM pass.
|
|
299
|
+
"""
|
|
300
|
+
|
|
301
|
+
is_ephemeral_chitchat: bool = Field(
|
|
302
|
+
default=False,
|
|
303
|
+
description=(
|
|
304
|
+
"True if the transcript is purely social pleasantries, greetings, or terminal sign-offs "
|
|
305
|
+
"with zero durable factual, procedural, or preference value."
|
|
306
|
+
),
|
|
307
|
+
)
|
|
308
|
+
classification_reason: str = Field(
|
|
309
|
+
default="",
|
|
310
|
+
description="Brief explanation if classified as ephemeral chitchat or special scope",
|
|
311
|
+
)
|
|
312
|
+
entities: list[ExtractedEntity] = Field(default_factory=list)
|
|
313
|
+
facts: list[ExtractedFact] = Field(default_factory=list)
|
|
314
|
+
|
|
315
|
+
|
|
316
|
+
class GraphVertexUpsert(BaseModel):
|
|
317
|
+
"""Canonical vertex representation for both the Seed Index and Graph KB."""
|
|
318
|
+
|
|
319
|
+
vertex_id: str
|
|
320
|
+
tenant_id: str
|
|
321
|
+
namespace: str
|
|
322
|
+
entity_class: str
|
|
323
|
+
upper_class: str
|
|
324
|
+
canonical_name: str
|
|
325
|
+
summary: str
|
|
326
|
+
embedding: list[float] = Field(default_factory=list)
|
|
327
|
+
updated_at: str = Field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
|
|
328
|
+
|
|
329
|
+
@staticmethod
|
|
330
|
+
def deterministic_id(
|
|
331
|
+
tenant_id: str, namespace: str, entity_class: str, canonical_name: str
|
|
332
|
+
) -> str:
|
|
333
|
+
"""
|
|
334
|
+
Deterministic UUIDv5/SHA-256 canonical vertex ID.
|
|
335
|
+
Prevents duplicate vertex creation under concurrent multi-agent race conditions.
|
|
336
|
+
"""
|
|
337
|
+
norm = f"{tenant_id}:{namespace}:{entity_class}:{canonical_name.strip().lower()}"
|
|
338
|
+
digest = hashlib.sha256(norm.encode("utf-8")).hexdigest()[:16]
|
|
339
|
+
return f"v_{tenant_id}_{digest}"
|
|
340
|
+
|
|
341
|
+
|
|
342
|
+
class GraphEdgeMutation(BaseModel):
|
|
343
|
+
"""Bi-temporal directed relationship edge mutation in the ABox."""
|
|
344
|
+
|
|
345
|
+
edge_id: str
|
|
346
|
+
tenant_id: str
|
|
347
|
+
namespace: str
|
|
348
|
+
source_vertex_id: str
|
|
349
|
+
target_vertex_id: str
|
|
350
|
+
predicate: str
|
|
351
|
+
fact_summary: str
|
|
352
|
+
is_functional: bool
|
|
353
|
+
confidence: float
|
|
354
|
+
source_episode_id: str
|
|
355
|
+
source_app: str
|
|
356
|
+
user_id: str
|
|
357
|
+
t_valid: str = Field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
|
|
358
|
+
t_invalid: str = "ACTIVE"
|
|
359
|
+
t_created: str = Field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
|
|
360
|
+
reinforcement_count: int = 1
|
|
361
|
+
|
|
362
|
+
|
|
363
|
+
class GraphFactReadResult(BaseModel):
|
|
364
|
+
"""Active or point-in-time historical edge returned during subgraph expansion."""
|
|
365
|
+
|
|
366
|
+
source_name: str
|
|
367
|
+
source_class: str = "p:Concept"
|
|
368
|
+
predicate: str
|
|
369
|
+
target_name: str
|
|
370
|
+
target_class: str = "p:Concept"
|
|
371
|
+
fact_summary: str
|
|
372
|
+
t_valid: str
|
|
373
|
+
t_invalid: str
|
|
374
|
+
namespace: str
|
|
375
|
+
source_episode_id: str = ""
|
|
376
|
+
confidence: float = 1.0
|
|
377
|
+
reinforcement_count: int = 1
|
|
378
|
+
|
|
379
|
+
|
|
380
|
+
class ReasoningTraceStep(BaseModel):
|
|
381
|
+
"""Tier 3 Procedural Memory step capturing an ADK agent's tool call and touched entities."""
|
|
382
|
+
|
|
383
|
+
step_index: int
|
|
384
|
+
tool_name: str
|
|
385
|
+
tool_input_summary: str
|
|
386
|
+
tool_output_summary: str
|
|
387
|
+
touched_vertex_ids: list[str] = Field(default_factory=list)
|
|
388
|
+
status: Literal["SUCCESS", "ERROR", "FALLBACK"] = "SUCCESS"
|
|
389
|
+
|
|
390
|
+
|
|
391
|
+
class PlaybookRecord(BaseModel):
|
|
392
|
+
"""
|
|
393
|
+
Redis Iris-inspired Tier 3 Semantic Playbook Record.
|
|
394
|
+
Caches proven, reusable multi-step resolution workflows and tool sequences
|
|
395
|
+
so agents can resolve recurring intents with lower latency and fewer LLM tokens.
|
|
396
|
+
"""
|
|
397
|
+
|
|
398
|
+
playbook_id: str = Field(default_factory=lambda: f"pb_{uuid.uuid4().hex[:12]}")
|
|
399
|
+
tenant_id: str
|
|
400
|
+
namespace: str
|
|
401
|
+
app_name: str
|
|
402
|
+
trigger_intent: str
|
|
403
|
+
workflow_steps: list[str] = Field(default_factory=list)
|
|
404
|
+
resolution_summary: str
|
|
405
|
+
embedding: list[float] = Field(default_factory=list)
|
|
406
|
+
success_count: int = 1
|
|
407
|
+
updated_at: str = Field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
|
|
408
|
+
|
|
409
|
+
|
|
410
|
+
class OutboxOperation(BaseModel):
|
|
411
|
+
"""Transactional Outbox item ensuring eventual consistency between Vector/Seed DB and Graph DB."""
|
|
412
|
+
|
|
413
|
+
outbox_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
|
|
414
|
+
tenant_id: str
|
|
415
|
+
operation_type: Literal["UPSERT_GRAPH_BATCH", "RECORD_TRACE", "PURGE_LINEAGE"]
|
|
416
|
+
payload: dict[str, Any]
|
|
417
|
+
status: str = "PENDING"
|
|
418
|
+
attempts: int = 0
|
|
419
|
+
|
|
420
|
+
|
|
421
|
+
class OntologyAuditLogEntry(BaseModel):
|
|
422
|
+
"""
|
|
423
|
+
Immutable Schema Provenance record tracking every ontology registration,
|
|
424
|
+
LLM-assisted review modification, and bottom-up overflow evolution.
|
|
425
|
+
"""
|
|
426
|
+
|
|
427
|
+
audit_id: str = Field(default_factory=lambda: f"aud_{uuid.uuid4().hex[:12]}")
|
|
428
|
+
tenant_id: str
|
|
429
|
+
target_id: str # pack_id or app_name
|
|
430
|
+
action: Literal[
|
|
431
|
+
"REGISTER_DOMAIN_PACK",
|
|
432
|
+
"REGISTER_APP_MANIFEST",
|
|
433
|
+
"LLM_REVIEW_AND_REFINE",
|
|
434
|
+
"AUTO_EVOLVE_FROM_OVERFLOW",
|
|
435
|
+
]
|
|
436
|
+
previous_version: str = "0.0.0"
|
|
437
|
+
new_version: str = "1.0.0"
|
|
438
|
+
added_or_modified_classes: dict[str, str] = Field(default_factory=dict)
|
|
439
|
+
added_or_modified_relations: dict[str, dict[str, Any]] = Field(default_factory=dict)
|
|
440
|
+
modifications_summary: list[str] = Field(default_factory=list)
|
|
441
|
+
triggered_by: str = "platform_steward"
|
|
442
|
+
source_episode_ids: list[str] = Field(default_factory=list)
|
|
443
|
+
timestamp: str = Field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
|
|
@@ -0,0 +1,189 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import json
|
|
4
|
+
from pathlib import Path
|
|
5
|
+
from typing import Any, Type
|
|
6
|
+
|
|
7
|
+
from pydantic import BaseModel
|
|
8
|
+
|
|
9
|
+
from .models import DomainPackSpec, RelationRule, UpperConceptType
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
class DomainPackLoader:
|
|
13
|
+
"""
|
|
14
|
+
Domain-agnostic loader that allows any team on the platform to define and load
|
|
15
|
+
a Layer 1 `DomainPackSpec` from:
|
|
16
|
+
1. JSON / Dict definitions
|
|
17
|
+
2. Python Pydantic Models (auto-introspecting classes and fields)
|
|
18
|
+
3. W3C OWL / RDFS / SHACL Turtle (`.ttl`) files (via `rdflib` if installed, or fallback parser)
|
|
19
|
+
"""
|
|
20
|
+
|
|
21
|
+
@staticmethod
|
|
22
|
+
def from_dict(data: dict[str, Any]) -> DomainPackSpec:
|
|
23
|
+
"""Loads a DomainPackSpec from a raw dictionary or parsed JSON/YAML payload."""
|
|
24
|
+
relations: dict[str, RelationRule] = {}
|
|
25
|
+
raw_rels = data.get("relations", {})
|
|
26
|
+
if isinstance(raw_rels, list):
|
|
27
|
+
for r in raw_rels:
|
|
28
|
+
rule = RelationRule.model_validate(r)
|
|
29
|
+
relations[rule.predicate] = rule
|
|
30
|
+
elif isinstance(raw_rels, dict):
|
|
31
|
+
for pred, r in raw_rels.items():
|
|
32
|
+
if isinstance(r, RelationRule):
|
|
33
|
+
relations[pred] = r
|
|
34
|
+
else:
|
|
35
|
+
relations[pred] = RelationRule.model_validate({**r, "predicate": pred})
|
|
36
|
+
|
|
37
|
+
disjoint = [tuple(pair) for pair in data.get("disjoint_classes", [])]
|
|
38
|
+
return DomainPackSpec(
|
|
39
|
+
pack_id=data["pack_id"],
|
|
40
|
+
domain_name=data.get("domain_name") or data["pack_id"].split("@")[0],
|
|
41
|
+
version=data.get("version", "1.0.0"),
|
|
42
|
+
classes=data.get("classes", {}),
|
|
43
|
+
disjoint_classes=disjoint,
|
|
44
|
+
relations=relations,
|
|
45
|
+
)
|
|
46
|
+
|
|
47
|
+
@staticmethod
|
|
48
|
+
def from_json_file(path: str | Path) -> DomainPackSpec:
|
|
49
|
+
"""Loads a DomainPackSpec from a JSON file on disk."""
|
|
50
|
+
raw = json.loads(Path(path).read_text(encoding="utf-8"))
|
|
51
|
+
return DomainPackLoader.from_dict(raw)
|
|
52
|
+
|
|
53
|
+
@staticmethod
|
|
54
|
+
def from_pydantic_models(
|
|
55
|
+
pack_id: str,
|
|
56
|
+
entity_models: list[ tuple[Type[BaseModel], UpperConceptType | str] ],
|
|
57
|
+
relations: list[RelationRule] | None = None,
|
|
58
|
+
disjoint_classes: list[tuple[str, str]] | None = None,
|
|
59
|
+
) -> DomainPackSpec:
|
|
60
|
+
"""
|
|
61
|
+
Compiles standard Python Pydantic classes directly into a governed `DomainPackSpec`
|
|
62
|
+
so application teams never need to write raw OWL/SHACL files.
|
|
63
|
+
"""
|
|
64
|
+
domain_name = pack_id.split("@")[0]
|
|
65
|
+
version = pack_id.split("@")[1] if "@" in pack_id else "1.0.0"
|
|
66
|
+
classes: dict[str, str] = {}
|
|
67
|
+
for model_cls, parent in entity_models:
|
|
68
|
+
parent_str = parent.value if isinstance(parent, UpperConceptType) else str(parent)
|
|
69
|
+
classes[model_cls.__name__] = parent_str
|
|
70
|
+
|
|
71
|
+
rel_map = {r.predicate: r for r in (relations or [])}
|
|
72
|
+
return DomainPackSpec(
|
|
73
|
+
pack_id=pack_id,
|
|
74
|
+
domain_name=domain_name,
|
|
75
|
+
version=version,
|
|
76
|
+
classes=classes,
|
|
77
|
+
disjoint_classes=disjoint_classes or [],
|
|
78
|
+
relations=rel_map,
|
|
79
|
+
)
|
|
80
|
+
|
|
81
|
+
@staticmethod
|
|
82
|
+
def from_turtle(
|
|
83
|
+
pack_id: str,
|
|
84
|
+
turtle_content: str,
|
|
85
|
+
) -> DomainPackSpec:
|
|
86
|
+
"""
|
|
87
|
+
Compiles an OWL/RDFS Turtle (`.ttl`) string into a runtime `DomainPackSpec`.
|
|
88
|
+
Uses `rdflib` when available, with a lightweight regex fallback for zero-dependency environments.
|
|
89
|
+
"""
|
|
90
|
+
domain_name = pack_id.split("@")[0]
|
|
91
|
+
version = pack_id.split("@")[1] if "@" in pack_id else "1.0.0"
|
|
92
|
+
classes: dict[str, str] = {}
|
|
93
|
+
disjoint: list[tuple[str, str]] = []
|
|
94
|
+
relations: dict[str, RelationRule] = {}
|
|
95
|
+
|
|
96
|
+
try:
|
|
97
|
+
import rdflib
|
|
98
|
+
from rdflib.namespace import OWL, RDF, RDFS
|
|
99
|
+
|
|
100
|
+
g = rdflib.Graph()
|
|
101
|
+
g.parse(data=turtle_content, format="turtle")
|
|
102
|
+
|
|
103
|
+
def _local_name(uri: Any) -> str:
|
|
104
|
+
s = str(uri)
|
|
105
|
+
if "upper#" in s:
|
|
106
|
+
return f"p:{s.split('#')[-1]}"
|
|
107
|
+
if "#" in s:
|
|
108
|
+
return s.split("#")[-1]
|
|
109
|
+
return s.rsplit("/", 1)[-1]
|
|
110
|
+
|
|
111
|
+
for cls_uri in g.subjects(RDF.type, OWL.Class):
|
|
112
|
+
cls_name = _local_name(cls_uri)
|
|
113
|
+
parent_name = UpperConceptType.CONCEPT.value
|
|
114
|
+
for parent_uri in g.objects(cls_uri, RDFS.subClassOf):
|
|
115
|
+
parent_name = _local_name(parent_uri)
|
|
116
|
+
classes[cls_name] = parent_name
|
|
117
|
+
|
|
118
|
+
for disj_uri in g.objects(cls_uri, OWL.disjointWith):
|
|
119
|
+
disjoint.append((cls_name, _local_name(disj_uri)))
|
|
120
|
+
|
|
121
|
+
for prop_uri in g.subjects(RDF.type, OWL.ObjectProperty):
|
|
122
|
+
label_objs = list(g.objects(prop_uri, RDFS.label))
|
|
123
|
+
pred_name = str(label_objs[0]) if label_objs else _local_name(prop_uri)
|
|
124
|
+
dom_objs = list(g.objects(prop_uri, RDFS.domain))
|
|
125
|
+
rng_objs = list(g.objects(prop_uri, RDFS.range))
|
|
126
|
+
is_func = (prop_uri, RDF.type, OWL.FunctionalProperty) in g
|
|
127
|
+
is_trans = (prop_uri, RDF.type, OWL.TransitiveProperty) in g
|
|
128
|
+
relations[pred_name] = RelationRule(
|
|
129
|
+
predicate=pred_name,
|
|
130
|
+
domain_class=_local_name(dom_objs[0]) if dom_objs else "owl:Thing",
|
|
131
|
+
range_class=_local_name(rng_objs[0]) if rng_objs else "owl:Thing",
|
|
132
|
+
is_functional=is_func,
|
|
133
|
+
is_transitive=is_trans,
|
|
134
|
+
)
|
|
135
|
+
|
|
136
|
+
return DomainPackSpec(
|
|
137
|
+
pack_id=pack_id,
|
|
138
|
+
domain_name=domain_name,
|
|
139
|
+
version=version,
|
|
140
|
+
classes=classes,
|
|
141
|
+
disjoint_classes=disjoint,
|
|
142
|
+
relations=relations,
|
|
143
|
+
)
|
|
144
|
+
except ImportError:
|
|
145
|
+
# Lightweight fallback parser for Turtle syntax when rdflib is not installed
|
|
146
|
+
import re
|
|
147
|
+
|
|
148
|
+
for match in re.finditer(
|
|
149
|
+
r"(?:\w+:)?(\w+)\s+a\s+owl:Class\s*;([^.]*)\.", turtle_content, re.DOTALL
|
|
150
|
+
):
|
|
151
|
+
cls_name = match.group(1)
|
|
152
|
+
body = match.group(2)
|
|
153
|
+
sub_match = re.search(r"rdfs:subClassOf\s+((?:p:|\w+:)?\w+)", body)
|
|
154
|
+
parent = sub_match.group(1) if sub_match else UpperConceptType.CONCEPT.value
|
|
155
|
+
if not parent.startswith("p:") and ":" in parent:
|
|
156
|
+
parent = parent.split(":", 1)[1]
|
|
157
|
+
classes[cls_name] = parent
|
|
158
|
+
for d_match in re.finditer(r"owl:disjointWith\s+([^\n;.]+)", body):
|
|
159
|
+
for target in d_match.group(1).split(","):
|
|
160
|
+
t_clean = target.strip().split(":")[-1]
|
|
161
|
+
if t_clean:
|
|
162
|
+
disjoint.append((cls_name, t_clean))
|
|
163
|
+
|
|
164
|
+
for match in re.finditer(
|
|
165
|
+
r"(?:\w+:)?(\w+)\s+a\s+([^;]+);([^.]*)\.", turtle_content, re.DOTALL
|
|
166
|
+
):
|
|
167
|
+
prop_id, types_str, body = match.group(1), match.group(2), match.group(3)
|
|
168
|
+
if "owl:ObjectProperty" not in types_str:
|
|
169
|
+
continue
|
|
170
|
+
lbl_match = re.search(r'rdfs:label\s+"([^"]+)"', body)
|
|
171
|
+
pred_name = lbl_match.group(1) if lbl_match else prop_id
|
|
172
|
+
dom_match = re.search(r"rdfs:domain\s+(?:\w+:)?(\w+)", body)
|
|
173
|
+
rng_match = re.search(r"rdfs:range\s+(?:\w+:)?(\w+)", body)
|
|
174
|
+
relations[pred_name] = RelationRule(
|
|
175
|
+
predicate=pred_name,
|
|
176
|
+
domain_class=dom_match.group(1) if dom_match else "owl:Thing",
|
|
177
|
+
range_class=rng_match.group(1) if rng_match else "owl:Thing",
|
|
178
|
+
is_functional="owl:FunctionalProperty" in types_str,
|
|
179
|
+
is_transitive="owl:TransitiveProperty" in types_str,
|
|
180
|
+
)
|
|
181
|
+
|
|
182
|
+
return DomainPackSpec(
|
|
183
|
+
pack_id=pack_id,
|
|
184
|
+
domain_name=domain_name,
|
|
185
|
+
version=version,
|
|
186
|
+
classes=classes,
|
|
187
|
+
disjoint_classes=disjoint,
|
|
188
|
+
relations=relations,
|
|
189
|
+
)
|