@botonic/react 0.40.0 → 0.41.0-alpha.0

package/src/components/system-debug-trace/debug-message.tsx

@@ -0,0 +1,111 @@
+import { EventAction } from '@botonic/core'
+import React, { useRef, useState } from 'react'
+
+import {
+  getAiAgentEventConfig,
+  getFallbackEventConfig,
+  getHandoffSuccessEventConfig,
+  getKeywordEventConfig,
+  getKnowledgeBaseEventConfig,
+  getSmartIntentEventConfig,
+} from './events'
+import { useLastLabelPosition } from './hooks/use-last-label-position'
+import { CaretDownSvg, CaretUpSvg } from './icons'
+import {
+  StyledDebugArrow,
+  StyledDebugContainer,
+  StyledDebugContent,
+  StyledDebugContentWrapper,
+  StyledDebugHeader,
+  StyledDebugIcon,
+  StyledDebugTitle,
+} from './styles'
+import { DebugEvent, DebugEventConfig } from './types'
+
+const getEventConfig = (
+  debugEvent: DebugEvent
+): DebugEventConfig | undefined => {
+  switch (debugEvent.action) {
+    case EventAction.Keyword:
+      return getKeywordEventConfig(debugEvent)
+    case EventAction.IntentSmart:
+      return getSmartIntentEventConfig(debugEvent)
+    case EventAction.HandoffSuccess:
+      return getHandoffSuccessEventConfig(debugEvent)
+    case EventAction.AiAgent:
+      return getAiAgentEventConfig(debugEvent)
+    case EventAction.Knowledgebase:
+      return getKnowledgeBaseEventConfig(debugEvent)
+    case EventAction.Fallback:
+      return getFallbackEventConfig(debugEvent)
+    default:
+      return undefined
+  }
+}
+
+interface DebugMessageProps {
+  debugEvent: DebugEvent
+  messageId?: string
+}
+
+export const DebugMessage = ({ debugEvent, messageId }: DebugMessageProps) => {
+  const [isExpanded, setIsExpanded] = useState(false)
+  const wrapperRef = useRef<HTMLDivElement>(null)
+
+  const eventConfig = getEventConfig(debugEvent)
+
+  useLastLabelPosition({
+    wrapperRef,
+    isExpanded,
+    debugEvent,
+    isCollapsible: eventConfig?.collapsible ?? false,
+  })
+
+  if (!eventConfig) {
+    return null
+  }
+
+  const { title, icon, component, collapsible } = eventConfig
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  const Component = component
+
+  const handleClick = (e: React.MouseEvent) => {
+    if (collapsible) {
+      const target = e.target as HTMLElement
+      const isButton = target.closest('button, a, [role="button"]')
+
+      if (!isButton) {
+        e.stopPropagation()
+        setIsExpanded(!isExpanded)
+      }
+    }
+  }
+
+  const containerClassName = collapsible
+    ? `collapsible${isExpanded ? ' expanded' : ''}`
+    : ''
+
+  return (
+    <StyledDebugContainer
+      className={containerClassName}
+      onClick={collapsible ? handleClick : undefined}
+    >
+      <StyledDebugHeader>
+        <StyledDebugIcon>{icon}</StyledDebugIcon>
+        <StyledDebugTitle>{title}</StyledDebugTitle>
+        {collapsible && (
+          <StyledDebugArrow>
+            {isExpanded ? <CaretUpSvg /> : <CaretDownSvg />}
+          </StyledDebugArrow>
+        )}
+      </StyledDebugHeader>
+      {Component && (
+        <StyledDebugContent style={{ display: isExpanded ? 'block' : 'none' }}>
+          <StyledDebugContentWrapper ref={wrapperRef}>
+            <Component {...debugEvent} messageId={messageId} />
+          </StyledDebugContentWrapper>
+        </StyledDebugContent>
+      )}
+    </StyledDebugContainer>
+  )
+}

package/src/components/system-debug-trace/events/ai-agent.tsx

