@ixo/common 1.1.0

package/src/ai/models/openai.ts

@@ -0,0 +1,54 @@
+import 'dotenv/config';
+
+import {
+  ChatOpenAI,
+  OpenAIEmbeddings,
+  type ChatOpenAIFields,
+  type ChatOpenAIResponseFormat,
+} from '@langchain/openai';
+import OpenAI, { type ClientOptions } from 'openai';
+
+const getChatOpenAiModel = (params?: ChatOpenAIFields): ChatOpenAI =>
+  new ChatOpenAI({
+    temperature: 0.2,
+    model: 'gpt-4o-mini',
+    apiKey: process.env.OPENAI_API_KEY,
+    ...params,
+  });
+
+const getOpenAiClient = (params?: ClientOptions): OpenAI =>
+  new OpenAI({
+    apiKey: process.env.OPENAI_API_KEY,
+    ...params,
+  });
+
+const getOpenAiEmbeddings = (
+  params?: ConstructorParameters<typeof OpenAIEmbeddings>[0],
+): OpenAIEmbeddings =>
+  new OpenAIEmbeddings({
+    model: 'text-embedding-3-small',
+    apiKey: process.env.OPENAI_API_KEY,
+    ...params,
+  });
+
+export const getOpenRouterChatModel = (params?: ChatOpenAIFields) =>
+  getChatOpenAiModel({
+    temperature: 0.8,
+    apiKey: process.env.OPEN_ROUTER_API_KEY,
+    model: params?.model ?? 'qwen/qwen3-14b', //qwen3-30b-a3b
+    ...params,
+    configuration: {
+      baseURL: 'https://openrouter.ai/api/v1',
+      ...params?.configuration,
+      defaultHeaders: {
+        'HTTP-Referer': 'oracle-app.com',
+        'X-Title': process.env.ORACLE_NAME ?? 'Oracle App',
+      },
+    },
+    modelKwargs: {
+      require_parameters: true,
+      ...params?.modelKwargs,
+    },
+  });
+export { getChatOpenAiModel, getOpenAiClient, getOpenAiEmbeddings };
+export type { ChatOpenAIResponseFormat };

package/src/ai/nodes/create-fake-node.ts

@@ -0,0 +1 @@
+export const createFakeNode = <S extends object>(state: S): S => state;

package/src/ai/nodes/find-docs/find-docs.prompt.ts

@@ -0,0 +1,61 @@
+const SELF_QUERY_RAG_PROMPT = `You are an advanced AI agent specializing in self-query Retrieval-Augmented Generation (RAG). Your primary function is to analyze client questions, generate optimized search queries for a knowledge base, and iteratively refine these queries based on initial results. Follow these comprehensive guidelines:
+
+1. Initial Analysis:
+   - Thoroughly examine the client's question or task
+   - Identify key concepts, entities, relationships, and any implicit information needs
+   - Determine the scope, context, and potential complexities of the inquiry
+
+2. Query Generation - First Pass:
+   - Create an initial set of 3-5 focused, non-redundant search queries
+   - Ensure each query addresses a unique aspect of the client's input
+   - Incorporate key terms from the original question for keyword optimization
+   - Vary query formulations to cover different potential phrasings and synonyms
+
+3. Iterative Refinement:
+   - After receiving initial results, analyze their relevance and comprehensiveness
+   - Identify gaps in the retrieved information
+   - Generate additional queries to fill these gaps or explore new angles
+   - Refine existing queries based on the quality of results they produced
+
+4. Query Diversification:
+   - Ensure a mix of query types:
+     a. Broad conceptual queries for general information
+     b. Specific detail-oriented queries for precise facts
+     c. Comparative queries to explore relationships between concepts
+     d. Contextual queries to gather background information
+
+5. Handling Complex Questions:
+   - For multi-faceted questions, break them down into component parts
+   - Generate separate query sets for each component
+   - Create integrative queries that explore connections between components
+
+6. Adapting to Query Results:
+   - If initial queries yield insufficient information, broaden the scope
+   - If results are too general, create more specific, targeted queries
+   - Adjust the vocabulary and technical level based on the knowledge base content
+
+7. Temporal and Contextual Considerations:
+   - Include queries that account for potential time-sensitive information
+   - Generate queries that explore historical context if relevant
+   - Consider geographical or domain-specific variations in terminology
+
+8. Output Format and Explanation:
+   - Present a numbered list of refined search queries
+   - For each query, provide:
+     a. The query itself
+     b. A brief explanation of its purpose and how it relates to the client's question
+     c. Any notable findings or gaps identified from previous iterations
+
+9. Continuous Learning:
+   - Track the effectiveness of different query structures and patterns
+   - Adapt your query generation strategy based on successful retrievals
+   - Note any recurring challenges or limitations in the knowledge base
+
+10. Final Review and Optimization:
+    - Ensure the final set of queries comprehensively covers the client's needs
+    - Eliminate any remaining redundancies or overly similar queries
+    - Prioritize queries based on their potential to provide the most relevant and valuable information
+
+Remember: Your goal is to generate a dynamic, adaptive set of queries that evolves based on initial results and comprehensively addresses the client's information needs. Quality, relevance, and adaptability are key to successful self-query RAG implementation.`;
+
+export { SELF_QUERY_RAG_PROMPT };

