​

Claude AI Integration

​

Model Configuration

• Client – createAnthropicClient() initialises the official Anthropic SDK, sourcing API keys and endpoints from environment variables (ANTHROPIC_API_KEY, optional proxy URLs).
• Defaults – buildAnthropicParamsForConversation sets model claude-3-5-sonnet-20241022, temperature tuned for deterministic outputs, and enables tool use with the active tool list.
• Token Limits – tokenLimit defines the maximum input size. Before each call, isHistoryExceedingTokenLimit counts tokens via messages.countTokens to determine if compacting is required.

​

Streaming Responses

• The orchestrator calls client.messages.stream (via streamClaudeResponseAndHandleToolUsage) and forwards deltas to the UI as stream:delta.
• Each delta arrives as structured JSON, enabling partial rendering and progress indicators.
• When the stream ends, the router emits stream:end with trace metadata so the UI can finalise the message.

​

Tool Use

• Claude selects from registered tools, emitting tool_use blocks. The backend intercepts them, stores a ToolChangeInterface, and pauses the stream until the user decision arrives.
• For each approved tool, the result is converted to Markdown (or JSON) and inserted back into the conversation history as a tool_result. This ensures Claude references actual outputs in subsequent reasoning steps.

​

Error Handling & Retries

• User Cancellations – Trigger a UserCancellationError, log a negative score in Langfuse, and notify the UI with stream:cancelled.
• Claude Errors – extractClaudeErrorType and mapClaudeErrorToPayload classify errors (e.g., rate limit, invalid request). The UI displays friendly messages and suggests retry strategies.
• Tool Failures – If a tool throws ToolExecutionError, the backend serialises the error, updates conversation history so Claude knows the failure details, and resumes the stream to let the model recover.

​

Attachments & Multimodal Inputs

• PDF and image attachments are added to the conversation as Claude document blocks (type: "document" or "image"), so the model can reason about their content alongside workbook context.
• Langfuse metadata captures attachment counts and sizes for auditing.