@@ -0,0 +1,158 @@
+import { EventAction } from '@botonic/core'
+import React, { useContext, useMemo } from 'react'
+
+import { WebchatContext } from '../../../webchat/context'
+import { useKnowledgeBaseInfo } from '../hooks/use-knowledge-base-info'
+import { ScrewdriverWrenchSvg, WandSvg } from '../icons'
+import {
+  StyledDebugDetail,
+  StyledDebugItemWithIcon,
+  StyledDebugLabel,
+  StyledDebugValue,
+} from '../styles'
+import { DebugEventConfig } from '../types'
+import { GuardrailList, SourcesSection } from './components'
+import { LABELS } from './constants'
+import { ChunkIdsGroupedBySourceData } from './knowledge-bases-types'
+
+interface ToolExecuted {
+  tool_name: string
+  tool_arguments: Record<string, unknown>
+  knowledgebase_sources_ids?: string[]
+  knowledgebase_chunks_ids?: string[]
+}
+
+export interface AiAgentDebugEvent {
+  action: EventAction.AiAgent
+  flow_node_content_id: string
+  user_input?: string
+  tools_executed: ToolExecuted[]
+  input_guardrails_triggered: string[]
+  output_guardrails_triggered: string[]
+  exit: boolean
+  error: boolean
+  knowledge_base_chunks_with_sources?: ChunkIdsGroupedBySourceData[]
+  messageId?: string
+}
+
+export const AiAgent = (props: AiAgentDebugEvent) => {
+  const { previewUtils } = useContext(WebchatContext)
+
+  // Collect all sources IDs, chunk IDs and query from all tools
+  const { allSourcesIds, allChunksIds, query } = useMemo(() => {
+    const allSourcesIds: string[] = []
+    const allChunksIds: string[] = []
+    let query: string | undefined
+
+    props.tools_executed.forEach(tool => {
+      if (
+        tool.tool_arguments?.query &&
+        typeof tool.tool_arguments.query === 'string'
+      ) {
+        query = tool.tool_arguments.query
+      }
+      if (tool.knowledgebase_sources_ids) {
+        allSourcesIds.push(...tool.knowledgebase_sources_ids)
+      }
+      if (tool.knowledgebase_chunks_ids) {
+        allChunksIds.push(...tool.knowledgebase_chunks_ids)
+      }
+    })
+
+    return { allSourcesIds, allChunksIds, query }
+  }, [props.tools_executed])
+
+  const {
+    sources: allSources,
+    chunks: allChunks,
+    chunksWithSources,
+    getIconForSourceType,
+  } = useKnowledgeBaseInfo({
+    sourceIds: allSourcesIds,
+    chunkIds: allChunksIds,
+    messageId: props.messageId,
+    existingChunksWithSources: props.knowledge_base_chunks_with_sources,
+  })
+
+  const handleSeeChunks = () => {
+    if (previewUtils?.onClickOpenChunks) {
+      previewUtils.onClickOpenChunks(chunksWithSources)
+    }
+  }
+  return (
+    <>
+      {query && (
+        <StyledDebugDetail>
+          <StyledDebugLabel>{LABELS.QUERY}</StyledDebugLabel>
+          <StyledDebugValue>&quot;{query}&quot;</StyledDebugValue>
+        </StyledDebugDetail>
+      )}
+
+      <SourcesSection
+        sources={allSources}
+        chunks={allChunks}
+        getIconForSourceType={getIconForSourceType}
+        onSeeChunks={handleSeeChunks}
+        label={LABELS.KNOWLEDGE_GATHERED}
+      />
+
+      {props.tools_executed.length > 0 && (
+        <StyledDebugDetail>
+          <StyledDebugLabel>{LABELS.EXECUTED_TOOLS}</StyledDebugLabel>
+          {props.tools_executed.map((tool, index) => (
+            <StyledDebugItemWithIcon key={`${tool.tool_name}-${index}`}>
+              <ScrewdriverWrenchSvg />
+              {tool.tool_name}
+            </StyledDebugItemWithIcon>
+          ))}
+        </StyledDebugDetail>
+      )}
+
+      {props.tools_executed.length === 0 && (
+        <StyledDebugDetail>
+          <StyledDebugLabel>{LABELS.NO_TOOLS_EXECUTED}</StyledDebugLabel>
+        </StyledDebugDetail>
+      )}
+
+      <GuardrailList
+        keyPrefix='input'
+        guardrails={props.input_guardrails_triggered}
+      />
+      <GuardrailList
+        keyPrefix='output'
+        guardrails={props.output_guardrails_triggered}
+        $isLastItem={!props.exit && !props.error}
+      />
+
+      {props.exit && (
+        <StyledDebugDetail $isLastItem={props.exit && !props.error}>
+          <StyledDebugLabel>{LABELS.EXIT}</StyledDebugLabel>
+        </StyledDebugDetail>
+      )}
+
+      {props.error && (
+        <StyledDebugDetail $isLastItem={props.exit && props.error}>
+          <StyledDebugLabel>{LABELS.ERROR}</StyledDebugLabel>
+        </StyledDebugDetail>
+      )}
+    </>
+  )
+}
+
+export const getAiAgentEventConfig = (
+  data: AiAgentDebugEvent
+): DebugEventConfig => {
+  const title = (
+    <>
+      AI Agent triggered <span>- {data.flow_node_content_id}</span>
+    </>
+  )
+
+  return {
+    action: EventAction.AiAgent,
+    title,
+    component: AiAgent,
+    icon: <WandSvg />,
+    collapsible: true,
+  }
+}

