@mate-academy/llm-gateway 1.3.0 → 1.3.2

package/README.md

@@ -16,9 +16,12 @@ npm install @mate-academy/llm-gateway
 
 - Support for multiple LLM providers (OpenAI, Google Generative AI)
 - Standardized completion service interface
-- Standardized assistance service interface
+- Standardized assistance service interface with file handling
+- Speech-to-text transcription capabilities
+- Text-to-speech generation capabilities
 - Factory pattern for easy provider selection
 - Consistent logging across all providers
+- Comprehensive testing suite with integration tests
 
 ## Usage
 
@@ -29,7 +32,12 @@ import {
   LLMProviders,
   LLMServiceFactory,
   LLMCompletionService,
-  LLMAssistanceService
+  LLMAssistanceService,
+  LLMSpeechToTextService,
+  LLMTextToSpeechService,
+  LLMRoles,
+  LLMMessageContentType,
+  LLMUploadFileMimeTypes,
 } from '@mate-academy/llm-gateway';
 
 // Define provider options
@@ -60,6 +68,20 @@ const assistanceService = LLMServiceFactory.getAssistanceService(
   logger, // your logger instance
   llmProviderOptions,
 );
+
+// Get speech-to-text service
+const speechToTextService = LLMServiceFactory.getSpeechToTextService(
+  LLMProviders.OpenAI,
+  logger, // your logger instance
+  llmProviderOptions,
+);
+
+// Get text-to-speech service
+const textToSpeechService = LLMServiceFactory.getTextToSpeechService(
+  LLMProviders.OpenAI,
+  logger, // your logger instance
+  llmProviderOptions,
+);
 ```
 
 ### Real-world Example
@@ -72,11 +94,15 @@ import {
   LLMServiceFactory,
   LLMCompletionService,
   LLMAssistanceService,
+  LLMSpeechToTextService,
+  LLMTextToSpeechService,
 } from '@mate-academy/llm-gateway';
 
 class MyUseCase {
   private llmCompletionService: LLMCompletionService<LLMProviders>;
   private llmAssistanceService: LLMAssistanceService<LLMProviders>;
+  private llmSpeechToTextService: LLMSpeechToTextService<LLMProviders>;
+  private llmTextToSpeechService: LLMTextToSpeechService<LLMProviders>;
 
   constructor(logger, config) {
     const llmProviderOptions = LLMServiceFactory.resolveProviderOptions(
@@ -104,20 +130,135 @@ class MyUseCase {
       logger,
       llmProviderOptions,
     );
+
+    this.llmSpeechToTextService = LLMServiceFactory.getSpeechToTextService(
+      config.llmProvider,
+      logger,
+      llmProviderOptions,
+    );
+
+    this.llmTextToSpeechService = LLMServiceFactory.getTextToSpeechService(
+      config.llmProvider,
+      logger,
+      llmProviderOptions,
+    );
   }
 
   async processRequest(prompt) {
     // Use completion service
-    const completion = await this.llmCompletionService.complete({
-      prompt,
-      maxTokens: 500,
+    const completion = await this.llmCompletionService.sendMessage({
+      message: {
+        role: LLMRoles.User,
+        content: { type: LLMMessageContentType.TEXT, text: prompt }
+      },
+      model: this.getPreferredModel(),
     });
 
     return completion;
   }
+
+  async transcribeAudio(audioPath) {
+    // Use speech-to-text service
+    const transcription = await this.llmSpeechToTextService.transcribe({
+      pathToAudio: audioPath,
+      model: this.getPreferredModel(),
+    });
+
+    return transcription;
+  }
+
+  async generateSpeech(text) {
+    // Use text-to-speech service
+    const speech = await this.llmTextToSpeechService.createSpeech({
+      text: text,
+      model: this.getPreferredModel(),
+      speechOptions: {
+        voice: 'alloy', // OpenAI voice option
+        response_format: 'mp3',
+      },
+    });
+
+    return speech;
+  }
+
+  private getPreferredModel() {
+    // Get the appropriate model from the service's available models
+    const models = Object.values(this.llmCompletionService.models);
+    return models[0]; // Use the first available model
+  }
 }
 ```
 
