Customer Support Answer

1// Customer Support Answer — customer support module
2//
3// The pipeline:
4//
5//   support.intake    normalise the ticket, score it, decide who answers
6//   support.answer    reply from the knowledge base, or from the LLM
7//   support.escalate  hand to a human, with the reason recorded
8//
9// Each stage is a task, so each retries independently and survives a restart.
10//
11// The decision in intake is the product:
12//
13//   score >= confidence_threshold   answer from the knowledge base
14//   score <  threshold, LLM on      ask the LLM, with the best KB entries as
15//                                   context; on ANY failure fall back to the
16//                                   knowledge base, and escalate if even that
17//                                   is below the floor
18//   score <  threshold, LLM off     escalate
19//
20// Nothing here returns a low-scoring canned answer as though it were a
21// confident one, and nothing here invents an answer when the model is down.
22 
23#include <algorithm>
24#include <atomic>
25#include <cstdint>
26#include <filesystem>
27#include <fstream>
28#include <mutex>
29#include <string>
30#include <vector>
31 
32#include "bs9/agent.hpp"
33#include "bs9/http.hpp"
34#include "bs9/json.hpp"
35#include "bs9/llm.hpp"
36#include "bs9/log.hpp"
37#include "bs9/metrics.hpp"
38#include "bs9/scheduler.hpp"
39 
40#include "support.hpp"
41 
42namespace fs = std::filesystem;
43 
44namespace {
45 
46constexpr const char* kIntake = "support.intake";
47constexpr const char* kAnswer = "support.answer";
48constexpr const char* kEscalate = "support.escalate";
49constexpr const char* kScope = "support";
50 
51struct Runtime {
52  support::Settings settings;
53  support::KnowledgeBase kb;
54  bs9::LlmConfig llm;
55  std::string kb_error;
56  std::string llm_error;
57  std::string transcript_path;
58  std::mutex transcript_mutex;
59};
60 
61Runtime& runtime() {
62  static Runtime instance;
63  return instance;
64}
65 
66std::uint64_t minutes_to_us(int minutes) {
67  return static_cast<std::uint64_t>(minutes) * 60ull * 1'000'000ull;
68}
69 
70std::string next_id(const char* prefix) {
71  static std::atomic<std::uint64_t> counter{0};
72  return std::string(prefix) + "-" + std::to_string(bs9::now_micros()) + "-" +
73         std::to_string(counter.fetch_add(1));
74}
75 
76/// One JSONL line per resolved or escalated ticket.
77///
78/// The ticket body is omitted unless the buyer opts in
79/// (`transcript_include_body`). A transcript gets copied into spreadsheets and
80/// support reviews far more readily than a ticket store does, and the body is
81/// the field most likely to carry personal data.
82void append_transcript(const bs9::Json& record) {
83  Runtime& rt = runtime();
84  if (rt.transcript_path.empty()) return;
85  const std::lock_guard<std::mutex> lock(rt.transcript_mutex);
86  std::ofstream out(rt.transcript_path, std::ios::app);
87  if (!out.good()) {
88    bs9::log_warn(kScope, "could not append to transcript " + rt.transcript_path);
89    return;
90  }
91  out << record.serialise(0) << "\n";
92}
93 
94bs9::Json ticket_summary(const support::Ticket& ticket) {
95  bs9::Json out{bs9::JsonObject{}};
96  out.set("ticket_id", ticket.id);
97  out.set("customer", ticket.customer);
98  out.set("channel", ticket.channel);
99  out.set("subject", ticket.subject);
100  // Length, not content, unless explicitly enabled.