@cloudbase/agent-observability 1.0.1-alpha.16 → 1.0.1-alpha.18

package/dist/index.d.ts

@@ -45,6 +45,69 @@ type TokenUsage = {
     /** Total number of tokens */
     totalTokens?: number;
 };
+/**
+ * LLM message for input/output tracking.
+ *
+ * Follows OpenInference semantic convention:
+ * - llm.input_messages.{i}.message.role
+ * - llm.input_messages.{i}.message.content
+ * - llm.output_messages.{i}.message.role
+ * - llm.output_messages.{i}.message.content
+ *
+ * @public
+ */
+type LLMMessage = {
+    /** Message role (e.g., 'user', 'assistant', 'system', 'tool') */
+    role: string;
+    /** Message content */
+    content?: string;
+    /** Tool calls for assistant messages */
+    toolCalls?: ToolCall[];
+    /** Tool call ID for tool messages */
+    toolCallId?: string;
+};
+/**
+ * Tool call details.
+ *
+ * Follows OpenInference semantic convention:
+ * - tool_call.id
+ * - tool_call.function.name
+ * - tool_call.function.arguments
+ *
+ * @public
+ */
+type ToolCall = {
+    /** Tool call ID */
+    id: string;
+    /** Function name */
+    function: {
+        /** Function name */
+        name: string;
+        /** Function arguments as JSON string */
+        arguments: string;
+    };
+};
+/**
+ * Document for retrieval tracking.
+ *
+ * Follows OpenInference semantic convention:
+ * - retrieval.documents.{i}.document.id
+ * - retrieval.documents.{i}.document.content
+ * - retrieval.documents.{i}.document.score
+ * - retrieval.documents.{i}.document.metadata
+ *
+ * @public
+ */
+type Document = {
+    /** Document ID */
+    id?: string;
+    /** Document content */
+    content?: string;
+    /** Relevance score */
+    score?: number;
+    /** Document metadata */
+    metadata?: Record<string, unknown>;
+};
 /**
  * Base attributes for all observation types.
  *
@@ -69,13 +132,18 @@ type BaseSpanAttributes = {
     version?: string;
     /** Environment where the operation is running (e.g., 'production', 'staging') */
     environment?: string;
+    /** Allow additional custom attributes (e.g., http.*, agui.*) */
+    [key: string]: unknown;
 };
 /**
  * LLM-specific attributes following OpenInference semantic conventions.
  *
  * Uses attributes like:
  * - llm.model_name
- * - llm.parameters.*
+ * - llm.system
+ * - llm.provider
+ * - llm.input_messages
+ * - llm.output_messages
  * - llm.token_count.*
  * - llm.invocation_parameters
  *
@@ -86,10 +154,22 @@ type LLMAttributes = BaseSpanAttributes & {
     completionStartTime?: Date;
     /** Name of the language model (e.g., 'gpt-4', 'claude-3-opus') */
     model?: string;
+    /** AI system/vendor identifier (e.g., 'openai', 'anthropic') */
+    system?: string;
+    /** Hosting provider (e.g., 'openai', 'azure', 'aws') */
+    provider?: string;
     /** Parameters passed to the model (temperature, max_tokens, etc.) */
     modelParameters?: Record<string, string | number>;
     /** Token usage metrics */
     usageDetails?: TokenUsage | Record<string, number>;
+    /** Input messages for chat completions */
+    inputMessages?: LLMMessage[];
+    /** Output messages from the model */
+    outputMessages?: LLMMessage[];
+    /** MIME type of input (e.g., 'application/json') */
+    inputMimeType?: string;
+    /** MIME type of output (e.g., 'application/json') */
+    outputMimeType?: string;
 };
 /**
  * Embedding-specific attributes following OpenInference semantic conventions.
@@ -108,10 +188,22 @@ type EmbeddingAttributes = LLMAttributes;
  * - tool.name
  * - tool.description
  * - tool.parameters
+ * - tool_call.id
+ * - tool_call.function.name
+ * - tool_call.function.arguments
  *
  * @public
  */