package/src/ai/nodes/find-docs/index.ts

@@ -0,0 +1,2 @@
+export * from './find-docs.prompt.js';
+export * from './node.js';

package/src/ai/nodes/find-docs/node.ts

@@ -0,0 +1,83 @@
+import { type VectorDBDataStore } from '@ixo/data-store';
+import { Logger } from '@ixo/logger';
+import { type Document } from '@langchain/core/documents';
+import { type BaseMessage } from '@langchain/core/messages';
+import { ChatPromptTemplate } from '@langchain/core/prompts';
+import { type RunnableConfig } from '@langchain/core/runnables';
+import 'dotenv/config';
+import z from 'zod';
+import {
+  getChatOpenAiModel,
+  retrieverToolFactory,
+  SELF_QUERY_RAG_PROMPT,
+} from '../../index.js';
+
+interface IFindDocsNodeRequiredState {
+  question: string;
+  docs: Document[];
+  messages?: BaseMessage[];
+  config?: {
+    isInternal: boolean;
+  };
+  status?: 'completed' | 'inProgress';
+}
+
+/**
+ * factory function that returns a Node that takes a state and config and returns a promise that resolves to a partial state.
+ * @param store - The vector database data store.
+ * @returns The Node that takes a state and config and returns a promise that resolves to a partial state.
+ */
+export const findDocsNode =
+  (store: VectorDBDataStore) =>
+  async (
+    state: IFindDocsNodeRequiredState,
+    config?: RunnableConfig,
+  ): Promise<Partial<IFindDocsNodeRequiredState>> => {
+    try {
+      const model = getChatOpenAiModel();
+      const modelWithTools = model.withStructuredOutput(
+        z.object({
+          questions: z.array(z.string('Generated Queries')),
+        }),
+      );
+
+      const chain = ChatPromptTemplate.fromMessages([
+        ['system', SELF_QUERY_RAG_PROMPT],
+        [
+          'user',
+          state.messages
+            ? `this is the last three messages from the user's conversation ${state.messages
+                .map((message) => message.content)
+                .slice(-3)
+                .join(',')}`
+            : state.question,
+        ],
+      ]).pipe(modelWithTools);
+
+      const response = await chain.invoke({}, config);
+      const retrieval = retrieverToolFactory({
+        filters: state.config?.isInternal
+          ? undefined
+          : { approved: true, visibility: 'public' },
+        store,
+      });
+      const docs = await Promise.all(
+        response.questions.map(
+          (question) =>
+            retrieval.invoke({ query: question }) as Promise<Document[]>,
+        ),
+      );
+
+      return {
+        docs: docs.flat().map((value) => ({
+          metadata: value.metadata,
+          pageContent: value.pageContent.toString(),
+          id: value.id,
+        })),
+        status: undefined,
+      };
+    } catch (error) {
+      Logger.error('Error finding docs', error);
+      throw error;
+    }
+  };

package/src/ai/nodes/generic-chat/generic-chat.node.ts

