spine-framework 0.3.107 → 0.3.109

package/.framework/functions/ai-interactions.ts

@@ -0,0 +1,240 @@
+/**
+ * @module ai-interactions
+ * @audience both
+ * @layer api-handler
+ * @stability stable
+ *
+ * Feedback capture and training data API for the AI-first support loop.
+ * Every AI↔human exchange produces a structured interaction record so the
+ * platform can measure loop health, drive KB creation, and accumulate a
+ * proprietary training dataset.
+ *
+ * **Routed by:** `GET/POST/PATCH /.netlify/functions/ai-interactions`
+ *
+ * **Actions:**
+ * | method | ?action                  | handler                  |
+ * |--------|--------------------------|--------------------------|
+ * | POST   | submit_feedback          | submitFeedback           |
+ * | POST   | create_interaction       | createInteraction        |
+ * | PATCH  | update_interaction       | updateInteraction        |
+ * | GET    | list                     | list                     |
+ * | GET    | metrics                  | metrics                  |
+ *
+ * INVARIANT: All writes go through admin-data — no direct DB writes here.
+ * INVARIANT: `submit_feedback` not_helpful triggers ticket escalation
+ *   by updating ticket status to human_assigned.
+ *
+ * @seeAlso agent-runner.ts (populates messages.data.retrieved_sources)
+ * @seeAlso custom/portal/hooks/useTickets.ts (calls submit_feedback)
+ * @seeAlso custom/cortex/functions/custom_case_analysis.ts (calls create_interaction)
+ */
+
+import { createHandler } from './_shared/middleware'
+import { adminDb } from './_shared/db'
+import { resolveTypeId } from './_shared/resolve-ids'
+import { create, update } from './admin-data'
+import { emitLog } from './_shared/audit'
+
+// ─── SUBMIT FEEDBACK ─────────────────────────────────────────────────────────
+/**
+ * Records customer helpful / not_helpful feedback on an AI message.
+ *
+ * - Stamps messages.data.feedback
+ * - If not_helpful: updates ticket to human_assigned + stamps escalation reason
+ * - Updates the matching ai_feedback_record if one exists for this message
+ *
+ * Body: message_id (required), ticket_id (required), feedback ('helpful' | 'not_helpful')
+ */
+export const submitFeedback = createHandler(async (ctx, body) => {
+  const { message_id, ticket_id, feedback } = body || {}
+  if (!message_id) throw new Error('message_id is required')
+  if (!ticket_id)  throw new Error('ticket_id is required')
+  if (!['helpful', 'not_helpful'].includes(feedback)) {
+    throw new Error('feedback must be "helpful" or "not_helpful"')
+  }
+
+  // Stamp feedback on the message — load existing data to merge safely
+  const { data: msg } = await adminDb
+    .from('messages').select('data').eq('id', message_id).single()
+  if (msg) {
+    await adminDb
+      .from('messages')
+      .update({ data: { ...(msg.data || {}), feedback } })
+      .eq('id', message_id)
+  }
+
+  // If not_helpful: escalate the ticket to human support
+  if (feedback === 'not_helpful' && ticket_id) {
+    const { data: ticket } = await adminDb
+      .from('items').select('status, data').eq('id', ticket_id).single()
+    if (ticket && ticket.status !== 'human_assigned' && ticket.status !== 'resolved') {
+      await adminDb
+        .from('items')
+        .update({
+          status: 'human_assigned',
+          data: { ...(ticket.data || {}), aim_escalation_reason: 'thumbs_down' },
+          updated_at: new Date().toISOString(),
+        })
+        .eq('id', ticket_id)
+    }
+  }
+
+  // Best-effort: update matching ai_feedback_record customer_feedback field
+  const { data: interactionRows } = await adminDb
+    .from('items')
+    .select('id, data')
+    .contains('data', { ai_message_id: message_id })
+    .limit(1)
+  if (interactionRows?.length) {
+    const interaction = interactionRows[0]
+    await adminDb
+      .from('items')
+      .update({ data: { ...(interaction.data || {}), customer_feedback: feedback } })
+      .eq('id', interaction.id)
+  }
+
+  await emitLog(ctx, 'ai_interaction.feedback_submitted',
+    { type: 'message', id: message_id },
+    { after: { feedback, ticket_id, escalated: feedback === 'not_helpful' } }
+  )
+
+  return { message_id, ticket_id, feedback, escalated: feedback === 'not_helpful' }
+})
+
+// ─── CREATE INTERACTION ───────────────────────────────────────────────────────
+/**
+ * Creates an ai_feedback_record item capturing a full AI↔human exchange.
+ * Called by the capture_ai_interaction pipeline after each agent message.
+ *
+ * Body: thread_id, ai_message_id, retrieved_sources, ai_confidence,
+ *       retrieval_confidence, kb_candidate (optional)
+ */
+export const createInteraction = createHandler(async (ctx, body) => {
+  const {
+    thread_id, ai_message_id, retrieved_sources = [],
+    ai_confidence, retrieval_confidence, kb_candidate
+  } = body || {}
+
+  if (!thread_id && !ai_message_id) {
+    throw new Error('thread_id or ai_message_id is required')
+  }
+
+  // Resolve the ai_feedback_record type — it lives in the cortex/portal app seeds
+  let typeId: string | null = null
+  try {
+    typeId = await resolveTypeId('item', 'ai_feedback_record')
+  } catch {
+    // Type not yet seeded — skip creation gracefully
+    return { skipped: true, reason: 'ai_feedback_record type not found' }
+  }
+  if (!typeId) return { skipped: true, reason: 'ai_feedback_record type not found' }
+
+  const record = await create(ctx, {
+    entity: 'items',
+    type_id: typeId,
+    title: `AI Interaction — ${new Date().toISOString().slice(0, 10)}`,
+    status: 'active',
+    data: {
+      thread_id:            thread_id || null,
+      ai_message_id:        ai_message_id || null,
+      human_message_id:     null,
+      retrieved_sources:    retrieved_sources,
+      ai_confidence:        ai_confidence ?? null,
+      retrieval_confidence: retrieval_confidence ?? null,
+      human_edits_made:     false,
+      customer_feedback:    null,
+      kb_candidate:         kb_candidate ?? null,
+      kb_article_id:        null,
+      reuse_count:          0,
+    },
+  })
+
+  return record
+})
+
+// ─── UPDATE INTERACTION ───────────────────────────────────────────────────────
+/**
+ * Patches an existing ai_feedback_record.
+ * Used to:
+ * - Link the KB article once a feedback record's question is promoted
+ * - Increment reuse_count when a similar question is AI-answered
+ * - Record human_message_id and human_edits_made after resolution
+ *
+ * Body: id (required), plus any of: kb_article_id, reuse_count,
+ *       human_message_id, human_edits_made, customer_feedback
+ */
+export const updateInteraction = createHandler(async (ctx, body) => {
+  const { id, ...fields } = body || {}
+  if (!id) throw new Error('id is required')
+
+  const allowed = ['kb_article_id', 'human_message_id', 'human_edits_made',
+                   'customer_feedback', 'kb_candidate', 'reuse_count']
+  const patch: Record<string, any> = {}
+  for (const key of allowed) {
+    if (fields[key] !== undefined) patch[key] = fields[key]
+  }
+
+  if (!Object.keys(patch).length) throw new Error('No updatable fields provided')
+
+  // Load existing data then merge
+  const { data: existing } = await adminDb
+    .from('items').select('data').eq('id', id).single()
+  if (!existing) throw new Error('Interaction record not found')
+
+  return update(
+    { ...ctx, query: { ...(ctx.query || {}), entity: 'items', id } } as any,
+    { data: { ...(existing.data || {}), ...patch } }
+  )
+})
+
+// ─── LIST ─────────────────────────────────────────────────────────────────────
+/**
+ * Lists ai_feedback_record items for the current account.
+ * Supports filtering by: feedback, kb_candidate, date_from, date_to
+ */
+export const list = createHandler(async (ctx, _body) => {
+  const { feedback, kb_candidate, limit = '50', offset = '0' } = ctx.query || {}
+
+  let q = ctx.db
+    .from('items')
+    .select('*')
+    .eq('account_id', ctx.accountId)
+    .order('created_at', { ascending: false })
+    .range(Number(offset), Number(offset) + Number(limit) - 1)
+
+  if (feedback) q = q.eq('data->>customer_feedback', feedback)
+  if (kb_candidate !== undefined) q = q.eq('data->>kb_candidate', kb_candidate)
+
+  // Filter to ai_feedback_record type only
+  const { data: typeRow } = await adminDb
+    .from('types').select('id').eq('slug', 'ai_feedback_record').eq('kind', 'item').maybeSingle()
+  if (typeRow?.id) q = q.eq('type_id', typeRow.id)
+
+  const { data, error } = await q
+  if (error) throw error
+  return data || []
+})
+
+// ─── HANDLER ─────────────────────────────────────────────────────────────────
+
+export const handler = createHandler(async (ctx, body) => {
+  const { action } = ctx.query || {}
+  const method = ctx.query?.method || 'GET'
+
+  switch (action) {
+    case 'submit_feedback':
+      if (method === 'POST') return await submitFeedback(ctx, body)
+      break
+    case 'create_interaction':
+      if (method === 'POST') return await createInteraction(ctx, body)
+      break
+    case 'update_interaction':
+      if (method === 'PATCH' || method === 'POST') return await updateInteraction(ctx, body)
+      break
+    case 'list':
+    default:
+      if (method === 'GET') return await list(ctx, body)
+  }
+
+  throw new Error('Invalid action or method')
+})