@builder.io/ai-utils 0.3.21 → 0.3.23

package/src/completion.ts

@@ -0,0 +1,174 @@
+import type {
+  BuilderContent,
+  BuilderElement,
+  Component,
+} from "@builder.io/sdk";
+import type { Message, MessageParam, Attachment } from "./messages.js";
+import type { BuilderModel } from "./events.js";
+
+export type { BuilderContent, BuilderElement, Component };
+
+export interface CompletionOptions {
+  /**
+   * How this assistant is being used. For example, "content-editor"
+   * is used when the assistant is being used in the Builder.io content editor.
+   */
+  assistantType?: string;
+
+  /**
+   * LLM Model identifier to lookup which sdk and model to use.
+   * If not provided the default model will be used.
+   * Note: This is not the Builder.io data model.
+   */
+  modelId?: string;
+
+  /**
+   * The unique LOCAL identifier of the thread to submit the user message to.
+   * This is used to identify the thread with our own id (openai assistant id is different)
+   */
+  id: string;
+
+  /**
+   * The unique OPENAI assistant id of the thread to submit the user message to.
+   * If the assistantThreadId is not provided, a new thread will be created.
+   */
+  assistantThreadId?: string;
+
+  /**
+   * The message history of the conversation, user prompt then assistant response.
+   * The messages are ordered from oldest to newest. The last message in the array
+   * is the message that the user has just sent.
+   */
+  messages: (MessageParam | Message)[];
+
+  /**
+   * Which platform (framework) the the user has choosen to get help with.
+   */
+  platformId?: string;
+
+  /**
+   * The user id of the user sending the message.
+   * This is used to track the user's progress in the conversation.
+   * User id is stored in localStorage for this domain, its not the builder user id.
+   */
+  userId: string;
+
+  /**
+   * The state of the builder editor.
+   */
+  builderState?: BuilderEditorState;
+
+  /**
+   * Additional console logs
+   */
+  debug?: boolean;
+
+  /**
+   * Date.now() timestamp of when the assistant was started.
+   * This is used to calculate the time taken between all events.
+   */
+  startMs?: number;
+  /**
+   * If events should be streamed back throughout the process.
+   *
+   * Setting to `false` will skip any intermediate processing and emitting
+   * events while collecting LLM deltas, but will only emit the final result.
+   *
+   * Defaults to `true`.
+   */
+  stream?: boolean;
+  /**
+   * Provide a system prompt id to lookup a pre-defined system prompt
+   * text sent to the LLM. Must be a pre-defined system prompt id!
+   */
+  systemPromptIds?: {
+    "content-edit"?: string;
+  };
+  /**
+   * Option on how this call should handle the conversation thread.
+   *
+   * `persist`:
+   *  - When there is no CompletionOptions `id`, it'll create a new thread id
+   *  - When given an existing `id`, it'll look up the past thread messages and prefix the messages
+   *
+   * `ephemeral`:
+   *  - Creates a new conversation each time, ignoring any existing thread history
+   *  - Will not save the conversation for future use
+   *
+   * Defaults to `persist`
+   */
+  thread?: "persist" | "ephemeral";
+
+  attachments?: Attachment[];
+}
+
+export interface BuilderEditorState {
+  /**
+   * The active locale of the builder editor.
+   */
+  activeLocale?: string;
+  /**
+   * The locale of the provided builder content.
+   */
+  contentLocale?: string;
+  /**
+   * Top level Builder content. The data.blocks array contains the BuilderElement.
+   */
+  content?: BuilderContent;
+  /**
+   * Builder custom components.
+   */
+  components?: Component[];
+  /**
+   * Builder design tokens.
+   */
+  designTokens?: Record<string, string>;
+  /**
+   * Builder model. (not the LLM model)
+   */
+  model?: BuilderModel;
+  /**
+   * Other models in the Builder account
+   */
+  otherModels?: BuilderModel[];
+  /**
+   * The URL that the Builder content preview is pointing to.
+   */
+  previewUrl?: string;
+  /**
+   * Selected ids in the builder.
+   */
+  selectedIds?: string[];
+  /**
+   * Builder space id.
+   */
+  spaceId?: string;
+  /**
+   * Builder user id.
+   */
+  userId?: string;
+  /**
+   * Email of the user in the builder.
+   */
+  userEmail?: string;
+  /**
+   * User's jobs
+   */
+  userJobs?: string[];
+  /**
+   * Builder session id.
+   */
+  sessionId?: string;
+  /**
+   * Custom instructions that could be add into the prompt.
+   */
+  customInstructions?: Record<string, string>;
+
+  // A URL to use as design inspiration when generating content
+  styleInspirationURL?: string;
+
+  /**
+   * All targeting attributes of the content.
+   */
+  allTargetingAttributes?: Record<string, any>;
+}

