@mate-academy/llm-gateway 0.0.1-canary.1

package/src/LLMService.entity.ts

@@ -0,0 +1,71 @@
+import {
+  LLMCountTokensFunction,
+  LLMMessage,
+  LLMModel,
+  LLMProviders,
+  LLMRoles,
+} from './LLMService.typedefs';
+
+interface CombineMessagesOptions<Provider extends LLMProviders> {
+  modelContext?: LLMMessage[];
+  history?: LLMMessage[];
+  message: string;
+  model: LLMModel<Provider>;
+  countTokensFn?: LLMCountTokensFunction<Provider>;
+}
+
+export class LLMServiceEntity {
+  private static countTokensFallback(messages: string[]): Promise<number> {
+    const message = messages.join('');
+    const basicTokens = message.split(/[\s,.;!?(){}[\]<>%&]+/).filter(Boolean);
+    const subwordTokens = basicTokens.flatMap((token) => (
+      token.split(
+        /(?<=[a-z])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])|(?<=[a-zA-Z])(?=\d)|(?<=[\d])(?=[a-zA-Z])/,
+      )
+    ));
+
+    return Promise.resolve(subwordTokens.length);
+  }
+
+  static async combineMessagesWithLimit<Provider extends LLMProviders>({
+    modelContext = [],
+    history = [],
+    message,
+    model,
+    countTokensFn = this.countTokensFallback,
+  }: CombineMessagesOptions<Provider>): Promise<LLMMessage[]> {
+    const combinedMessages: LLMMessage[] = [...modelContext];
+
+    if (history[0]) {
+      const firstHistoryMessage = history[0];
+
+      combinedMessages.push(firstHistoryMessage);
+    }
+
+    const messagesToConsider = [
+      { role: LLMRoles.User, content: message },
+      ...history.slice(1).reverse(),
+    ];
+
+    const messages = combinedMessages.map(
+      (combinedMessage) => combinedMessage.content,
+    );
+
+    let tokenCount = await countTokensFn(messages, model);
+
+    for (const msg of messagesToConsider) {
+      const tempTokenCount = tokenCount + (
+        await countTokensFn([msg.content], model)
+      );
+
+      if (tempTokenCount <= model.limits.maxInputTokens) {
+        combinedMessages.push(msg);
+        tokenCount = tempTokenCount;
+      } else {
+        break;
+      }
+    }
+
+    return combinedMessages;
+  }
+}

package/src/LLMService.factory.ts

@@ -0,0 +1,57 @@
+import { Logger } from '@mate-academy/core';
+import {
+  LLMInstanceOptions,
+  LLMProviders,
+  LLMPurposes,
+  LLMServiceByPurpose,
+} from './LLMService.typedefs';
+import { LLM_SERVICE_FACTORIES } from './LLMService.constants';
+
+export class LLMServiceFactory {
+  private static getService<
+    Purpose extends LLMPurposes,
+    Provider extends LLMProviders,
+  >(
+    purpose: Purpose,
+    provider: Provider,
+    logger: Logger,
+    options: LLMInstanceOptions[Provider    ],
+  ): LLMServiceByPurpose<Provider>[Purpose] {
+    switch (provider) {
+      case LLMProviders.OpenAI:
+      case LLMProviders.GoogleGenerativeAI:
+        return LLM_SERVICE_FACTORIES[provider]
+          .createService(
+            purpose,
+            logger,
+            options,
+          );
+
+      default:
+        throw new Error(`Provider [${provider}] is not supported`);
+    }
+  }
+
+  static getCompletionService<Provider extends LLMProviders>(
+    provider: Provider,
+    logger: Logger,
+    options: LLMInstanceOptions[Provider],
+  ): LLMServiceByPurpose<Provider>[LLMPurposes.Completion] {
+    return this.getService(LLMPurposes.Completion, provider, logger, options);
+  }
+
+  static getAssistanceService<Provider extends LLMProviders>(
+    provider: Provider,
+    logger: Logger,
+    options: LLMInstanceOptions[Provider],
+  ): LLMServiceByPurpose<Provider>[LLMPurposes.Assistance] {
+    return this.getService(LLMPurposes.Assistance, provider, logger, options);
+  }
+
+  static resolveProviderOptions<Provider extends LLMProviders>(
+    provider: Provider,
+    options: Record<Provider, LLMInstanceOptions[Provider]>,
+  ): LLMInstanceOptions[Provider] {
+    return options[provider];
+  }
+}