+### Usage Examples
+
+#### Basic Text Completion
+
+```typescript
+const result = await completionService.sendMessage({
+  message: {
+    role: LLMRoles.User,
+    content: { type: LLMMessageContentType.TEXT, text: 'Hello, how are you?' }
+  },
+  model: preferredModel,
+});
+
+console.log(result.text); // AI response
+```
+
+#### File-based Assistance
+
+```typescript
+// Upload files for context
+const uploadedFile = await assistanceService.uploadFile({
+  name: 'document.txt',
+  path: '/path/to/document.txt',
+  mimeType: LLMUploadFileMimeTypes.PLAIN_TEXT,
+});
+
+// Create file storage
+const storage = await assistanceService.createFileStorage({
+  uploadedFiles: [uploadedFile],
+  model: preferredModel,
+  instructions: 'Help me analyze this document',
+});
+
+// Create chat with file context
+const chat = await assistanceService.createChat({
+  storageId: storage.storageId,
+  model: preferredModel,
+  history: [],
+  files: [uploadedFile],
+  instructions: 'Answer questions about the uploaded document',
+});
+```
+
+#### Speech-to-Text Transcription
+
+```typescript
+const transcription = await speechToTextService.transcribe({
+  pathToAudio: '/path/to/audio.mp3',
+  model: preferredModel,
+});
+
+console.log(transcription.text); // Transcribed text
+```
+
+#### Text-to-Speech Generation
+
+```typescript
+const speech = await textToSpeechService.createSpeech({
+  text: 'Hello, this will be converted to speech',
+  model: preferredModel,
+  speechOptions: {
+    voice: 'alloy', // OpenAI voice option
+    response_format: 'mp3',
+  },
+});
+
+// Save audio buffer to file
+fs.writeFileSync('output.mp3', speech.audio);
+```
+
 ## API Reference
 
 ### LLMProviders
@@ -126,12 +267,25 @@ Enum of supported LLM providers:
 
 ```typescript
 enum LLMProviders {
-  OpenAI = 'openai',
-  GoogleGenerativeAI = 'google',
+  OpenAI = 'OpenAI',
+  GoogleGenerativeAI = 'GoogleGenerativeAI',
   // other providers may be added in the future
 }
 ```
 
+### LLMPurposes
+
+Enum of supported service purposes:
+
+```typescript
+enum LLMPurposes {
+  Completion = 'completion',
+  Assistance = 'assistance',
+  SpeechToText = 'speech_to_text',
+  TextToSpeech = 'text_to_speech',
+}
+```
+
 ### LLMServiceFactory
 
 Factory class for creating LLM service instances.
@@ -141,6 +295,8 @@ Factory class for creating LLM service instances.
 - `resolveProviderOptions(provider, optionsMap)`: Resolves the options for the specified provider
 - `getCompletionService(provider, logger, options)`: Creates a completion service instance
 - `getAssistanceService(provider, logger, options)`: Creates an assistance service instance
+- `getSpeechToTextService(provider, logger, options)`: Creates a speech-to-text service instance
+- `getTextToSpeechService(provider, logger, options)`: Creates a text-to-speech service instance
 
 ### LLMCompletionService
 
@@ -148,30 +304,204 @@ Interface for text completion services.
 
 #### Methods
 
-- `complete(params)`: Generate a completion for the given prompt
+- `sendMessage(options)`: Send a message to the LLM and get a completion response
 
 ### LLMAssistanceService
 
-Interface for chat/assistance services.
+Interface for chat/assistance services with file handling capabilities.
+
+#### Methods
+
+- `uploadFile(file)`: Upload a file to the LLM service
+  - Parameters: `LLMUploadFile` with `name`, `path`, and `mimeType`
+  - Returns: `Promise<LLMUploadFileResult>`
+- `deleteFile(fileId)`: Delete a file from the LLM service
+- `createFileStorage(options)`: Create a file storage for organizing files
+  - Parameters: `LLMCreateFileStorageOptions` with `uploadedFiles`, `model`, and optional `instructions`
+  - Returns: `Promise<LLMCreateFileStorageResult>`
+- `deleteFileStorage(fileStorageId)`: Delete a file storage
+- `createAssistant(options)`: Create an AI assistant with specific instructions
+  - Parameters: `LLMCreateAssistantOptions` with `model`, optional `instructions` and `storageIds`
+  - Returns: `Promise<LLMCreateAssistantResult>`
+- `deleteAssistant(assistantId)`: Delete an assistant
+- `createChat(options)`: Create a new chat/conversation
+  - Parameters: `LLMCreateChatOptions` with `model`, optional `instructions`, `history`, `files`, and `storageId`
+  - Returns: `Promise<LLMCreateChatResult>`
+- `deleteChat(chatId)`: Delete a chat
+- `assistInChat(options)`: Send a message in an existing chat and get an assistant response
+  - Parameters: `LLMAssistanceOptions` with `model`, `message`, `chatId`, and `assistantId`
+  - Returns: `Promise<LLMAssistanceResult>`
+
+### LLMSpeechToTextService
+
+Interface for converting speech audio to text.
 
 #### Methods
 
