observa-sdk 0.0.8 → 0.0.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +300 -11
  2. package/dist/index.cjs +658 -7
  3. package/dist/index.d.cts +181 -3
  4. package/dist/index.d.ts +181 -3
  5. package/dist/index.js +663 -7
  6. package/package.json +1 -1
package/dist/index.d.cts CHANGED
@@ -63,7 +63,64 @@ declare class Observa {
63
63
  userId?: string;
64
64
  }): string;
65
65
  /**
66
- * Track a tool call
66
+ * Track an LLM call with full OTEL support
67
+ * CRITICAL: This is the primary method for tracking LLM calls with all SOTA parameters
68
+ */
69
+ trackLLMCall(options: {
70
+ model: string;
71
+ input?: string | null;
72
+ output?: string | null;
73
+ inputTokens?: number | null;
74
+ outputTokens?: number | null;
75
+ totalTokens?: number | null;
76
+ latencyMs: number;
77
+ timeToFirstTokenMs?: number | null;
78
+ streamingDurationMs?: number | null;
79
+ finishReason?: string | null;
80
+ responseId?: string | null;
81
+ systemFingerprint?: string | null;
82
+ cost?: number | null;
83
+ temperature?: number | null;
84
+ maxTokens?: number | null;
85
+ operationName?: "chat" | "text_completion" | "generate_content" | string | null;
86
+ providerName?: string | null;
87
+ responseModel?: string | null;
88
+ topK?: number | null;
89
+ topP?: number | null;
90
+ frequencyPenalty?: number | null;
91
+ presencePenalty?: number | null;
92
+ stopSequences?: string[] | null;
93
+ seed?: number | null;
94
+ inputCost?: number | null;
95
+ outputCost?: number | null;
96
+ inputMessages?: Array<{
97
+ role: string;
98
+ content?: string | any;
99
+ parts?: Array<{
100
+ type: string;
101
+ content: any;
102
+ }>;
103
+ }> | null;
104
+ outputMessages?: Array<{
105
+ role: string;
106
+ content?: string | any;
107
+ parts?: Array<{
108
+ type: string;
109
+ content: any;
110
+ }>;
111
+ finish_reason?: string;
112
+ }> | null;
113
+ systemInstructions?: Array<{
114
+ type: string;
115
+ content: string | any;
116
+ }> | null;
117
+ serverAddress?: string | null;
118
+ serverPort?: number | null;
119
+ conversationIdOtel?: string | null;
120
+ choiceCount?: number | null;
121
+ }): string;
122
+ /**
123
+ * Track a tool call with OTEL standardization
67
124
  */