package/src/LLMService.typedefs.ts

@@ -0,0 +1,174 @@
+import { Logger } from '@mate-academy/core';
+import { ClientOptions, OpenAI } from 'openai';
+import { GoogleGenAI } from '@google/genai';
+import { OpenAIModelNames } from './providers/OpenAI/OpenAI.typedefs';
+import { GoogleGenerativeAIModelNames } from './providers/GoogleGenerativeAI/GoogleGenerativeAI.typedefs';
+import { LLMCompletionService } from './services/LLMCompletionService.abstract';
+import { LLMAssistanceService } from './services/LLMAssistanceService.abstract';
+
+export enum LLMProviders {
+  OpenAI = 'OpenAI',
+  GoogleGenerativeAI = 'GoogleGenerativeAI',
+}
+
+export type LLMInstances = {
+  [LLMProviders.OpenAI]: OpenAI;
+  [LLMProviders.GoogleGenerativeAI]: GoogleGenAI;
+};
+
+export type LLMInstanceOptions = {
+  [LLMProviders.OpenAI]: ClientOptions;
+  [LLMProviders.GoogleGenerativeAI]: { apiKey: string };
+};
+
+export enum LLMPurposes {
+  Completion = 'completion',
+  Assistance = 'assistance',
+}
+
+export type LLMServiceByPurpose<Provider extends LLMProviders> = {
+  [LLMPurposes.Completion]: LLMCompletionService<Provider>;
+  [LLMPurposes.Assistance]: LLMAssistanceService<Provider>;
+};
+
+export type LLMServiceBuilder<
+  Provider extends LLMProviders,
+  Purpose extends LLMPurposes,
+> = (
+  logger: Logger,
+  options: LLMInstanceOptions[Provider],
+) => LLMServiceByPurpose<Provider>[Purpose];
+
+export interface LLMLimits {
+  maxInputTokens: number;
+  maxOutputTokens: number;
+}
+
+export interface LLMConfig {
+  temperature?: number;
+  top_p?: number | null;
+}
+
+export type LLMProviderAvailableModels<
+  Provider extends LLMProviders
+> = Record<
+  LLMModelName[Provider],
+  LLMModel<Provider>
+>;
+
+export type LLMProviderModelsByPurpose<
+  Purpose extends LLMPurposes,
+  Provider extends LLMProviders
+> = Record<
+  Purpose,
+  Partial<LLMProviderAvailableModels<Provider>>
+>;
+
+export type LLMModelName = {
+  [LLMProviders.OpenAI]: OpenAIModelNames;
+  [LLMProviders.GoogleGenerativeAI]: GoogleGenerativeAIModelNames;
+};
+
+export interface LLMModel<Provider extends LLMProviders> {
+  name: LLMModelName[Provider];
+  limits: LLMLimits;
+  config: LLMConfig;
+}
+
+export enum LLMRoles {
+  User = 'user',
+  Assistant = 'assistant',
+}
+
+export interface LLMMessage {
+  role: LLMRoles;
+  content: string;
+}
+
+export type LLMRequestError = Error;
+
+export type LLMRequestResult<Result> = Result | { error: LLMRequestError };
+
+export type LLMCompletionResult = LLMRequestResult<{ text: string }>;
+export interface LLMSendMessageOptions<Provider extends LLMProviders> {
+  message: LLMMessage;
+  model: LLMModel<Provider>;
+  history?: LLMMessage[];
+  instructions?: string;
+}
+
+export enum LLMUploadFileMimeTypes {
+  PNG = 'image/png',
+  PLAIN_TEXT = 'text/plain',
+}
+
+export interface LLMUploadFile {
+  mimeType: LLMUploadFileMimeTypes;
+  name: string;
+  path: string;
+}
+
+export interface LLMUploadedFile extends LLMUploadFile {
+  fileId: string;
+}
+
+export type LLMUploadFileResult = LLMRequestResult<LLMUploadedFile>;
+
+export interface LLMCreateFileStorageOptions<Provider extends LLMProviders> {
+  uploadedFiles: LLMUploadedFile[];
+  model: LLMModel<Provider>;
+  instructions?: string;
+}
+
+export interface LLMCreatedFileStorage {
+  storageId: string;
+}
+
+export type LLMCreateFileStorageResult = LLMRequestResult<
+  LLMCreatedFileStorage
+>;
+
+export interface LLMCreateAssistantOptions<Provider extends LLMProviders> {
+  model: LLMModel<Provider>;
+  instructions?: string;
+  storageIds?: string[];
+}
+
+export interface LLMCreatedAssistant {
+  assistantId: string;
+}
+
+export type LLMCreateAssistantResult = LLMRequestResult<LLMCreatedAssistant>;
+
+export interface LLMCreateChatOptions<Provider extends LLMProviders> {
+  model: LLMModel<Provider>;
+  instructions?: string;
+  history?: string[];
+  files?: LLMUploadedFile[];
+  storageId?: string;
+}
+
+export interface LLMCreatedChat {
+  chatId: string;
+}
+
+export type LLMCreateChatResult = LLMRequestResult<LLMCreatedChat>;
+
+export interface LLMAssistanceMessage extends LLMMessage {
+  attachment?: LLMUploadFileResult;
+  instructions?: string;
+}
+
+export interface LLMAssistanceOptions<Provider extends LLMProviders> {
+  model: LLMModel<Provider>;
+  message: LLMAssistanceMessage;
+  chatId: string;
+  assistantId: string;
+}
+
+export type LLMAssistanceResult = LLMRequestResult<{ text: string }>;
+
+export type LLMCountTokensFunction<Provider extends LLMProviders> = (
+  messages: string[],
+  model: LLMModel<Provider>,
+) => Promise<number>;

