@alquimia-ai/tools 1.13.2 → 2.1.0

package/dist/hooks/index.mjs

@@ -1,5 +1,223 @@
 // src/hooks/alquimia.hook.tsx
-import { useRef, useState } from "react";
+import { useMemo, useRef, useState } from "react";
+
+// src/sdk/alquimia-sdk.ts
+import axios from "axios";
+var AlquimiaSDK = class {
+  constructor(assistantId, adapter, options = {}) {
+    this.conversationId = null;
+    this.sessionId = null;
+    // Internal subscription id from infer (`taskid` on the wire).
+    this.streamId = null;
+    this.tools = [];
+    this.extraInstructions = null;
+    this.assistantConfig = null;
+    this.userId = null;
+    this.attachments = [];
+    this.attachmentResponses = [];
+    if (!assistantId) {
+      throw new Error("AlquimiaSDK: assistantId is required");
+    }
+    if (!adapter) {
+      throw new Error(
+        "AlquimiaSDK: adapter is required. Use createNextJsAdapter() or createFetchAdapter()"
+      );
+    }
+    this.assistantId = assistantId;
+    this.adapter = adapter;
+    this.enforceCharacterization = options.enforceCharacterization ?? true;
+    this.axiosInstance = axios.create();
+    this.axiosInstance.interceptors.response.use(
+      (response) => response,
+      async (error) => {
+        if (error.response?.status && this.loggerProvider) {
+          await this.loggerProvider.logError("Server Error", error, {
+            url: error.config.url,
+            method: error.config.method,
+            data: error.config.data,
+            status: error.response.status,
+            responseData: error.response.data
+          });
+        }
+        return Promise.reject(error);
+      }
+    );
+    this.textToSpeech = this.textToSpeech.bind(this);
+    this.speechToText = this.speechToText.bind(this);
+  }
+  withConversationId(conversationId) {
+    this.conversationId = conversationId;
+    return this;
+  }
+  withAttachments(attachments) {
+    this.attachments = attachments;
+    return this;
+  }
+  withWhisperProvider(provider) {
+    this.whisperProvider = provider;
+    return this;
+  }
+  withStableDiffusionProvider(provider) {
+    this.stableDiffusionProvider = provider;
+    return this;
+  }
+  withAnalyzeCharacterizationProvider(provider) {
+    this.analyzeCharacterizationProvider = provider;
+    return this;
+  }
+  withRatingsProvider(provider) {
+    this.ratingsProvider = provider;
+    return this;
+  }
+  withLoggerProvider(provider) {
+    this.loggerProvider = provider;
+    return this;
+  }
+  withTools(tools) {
+    this.tools = tools;
+    return this;
+  }
+  withExtraInstructions(extraInstructions) {
+    this.extraInstructions = extraInstructions;
+    return this;
+  }
+  withAssistantConfig(assistantConfig) {
+    this.assistantConfig = assistantConfig;
+    return this;
+  }
+  withUserId(userId) {
+    this.userId = userId;
+    return this;
+  }
+  getEnforceCharacterization() {
+    return this.enforceCharacterization ?? true;
+  }
+  textToSpeech(text) {
+    if (!this.whisperProvider) {
+      throw new Error("Whisper provider not initialized");
+    }
+    return this.whisperProvider.textToSpeech(text);
+  }
+  speechToText(audio) {
+    if (!this.whisperProvider) {
+      throw new Error("Whisper provider not initialized");
+    }
+    return this.whisperProvider.speechToText(audio);
+  }
+  async sendMessage(query, traceParent) {
+    if (!this.conversationId) {
+      throw new Error(
+        "Conversation not initialized. Call withConversationId() before sendMessage()"
+      );
+    }
+    const inferUrl = this.adapter.resolveInferUrl(this.assistantId);
+    const adapterHeaders = this.adapter.getHeaders?.() ?? {};
+    const hasClientTools = Array.isArray(this.tools) && this.tools.length > 0;
+    const initMessage = {
+      query,
+      session_id: this.conversationId,
+      user_id: this.userId,
+      ...this.extraInstructions && { extra_instructions: this.extraInstructions },
+      ...this.assistantConfig && { config: this.assistantConfig },
+      ...hasClientTools && {
+        evaluation_strategy: {
+          evaluation_strategy_id: "native",
+          tool_schemas: this.tools
+        }
+      }
+    };
+    const result = (await this.axiosInstance.post(inferUrl, initMessage, {
+      headers: {
+        "Content-Type": "application/json",
+        "x-trace-parent": traceParent || "",
+        ...adapterHeaders,
+        ...this.buildIdentityHeaders()
+      }
+    })).data;
+    this.streamId = result.taskid ?? null;
+    this.attachmentResponses = result.attachments ?? [];
+    this.attachments = [];
+    return this;
+  }
+  async generateImage(query) {
+    if (!this.stableDiffusionProvider) {
+      throw new Error("Stable Diffusion provider not initialized");
+    }
+    return this.stableDiffusionProvider.generateImage(query);
+  }
+  async analyzeCharacterization(text) {
+    if (!this.analyzeCharacterizationProvider) {
+      throw new Error("Analyze characterization provider not initialized");
+    }
+    return this.analyzeCharacterizationProvider.analyzeCharacterization(text);
+  }
+  async rate(data) {
+    if (!this.ratingsProvider) {
+      throw new Error("Ratings provider not initialized");
+    }
+    return this.ratingsProvider.rate(data);
+  }
+  async logInfo(message, data) {
+    if (!this.loggerProvider) {
+      throw new Error("Logger provider not initialized");
+    }
+    return this.loggerProvider.logInfo(message, data);
+  }
+  async logError(message, error, data) {
+    if (!this.loggerProvider) {
+      throw new Error("Logger provider not initialized");
+    }
+    return this.loggerProvider.logError(message, error, data);
+  }
+  /**
+   * @deprecated The runtime no longer returns attachment IDs from the infer
+   * response — attachments are uploaded as standalone blobs and linked to the
+   * session via headers. Always returns `[]`; kept for source compatibility.
+   */
+  getAttachmentResponses() {
+    return this.attachmentResponses;
+  }
+  async uploadAttachment(file, _attachmentId) {
+    const url = this.adapter.resolveBlobUploadUrl();
+    const adapterHeaders = this.adapter.getHeaders?.() ?? {};
+    const formData = new FormData();
+    formData.append("file", file);
+    await this.axiosInstance.post(url, formData, {
+      headers: {
+        "Content-Type": "multipart/form-data",
+        ...adapterHeaders,
+        ...this.buildIdentityHeaders()
+      }
+    });
+  }
+  /**
+   * Identity headers (kebab-case) required by `/context/blob/upload` and
+   * the rest of the runtime's internal endpoints introduced in v0.2.0→next.
+   */
+  buildIdentityHeaders() {
+    const headers = {
+      "assistant-id": this.assistantId
+    };
+    if (this.conversationId) headers["session-id"] = this.conversationId;
+    if (this.userId) headers["user-id"] = this.userId;
+    if (this.streamId) headers["task-id"] = this.streamId;
+    return headers;
+  }
+  getUrlStream() {
+    if (!this.streamId) {
+      throw new Error("Stream ID not initialized. Call sendMessage() first");
+    }
+    return this.adapter.resolveStreamUrl(this.streamId);
+  }
+  getStreamId() {
+    return this.streamId;
+  }
+  /** Alias for {@link getStreamId} — same value as infer `taskid`. */
+  getTaskId() {
+    return this.streamId;
+  }
+};
+var alquimia_sdk_default = AlquimiaSDK;
 
 // src/utils/utils.ts
 function getCookies(name) {
@@ -84,7 +302,20 @@ function mergeToolEvents(initial, toolEvents) {
 }
 
 // src/hooks/alquimia.hook.tsx
-function useAlquimia(sdk) {
+function useAlquimia(config) {
+  const sdk = useMemo(() => {
+    const instance = new alquimia_sdk_default(config.assistantId, config.adapter, {
+      enforceCharacterization: config.options?.enforceCharacterization
+    });
+    if (config.providers?.whisper) instance.withWhisperProvider(config.providers.whisper);
+    if (config.providers?.stableDiffusion) instance.withStableDiffusionProvider(config.providers.stableDiffusion);
+    if (config.providers?.characterization) instance.withAnalyzeCharacterizationProvider(config.providers.characterization);
+    if (config.providers?.ratings) instance.withRatingsProvider(config.providers.ratings);
+    if (config.providers?.logger) instance.withLoggerProvider(config.providers.logger);
+    if (config.options?.userId) instance.withUserId(config.options.userId);
+    if (config.options?.extraInstructions) instance.withExtraInstructions(config.options.extraInstructions);
+    return instance;
+  }, [config.assistantId, config.adapter]);
   const [input, setInput] = useState("");
   const [isMessageLoading, setIsMessageLoading] = useState(false);
   const [isStreamingLoading, setIsStreamingLoading] = useState(false);
@@ -93,10 +324,10 @@ function useAlquimia(sdk) {
   const [isAudioRecording, setIsAudioRecording] = useState(false);
   const [messages, setMessages] = useState([]);
   const eventSourceRef = useRef(null);
+  const streamUserCancelledRef = useRef(false);
   const [sessionId, setSessionId] = useState(null);
   const [activeTool, setActiveTool] = useState(null);
   const [lastRequest, setLastRequest] = useState(null);
-  const [evaluationStrategy, setEvaluationStrategy] = useState("");
   const [hasThinkings, setHasThinkings] = useState(false);
   const [attachments, setAttachments] = useState([]);
   const [isUploadingAttachments, setIsUploadingAttachments] = useState(false);
@@ -117,11 +348,9 @@ function useAlquimia(sdk) {
   function clearAttachments() {
     setAttachments([]);
   }
-  function processMessageChunk(messageId, chunk, error_code, error_detail, stream_id, additionalInfo, loading, tooler, thinkings) {
+  function processMessageChunk(messageId, chunk, error_code, error_detail, taskid, additionalInfo, loading, tooler, thinkings) {
     setMessages((currentMessages) => {
-      const messageIndex = currentMessages.findIndex(
-        (message) => message?.id === messageId
-      );
+      const messageIndex = currentMessages.findIndex((message) => message?.id === messageId);
       if (messageIndex !== -1) {
         const updatedMessages = [...currentMessages];
         const updatedMessage = {
@@ -131,14 +360,11 @@ function useAlquimia(sdk) {
           role: updatedMessages[messageIndex]?.role || "assistant",
           error_code,
           error_detail,
-          stream_id,
+          taskid,
           additionalInfo,
           created_at: (/* @__PURE__ */ new Date()).getTime().toString(),
           loading,
-          tooler: mergeToolEvents(
-            updatedMessages[messageIndex]?.tooler || [],
-            tooler
-          ),
+          tooler: mergeToolEvents(updatedMessages[messageIndex]?.tooler || [], tooler),
           thinkings: mergeThinkingsByControlId(
             updatedMessages[messageIndex]?.thinkings || [],
             thinkings || []
@@ -155,7 +381,7 @@ function useAlquimia(sdk) {
             id: messageId,
             error_code,
             error_detail,
-            stream_id,
+            taskid,
             created_at: (/* @__PURE__ */ new Date()).getTime().toString(),
             loading,
             tooler: mergeToolEvents([], tooler),
@@ -177,7 +403,7 @@ function useAlquimia(sdk) {
           chunk?.answer || "",
           chunk?.error_code,
           chunk?.error_detail,
-          chunk?.stream_id,
+          chunk?.taskid,
           options?.additionalInfo,
           chunk?.loading,
           chunk?.tooler,
@@ -193,11 +419,7 @@ function useAlquimia(sdk) {
     setIsMessageLoading(true);
     event.preventDefault();
     if (input) {
-      await processAndSendMessage(input, {
-        traceParentId,
-        sessionId: sessionId2,
-        additionalInfo
-      });
+      await processAndSendMessage(input, { traceParentId, sessionId: sessionId2, additionalInfo });
     }
     setIsMessageLoading(false);
   }
@@ -221,6 +443,7 @@ function useAlquimia(sdk) {
     setMessages(messages2);
   }
   function handleLoadingCancel() {
+    streamUserCancelledRef.current = true;
     eventSourceRef.current?.close();
     eventSourceRef.current = null;
     setIsMessageLoading(false);
@@ -244,7 +467,7 @@ function useAlquimia(sdk) {
   }
   function getCookie(name) {
     const cookies = document.cookie.split(";");
-    for (let cookie of cookies) {
+    for (const cookie of cookies) {
       const [cookieName, cookieValue] = cookie.trim().split("=");
       if (cookieName === name) {
         return decodeURIComponent(cookieValue);
@@ -260,23 +483,22 @@ function useAlquimia(sdk) {
   }
   async function sendMessage(message, callBack, traceParentId, sessionId2) {
     setIsStreamingLoading(true);
-    callBack({
-      type: "loading",
-      loading: true
-    });
+    callBack({ type: "loading", loading: true });
     const conversationId = sessionId2 || getCookie("alquimia-session");
     setIsMessageStreaming(true);
     setActiveTool(null);
     setLastRequest(message);
     try {
       const hasAttachments = attachments.length > 0;
-      const sdkCall = sdk.widthConversationId(conversationId || "");
+      const sdkCall = sdk.withConversationId(conversationId || "");
       if (hasAttachments) {
-        sdkCall.withAttachments(attachments.map((f) => ({
-          filename: f.name,
-          content_type: f.type,
-          content_size: f.size
-        })));
+        sdkCall.withAttachments(
+          attachments.map((f) => ({
+            filename: f.name,
+            content_type: f.type,
+            content_size: f.size
+          }))
+        );
       }
       const response = await sdkCall.sendMessage(message, traceParentId);
       if (hasAttachments) {
@@ -284,9 +506,7 @@ function useAlquimia(sdk) {
         try {
           const attachmentResponses = response.getAttachmentResponses();
           await Promise.all(
-            attachments.map(
-              (file, i) => response.uploadAttachment(file, attachmentResponses[i])
-            )
+            attachments.map((file, i) => response.uploadAttachment(file, attachmentResponses[i]))
           );
         } catch (uploadError) {
           setIsUploadingAttachments(false);
@@ -305,6 +525,7 @@ function useAlquimia(sdk) {
       }
       const streamUrl = response.getUrlStream();
       const streamId = response.getStreamId() || "";
+      streamUserCancelledRef.current = false;
       const streamState = {
         streamId,
         connectedAt: Date.now(),
@@ -315,8 +536,6 @@ function useAlquimia(sdk) {
       };
       const eventSource = new EventSource(streamUrl);
       eventSourceRef.current = eventSource;
-      const evaluationStrategy2 = response.getEvaluationStrategy();
-      setEvaluationStrategy(evaluationStrategy2);
       eventSource.onopen = () => {
         streamState.openedAt = Date.now();
       };
@@ -327,23 +546,37 @@ function useAlquimia(sdk) {
       };
       eventSource.onerror = () => {
         if (streamState.closedByClient) return;
+        if (streamUserCancelledRef.current) {
+          streamUserCancelledRef.current = false;
+          return;
+        }
         streamState.closedByClient = true;
         const elapsed = Date.now() - streamState.connectedAt;
         const sinceLastMessage = streamState.lastMessageAt ? Date.now() - streamState.lastMessageAt : null;
         cleanup(false, eventSource);
         let errorDetail;
         if (!streamState.openedAt) {
-          errorDetail = `Stream failed to connect (after ${elapsed}ms). URL: ${streamUrl}`;
+          errorDetail = "Could not open the live response. Check your connection and try again.";
         } else if (streamState.messagesReceived === 0) {
-          errorDetail = `Stream connected but received no messages before error (open for ${elapsed}ms).`;
+          errorDetail = "No response was received. Try again in a moment.";
         } else {
-          errorDetail = `Stream dropped after ${streamState.messagesReceived} message(s), ${sinceLastMessage}ms since last message (total ${elapsed}ms). Possible timeout.`;
+          errorDetail = "The response was interrupted. Try again.";
+        }
+        if (typeof console !== "undefined" && console.debug) {
+          console.debug("[Alquimia] SSE transport error", {
+            streamUrl,
+            taskId: streamId,
+            opened: Boolean(streamState.openedAt),
+            messagesReceived: streamState.messagesReceived,
+            elapsedMs: elapsed,
+            sinceLastMessageMs: sinceLastMessage
+          });
         }
         callBack({
           type: "error",
           error_code: "STREAM_ERROR",
           error_detail: errorDetail,
-          stream_id: streamId
+          taskid: streamId
         });
       };
     } catch (error) {
@@ -354,13 +587,14 @@ function useAlquimia(sdk) {
       setStreamingMessageId(null);
       callBack({
         type: "error",
-        error_code: error.status?.toString() || "REQUEST_ERROR",
+        error_code: error.response?.status != null ? String(error.response.status) : "REQUEST_ERROR",
         error_detail: errMessage
       });
     }
   }
   function handleMessageEvent(event, callBack, eventSource, streamState) {
     const data = JSON.parse(event.data);
+    const eventTaskId = data.taskid || "";
     if (data.errors?.length) {
       for (const error of data.errors) {
         const detail = error.error_detail || (error.data != null ? `${error.data} (controlId: ${error.control_id})` : "Unknown error");
@@ -368,7 +602,7 @@ function useAlquimia(sdk) {
           type: "error",
           error_code: error.event_class || error.status || "UNKNOWN_ERROR",
           error_detail: detail,
-          stream_id: data.stream_id || ""
+          taskid: eventTaskId
         });
       }
       if (streamState) streamState.closedByClient = true;
@@ -376,31 +610,21 @@ function useAlquimia(sdk) {
       return;
     }
     if (data.tools_output?.length) {
-      callBack({
-        type: "answer",
-        answer: "",
-        tooler: data.tools_output
-      });
+      callBack({ type: "answer", answer: "", tooler: data.tools_output });
     }
     if (data.thinkings?.length) {
       setHasThinkings(true);
-      callBack({
-        type: "answer",
-        thinkings: data.thinkings
-      });
+      callBack({ type: "answer", thinkings: data.thinkings });
     }
-    const response = data.response;
-    const content = response?.event_class === "AssistantInferenceResponse" && typeof response.data === "string" ? response.data : null;
-    if (content) {
-      callBack({
-        type: "answer",
-        answer: content
-      });
+    if (data.event_class === "AssistantInferenceResponse") {
+      const final = data;
+      callBack({ type: "answer", answer: final.data });
       if (streamState) streamState.closedByClient = true;
       cleanup(false, eventSource);
     }
   }
   return {
+    sdk,
     activeTool,
     cleanMessages,
     createMessageId,
@@ -411,7 +635,9 @@ function useAlquimia(sdk) {
     handleLoadingCancel,
     input,
     isLoading,
+    isMessageLoading,
     isMessageStreaming,
+    isStreamingLoading,
     streamingMessageId,
     isAudioRecording,
     lastRequest,
@@ -424,7 +650,6 @@ function useAlquimia(sdk) {
     setSessionId,
     setLastRequest,
     setIsAudioRecording,
-    evaluationStrategy,
     hasThinkings,
     attachments,
     addAttachment,