-- `createAssistant(params)`: Create a new assistant
-- `getAssistant(assistantId)`: Retrieve an existing assistant
-- `createThread(params)`: Create a new thread
-- `addMessage(threadId, params)`: Add a message to a thread
-- `runAssistant(params)`: Run an assistant on a thread
-- `getRunResult(params)`: Get the result of an assistant run
+- `transcribe(options)`: Convert audio file to text transcription
+
+### LLMTextToSpeechService
+
+Interface for converting text to speech audio.
+
+#### Methods
+
+- `createSpeech(options)`: Convert text to speech audio file
 
 ## Supported Providers
 
 ### OpenAI
 
-Supports both completion and assistance APIs. For more information, see [OpenAI API documentation](https://platform.openai.com/docs/api-reference).
+Supports all service types: completion, assistance, speech-to-text, and text-to-speech APIs. For more information, see [OpenAI API documentation](https://platform.openai.com/docs/api-reference).
+
+**Available Models:**
+- GPT-4 models for completion and assistance
+- Whisper models for speech-to-text transcription
+- TTS models for text-to-speech generation
 
 ### Google Generative AI
 
-Supports completion API through Google's Generative AI models. For more information, see [Google Generative AI documentation](https://ai.google.dev/docs).
+Supports completion and assistance APIs through Google's Generative AI models. For more information, see [Google Generative AI documentation](https://ai.google.dev/docs).
+
+**Available Models:**
+- Gemini models for completion, assistance and speech-to-text
+
+## Testing
+
+The LLM Gateway includes a comprehensive testing suite with both unit and integration tests.
+
+### Test Structure
+
+The package includes:
+- **Integration tests** for all service types (`src/tests/integration/`)
+- **Test helpers** for common testing utilities (`src/tests/helpers.ts`)
+- **Mock implementations** for testing environments
+- **Audio test files** for speech-to-text testing
+
+### Running Tests
+
+```bash
+# Run all tests with logging
+npm test
+
+# Run tests silently (without logs)
+npm run test:silent
+
+# Run with specific environment variables
+ENABLE_LOGGING=true npm test
+```
+
+### Test Configuration
+
+Integration tests require API keys for the respective providers:
+
+```bash
+# Required environment variables for OpenAI tests
+OPENAI_SECRET_API_KEY=your_openai_api_key
+OPENAI_ORG_ID=your_organization_id  # optional
+OPENAI_BASE_URL=https://api.openai.com/v1  # optional
+
+# Required environment variables for Google AI tests
+GOOGLE_GENERATIVE_AI_API_KEY=your_google_ai_api_key
+```
+
+### Test Coverage
+
+The integration tests cover:
+
+1. **Completion Service Tests:**
+   - Basic message sending and responses
+   - Message history handling
+   - Error handling for invalid inputs
+   - Model-specific functionality
+
+2. **Assistance Service Tests:**
+   - File upload and storage creation
+   - Chat creation and management
+   - Assistant interactions
+   - File-based conversations
+
+3. **Speech-to-Text Service Tests:**
+   - Audio file transcription
+   - Multiple audio format support
+   - Error handling for invalid files
+   - Model-specific transcription quality
+
+4. **Text-to-Speech Service Tests:**
+   - Text-to-audio conversion
+   - Voice selection options
+   - Audio format configuration
+   - Error handling
+
+### Test Helpers
+
+The package provides several test utilities:
+
+```typescript
+import {
+  mockLogger,
+  resolveTestConfig,
+  hasText,
+  hasError,
+} from '@mate-academy/llm-gateway/tests/helpers';
+
+// Mock logger for testing
+const logger = mockLogger;
+
+// Get test configuration for specific service purpose
+const testConfig = resolveTestConfig(LLMPurposes.Completion);
+
+// Type guards for test assertions
+if (hasText(result)) {
+  expect(result.text).toContain('expected content');
+}
+
+if (hasError(result)) {
+  expect(result.error).toBeDefined();
+}
+```
+
+### Writing Custom Tests
+
+Example of writing a custom integration test:
+
+```typescript
+import {
+  describe,
+  it,
+  expect,
+  beforeAll,
+} from '@jest/globals';
+import {
+  LLMServiceFactory,
+  LLMProviders,
+  LLMPurposes,
+} from '@mate-academy/llm-gateway';
+import { mockLogger, resolveTestConfig } from '@mate-academy/llm-gateway/tests/helpers';
+
+describe('Custom LLM Integration Test', () => {
+  const testConfig = resolveTestConfig(LLMPurposes.Completion);
+
+  Object.values(testConfig).forEach(({ provider, clientOptions, requireCredentials }) => {
+    describe(`${provider} Provider`, () => {
+      let service;
+
+      beforeAll(() => {
+        requireCredentials();
+        service = LLMServiceFactory.getCompletionService(
+          provider,
+          mockLogger,
+          clientOptions
+        );
+      });
+
+      it('should process custom request', async () => {
+        // Your custom test logic here
+      });
+    });
+  });
+});
+```
 
 ## Developer Guide: Adding a New Provider
 
@@ -325,6 +655,18 @@ export const YOUR_PROVIDER_MODELS: LLMProviderModelsByPurpose<
       YourProviderModelNames.MODEL_TWO, // Only MODEL_TWO supports assistance
     ],
   ),