@@ -0,0 +1,58 @@
+import { Logger } from '@ixo/logger';
+import { BaseMessage } from '@langchain/core/messages';
+import {
+  ChatPromptTemplate,
+  MessagesPlaceholder,
+} from '@langchain/core/prompts';
+import { RunnableConfig } from '@langchain/core/runnables';
+import { StructuredTool, Tool } from '@langchain/core/tools';
+import { getChatOpenAiModel } from 'src/ai/models/openai.js';
+import { GENERIC_CHAT_PROMPT, InputVariables } from './generic-chat.prompt.js';
+
+type StateWithMessages<S extends object> = {
+  messages: BaseMessage[];
+} & S;
+
+export const createGenericChatNode = (
+  inputVariables: InputVariables,
+  tools: (Tool | StructuredTool)[],
+  llm = getChatOpenAiModel(),
+) => {
+  return async <S extends object>(
+    state: StateWithMessages<S>,
+    config?: RunnableConfig,
+  ) => {
+    Logger.debug('Generic chat node called', {
+      state,
+      config,
+    });
+
+    let systemPrompt = '';
+    try {
+      systemPrompt = await GENERIC_CHAT_PROMPT.format(inputVariables);
+    } catch (error) {
+      Logger.error('Error formatting system prompt', error);
+      throw error;
+    }
+
+    const chain = ChatPromptTemplate.fromMessages([
+      ['system', systemPrompt],
+      new MessagesPlaceholder('msgs'),
+    ]).pipe(llm.bindTools(tools));
+
+    const result = await chain.invoke(
+      {
+        msgs: state.messages,
+      },
+      config,
+    );
+
+    Logger.debug('Generic chat node result', {
+      result,
+    });
+
+    return {
+      messages: [result],
+    };
+  };
+};

package/src/ai/nodes/generic-chat/generic-chat.prompt.ts

@@ -0,0 +1,66 @@
+import { PromptTemplate } from '@langchain/core/prompts';
+
+export type InputVariables = {
+  APP_NAME: string;
+  APP_PURPOSE: string;
+  APP_MAIN_FEATURES: string;
+  APP_TARGET_USERS: string;
+  APP_UNIQUE_SELLING_POINTS: string;
+};
+
+export const GENERIC_CHAT_PROMPT = new PromptTemplate<InputVariables, never>({
+  template: `# IXO AI Assistant: Expert Guide and Conversational Partner
+
+## Your Identity
+You are an AI assistant for the IXO Organization. Your primary role is to engage users in friendly, natural conversations, offering casual and informative chitchat. You can discuss various topics to keep conversations engaging and approachable.
+
+Additionally, you have detailed knowledge about the app hosting you. Below is essential information about the hosting app that you can refer to when responding to user inquiries about it:
+
+## App Information
+### App Details
+- **App Name**: {{APP_NAME}}
+- **App Purpose**: {{APP_PURPOSE}}
+- **Main Features**: {{APP_MAIN_FEATURES}}
+- **Target Users**: {{APP_TARGET_USERS}}
+- **Unique Selling Points**: {{APP_UNIQUE_SELLING_POINTS}}
+
+
+## Your Capabilities
+- Provide detailed information about the IXO app and ecosystem
+- Engage in natural, friendly conversation on various topics
+- Explain complex concepts in accessible language
+- Guide users through app features when they express interest
+- Offer relevant suggestions based on user inquiries
+
+## Communication Style
+- **Tone**: Professional yet warm, conversational, and engaging
+- **Language**: Clear, concise, and jargon-free unless requested
+- **Personality**: Helpful, patient, and slightly enthusiastic
+- **Responses**: Informative but concise, typically 2-4 sentences
+
+## Interaction Guidelines
+- Begin responses with direct answers to user questions
+- When discussing app features, provide concrete examples of how they benefit users
+- For complex topics, use analogies or step-by-step explanations
+- If uncertain about a specific app detail, acknowledge this transparently
+- Balance informative content with conversational elements
+- Proactively suggest relevant app features when appropriate
+- Personalize responses based on user's demonstrated knowledge level
+
+## What to Avoid
+- Making claims about app capabilities not listed in your knowledge base
+- Using overly technical language with non-technical users
+- Providing lengthy, overwhelming responses
+- Making definitive statements about future IXO developments unless explicitly mentioned
+- Sharing sensitive information about IXO's internal operations
+
+Remember that your primary goal is to create a positive, informative experience that builds trust in the IXO platform while making users feel valued and understood.`,
+  inputVariables: [
+    'APP_NAME',
+    'APP_PURPOSE',
+    'APP_MAIN_FEATURES',
+    'APP_TARGET_USERS',
+    'APP_UNIQUE_SELLING_POINTS',
+  ],
+  templateFormat: 'mustache',
+});

