@synova-cloud/sdk 1.6.0 → 1.8.0

package/README.md

@@ -174,6 +174,205 @@ 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 |
+
+### Observability
+
+Track and group your LLM calls using traces and spans. Each execution creates a span, and multiple spans can be grouped into a trace using `sessionId`.
+
+#### Session-Based Tracing
+
+Use `sessionId` to group related calls (e.g., a conversation) into a single trace:
+
+```typescript
+const sessionId = 'chat_user123_conv1';
+
+// First message - creates new trace
+const response1 = await client.prompts.execute('prm_abc123', {
+  provider: 'openai',
+  model: 'gpt-4o',
+  sessionId,
+  variables: { topic: 'TypeScript' },
+});
+
+console.log(response1.traceId);  // trc_xxx
+console.log(response1.spanId);   // spn_xxx
+
+// Follow-up - same sessionId = same trace, new span
+const response2 = await client.prompts.execute('prm_abc123', {
+  provider: 'openai',
+  model: 'gpt-4o',
+  sessionId,
+  messages: [
+    { role: 'assistant', content: response1.content },
+    { role: 'user', content: 'Tell me more' },
+  ],
+});
+
+// response2.traceId === response1.traceId (same trace)
+// response2.spanId !== response1.spanId (new span)
+```
+
+#### Response Properties
+
+Every execution returns observability IDs:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `spanDataId` | `string` | Execution data ID (messages, response, usage) |
+| `traceId` | `string` | Trace ID (groups related calls) |
+| `spanId` | `string` | Span ID (this specific call) |
+
+#### Custom Span Tracking
+
+Track tool calls, retrieval operations, and custom logic as spans within a trace.
+
+**Manual approach:**
+
+```typescript
+// Create span
+const span = await client.spans.create(traceId, {
+  type: 'tool',
+  toolName: 'fetch_weather',
+  toolArguments: { city: 'NYC' },
+  parentSpanId: generationSpanId,
+});
+
+// Execute
+const weather = await fetchWeather('NYC');
+
+// End span
+await client.spans.end(span.id, {
+  status: 'completed',
+  toolResult: weather,
+});
+```
+
+**Wrapper approach:**
+
+```typescript
+// wrapTool() - for tools
+const weather = await client.spans.wrapTool(
+  { traceId, toolName: 'fetch_weather', parentSpanId },
+  { city: 'NYC' },
+  async (args) => fetchWeather(args.city),
+);
+
+// wrap() - for custom/retriever/embedding
+const docs = await client.spans.wrap(
+  { traceId, type: 'retriever', name: 'vector_search' },
+  { query: 'how to...', topK: 5 },
+  async () => vectorDb.search(query),
+);
+```
+
+Wrappers automatically handle errors and set `status: 'error'` with message.
+
+#### Span Types
+
+| Type | Use Case |
+|------|----------|
+| `generation` | LLM calls (auto-created by `execute()`) |
+| `tool` | Tool/function calls |
+| `retriever` | RAG document retrieval |
+| `embedding` | Embedding generation |
+| `custom` | Any custom operation |
+
+#### Viewing Traces
+
+View your traces in the [Synova Cloud Dashboard](https://app.synova.cloud) under the Observability section. Each trace shows:
+- All spans (LLM calls) in the session
+- Input/output for each span
+- Token usage and latency
+- Error details if any
+
 ### Models
 
 #### List All Models
@@ -268,28 +467,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 +522,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);
   }
 }
 ```
@@ -412,14 +629,25 @@ import type {
   ISynovaPromptVariable,
   ISynovaGetPromptOptions,
   // Execution
-  ISynovaExecuteOptions,
-  ISynovaExecuteResponse,
-  ISynovaUsage,
+  ISynovaExecuteOptions,       // includes sessionId
+  ISynovaExecuteTypedOptions,
+  ISynovaExecuteResponse,      // includes spanDataId, traceId, spanId
+  ISynovaExecutionUsage,
   ISynovaExecutionError,
   // Messages
   ISynovaMessage,
   TSynovaMessageRole,
   TSynovaResponseType,
+  // Spans
+  ISynovaSpan,
+  ISynovaSpanData,
+  ISynovaCreateSpanOptions,
+  ISynovaEndSpanOptions,
+  ISynovaWrapOptions,
+  ISynovaWrapToolOptions,
+  TSynovaSpanType,
+  TSynovaSpanStatus,
+  TSynovaSpanLevel,
   // Files
   ISynovaFileAttachment,
   ISynovaFileThumbnails,
@@ -435,6 +663,13 @@ import type {
   ISynovaModelsResponse,
   ISynovaListModelsOptions,
   TSynovaModelType,
+  // Schema
+  IJsonSchema,
+  TJsonSchemaType,
+  TJsonSchemaFormat,
+  TClassConstructor,
+  // Errors
+  IValidationViolation,
 } from '@synova-cloud/sdk';
 ```
 
@@ -452,6 +687,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