stable asset queries, lexical search, filters, contextual entity and relationship retrieval, permission-aware fail-closed behavior, source-grounded snippets, feedback capture, and KPI hooks

src/kontextual_engine/core/__init__.py

@@ -40,6 +40,7 @@ from .relationships import (
     CoreRelationship,
     RelationshipTargetKind,
 )
+from .retrieval_feedback import RetrievalFeedbackLabel, RetrievalFeedbackRecord
 
 __all__ = [
     "Actor",
@@ -76,6 +77,8 @@ __all__ = [
     "PolicyEffect",
     "RelationshipTargetKind",
     "RepresentationKind",
+    "RetrievalFeedbackLabel",
+    "RetrievalFeedbackRecord",
     "Sensitivity",
     "SourceReference",
     "SourcePayload",

src/kontextual_engine/core/relationships.py

@@ -19,6 +19,8 @@ class ContextEntityType(str, Enum):
     PROCESS = "process"
     SOURCE_SYSTEM = "source_system"
     TOPIC = "topic"
+    WORKFLOW_RUN = "workflow_run"
+    GENERATED_ARTIFACT = "generated_artifact"
     BUSINESS_OBJECT = "business_object"
 
 

src/kontextual_engine/core/retrieval_feedback.py

@@ -0,0 +1,59 @@
+"""Retrieval feedback and quality signal 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 RetrievalFeedbackLabel(str, Enum):
+    USEFUL = "useful"
+    IRRELEVANT = "irrelevant"
+    MISSING = "missing"
+    UNSAFE = "unsafe"
+    LOW_CONFIDENCE = "low_confidence"
+
+
+@dataclass(frozen=True)
+class RetrievalFeedbackRecord:
+    label: RetrievalFeedbackLabel
+    query: dict[str, Any]
+    result_ref: dict[str, Any]
+    actor_id: str
+    correlation_id: str
+    notes: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+    feedback_id: str = field(default_factory=lambda: new_id("feedback"))
+    created_at: str = field(default_factory=lambda: utc_now().isoformat())
+
+    def to_dict(self) -> dict[str, Any]:
+        return compact_dict(
+            {
+                "feedback_id": self.feedback_id,
+                "label": self.label.value,
+                "query": dict(self.query),
+                "result_ref": dict(self.result_ref),
+                "actor_id": self.actor_id,
+                "correlation_id": self.correlation_id,
+                "notes": self.notes,
+                "metadata": dict(self.metadata),
+                "created_at": self.created_at,
+            }
+        )
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "RetrievalFeedbackRecord":
+        return cls(
+            feedback_id=data["feedback_id"],
+            label=RetrievalFeedbackLabel(data["label"]),
+            query=dict(data.get("query", {})),
+            result_ref=dict(data.get("result_ref", {})),
+            actor_id=data["actor_id"],
+            correlation_id=data["correlation_id"],
+            notes=data.get("notes"),
+            metadata=dict(data.get("metadata", {})),
+            created_at=data["created_at"],
+        )