-type ToolAttributes = BaseSpanAttributes;
+type ToolAttributes = BaseSpanAttributes & {
+    /** Tool name */
+    toolName?: string;
+    /** Tool description */
+    toolDescription?: string;
+    /** Tool parameters schema */
+    toolParameters?: Record<string, unknown>;
+    /** Tool call details */
+    toolCall?: ToolCall;
+};
 /**
  * Agent-specific attributes following OpenInference semantic conventions.
  *
@@ -121,7 +213,10 @@ type ToolAttributes = BaseSpanAttributes;
  *
  * @public
  */
-type AgentAttributes = BaseSpanAttributes;
+type AgentAttributes = BaseSpanAttributes & {
+    /** Agent name */
+    agentName?: string;
+};
 /**
  * Chain-specific attributes following OpenInference semantic conventions.
  *
@@ -138,11 +233,16 @@ type ChainAttributes = BaseSpanAttributes;
  * Uses attributes like:
  * - retriever.name
  * - retriever.query
- * - retriever.*
+ * - retrieval.documents
  *
  * @public
  */
-type RetrieverAttributes = BaseSpanAttributes;
+type RetrieverAttributes = BaseSpanAttributes & {
+    /** Retrieved documents */
+    documents?: Document[];
+    /** Query used for retrieval */
+    query?: string;
+};
 /**
  * Reranker-specific attributes following OpenInference semantic conventions.
  *
@@ -725,4 +825,4 @@ type ObserveOptions = Omit<StartObservationOpts, "name"> & {
  */
 declare function observe<T extends (...args: any[]) => any>(fn: T, options?: ObserveOptions): T;
 
-export { type AgentAttributes, type BaseSpanAttributes, type ChainAttributes, type EmbeddingAttributes, type EvaluatorAttributes, type GuardrailAttributes, type LLMAttributes, type Observation, ObservationAgent, type ObservationAttributes, ObservationChain, ObservationEmbedding, ObservationEvaluator, ObservationGuardrail, ObservationLLM, type ObservationLevel, ObservationReranker, ObservationRetriever, ObservationSpan, ObservationTool, type ObservationType, type ObserveOptions, type RerankerAttributes, type RetrieverAttributes, type StartActiveObservationOpts, type StartObservationOptions, type StartObservationOpts, type ToolAttributes, type TraceAttributes, createObservationAttributes, createTraceAttributes, getActiveSpanId, getActiveTraceId, getTracer, getTracerProvider, observe, setTracerProvider, startActiveObservation, startObservation, updateActiveObservation, updateActiveTrace };
+export { type AgentAttributes, type BaseSpanAttributes, type ChainAttributes, type Document, type EmbeddingAttributes, type EvaluatorAttributes, type GuardrailAttributes, type LLMAttributes, type LLMMessage, type Observation, ObservationAgent, type ObservationAttributes, ObservationChain, ObservationEmbedding, ObservationEvaluator, ObservationGuardrail, ObservationLLM, type ObservationLevel, ObservationReranker, ObservationRetriever, ObservationSpan, ObservationTool, type ObservationType, type ObserveOptions, type RerankerAttributes, type RetrieverAttributes, type StartActiveObservationOpts, type StartObservationOptions, type StartObservationOpts, type ToolAttributes, type ToolCall, type TraceAttributes, createObservationAttributes, createTraceAttributes, getActiveSpanId, getActiveTraceId, getTracer, getTracerProvider, observe, setTracerProvider, startActiveObservation, startObservation, updateActiveObservation, updateActiveTrace };

package/dist/index.js

