@synova-cloud/sdk 1.7.0 → 1.8.0

package/README.md

@@ -263,6 +263,116 @@ const topic = await client.prompts.execute('prm_abc123', {
 | `@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
@@ -519,15 +629,25 @@ import type {
   ISynovaPromptVariable,
   ISynovaGetPromptOptions,
   // Execution
-  ISynovaExecuteOptions,
+  ISynovaExecuteOptions,       // includes sessionId
   ISynovaExecuteTypedOptions,
-  ISynovaExecuteResponse,
+  ISynovaExecuteResponse,      // includes spanDataId, traceId, spanId
   ISynovaExecutionUsage,
   ISynovaExecutionError,
   // Messages
   ISynovaMessage,
   TSynovaMessageRole,
   TSynovaResponseType,
+  // Spans
+  ISynovaSpan,
+  ISynovaSpanData,
+  ISynovaCreateSpanOptions,
+  ISynovaEndSpanOptions,
+  ISynovaWrapOptions,
+  ISynovaWrapToolOptions,
+  TSynovaSpanType,
+  TSynovaSpanStatus,
+  TSynovaSpanLevel,
   // Files
   ISynovaFileAttachment,
   ISynovaFileThumbnails,

package/dist/index.cjs

@@ -107,7 +107,7 @@ var ValidationSynovaError = class extends SynovaError {
 };
 
 // src/version.ts
-var SDK_VERSION = "1.7.0" ;
+var SDK_VERSION = "1.8.0" ;
 
 // src/utils/http.ts
 var HttpClient = class {
@@ -820,6 +820,7 @@ var PromptsResource = class {
     if (options.metadata !== void 0) body.metadata = options.metadata;
     if (options.parameters !== void 0) body.parameters = options.parameters;
     if (options.responseSchema !== void 0) body.responseSchema = options.responseSchema;
+    if (options.sessionId !== void 0) body.sessionId = options.sessionId;
     const response = await this.http.request({
       method: "POST",
       path: `/api/v1/prompts/${promptId}/run`,
@@ -1004,6 +1005,137 @@ var FilesResource = class {
   }
 };
 
+// src/resources/spans.ts
+var SpansResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Create a new span within a trace
+   *
+   * @param traceId - The trace ID to create span in
+   * @param options - Span creation options
+   * @returns Created span
+   */
+  async create(traceId, options) {
+    const body = {
+      type: options.type
+    };
+    if (options.parentSpanId !== void 0) body.parentSpanId = options.parentSpanId;
+    if (options.name !== void 0) body.name = options.name;
+    if (options.input !== void 0) body.input = options.input;
+    if (options.toolName !== void 0) body.toolName = options.toolName;
+    if (options.toolArguments !== void 0) body.toolArguments = options.toolArguments;
+    if (options.metadata !== void 0) body.metadata = options.metadata;
+    return this.http.request({
+      method: "POST",
+      path: `/api/v1/traces/${traceId}/spans`,
+      body
+    });
+  }
+  /**
+   * End/complete a span
+   *
+   * @param spanId - The span ID to end
+   * @param options - Span end options
+   * @returns Updated span
+   */
+  async end(spanId, options) {
+    const body = {};
+    if (options?.status !== void 0) body.status = options.status;
+    if (options?.level !== void 0) body.level = options.level;
+    if (options?.statusMessage !== void 0) body.statusMessage = options.statusMessage;
+    if (options?.output !== void 0) body.output = options.output;
+    if (options?.toolResult !== void 0) body.toolResult = options.toolResult;
+    if (options?.durationMs !== void 0) body.durationMs = options.durationMs;
+    return this.http.request({
+      method: "PATCH",
+      path: `/api/v1/spans/${spanId}`,
+      body
+    });
+  }
+  /**
+   * Wrap an async function with automatic span tracking
+   *
+   * @param options - Span options (traceId, type, name, etc.)
+   * @param input - Input data to record in span
+   * @param fn - Async function to execute
+   * @returns Result of the function
+   *
+   * @example
+   * ```ts
+   * const result = await client.spans.wrap(
+   *   { traceId: 'trc_123', type: 'retriever', name: 'vector_search' },
+   *   { query: 'how to...', topK: 5 },
+   *   async () => vectorDb.search(query),
+   * );
+   * ```
+   */
+  async wrap(options, input, fn) {
+    const span = await this.create(options.traceId, {
+      type: options.type,
+      name: options.name,
+      parentSpanId: options.parentSpanId,
+      input,
+      metadata: options.metadata
+    });
+    try {
+      const result = await fn();
+      await this.end(span.id, {
+        status: "completed",
+        output: result
+      });
+      return result;
+    } catch (error) {
+      await this.end(span.id, {
+        status: "error",
+        statusMessage: error instanceof Error ? error.message : String(error)
+      });
+      throw error;
+    }
+  }
+  /**
+   * Wrap a tool function with automatic span tracking
+   *
+   * @param options - Tool span options (traceId, toolName, etc.)
+   * @param args - Tool arguments to record
+   * @param fn - Tool function to execute
+   * @returns Result of the tool
+   *
+   * @example
+   * ```ts
+   * const weather = await client.spans.wrapTool(
+   *   { traceId: 'trc_123', toolName: 'fetch_weather', parentSpanId: 'spn_abc' },
+   *   { city: 'NYC' },
+   *   async (args) => fetchWeather(args.city),
+   * );
+   * ```
+   */
+  async wrapTool(options, args, fn) {
+    const span = await this.create(options.traceId, {
+      type: "tool",
+      toolName: options.toolName,
+      toolArguments: args,
+      parentSpanId: options.parentSpanId,
+      metadata: options.metadata
+    });
+    try {
+      const result = await fn(args);
+      await this.end(span.id, {
+        status: "completed",
+        toolResult: result
+      });
+      return result;
+    } catch (error) {
+      await this.end(span.id, {
+        status: "error",
+        statusMessage: error instanceof Error ? error.message : String(error)
+      });
+      throw error;
+    }
+  }
+};
+
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.synova.cloud";
 var DEFAULT_TIMEOUT = 3e4;
@@ -1024,6 +1156,7 @@ var SynovaCloudSdk = class {
   prompts;
   models;
   files;
+  spans;
   http;
   /**
    * Create a new Synova Cloud SDK client
@@ -1052,6 +1185,7 @@ var SynovaCloudSdk = class {
     this.prompts = new PromptsResource(this.http);
     this.models = new ModelsResource(this.http);
     this.files = new FilesResource(this.http);
+    this.spans = new SpansResource(this.http);
   }
 };