observa-sdk 0.0.8 → 0.0.9

package/dist/index.d.ts

@@ -63,7 +63,64 @@ declare class Observa {
         userId?: string;
     }): string;
     /**
-     * Track a tool call
+     * Track an LLM call with full OTEL support
+     * CRITICAL: This is the primary method for tracking LLM calls with all SOTA parameters
+     */
+    trackLLMCall(options: {
+        model: string;
+        input?: string | null;
+        output?: string | null;
+        inputTokens?: number | null;
+        outputTokens?: number | null;
+        totalTokens?: number | null;
+        latencyMs: number;
+        timeToFirstTokenMs?: number | null;
+        streamingDurationMs?: number | null;
+        finishReason?: string | null;
+        responseId?: string | null;
+        systemFingerprint?: string | null;
+        cost?: number | null;
+        temperature?: number | null;
+        maxTokens?: number | null;
+        operationName?: "chat" | "text_completion" | "generate_content" | string | null;
+        providerName?: string | null;
+        responseModel?: string | null;
+        topK?: number | null;
+        topP?: number | null;
+        frequencyPenalty?: number | null;
+        presencePenalty?: number | null;
+        stopSequences?: string[] | null;
+        seed?: number | null;
+        inputCost?: number | null;
+        outputCost?: number | null;
+        inputMessages?: Array<{
+            role: string;
+            content?: string | any;
+            parts?: Array<{
+                type: string;
+                content: any;
+            }>;
+        }> | null;
+        outputMessages?: Array<{
+            role: string;
+            content?: string | any;
+            parts?: Array<{
+                type: string;
+                content: any;
+            }>;
+            finish_reason?: string;
+        }> | null;
+        systemInstructions?: Array<{
+            type: string;
+            content: string | any;
+        }> | null;
+        serverAddress?: string | null;
+        serverPort?: number | null;
+        conversationIdOtel?: string | null;
+        choiceCount?: number | null;
+    }): string;
+    /**
+     * Track a tool call with OTEL standardization
      */
     trackToolCall(options: {
         toolName: string;
@@ -72,9 +129,15 @@ declare class Observa {
         resultStatus: "success" | "error" | "timeout";
         latencyMs: number;
         errorMessage?: string;
+        operationName?: "execute_tool" | string | null;
+        toolType?: "function" | "extension" | "datastore" | string | null;
+        toolDescription?: string | null;
+        toolCallId?: string | null;
+        errorType?: string | null;
+        errorCategory?: string | null;
     }): string;
     /**
-     * Track a retrieval operation
+     * Track a retrieval operation with vector metadata enrichment
      */
     trackRetrieval(options: {
         contextIds?: string[];
@@ -82,9 +145,17 @@ declare class Observa {
         k?: number;
         similarityScores?: number[];
         latencyMs: number;
+        retrievalContext?: string | null;
+        embeddingModel?: string | null;
+        embeddingDimensions?: number | null;
+        vectorMetric?: "cosine" | "euclidean" | "dot_product" | string | null;
+        rerankScore?: number | null;
+        fusionMethod?: string | null;
+        deduplicationRemovedCount?: number | null;
+        qualityScore?: number | null;
     }): string;
     /**
-     * Track an error with stack trace support
+     * Track an error with structured error classification
      */
     trackError(options: {
         errorType: string;
@@ -92,6 +163,8 @@ declare class Observa {
         stackTrace?: string;
         context?: Record<string, any>;
         error?: Error;
+        errorCategory?: string | null;
+        errorCode?: string | null;
     }): string;
     /**
      * Track user feedback
@@ -119,6 +192,63 @@ declare class Observa {
         finalOutput?: string;
         outputLength?: number;
     }): string;
+    /**
+     * Track an embedding operation (TIER 1: Critical)
+     */
+    trackEmbedding(options: {
+        model: string;
+        dimensionCount?: number | null;
+        encodingFormats?: string[] | null;
+        inputTokens?: number | null;
+        outputTokens?: number | null;
+        latencyMs: number;
+        cost?: number | null;
+        inputText?: string | null;
+        inputHash?: string | null;
+        embeddings?: number[][] | null;
+        embeddingsHash?: string | null;
+        operationName?: "embeddings" | string | null;
+        providerName?: string | null;
+    }): string;
+    /**
+     * Track a vector database operation (TIER 3)
+     */
+    trackVectorDbOperation(options: {
+        operationType: "vector_search" | "index_upsert" | "delete" | string;
+        indexName?: string | null;
+        indexVersion?: string | null;
+        vectorDimensions?: number | null;
+        vectorMetric?: "cosine" | "euclidean" | "dot_product" | string | null;
+        resultsCount?: number | null;
+        scores?: number[] | null;
+        latencyMs: number;
+        cost?: number | null;
+        apiVersion?: string | null;
+        providerName?: string | null;
+    }): string;
+    /**
+     * Track a cache operation (TIER 3)
+     */
+    trackCacheOperation(options: {
+        cacheBackend?: "redis" | "in_memory" | "memcached" | string | null;
+        cacheKey?: string | null;
+        cacheNamespace?: string | null;
+        hitStatus: "hit" | "miss";
+        latencyMs: number;
+        savedCost?: number | null;
+        ttl?: number | null;
+        evictionInfo?: Record<string, any> | null;
+    }): string;
+    /**
+     * Track agent creation (TIER 3)
+     */
+    trackAgentCreate(options: {
+        agentName: string;
+        agentConfig?: Record<string, any> | null;
+        toolsBound?: string[] | null;
+        modelConfig?: Record<string, any> | null;
+        operationName?: "create_agent" | string | null;
+    }): string;
     /**
      * Execute a function within a span context (for nested operations)
      * This allows tool calls to be nested under LLM calls, etc.
@@ -150,6 +280,54 @@ declare class Observa {
      * Cleanup (call when shutting down)
      */
     end(): Promise<void>;
+    /**
+     * Observe OpenAI client - wraps client with automatic tracing
+     *
+     * @param client - OpenAI client instance
+     * @param options - Observation options (name, tags, userId, sessionId, redact)
+     * @returns Wrapped OpenAI client
+     *
+     * @example
+     * ```typescript
+     * import OpenAI from 'openai';
+     * const openai = new OpenAI({ apiKey: '...' });
+     * const wrapped = observa.observeOpenAI(openai, {
+     *   name: 'my-app',
+     *   redact: (data) => ({ ...data, messages: '[REDACTED]' })
+     * });
+     * ```
+     */
+    observeOpenAI(client: any, options?: {
+        name?: string;
+        tags?: string[];
+        userId?: string;
+        sessionId?: string;
+        redact?: (data: any) => any;
+    }): any;
+    /**
+     * Observe Anthropic client - wraps client with automatic tracing
+     *
+     * @param client - Anthropic client instance
+     * @param options - Observation options (name, tags, userId, sessionId, redact)
+     * @returns Wrapped Anthropic client
+     *
+     * @example
+     * ```typescript
+     * import Anthropic from '@anthropic-ai/sdk';
+     * const anthropic = new Anthropic({ apiKey: '...' });
+     * const wrapped = observa.observeAnthropic(anthropic, {
+     *   name: 'my-app',
+     *   redact: (data) => ({ ...data, messages: '[REDACTED]' })
+     * });
+     * ```
+     */
+    observeAnthropic(client: any, options?: {
+        name?: string;
+        tags?: string[];
+        userId?: string;
+        sessionId?: string;
+        redact?: (data: any) => any;
+    }): any;
     track(event: TrackEventInput, action: () => Promise<Response>, options?: {
         trackBlocking?: boolean;
     }): Promise<any>;

package/dist/index.js

@@ -383,7 +383,78 @@ var Observa = class {
     return this.currentTraceId;
   }
   /**
-   * Track a tool call
+   * Track an LLM call with full OTEL support
+   * CRITICAL: This is the primary method for tracking LLM calls with all SOTA parameters
+   */
+  trackLLMCall(options) {
+    const spanId = crypto.randomUUID();
+    let providerName = options.providerName;
+    if (!providerName && options.model) {
+      const modelLower = options.model.toLowerCase();
+      if (modelLower.includes("gpt") || modelLower.includes("openai")) {
+        providerName = "openai";
+      } else if (modelLower.includes("claude") || modelLower.includes("anthropic")) {
+        providerName = "anthropic";
+      } else if (modelLower.includes("gemini") || modelLower.includes("google")) {
+        providerName = "google";
+      } else if (modelLower.includes("vertex")) {
+        providerName = "gcp.vertex_ai";
+      } else if (modelLower.includes("bedrock") || modelLower.includes("aws")) {
+        providerName = "aws.bedrock";
+      }
+    }
+    const operationName = options.operationName || "chat";
+    this.addEvent({
+      event_type: "llm_call",
+      span_id: spanId,
+      attributes: {
+        llm_call: {
+          model: options.model,
+          input: options.input || null,
+          output: options.output || null,
+          input_tokens: options.inputTokens || null,
+          output_tokens: options.outputTokens || null,
+          total_tokens: options.totalTokens || null,
+          latency_ms: options.latencyMs,
+          time_to_first_token_ms: options.timeToFirstTokenMs || null,
+          streaming_duration_ms: options.streamingDurationMs || null,
+          finish_reason: options.finishReason || null,
+          response_id: options.responseId || null,
+          system_fingerprint: options.systemFingerprint || null,
+          cost: options.cost || null,
+          temperature: options.temperature || null,
+          max_tokens: options.maxTokens || null,
+          // TIER 1: OTEL Semantic Conventions
+          operation_name: operationName,
+          provider_name: providerName || null,
+          response_model: options.responseModel || null,
+          // TIER 2: Sampling parameters
+          top_k: options.topK || null,
+          top_p: options.topP || null,
+          frequency_penalty: options.frequencyPenalty || null,
+          presence_penalty: options.presencePenalty || null,
+          stop_sequences: options.stopSequences || null,
+          seed: options.seed || null,
+          // TIER 2: Structured cost tracking
+          input_cost: options.inputCost || null,
+          output_cost: options.outputCost || null,
+          // TIER 1: Structured message objects
+          input_messages: options.inputMessages || null,
+          output_messages: options.outputMessages || null,
+          system_instructions: options.systemInstructions || null,
+          // TIER 2: Server metadata
+          server_address: options.serverAddress || null,
+          server_port: options.serverPort || null,
+          // TIER 2: Conversation grouping
+          conversation_id_otel: options.conversationIdOtel || null,
+          choice_count: options.choiceCount || null
+        }
+      }
+    });
+    return spanId;
+  }
+  /**
+   * Track a tool call with OTEL standardization
    */
   trackToolCall(options) {
     const spanId = crypto.randomUUID();
@@ -397,14 +468,21 @@ var Observa = class {
           result: options.result || null,
           result_status: options.resultStatus,
           latency_ms: options.latencyMs,
-          error_message: options.errorMessage || null
+          error_message: options.errorMessage || null,
+          // TIER 2: OTEL Tool Standardization
+          operation_name: options.operationName || "execute_tool",
+          tool_type: options.toolType || null,
+          tool_description: options.toolDescription || null,
+          tool_call_id: options.toolCallId || null,
+          error_type: options.errorType || null,
+          error_category: options.errorCategory || null
         }
       }
     });
     return spanId;
   }
   /**
-   * Track a retrieval operation
+   * Track a retrieval operation with vector metadata enrichment
    */
   trackRetrieval(options) {
     const spanId = crypto.randomUUID();
@@ -418,14 +496,23 @@ var Observa = class {
           k: options.k || null,
           top_k: options.k || null,
           similarity_scores: options.similarityScores || null,
-          latency_ms: options.latencyMs
+          latency_ms: options.latencyMs,
+          // TIER 2: Retrieval enrichment
+          retrieval_context: options.retrievalContext || null,
+          embedding_model: options.embeddingModel || null,
+          embedding_dimensions: options.embeddingDimensions || null,
+          vector_metric: options.vectorMetric || null,
+          rerank_score: options.rerankScore || null,
+          fusion_method: options.fusionMethod || null,
+          deduplication_removed_count: options.deduplicationRemovedCount || null,
+          quality_score: options.qualityScore || null
         }
       }
     });
     return spanId;
   }
   /**
-   * Track an error with stack trace support
+   * Track an error with structured error classification
    */
   trackError(options) {
     const spanId = crypto.randomUUID();
@@ -441,7 +528,10 @@ var Observa = class {
           error_type: options.errorType,
           error_message: options.errorMessage,
           stack_trace: stackTrace || null,
-          context: options.context || null
+          context: options.context || null,
+          // TIER 2: Structured error classification
+          error_category: options.errorCategory || null,
+          error_code: options.errorCode || null
         }
       }
     });
