Architecture core for Knowledge Assets

src/kontextual_engine/core/relationships.py

@@ -0,0 +1,82 @@
+"""Context entity and typed relationship primitives."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+from .primitives import compact_dict, new_id, utc_now
+
+
+class ContextEntityType(str, Enum):
+    PERSON = "person"
+    TEAM = "team"
+    PROJECT = "project"
+    CASE = "case"
+    CUSTOMER = "customer"
+    PRODUCT = "product"
+    PROCESS = "process"
+    SOURCE_SYSTEM = "source_system"
+    TOPIC = "topic"
+    BUSINESS_OBJECT = "business_object"
+
+
+@dataclass(frozen=True)
+class ContextEntity:
+    entity_type: ContextEntityType
+    name: str
+    external_ref: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+    entity_id: str = field(default_factory=lambda: new_id("entity"))
+
+    def to_dict(self) -> dict[str, Any]:
+        return compact_dict(
+            {
+                "entity_id": self.entity_id,
+                "entity_type": self.entity_type.value,
+                "name": self.name,
+                "external_ref": self.external_ref,
+                "metadata": dict(self.metadata),
+            }
+        )
+
+
+class RelationshipTargetKind(str, Enum):
+    ASSET = "asset"
+    CONTEXT_ENTITY = "context_entity"
+
+
+@dataclass(frozen=True)
+class CoreRelationship:
+    source_id: str
+    target_id: str
+    predicate: str
+    target_kind: RelationshipTargetKind = RelationshipTargetKind.ASSET
+    direction: str = "outbound"
+    confidence: float | None = None
+    valid_from: str | None = None
+    valid_to: str | None = None
+    actor_id: str | None = None
+    provenance: dict[str, Any] = field(default_factory=dict)
+    relationship_id: str = field(default_factory=lambda: new_id("rel"))
+    created_at: str = field(default_factory=lambda: utc_now().isoformat())
+
+    def to_dict(self) -> dict[str, Any]:
+        return compact_dict(
+            {
+                "relationship_id": self.relationship_id,
+                "source_id": self.source_id,
+                "target_id": self.target_id,
+                "predicate": self.predicate,
+                "target_kind": self.target_kind.value,
+                "direction": self.direction,
+                "confidence": self.confidence,
+                "valid_from": self.valid_from,
+                "valid_to": self.valid_to,
+                "actor_id": self.actor_id,
+                "provenance": dict(self.provenance),
+                "created_at": self.created_at,
+            }
+        )
+