+  [LLMPurposes.SpeechToText]: pick(
+    YOUR_PROVIDER_AVAILABLE_MODELS,
+    [
+      YourProviderModelNames.MODEL_ONE, // Speech-to-text capable model
+    ],
+  ),
+  [LLMPurposes.TextToSpeech]: pick(
+    YOUR_PROVIDER_AVAILABLE_MODELS,
+    [
+      YourProviderModelNames.MODEL_ONE, // Text-to-speech capable model
+    ],
+  ),
 };
 
 // Define service builders for each LLM purpose
@@ -339,6 +681,12 @@ export const YOUR_PROVIDER_SERVICE_BUILDERS: {
   [LLMPurposes.Assistance]: (logger, options) => (
     new YourProviderAssistanceService(logger, options)
   ),
+  [LLMPurposes.SpeechToText]: (logger, options) => (
+    new YourProviderSpeechToTextService(logger, options)
+  ),
+  [LLMPurposes.TextToSpeech]: (logger, options) => (
+    new YourProviderTextToSpeechService(logger, options)
+  ),
 };
 ```
 
@@ -396,9 +744,8 @@ export class YourProviderCompletionService extends LLMCompletionService<LLMProvi
 import { Logger } from '../../../LLMService.typedefs';
 import { LLMAssistanceService } from '../../../services/LLMAssistanceService.abstract';
 import {
-  AssistantParams,
-  ThreadParams,
-  MessageParams,
+  LLMAssistanceOptions,
+  LLMAssistanceResult,
   LLMProviders
 } from '../../../LLMService.typedefs';
 import { YourProviderEntity } from '../YourProvider.entity';
@@ -412,6 +759,94 @@ export class YourProviderAssistanceService extends LLMAssistanceService<LLMProvi
   }
 
   // Implement required assistance methods
+  async uploadFile(file: LLMUploadFile): Promise<LLMUploadFileResult> {
+    // Implementation for file upload
+  }
+
+  async createFileStorage(options: LLMCreateFileStorageOptions): Promise<LLMCreateFileStorageResult> {
+    // Implementation for file storage creation
+  }
+
+  async createChat(options: LLMCreateChatOptions): Promise<LLMCreateChatResult> {
+    // Implementation for chat creation
+  }
+
+  async assistInChat(options: LLMAssistanceOptions): Promise<LLMAssistanceResult> {
+    // Implementation for chat assistance
+  }
+}
+```
+
+**SpeechToTextService (if applicable)**:
+
+```typescript
+import { Logger } from '../../../LLMService.typedefs';
+import { LLMSpeechToTextService } from '../../../services/LLMSpeechToTextService.abstract';
+import {
+  LLMTranscribeOptions,
+  LLMTranscribeResult,
+  LLMProviders
+} from '../../../LLMService.typedefs';
+import { YourProviderEntity } from '../YourProvider.entity';
+
+export class YourProviderSpeechToTextService extends LLMSpeechToTextService<LLMProviders.YourProvider> {
+  constructor(
+    logger: Logger,
+    private readonly providerEntity: YourProviderEntity,
+  ) {
+    super(logger);
+  }
+
+  async transcribe(options: LLMTranscribeOptions<typeof this.provider>): Promise<LLMTranscribeResult> {
+    this.logger.info('Starting transcription with YourProvider', { options });
+
+    try {
+      // Implement provider-specific transcription logic
+      return {
+        text: 'Transcribed text from audio',
+      };
+    } catch (error) {
+      this.logger.error('Error in YourProvider transcription', { error });
+      throw error;
+    }
+  }
+}
+```
+
+**TextToSpeechService (if applicable)**:
+
+```typescript
+import { Logger } from '../../../LLMService.typedefs';
+import { LLMTextToSpeechService } from '../../../services/LLMTextToSpeechService.abstract';
+import {
+  LLMCreateSpeechOptions,
+  LLMCreateSpeechResult,
+  LLMProviders
+} from '../../../LLMService.typedefs';
+import { YourProviderEntity } from '../YourProvider.entity';
+
+export class YourProviderTextToSpeechService extends LLMTextToSpeechService<LLMProviders.YourProvider> {
+  constructor(
+    logger: Logger,
+    private readonly providerEntity: YourProviderEntity,
+  ) {
+    super(logger);
+  }
+
+  async createSpeech(options: LLMCreateSpeechOptions<typeof this.provider>): Promise<LLMCreateSpeechResult> {
+    this.logger.info('Starting speech creation with YourProvider', { options });
+
+    try {
+      // Implement provider-specific speech creation logic
+      return {
+        audio: Buffer.from('audio data'),
+        mimeType: 'audio/mp3',
+      };
+    } catch (error) {
+      this.logger.error('Error in YourProvider speech creation', { error });
+      throw error;
+    }
+  }
 }
 ```
 
