@ixo/common 1.1.0

package/src/ai/semantic-router-factory/semantic-router-prompt.ts

@@ -0,0 +1,168 @@
+export const semanticRouterPrompt = `You are semantic router responsible for determining the next route based on the given routes and state.
+
+**Instructions:**
+
+1. **Read the Input:**
+   - You will receive two pieces of input:
+     - **Routes**: A set of named routes with specific conditions that need to be evaluated.
+     - **State**: A set of properties that will be used to determine the next route. from the conditions provided in the routes.
+
+2. **Understand the Conditions Format:**
+   - Conditions will be provided in a human-readable format. They may involve:
+     - Checking the value of specific properties (e.g., "if the user type is 'admin'").
+     - Evaluating multiple conditions with logical connectors like "AND" or "OR" (e.g., "if the user type is 'guest' AND the access level is 'restricted'").
+   - Your task is to convert these human-readable conditions into logical expressions that can be evaluated programmatically.
+
+3. **Special Handling for Message Arrays:**
+   - If the state contains a 'messages' array, respect their chronological order.
+   - The most recent messages (at the end of the array) should have higher significance for determining intent.
+   - Pay special attention to the last user message as it often contains the most current intent.
+
+4. **Evaluate Each Route:**
+   - For each route, check if the current state satisfies the condition:
+     - Example:
+       - Condition: "if the user type is 'admin' AND the access level is 'full'"
+       - State: 
+         \`\`\`yaml
+         userType: admin
+         accessLevel: limited
+         \`\`\`
+       - Evaluation: This condition does NOT match because \`accessLevel\` is 'limited', not 'full'.
+
+5. **Return the Matching Route:**
+   - Identify and return the name of the first route where all conditions are met.
+   - If no route matches, return 'undefined'.
+
+**Example 1:**
+
+- **Routes:**
+  \`\`\`yaml
+  adminDashboard: "if the user type is 'admin' AND the access level is 'full'"
+  guestAccess: "if the user type is 'guest' AND the access level is 'restricted'"
+  viewOnlyMode: "if the access level is 'view-only'"
+  \`\`\`
+  
+- **State:**
+  \`\`\`yaml
+  userType: guest
+  accessLevel: restricted
+  \`\`\`
+
+**Evaluation:**
+- **adminDashboard**: Does not match (user type is 'guest', not 'admin').
+- **guestAccess**: Matches (user type is 'guest' and access level is 'restricted').
+- **viewOnlyMode**: Does not match (access level is 'restricted', not 'view-only').
+
+**Result:**
+- Output: "guestAccess"
+
+---
+
+**Example 2:**
+
+- **Routes:**
+  \`\`\`yaml
+  escalateTicket: "if the ticket priority is 'high' AND the status is 'open'"
+  autoClose: "if the ticket status is 'resolved' AND the resolution time is less than 2 days"
+  notifySupervisor: "if the ticket priority is 'high' OR the customer rating is less than 3"
+  \`\`\`
+
+- **State:**
+  \`\`\`yaml
+  ticketPriority: high
+  status: open
+  customerRating: 4
+  \`\`\`
+
+**Evaluation:**
+- **escalateTicket**: Matches (priority is 'high' and status is 'open').
+- **autoClose**: Does not match (status is 'open', not 'resolved').
+- **notifySupervisor**: Also matches (priority is 'high').
+
+**Result:**
+- Output: "escalateTicket" (First match found based on input order)
+
+---
+
+**Example 3 (with Messages):**
+
+- **Routes:**
+  \`\`\`yaml
+  chatMode: "if the messages contain casual conversation or greetings"
+  taskExecution: "if the messages indicate a specific task to be performed"
+  informationRequest: "if the messages contain questions about how to use the system"
+  \`\`\`
+
+- **State:**
+  \`\`\`yaml
+  messages:
+    - sender: user
+      content: "Hello there!"
+    - sender: assistant
+      content: "Hi! How can I help you today?"
+    - sender: user
+      content: "I need to create a new domain for my project."
+  \`\`\`
+
+**Evaluation:**
+- **chatMode**: Does not match fully (initial messages were greetings, but the final message indicates a task).
+- **taskExecution**: Matches (the last message clearly indicates a specific task - domain creation).
+- **informationRequest**: Does not match (no questions about system usage).
+
+**Result:**
+- Output: "taskExecution" (Based on the latest user intent in the message array)
+
+---
+
+**Example 4:**
+
+- **Routes:**
+  \`\`\`yaml
+  initiateRefund: "if the order status is 'cancelled' AND the payment method is 'credit card'"
+  followUp: "if the order status is 'shipped' AND the delivery status is 'delayed'"
+  quickResolve: "if the order status is 'delivered' AND the customer feedback is 'positive'"
+  \`\`\`
+
+- **State:**
+  \`\`\`yaml
+  orderStatus: shipped
+  deliveryStatus: delayed
+  paymentMethod: credit card
+  \`\`\`
+
+**Evaluation:**
+- **initiateRefund**: Does not match (order status is 'shipped', not 'cancelled').
+- **followUp**: Matches (order status is 'shipped' and delivery status is 'delayed').
+- **quickResolve**: Does not match (order status is 'shipped', not 'delivered').
+
+**Result:**
+- Output: "followUp"
+
+**Goal:**
+- Analyze the routes and state provided.
+- Explain each evaluation step clearly.
+- Return the correct route name or "undefined" if no match is found.
+
+**Output Format:**
+- Provide a single line output with the name of the matched route or "undefined".
+
+**Additional Notes:**
+- Be precise and ensure the evaluation logic follows the conditions specified.
+- If multiple conditions are specified, all must be met for a route to be valid.
+- The decision should be based on clear, logical reasoning derived from the state values.
+- When messages are included, prioritize the most recent message for determining intent.
+- Message ordering represents the chronological flow of conversation - later messages reflect the most current intent.
+
+----
+YOUR MISSION IS TO RESOLVE THE ROUTE BASED ON THE STATE PROVIDED. GOOD LUCK!
+
+- **Routes:**
+\`\`\`yaml
+{routes}
+\`\`\`
+
+- **State:**
+\`\`\`yaml
+{state}
+\`\`\`
+`;