package/src/functional.utils.ts

@@ -0,0 +1,7 @@
+export const pick = <T, K extends keyof T>(obj: T, keys: K[]): Pick<T, K> => (
+  keys.reduce((acc, key) => {
+    Object.assign(acc, { [key]: obj[key] });
+
+    return acc;
+  }, {} as Pick<T, K>)
+);

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from './LLMService.constants';
+export * from './LLMService.entity';
+export * from './LLMService.factory';
+export * from './LLMService.typedefs';
+export * from './providers';
+export * from './services';

package/src/providers/GoogleGenerativeAI/GoogleGenerativeAI.constants.ts

@@ -0,0 +1,127 @@
+import {
+  LLMProviderAvailableModels,
+  LLMProviderModelsByPurpose,
+  LLMProviders,
+  LLMPurposes,
+  LLMServiceBuilder,
+} from '../../LLMService.typedefs';
+import { GoogleGenerativeAIModelNames } from './GoogleGenerativeAI.typedefs';
+import {
+  GoogleGenerativeAIAssistanceService,
+  GoogleGenerativeAICompletionService,
+} from '../../providers/GoogleGenerativeAI/services';
+import { pick } from '../../functional.utils';
+
+export const MIN_CACHE_CONTENT_LENGTH = 32_768;
+
+const GOOGLE_AI_AVAILABLE_MODELS: LLMProviderAvailableModels<
+  LLMProviders.GoogleGenerativeAI
+> = {
+  [GoogleGenerativeAIModelNames.GEMINI_1_5_FLASH]: {
+    name: GoogleGenerativeAIModelNames.GEMINI_1_5_FLASH,
+    limits: {
+      maxInputTokens: 1_048_576,
+      maxOutputTokens: 8_192,
+    },
+    config: {
+      temperature: 0.2,
+    },
+  },
+  [GoogleGenerativeAIModelNames.GEMINI_1_5_FLASH_STABLE]: {
+    name: GoogleGenerativeAIModelNames.GEMINI_1_5_FLASH_STABLE,
+    limits: {
+      maxInputTokens: 1_048_576,
+      maxOutputTokens: 8_192,
+    },
+    config: {
+      temperature: 0.2,
+    },
+  },
+  [GoogleGenerativeAIModelNames.GEMINI_1_5_PRO]: {
+    name: GoogleGenerativeAIModelNames.GEMINI_1_5_PRO,
+    limits: {
+      maxInputTokens: 2_097_152,
+      maxOutputTokens: 8_192,
+    },
+    config: {
+      temperature: 0.2,
+    },
+  },
+  [GoogleGenerativeAIModelNames.GEMINI_1_5_PRO_STABLE]: {
+    name: GoogleGenerativeAIModelNames.GEMINI_1_5_PRO_STABLE,
+    limits: {
+      maxInputTokens: 2_097_152,
+      maxOutputTokens: 8_192,
+    },
+    config: {
+      temperature: 0.2,
+    },
+  },
+  [GoogleGenerativeAIModelNames.GEMINI_2_0_FLASH]: {
+    name: GoogleGenerativeAIModelNames.GEMINI_2_0_FLASH,
+    limits: {
+      maxInputTokens: 1_048_576,
+      maxOutputTokens: 8_192,
+    },
+    config: {
+      temperature: 0.2,
+    },
+  },
+  [GoogleGenerativeAIModelNames.GEMINI_2_0_FLASH_STABLE]: {
+    name: GoogleGenerativeAIModelNames.GEMINI_2_0_FLASH_STABLE,
+    limits: {
+      maxInputTokens: 1_048_576,
+      maxOutputTokens: 8_192,
+    },
+    config: {
+      temperature: 0.2,
+    },
+  },
+  [GoogleGenerativeAIModelNames.GEMINI_2_5_PRO_PREVIEW]: {
+    name: GoogleGenerativeAIModelNames.GEMINI_2_5_PRO_PREVIEW,
+    limits: {
+      maxInputTokens: 1_048_576,
+      maxOutputTokens: 65_536,
+    },
+    config: {
+      temperature: 0.2,
+    },
+  },
+};
+
+export const GOOGLE_AI_MODELS: LLMProviderModelsByPurpose<
+  LLMPurposes,
+  LLMProviders.GoogleGenerativeAI
+> = {
+  [LLMPurposes.Completion]: pick(
+    GOOGLE_AI_AVAILABLE_MODELS,
+    [
+      GoogleGenerativeAIModelNames.GEMINI_1_5_FLASH,
+      GoogleGenerativeAIModelNames.GEMINI_1_5_PRO,
+      GoogleGenerativeAIModelNames.GEMINI_2_0_FLASH,
+      GoogleGenerativeAIModelNames.GEMINI_2_5_PRO_PREVIEW,
+    ],
+  ),
+  // Stable models are used for assistance as they support additional methods
+  [LLMPurposes.Assistance]: pick(
+    GOOGLE_AI_AVAILABLE_MODELS,
+    [
+      GoogleGenerativeAIModelNames.GEMINI_1_5_FLASH_STABLE,
+      GoogleGenerativeAIModelNames.GEMINI_1_5_PRO_STABLE,
+      GoogleGenerativeAIModelNames.GEMINI_2_0_FLASH_STABLE,
+    ],
+  ),
+};
+
+export const GOOGLE_AI_SERVICE_BUILDERS: {
+  [purpose in LLMPurposes]: (
+    LLMServiceBuilder<LLMProviders.GoogleGenerativeAI, purpose> | null
+  )
+} = {
+  [LLMPurposes.Completion]: (logger, options) => (
+    new GoogleGenerativeAICompletionService(logger, options)
+  ),
+  [LLMPurposes.Assistance]: (logger, options) => (
+    new GoogleGenerativeAIAssistanceService(logger, options)
+  ),
+};

