@mate-academy/llm-gateway 2.5.3 → 3.0.1

package/README.md

@@ -16,6 +16,7 @@ npm install @mate-academy/llm-gateway
 
 - Support for multiple LLM providers (OpenAI, Google Generative AI)
 - **Structured Output**: Type-safe JSON responses with schema validation
+- **Extensible Schema Architecture**: Driver pattern with provider-specific adapters
 - Standardized completion service interface
 - Standardized assistance service interface with file handling
 - Speech-to-text transcription capabilities
@@ -30,6 +31,23 @@ npm install @mate-academy/llm-gateway
 
 ## Usage
 
+### Logger Interface
+
+The package accepts an optional logger that implements the `LLMLogger` interface. Most logging libraries are compatible (`@mate-academy/logger`, winston, pino, etc.). If no logger is provided, no logging will occur.
+
+```typescript
+// Using @mate-academy/logger (recommended)
+import { logger } from '@mate-academy/logger';
+
+// Or simple console logger
+const logger = {
+  info: (msg, meta) => console.log(msg, meta),
+  error: (msg, meta) => console.error(msg, meta),
+  warn: (msg, meta) => console.warn(msg, meta),
+  child: (context) => logger,
+};
+```
+
 ### Basic Setup
 
 ```typescript
@@ -47,6 +65,7 @@ import {
   LLMModel,
   LLMSchema,
   createPromptTemplate,
+  LLMLogger,
 } from '@mate-academy/llm-gateway';
 
 // Define provider options
@@ -65,32 +84,32 @@ const llmProviderOptions = LLMServiceFactory.resolveProviderOptions(
 );
 
 // Get completion service
-const completionService = LLMServiceFactory.getCompletionService(
-  LLMProviders.OpenAI,
-  logger, // your logger instance
-  llmProviderOptions,
-);
+const completionService = LLMServiceFactory.getCompletionService({
+  provider: LLMProviders.OpenAI,
+  options: llmProviderOptions,
+  logger, // optional - omit for no logging
+});
 
 // Get assistance service
-const assistanceService = LLMServiceFactory.getAssistanceService(
-  LLMProviders.OpenAI,
-  logger, // your logger instance
-  llmProviderOptions,
-);
+const assistanceService = LLMServiceFactory.getAssistanceService({
+  provider: LLMProviders.OpenAI,
+  options: llmProviderOptions,
+  logger, // optional - omit for no logging
+});
 
 // Get speech-to-text service
-const speechToTextService = LLMServiceFactory.getSpeechToTextService(
-  LLMProviders.OpenAI,
-  logger, // your logger instance
-  llmProviderOptions,
-);
+const speechToTextService = LLMServiceFactory.getSpeechToTextService({
+  provider: LLMProviders.OpenAI,
+  options: llmProviderOptions,
+  logger, // optional - omit for no logging
+});
 
 // Get text-to-speech service
-const textToSpeechService = LLMServiceFactory.getTextToSpeechService(
-  LLMProviders.OpenAI,
-  logger, // your logger instance
-  llmProviderOptions,
-);
+const textToSpeechService = LLMServiceFactory.getTextToSpeechService({
+  provider: LLMProviders.OpenAI,
+  options: llmProviderOptions,
+  logger, // optional - omit for no logging
+});
 ```
 
 ### Real-world Example
@@ -128,29 +147,29 @@ class MyUseCase {
       },
     );
 
-    this.llmCompletionService = LLMServiceFactory.getCompletionService(
-      config.llmProvider,
+    this.llmCompletionService = LLMServiceFactory.getCompletionService({
+      provider: config.llmProvider,
+      options: llmProviderOptions,
       logger,
-      llmProviderOptions,
-    );
+    });
 
-    this.llmAssistanceService = LLMServiceFactory.getAssistanceService(
-      config.llmProvider,
+    this.llmAssistanceService = LLMServiceFactory.getAssistanceService({
+      provider: config.llmProvider,
+      options: llmProviderOptions,
       logger,
-      llmProviderOptions,
-    );
+    });
 