package/src/ai/semantic-router-factory/validate-routes.ts

@@ -0,0 +1,26 @@
+export const validateRoutes = <
+  K extends string[],
+  R extends Record<string, string> = Record<string, string>,
+>(
+  routes: R,
+  basedOn: K,
+): (keyof R)[] => {
+  const keys = Object.keys(routes) as (keyof R)[];
+  if (keys.length <= 1) {
+    throw new Error(
+      `The routes must have at least 2 routes ${keys.toString()} provided`,
+    );
+  }
+  for (const key in routes) {
+    const value = routes[key];
+
+    basedOn.forEach((element) => {
+      if (!value?.includes(element)) {
+        throw new Error(
+          `Invalid route map the value of the route ${key} must include the ${basedOn.toString()} So that the route can be resolve the path`,
+        );
+      }
+    });
+  }
+  return keys;
+};

package/src/ai/tools/action-caller.ts

@@ -0,0 +1,37 @@
+import { callFrontendTool } from './frontend-tool-caller.js';
+
+export interface AgActionResult {
+  result?: any;
+  error?: string;
+  success: boolean;
+}
+
+export interface IAgActionCallerParams {
+  sessionId: string;
+  toolCallId: string;
+  toolName: string;
+  args: any;
+  timeout?: number;
+}
+
+/**
+ * Call an AG-UI action that executes on the frontend and wait for the result
+ * @param params - The parameters for the AG-UI action call
+ * @returns Promise that resolves with the action result
+ */
+export async function callAgAction({
+  sessionId,
+  toolCallId,
+  toolName,
+  args,
+  timeout = 10000, // 10 seconds for UI actions
+}: IAgActionCallerParams): Promise<any> {
+  return callFrontendTool({
+    sessionId,
+    toolId: toolCallId,
+    toolName,
+    args,
+    toolType: 'agui',
+    timeout,
+  });
+}

package/src/ai/tools/ask-ixo-guru/ask-ixo-guru.ts