package/src/ai/nodes/generic-chat/index.ts

@@ -0,0 +1 @@
+export * from './generic-chat.node.js';

package/src/ai/nodes/index.ts

@@ -0,0 +1,3 @@
+export * from './create-fake-node.js';
+export * from './find-docs/index.js';
+export * from './generic-chat/index.js';

package/src/ai/semantic-router-factory/create-semantic-router.test.ts

@@ -0,0 +1,98 @@
+import { createSemanticRouter } from './create-semantic-router.js';
+
+const parse = jest.fn();
+const create = jest.fn();
+jest.mock('openai', () => ({
+  OpenAI: jest.fn().mockImplementation(() => {
+    function fn(): unknown {
+      return {};
+    }
+
+    fn.beta = {
+      chat: {
+        completions: { parse },
+      },
+    };
+
+    fn.chat = {
+      completions: { create },
+    };
+    return fn;
+  }),
+}));
+
+describe('createSemanticRouter', () => {
+  it('should create a semantic router with valid routes', () => {
+    // const router = createSemanticRouter(
+    //   {
+    //     generateBlog: 'if the intent is blog',
+    //     generateSocialMediaPost: 'if the intent is post',
+    //   },
+    //   ['intent'],
+    // );
+    expect(() =>
+      createSemanticRouter(
+        {
+          generateBlog: 'if the intent is blog',
+          generateSocialMediaPost: 'if the intent is post',
+        },
+        ['intent'],
+      ),
+    ).not.toThrow();
+  });
+
+  it('should fail to create a semantic router with invalid routes', () => {
+    expect(() => createSemanticRouter({}, ['intent'])).toThrow();
+  });
+
+  it('should fail to get route with invalid state', async () => {
+    const router = createSemanticRouter(
+      {
+        generateBlog: 'if the intent is blog',
+        generateSocialMediaPost: 'if the intent is post',
+      },
+      ['intent'],
+    );
+    await expect(
+      router({
+        foo: 'boo',
+      }),
+    ).rejects.toThrow();
+  });
+
+  it('should get route with valid state', async () => {
+    const router = createSemanticRouter(
+      {
+        generateBlog: 'if the intent is blog',
+        generateSocialMediaPost: 'if the intent is post',
+      },
+      ['intent'],
+      'gpt-4o-mini',
+      false,
+    );
+
+    parse.mockResolvedValue({
+      choices: [
+        {
+          message: {
+            parsed: {
+              nextRoute: 'generateBlog',
+            },
+            content: 'generateBlog',
+            role: 'assistant',
+            refusal: null,
+            tool_calls: [],
+          },
+          finish_reason: 'stop',
+          index: 0,
+          logprobs: null,
+        },
+      ],
+    });
+
+    const route = await router({
+      intent: 'blog',
+    });
+    expect(route).toBe('generateBlog');
+  });
+});

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