package/src/providers/GoogleGenerativeAI/GoogleGenerativeAI.entity.ts

@@ -0,0 +1,67 @@
+import {
+  Part,
+  GoogleGenAI,
+  ContentListUnion,
+  GenerateContentParameters,
+} from '@google/genai';
+import {
+  LLMMessage,
+  LLMModel,
+  LLMProviders,
+  LLMUploadedFile,
+} from '../../LLMService.typedefs';
+
+export class GoogleGenerativeAIEntity {
+  static getContentParameters(
+    model: LLMModel<LLMProviders.GoogleGenerativeAI>,
+    messages: LLMMessage[],
+    instructions?: string,
+  ): GenerateContentParameters {
+    return {
+      model: model.name,
+      contents: messages.map((message) => ({
+        parts: [{
+          text: message.content,
+        }],
+        role: message.role,
+      })),
+      config: {
+        systemInstruction: instructions,
+        temperature: model.config.temperature,
+      },
+    };
+  }
+
+  static getFileDataParts(
+    uploadedFiles: LLMUploadedFile[],
+  ): Pick<Part, 'fileData'>[] {
+    return uploadedFiles.map((file) => ({
+      fileData: {
+        fileUri: file.path,
+        mimeType: file.mimeType,
+      },
+    }));
+  }
+
+  static getTextParts(
+    messages: string[],
+  ): Pick<Part, 'text'>[] {
+    return messages.map((message) => ({ text: message }));
+  }
+
+  static getCountTokensFn(
+    instance: GoogleGenAI,
+  ) {
+    return async (
+      contents: ContentListUnion,
+      model: LLMModel<LLMProviders.GoogleGenerativeAI>,
+    ): Promise<number> => {
+      const tokenCount = await instance.models.countTokens({
+        model: model.name,
+        contents,
+      });
+
+      return tokenCount.totalTokens ?? 0;
+    };
+  }
+}