@@ -528,7 +963,11 @@ export class LLMServiceFactory {
     switch (provider) {
       // ... other providers
       case LLMProviders.YourProvider:
-        return YourProviderServiceFactory.createCompletionService(logger, options);
+        return YourProviderServiceFactory.createService(
+          LLMPurposes.Completion,
+          logger,
+          options
+        );
       default:
         throw new Error(`Unsupported provider: ${provider}`);
     }
@@ -542,7 +981,47 @@ export class LLMServiceFactory {
     switch (provider) {
       // ... other providers
       case LLMProviders.YourProvider:
-        return YourProviderServiceFactory.createAssistanceService(logger, options);
+        return YourProviderServiceFactory.createService(
+          LLMPurposes.Assistance,
+          logger,
+          options
+        );
+      default:
+        throw new Error(`Unsupported provider: ${provider}`);
+    }
+  }
+
+  static getSpeechToTextService<T extends LLMProviders>(
+    provider: T,
+    logger: Logger,
+    options: any,
+  ) {
+    switch (provider) {
+      // ... other providers
+      case LLMProviders.YourProvider:
+        return YourProviderServiceFactory.createService(
+          LLMPurposes.SpeechToText,
+          logger,
+          options
+        );
+      default:
+        throw new Error(`Unsupported provider: ${provider}`);
+    }
+  }
+
+  static getTextToSpeechService<T extends LLMProviders>(
+    provider: T,
+    logger: Logger,
+    options: any,
+  ) {
+    switch (provider) {
+      // ... other providers
+      case LLMProviders.YourProvider:
+        return YourProviderServiceFactory.createService(
+          LLMPurposes.TextToSpeech,
+          logger,
+          options
+        );
       default:
         throw new Error(`Unsupported provider: ${provider}`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mate-academy/llm-gateway",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "description": "A gateway package for LLM services.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -65,7 +65,7 @@
     "axios": "^1.9.0",
     "js-tiktoken": "^1.0.20",
     "mime-types": "^3.0.1",
-    "openai": "^5.1.1",
+    "openai": "^5.2.0",
     "uuid": "^11.1.0"
   }
 }