package/src/components/system-debug-trace/events/components/guardrail-item.tsx

@@ -0,0 +1,53 @@
+import React from 'react'
+
+import { HandSvg } from '../../icons'
+import {
+  StyledGuardrailItem,
+  StyledGuardrailLabel,
+  StyledGuardrailValue,
+} from '../../styles'
+import { LABELS } from '../constants'
+
+interface GuardrailItemProps {
+  guardrail: string
+  keyPrefix: string
+  $isLastItem?: boolean
+}
+
+export const GuardrailItem: React.FC<GuardrailItemProps> = ({
+  guardrail,
+  keyPrefix,
+  $isLastItem,
+}) => (
+  <StyledGuardrailItem
+    key={`${keyPrefix}-${guardrail}`}
+    $isLastItem={$isLastItem}
+  >
+    <HandSvg />
+    <StyledGuardrailLabel>{LABELS.GUARDRAIL_TRIGGERED}</StyledGuardrailLabel>
+    <StyledGuardrailValue>- {guardrail}</StyledGuardrailValue>
+  </StyledGuardrailItem>
+)
+
+interface GuardrailListProps {
+  guardrails: string[]
+  keyPrefix: string
+  $isLastItem?: boolean
+}
+
+export const GuardrailList: React.FC<GuardrailListProps> = ({
+  guardrails,
+  keyPrefix,
+  $isLastItem,
+}) => (
+  <>
+    {guardrails.map(guardrail => (
+      <GuardrailItem
+        key={`${keyPrefix}-${guardrail}`}
+        guardrail={guardrail}
+        keyPrefix={keyPrefix}
+        $isLastItem={$isLastItem}
+      />
+    ))}
+  </>
+)

package/src/components/system-debug-trace/events/components/index.ts

@@ -0,0 +1,2 @@
+export * from './guardrail-item'
+export * from './sources-section'

package/src/components/system-debug-trace/events/components/sources-section.tsx

