conversationTopics.ts

import type {
  AnalyticsApi,
  Models,
  SpeechTextAnalyticsApi,
} from "purecloud-platform-client-v2";
import { z } from "zod";
import { createTool, type ToolFactory } from "../utils/createTool.js";
import { errorResult } from "../utils/errorResult.js";
import { isUnauthorisedError } from "../utils/genesys/isUnauthorisedError.js";
import { chunks } from "./chunks.js";

export interface ToolDependencies {
  readonly speechTextAnalyticsApi: Pick<
    SpeechTextAnalyticsApi,
    "getSpeechandtextanalyticsTopics"
  >;
  readonly analyticsApi: Pick<
    AnalyticsApi,
    | "getAnalyticsConversationDetails"
    | "postAnalyticsTranscriptsAggregatesQuery"
  >;
}

const MAX_IDS_ALLOWED_BY_API = 50;

const paramsSchema = z.object({
  conversationId: z
    .string()
    .uuid()
    .describe(
      "A UUID for a conversation. (e.g., 00000000-0000-0000-0000-000000000000)",
    ),
});

export const conversationTopics: ToolFactory<
  ToolDependencies,
  typeof paramsSchema
> = ({ speechTextAnalyticsApi, analyticsApi }) =>
  createTool({
    schema: {
      name: "conversation_topics",
      annotations: { title: "Conversation Topics" },
      description:
        "Retrieves Speech and Text Analytics topics detected for a specific conversation. Topics represent business-level intents (e.g. cancellation, billing enquiry) inferred from recognised phrases in the customer-agent interaction.",
      paramsSchema,
    },
    call: async ({ conversationId }) => {
      let conversationDetails: Models.AnalyticsConversationWithoutAttributes;

      try {
        conversationDetails =
          await analyticsApi.getAnalyticsConversationDetails(conversationId);
      } catch (error: unknown) {
        const errorMessage = isUnauthorisedError(error)
          ? "Failed to retrieve conversation topics: Unauthorised access. Please check API credentials or permissions"
          : `Failed to retrieve conversation topics: ${error instanceof Error ? error.message : JSON.stringify(error)}`;

        return errorResult(errorMessage);
      }

      if (
        !conversationDetails.conversationStart ||
        !conversationDetails.conversationEnd
      ) {
        return errorResult(
          "Unable to find conversation Start and End date needed for retrieving topics",
        );
      }

      // Widen the time range either side to ensure the conversation timeframe is enclosed.
      // Conversation not returned if either only partially covered by interval, or matched exactly.
      const startDate = new Date(conversationDetails.conversationStart);
      startDate.setMinutes(startDate.getMinutes() - 10);

      const endDate = new Date(conversationDetails.conversationEnd);
      endDate.setMinutes(endDate.getMinutes() + 10);

      let jobDetails: Models.TranscriptAggregateQueryResponse;
      try {
        jobDetails = await analyticsApi.postAnalyticsTranscriptsAggregatesQuery(
          {
            interval: `${startDate.toISOString()}/${endDate.toISOString()}`,
            filter: {
              type: "and",
              predicates: [
                {
                  dimension: "conversationId",
                  value: conversationId,
                },
                {
                  dimension: "resultsBy",
                  value: "communication",
                },
              ],
            },
            groupBy: ["topicId"],
            metrics: ["nTopicCommunications"],
          },
        );
      } catch (error: unknown) {
        const errorMessage = isUnauthorisedError(error)
          ? "Failed to retrieve conversation topics: Unauthorised access. Please check API credentials or permissions"
          : `Failed to retrieve conversation topics: ${error instanceof Error ? error.message : JSON.stringify(error)}`;

        return errorResult(errorMessage);
      }

      const topicIds = new Set<string>();

      for (const result of jobDetails.results ?? []) {
        if (result.group?.topicId) {
          topicIds.add(result.group.topicId);
        }
      }

      if (topicIds.size === 0) {
        return {
          content: [
            {
              type: "text",
              text: `Conversation ID: ${conversationId}\nNo detected topics for this conversation.`,
            },
          ],
        };
      }

      const topics: Models.ListedTopic[] = [];

      try {
        for (const topicIdChunk of chunks(
          Array.from(topicIds.values()),
          MAX_IDS_ALLOWED_BY_API,
        )) {
          const topicsListings =
            await speechTextAnalyticsApi.getSpeechandtextanalyticsTopics({
              ids: topicIdChunk,
              pageSize: MAX_IDS_ALLOWED_BY_API,
            });

          topics.push(...(topicsListings.entities ?? []));
        }
      } catch (error: unknown) {
        const errorMessage = isUnauthorisedError(error)
          ? "Failed to retrieve conversation topics: Unauthorised access. Please check API credentials or permissions"
          : `Failed to retrieve conversation topics: ${error instanceof Error ? error.message : JSON.stringify(error)}`;

        return errorResult(errorMessage);
      }

      const topicNames = topics
        .filter((topic) => topic.name && topic.description)
        .map(({ name, description }) => ({
          name: name ?? "",
          description: description ?? "",
        }));

      return {
        content: [
          {
            type: "text",
            text: JSON.stringify({
              conversationId: conversationId,
              detectedTopics: topicNames,
            }),
          },
        ],
      };
    },
  });