@@ -0,0 +1,136 @@
+import { Logger } from '@ixo/logger';
+import { PromptTemplate } from '@langchain/core/prompts';
+import { LangfuseConfig, observeOpenAI } from 'langfuse';
+import { OpenAI } from 'openai';
+import { zodResponseFormat } from 'openai/helpers/zod';
+import  z from 'zod';
+import { type EnsureKeys } from '../types.js';
+import { jsonToYaml } from '../utils/index.js';
+import { semanticRouterPrompt } from './semantic-router-prompt.js';
+import { validateRoutes } from './validate-routes.js';
+import { APIPromise } from 'openai/index.js';
+import { ParsedChatCompletion } from 'openai/resources/chat/completions.mjs';
+
+/**
+ * Creates a semantic router that resolves the path based on the given routes and basedOn value.
+ *  routes The routes that will be used to resolve the path
+ *  basedOn Array of keys from the state that will be used to resolve the path
+ * @returns A function that will be used to resolve the path
+ *
+ * @example
+ * ```typescript
+ * const routes = {
+ *   generateBlog: 'if the intent is blog',
+ *   generateSocialMediaPost: 'if the intent is post',
+ * }
+ *
+ * const intentRouter = createSemanticRouter(routes, ['intent']);
+ * ```
+ */
+export const createSemanticRouter = <
+  K extends string[],
+  R extends Record<string, string> = Record<string, string>,
+>(
+  routes: R,
+  basedOn: K,
+  model:
+    | 'gpt-4o-mini'
+    | 'gpt-4o'
+    | 'gpt-4.1-nano'
+    | 'gpt-4.1-mini' = 'gpt-4.1-mini',
+  isComplex = false,
+): ((
+  state: EnsureKeys<Record<string, unknown>, K>,
+  traceConfig?: LangfuseConfig,
+) => Promise<keyof R>) => {
+  const keys = validateRoutes(routes, basedOn);
+  const schema = z.object({
+    nextRoute: z.enum(keys as [string, ...string[]], 'The routes that will be used to resolve the path'),
+  });
+  return async <T extends Record<string, unknown>>(
+    state: EnsureKeys<T, K>,
+    traceConfig?: LangfuseConfig,
+  ): Promise<keyof R> => {
+    const selectedValues = {} as Record<string, string | object>;
+    for (const key of basedOn) {
+      const stateValue = state[key];
+      if (!stateValue) {
+        throw new Error(`The state must have a value for the key ${key}`);
+      }
+
+      selectedValues[key] = stateValue;
+    }
+    if (Object.values(selectedValues).length === 0) {
+      throw new Error(
+        `The state must have a value for the key ${basedOn.toString()}`,
+      );
+    }
+
+    // find the route that matches the state
+    const prompt = PromptTemplate.fromTemplate(semanticRouterPrompt);
+
+    const client = observeOpenAI(new OpenAI(), traceConfig);
+    const promptWithState = await prompt.format({
+      routes: jsonToYaml(routes),
+      state: jsonToYaml(selectedValues),
+    });
+
+    const getRoute = async (
+      messages: (
+        | { role: 'system'; content: string }
+        | { role: 'user'; content: string }
+      )[],
+    ): Promise<
+      APIPromise<
+        ParsedChatCompletion<{
+          nextRoute: string;
+        }>
+      >
+    > => {
+      if (model === 'gpt-4.1-nano' && isComplex) {
+        const { choices } = await client.chat.completions.create({
+          messages,
+          model,
+        });
+
+        const route = choices[0]?.message?.content?.toString();
+        Logger.debug('🚀 ~ route:', route);
+        return client.chat.completions.parse({
+          model,
+          messages,
+          response_format: zodResponseFormat(schema, 'routesResponse'),
+        });
+      }
+      return client.chat.completions.parse({
+        model,
+        messages,
+        response_format: zodResponseFormat(schema, 'routesResponse'),
+      });
+    };
+
+    const completion = await getRoute([
+      { role: 'system', content: promptWithState },
+      {
+        role: 'user',
+        content:
+          'Think and analyze the routes and messages then select the next route',
+      },
+    ]);
+    const message = completion.choices[0]?.message;
+
+    if (message?.parsed) {
+      const nextRoute = message.parsed.nextRoute;
+      Logger.debug(
+        `🚀 ~ nextRoute: ${message.parsed.nextRoute.toString()}`,
+        message.parsed,
+      );
+
+      return nextRoute as keyof R;
+    }
+
+    Logger.error('Error parsing the response from the semantic router');
+    throw new Error('Error parsing the response from the semantic router');
+  };
+};
+
+export { zodResponseFormat, type ParsedChatCompletion };

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

@@ -0,0 +1,3 @@
+export * from './create-semantic-router.js';
+export * from './semantic-router-prompt.js';
+export * from './validate-routes.js';