@cloudbase/agent-observability 1.0.1-alpha.9

package/src/types.ts

@@ -0,0 +1,254 @@
+/**
+ * Types of observations (spans) supported by AG-Kit observability.
+ *
+ * These types align with OpenInference semantic conventions:
+ * https://github.com/Arize-ai/openinference/tree/main/spec
+ *
+ * - `span`: General-purpose operations (OpenInference: internal/span)
+ * - `llm`: Language model calls (OpenInference: LLM)
+ * - `embedding`: Text embedding operations (OpenInference: EMBEDDING)
+ * - `agent`: AI agent workflows (OpenInference: AGENT)
+ * - `tool`: Tool/function calls (OpenInference: TOOL)
+ * - `chain`: Multi-step workflows (OpenInference: CHAIN)
+ * - `retriever`: Document retrieval (OpenInference: RETRIEVER)
+ * - `reranker`: Result reranking (OpenInference: RERANKER)
+ * - `guardrail`: Safety checks (OpenInference: GUARDRAIL)
+ * - `evaluator`: Quality assessment (OpenInference: EVALUATOR)
+ *
+ * @public
+ */
+export type ObservationType =
+  | "span"
+  | "llm"
+  | "embedding"
+  | "agent"
+  | "tool"
+  | "chain"
+  | "retriever"
+  | "reranker"
+  | "guardrail"
+  | "evaluator";
+
+/**
+ * Severity levels for observations.
+ *
+ * @public
+ */
+export type ObservationLevel = "DEBUG" | "DEFAULT" | "WARNING" | "ERROR";
+
+/**
+ * Token usage details for LLM calls.
+ *
+ * Follows OpenInference semantic convention:
+ * - llm.token_count.prompt
+ * - llm.token_count.completion
+ * - llm.token_count.total
+ *
+ * @public
+ */
+export type TokenUsage = {
+  /** Number of tokens in the prompt */
+  promptTokens?: number;
+  /** Number of tokens in the completion */
+  completionTokens?: number;
+  /** Total number of tokens */
+  totalTokens?: number;
+};
+
+/**
+ * Base attributes for all observation types.
+ *
+ * Uses OpenInference semantic conventions where applicable:
+ * - input.value: Input data
+ * - output.value: Output data
+ *
+ * @public
+ */
+export type BaseSpanAttributes = {
+  /** Input data for the operation */
+  input?: unknown;
+  /** Output data from the operation */
+  output?: unknown;
+  /** Additional metadata as key-value pairs */
+  metadata?: Record<string, unknown>;
+  /** Severity level of the observation */
+  level?: ObservationLevel;
+  /** Human-readable status message */
+  statusMessage?: string;
+  /** Version identifier for the code/model being tracked */
+  version?: string;
+  /** Environment where the operation is running (e.g., 'production', 'staging') */
+  environment?: string;
+};
+
+/**
+ * LLM-specific attributes following OpenInference semantic conventions.
+ *
+ * Uses attributes like:
+ * - llm.model_name
+ * - llm.parameters.*
+ * - llm.token_count.*
+ * - llm.invocation_parameters
+ *
+ * @public
+ */
+export type LLMAttributes = BaseSpanAttributes & {
+  /** Timestamp when the model started generating completion */
+  completionStartTime?: Date;
+  /** Name of the language model (e.g., 'gpt-4', 'claude-3-opus') */
+  model?: string;
+  /** Parameters passed to the model (temperature, max_tokens, etc.) */
+  modelParameters?: Record<string, string | number>;
+  /** Token usage metrics */
+  usageDetails?: TokenUsage | Record<string, number>;
+};
+
+/**
+ * Embedding-specific attributes following OpenInference semantic conventions.
+ *
+ * Uses attributes like:
+ * - embedding.model_name
+ * - embedding.embeddings.*
+ *
+ * @public
+ */
+export type EmbeddingAttributes = LLMAttributes;
+
+/**
+ * Tool-specific attributes following OpenInference semantic conventions.
+ *
+ * Uses attributes like:
+ * - tool.name
+ * - tool.description
+ * - tool.parameters
+ *
+ * @public
+ */
+export type ToolAttributes = BaseSpanAttributes;
+
+/**
+ * Agent-specific attributes following OpenInference semantic conventions.
+ *
+ * Uses attributes like:
+ * - agent.name
+ * - agent.* (various agent-specific metadata)
+ *
+ * @public
+ */
+export type AgentAttributes = BaseSpanAttributes;
+
+/**
+ * Chain-specific attributes following OpenInference semantic conventions.
+ *
+ * Uses attributes like:
+ * - chain.name
+ * - chain.* (various chain-specific metadata)
+ *
+ * @public
+ */
+export type ChainAttributes = BaseSpanAttributes;
+
+/**
+ * Retriever-specific attributes following OpenInference semantic conventions.
+ *
+ * Uses attributes like:
+ * - retriever.name
+ * - retriever.query
+ * - retriever.*
+ *
+ * @public
+ */
+export type RetrieverAttributes = BaseSpanAttributes;
+
+/**
+ * Reranker-specific attributes following OpenInference semantic conventions.
+ *
+ * Uses attributes like:
+ * - reranker.model_name
+ * - reranker.top_k
+ * - reranker.*
+ *
+ * @public
+ */
+export type RerankerAttributes = BaseSpanAttributes;
+
+/**
+ * Evaluator-specific attributes.
+ *
+ * @public
+ */
+export type EvaluatorAttributes = BaseSpanAttributes;
+
+/**
+ * Guardrail-specific attributes following OpenInference semantic conventions.
+ *
+ * Uses attributes like:
+ * - guardrail.name
+ * - guardrail.*
+ *
+ * @public
+ */
+export type GuardrailAttributes = BaseSpanAttributes;
+
+/**
+ * Union type for all observation attributes.
+ *
+ * @public
+ */
+export type ObservationAttributes =
+  & BaseSpanAttributes
+  & LLMAttributes
+  & ToolAttributes
+  & AgentAttributes
+  & ChainAttributes
+  & RetrieverAttributes
+  & RerankerAttributes
+  & EvaluatorAttributes
+  & GuardrailAttributes;
+
+/**
+ * Attributes for traces.
+ *
+ * Traces are the top-level containers that group related observations together.
+ * Uses OpenInference semantic conventions where applicable.
+ *
+ * @public
+ */
+export type TraceAttributes = {
+  /** Human-readable name for the trace */
+  name?: string;
+  /** Identifier for the user associated with this trace */
+  userId?: string;
+  /** Session identifier for grouping related traces */
+  sessionId?: string;
+  /** Version identifier for the code/application */
+  version?: string;
+  /** Release identifier for deployment tracking */
+  release?: string;
+  /** Input data that initiated the trace */
+  input?: unknown;
+  /** Final output data from the trace */
+  output?: unknown;
+  /** Additional metadata for the trace */
+  metadata?: unknown;
+  /** Tags for categorizing and filtering traces */
+  tags?: string[];
+  /** Whether this trace should be publicly visible */
+  public?: boolean;
+  /** Environment where the trace was captured */
+  environment?: string;
+};
+
+/**
+ * Context information for linking observations to traces.
+ *
+ * Used internally for maintaining parent-child relationships between observations.
+ *
+ * @public
+ */
+export type TraceContext = {
+  /** The trace ID that observations should be linked to */
+  traceId: string;
+  /** Optional parent observation ID for creating hierarchical relationships */
+  parentObservationId?: string;
+};