@@ -125,6 +125,18 @@ function createObservationAttributes(type, attributes) {
     if (model) {
       otelAttributes[import_openinference_semantic_conventions2.SemanticConventions.LLM_MODEL_NAME] = model;
     }
+    const system = attributes?.system;
+    const provider = attributes?.provider;
+    const inputMessages = attributes?.inputMessages;
+    const outputMessages = attributes?.outputMessages;
+    const inputMimeType = attributes?.inputMimeType;
+    const outputMimeType = attributes?.outputMimeType;
+    if (system !== void 0) {
+      otelAttributes[import_openinference_semantic_conventions2.SemanticConventions.LLM_SYSTEM] = String(system);
+    }
+    if (provider !== void 0) {
+      otelAttributes[import_openinference_semantic_conventions2.SemanticConventions.LLM_PROVIDER] = String(provider);
+    }
     if (modelParameters) {
       otelAttributes[import_openinference_semantic_conventions2.SemanticConventions.LLM_INVOCATION_PARAMETERS] = _serialize(modelParameters);
       otelAttributes[OtelSpanAttributes.LLM_MODEL_PARAMETERS] = _serialize(modelParameters);
@@ -147,6 +159,20 @@ function createObservationAttributes(type, attributes) {
     if (completionStartTime) {
       otelAttributes[OtelSpanAttributes.LLM_COMPLETION_START_TIME] = _serialize(completionStartTime);
     }
+    if (inputMessages !== void 0 && Array.isArray(inputMessages)) {
+      const messageAttrs = _flattenLLMMessages(inputMessages, "llm.input_messages");
+      Object.assign(otelAttributes, messageAttrs);
+    }
+    if (outputMessages !== void 0 && Array.isArray(outputMessages)) {
+      const messageAttrs = _flattenLLMMessages(outputMessages, "llm.output_messages");
+      Object.assign(otelAttributes, messageAttrs);
+    }
+    if (inputMimeType !== void 0) {
+      otelAttributes[import_openinference_semantic_conventions2.SemanticConventions.INPUT_MIME_TYPE] = String(inputMimeType);
+    }
+    if (outputMimeType !== void 0) {
+      otelAttributes[import_openinference_semantic_conventions2.SemanticConventions.OUTPUT_MIME_TYPE] = String(outputMimeType);
+    }
   }
   if (type === "embedding") {
     if (model) {
@@ -156,6 +182,42 @@ function createObservationAttributes(type, attributes) {
       otelAttributes[import_openinference_semantic_conventions2.SemanticConventions.LLM_INVOCATION_PARAMETERS] = _serialize(modelParameters);
     }
   }
+  if (type === "tool") {
+    const toolName = attributes?.toolName ?? attributes?.tool_name;
+    const toolDescription = attributes?.toolDescription;
+    const toolParameters = attributes?.toolParameters;
+    const toolCall = attributes?.toolCall;
+    if (toolName !== void 0) {
+      otelAttributes[import_openinference_semantic_conventions2.SemanticConventions.TOOL_NAME] = String(toolName);
+    }
+    if (toolDescription !== void 0) {
+      otelAttributes[import_openinference_semantic_conventions2.SemanticConventions.TOOL_DESCRIPTION] = String(toolDescription);
+    }
+    if (toolParameters !== void 0) {
+      otelAttributes[import_openinference_semantic_conventions2.SemanticConventions.TOOL_PARAMETERS] = _serialize(toolParameters);
+    }
+    if (toolCall !== void 0 && typeof toolCall === "object") {
+      const toolCallAttrs = _flattenToolCall(toolCall);
+      Object.assign(otelAttributes, toolCallAttrs);
+    }
+  }
+  if (type === "agent") {
+    const agentName = attributes?.agentName;
+    if (agentName !== void 0) {
+      otelAttributes[import_openinference_semantic_conventions2.SemanticConventions.AGENT_NAME] = String(agentName);
+    }
+  }
+  if (type === "retriever") {
+    const documents = attributes?.documents;
+    const query = attributes?.query;
+    if (documents !== void 0 && Array.isArray(documents)) {
+      const docAttrs = _flattenDocuments(documents);
+      Object.assign(otelAttributes, docAttrs);
+    }
+    if (query !== void 0) {
+      otelAttributes["retriever.query"] = String(query);
+    }
+  }
   const metadataAttrs = _flattenAndSerializeMetadata(
     metadata,
     import_openinference_semantic_conventions2.SemanticConventions.METADATA
@@ -166,6 +228,11 @@ function createObservationAttributes(type, attributes) {
     OtelSpanAttributes.OBSERVATION_METADATA
   );
   Object.assign(otelAttributes, obsetvabilityMetadataAttrs);
+  for (const [key, value] of Object.entries(attributes)) {
+    if (!(key in otelAttributes) && value !== void 0 && value !== null) {
+      otelAttributes[key] = typeof value === "string" ? value : _serialize(value);
+    }
+  }
   return Object.fromEntries(
     Object.entries(otelAttributes).filter(([_, v]) => v != null)
   );
@@ -199,6 +266,96 @@ function _flattenAndSerializeMetadata(metadata, prefix) {
   }
   return metadataAttributes;
 }
+function _flattenLLMMessages(messages, prefix) {
+  const attributes = {};
+  if (!messages || !Array.isArray(messages)) {
+    return attributes;
+  }
+  try {
+    messages.forEach((msg, index) => {
+      if (!msg || typeof msg !== "object") return;
+      const baseKey = `${prefix}.${index}.message`;
+      if (msg.role !== void 0) {
+        attributes[`${baseKey}.role`] = String(msg.role);
+      }
+      if (msg.content !== void 0) {
+        attributes[`${baseKey}.content`] = String(msg.content);
+      }
+      if (msg.toolCallId !== void 0) {
+        attributes[`${baseKey}.tool_call_id`] = String(msg.toolCallId);
+      }
+      if (msg.toolCalls && Array.isArray(msg.toolCalls)) {
+        msg.toolCalls.forEach((toolCall, tcIndex) => {
+          if (!toolCall || typeof toolCall !== "object") return;
+          const tcKey = `${baseKey}.tool_calls.${tcIndex}`;
+          if (toolCall.id !== void 0) {
+            attributes[`${tcKey}.id`] = String(toolCall.id);
+          }
+          if (toolCall.function !== void 0) {
+            if (toolCall.function.name !== void 0) {
+              attributes[`${tcKey}.function.name`] = String(toolCall.function.name);
+            }
+            if (toolCall.function.arguments !== void 0) {
+              attributes[`${tcKey}.function.arguments`] = String(toolCall.function.arguments);
+            }
+          }
+        });
+      }
+    });
+  } catch (e) {
+  }
+  return attributes;
+}
+function _flattenDocuments(documents) {
+  const attributes = {};
+  if (!documents || !Array.isArray(documents)) {
+    return attributes;
+  }
+  try {
+    documents.forEach((doc, index) => {
+      if (!doc || typeof doc !== "object") return;
+      const baseKey = `retrieval.documents.${index}.document`;
+      if (doc.id !== void 0) {
+        attributes[`${baseKey}.id`] = String(doc.id);
+      }
+      if (doc.content !== void 0) {
+        attributes[`${baseKey}.content`] = String(doc.content);
+      }
+      if (doc.score !== void 0) {
+        attributes[`${baseKey}.score`] = String(doc.score);
+      }
+      if (doc.metadata !== void 0 && typeof doc.metadata === "object") {
+        const metadataSerialized = _serialize(doc.metadata);
+        if (metadataSerialized) {
+          attributes[`${baseKey}.metadata`] = metadataSerialized;
+        }
+      }
+    });
+  } catch (e) {
+  }
+  return attributes;
+}
+function _flattenToolCall(toolCall) {
+  const attributes = {};
+  if (!toolCall || typeof toolCall !== "object") {
+    return attributes;
+  }
+  try {
+    if (toolCall.id !== void 0) {
+      attributes["tool_call.id"] = String(toolCall.id);
+    }
+    if (toolCall.function !== void 0) {
+      if (toolCall.function.name !== void 0) {
+        attributes["tool_call.function.name"] = String(toolCall.function.name);
+      }
+      if (toolCall.function.arguments !== void 0) {
+        attributes["tool_call.function.arguments"] = String(toolCall.function.arguments);
+      }
+    }
+  } catch (e) {
+  }
+  return attributes;
+}
 var import_openinference_semantic_conventions2;
 var init_attributes = __esm({
   "src/core/attributes.ts"() {