package/src/events.ts

@@ -0,0 +1,485 @@
+import type { BuilderContent, BuilderElement } from "@builder.io/sdk";
+import type { AssistantMessage, AssistantMessageAction } from "./messages.js";
+import type { AssistantSettings } from "./settings.js";
+
+export type BuilderAssistantEventHandler = (ev: BuilderAssistantEvent) => void;
+
+export type BuilderAssistantEvent =
+  | AssistantCompletionResultEvent
+  | AssistantErrorEvent
+  | AssistantStreamErrorEvent
+  | AppCloseEvent
+  | AppMessagesClickEvent
+  | AppMessagesGenerationEvent
+  | AppMessageEditCustomInstructionsEvent
+  | AppPromptAbortEvent
+  | AppPromptFocusEvent
+  | AppPromptSubmitEvent
+  | AppReadyEvent
+  | AppSettingsSetEvent
+  | AppThreadNewEvent
+  | AssistantStatsEvent
+  | AssistantThemeEvent
+  | BuilderEditorAuthEvent
+  | BuilderEditorStateEvent
+  | ContentUpdateEvent
+  | ContentApplySnapshotEvent
+  | ModelUndoEvent
+  | ModelRedoEvent
+  | ResultEvent
+  | ThreadCreatedEvent
+  | ThreadMessageCompletedEvent
+  | ThreadMessageCreatedEvent
+  | ThreadMessageDeltaEvent
+  | ThreadMessageFeedbackEvent
+  | ThreadRunStepCreatedEvent
+  | ThreadRunStepDeltaEvent
+  | AppAcceptChangeEvent
+  | AppAcceptRejectEvent
+  | AssistantTrackEvent
+  | AssistantEditorAuthMessage
+  | AppAttachmentTemplateEvent
+  | ThreadMessageRetryEvent
+  | AppFigmaImportEvent
+  | AppWebImportEvent
+  | AppAiTemplatesEvent
+  | AssistantContentInitialEvent
+  | ThreadMessageSummaryEvent
+  | AssistantHeartbeatEvent
+  | ShowUpgradeDialogEvent;
+
+export interface AssistantCompletionResultEvent {
+  type: "assistant.result";
+  data: {
+    content?: BuilderContent;
+    stats?: AssistantStats;
+  };
+  resolveId?: string;
+}
+
+export interface AssistantError {
+  message: string;
+  status?: number;
+  // any actions associated with the error such as a "new chat" button
+  actions?: AssistantMessageAction[];
+}
+
+export interface AssistantErrorEvent {
+  type: "assistant.error";
+  data: AssistantError;
+}
+
+export interface AssistantStreamErrorEvent {
+  type: "assistant.stream.error";
+  data: AssistantError;
+}
+
+export interface AppFigmaImportEvent {
+  type: "assistant.app.figmaImport";
+}
+
+export interface AppWebImportEvent {
+  type: "assistant.app.webImport";
+}
+
+export interface AppAiTemplatesEvent {
+  type: "assistant.app.aiTemplates";
+}
+
+export interface AssistantTrackEvent {
+  type: "assistant.track";
+  data: {
+    name: string;
+    properties: Record<string, any>;
+  };
+}
+
+export interface AssistantThemeEvent {
+  type: "assistant.app.theme.update";
+  data: {
+    theme: string;
+  };
+}
+
+export interface AppCloseEvent {
+  type: "assistant.app.close";
+}
+
+export interface AppMessagesClickEvent {
+  type: "assistant.app.messages.click";
+}
+
+export interface ShowUpgradeDialogEvent {
+  type: "assistant.app.showUpgradeDialog";
+}
+
+export interface AppAcceptChangeEvent {
+  type: "assistant.app.change.accept";
+}
+export interface AppAcceptRejectEvent {
+  type: "assistant.app.change.reject";
+}
+
+export interface AppMessageEditCustomInstructionsEvent {
+  type: "assistant.app.messages.editCustomInstructions";
+}
+
+export interface AppAttachmentTemplateEvent {
+  type: "assistant.app.attachment.template";
+  data: {
+    id: number;
+    name: string;
+  };
+}
+
+export interface AppMessagesGenerationEvent {
+  type: "assistant.app.messages.generation";
+  data: {
+    state: GenerationState;
+  };
+}
+
+/**
+ * idle: no messages are being generated or queued to be generated
+ *
+ * queued: messages have been sent to the LLM, but no response has been received yet
+ *
+ * generating: messages are actively being generated and streaming back to the UI
+ */
+export type GenerationState = "idle" | "queued" | "generating";
+
+export interface AppPromptAbortEvent {
+  type: "assistant.app.prompt.abort";
+}
+
+export interface AppPromptFocusEvent {
+  type: "assistant.app.prompt.focus";
+}
+
+export interface AppPromptSubmitEvent {
+  type: "assistant.app.prompt.submit";
+  data: {
+    prompt: string;
+    attachments: any[];
+  };
+}
+
+export interface AppReadyEvent {
+  type: "assistant.app.ready";
+}
+
+export interface AppSettingsSetEvent {
+  type: "assistant.app.settings.set";
+  data: Partial<AssistantSettings>;
+}
+
+export interface AppThreadNewEvent {
+  type: "assistant.app.thread.new";
+}
+
+export interface AssistantEditorAuthMessage {
+  type: "assistant.editor.auth.update";
+}
+
+export interface BuilderEditorAuthEvent extends AwaitResultEvent {
+  type: "assistant.editor.auth";
+}
+
+export interface BuilderEditorStateEvent extends AwaitResultEvent {
+  type: "assistant.editor.state";
+}
+
+export interface AwaitResultEvent {
+  resolveId?: string;
+}
+
+export interface ResultEvent {
+  type: "assistant.result";
+  resolveId: string;
+  data: any;
+}
+
+export interface ContentCreatePatch {
+  parentId: string;
+  insertBeforeId: string;
+  element: BuilderElement;
+}
+
+export interface ContentApplySnapshot {
+  /**
+   * The id of the BuilderContent to apply the snapshot to
+   */
+  id: string;
+  /**
+   * Each snapshot can be either a full BuilderContent or individual BuilderElements.
+   * Order matters, as the snapshots will be applied in the order they are listed.
+   * The builder app will handle the logic of applying the snapshots in the correct order
+   * and to the right content/elements.
+   */
+  snapshots: (BuilderElement | BuilderContent)[];
+}
+
+export interface ContentApplySnapshotEvent {
+  type: "assistant.content.applysnapshot";
+  data: ContentApplySnapshot;
+}
+
+export interface ContentUpdateEvent {
+  type: "assistant.content.update";
+  data: ContentUpdatePatch[];
+}
+
+export type ContentUpdatePatch = ContentTsUpdateComponentPatch;
+
+interface ContentPatchBase {
+  id: string;
+  nodeId?: string;
+  builderId?: string;
+  description?: string;
+  value: string;
+  displayValue?: string;
+  ts: number;
+  /**
+   * A change value is considered incomplete until we also parsed it's closing xml tag.
+   */
+  incomplete?: boolean;
+  /**
+   * If there was an error applying the patch, this will contain the error message.
+   */
+  error?: string;
+
+  /**
+   * If `true`, Editor AI attempted to process this patch. It could be that the patch
+   * had invalid syntax or that the LLM made its changes incorrectly. This can be used
+   * to differentiate between a patch that is actively being streamed in, as indicated by
+   * the "incomplete" property, and a patch that is has finished streaming and is being
+   * processed.
+   */
+  attemptedProcess?: boolean;
+}
+
+export interface ContentTsUpdateComponentPatch extends ContentPatchBase {
+  type: "update_component";
+}
+
+export interface AssistantStatsEvent {
+  type: "assistant.stats";
+  data: AssistantStats;
+}
+
+export interface AssistantStats {
+  /**
+   * The unique id of the thread (not the openai threadId)
+   */
+  threadId: string;
+  /**
+   * The unique id of the completion, which is a combination of the user's prompt and assistant's response.
+   */
+  completionId: string;
+  /**
+   * The model id used to generate this completion.
+   */
+  modelId: string;
+  /**
+   * The assistant's response message.
+   */
+  assistantMessage: string;
+  /**
+   * The assistant's summary of what it did. This appears after assistantMessage
+   * as well as any changes it made.
+   */
+  assistantSummary: string;
+  /**
+   * The user's prompt message.
+   */
+  userMessage: string;
+  /**
+   * The index within the thread the assistant message is.
+   * For a first assistant message, the index will be 1 (the user message is index 0).
+   * For a second assistant message, the index will be 3 (the user message is index 2), and so on.
+   */
+  assistantMessageIndex: number;
+  /**
+   * The timestamp (Date.now()) of when the user first submitted their prompt.
+   */
+  userPromptMs: number;
+  /**
+   * The timestamp of the first assistant chunk in the response.
+   */
+  firstChunkMs: number;
+  /**
+   * The timestamp of the last assistant chunk in the response.
+   */
+  lastChunkMs: number;
+  /**
+   * The total number of chunks in the assistant's streamed response.
+   */
+  chunkCount: number;
+  /**
+   * The total number of characters in the generated prompt sent to the LLM.
+   */
+  promptLength: number;
+  /**
+   * The total number of characters in the assistant's response.
+   */
+  completionLength: number;
+  /**
+   * If the user provided custom instructions for the prompt.
+   */
+  hasCustomInstructions: boolean;
+  /**
+   * The deployed version.
+   */
+  version: string;
+  /**
+   * Error message if there was one.
+   */
+  errorMessage?: string;
+  /**
+   * Input tokens
+   */
+  inputTokens?: number;
+  /**
+   * Output tokens
+   */
+  outputTokens?: number;
+  /**
+   * Output tokens
+   */
+  completionCost?: number;
+  /**
+   * Number of streamed snapshots
+   */
+  streamedSnapshots?: number;
+  /**
+   * Number of cached input tokens
+   */
+  cacheInputTokens?: number;
+  /**
+   * Number of cached created tokens
+   */
+  cacheCreatedTokens?: number;
+}
+
+export interface ModelUndoEvent {
+  type: "assistant.model.undo";
+}
+
+export interface ModelRedoEvent {
+  type: "assistant.model.redo";
+}
+
+export interface BuilderModel {
+  name?: string;
+  friendlyName?: string;
+  description?: string;
+  type?: string;
+  fields?: BuilderModelField[];
+}
+
+export interface BuilderModelField {
+  name?: string;
+  type?: string;
+  description?: string;
+}
+
+export interface ThreadMessageFeedbackEvent {
+  type: "assistant.thread.message.feedback";
+  data: CompletionResponseFeedback;
+}
+
+export interface CompletionResponseFeedback {
+  userId: string;
+  builderUserId?: string;
+  builderEmail?: string;
+  responseId?: string;
+  frontendUrl: string | undefined;
+  frontendCommitId: string | undefined;
+  backendDomain?: string;
+  backendCommitId: string | undefined;
+  feedbackText: string;
+  sentiment?: "positive" | "negative";
+}
+
+export interface ThreadCreatedEvent {
+  type: "assistant.thread.created";
+  data: ThreadCreated;
+}
+
+export interface ThreadCreated {
+  platformId: string;
+  threadId: string;
+  vectorStoreId: string;
+}
+
+export interface ThreadMessageCreatedEvent {
+  type: "assistant.thread.message.created";
+  data: ThreadMessageCreated;
+}
+
+export interface ThreadMessageCreated {
+  id: string;
+  responseId: string;
+  threadId: string;
+}
+
+export interface ThreadMessageDeltaEvent {
+  type: "assistant.thread.message.delta";
+  data: ThreadMessageDelta;
+}
+
+// use this event to keep a streaming connection alive
+export interface AssistantHeartbeatEvent {
+  type: "assistant.heartbeat";
+}
+
+export interface ThreadMessageDelta {
+  id: string;
+  text: string;
+}
+
+export interface ThreadMessageCompletedEvent {
+  type: "assistant.thread.message.completed";
+  data: ThreadMessageCompleted;
+}
+
+export interface ThreadMessageRetryEvent {
+  type: "assistant.thread.message.retry";
+}
+
+export interface ThreadMessageSummaryEvent {
+  type: "assistant.thread.message.summary.delta";
+  data: ThreadMessageDelta;
+}
+
+export interface ThreadMessageCompleted extends AssistantMessage {
+  platformId: string;
+  threadId: string;
+  commitId?: string;
+}
+
+export interface ThreadRunStepDeltaEvent {
+  type: "assistant.thread.run.step.delta";
+  data: ThreadMessageStepDelta;
+}
+
+export interface ThreadMessageStepDelta {
+  delta: any;
+}
+
+export interface ThreadRunStepCreatedEvent {
+  type: "assistant.thread.run.step.created";
+}
+
+export type DeepPartial<T> = T extends object
+  ? {
+      [P in keyof T]?: DeepPartial<T[P]>;
+    }
+  : T;
+
+export interface AssistantContentInitialEvent {
+  type: "assistant.content.initial";
+  data: {
+    code: string;
+  };
+}