@cms.ai/brand_brain 0.0.1 → 0.1.0

package/src/skill-state.ts

@@ -0,0 +1,206 @@
+import { GuideEvent, SkillResponseType } from "./types";
+import type {
+  BusinessCaseDraftRef,
+  BusinessCaseFormatOption,
+  ContentRecommendation,
+  DiagnoseSubtypeName,
+  DiagnosticHeader,
+  DiagnosticQuestion,
+  GuideDocument,
+  GuideSkillEvent,
+  HowToOutline,
+  HowToStep,
+  PlaylistHeader,
+  PlaylistItem,
+  SkillCTA,
+  SkillRecommendation,
+  SkillResponseTypeType,
+  SolutionDesignEdge,
+  SolutionDesignHeader,
+  SolutionDesignNode,
+} from "./types";
+
+/**
+ * Renderable state for one skill turn, folded from the `skill` events of a
+ * single {@link GuideClient.ask} stream. Which fields fill in depends on
+ * `skill`; everything else stays at its empty default:
+ *
+ * - `answer`:         `documents`, `followUpRecommendations`, `ctas`
+ * - `recommend`:      `contentRecommendations`, `ctas`
+ * - `diagnose`:       `diagnoseHeader`, `diagnoseQuestions`
+ * - `playlist`:       `playlistHeader`, `playlistItems`
+ * - `howto`:          `howToOutline` (render first), then `howToSteps`
+ * - `businesscase`:   `businessCaseFormats`/`businessCaseDrafts` (chooser), then
+ *                     `businessCaseContent[subType]` markdown as a format streams
+ * - `solutiondesign`: `solutionDesignHeader`, `solutionDesignNodes`/`Edges`
+ */
+export interface GuideSkillTurn {
+  /** Which skill this turn ran. Null until `skill_start` arrives. */
+  skill: SkillResponseTypeType | null;
+  /** `streaming` until `skill_end`. */
+  status: "streaming" | "complete";
+  /** The assistant message this skill output belongs to. */
+  messageId: string | null;
+  /** Diagnose mode — `context_gathering` runs `followUpSkill` after answers are submitted. */
+  diagnoseSubtype: DiagnoseSubtypeName | null;
+  followUpSkill: string | null;
+  /** Accumulated long-form markdown body (`skill_content` deltas). */
+  content: string;
+  /** Source documents behind the reply — render as citation/source cards. */
+  documents: GuideDocument[];
+  /** The recommend skill's content cards. */
+  contentRecommendations: ContentRecommendation[];
+  /** Post-answer follow-up pills — `ask(prompt, { forcedSkill: skill })` on click. */
+  followUpRecommendations: SkillRecommendation[];
+  /** Calls-to-action — render the first below the response. */
+  ctas: SkillCTA[];
+  diagnoseHeader: DiagnosticHeader | null;
+  diagnoseQuestions: DiagnosticQuestion[];
+  playlistHeader: PlaylistHeader | null;
+  playlistItems: PlaylistItem[];
+  howToOutline: HowToOutline | null;
+  howToSteps: HowToStep[];
+  businessCaseFormats: BusinessCaseFormatOption[];
+  businessCaseDrafts: Record<string, BusinessCaseDraftRef>;
+  /** Accumulated draft markdown per business case subType. */
+  businessCaseContent: Record<string, string>;
+  solutionDesignHeader: SolutionDesignHeader | null;
+  solutionDesignNodes: SolutionDesignNode[];
+  solutionDesignEdges: SolutionDesignEdge[];
+  /** Persisted deliverable id (for `client.skills.get`/`update`), set on `skill_end`. */
+  skillInstanceId: string | null;
+}
+
+/** A fresh, empty turn state. */
+export function createSkillTurn(): GuideSkillTurn {
+  return {
+    skill: null,
+    status: "streaming",
+    messageId: null,
+    diagnoseSubtype: null,
+    followUpSkill: null,
+    content: "",
+    documents: [],
+    contentRecommendations: [],
+    followUpRecommendations: [],
+    ctas: [],
+    diagnoseHeader: null,
+    diagnoseQuestions: [],
+    playlistHeader: null,
+    playlistItems: [],
+    howToOutline: null,
+    howToSteps: [],
+    businessCaseFormats: [],
+    businessCaseDrafts: {},
+    businessCaseContent: {},
+    solutionDesignHeader: null,
+    solutionDesignNodes: [],
+    solutionDesignEdges: [],
+    skillInstanceId: null,
+  };
+}
+
+/** A recommendations payload is content cards iff its entries carry `targetSkill`. */
+function isContentRecommendations(
+  recommendations: ContentRecommendation[] | SkillRecommendation[],
+): recommendations is ContentRecommendation[] {
+  return recommendations.length > 0 && "targetSkill" in recommendations[0];
+}
+
+/**
+ * Fold one `skill` stream event into the turn state. Pure and immutable — the
+ * returned object is a new reference whenever anything changed, so the result
+ * can back React state directly:
+ *
+ * ```ts
+ * let turn = createSkillTurn();
+ * for await (const event of client.ask(message)) {
+ *   if (event.type === "skill") turn = reduceSkillEvent(turn, event);
+ * }
+ * ```
+ */
+export function reduceSkillEvent(turn: GuideSkillTurn, event: GuideSkillEvent): GuideSkillTurn {
+  switch (event.name) {
+    case GuideEvent.SkillStart: {
+      // A business case turn continues across skill_start when the visitor picks
+      // a format from the chooser — preserve the chooser + accumulated drafts.
+      const continuesBusinessCase =
+        event.value.skill === SkillResponseType.BusinessCase && turn.skill === SkillResponseType.BusinessCase;
+      const base = continuesBusinessCase
+        ? {
+            ...createSkillTurn(),
+            businessCaseFormats: turn.businessCaseFormats,
+            businessCaseDrafts: turn.businessCaseDrafts,
+            businessCaseContent: turn.businessCaseContent,
+          }
+        : createSkillTurn();
+      return {
+        ...base,
+        skill: event.value.skill,
+        messageId: event.value.messageId,
+        diagnoseSubtype: event.value.diagnoseSubtype ?? null,
+        followUpSkill: event.value.followUpSkill ?? null,
+      };
+    }
+    case GuideEvent.SkillContent:
+      return { ...turn, content: turn.content + event.value.delta };
+    case GuideEvent.SkillDocuments:
+      return { ...turn, documents: event.value.documents };
+    case GuideEvent.SkillRecommendations:
+      return isContentRecommendations(event.value.recommendations)
+        ? { ...turn, contentRecommendations: event.value.recommendations }
+        : { ...turn, followUpRecommendations: event.value.recommendations };
+    case GuideEvent.SkillCTAs:
+      return { ...turn, ctas: event.value.ctas };
+    case GuideEvent.SkillDiagnoseHeader:
+      return { ...turn, diagnoseHeader: event.value.header };
+    case GuideEvent.SkillDiagnoseQuestion:
+      return { ...turn, diagnoseQuestions: [...turn.diagnoseQuestions, event.value.question] };
+    case GuideEvent.SkillPlaylistHeader:
+      return { ...turn, playlistHeader: event.value.header };
+    case GuideEvent.SkillPlaylistItems:
+      return { ...turn, playlistItems: event.value.items };
+    case GuideEvent.SkillPlaylistRationale:
+      return {
+        ...turn,
+        playlistItems: turn.playlistItems.map((item) =>
+          item.id === event.value.itemId ? { ...item, rationale: event.value.rationale } : item,
+        ),
+      };
+    case GuideEvent.SkillHowToOutline:
+      // The how-to instance is persisted at outline time, so the id can arrive
+      // here — long before skill_end — letting consumers save progress early.
+      return {
+        ...turn,
+        howToOutline: event.value.outline,
+        skillInstanceId: event.value.skillInstanceId ?? turn.skillInstanceId,
+      };
+    case GuideEvent.SkillHowToSteps:
+      return { ...turn, howToSteps: event.value.steps };
+    case GuideEvent.SkillBusinessCaseChooser:
+      return { ...turn, businessCaseFormats: event.value.formats, businessCaseDrafts: event.value.drafts };
+    case GuideEvent.SkillBusinessCaseDelta: {
+      const existing = turn.businessCaseContent[event.value.subType] ?? "";
+      return {
+        ...turn,
+        businessCaseContent: { ...turn.businessCaseContent, [event.value.subType]: existing + event.value.delta },
+      };
+    }
+    case GuideEvent.SkillSolutionDesignHeader:
+      return { ...turn, solutionDesignHeader: event.value.header };
+    case GuideEvent.SkillSolutionDesignDiagram:
+      return { ...turn, solutionDesignNodes: event.value.nodes, solutionDesignEdges: event.value.edges };
+    case GuideEvent.SkillEnd:
+      return {
+        ...turn,
+        status: "complete",
+        // skillResponseId is the wire's legacy alias for the same id.
+        skillInstanceId: event.value.skillInstanceId ?? event.value.skillResponseId ?? turn.skillInstanceId,
+      };
+    default: {
+      // Exhaustiveness guard: a new GuideSkillEvent variant must be handled here.
+      const _exhaustive: never = event;
+      return _exhaustive;
+    }
+  }
+}