truth-hitl: support enhanced review payload shapes for UI (#389)

Author: Cataldir

apps/truth-hitl/src/truth_hitl/review_manager.py

@@ -7,6 +7,9 @@
 
 from pydantic import BaseModel
 
+ReasoningPayload = str | list[str] | dict[str, Any] | list[dict[str, Any]]
+SourceAssetPayload = str | dict[str, Any]
+
 
 class ReviewItem(BaseModel):
     """A proposed attribute pending human review."""
@@ -27,8 +30,8 @@ class ReviewItem(BaseModel):
     reviewed_by: str | None = None
     original_data: dict[str, Any] | None = None
     enriched_data: dict[str, Any] | None = None
-    reasoning: str | None = None
-    source_assets: list[dict[str, Any]] | None = None
+    reasoning: ReasoningPayload | None = None
+    source_assets: list[SourceAssetPayload] | None = None
     source_type: str | None = None
 
 
@@ -55,8 +58,8 @@ class AuditEvent(BaseModel):
     timestamp: datetime
     original_data: dict[str, Any] | None = None
     enriched_data: dict[str, Any] | None = None
-    reasoning: str | None = None
-    source_assets: list[dict[str, Any]] | None = None
+    reasoning: ReasoningPayload | None = None
+    source_assets: list[SourceAssetPayload] | None = None
     source_type: str | None = None
 
 

apps/truth-hitl/tests/test_event_handlers.py

@@ -5,7 +5,9 @@
 import json
 
 import pytest
-from truth_hitl.event_handlers import build_event_handlers
+import truth_hitl.event_handlers as event_handlers
+from truth_hitl.adapters import build_hitl_adapters
+from truth_hitl.review_manager import ReviewManager
 
 
 class FakeEvent:
@@ -20,7 +22,7 @@ def body_as_str(self) -> str:
 
 @pytest.mark.asyncio
 async def test_handle_hitl_job_enqueues_item():
-    handlers = build_event_handlers()
+    handlers = event_handlers.build_event_handlers()
     handler = handlers["hitl-jobs"]
 
     payload = {
@@ -44,7 +46,7 @@ async def test_handle_hitl_job_enqueues_item():
 
 @pytest.mark.asyncio
 async def test_handle_hitl_job_skips_missing_entity_id():
-    handlers = build_event_handlers()
+    handlers = event_handlers.build_event_handlers()
     handler = handlers["hitl-jobs"]
 
     payload = {
@@ -57,7 +59,7 @@ async def test_handle_hitl_job_skips_missing_entity_id():
 
 @pytest.mark.asyncio
 async def test_handle_hitl_job_skips_missing_attr_id():
-    handlers = build_event_handlers()
+    handlers = event_handlers.build_event_handlers()
     handler = handlers["hitl-jobs"]
 
     payload = {
@@ -68,5 +70,62 @@ async def test_handle_hitl_job_skips_missing_attr_id():
 
 
 def test_build_event_handlers_includes_hitl_jobs():
-    handlers = build_event_handlers()
+    handlers = event_handlers.build_event_handlers()
     assert "hitl-jobs" in handlers
+
+
+@pytest.mark.asyncio
+async def test_handle_hitl_job_accepts_enhanced_ui_payload_shapes(monkeypatch):
+    review_manager = ReviewManager()
+
+    def _stub_build_hitl_adapters():
+        return build_hitl_adapters(review_manager=review_manager)
+
+    monkeypatch.setattr(event_handlers, "build_hitl_adapters", _stub_build_hitl_adapters)
+
+    handlers = event_handlers.build_event_handlers()
+    handler = handlers["hitl-jobs"]
+
+    payload = {
+        "event_type": "proposed_attribute",
+        "data": {
+            "entity_id": "prod-100",
+            "attr_id": "attr-200",
+            "field_name": "material",
+            "proposed_value": "Organic Cotton",
+            "confidence": 0.92,
+            "source": "ai",
+            "product_title": "Heritage Shirt",
+            "category_label": "Apparel",
+            "reasoning": [
+                "Image texture suggests cotton",
+                "Catalog title includes 'cotton'",
+            ],
+            "source_assets": [
+                "https://cdn.example.com/products/prod-100/front.jpg",
+                {
+                    "url": "https://cdn.example.com/products/prod-100/zoom.jpg",
+                    "asset_id": "dam-200",
+                    "kind": "image",
+                },
+            ],
+            "source_type": "hybrid",
+        },
+    }
+
+    await handler(None, FakeEvent(payload))
+
+    queued = review_manager.get_by_entity("prod-100")
+    assert len(queued) == 1
+    assert queued[0].reasoning == [
+        "Image texture suggests cotton",
+        "Catalog title includes 'cotton'",
+    ]
+    assert queued[0].source_assets == [
+        "https://cdn.example.com/products/prod-100/front.jpg",
+        {
+            "url": "https://cdn.example.com/products/prod-100/zoom.jpg",
+            "asset_id": "dam-200",
+            "kind": "image",
+        },
+    ]

docs/implementation/truth-layer-api.md

@@ -275,6 +275,45 @@ When available, proposal payloads include enrichment context fields for reviewer
 
 These fields are optional for backward compatibility with older proposals.
 
+For enhanced review UI support, `reasoning` and `source_assets` accept richer shapes:
+
+- `reasoning`: string, list of strings, or structured reasoning objects.
+- `source_assets`: list containing DAM image URLs and/or structured asset metadata objects.
+
+### Example MCP response: `/review/get_proposal`
+
+```json
+{
+  "entity_id": "prod-100",
+  "proposal": {
+    "entity_id": "prod-100",
+    "attr_id": "attr-200",
+    "field_name": "material",
+    "proposed_value": "Organic Cotton",
+    "current_value": null,
+    "original_data": {
+      "material": null
+    },
+    "enriched_data": {
+      "material": "Organic Cotton"
+    },
+    "reasoning": [
+      "Image texture suggests cotton",
+      "Catalog title includes 'cotton'"
+    ],
+    "source_assets": [
+      "https://cdn.example.com/products/prod-100/front.jpg",
+      {
+        "asset_id": "dam-200",
+        "url": "https://cdn.example.com/products/prod-100/zoom.jpg",
+        "kind": "image"
+      }
+    ],
+    "source_type": "hybrid"
+  }
+}
+```
+
 ### HITL Decision Gate in the Notebook
 
 - Queue observation occurs in `Stage 8 - HITL Queue Observation` using Truth HITL `stats` and `list` actions.