-    this.llmSpeechToTextService = LLMServiceFactory.getSpeechToTextService(
-      config.llmProvider,
+    this.llmSpeechToTextService = LLMServiceFactory.getSpeechToTextService({
+      provider: config.llmProvider,
+      options: llmProviderOptions,
       logger,
-      llmProviderOptions,
-    );
+    });
 
-    this.llmTextToSpeechService = LLMServiceFactory.getTextToSpeechService(
-      config.llmProvider,
+    this.llmTextToSpeechService = LLMServiceFactory.getTextToSpeechService({
+      provider: config.llmProvider,
+      options: llmProviderOptions,
       logger,
-      llmProviderOptions,
-    );
+    });
   }
 
   async processRequest(prompt) {
@@ -257,7 +276,7 @@ const result = await completionService.sendMessage({
 // Type-safe access to structured data
 if (result.data) {
   console.log(result.data.name);        // string
-  console.log(result.data.age);         // number  
+  console.log(result.data.age);         // number
   console.log(result.data.email);       // string
   console.log(result.data.isActive);    // boolean
 }
@@ -380,6 +399,65 @@ if (result.data) {
 - Use `.min()` and `.max()` instead of `.positive()`, `.negative()`
 - Test schemas with both providers if cross-compatibility is important
 
+#### Schema Architecture
+
+The package uses a **driver pattern** for schema conversion, automatically adapting schemas to each provider's specific format while maintaining a unified API.
+
+Schema adapters are automatically registered when providers are imported, so no manual configuration is needed. For detailed architecture information and extending with new providers, see the [Developer Guide](#developer-guide).
+
+### Model Configuration
+
+Each model comes with default configuration values that can be customized for your specific needs.
+
+#### Accessing and Customizing Models
+
+```typescript
+// Get available models from the service
+const models = completionService.models;
+
+// Get a specific model
+const model = models[OpenAIModelNames.GPT_4_OMNI];
+
+// Customize model configuration
+const customModel = {
+  ...model,
+  config: {
+    ...model.config,
+    temperature: 0.8,  // Override temperature (0-2, controls randomness)
+    top_p: 0.9,       // Override top_p (nucleus sampling)
+  }
+};
+
+// Use customized model in requests
+const result = await completionService.sendMessage({
+  message: {
+    role: LLMRoles.User,
+    content: [{ type: LLMMessageContentType.TEXT, text: 'Hello!' }]
+  },
+  model: customModel,
+});
+```
+
+#### Model-Specific Configuration
+
+**GPT-5 Models** have special configuration options:
+
+```typescript
+const gpt5Model = models[OpenAIModelNames.GPT_5];
+
+const customGPT5Model = {
+  ...gpt5Model,
+  config: {
+    ...gpt5Model.config,
+    temperature: 1,  // Note: GPT-5 only supports temperature=1
+    reasoning_effort: 'high',  // 'minimal' | 'medium' | 'high'
+    verbosity: 'low',  // 'low' | 'medium' | 'high'
+  }
+};
+```
+
+**Note:** GPT-5 models require `temperature: 1` and cannot be changed. GPT-5-MINI only supports the default temperature.
+
 #### File-based Assistance
 
 ```typescript
@@ -390,11 +468,11 @@ const uploadedFile = await assistanceService.uploadFile({
   mimeType: LLMUploadFileMimeTypes.PLAIN_TEXT,
 });
 
-// Create file storage
+// Create file storage with instructions
 const storage = await assistanceService.createFileStorage({
   uploadedFiles: [uploadedFile],
   model: preferredModel,
-  instructions: 'Help me analyze this document',
+  instructions: 'Help me analyze this document',  // Optional context for the storage
 });
 
 // Create chat with file context
@@ -403,7 +481,7 @@ const chat = await assistanceService.createChat({
   model: preferredModel,
   history: [],
   files: [uploadedFile],
-  instructions: 'Answer questions about the uploaded document',
+  instructions: 'Answer questions about the uploaded document',  // Initial assistant instructions
 });
 ```
 
@@ -414,7 +492,7 @@ const transcription = await speechToTextService.transcribe({
   pathToAudio: '/path/to/audio.mp3',
   mimeType: LLMUploadFileMimeTypes.AUDIO_MP3, // Optional, but recommended
   model: preferredModel,
-  instructions: 'Transcribe the audio file', // Optional instructions
+  instructions: 'Transcribe the audio file', // Optional: custom prompt for transcription context
 });
 
 console.log(transcription.text); // Transcribed text
@@ -563,6 +641,12 @@ Interface for text completion services.
 #### Methods
 
 - `sendMessage(options)`: Send a message to the LLM and get a completion response
+  - `message`: The message to send
+  - `model`: The LLM model to use (with optional config overrides)
+  - `history`: Optional conversation history
+  - `instructions`: Optional system instructions to guide the model's behavior
+  - `schema`: Optional schema for structured output
+  - `abortSignal`: Optional abort signal for cancellation
 
 ### LLMAssistanceService
 
@@ -573,10 +657,22 @@ Interface for chat/assistance services with file handling capabilities.
 - `uploadFile(fileOptions)`: Upload a file to the LLM service
 - `deleteFile(fileId)`: Delete a file from the LLM service
 - `createFileStorage(options)`: Create a file storage for organizing files
+  - `uploadedFiles`: Array of previously uploaded files
+  - `model`: The LLM model to use
+  - `instructions`: Optional instructions for how to use the stored files
 - `deleteFileStorage(fileStorageId)`: Delete a file storage
 - `createAssistant(options)`: Create an AI assistant with specific instructions
+  - `model`: The LLM model to use
+  - `instructions`: Optional instructions defining the assistant's behavior
+  - `storageIds`: Optional array of storage IDs to give the assistant access to
+  - `name`: Optional name for the assistant
 - `deleteAssistant(assistantId)`: Delete an assistant
 - `createChat(options)`: Create a new chat/conversation
+  - `model`: The LLM model to use
+  - `instructions`: Optional initial instructions for the conversation
+  - `history`: Optional conversation history
+  - `files`: Optional array of uploaded files
+  - `storageId`: Optional storage ID to use
 - `deleteChat(chatId)`: Delete a chat
 - `assistInChat(options)`: Send a message in an existing chat and get an assistant response
 - `countTokens(messages, model)`: Count tokens in messages for context management
@@ -588,6 +684,10 @@ Interface for converting speech audio to text.
 #### Methods
 
 - `transcribe(options)`: Convert audio file to text transcription
+  - `pathToAudio`: Path to the audio file
+  - `mimeType`: Optional MIME type of the audio file
+  - `model`: The LLM model to use
+  - `instructions`: Optional custom transcription prompt or context
 
 ### LLMTextToSpeechService
 
@@ -665,6 +765,7 @@ const fullLesson = coursePrompt({
 const basicLesson = coursePrompt({
   topicTitle: 'React Hooks',
   hasPrerequisites: false,
+  prerequisites: '',
   includeExercises: false,
   difficultyLevel: 'beginner'
 });
@@ -733,7 +834,7 @@ const reviewInstruction = codeReviewPrompt({
   outputFormat: 'structured',
   includeCode: true,
   codeSnippet: 'function example() { /* code here */ }',
-  provideExamples: false
+  provideExamples: false,
 });
 ```
 
@@ -887,15 +988,33 @@ Creates a prompt template function from a template string.
 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
-- TTS models for text-to-speech generation
+
+| Model | Purpose | Max Input | Max Output | Notes |
+|-------|---------|-----------|------------|-------|
+| gpt-4o | Completion, Assistance | 128K | 16K | General purpose, balanced |
+| gpt-4o-mini | Completion, Assistance | 128K | 16K | Faster, cost-effective |
+| gpt-4.1 | Completion, Assistance | 1M+ | 32K | Extended context window |
+| gpt-5 | Completion, Assistance | 400K | 128K | Advanced reasoning, requires temperature=1 |
+| gpt-5-mini | Completion, Assistance | 400K | 128K | Smaller GPT-5 variant |
+| gpt-4o-transcribe | Speech-to-Text | 16K | 2K | Optimized for transcription |
+| gpt-4o-mini-transcribe | Speech-to-Text | 16K | 2K | Cost-effective transcription |
+| tts-1 | Text-to-Speech | - | - | Standard TTS model |
+| gpt-4o-mini-tts | Text-to-Speech | - | - | Alternative TTS model |
 
 ### Google Generative AI
 
-Supports completion and assistance APIs through Google's Generative AI models. For more information, see [Google Generative AI documentation](https://ai.google.dev/docs).
+Supports completion, assistance, speech-to-text, and text-to-speech 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
+
+| Model | Purpose | Max Input | Max Output | Notes |
+|-------|---------|-----------|------------|-------|
+| gemini-2.5-flash | Completion, Assistance, Speech-to-Text | 1M+ | 65K | Fast, cost-effective, supports caching for long context |
+| gemini-2.5-pro | Completion, Assistance, Speech-to-Text | 1M+ | 65K | Advanced reasoning, supports caching for long context |
+| gemini-2.5-flash-preview-tts | Text-to-Speech | 8K | 16K | Preview TTS model with flash performance |
+| gemini-2.5-pro-preview-tts | Text-to-Speech | 8K | 16K | Preview TTS model with pro capabilities |
+
+**Note:** Google Generative AI models support context caching for content longer than 32,768 tokens, which can significantly reduce costs for repeated queries on the same large context.
 
 ## Testing
 
@@ -968,33 +1087,84 @@ The integration tests cover:
 
 The package provides several test utilities:
 
-```typescript
-import {
-  mockLogger,
-  resolveTestConfig,
-  hasText,
-  hasError,
-} from '@mate-academy/llm-gateway/tests/helpers';
+#### resolveTestConfig Function
 
-// Mock logger for testing
-const logger = mockLogger;
+The `resolveTestConfig` function creates standardized test configurations for all supported providers based on the service purpose:
+
+```typescript
+import { resolveTestConfig } from '@mate-academy/llm-gateway/tests/helpers';
 
-// Get test configuration for specific service purpose
+// Get test config for completion services
 const testConfig = resolveTestConfig(LLMPurposes.Completion);
 
+// testConfig contains configuration for all providers:
+// {
+//   [LLMProviders.OpenAI]: {
+//     provider: LLMProviders.OpenAI,
+//     availableModels: {...}, // Models available for completion
+//     clientOptions: { apiKey: process.env.OPENAI_SECRET_API_KEY, ... },
+//     requireCredentials: () => void, // Throws if credentials missing
+//     isEnabled: true
+//   },
+//   [LLMProviders.GoogleGenerativeAI]: {
+//     provider: LLMProviders.GoogleGenerativeAI,
+//     availableModels: {...}, // Models available for completion
+//     clientOptions: { apiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY },
+//     requireCredentials: () => void, // Throws if credentials missing
+//     isEnabled: true
+//   }
+// }
+
+// Use in tests to iterate over all providers
+Object.values(testConfig).forEach((config) => {
+  const { provider, clientOptions, availableModels, requireCredentials } = config;
+
+  describe(`${provider} Provider`, () => {
+    beforeAll(() => {
+      requireCredentials(); // Ensures API keys are present
+    });
+
+    it('should create service', () => {
+      const service = LLMServiceFactory.getCompletionService({
+        provider,
+        options: clientOptions,
+        logger: mockLogger, // Optional
+      });
+      expect(service).toBeDefined();
+    });
+  });
+});
+```
+
+#### Mock Logger
+
+```typescript
+// Note: Test helpers are for internal use only
+// When testing your integration, create your own mock logger:
+const mockLogger = {
+  info: jest.fn(),
+  error: jest.fn(),
+  warn: jest.fn(),
+  child: jest.fn(() => mockLogger),
+};
+```
+
+#### Type Guards
+
+```typescript
 // Type guards for test assertions
-if (hasText(result)) {
+if ('text' in result && result.text) {
   expect(result.text).toContain('expected content');
 }
 
-if (hasError(result)) {
+if ('error' in result && result.error) {
   expect(result.error).toBeDefined();
 }
 ```
 
 ### Writing Custom Tests
 
-Example of writing a custom integration test:
+Example of writing a custom integration test using `resolveTestConfig`:
 
 ```typescript
 import {
@@ -1007,34 +1177,109 @@ import {
   LLMServiceFactory,
   LLMProviders,
   LLMPurposes,
+  resolveTestConfig,
 } from '@mate-academy/llm-gateway';
-import { mockLogger, resolveTestConfig } from '@mate-academy/llm-gateway/tests/helpers';
+
+// Create your own mock logger
+const mockLogger = {
+  info: jest.fn(),
+  error: jest.fn(),
+  warn: jest.fn(),
+  child: jest.fn(() => mockLogger),
+};
 
 describe('Custom LLM Integration Test', () => {
+  // Use resolveTestConfig for consistent test configuration
   const testConfig = resolveTestConfig(LLMPurposes.Completion);
 
-  Object.values(testConfig).forEach(({ provider, clientOptions, requireCredentials }) => {
+  // Test all enabled providers
+  Object.values(testConfig).forEach((config) => {
+    const { provider, clientOptions, requireCredentials } = config;
+
     describe(`${provider} Provider`, () => {
       let service;
 
       beforeAll(() => {
-        requireCredentials();
-        service = LLMServiceFactory.getCompletionService(
+        requireCredentials(); // Validates API keys are present
+
+        service = LLMServiceFactory.getCompletionService({
           provider,
-          mockLogger,
-          clientOptions
-        );
+          options: clientOptions,
+          logger: mockLogger, // Optional - can be omitted
+        });
       });
 
       it('should process custom request', async () => {
         // Your custom test logic here
+        const result = await service.sendMessage({
+          message: {
+            role: LLMRoles.User,
+            content: [{ type: LLMMessageContentType.TEXT, text: 'Test message' }],
+          },
+          model: Object.values(config.availableModels)[0], // Use first available model
+        });
+
+        // Use type guards for assertions
+        if ('text' in result && result.text) {
+          expect(result.text).toBeDefined();
+          expect(typeof result.text).toBe('string');
+        } else if ('error' in result && result.error) {
+          throw result.error;
+        }
       });
     });
   });
 });
 ```
 
-## Developer Guide: Adding a New Provider
+## Developer Guide
+
+### Schema Architecture Overview
+
+The LLM Gateway uses a **driver pattern** for schema conversion, providing clean separation between core schema logic and provider-specific implementations.
+
+**Core Components:**
+
+- **`LLMSchema`**: Core schema builder with unified API
+- **`SchemaAdapterInterface`**: Simple contract for provider-specific schema converters  
+- **`SCHEMA_ADAPTER_REGISTRY`**: Type-safe registry ensuring all providers are handled
+- **Provider Adapters**: Convert generic JSON Schema to provider-specific formats
+
+**How It Works:**
+
+```typescript
+// The schema uses a unified API regardless of provider
+const schema = LLMSchema.object({
+  name: LLMSchema.string(),
+  age: LLMSchema.number().min(1),
+});
+
+// Internally, services call _toProviderSchema() which automatically 
+// converts to the correct provider-specific format:
+schema._toProviderSchema(LLMProviders.OpenAI);           // → OpenAI JSON Schema format
+schema._toProviderSchema(LLMProviders.GoogleGenerativeAI); // → Google Type-based format
+```
+
+**Provider Schema Adapters:**
+
+Each provider has its own schema adapter located in `src/providers/{Provider}/schemas/`:
+
+- **`OpenAISchemaAdapter`**: Converts to OpenAI's JSON Schema format, handles strict mode requirements
+- **`GoogleSchemaAdapter`**: Converts to Google's Type-based schema format using their `Type` enum
+
+**Type-Safe Registry:**
+
+Schema adapters are managed through a centralized, type-safe registry that ensures compile-time safety:
+
+```typescript
+// src/utilities/schema/adapters/SchemaAdapterRegistry.ts
+export const SCHEMA_ADAPTER_REGISTRY = {
+  OpenAI: new OpenAISchemaAdapter(),
+  GoogleGenerativeAI: new GoogleSchemaAdapter(),
+} as const satisfies Record<LLMProviders, SchemaAdapterInterface | null>;
+```
+
+### Adding a New Provider
 
 To add support for a new LLM provider, follow these steps:
 
@@ -1049,6 +1294,8 @@ src/providers/YourProvider/
 ├── YourProvider.entity.ts      # Provider-specific entity
 ├── YourProvider.typedefs.ts    # TypeScript definitions
 ├── YourProviderService.factory.ts # Factory for your provider's services
+├── schemas/                    # Schema conversion adapters
+│   └── YourProviderSchemaAdapter.ts
 └── services/                   # Provider service implementations
     ├── index.ts
     ├── YourProviderCompletionService.ts
@@ -1123,7 +1370,60 @@ export type LLMModelName = {
 };
 ```
 
-### 4. Implement Provider Constants
+### 4. Create Schema Adapter
+
+Implement a schema adapter in `src/providers/YourProvider/schemas/YourProviderSchemaAdapter.ts`:
+
+```typescript
+import { LLMProviders } from '@/LLMService.typedefs';
+import type { SchemaAdapterInterface } from '@/utilities/schema/adapters/SchemaAdapterInterface';
+
+export class YourProviderSchemaAdapter implements SchemaAdapterInterface {
+  convertSchema(jsonSchema: any): any {
+    // Convert JSON Schema to your provider's specific format
+    // Example: transform to provider-specific schema structure
+    return this.transformToYourProviderFormat(jsonSchema);
+  }
+  
+  private transformToYourProviderFormat(jsonSchema: any): any {
+    // Implement provider-specific schema transformation logic
+    // Handle objects, arrays, strings, numbers, etc.
+    // Return the schema in your provider's expected format
+    
+    if (jsonSchema.type === 'object') {
+      // Handle object schemas
+      return {
+        // Your provider's object schema format
+      };
+    }
+    
+    // Handle other schema types...
+    return jsonSchema;
+  }
+}
+```
+
+### 5. Add Adapter to Schema Registry
+
+Update the schema adapter registry in `src/utilities/schema/adapters/SchemaAdapterRegistry.ts`:
+
+```typescript
+import { YourProviderSchemaAdapter } from '@/providers/YourProvider/schemas/YourProviderSchemaAdapter';
+
+export const SCHEMA_ADAPTER_REGISTRY = {
+  OpenAI: new OpenAISchemaAdapter(),
+  GoogleGenerativeAI: new GoogleSchemaAdapter(),
+  YourProvider: new YourProviderSchemaAdapter(), // Add your adapter here
+  // TypeScript will enforce that ALL providers have adapters
+} as const satisfies Record<LLMProviders, SchemaAdapterInterface | null>;
+```
+
+If your provider doesn't support structured output, set it to `null`:
+```typescript
+YourProvider: null, // Provider doesn't support structured output
+```
+
+### 6. Implement Provider Constants
 
 Define constants in `src/providers/YourProvider/YourProvider.constants.ts`:
 
@@ -1221,7 +1521,7 @@ export const YOUR_PROVIDER_SERVICE_BUILDERS: {
 };
 ```
 
-### 5. Implement Provider Entity (if needed)
+### 6. Implement Provider Entity (if needed)
 
 Create the entity class in `src/providers/YourProvider/YourProvider.entity.ts`:
 
@@ -1231,28 +1531,28 @@ export class YourProviderEntity {
 }
 ```
 
-### 6. Implement Service Classes
+### 7. Implement Service Classes
 
 Create service implementations in the `services` directory:
 
 **CompletionService (src/providers/YourProvider/services/YourProviderCompletionService.ts)**:
 
 ```typescript
-import { Logger } from '../../../LLMService.typedefs';
+import { LLMLogger } 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,
+    logger: LLMLogger | undefined,
     private readonly providerEntity: YourProviderEntity,
   ) {
     super(logger);
   }
 
   async complete(params: CompletionParams): Promise<CompletionResult> {
-    this.logger.info('Starting completion with YourProvider', { params });
+    this.logger?.info('Starting completion with YourProvider', { params });
 
     try {
       // Implement provider-specific completion logic
@@ -1262,7 +1562,7 @@ export class YourProviderCompletionService extends LLMCompletionService<LLMProvi
         // Include other required fields
       };
     } catch (error) {
-      this.logger.error('Error in YourProvider completion', { error });
+      this.logger?.error('Error in YourProvider completion', { error });
       throw error;
     }
   }
@@ -1272,7 +1572,7 @@ export class YourProviderCompletionService extends LLMCompletionService<LLMProvi
 **AssistanceService (if applicable)**:
 
 ```typescript
-import { Logger } from '../../../LLMService.typedefs';
+import { LLMLogger } from '../../../LLMService.typedefs';
 import { LLMAssistanceService } from '../../../services/LLMAssistanceService.abstract';
 import {
   LLMAssistanceOptions,
@@ -1283,7 +1583,7 @@ import { YourProviderEntity } from '../YourProvider.entity';
 
 export class YourProviderAssistanceService extends LLMAssistanceService<LLMProviders.YourProvider> {
   constructor(
-    logger: Logger,
+    logger: LLMLogger,
     private readonly providerEntity: YourProviderEntity,
   ) {
     super(logger);
@@ -1311,7 +1611,7 @@ export class YourProviderAssistanceService extends LLMAssistanceService<LLMProvi
 **SpeechToTextService (if applicable)**:
 
 ```typescript
-import { Logger } from '../../../LLMService.typedefs';
+import { LLMLogger } from '../../../LLMService.typedefs';
 import { LLMSpeechToTextService } from '../../../services/LLMSpeechToTextService.abstract';
 import {
   LLMTranscribeOptions,
@@ -1322,14 +1622,14 @@ import { YourProviderEntity } from '../YourProvider.entity';
 
 export class YourProviderSpeechToTextService extends LLMSpeechToTextService<LLMProviders.YourProvider> {
   constructor(
-    logger: Logger,
+    logger: LLMLogger | undefined,
     private readonly providerEntity: YourProviderEntity,
   ) {
     super(logger);
   }
 
   async transcribe(options: LLMTranscribeOptions<typeof this.provider>): Promise<LLMTranscribeResult> {
-    this.logger.info('Starting transcription with YourProvider', { options });
+    this.logger?.info('Starting transcription with YourProvider', { options });
 
     try {
       // Implement provider-specific transcription logic
@@ -1337,7 +1637,7 @@ export class YourProviderSpeechToTextService extends LLMSpeechToTextService<LLMP
         text: 'Transcribed text from audio',
       };
     } catch (error) {
-      this.logger.error('Error in YourProvider transcription', { error });
+      this.logger?.error('Error in YourProvider transcription', { error });
       throw error;
     }
   }
@@ -1347,7 +1647,7 @@ export class YourProviderSpeechToTextService extends LLMSpeechToTextService<LLMP
 **TextToSpeechService (if applicable)**:
 
 ```typescript
-import { Logger } from '../../../LLMService.typedefs';
+import { LLMLogger } from '../../../LLMService.typedefs';
 import { LLMTextToSpeechService } from '../../../services/LLMTextToSpeechService.abstract';
 import {
   LLMCreateSpeechOptions,
@@ -1358,14 +1658,14 @@ import { YourProviderEntity } from '../YourProvider.entity';
 
 export class YourProviderTextToSpeechService extends LLMTextToSpeechService<LLMProviders.YourProvider> {
   constructor(
-    logger: Logger,
+    logger: LLMLogger | undefined,
     private readonly providerEntity: YourProviderEntity,
   ) {
     super(logger);
   }
 
   async createSpeech(options: LLMCreateSpeechOptions<typeof this.provider>): Promise<LLMCreateSpeechResult> {
-    this.logger.info('Starting speech creation with YourProvider', { options });
+    this.logger?.info('Starting speech creation with YourProvider', { options });
 
     try {
       // Implement provider-specific speech creation logic
@@ -1374,14 +1674,14 @@ export class YourProviderTextToSpeechService extends LLMTextToSpeechService<LLMP
         mimeType: 'audio/mp3',
       };
     } catch (error) {
-      this.logger.error('Error in YourProvider speech creation', { error });
+      this.logger?.error('Error in YourProvider speech creation', { error });
       throw error;
     }
   }
 }
 ```
 
-### 7. Create Service Factory
+### 8. Create Service Factory
 
 First, define service builders in `src/providers/YourProvider/YourProvider.constants.ts`:
 
@@ -1412,14 +1712,13 @@ export const YOUR_PROVIDER_SERVICE_BUILDERS: {
 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 { LLMServicePurposeFactory, type LLMCreateServiceOptions } from '../../services';
 import { YOUR_PROVIDER_SERVICE_BUILDERS } from './YourProvider.constants';
 
 export class YourProviderServiceFactory extends LLMServicePurposeFactory<
@@ -1428,10 +1727,9 @@ export class YourProviderServiceFactory extends LLMServicePurposeFactory<
   createService<
     Purpose extends LLMPurposes
   >(
-    purpose: Purpose,
-    logger: Logger,
-    options: LLMInstanceOptions[LLMProviders.YourProvider],
+    serviceOptions: LLMCreateServiceOptions<LLMProviders.YourProvider, Purpose>,
   ): LLMServiceByPurpose<LLMProviders.YourProvider>[Purpose] {
+    const { purpose, logger, options } = serviceOptions;
     const serviceBuilder = YOUR_PROVIDER_SERVICE_BUILDERS[purpose];
 
     if (!serviceBuilder) {
@@ -1443,7 +1741,7 @@ export class YourProviderServiceFactory extends LLMServicePurposeFactory<
 }
 ```
 
-### 8. Update Entry Point Files
+### 9. Update Entry Point Files
 
 Update the provider's `index.ts`:
 
@@ -1462,14 +1760,14 @@ Update the main providers `index.ts` at `src/providers/index.ts`:
 export * from './YourProvider';
 ```
 
-### 9. Update LLM Service Factory
+### 10. Update LLM Service Factory
 
 Modify `src/LLMService.factory.ts` to include your new provider:
 
 ```typescript
 import {
   LLMProviders,
-  Logger,
+  LLMServiceOptions,
   YourProviderOptions,
 } from './LLMService.typedefs';
 import { YourProviderServiceFactory } from './providers/YourProvider';
@@ -1487,72 +1785,68 @@ export class LLMServiceFactory {
   }
 
   static getCompletionService<T extends LLMProviders>(
-    provider: T,
-    logger: Logger,
-    options: any,
+    serviceOptions: LLMServiceOptions<T>,
   ) {
+    const { provider, options, logger } = serviceOptions;
     switch (provider) {
       // ... other providers
       case LLMProviders.YourProvider:
-        return YourProviderServiceFactory.createService(
-          LLMPurposes.Completion,
+        return YourProviderServiceFactory.createService({
+          purpose: LLMPurposes.Completion,
           logger,
           options
-        );
+        });
       default:
         throw new Error(`Unsupported provider: ${provider}`);
     }
   }
 
   static getAssistanceService<T extends LLMProviders>(
-    provider: T,
-    logger: Logger,
-    options: any,
+    serviceOptions: LLMServiceOptions<T>,
   ) {
+    const { provider, options, logger } = serviceOptions;
     switch (provider) {
       // ... other providers
       case LLMProviders.YourProvider:
-        return YourProviderServiceFactory.createService(
-          LLMPurposes.Assistance,
+        return YourProviderServiceFactory.createService({
+          purpose: LLMPurposes.Assistance,
           logger,
           options
-        );
+        });
       default:
         throw new Error(`Unsupported provider: ${provider}`);
     }
   }
 
   static getSpeechToTextService<T extends LLMProviders>(
-    provider: T,
-    logger: Logger,
-    options: any,
+    serviceOptions: LLMServiceOptions<T>,
   ) {
+    const { provider, options, logger } = serviceOptions;
     switch (provider) {
       // ... other providers
       case LLMProviders.YourProvider:
-        return YourProviderServiceFactory.createService(
-          LLMPurposes.SpeechToText,
+        return YourProviderServiceFactory.createService({
+          purpose: LLMPurposes.SpeechToText,
           logger,
           options
-        );
+        });
       default:
         throw new Error(`Unsupported provider: ${provider}`);
     }
   }
 
   static getTextToSpeechService<T extends LLMProviders>(
-    provider: T,
-    logger: Logger,
-    options: any,
+    serviceOptions: LLMServiceOptions<T>,
   ) {
+    const { provider, options, logger } = serviceOptions;
     switch (provider) {
       // ... other providers
       case LLMProviders.YourProvider:
-        return YourProviderServiceFactory.createService(
-          LLMPurposes.TextToSpeech,
+        return YourProviderServiceFactory.createService({
+          purpose: LLMPurposes.TextToSpeech,
           logger,
           options
-        );
+        });
       default:
         throw new Error(`Unsupported provider: ${provider}`);
     }