@@ -0,0 +1,66 @@
+import React from 'react'
+
+import {
+  StyledDebugDetail,
+  StyledDebugItemWithIcon,
+  StyledDebugLabel,
+  StyledFileSourceValue,
+  StyledSeeChunksButton,
+  StyledUrlSourceValue,
+} from '../../styles'
+import { LABELS } from '../constants'
+import { HubtypeChunk, HubtypeSource } from '../knowledge-bases-types'
+
+interface SourcesSectionProps {
+  sources: HubtypeSource[]
+  chunks: HubtypeChunk[]
+  getIconForSourceType: (source: HubtypeSource) => React.ReactNode
+  onSeeChunks: () => void
+  label?: string
+}
+
+export const SourcesSection = ({
+  sources,
+  chunks,
+  getIconForSourceType,
+  onSeeChunks,
+  label = LABELS.SOURCES,
+}: SourcesSectionProps) => {
+  if (sources.length === 0) return null
+
+  return (
+    <StyledDebugDetail>
+      <StyledDebugLabel>{label}</StyledDebugLabel>
+      {sources.map(source => {
+        const icon = getIconForSourceType(source)
+        const isUrl = source.type === 'url'
+        const value = isUrl
+          ? source.activeExtractionJob?.url
+          : source.activeExtractionJob?.fileName
+
+        return (
+          <StyledDebugItemWithIcon key={source.id}>
+            {icon}
+            {isUrl ? (
+              <StyledUrlSourceValue
+                href={value ?? ''}
+                target='_blank'
+                rel='noopener noreferrer'
+                title={value ?? 'Not detected'}
+              >
+                {value}
+              </StyledUrlSourceValue>
+            ) : (
+              <StyledFileSourceValue>{value}</StyledFileSourceValue>
+            )}
+          </StyledDebugItemWithIcon>
+        )
+      })}
+      {chunks.length > 0 && (
+        <StyledSeeChunksButton onClick={onSeeChunks}>
+          {LABELS.SEE_CHUNKS_BUTTON}
+        </StyledSeeChunksButton>
+      )}
+    </StyledDebugDetail>
+  )
+}

package/src/components/system-debug-trace/events/constants.ts

@@ -0,0 +1,15 @@
+export const LABELS = {
+  GUARDRAIL_TRIGGERED: 'Guardrail triggered',
+  KNOWLEDGE_FOUND: 'Knowledge found',
+  FAITHFUL_ANSWER: 'Faithful answer',
+  QUERY: 'Query',
+  SOURCES: 'Sources',
+  KNOWLEDGE_GATHERED: 'Knowledge gathered',
+  EXECUTED_TOOLS: 'Executed tools',
+  NO_TOOLS_EXECUTED: 'No tools executed',
+  EXIT: 'Exit',
+  ERROR: 'Error',
+  QUEUE: 'Queue',
+  KNOWLEDGE_BASE_FAIL_REASON: 'Knowledge Base Fail Reason',
+  SEE_CHUNKS_BUTTON: 'See chunks',
+} as const

package/src/components/system-debug-trace/events/fallback.tsx

@@ -0,0 +1,31 @@
+import { EventAction } from '@botonic/core'
+import React from 'react'
+
+import { LifeRingSvg } from '../icons/life-ring'
+import { DebugEventConfig } from '../types'
+
+export interface FallbackDebugEvent {
+  action: EventAction.Fallback
+  user_input: string
+  fallback_out: number
+  fallback_message_id: string
+}
+
+export const getFallbackEventConfig = (
+  data: FallbackDebugEvent
+): DebugEventConfig => {
+  const ordinal = data.fallback_out === 1 ? '1st' : '2nd'
+  const title = (
+    <>
+      Fallback message triggered <span>- {ordinal} message</span>
+    </>
+  )
+
+  return {
+    action: EventAction.Fallback,
+    title,
+    component: null,
+    icon: <LifeRingSvg />,
+    collapsible: false,
+  }
+}

package/src/components/system-debug-trace/events/handoff-success.tsx

