@synova-cloud/sdk 1.6.0 → 1.7.0

package/README.md

@@ -174,6 +174,95 @@ if (response.type === 'image') {
 }
 ```
 
+#### Structured Output (Typed Responses)
+
+Get typed and validated responses from LLMs using JSON Schema.
+
+First, install optional peer dependencies:
+```bash
+npm install class-validator class-transformer
+```
+
+Define a response class with decorators:
+```typescript
+import { IsString, IsArray, IsNumber, Min, Max } from 'class-validator';
+import { Description, Example, ArrayItems } from '@synova-cloud/sdk';
+
+class TopicDto {
+  @IsString()
+  @Description('Article title for SEO')
+  @Example('10 Ways to Improve SQL Performance')
+  title: string;
+
+  @IsString()
+  @Description('Short description')
+  description: string;
+
+  @IsArray()
+  @ArrayItems(String)
+  @Description('SEO keywords')
+  keywords: string[];
+
+  @IsNumber()
+  @Min(1)
+  @Max(10)
+  @Description('Priority from 1 to 10')
+  priority: number;
+}
+```
+
+Execute with `responseClass` to get typed response:
+```typescript
+const topic = await client.prompts.execute('prm_abc123', {
+  provider: 'openai',
+  model: 'gpt-4o',
+  responseClass: TopicDto,
+});
+
+// topic is typed as TopicDto
+console.log(topic.title);     // string
+console.log(topic.keywords);  // string[]
+console.log(topic.priority);  // number
+```
+
+Works with `executeByTag` and `executeByVersion` too:
+```typescript
+const topic = await client.prompts.executeByTag('prm_abc123', 'production', {
+  provider: 'openai',
+  model: 'gpt-4o',
+  responseClass: TopicDto,
+});
+```
+
+Disable validation if needed:
+```typescript
+const topic = await client.prompts.execute('prm_abc123', {
+  provider: 'openai',
+  model: 'gpt-4o',
+  responseClass: TopicDto,
+  validate: false, // Skip class-validator validation
+});
+```
+
+**Available Schema Decorators:**
+
+| Decorator | Description |
+|-----------|-------------|
+| `@Description(text)` | Adds description to help LLM |
+| `@Example(...values)` | Adds example values |
+| `@Default(value)` | Sets default value |
+| `@ArrayItems(Type)` | Sets array item type |
+| `@Format(format)` | Sets string format (email, uri, uuid, date-time) |
+| `@Nullable()` | Marks as nullable |
+| `@SchemaMin(n)` | Minimum number value |
+| `@SchemaMax(n)` | Maximum number value |
+| `@SchemaMinLength(n)` | Minimum string length |
+| `@SchemaMaxLength(n)` | Maximum string length |
+| `@SchemaPattern(regex)` | Regex pattern for string |
+| `@SchemaMinItems(n)` | Minimum array length |
+| `@SchemaMaxItems(n)` | Maximum array length |
+| `@SchemaEnum(values)` | Allowed enum values |
+
 ### Models
 
 #### List All Models
@@ -268,28 +357,48 @@ console.log(response.content);
 
 ## Error Handling
 
-The SDK provides typed errors for different failure scenarios. All API errors extend `ApiSynovaError` and include full error details:
+The SDK provides typed errors for different failure scenarios:
 
 ```typescript
 import {
   SynovaCloudSdk,
-  SynovaError,
-  ApiSynovaError,
+  ExecutionSynovaError,
+  ValidationSynovaError,
   AuthSynovaError,
   NotFoundSynovaError,
   RateLimitSynovaError,
   ServerSynovaError,
   TimeoutSynovaError,
   NetworkSynovaError,
+  ApiSynovaError,
 } from '@synova-cloud/sdk';
 
 try {
   const response = await client.prompts.execute('prm_abc123', {
     provider: 'openai',
     model: 'gpt-4o',
-    variables: { name: 'World' },
+    responseClass: TopicDto,
   });
 } catch (error) {
+  // LLM execution error (rate limit, invalid key, context too long, etc.)
+  if (error instanceof ExecutionSynovaError) {
+    console.error(`LLM error [${error.code}]: ${error.message}`);
+    console.error(`Provider: ${error.provider}`);
+    console.error(`Retryable: ${error.retryable}`);
+    if (error.retryAfterMs) {
+      console.error(`Retry after: ${error.retryAfterMs}ms`);
+    }
+  }
+
+  // Validation error (response doesn't match class-validator constraints)
+  if (error instanceof ValidationSynovaError) {
+    console.error('Validation failed:');
+    for (const v of error.violations) {
+      console.error(`  ${v.property}: ${Object.values(v.constraints).join(', ')}`);
+    }
+  }
+
+  // API errors
   if (error instanceof AuthSynovaError) {
     console.error('Invalid API key');
   } else if (error instanceof NotFoundSynovaError) {
@@ -303,10 +412,8 @@ try {
   } else if (error instanceof NetworkSynovaError) {
     console.error(`Network error: ${error.message}`);
   } else if (error instanceof ApiSynovaError) {
-    // All API errors have these properties:
     console.error(`API error [${error.code}]: ${error.message}`);
     console.error(`Request ID: ${error.requestId}`);
-    console.error(`Details:`, error.details);
   }
 }
 ```
@@ -413,8 +520,9 @@ import type {
   ISynovaGetPromptOptions,
   // Execution
   ISynovaExecuteOptions,
+  ISynovaExecuteTypedOptions,
   ISynovaExecuteResponse,
-  ISynovaUsage,
+  ISynovaExecutionUsage,
   ISynovaExecutionError,
   // Messages
   ISynovaMessage,
@@ -435,6 +543,13 @@ import type {
   ISynovaModelsResponse,
   ISynovaListModelsOptions,
   TSynovaModelType,
+  // Schema
+  IJsonSchema,
+  TJsonSchemaType,
+  TJsonSchemaFormat,
+  TClassConstructor,
+  // Errors
+  IValidationViolation,
 } from '@synova-cloud/sdk';
 ```
 
@@ -452,6 +567,15 @@ const client = new SynovaCloudSdk('your-api-key');
 
 - Node.js 18+ (uses native `fetch`)
 
+### Optional Peer Dependencies
+
+For structured output with typed responses:
+```bash
+npm install class-validator class-transformer
+```
+
+These are optional - the SDK works without them, but `responseClass` feature requires them.
+
 ## License
 
 MIT