@mate-academy/llm-gateway 1.0.3 → 1.0.4

package/README.md

@@ -173,6 +173,383 @@ Supports both completion and assistance APIs. For more information, see [OpenAI
 
 Supports completion API through Google's Generative AI models. For more information, see [Google Generative AI documentation](https://ai.google.dev/docs).
 
+## Developer Guide: Adding a New Provider
+
+To add support for a new LLM provider, follow these steps:
+
+### 1. Create Provider Directory Structure
+
+Create a new directory in `src/providers` with your provider name, following the established pattern:
+
+```
+src/providers/YourProvider/
+├── index.ts                    # Entry point for provider exports
+├── YourProvider.constants.ts   # Provider-specific constants
+├── YourProvider.entity.ts      # Provider-specific entity
+├── YourProvider.typedefs.ts    # TypeScript definitions
+├── YourProviderService.factory.ts # Factory for your provider's services
+└── services/                   # Provider service implementations
+    ├── index.ts
+    ├── YourProviderCompletionService.ts
+    └── YourProviderAssistanceService.ts
+```
+
+### 2. Add Provider to LLM Providers Enum
+
+Update the LLM providers enum in `src/LLMService.typedefs.ts`:
+
+```typescript
+export enum LLMProviders {
+  OpenAI = 'openai',
+  GoogleGenerativeAI = 'google',
+  YourProvider = 'your-provider-id',
+}
+```
+
+### 3. Define Provider-Specific Types
+
+Create type definitions in `src/providers/YourProvider/YourProvider.typedefs.ts`:
+
+```typescript
+// Define model names as an enum for type safety
+export enum YourProviderModelNames {
+  MODEL_ONE = 'model-one',
+  MODEL_TWO = 'model-extended',
+}
+
+// Define message roles if applicable
+export enum YourProviderRoles {
+  User = 'user',
+  Assistant = 'assistant',
+  System = 'system',
+}
+
+// Add any other provider-specific enums or interfaces
+```
+
+Then ensure your provider is properly integrated in the main type system by updating the necessary type mappings in `src/LLMService.typedefs.ts`:
+
+```typescript
+// Add import for your provider's types
+import { type YourProviderModelNames } from './providers/YourProvider/YourProvider.typedefs';
+
+// Update the LLMProviders enum
+export enum LLMProviders {
+  OpenAI = 'OpenAI',
+  GoogleGenerativeAI = 'GoogleGenerativeAI',
+  YourProvider = 'YourProvider',
+}
+
+// Update LLMInstances type mapping
+export type LLMInstances = {
+  // ...existing code...
+  [LLMProviders.YourProvider]: YourProviderClient; // Your provider's client type
+};
+
+// Update LLMInstanceOptions type mapping
+export type LLMInstanceOptions = {
+  // ...existing code...
+  [LLMProviders.YourProvider]: {
+    apiKey: string;
+    // Add other provider-specific options
+  };
+};
+
+// Update LLMModelName type mapping
+export type LLMModelName = {
+  // ...existing code...
+  [LLMProviders.YourProvider]: YourProviderModelNames;
+};
+```
+
+### 4. Implement Provider Constants
+
+Define constants in `src/providers/YourProvider/YourProvider.constants.ts`:
+
+```typescript
+import {
+  type LLMProviderAvailableModels,
+  type LLMProviderModelsByPurpose,
+  type LLMProviders,
+  LLMPurposes,
+  type LLMServiceBuilder,
+} from '../../LLMService.typedefs';
+import { YourProviderModelNames } from './YourProvider.typedefs';
+import {
+  YourProviderAssistanceService,
+  YourProviderCompletionService,
+} from './services';
+import { pick } from '../../functional.utils';
+
+// Define available models with their capabilities and configurations
+const YOUR_PROVIDER_AVAILABLE_MODELS: LLMProviderAvailableModels<
+  LLMProviders.YourProvider
+> = {
+  [YourProviderModelNames.MODEL_ONE]: {
+    name: YourProviderModelNames.MODEL_ONE,
+    limits: {
+      maxInputTokens: 8_000,
+      maxOutputTokens: 2_000,
+    },
+    config: {
+      temperature: 0.2,
+    },
+  },
+  [YourProviderModelNames.MODEL_TWO]: {
+    name: YourProviderModelNames.MODEL_TWO,
+    limits: {
+      maxInputTokens: 16_000,
+      maxOutputTokens: 4_000,
+    },
+    config: {
+      temperature: 0.2,
+    },
+  },
+};
+
+// Specify which models are available for each purpose
+export const YOUR_PROVIDER_MODELS: LLMProviderModelsByPurpose<
+  LLMPurposes,
+  LLMProviders.YourProvider
+> = {
+  [LLMPurposes.Completion]: pick(
+    YOUR_PROVIDER_AVAILABLE_MODELS,
+    [
+      YourProviderModelNames.MODEL_ONE,
+      YourProviderModelNames.MODEL_TWO,
+    ],
+  ),
+  [LLMPurposes.Assistance]: pick(
+    YOUR_PROVIDER_AVAILABLE_MODELS,
+    [
+      YourProviderModelNames.MODEL_TWO, // Only MODEL_TWO supports assistance
+    ],
+  ),
+};
+
+// Define service builders for each LLM purpose
+export const YOUR_PROVIDER_SERVICE_BUILDERS: {
+  [purpose in LLMPurposes]: (
+    LLMServiceBuilder<LLMProviders.YourProvider, purpose> | null
+  )
+} = {
+  [LLMPurposes.Completion]: (logger, options) => (
+    new YourProviderCompletionService(logger, options)
+  ),
+  [LLMPurposes.Assistance]: (logger, options) => (
+    new YourProviderAssistanceService(logger, options)
+  ),
+};
+```
+
+### 5. Implement Provider Entity (if needed)
+
+Create the entity class in `src/providers/YourProvider/YourProvider.entity.ts`:
+
+```typescript
+export class YourProviderEntity {
+  // Implement provider-specific methods
+}
+```
+
+### 6. Implement Service Classes
+
+Create service implementations in the `services` directory:
+
+**CompletionService (src/providers/YourProvider/services/YourProviderCompletionService.ts)**:
+
+```typescript
+import { Logger } from '../../../LLMService.typedefs';
+import { LLMCompletionService } from '../../../services/LLMCompletionService.abstract';
+import { CompletionParams, CompletionResult, LLMProviders } from '../../../LLMService.typedefs';
+import { YourProviderEntity } from '../YourProvider.entity';
+
+export class YourProviderCompletionService extends LLMCompletionService<LLMProviders.YourProvider> {
+  constructor(
+    logger: Logger,
+    private readonly providerEntity: YourProviderEntity,
+  ) {
+    super(logger);
+  }
+
+  async complete(params: CompletionParams): Promise<CompletionResult> {
+    this.logger.info('Starting completion with YourProvider', { params });
+
+    try {
+      // Implement provider-specific completion logic
+
+      return {
+        text: 'Completed text',
+        // Include other required fields
+      };
+    } catch (error) {
+      this.logger.error('Error in YourProvider completion', { error });
+      throw error;
+    }
+  }
+}
+```
+
+**AssistanceService (if applicable)**:
+
+```typescript
+import { Logger } from '../../../LLMService.typedefs';
+import { LLMAssistanceService } from '../../../services/LLMAssistanceService.abstract';
+import {
+  AssistantParams,
+  ThreadParams,
+  MessageParams,
+  LLMProviders
+} from '../../../LLMService.typedefs';
+import { YourProviderEntity } from '../YourProvider.entity';
+
+export class YourProviderAssistanceService extends LLMAssistanceService<LLMProviders.YourProvider> {
+  constructor(
+    logger: Logger,
+    private readonly providerEntity: YourProviderEntity,
+  ) {
+    super(logger);
+  }
+
+  // Implement required assistance methods
+}
+```
+
+### 7. Create Service Factory
+
+First, define service builders in `src/providers/YourProvider/YourProvider.constants.ts`:
+
+```typescript
+import {
+  LLMPurposes,
+  type LLMServiceBuilder,
+} from '../../LLMService.typedefs';
+import {
+  YourProviderAssistanceService,
+  YourProviderCompletionService,
+} from './services';
+
+export const YOUR_PROVIDER_SERVICE_BUILDERS: {
+  [purpose in LLMPurposes]: (
+    LLMServiceBuilder<LLMProviders.YourProvider, purpose> | null
+  )
+} = {
+  [LLMPurposes.Completion]: (logger, options) => (
+    new YourProviderCompletionService(logger, options)
+  ),
+  [LLMPurposes.Assistance]: (logger, options) => (
+    new YourProviderAssistanceService(logger, options)
+  ),
+};
+```
+
+Then, implement the service factory in `src/providers/YourProvider/YourProviderService.factory.ts`:
+
+```typescript
+import { type Logger } from '@mate-academy/core';
+import {
+  type LLMInstanceOptions,
+  LLMProviders,
+  type LLMPurposes,
+  type LLMServiceByPurpose,
+} from '../../LLMService.typedefs';
+import { LLMServicePurposeFactory } from '../../services';
+import { YOUR_PROVIDER_SERVICE_BUILDERS } from './YourProvider.constants';
+
+export class YourProviderServiceFactory extends LLMServicePurposeFactory<
+  LLMProviders.YourProvider
+> {
+  createService<
+    Purpose extends LLMPurposes
+  >(
+    purpose: Purpose,
+    logger: Logger,
+    options: LLMInstanceOptions[LLMProviders.YourProvider],
+  ): LLMServiceByPurpose<LLMProviders.YourProvider>[Purpose] {
+    const serviceBuilder = YOUR_PROVIDER_SERVICE_BUILDERS[purpose];
+
+    if (!serviceBuilder) {
+      throw new Error(`Purpose [${purpose}] is not supported for [${LLMProviders.YourProvider}] service`);
+    }
+
+    return serviceBuilder(logger, options);
+  }
+}
+```
+
+### 8. Update Entry Point Files
+
+Update the provider's `index.ts`:
+
+```typescript
+export * from './YourProvider.constants';
+export * from './YourProvider.entity';
+export * from './YourProvider.typedefs';
+export * from './YourProviderService.factory';
+export * from './services';
+```
+
+Update the main providers `index.ts` at `src/providers/index.ts`:
+
+```typescript
+// ... other providers
+export * from './YourProvider';
+```
+
+### 9. Update LLM Service Factory
+
+Modify `src/LLMService.factory.ts` to include your new provider:
+
+```typescript
+import {
+  LLMProviders,
+  Logger,
+  YourProviderOptions,
+} from './LLMService.typedefs';
+import { YourProviderServiceFactory } from './providers/YourProvider';
+import { YourProviderOptions } from './providers/YourProvider/YourProvider.typedefs';
+
+export class LLMServiceFactory {
+  static resolveProviderOptions<T extends LLMProviders>(
+    provider: T,
+    optionsMap: {
+      // ... other providers
+      [LLMProviders.YourProvider]?: YourProviderOptions;
+    },
+  ) {
+    return optionsMap[provider];
+  }
+
+  static getCompletionService<T extends LLMProviders>(
+    provider: T,
+    logger: Logger,
+    options: any,
+  ) {
+    switch (provider) {
+      // ... other providers
+      case LLMProviders.YourProvider:
+        return YourProviderServiceFactory.createCompletionService(logger, options);
+      default:
+        throw new Error(`Unsupported provider: ${provider}`);
+    }
+  }
+
+  static getAssistanceService<T extends LLMProviders>(
+    provider: T,
+    logger: Logger,
+    options: any,
+  ) {
+    switch (provider) {
+      // ... other providers
+      case LLMProviders.YourProvider:
+        return YourProviderServiceFactory.createAssistanceService(logger, options);
+      default:
+        throw new Error(`Unsupported provider: ${provider}`);
+    }
+  }
+}
+```
+
 ## License
 
 [MIT](LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mate-academy/llm-gateway",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "A gateway package for LLM services.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",