@@ -0,0 +1,43 @@
+import { EventAction } from '@botonic/core'
+import React from 'react'
+
+import { HeadSetSvg } from '../icons'
+import {
+  StyledDebugDetail,
+  StyledDebugLabel,
+  StyledDebugValue,
+} from '../styles'
+import { DebugEventConfig } from '../types'
+import { LABELS } from './constants'
+
+export interface HandoffSuccessDebugEvent {
+  action: EventAction.HandoffSuccess
+  handoff_queue_name: string
+  handoff_is_queue_open: boolean
+}
+
+export const HandoffSuccess = (props: HandoffSuccessDebugEvent) => {
+  return (
+    <StyledDebugDetail>
+      <StyledDebugLabel>{LABELS.QUEUE}</StyledDebugLabel>
+      <StyledDebugValue>{props.handoff_queue_name}</StyledDebugValue>
+    </StyledDebugDetail>
+  )
+}
+
+export const getHandoffSuccessEventConfig = (
+  data: HandoffSuccessDebugEvent
+): DebugEventConfig => {
+  return {
+    action: EventAction.HandoffSuccess,
+    title: (
+      <>
+        Handoff to agent <span>- {data.handoff_queue_name}</span>
+      </>
+    ),
+    icon: <HeadSetSvg />,
+    // TODO: Disable component and collapsible for now because we are only showing the queue name
+    component: null,
+    collapsible: false,
+  }
+}

package/src/components/system-debug-trace/events/index.ts

@@ -0,0 +1,7 @@
+export * from './ai-agent'
+export * from './fallback'
+export * from './handoff-success'
+export * from './keyword'
+export * from './knowledge-base'
+export * from './knowledge-bases-types'
+export * from './smart-intent'

package/src/components/system-debug-trace/events/keyword.tsx

@@ -0,0 +1,31 @@
+import { EventAction } from '@botonic/core'
+import React from 'react'
+
+import { QuoteRightSvg } from '../icons/quote-right'
+import { DebugEventConfig } from '../types'
+
+export interface KeywordDebugEvent {
+  action: EventAction.Keyword
+  flow_id: string
+  flow_node_id: string
+  nlu_keyword_is_regex: boolean
+  nlu_keyword_name: string
+}
+
+export const getKeywordEventConfig = (
+  data: KeywordDebugEvent
+): DebugEventConfig => {
+  const title = (
+    <>
+      Keyword matched <span>- &quot;{data.nlu_keyword_name}&quot;</span>
+    </>
+  )
+
+  return {
+    action: EventAction.Keyword,
+    title,
+    component: null,
+    icon: <QuoteRightSvg />,
+    collapsible: false,
+  }
+}

package/src/components/system-debug-trace/events/knowledge-base.tsx