68
125
  trackToolCall(options: {
69
126
  toolName: string;
@@ -72,9 +129,15 @@ declare class Observa {
72
129
  resultStatus: "success" | "error" | "timeout";
73
130
  latencyMs: number;
74
131
  errorMessage?: string;
132
+ operationName?: "execute_tool" | string | null;
133
+ toolType?: "function" | "extension" | "datastore" | string | null;
134
+ toolDescription?: string | null;
135
+ toolCallId?: string | null;
136
+ errorType?: string | null;
137
+ errorCategory?: string | null;
75
138
  }): string;
76
139
  /**
77
- * Track a retrieval operation
140
+ * Track a retrieval operation with vector metadata enrichment
78
141
  */
79
142
  trackRetrieval(options: {
80
143
  contextIds?: string[];
@@ -82,9 +145,17 @@ declare class Observa {
82
145
  k?: number;
83
146
  similarityScores?: number[];
84
147
  latencyMs: number;
148
+ retrievalContext?: string | null;
149
+ embeddingModel?: string | null;
150
+ embeddingDimensions?: number | null;
151
+ vectorMetric?: "cosine" | "euclidean" | "dot_product" | string | null;
152
+ rerankScore?: number | null;
153
+ fusionMethod?: string | null;
154
+ deduplicationRemovedCount?: number | null;
155
+ qualityScore?: number | null;
85
156
  }): string;
86
157
  /**
87
- * Track an error with stack trace support
158
+ * Track an error with structured error classification
88
159
  */
89
160
  trackError(options: {
90
161
  errorType: string;
@@ -92,6 +163,8 @@ declare class Observa {
92
163
  stackTrace?: string;
93
164
  context?: Record<string, any>;
94
165
  error?: Error;
166
+ errorCategory?: string | null;
167
+ errorCode?: string | null;
95
168
  }): string;
96
169
  /**
97
170
  * Track user feedback
@@ -119,6 +192,63 @@ declare class Observa {
119
192
  finalOutput?: string;
120
193
  outputLength?: number;
121
194
  }): string;
195
+ /**
196
+ * Track an embedding operation (TIER 1: Critical)
197
+ */
198
+ trackEmbedding(options: {
199
+ model: string;
200
+ dimensionCount?: number | null;
201
+ encodingFormats?: string[] | null;
202
+ inputTokens?: number | null;
203
+ outputTokens?: number | null;
204
+ latencyMs: number;
205
+ cost?: number | null;
206
+ inputText?: string | null;
207
+ inputHash?: string | null;
208
+ embeddings?: number[][] | null;
209
+ embeddingsHash?: string | null;
210
+ operationName?: "embeddings" | string | null;
211
+ providerName?: string | null;
212
+ }): string;
213
+ /**
214
+ * Track a vector database operation (TIER 3)
215
+ */
216
+ trackVectorDbOperation(options: {
217
+ operationType: "vector_search" | "index_upsert" | "delete" | string;
218
+ indexName?: string | null;
219
+ indexVersion?: string | null;
220
+ vectorDimensions?: number | null;
221
+ vectorMetric?: "cosine" | "euclidean" | "dot_product" | string | null;
222
+ resultsCount?: number | null;
223
+ scores?: number[] | null;
224
+ latencyMs: number;
225
+ cost?: number | null;
226
+ apiVersion?: string | null;
227
+ providerName?: string | null;
228
+ }): string;
229
+ /**
230
+ * Track a cache operation (TIER 3)
231
+ */
232
+ trackCacheOperation(options: {
233
+ cacheBackend?: "redis" | "in_memory" | "memcached" | string | null;
234
+ cacheKey?: string | null;
235
+ cacheNamespace?: string | null;
236
+ hitStatus: "hit" | "miss";
237
+ latencyMs: number;
238
+ savedCost?: number | null;
239
+ ttl?: number | null;
240
+ evictionInfo?: Record<string, any> | null;
241
+ }): string;
242
+ /**
243
+ * Track agent creation (TIER 3)
244
+ */
245
+ trackAgentCreate(options: {
246
+ agentName: string;
247
+ agentConfig?: Record<string, any> | null;
248
+ toolsBound?: string[] | null;
249
+ modelConfig?: Record<string, any> | null;
250
+ operationName?: "create_agent" | string | null;
251
+ }): string;
122
252
  /**
123
253
  * Execute a function within a span context (for nested operations)
124
254
  * This allows tool calls to be nested under LLM calls, etc.
@@ -150,6 +280,54 @@ declare class Observa {
150
280
  * Cleanup (call when shutting down)
151
281
  */
152
282
  end(): Promise<void>;
283
+ /**
284
+ * Observe OpenAI client - wraps client with automatic tracing
285
+ *
286
+ * @param client - OpenAI client instance
287
+ * @param options - Observation options (name, tags, userId, sessionId, redact)
288
+ * @returns Wrapped OpenAI client
289
+ *
290
+ * @example
291
+ * ```typescript
292
+ * import OpenAI from 'openai';
293
+ * const openai = new OpenAI({ apiKey: '...' });
294
+ * const wrapped = observa.observeOpenAI(openai, {
295
+ * name: 'my-app',
296
+ * redact: (data) => ({ ...data, messages: '[REDACTED]' })
297
+ * });
298
+ * ```
299
+ */
300
+ observeOpenAI(client: any, options?: {
301
+ name?: string;
302
+ tags?: string[];
303
+ userId?: string;
304
+ sessionId?: string;
305
+ redact?: (data: any) => any;
306
+ }): any;
307
+ /**
308
+ * Observe Anthropic client - wraps client with automatic tracing
309
+ *
310
+ * @param client - Anthropic client instance
311
+ * @param options - Observation options (name, tags, userId, sessionId, redact)
312
+ * @returns Wrapped Anthropic client
313
+ *
314
+ * @example
315
+ * ```typescript
316
+ * import Anthropic from '@anthropic-ai/sdk';
317
+ * const anthropic = new Anthropic({ apiKey: '...' });
318
+ * const wrapped = observa.observeAnthropic(anthropic, {
319
+ * name: 'my-app',
320
+ * redact: (data) => ({ ...data, messages: '[REDACTED]' })
321
+ * });
322
+ * ```
323
+ */
324
+ observeAnthropic(client: any, options?: {
325
+ name?: string;
326
+ tags?: string[];
327
+ userId?: string;
328
+ sessionId?: string;
329
+ redact?: (data: any) => any;
330
+ }): any;
153
331
  track(event: TrackEventInput, action: () => Promise<Response>, options?: {
154
332
  trackBlocking?: boolean;
155
333
  }): Promise<any>;
package/dist/index.d.ts CHANGED
@@ -63,7 +63,64 @@ declare class Observa {
63
63
  userId?: string;
64
64
  }): string;
65
65
  /**
66
- * Track a tool call
66
+ * Track an LLM call with full OTEL support
67
+ * CRITICAL: This is the primary method for tracking LLM calls with all SOTA parameters
68
+ */
69
+ trackLLMCall(options: {
70
+ model: string;
71
+ input?: string | null;
72
+ output?: string | null;
73
+ inputTokens?: number | null;
74
+ outputTokens?: number | null;
75
+ totalTokens?: number | null;
76
+ latencyMs: number;
77
+ timeToFirstTokenMs?: number | null;
78
+ streamingDurationMs?: number | null;
79
+ finishReason?: string | null;
80
+ responseId?: string | null;
81
+ systemFingerprint?: string | null;
82
+ cost?: number | null;
83
+ temperature?: number | null;
84
+ maxTokens?: number | null;
85
+ operationName?: "chat" | "text_completion" | "generate_content" | string | null;
86
+ providerName?: string | null;
87
+ responseModel?: string | null;
88
+ topK?: number | null;
89
+ topP?: number | null;
90
+ frequencyPenalty?: number | null;
91
+ presencePenalty?: number | null;
92
+ stopSequences?: string[] | null;
93
+ seed?: number | null;
94
+ inputCost?: number | null;
95
+ outputCost?: number | null;
96
+ inputMessages?: Array<{
97
+ role: string;
98
+ content?: string | any;
99
+ parts?: Array<{
100
+ type: string;
101
+ content: any;
102
+ }>;
103
+ }> | null;
104
+ outputMessages?: Array<{
105
+ role: string;
106
+ content?: string | any;
107
+ parts?: Array<{
108
+ type: string;
109
+ content: any;
110
+ }>;
111
+ finish_reason?: string;
112
+ }> | null;
113
+ systemInstructions?: Array<{
114
+ type: string;
115
+ content: string | any;
116
+ }> | null;
117
+ serverAddress?: string | null;
118
+ serverPort?: number | null;
119
+ conversationIdOtel?: string | null;
120
+ choiceCount?: number | null;
121
+ }): string;
122
+ /**
123
+ * Track a tool call with OTEL standardization
67
124
  */
68
125
  trackToolCall(options: {
69
126
  toolName: string;
@@ -72,9 +129,15 @@ declare class Observa {
72
129
  resultStatus: "success" | "error" | "timeout";
73
130
  latencyMs: number;
74
131
  errorMessage?: string;
132
+ operationName?: "execute_tool" | string | null;
133
+ toolType?: "function" | "extension" | "datastore" | string | null;
134
+ toolDescription?: string | null;
135
+ toolCallId?: string | null;
136
+ errorType?: string | null;
137
+ errorCategory?: string | null;
75
138
  }): string;
76
139
  /**
77
- * Track a retrieval operation
140
+ * Track a retrieval operation with vector metadata enrichment
78
141
  */
79
142
  trackRetrieval(options: {
80
143
  contextIds?: string[];
@@ -82,9 +145,17 @@ declare class Observa {
82
145
  k?: number;
83
146
  similarityScores?: number[];
84
147
  latencyMs: number;
148
+ retrievalContext?: string | null;
149
+ embeddingModel?: string | null;
150
+ embeddingDimensions?: number | null;
151
+ vectorMetric?: "cosine" | "euclidean" | "dot_product" | string | null;
152
+ rerankScore?: number | null;
153
+ fusionMethod?: string | null;
154
+ deduplicationRemovedCount?: number | null;
155
+ qualityScore?: number | null;
85
156
  }): string;
86
157
  /**
87
- * Track an error with stack trace support
158
+ * Track an error with structured error classification
88
159
  */
89
160
  trackError(options: {
90
161
  errorType: string;
@@ -92,6 +163,8 @@ declare class Observa {
92
163
  stackTrace?: string;
93
164
  context?: Record<string, any>;
94
165
  error?: Error;
166
+ errorCategory?: string | null;
167
+ errorCode?: string | null;
95
168
  }): string;
96
169
  /**
97
170
  * Track user feedback
@@ -119,6 +192,63 @@ declare class Observa {
119
192
  finalOutput?: string;
120
193
  outputLength?: number;
121
194
  }): string;
195
+ /**
196
+ * Track an embedding operation (TIER 1: Critical)
197
+ */
198
+ trackEmbedding(options: {
199
+ model: string;
200
+ dimensionCount?: number | null;
201
+ encodingFormats?: string[] | null;
202
+ inputTokens?: number | null;
203
+ outputTokens?: number | null;
204
+ latencyMs: number;
205
+ cost?: number | null;
206
+ inputText?: string | null;
207
+ inputHash?: string | null;
208
+ embeddings?: number[][] | null;
209
+ embeddingsHash?: string | null;
210
+ operationName?: "embeddings" | string | null;
211
+ providerName?: string | null;
212
+ }): string;
213
+ /**
214
+ * Track a vector database operation (TIER 3)
215
+ */
216
+ trackVectorDbOperation(options: {
217
+ operationType: "vector_search" | "index_upsert" | "delete" | string;
218
+ indexName?: string | null;
219
+ indexVersion?: string | null;
220
+ vectorDimensions?: number | null;
221
+ vectorMetric?: "cosine" | "euclidean" | "dot_product" | string | null;
222
+ resultsCount?: number | null;
223
+ scores?: number[] | null;
224
+ latencyMs: number;
225
+ cost?: number | null;
226
+ apiVersion?: string | null;
227
+ providerName?: string | null;
228
+ }): string;
229
+ /**
230
+ * Track a cache operation (TIER 3)
231
+ */
232
+ trackCacheOperation(options: {
233
+ cacheBackend?: "redis" | "in_memory" | "memcached" | string | null;
234
+ cacheKey?: string | null;
235
+ cacheNamespace?: string | null;
236
+ hitStatus: "hit" | "miss";
237
+ latencyMs: number;
238
+ savedCost?: number | null;
239
+ ttl?: number | null;
240
+ evictionInfo?: Record<string, any> | null;
241
+ }): string;
242
+ /**
243
+ * Track agent creation (TIER 3)
244
+ */
245
+ trackAgentCreate(options: {
246
+ agentName: string;
247
+ agentConfig?: Record<string, any> | null;
248
+ toolsBound?: string[] | null;
249
+ modelConfig?: Record<string, any> | null;
250
+ operationName?: "create_agent" | string | null;
251
+ }): string;
122
252
  /**
123
253
  * Execute a function within a span context (for nested operations)
124
254
  * This allows tool calls to be nested under LLM calls, etc.
@@ -150,6 +280,54 @@ declare class Observa {
150
280
  * Cleanup (call when shutting down)
151
281
  */
152
282
  end(): Promise<void>;
283
+ /**
284
+ * Observe OpenAI client - wraps client with automatic tracing
285
+ *
286
+ * @param client - OpenAI client instance
287
+ * @param options - Observation options (name, tags, userId, sessionId, redact)
288
+ * @returns Wrapped OpenAI client
289
+ *
290
+ * @example
291
+ * ```typescript
292
+ * import OpenAI from 'openai';
293
+ * const openai = new OpenAI({ apiKey: '...' });
294
+ * const wrapped = observa.observeOpenAI(openai, {
295
+ * name: 'my-app',
296
+ * redact: (data) => ({ ...data, messages: '[REDACTED]' })
297
+ * });
298
+ * ```
299
+ */
300
+ observeOpenAI(client: any, options?: {
301
+ name?: string;
302
+ tags?: string[];
303
+ userId?: string;
304
+ sessionId?: string;
305
+ redact?: (data: any) => any;
306
+ }): any;
307
+ /**
308
+ * Observe Anthropic client - wraps client with automatic tracing
309
+ *
310
+ * @param client - Anthropic client instance
311
+ * @param options - Observation options (name, tags, userId, sessionId, redact)
312
+ * @returns Wrapped Anthropic client
313
+ *
314
+ * @example
315
+ * ```typescript
316
+ * import Anthropic from '@anthropic-ai/sdk';
317
+ * const anthropic = new Anthropic({ apiKey: '...' });
318
+ * const wrapped = observa.observeAnthropic(anthropic, {
319
+ * name: 'my-app',
320
+ * redact: (data) => ({ ...data, messages: '[REDACTED]' })
321
+ * });
322
+ * ```
323
+ */
324
+ observeAnthropic(client: any, options?: {
325
+ name?: string;
326
+ tags?: string[];
327
+ userId?: string;
328
+ sessionId?: string;
329
+ redact?: (data: any) => any;
330
+ }): any;
153
331
  track(event: TrackEventInput, action: () => Promise<Response>, options?: {
154
332
  trackBlocking?: boolean;
155
333
  }): Promise<any>;