Skip to main content

SDK concepts

This guide explains the fundamental concepts behind the Kapa React SDK to help you understand how the different parts work together.

Component relationships​

The SDK has the following component structure:

┌───────────────────┐
│   KapaProvider    │ ◄── Configures the SDK with your integration ID
└─────────┬─────────┘
          │
          ▼
    ┌───────────┐
    │  useChat  │ ◄── Hook that exposes SDK functionality
    └─────┬─────┘
          │
          ▼
┌───────────────────┐
│  Your Components  │ ◄── Your custom UI using the SDK
└───────────────────┘

The KapaProvider wraps your application and makes functionality available through the useChat hook, which your components use to access the conversation and control the chat.

Question-answer lifecycle​

The question-answer lifecycle represents the states a QA pair goes through when building a stateful UI:

┌─────────────┐     ┌────────────┐     ┌────────────┐     ┌────────────┐
│  Question   │────►│ Preparing  │────►│ Generating │────►│ Completed  │
│  submitted  │     │  answer    │     │   answer   │     │   answer   │
└─────────────┘     └────────────┘     └────────────┘     └────────────┘

Each QA pair goes through these stages, with properties changing along the way:

1. Question submitted​

When a user asks a question:

  • A new QA pair is added to the conversation
  • id is null
  • answer is an empty string
  • isFeedbackSubmissionEnabled is false

2. Preparing answer​

When the SDK connects to the backend:

  • isPreparingAnswer becomes true
  • isGeneratingAnswer remains false
  • The UI can show an initial loading state

3. Generating answer​

As the answer begins streaming in:

  • isGeneratingAnswer becomes true
  • isPreparingAnswer becomes false
  • answer text updates incrementally as chunks arrive
  • sources may be updated as citations are identified
  • id remains null

If the user calls stopGeneration():

  • isGenerationAborted immediately becomes true
  • isGeneratingAnswer becomes false
  • The answer remains in its partial state

4. Completed answer​

Once generation is complete:

  • isGeneratingAnswer becomes false
  • id is set to a unique string
  • isFeedbackSubmissionEnabled becomes true
  • answer contains the complete response
  • sources contains the final list of citations

At this point, feedback UI elements can be displayed since the QA pair has an ID and feedback is enabled.

Streaming behavior​

The SDK uses streaming to display answers as they're generated:

  • Answers appear word-by-word in real-time
  • Source citations are extracted from the text
  • User can stop generation at any time with stopGeneration()

This provides a more responsive experience compared to waiting for the entire answer to be generated.

Conversation management​

The SDK maintains the entire conversation history in the conversation object, which:

  • Is an array of question-answer pairs
  • Contains all questions, answers, sources, and feedback
  • Provides helper methods for accessing specific QA pairs

This conversation state is managed automatically.