@@ -0,0 +1,115 @@
+import { EventAction } from '@botonic/core'
+import React, { useContext } from 'react'
+
+import { WebchatContext } from '../../../webchat/context'
+import { useKnowledgeBaseInfo } from '../hooks/use-knowledge-base-info'
+import { CircleCheckSvg, WandSvg } from '../icons'
+import {
+  StyledDebugDetail,
+  StyledDebugLabel,
+  StyledDebugValue,
+  StyledGuardrailItem,
+  StyledGuardrailLabel,
+} from '../styles'
+import { DebugEventConfig } from '../types'
+import { SourcesSection } from './components'
+import { LABELS } from './constants'
+import { ChunkIdsGroupedBySourceData } from './knowledge-bases-types'
+
+export interface KnowledgeBaseDebugEvent {
+  action: EventAction.Knowledgebase
+  flow_id: string
+  flow_node_id: string
+  knowledgebase_inference_id: string
+  knowledgebase_fail_reason: string
+  knowledgebase_sources_ids: string[]
+  knowledgebase_chunks_ids: string[]
+  user_input: string
+  knowledge_base_chunks_with_sources?: ChunkIdsGroupedBySourceData[]
+  messageId?: string
+}
+
+export const KnowledgeBase = (props: KnowledgeBaseDebugEvent) => {
+  const { previewUtils } = useContext(WebchatContext)
+  const {
+    sources,
+    chunks,
+    chunksWithSources,
+    getIconForSourceType,
+    hasKnowledge,
+    isFaithful,
+  } = useKnowledgeBaseInfo({
+    sourceIds: props.knowledgebase_sources_ids,
+    chunkIds: props.knowledgebase_chunks_ids,
+    messageId: props.messageId,
+    existingChunksWithSources: props.knowledge_base_chunks_with_sources,
+    failReason: props.knowledgebase_fail_reason,
+  })
+
+  const showFailReason = !hasKnowledge || !isFaithful
+
+  const handleSeeChunks = () => {
+    if (previewUtils?.onClickOpenChunks) {
+      previewUtils.onClickOpenChunks(chunksWithSources)
+    }
+  }
+
+  return (
+    <>
+      <StyledDebugDetail>
+        <StyledDebugLabel>{LABELS.QUERY}</StyledDebugLabel>
+        <StyledDebugValue>&quot;{props.user_input}&quot;</StyledDebugValue>
+      </StyledDebugDetail>
+
+      {showFailReason ? (
+        <StyledDebugDetail>
+          <StyledDebugLabel>
+            {LABELS.KNOWLEDGE_BASE_FAIL_REASON}
+          </StyledDebugLabel>
+          <StyledDebugValue>{props.knowledgebase_fail_reason}</StyledDebugValue>
+        </StyledDebugDetail>
+      ) : (
+        <>
+          <SourcesSection
+            sources={sources}
+            chunks={chunks}
+            getIconForSourceType={getIconForSourceType}
+            onSeeChunks={handleSeeChunks}
+          />
+
+          {hasKnowledge && (
+            <StyledGuardrailItem>
+              <CircleCheckSvg />
+              <StyledGuardrailLabel>
+                {LABELS.KNOWLEDGE_FOUND}
+              </StyledGuardrailLabel>
+            </StyledGuardrailItem>
+          )}
+
+          {isFaithful && (
+            <StyledGuardrailItem $isLastItem={true}>
+              <CircleCheckSvg />
+              <StyledGuardrailLabel>
+                {LABELS.FAITHFUL_ANSWER}
+              </StyledGuardrailLabel>
+            </StyledGuardrailItem>
+          )}
+        </>
+      )}
+    </>
+  )
+}
+
+export const getKnowledgeBaseEventConfig = (
+  _data: KnowledgeBaseDebugEvent
+): DebugEventConfig => {
+  const title = <>Knowledge Base triggered</>
+
+  return {
+    action: EventAction.Knowledgebase,
+    title,
+    component: KnowledgeBase,
+    icon: <WandSvg />,
+    collapsible: true,
+  }
+}

package/src/components/system-debug-trace/events/knowledge-bases-types.ts

@@ -0,0 +1,33 @@
+interface HubtypeExtractionJob {
+  id: string
+  fileName: string
+  fileUrl: string
+  url: string | null
+  isActive: boolean
+  status: string
+  hash: string
+  createdAt: string
+}
+
+export interface HubtypeSource {
+  id: string
+  name: string
+  type: string
+  scrapingCountryCode: string | null
+  createdAt: string
+  createdBy: string
+  lastUpdatedAt: string
+  lastUpdatedBy: string
+  activeExtractionJob: HubtypeExtractionJob
+  lastExtractionJob: HubtypeExtractionJob
+}
+
+export interface HubtypeChunk {
+  id: string
+  text: string
+}
+
+export interface ChunkIdsGroupedBySourceData {
+  source: HubtypeSource
+  chunks: HubtypeChunk[]
+}

package/src/components/system-debug-trace/events/smart-intent.tsx

@@ -0,0 +1,26 @@
+import { EventAction } from '@botonic/core'
+import React from 'react'
+
+import { BrainSvg } from '../icons'
+import { DebugEventConfig } from '../types'
+
+export interface SmartIntentDebugEvent {
+  action: EventAction.IntentSmart
+  nlu_intent_smart_title: string
+}
+
+export const getSmartIntentEventConfig = (
+  data: SmartIntentDebugEvent
+): DebugEventConfig => {
+  const title = (
+    <>
+      Smart intent triggered <span>- "{data.nlu_intent_smart_title}"</span>
+    </>
+  )
+  return {
+    action: EventAction.IntentSmart,
+    title,
+    component: null,
+    icon: <BrainSvg />,
+  }
+}