|
| 1 | +import type { SemanticConfidence, SemanticRelationHint } from "@tomismeta/aperture-core/semantic"; |
| 2 | +import type { FrameLane } from "./frame-model.js"; |
| 3 | +import type { StoredAttentionFrame } from "./types.js"; |
| 4 | + |
| 5 | +export type FrameExplainability = { |
| 6 | + whyNow: string | null; |
| 7 | + laneReason: string; |
| 8 | + signalStrength: SemanticConfidence | null; |
| 9 | + signals: string[]; |
| 10 | + relationLabels: string[]; |
| 11 | + continuity: string | null; |
| 12 | +}; |
| 13 | + |
| 14 | +function asRecord(value: unknown): Record<string, unknown> | null { |
| 15 | + return typeof value === "object" && value !== null && !Array.isArray(value) |
| 16 | + ? value as Record<string, unknown> |
| 17 | + : null; |
| 18 | +} |
| 19 | + |
| 20 | +function readStringArray(value: unknown): string[] { |
| 21 | + if (!Array.isArray(value)) return []; |
| 22 | + return value.filter((entry): entry is string => typeof entry === "string" && entry.trim().length > 0); |
| 23 | +} |
| 24 | + |
| 25 | +function readSemanticConfidence(frame: StoredAttentionFrame): SemanticConfidence | null { |
| 26 | + const semantic = asRecord(frame.metadata?.semantic); |
| 27 | + const confidence = semantic?.confidence; |
| 28 | + return confidence === "low" || confidence === "medium" || confidence === "high" ? confidence : null; |
| 29 | +} |
| 30 | + |
| 31 | +function readSemanticRelationHints(frame: StoredAttentionFrame): SemanticRelationHint[] { |
| 32 | + const semantic = asRecord(frame.metadata?.semantic); |
| 33 | + const relationHints = semantic?.relationHints; |
| 34 | + if (!Array.isArray(relationHints)) return []; |
| 35 | + |
| 36 | + return relationHints.filter((entry): entry is SemanticRelationHint => { |
| 37 | + if (typeof entry !== "object" || entry === null) return false; |
| 38 | + const hint = entry as Record<string, unknown>; |
| 39 | + return ( |
| 40 | + hint.kind === "same_issue" |
| 41 | + || hint.kind === "resolves" |
| 42 | + || hint.kind === "supersedes" |
| 43 | + || hint.kind === "repeats" |
| 44 | + || hint.kind === "escalates" |
| 45 | + ); |
| 46 | + }); |
| 47 | +} |
| 48 | + |
| 49 | +function relationHintLabel(hint: SemanticRelationHint): string { |
| 50 | + switch (hint.kind) { |
| 51 | + case "same_issue": |
| 52 | + return "Part of the same thread"; |
| 53 | + case "resolves": |
| 54 | + return "Resolves an earlier blocker"; |
| 55 | + case "supersedes": |
| 56 | + return "Moves the request forward"; |
| 57 | + case "repeats": |
| 58 | + return "Repeats an earlier ask"; |
| 59 | + case "escalates": |
| 60 | + return "Raises the urgency"; |
| 61 | + } |
| 62 | +} |
| 63 | + |
| 64 | +function laneReason(lane: FrameLane): string { |
| 65 | + switch (lane) { |
| 66 | + case "active": |
| 67 | + return "This is the most urgent item in the queue right now."; |
| 68 | + case "queued": |
| 69 | + return "This is queued behind the current top item."; |
| 70 | + case "ambient": |
| 71 | + return "This is visible for awareness without needing action yet."; |
| 72 | + } |
| 73 | +} |
| 74 | + |
| 75 | +function continuitySummary(frame: StoredAttentionFrame): string | null { |
| 76 | + const episode = asRecord(frame.metadata?.episode); |
| 77 | + const size = typeof episode?.size === "number" ? episode.size : null; |
| 78 | + const state = typeof episode?.state === "string" ? episode.state.replace(/_/g, " ") : null; |
| 79 | + |
| 80 | + if (!size || size <= 1) return null; |
| 81 | + if (state) return `Part of a ${state} thread with ${size} related interactions.`; |
| 82 | + return `Part of a thread with ${size} related interactions.`; |
| 83 | +} |
| 84 | + |
| 85 | +function frameSignals(frame: StoredAttentionFrame): string[] { |
| 86 | + const attention = asRecord(frame.metadata?.attention); |
| 87 | + const rationale = readStringArray(attention?.rationale); |
| 88 | + const factors = readStringArray(frame.provenance?.factors); |
| 89 | + return [...new Set([...(rationale.length > 0 ? rationale : factors), ...factors])]; |
| 90 | +} |
| 91 | + |
| 92 | +export function signalStrengthLabel(confidence: SemanticConfidence): string { |
| 93 | + return `${confidence} confidence`; |
| 94 | +} |
| 95 | + |
| 96 | +export function explainFrame(frame: StoredAttentionFrame, lane: FrameLane): FrameExplainability { |
| 97 | + const relationLabels = [...new Set(readSemanticRelationHints(frame).map(relationHintLabel))]; |
| 98 | + |
| 99 | + return { |
| 100 | + whyNow: frame.provenance?.whyNow ?? frame.summary ?? null, |
| 101 | + laneReason: laneReason(lane), |
| 102 | + signalStrength: readSemanticConfidence(frame), |
| 103 | + signals: frameSignals(frame), |
| 104 | + relationLabels, |
| 105 | + continuity: continuitySummary(frame), |
| 106 | + }; |
| 107 | +} |
0 commit comments