@sensu-ai/sdk 0.1.5 → 0.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sensu-ai/sdk",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "type": "module",
   "main": "./src/index.ts",
   "exports": {

package/src/client.ts

@@ -22,6 +22,7 @@ import type {
   DeployPromptVersionOptions,
   StartSessionOptions,
   ResumeSessionOptions,
+  RetrievalChunkInput,
 } from './types.js';
 
 // ---------------------------------------------------------------------------
@@ -86,6 +87,7 @@ export class StepHandle {
   async trackLlm(opts: TrackLlmOptions): Promise<unknown> {
     const startMs = Date.now();
     const spanId = randomUUID();
+    const llmCallId = opts.llmCallId ?? randomUUID();
 
     this.client.enqueue({
       ...this.base(),
@@ -113,10 +115,11 @@ export class StepHandle {
     const usage = extractUsage(result, opts.model);
     const contextBreakdown = opts.extractContextBreakdown?.(result);
 
-    this.client.enqueue({
+    (this.client.enqueue as (e: unknown) => void)({
       ...this.base(),
       span_id: spanId,
       event_type: 'llm.request.completed',
+      llm_call_id: llmCallId,
       provider: opts.provider,
       model: opts.model,
       max_context_tokens: opts.maxContextTokens,
@@ -124,6 +127,8 @@ export class StepHandle {
       status,
       ...usage,
       ...(contextBreakdown ? { context_breakdown: contextBreakdown } : {}),
+      ...(opts.messagesSnapshot?.length ? { messages_snapshot: opts.messagesSnapshot } : {}),
+      ...(opts.referencedChunkIds?.length ? { referenced_chunk_ids: opts.referencedChunkIds } : {}),
     });
 
     if (err) throw err;
@@ -213,10 +218,18 @@ export class StepHandle {
 
   /** Emit a raw retrieval completed event (when you have the stats already) */
   recordRetrieval(opts: RawRetrievalOptions): void {
+    const chunks: RetrievalChunkInput[] | undefined = opts.chunks;
     this.client.enqueue({
       ...this.base(),
       event_type: 'retrieval.completed',
-      ...opts,
+      vector_store_id: opts.vectorStoreId,
+      top_k: opts.topK,
+      latency_ms: opts.latencyMs,
+      chunks_returned: opts.chunksReturned,
+      tokens_injected: opts.tokensInjected,
+      similarity_score_avg: opts.similarityScoreAvg,
+      status: opts.status,
+      ...(chunks?.length ? { chunks } : {}),
     });
   }
 
@@ -443,6 +456,8 @@ export class RunHandle {
       score: opts.score,
       evaluator_id: opts.evaluatorId,
       model_used_for_eval: opts.modelUsedForEval,
+      ...(opts.stepId ? { step_id: opts.stepId } : {}),
+      ...(opts.llmCallId ? { llm_call_id: opts.llmCallId } : {}),
     });
   }
 

package/src/types.ts

@@ -35,6 +35,13 @@ export interface ContextBreakdown {
   retrieval_tokens?: number;
 }
 
+export interface MessageSnapshotItem {
+  role: 'system' | 'user' | 'assistant' | 'tool';
+  tool_name?: string;
+  token_count: number;
+  content_hash: string;
+}
+
 export interface TrackLlmOptions {
   provider: string;
   model: string;
@@ -46,6 +53,12 @@ export interface TrackLlmOptions {
    * Called with the raw response after fn() resolves.
    */
   extractContextBreakdown?: (result: unknown) => ContextBreakdown | undefined;
+  /** Stable ID for this LLM call — used to link eval scores. Generated if omitted. */
+  llmCallId?: string;
+  /** Snapshot of every message in the context window sent to this LLM call. */
+  messagesSnapshot?: MessageSnapshotItem[];
+  /** IDs of retrieval chunks whose content the model actually referenced in its output. */
+  referencedChunkIds?: string[];
 }
 
 export interface LlmResult {
@@ -89,6 +102,14 @@ export interface TrackRetrievalOptions {
   topK?: number;
 }
 
+export interface RetrievalChunkInput {
+  chunk_id: string;
+  source?: string;
+  token_count: number;
+  similarity_score?: number;
+  content_preview?: string;
+}
+
 export interface RawRetrievalOptions {
   vectorStoreId?: string;
   topK?: number;
@@ -97,6 +118,8 @@ export interface RawRetrievalOptions {
   tokensInjected?: number;
   similarityScoreAvg?: number;
   status?: 'success' | 'error';
+  /** Per-chunk detail for retrieval noise analysis. */
+  chunks?: RetrievalChunkInput[];
 }
 
 export interface TrackEmbeddingOptions {
@@ -132,6 +155,10 @@ export interface RecordEvalScoreOptions {
   score: number;
   evaluatorId?: string;
   modelUsedForEval?: string;
+  /** Step ID this eval score is linked to — enables quality correlation view. */
+  stepId?: string;
+  /** LLM call ID this eval score is linked to — must match the llmCallId used in trackLlm(). */
+  llmCallId?: string;
 }
 
 // ---------------------------------------------------------------------------