@mate-academy/llm-gateway 3.0.0 → 3.0.3

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
@@ -398,6 +399,12 @@ 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.
@@ -764,6 +771,47 @@ const basicLesson = coursePrompt({
 });
 ```
 
+#### Negative Conditional Sections
+
+Negative conditions allow you to show content when a value is falsy:
+
+```typescript
+const feedbackPrompt = createPromptTemplate(`
+  Analyze the {{language}} code submission.
+  {{#passed}}
+  Great job! The tests passed successfully.
+  {{/passed}}
+  {{#!passed}}
+  The tests did not pass. Please review the following issues:
+  {{errors}}
+  {{/passed}}
+  
+  {{#!skipSuggestions}}
+  Here are some suggestions for improvement:
+  - Consider refactoring for better readability
+  - Add more comprehensive error handling
+  {{/skipSuggestions}}
+`);
+
+// When tests pass
+const successResult = feedbackPrompt({
+  language: 'JavaScript',
+  passed: true,
+  errors: '',
+  skipSuggestions: false
+});
+// Result: Shows success message and suggestions
+
+// When tests fail
+const failureResult = feedbackPrompt({
+  language: 'Python',
+  passed: false,
+  errors: 'TypeError on line 15',
+  skipSuggestions: false
+});
+// Result: Shows failure message with errors and suggestions
+```
+
 #### Nested Conditional Sections
 
 You can nest conditional sections for more complex logic:
@@ -962,8 +1010,10 @@ Creates a prompt template function from a template string.
 - Replacement values can be strings, numbers, or booleans (automatically converted to strings)
 
 **Conditional Sections:**
-- Conditional sections use the syntax: `{{#conditionName}}content{{/conditionName}}`
-- The section content is included only if the condition variable is truthy
+- Positive conditional sections use the syntax: `{{#conditionName}}content{{/conditionName}}`
+  - The section content is included only if the condition variable is truthy
+- Negative conditional sections use the syntax: `{{#!conditionName}}content{{/conditionName}}`
+  - The section content is included only if the condition variable is falsy
 - Truthy values: `true`, non-empty strings, non-zero numbers
 - Falsy values: `false`, empty strings, `0`, `null`, `undefined`
 - Conditional variables are optional in the type system when used only as conditions
@@ -1111,7 +1161,7 @@ const testConfig = resolveTestConfig(LLMPurposes.Completion);
 // 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
@@ -1194,7 +1244,7 @@ describe('Custom LLM Integration Test', () => {
 
       beforeAll(() => {
         requireCredentials(); // Validates API keys are present
-        
+
         service = LLMServiceFactory.getCompletionService({
           provider,
           options: clientOptions,
@@ -1225,7 +1275,54 @@ describe('Custom LLM Integration Test', () => {
 });
 ```
 
-## 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:
 
@@ -1240,6 +1337,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
@@ -1314,7 +1413,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`:
 
@@ -1412,7 +1564,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`:
 
@@ -1422,7 +1574,7 @@ export class YourProviderEntity {
 }
 ```
 
-### 6. Implement Service Classes
+### 7. Implement Service Classes
 
 Create service implementations in the `services` directory:
 
@@ -1572,7 +1724,7 @@ export class YourProviderTextToSpeechService extends LLMTextToSpeechService<LLMP
 }
 ```
 
-### 7. Create Service Factory
+### 8. Create Service Factory
 
 First, define service builders in `src/providers/YourProvider/YourProvider.constants.ts`:
 
@@ -1632,7 +1784,7 @@ export class YourProviderServiceFactory extends LLMServicePurposeFactory<
 }
 ```
 
-### 8. Update Entry Point Files
+### 9. Update Entry Point Files
 
 Update the provider's `index.ts`:
 
@@ -1651,7 +1803,7 @@ 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: