관리자 감정 관측 기록과 조회 API 추가

apps/api/app/services/client_affect.py

@@ -6,6 +6,12 @@ import math
 from dataclasses import dataclass
 from typing import Any, Iterable, Mapping
 
+from ..contracts.client_affect import (
+    ClientAffectContextV1,
+    ClientAffectDimensionTraceV1,
+    ClientAffectPolicyV1,
+    ClientAffectTraceV1,
+)
 from . import guardrail
 from .jev_client import AppraisalResult, EMOTION_DIMENSIONS
 
@@ -40,7 +46,13 @@ _NEGATIVE_EMOTIONS = frozenset(
     {"anxiety", "sadness", "anger", "shame", "guilt", "loneliness"}
 )
 _POSITIVE_EMOTIONS = frozenset({"relief", "hope", "trust"})
+_AFFECT_POLICY_VERSION = "jev-affect-v1"
+_ACCEPTED_ALPHA = 0.35
+_ACCEPTED_CAP = 0.15
+_TENTATIVE_ALPHA = 0.15
+_TENTATIVE_CAP = 0.075
 _TENTATIVE_CONFIDENCE_FLOOR = 0.35
+_ADJACENT_PROBABILITY_THRESHOLD = 0.8
 _PROBABILITY_SUM_TOLERANCE = 0.025000001
 
 
@@ -83,7 +95,10 @@ def _tentative_distribution_is_concentrated(probabilities: Any) -> bool:
     if not math.isclose(total, 1.0, abs_tol=_PROBABILITY_SUM_TOLERANCE):
         return False
     normalized = tuple(value / total for value in values if value is not None)
-    return max(normalized[index] + normalized[index + 1] for index in range(4)) >= 0.80
+    return (
+        max(normalized[index] + normalized[index + 1] for index in range(4))
+        >= _ADJACENT_PROBABILITY_THRESHOLD
+    )
 
 
 def _baseline_value(affect_baseline: Mapping[str, Any], key: str) -> float | None:
@@ -163,15 +178,15 @@ def transition_emotions(
             held.append(dimension)
             continue
         if confidence >= threshold:
-            alpha = 0.35
-            cap = 0.15
+            alpha = _ACCEPTED_ALPHA
+            cap = _ACCEPTED_CAP
         elif (
             confidence >= _TENTATIVE_CONFIDENCE_FLOOR
             and _tentative_distribution_is_concentrated(estimate.probabilities)
         ):
             # confidence는 정답 확률이 아니라 분포 집중도 요약이다.
-            alpha = 0.15
-            cap = 0.075
+            alpha = _TENTATIVE_ALPHA
+            cap = _TENTATIVE_CAP
             tentative.append(dimension)
         else:
             updated[f"emotion_{dimension}"] = old
@@ -189,6 +204,94 @@ def transition_emotions(
     )
 
 
+def _trace_probabilities(value: Any) -> tuple[float, float, float, float, float] | None:
+    if not isinstance(value, tuple) or len(value) != 5:
+        return None
+    normalized = tuple(_unit_number(item) for item in value)
+    if any(item is None for item in normalized):
+        return None
+    return (
+        normalized[0],
+        normalized[1],
+        normalized[2],
+        normalized[3],
+        normalized[4],
+    )
+
+
+def build_client_affect_trace(
+    *,
+    affect_state_before: Mapping[str, Any],
+    affect_baseline: Mapping[str, Any],
+    affect_state_after: Mapping[str, Any],
+    appraisal: AppraisalResult,
+    transition: AffectTransition,
+    turn_seq: int,
+    stage: str,
+    resistance: float,
+    effective_openness: float,
+    rapport_credit: float,
+    min_confidence: float,
+) -> ClientAffectTraceV1:
+    """전이와 같은 입력으로 관리자 전용 trace를 고정 순서로 만든다."""
+    before = resolve_emotions(affect_state_before, affect_baseline)
+    after = resolve_emotions(affect_state_after, affect_baseline)
+    tentative = set(transition.tentative_dimensions)
+    accepted = set(transition.accepted_dimensions)
+    dimensions: list[ClientAffectDimensionTraceV1] = []
+    for key in EMOTION_DIMENSIONS:
+        estimate = appraisal.emotions.get(key)
+        target = _unit_number(estimate.score) if estimate is not None else None
+        confidence = _unit_number(estimate.confidence) if estimate is not None else None
+        probabilities = (
+            _trace_probabilities(estimate.probabilities) if estimate is not None else None
+        )
+        if key in tentative:
+            decision = "tentative"
+        elif key in accepted:
+            decision = "accepted"
+        else:
+            decision = "held"
+        dimensions.append(
+            ClientAffectDimensionTraceV1(
+                key=key,
+                before=before[key],
+                target=target,
+                after=after[key],
+                confidence=confidence,
+                probabilities=probabilities,
+                decision=decision,
+            )
+        )
+    return ClientAffectTraceV1(
+        schema_version=1,
+        provider=appraisal.provider,
+        model=appraisal.model,
+        latency_ms=appraisal.latency_ms,
+        input_tokens=appraisal.input_tokens,
+        output_tokens=appraisal.output_tokens,
+        cost_usd=appraisal.cost_usd,
+        turn_seq=turn_seq,
+        policy=ClientAffectPolicyV1(
+            version=_AFFECT_POLICY_VERSION,
+            min_confidence=min_confidence,
+            accepted_alpha=_ACCEPTED_ALPHA,
+            accepted_cap=_ACCEPTED_CAP,
+            tentative_alpha=_TENTATIVE_ALPHA,
+            tentative_cap=_TENTATIVE_CAP,
+            tentative_confidence_floor=_TENTATIVE_CONFIDENCE_FLOOR,
+            adjacent_probability_threshold=_ADJACENT_PROBABILITY_THRESHOLD,
+        ),
+        context=ClientAffectContextV1(
+            stage=stage,
+            resistance=resistance,
+            effective_openness=effective_openness,
+            rapport_credit=rapport_credit,
+        ),
+        dimensions=tuple(dimensions),
+    )
+
+
 def _mask_text(
     value: Any,
     *,
@@ -384,6 +487,7 @@ def public_end_state(end_state: Mapping[str, Any]) -> dict[str, Any]:
 __all__ = [
     "AffectTransition",
     "baseline_emotions",
+    "build_client_affect_trace",
     "build_appraisal_state",
     "public_end_state",
     "resolve_emotions",