@@ -495,6 +585,114 @@ var Observa = class {
     });
     return spanId;
   }
+  /**
+   * Track an embedding operation (TIER 1: Critical)
+   */
+  trackEmbedding(options) {
+    const spanId = crypto.randomUUID();
+    let providerName = options.providerName;
+    if (!providerName && options.model) {
+      const modelLower = options.model.toLowerCase();
+      if (modelLower.includes("text-embedding") || modelLower.includes("openai")) {
+        providerName = "openai";
+      } else if (modelLower.includes("textembedding") || modelLower.includes("google")) {
+        providerName = "google";
+      } else if (modelLower.includes("vertex")) {
+        providerName = "gcp.vertex_ai";
+      }
+    }
+    this.addEvent({
+      event_type: "embedding",
+      span_id: spanId,
+      attributes: {
+        embedding: {
+          model: options.model,
+          dimension_count: options.dimensionCount || null,
+          encoding_formats: options.encodingFormats || null,
+          input_tokens: options.inputTokens || null,
+          output_tokens: options.outputTokens || null,
+          latency_ms: options.latencyMs,
+          cost: options.cost || null,
+          input_text: options.inputText || null,
+          input_hash: options.inputHash || null,
+          embeddings: options.embeddings || null,
+          embeddings_hash: options.embeddingsHash || null,
+          operation_name: options.operationName || "embeddings",
+          provider_name: providerName || null
+        }
+      }
+    });
+    return spanId;
+  }
+  /**
+   * Track a vector database operation (TIER 3)
+   */
+  trackVectorDbOperation(options) {
+    const spanId = crypto.randomUUID();
+    this.addEvent({
+      event_type: "vector_db_operation",
+      span_id: spanId,
+      attributes: {
+        vector_db_operation: {
+          operation_type: options.operationType,
+          index_name: options.indexName || null,
+          index_version: options.indexVersion || null,
+          vector_dimensions: options.vectorDimensions || null,
+          vector_metric: options.vectorMetric || null,
+          results_count: options.resultsCount || null,
+          scores: options.scores || null,
+          latency_ms: options.latencyMs,
+          cost: options.cost || null,
+          api_version: options.apiVersion || null,
+          provider_name: options.providerName || null
+        }
+      }
+    });
+    return spanId;
+  }
+  /**
+   * Track a cache operation (TIER 3)
+   */
+  trackCacheOperation(options) {
+    const spanId = crypto.randomUUID();
+    this.addEvent({
+      event_type: "cache_operation",
+      span_id: spanId,
+      attributes: {
+        cache_operation: {
+          cache_backend: options.cacheBackend || null,
+          cache_key: options.cacheKey || null,
+          cache_namespace: options.cacheNamespace || null,
+          hit_status: options.hitStatus,
+          latency_ms: options.latencyMs,
+          saved_cost: options.savedCost || null,
+          ttl: options.ttl || null,
+          eviction_info: options.evictionInfo || null
+        }
+      }
+    });
+    return spanId;
+  }
+  /**
+   * Track agent creation (TIER 3)
+   */
+  trackAgentCreate(options) {
+    const spanId = crypto.randomUUID();
+    this.addEvent({
+      event_type: "agent_create",
+      span_id: spanId,
+      attributes: {
+        agent_create: {
+          agent_name: options.agentName,
+          agent_config: options.agentConfig || null,
+          tools_bound: options.toolsBound || null,
+          model_config: options.modelConfig || null,
+          operation_name: options.operationName || "create_agent"
+        }
+      }
+    });
+    return spanId;
+  }
   /**
    * Execute a function within a span context (for nested operations)
    * This allows tool calls to be nested under LLM calls, etc.
@@ -595,6 +793,21 @@ var Observa = class {
     });
     if (trace.model) {
       const llmSpanId = crypto.randomUUID();
+      let providerName = null;
+      if (trace.model) {
+        const modelLower = trace.model.toLowerCase();
+        if (modelLower.includes("gpt") || modelLower.includes("openai")) {
+          providerName = "openai";
+        } else if (modelLower.includes("claude") || modelLower.includes("anthropic")) {
+          providerName = "anthropic";
+        } else if (modelLower.includes("gemini") || modelLower.includes("google")) {
+          providerName = "google";
+        } else if (modelLower.includes("vertex")) {
+          providerName = "gcp.vertex_ai";
+        } else if (modelLower.includes("bedrock") || modelLower.includes("aws")) {
+          providerName = "aws.bedrock";
+        }
+      }
       events.push({
         ...baseEvent,
         span_id: llmSpanId,
@@ -615,8 +828,13 @@ var Observa = class {
             finish_reason: trace.finishReason || null,
             response_id: trace.responseId || null,
             system_fingerprint: trace.systemFingerprint || null,
-            cost: null
+            cost: null,
             // Cost calculation handled by backend
+            // TIER 1: OTEL Semantic Conventions (auto-inferred)
+            operation_name: "chat",
+            // Default for legacy track() method
+            provider_name: providerName
+            // Other OTEL fields can be added via trackLLMCall() method
           }
         }
       });
@@ -708,6 +926,64 @@ var Observa = class {
     }
     await this.flush();
   }
+  /**
+   * Observe OpenAI client - wraps client with automatic tracing
+   * 
+   * @param client - OpenAI client instance
+   * @param options - Observation options (name, tags, userId, sessionId, redact)
+   * @returns Wrapped OpenAI client
+   * 
+   * @example
+   * ```typescript
+   * import OpenAI from 'openai';
+   * const openai = new OpenAI({ apiKey: '...' });
+   * const wrapped = observa.observeOpenAI(openai, {
+   *   name: 'my-app',
+   *   redact: (data) => ({ ...data, messages: '[REDACTED]' })
+   * });
+   * ```
+   */
+  observeOpenAI(client, options) {
+    try {
+      const requireFn = globalThis.require || ((module) => {
+        throw new Error("require is not available");
+      });
+      const { observeOpenAI: observeOpenAIFn } = requireFn("./instrumentation/openai");
+      return observeOpenAIFn(client, { ...options, observa: this });
+    } catch (error) {
+      console.error("[Observa] Failed to load OpenAI wrapper:", error);
+      return client;
+    }
+  }
+  /**
+   * Observe Anthropic client - wraps client with automatic tracing
+   * 
+   * @param client - Anthropic client instance
+   * @param options - Observation options (name, tags, userId, sessionId, redact)
+   * @returns Wrapped Anthropic client
+   * 
+   * @example
+   * ```typescript
+   * import Anthropic from '@anthropic-ai/sdk';
+   * const anthropic = new Anthropic({ apiKey: '...' });
+   * const wrapped = observa.observeAnthropic(anthropic, {
+   *   name: 'my-app',
+   *   redact: (data) => ({ ...data, messages: '[REDACTED]' })
+   * });
+   * ```
+   */
+  observeAnthropic(client, options) {
+    try {
+      const requireFn = globalThis.require || ((module) => {
+        throw new Error("require is not available");
+      });
+      const { observeAnthropic: observeAnthropicFn } = requireFn("./instrumentation/anthropic");
+      return observeAnthropicFn(client, { ...options, observa: this });
+    } catch (error) {
+      console.error("[Observa] Failed to load Anthropic wrapper:", error);
+      return client;
+    }
+  }
   async track(event, action, options) {
     if (this.sampleRate < 1 && Math.random() > this.sampleRate) {
       return action();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "observa-sdk",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "description": "Enterprise-grade observability SDK for AI applications. Track and monitor LLM interactions with zero friction.",
   "type": "module",
   "main": "./dist/index.cjs",