orchid-ai 2.0.2 → 2.1.0

package/src/hooks/useOrchidAiChat.js

@@ -1,15 +1,25 @@
 import { useState, useCallback, useRef } from 'react';
+import {
+  ORCHID_AI_SSE_STATUS_CLEAR_STREAM,
+  orchidAiStatusClearsStreamBuffer,
+} from '../orchidAiStreamingTitle';
+import {
+  augmentLiveProcessTraceSnapshot,
+  createOrchidAiProcessTraceCollector,
+  snapshotOrchidAiProcessTraceItems,
+  orchidAiProcessTraceHasDisplayableContent,
+} from '../orchidAiProcessTrace';
 
 /**
  * Default status message strings. Export these so server-side code can import
  * and reference the same values, making it easy to keep client and server in sync
  * or swap them out per-app.
  *
- * Set showStatus: false on the hook to disable status display entirely.
+ * Set showStatus: false on the hook to suppress status display entirely.
  */
 export const ORCHID_AI_DEFAULT_STATUS = {
   thinking: 'Thinking',
-  compilingResponse: 'Compiling response',
+  compilingResponse: ORCHID_AI_SSE_STATUS_CLEAR_STREAM,
   lookingUpData: 'Looking up data',
 };
 
@@ -32,12 +42,8 @@ export function useOrchidAiChat({ endpoint, buildBody, getHeaders, showStatus =
   const [loading, setLoading] = useState(false);
   const [statusText, setStatusText] = useState('');
 
-  // Track messages in a ref so sendMessage always reads the latest without needing
-  // messages in its dependency array (avoids capturing stale history).
   const messagesRef = useRef(initialMessages);
 
-  // Keep latest callbacks in refs so sendMessage identity stays stable regardless
-  // of whether the parent re-creates buildBody/getHeaders each render.
   const buildBodyRef = useRef(buildBody);
   const getHeadersRef = useRef(getHeaders);
   buildBodyRef.current = buildBody;
@@ -70,10 +76,39 @@ export function useOrchidAiChat({ endpoint, buildBody, getHeaders, showStatus =
 
         const contentType = response.headers.get('content-type') ?? '';
 
-        if (contentType.includes('text/event-stream')) {
+        if (contentType.includes('text/event-stream') && response.body) {
           const reader = response.body.getReader();
           const decoder = new TextDecoder();
           let buffer = '';
+          const collector = createOrchidAiProcessTraceCollector();
+
+          addMessage({
+            role: 'assistant',
+            content: '',
+            isStreaming: true,
+            processTrace: snapshotOrchidAiProcessTraceItems(collector),
+            processInterimLive: '',
+          });
+
+          const patchStreamingAssistant = () => {
+            setMessages((prev) => {
+              const next = [...prev];
+              const last = next[next.length - 1];
+              if (last?.role !== 'assistant' || last?.isStreaming !== true) return prev;
+              next[next.length - 1] = {
+                ...last,
+                content: collector.getLiveMain(),
+                processTrace: augmentLiveProcessTraceSnapshot(
+                  snapshotOrchidAiProcessTraceItems(collector),
+                  collector.getLiveMain(),
+                  collector.getLiveInterim()
+                ),
+                processInterimLive: collector.getLiveInterim(),
+              };
+              messagesRef.current = next;
+              return next;
+            });
+          };
 
           while (true) {
             const { done, value } = await reader.read();
@@ -86,18 +121,54 @@ export function useOrchidAiChat({ endpoint, buildBody, getHeaders, showStatus =
               if (!line.startsWith('data: ')) continue;
               try {
                 const event = JSON.parse(line.slice(6));
-                if (event.type === 'status' && showStatus) {
-                  setStatusText(event.text);
+                if (event.type === 'status') {
+                  if (showStatus) setStatusText(event.text);
+                  collector.onStatus(event.text, {
+                    isClearStream: orchidAiStatusClearsStreamBuffer(event.text),
+                  });
+                  patchStreamingAssistant();
+                } else if (event.type === 'query') {
+                  collector.onQuery(event.tool, event.input);
+                  patchStreamingAssistant();
+                } else if (event.type === 'delta') {
+                  collector.onDelta(event.text);
+                  patchStreamingAssistant();
                 } else if (event.type === 'done') {
-                  addMessage({
-                    role: 'assistant',
-                    content: event.response,
-                    truncated: event.truncated,
+                  const rawTrace = collector.buildPersistedTrace();
+                  const trace =
+                    rawTrace && orchidAiProcessTraceHasDisplayableContent(rawTrace, '')
+                      ? rawTrace
+                      : undefined;
+                  setMessages((prev) => {
+                    const next = [...prev];
+                    const last = next[next.length - 1];
+                    const finalMsg = {
+                      role: 'assistant',
+                      content: event.response,
+                      truncated: event.truncated === true,
+                      ...(trace ? { processTrace: trace } : {}),
+                      ...(event.queryContext ? { queryContext: event.queryContext } : {}),
+                    };
+                    if (last?.role === 'assistant' && last?.isStreaming) {
+                      next[next.length - 1] = finalMsg;
+                    } else {
+                      next.push(finalMsg);
+                    }
+                    messagesRef.current = next;
+                    return next;
                   });
                 } else if (event.type === 'error') {
-                  addMessage({
-                    role: 'assistant',
-                    content: event.error || 'Something went wrong.',
+                  setMessages((prev) => {
+                    const next = [...prev];
+                    const last = next[next.length - 1];
+                    const errMsg = { role: 'assistant', content: event.error || 'Something went wrong.' };
+                    if (last?.role === 'assistant' && last?.isStreaming) {
+                      next[next.length - 1] = errMsg;
+                    } else {
+                      next.push(errMsg);
+                    }
+                    messagesRef.current = next;
+                    return next;
                   });
                 }
               } catch {
@@ -106,10 +177,14 @@ export function useOrchidAiChat({ endpoint, buildBody, getHeaders, showStatus =
             }
           }
         } else {
-          // Plain JSON fallback for non-streaming backends
           const data = await response.json();
           if (response.ok) {
-            addMessage({ role: 'assistant', content: data.response, truncated: data.truncated });
+            addMessage({
+              role: 'assistant',
+              content: data.response,
+              truncated: data.truncated,
+              ...(data.queryContext ? { queryContext: data.queryContext } : {}),
+            });
           } else {
             addMessage({ role: 'assistant', content: data.error || 'Something went wrong.' });
           }

package/src/index.d.ts

@@ -6,6 +6,21 @@ export interface ChatMessage {
   role: 'user' | 'assistant';
   content: string;
   truncated?: boolean;
+  /** When true, UI may show streaming placeholders (orchid-ai ChatWindow). */
+  isStreaming?: boolean;
+  /** Collapsible interim trace (statuses + pre-final text). Persisted for Hermes-style chats. */
+  processTrace?: {
+    items: Array<{ type: 'status' | 'text'; value: string }>;
+    defaultCollapsed?: boolean;
+  };
+  /** Live tool preamble not yet flushed into processTrace.items (streaming only). */
+  processInterimLive?: string;
+  /**
+   * Filters/parameters the AI used to query the database. Sent by the server in the
+   * `done` SSE event or JSON response as `queryContext`. Displayed when `showQuerySummary`
+   * is true on ChatWindow or Message.
+   */
+  queryContext?: Record<string, unknown>;
 }
 
 export interface ChatWindowProps {
@@ -15,6 +30,14 @@ export interface ChatWindowProps {
   onSuggestionClick?: (text: string) => void;
   aiEnabled?: boolean;
   organisationName?: string;
+  /** When false, tool/interim statuses show inline next to typing dots (Hermes / iLink config). */
+  showProcessTracePanel?: boolean;
+  /**
+   * When true, shows a collapsed "Filters used" disclosure under each assistant message
+   * that has a `queryContext`. Helps users understand why the AI returned specific data.
+   * Defaults to false.
+   */
+  showQuerySummary?: boolean;
   /** Any extra props are forwarded to the root element */
   [key: string]: unknown;
 }
@@ -31,6 +54,15 @@ export interface MessageProps {
   role: 'user' | 'assistant';
   content: string;
   truncated?: boolean;
+  exportPrefix?: string;
+  isStreaming?: boolean;
+  /** Shown above streaming content while server emits status (e.g. “Compiling response”). */
+  streamingStatusText?: string;
+  processTrace?: ChatMessage['processTrace'];
+  processInterimLive?: string;
+  showProcessTracePanel?: boolean;
+  queryContext?: Record<string, unknown>;
+  showQuerySummary?: boolean;
 }
 
 export const ChatWindow: React.FC<ChatWindowProps>;
@@ -134,6 +166,45 @@ export function validateTablePayload(data: unknown): boolean;
 export function parseChartBlock(block: string): unknown;
 export function resolveChartBlock(block: string): unknown;
 
+// ─── Process trace + SSE markers (Hermes) ───────────────────────────────────
+
+export function orchidAiProcessTraceEntryKind(entry: {
+  type: 'status' | 'text';
+  value: string;
+}): 'text' | 'tool' | 'compile' | 'mind';
+
+export function createOrchidAiProcessTraceCollector(): {
+  onStatus(text: string, opts?: { isClearStream?: boolean }): void;
+  onDelta(text: string): void;
+  getLiveMain(): string;
+  getLiveInterim(): string;
+  getItems(): Array<{ type: 'status' | 'text'; value: string }>;
+  reset(): void;
+  buildPersistedTrace():
+    | { items: Array<{ type: 'status' | 'text'; value: string }>; defaultCollapsed: boolean }
+    | undefined;
+};
+
+export function snapshotOrchidAiProcessTraceItems(
+  collector: ReturnType<typeof createOrchidAiProcessTraceCollector>
+): { items: Array<{ type: 'status' | 'text'; value: string }>; defaultCollapsed: boolean };
+
+export function augmentLiveProcessTraceSnapshot(
+  trace: { items: Array<{ type: 'status' | 'text'; value: string }>; defaultCollapsed: boolean },
+  streamingMain: string,
+  liveInterim?: string
+): { items: Array<{ type: 'status' | 'text'; value: string }>; defaultCollapsed: boolean };
+
+export function orchidAiProcessTraceHasDisplayableContent(
+  trace: ChatMessage['processTrace'] | undefined,
+  liveInterim: string | undefined,
+  options?: { isStreaming?: boolean }
+): boolean;
+
+/** SSE status before post-tool assistant text; client separates interim vs final answer. */
+export const ORCHID_AI_SSE_STATUS_CLEAR_STREAM: string;
+export function orchidAiStatusClearsStreamBuffer(statusText: unknown): boolean;
+
 // ─── Constants ───────────────────────────────────────────────────────────────
 
 export const ORCHID_AI_VISUALIZATION_INSTRUCTIONS: string;

package/src/index.js

@@ -50,3 +50,14 @@ export {
 
 // AI system prompt constant
 export { ORCHID_AI_VISUALIZATION_INSTRUCTIONS } from './constants/visualizationInstructions';
+
+export {
+  augmentLiveProcessTraceSnapshot,
+  createOrchidAiProcessTraceCollector,
+  orchidAiProcessTraceHasDisplayableContent,
+  snapshotOrchidAiProcessTraceItems,
+  orchidAiProcessTraceEntryKind,
+} from './orchidAiProcessTrace';
+
+// SSE + interim/process trace (Hermes)
+export { ORCHID_AI_SSE_STATUS_CLEAR_STREAM, orchidAiStatusClearsStreamBuffer } from './orchidAiStreamingTitle';

package/src/orchidAiProcessTrace.js

@@ -0,0 +1,175 @@
+import { ORCHID_AI_SSE_STATUS_CLEAR_STREAM } from './orchidAiStreamingTitle';
+
+/**
+ * Visual timeline lane for Message.jsx: tool-style statuses vs compile vs generic vs prose.
+ * @param {{ type: 'status' | 'text', value: string }} entry
+ * @returns {'text' | 'tool' | 'compile' | 'mind'}
+ */
+export function orchidAiProcessTraceEntryKind(entry) {
+  if (!entry || entry.type === 'text') return 'text';
+  const t = String(entry.value || '');
+  if (t.trim() === ORCHID_AI_SSE_STATUS_CLEAR_STREAM) return 'compile';
+  if (
+    /^Looking up/i.test(t) ||
+    /^Found \d+/i.test(t) ||
+    /^Searching the web/i.test(t) ||
+    /^Searching knowledge base/i.test(t)
+  ) {
+    return 'tool';
+  }
+  return 'mind';
+}
+
+/**
+ * Collects interim tool/preamble text + statuses for the Hermes / Orchid SSE stream.
+ * Final answer deltas go to getLiveMain(); pre-tool/streaming preamble goes to
+ * getLiveInterim() and (on "Compiling response") into frozen `items`.
+ *
+ * Phase machine:
+ * - `open_answer`: deltas accumulate in main (direct replies, or post-compile answer).
+ * - When a tool-style status arrives (e.g. "Looking up jobs"), migrate main → interim and enter `tool_interim`.
+ * - `tool_interim`: deltas go to interim; on `Compiling response`, flush interim to items and return to `open_answer`.
+ */
+export function createOrchidAiProcessTraceCollector() {
+  /** @type {'open_answer' | 'tool_interim'} */
+  let phase = 'open_answer';
+  let preBuf = '';
+  let mainBuf = '';
+  /** @type {{ type: 'status' | 'text', value: string }[]} */
+  const items = [];
+
+  /** @param {string} text */
+  function toolishStatus(text) {
+    const t = String(text || '');
+    return (
+      /^Looking up/i.test(t) ||
+      /^Found \d+/i.test(t) ||
+      /^Searching the web/i.test(t) ||
+      /^Searching knowledge base/i.test(t)
+    );
+  }
+
+  return {
+    /**
+     * @param {string} tool - tool name e.g. "query_orders"
+     * @param {Record<string, unknown>} input - raw tool input parameters
+     */
+    onQuery(tool, input) {
+      items.push({ type: 'query', tool: String(tool), input: input || {} });
+    },
+    /**
+     * @param {string} text
+     * @param {{ isClearStream?: boolean }} [opts] — true for {@link ORCHID_AI_SSE_STATUS_CLEAR_STREAM}
+     */
+    onStatus(text, opts = {}) {
+      const isClearStream = opts.isClearStream === true;
+      if (isClearStream) {
+        if (preBuf) items.push({ type: 'text', value: preBuf });
+        preBuf = '';
+        phase = 'open_answer';
+        items.push({ type: 'status', value: String(text) });
+        return;
+      }
+      if (toolishStatus(text) && phase === 'open_answer') {
+        phase = 'tool_interim';
+        if (mainBuf) {
+          preBuf = mainBuf;
+          mainBuf = '';
+        }
+      }
+      items.push({ type: 'status', value: String(text) });
+    },
+    /** @param {string} text */
+    onDelta(text) {
+      const t = String(text);
+      if (phase === 'tool_interim') preBuf += t;
+      else mainBuf += t;
+    },
+    getLiveMain() {
+      return mainBuf;
+    },
+    getLiveInterim() {
+      return phase === 'tool_interim' ? preBuf : '';
+    },
+    /** @returns {{ type: 'status' | 'text', value: string }[]} */
+    getItems() {
+      return items;
+    },
+    reset() {
+      phase = 'open_answer';
+      preBuf = '';
+      mainBuf = '';
+      items.length = 0;
+    },
+    /** Persisted shape for assistant bubbles; omit when nothing to show. */
+    buildPersistedTrace() {
+      if (!items.length) return undefined;
+      return {
+        items: items.map(serializeTraceItem),
+        defaultCollapsed: true,
+      };
+    },
+  };
+}
+
+function serializeTraceItem(x) {
+  if (x.type === 'query') return { type: 'query', tool: x.tool, input: x.input };
+  return { type: x.type, value: x.value };
+}
+
+/** Snapshot `items` for React state / persisted shape (live streaming; not collapsed). */
+export function snapshotOrchidAiProcessTraceItems(collector) {
+  const items = collector.getItems();
+  return {
+    items: items.map(serializeTraceItem),
+    defaultCollapsed: false,
+  };
+}
+
+/**
+ * Display-only: Hermes sends one `status` ("Thinking") then `delta` chunks for direct replies.
+ * Deltas never become timeline rows, so the Working panel would stay on Thinking forever.
+ * Append a synthetic step while streamed content exists (not persisted — see `buildPersistedTrace`).
+ *
+ * @param {{ items: Array<{ type: 'status' | 'text', value: string }>, defaultCollapsed: boolean }} trace
+ * @param {string} streamingMain
+ * @param {string} [liveInterim]
+ */
+export function augmentLiveProcessTraceSnapshot(trace, streamingMain, liveInterim = '') {
+  if (!trace || !Array.isArray(trace.items)) return trace;
+  const items = trace.items;
+  const mainTrim = typeof streamingMain === 'string' ? streamingMain.trim() : '';
+  const interimTrim = typeof liveInterim === 'string' ? liveInterim.trim() : '';
+
+  const onlyThinking =
+    items.length === 1 &&
+    items[0]?.type === 'status' &&
+    String(items[0].value || '').trim().toLowerCase() === 'thinking';
+
+  if (!onlyThinking) return trace;
+
+  if (mainTrim.length > 0) {
+    return {
+      ...trace,
+      items: [...items, { type: 'status', value: 'Drafting response' }],
+    };
+  }
+  if (interimTrim.length > 0) {
+    return {
+      ...trace,
+      items: [...items, { type: 'status', value: 'Gathering details' }],
+    };
+  }
+  return trace;
+}
+
+/** Whether to render the process trace panel. Pass `{ isStreaming: true }` during SSE so a lone “Thinking” status still opens the live tray. */
+export function orchidAiProcessTraceHasDisplayableContent(trace, liveInterim, options) {
+  const isStreaming = options?.isStreaming === true;
+  if (typeof liveInterim === 'string' && liveInterim.trim() !== '') return true;
+  const list = trace?.items;
+  if (!Array.isArray(list) || list.length === 0) return false;
+  if (isStreaming) return true;
+  if (list.some((i) => i && i.type === 'text' && String(i.value || '').trim() !== '')) return true;
+  return list.length > 1;
+}

package/src/orchidAiStreamingTitle.js

@@ -0,0 +1,12 @@
+/**
+ * SSE `status` emitted by Hermes immediately before streaming the post-tool assistant message.
+ * Clients use this to separate interim text from the final answer (see `orchidAiProcessTrace`).
+ *
+ * Keep in sync with `onStatus?.('Compiling response')` in iLink `orchidAiAnthropicChat.js`.
+ */
+export const ORCHID_AI_SSE_STATUS_CLEAR_STREAM = 'Compiling response';
+
+/** @param {unknown} statusText from `{ type: 'status', text }` */
+export function orchidAiStatusClearsStreamBuffer(statusText) {
+  return typeof statusText === 'string' && statusText.trim() === ORCHID_AI_SSE_STATUS_CLEAR_STREAM;
+}