package/src/providers/GoogleGenerativeAI/GoogleGenerativeAI.typedefs.ts

@@ -0,0 +1,14 @@
+export enum GoogleGenerativeAIModelNames {
+  GEMINI_1_5_FLASH = 'gemini-1.5-flash',
+  GEMINI_1_5_FLASH_STABLE = 'gemini-1.5-flash-001',
+  GEMINI_1_5_PRO = 'gemini-1.5-pro',
+  GEMINI_1_5_PRO_STABLE = 'gemini-1.5-pro-002',
+  GEMINI_2_0_FLASH = 'gemini-2.0-flash',
+  GEMINI_2_0_FLASH_STABLE = 'gemini-2.0-flash-001',
+  GEMINI_2_5_PRO_PREVIEW = 'gemini-2.5-pro-preview-03-25',
+}
+
+export enum GoogleGenerativeAIRoles {
+  User = 'user',
+  Model = 'model',
+}

package/src/providers/GoogleGenerativeAI/GoogleGenerativeAIService.factory.ts

@@ -0,0 +1,29 @@
+import { Logger } from '@mate-academy/core';
+import {
+  LLMInstanceOptions,
+  LLMProviders,
+  LLMPurposes,
+  LLMServiceByPurpose,
+} from '../../LLMService.typedefs';
+import { LLMServicePurposeFactory } from '../../services';
+import { GOOGLE_AI_SERVICE_BUILDERS } from './GoogleGenerativeAI.constants';
+
+export class GoogleGenerativeAIServiceFactory extends LLMServicePurposeFactory<
+  LLMProviders.GoogleGenerativeAI
+> {
+  createService<
+    Purpose extends LLMPurposes
+  >(
+    purpose: Purpose,
+    logger: Logger,
+    options: LLMInstanceOptions[LLMProviders.GoogleGenerativeAI],
+  ): LLMServiceByPurpose<LLMProviders.GoogleGenerativeAI>[Purpose] {
+    const serviceBuilder = GOOGLE_AI_SERVICE_BUILDERS[purpose];
+
+    if (!serviceBuilder) {
+      throw new Error(`Purpose [${purpose}] is not supported for [${LLMProviders.GoogleGenerativeAI}] service`);
+    }
+
+    return serviceBuilder(logger, options);
+  }
+}