Skip to main content

Chat Feature

The AI-powered chat feature allows you to interact with your workspace in real-time using natural language.

Embedding Chat Components​

The core chat UI is the AiConversationPanel used alongside the WorkspaceProvider.

import { AiConversationPanel } from '@/components/ai-chat/AiConversationPanel';
import { WorkspaceProvider } from '@repo/core/workspace';

function MyWorkspacePage({ workspaceId, projectId }: { workspaceId: string; projectId: string }) {
  return (
    <WorkspaceProvider nodes={[]} edges={[]} workspaceId={workspaceId}>
      <div style={{ height: 600 }}>
        <AiConversationPanel sessionId={workspaceId} projectId={projectId} />
      </div>
    </WorkspaceProvider>
  );
}
  • sessionId associates messages with a conversation
  • projectId is used for dataset and document actions

How Tool-Calling Works​

The chat feature supports LLM tool-calling to interact with the workspace in real-time. This is achieved via WorkspaceProvider and the Vercel AI SDK useChat hook.

The updateWeirParameters Tool​

A key example of tool-calling is the updateWeirParameters tool. When the AI assistant determines that it needs to update the properties of a weir in the hydraulic model, it can call this tool.

Here's the flow:

  1. The user asks the AI to change a weir property (e.g., "Set the design head of the main weir to 5.5").
  2. The backend API receives the message and, using the Vercel AI SDK, passes the updateWeirParameters tool definition to the LLM.
  3. The LLM understands the user's intent and generates a tool call with the necessary arguments (e.g., nodeId and the updates object).
  4. The frontend AiConversationPanel receives this tool call via the onToolCall handler in the useChat hook.
  5. The handler then calls updateNodeData from the useWorkspace context.
  6. This updates the state of the nodes in the React Flow canvas, and the changes are immediately reflected in the WeirPanel component, which also consumes this context.

This creates a seamless loop where the AI can directly manipulate the application's state based on the user's conversation.

Limitations and Future Enhancements​

Current Limitations​

  • Single Tool: Currently, only the updateWeirParameters tool is implemented.
  • Error Handling: While the backend has basic error handling, the frontend could provide more specific feedback to the user when a tool call fails.
  • No Tool-Use Persistence: The fact that a tool was called is not yet saved in the chat history, which means the context is lost on a page refresh.

Future Enhancements​

  • More Tools: Implement more tools for interacting with other parts of the application (e.g., creating new nodes, running analyses).
  • Streaming UI for Tool Usage: Visually indicate to the user when the AI is using a tool.
  • Code Block Actions: Add "Copy" or "Insert" buttons to code blocks in chat messages.
  • Tool-Use Persistence: Save tool calls and their results to the ChatMessage model in the database.