@@ -0,0 +1,73 @@
+import { tool } from '@langchain/core/tools';
+import  z from 'zod';
+import { jsonToYaml } from '../../utils/json-to-yaml.js';
+
+export type RequestPayload = {
+  message: string;
+  did: string;
+  sessionId: string;
+};
+
+export type ResponsePayload = {
+  message: {
+    type: 'ai';
+    content: string;
+  };
+  docs: [];
+  sessionId: string;
+};
+
+const callGuruApi = async ({
+  question,
+  sessionId,
+}: {
+  question: string;
+  sessionId: string;
+}): Promise<string> => {
+  if (!process.env.IXO_GURU_QUERY_ENDPOINT) {
+    throw new Error('IXO Guru API URL is not set');
+  }
+
+  if (!process.env.GURU_ASSISTANCE_API_TOKEN) {
+    throw new Error('Guru Assistance API token is not set');
+  }
+  if (!process.env.ORACLE_DID) {
+    throw new Error('Oracle DID is not set');
+  }
+  const payload: RequestPayload = {
+    message: question,
+    did: process.env.ORACLE_DID ?? '',
+    sessionId,
+  };
+
+  const response = await fetch(process.env.IXO_GURU_QUERY_ENDPOINT, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${process.env.GURU_ASSISTANCE_API_TOKEN}`,
+    },
+    body: JSON.stringify(payload),
+  });
+
+  if (!response.ok) {
+    throw new Error(`Error: ${response.statusText}`);
+  }
+
+  const data = (await response.json()) as ResponsePayload;
+  return jsonToYaml({
+    answer: data.message.content,
+    sessionId: data.sessionId,
+  });
+};
+
+export const askIXOGuruTool = tool(callGuruApi, {
+  name: 'ask_guru_ai',
+  description:
+    'Ask the IXO Guru AI a question - IXO guru has access to internal knowledge base of IXO organization this tool will return the answer and the session ID to use for chat history if you want to continue a conversation within the same session send the same session ID otherwise a new session ID',
+  schema: z.object({
+    question: z.string( 'The question to ask the IXO Guru AI',),
+    sessionId: z
+      .string( 'The session ID to use for chat history if you want to continue a conversation within the same session send the same session ID otherwise a new session ID',)
+      .uuid( 'Session ID must be a valid UUID',),
+  }),
+});

package/src/ai/tools/ask-ixo-guru/index.ts

@@ -0,0 +1 @@
+export * from './ask-ixo-guru.js';

package/src/ai/tools/browser-tool-caller.ts

@@ -0,0 +1,37 @@
+import { callFrontendTool } from './frontend-tool-caller.js';
+
+export interface BrowserToolResult {
+  result?: any;
+  error?: string;
+  success: boolean;
+}
+
+export interface IBrowserToolCallerParams {
+  sessionId: string;
+  toolCallId: string;
+  toolName: string;
+  args: any;
+  timeout?: number;
+}
+
+/**
+ * Call a tool that executes on the browser client and wait for the result
+ * @param params - The parameters for the browser tool call
+ * @returns Promise that resolves with the tool result
+ */
+export async function callBrowserTool({
+  sessionId,
+  toolCallId,
+  toolName,
+  args,
+  timeout = 15000,
+}: IBrowserToolCallerParams): Promise<any> {
+  return callFrontendTool({
+    sessionId,
+    toolId: toolCallId,
+    toolName,
+    args,
+    toolType: 'browser',
+    timeout,
+  });
+}

package/src/ai/tools/frontend-tool-caller.ts

@@ -0,0 +1,86 @@
+import { rootEventEmitter } from '@ixo/oracles-events';
+import { BrowserToolCallEvent } from '@ixo/oracles-events';
+import { ActionCallEvent } from '@ixo/oracles-events';
+
+export interface IFrontendToolCallerParams {
+  sessionId: string;
+  toolId: string;
+  toolName: string;
+  args: any;
+  toolType: 'browser' | 'agui';
+  timeout?: number;
+}
+
+/**
+ * Unified function to call frontend tools (browser tools or AG-UI actions)
+ * and wait for their result via WebSocket
+ * @param params - The parameters for the frontend tool call
+ * @returns Promise that resolves with the tool result
+ */
+export async function callFrontendTool({
+  sessionId,
+  toolId,
+  toolName,
+  args,
+  toolType,
+  timeout = 15000,
+}: IFrontendToolCallerParams): Promise<any> {
+  // Step 1: Emit appropriate event based on tool type
+  if (toolType === 'browser') {
+    new BrowserToolCallEvent({
+      sessionId,
+      requestId: toolId,
+      toolCallId: toolId,
+      toolName,
+      args,
+    }).emit();
+  } else {
+    new ActionCallEvent({
+      sessionId,
+      requestId: toolId,
+      toolCallId: toolId,
+      toolName,
+      args,
+      status: 'isRunning',
+    } as any).emit();
+  }
+
+  // Step 2: Wait for result via rootEventEmitter
+  const resultEventName =
+    toolType === 'browser' ? 'browser_tool_result' : 'action_call_result';
+
+  return await new Promise((resolve, reject) => {
+    let timeoutHandle: NodeJS.Timeout;
+
+    const resultHandler = (data: any) => {
+      const receivedId = data.toolCallId;
+      if (receivedId === toolId) {
+        clearTimeout(timeoutHandle);
+        rootEventEmitter.removeListener(resultEventName, resultHandler);
+
+        // Handle success
+        if (data.error) {
+          reject(new Error(data.error));
+        } else if (toolType === 'agui' && data.result?.success === false) {
+          // AG-UI specific error handling
+          reject(new Error(data.result.error || 'Action failed'));
+        } else {
+          resolve(data.result);
+        }
+      }
+    };
+
+    // Listen for the specific tool result
+    rootEventEmitter.on(resultEventName, resultHandler);
+
+    // Set timeout
+    timeoutHandle = setTimeout(() => {
+      rootEventEmitter.removeListener(resultEventName, resultHandler);
+      reject(
+        new Error(
+          `${toolType === 'agui' ? 'AG-UI action' : 'Browser tool'} timeout after ${timeout}ms: ${toolName}`,
+        ),
+      );
+    }, timeout);
+  });
+}

package/src/ai/tools/index.ts

@@ -0,0 +1,10 @@
+export * from './ask-ixo-guru/index.js';
+export * from './browser-tool-caller.js';
+export * from './parser-browser-tool.js';
+export * from './retriever-tool/index.js';
+export * from './scrape-web-page.js';
+export * from './web-search-tool.js';
+export * from './log-action-to-matrix.js';
+export * from './action-caller.js';
+export * from './frontend-tool-caller.js';
+export * from './parser-action-tool.js';

package/src/ai/tools/log-action-to-matrix.ts

@@ -0,0 +1,30 @@
+import { Logger } from '@ixo/logger';
+import { MatrixManager } from '@ixo/matrix';
+
+const matrixManager = MatrixManager.getInstance();
+
+
+interface IAction {
+  name: string;
+  args: Record<string, any>;
+  result: any;
+  error?: string;
+  success: boolean;
+}
+
+export async function logActionToMatrix(
+  action: IAction,
+  config: {
+    roomId: string;
+    threadId?: string;
+  },
+) {
+  if (!matrixManager.getInitializationStatus().isInitialized) {
+    await matrixManager.init();
+  }
+  matrixManager
+    .sendActionLog(config.roomId, action, config.threadId)
+    .catch((error) => {
+      Logger.error('Error sending action to matrix:', error);
+    });
+}

package/src/ai/tools/parser-action-tool.ts

@@ -0,0 +1,61 @@
+import { IRunnableConfigWithRequiredFields } from '@ixo/matrix';
+import { tool } from '@langchain/core/tools';
+import { callAgAction } from './action-caller.js';
+import { logActionToMatrix } from './log-action-to-matrix.js';
+
+interface IParseAgActionParams {
+  name: string;
+  description: string;
+  schema: Record<string, any>;
+}
+
+// Helper function to parse AG-UI action into LangChain tool
+export function parserActionTool(action: IParseAgActionParams) {
+  const { name, description, schema } = action;
+  return tool(
+    async (input, runnableConfig) => {
+      const { configurable } =
+        runnableConfig as IRunnableConfigWithRequiredFields;
+      const { thread_id: sessionId, requestId, configs } = configurable;
+
+      if (!sessionId) {
+        throw new Error('sessionId is required for AG-UI actions');
+      }
+
+      // Call the action and WAIT for result from frontend
+      const result = await callAgAction({
+        sessionId,
+        toolCallId: `ag_${requestId}`,
+        toolName: name,
+        args: input,
+        timeout: 5000, // 5 seconds
+      });
+
+      if (configs?.matrix.roomId) {
+        logActionToMatrix(
+          {
+            name: name,
+            args: input as Record<string, unknown>,
+            result,
+            success: true,
+          },
+          {
+            roomId: configs.matrix.roomId,
+            threadId: sessionId,
+          },
+        );
+      }
+
+      // Return the actual result from frontend
+      return JSON.stringify(result);
+    },
+    {
+      name: name,
+      description: description,
+      schema: schema,
+      metadata: {
+        actionTool: true,
+      },
+    },
+  );
+}

package/src/ai/tools/parser-browser-tool.ts

@@ -0,0 +1,55 @@
+import { IRunnableConfigWithRequiredFields } from '@ixo/matrix';
+import { tool } from '@langchain/core/tools';
+import { callBrowserTool } from './browser-tool-caller.js';
+import { logActionToMatrix } from './log-action-to-matrix.js';
+
+interface IParserBrowserToolParams {
+  description: string;
+  schema: Record<string, any>;
+  toolName: string;
+}
+
+export function parserBrowserTool(params: IParserBrowserToolParams) {
+  const { description, schema, toolName } = params;
+  return tool(
+    async (input, runnablesConfig) => {
+      const {
+        configurable: { thread_id: sessionId, requestId, configs },
+      } = runnablesConfig as IRunnableConfigWithRequiredFields;
+      if (!sessionId) {
+        throw new Error('sessionId is required');
+      }
+
+      const result = await callBrowserTool({
+        sessionId,
+        toolName,
+        args: input,
+        toolCallId: `tc-${requestId}`,
+      });
+
+      if (configs?.matrix.roomId) {
+        logActionToMatrix(
+          {
+            name: toolName,
+            args: input as Record<string, unknown>,
+            result,
+            success: true,
+          },
+          {
+            roomId: configs.matrix.roomId,
+            threadId: sessionId,
+          },
+        );
+      }
+      return result;
+    },
+    {
+      name: toolName,
+      description,
+      schema,
+      metadata: {
+        browserTool: true,
+      },
+    },
+  );
+}

package/src/ai/tools/retriever-tool/index.ts

@@ -0,0 +1 @@
+export * from './retriever-tool.js';