Development README for @cmnd-ai/chatbot-react

Getting Started (Development)

1. Install dependencies:

   npm install

2. Start the development server:

   npm run dev

3. Link the package locally: In a separate terminal, run:

   npm link

4. Test in another project: In the project where you want to use @cmnd-ai/chatbot-react, run:

   npm link @cmnd-ai/chatbot-react

This will allow you to test your local changes in another project without publishing to npm.

Core Hook Implementation (useCMNDChat)

The useCMNDChat hook is designed to be the logic engine of the chatbot. Key implementation details:

• State Management: Uses native React useState for messages, input, and loading states.
• Real-time Streaming: Utilizes postUserConversation with a stream reader to process response chunks.
• Tool Orchestration:
  • Backend Tools: Automatically confirms tool call by setting confirmed: true. This triggers the server to execute the tool and return the actual data.
  • UI Tools: Fires the onToolCall callback. The developer must execute the tool logic and call submitToolResult(output).
• Message Cleaning: When cleanResponse: true is enabled, assistant messages are passed through a cleanMarkdown utility to return plaintext.
• Persistence: Automatically saves and loads conversation IDs from localStorage based on the organizationId and chatbotId.

Tool Call Flow

1. AI generates a function_call.
2. Hook receives the call and adds a message with role: "function" to the state (internally).
3. Internal Behavior:
   • Backend Tools: The hook automatically calls confirmBackendTool(). This sends a confirmed message back to the server.
   • UI Tools: The hook notifies the developer via onToolCall.
4. Execution:
   • Backend Tools: The server receives the confirmation, executes the tool, and returns the real data in the next stream update.
   • UI Tools: The developer manually calls submitToolResult(data) with the result of the frontend execution.
5. The conversation resumes with the tool results included in the history.

Backend Tool Data Flow

User: "Show my playlists"
  ↓
AI calls: get_playlists() (role: function)
  ↓
Hook auto-confirms: internal confirmBackendTool() (sets confirmed: true)
  ↓
Server executes and returns: { playlists: [...] } (Actual data)
  ↓
AI receives data and responds: "Here are your playlists: ..."

Note: FUNCTION role messages are filtered out from the messages array returned by the hook to keep the UI clean. Only USER and ASSISTANT messages are exposed.

Building and Releasing

1. Build the package:

   npm run build

2. Release: This project uses semantic-release for automated versioning and npm publishing. Ensure your commit messages follow the Conventional Commits specification.