@illuma-ai/observability-core 0.1.0 → 0.2.0

package/dist/types.d.ts

@@ -2,7 +2,8 @@
  * Core types for the Illuma Observability SDK.
  *
  * This module is the single source of truth for all observability types.
- * It mirrors the Langfuse ingestion API contract so payloads are wire-compatible.
+ * It mirrors the Langfuse ingestion API contract so payloads are wire-compatible,
+ * and incorporates best patterns from Opik for comprehensive LLM observability.
  */
 /** Observation severity / log level. */
 export declare enum ObservationLevel {
@@ -11,9 +12,39 @@ export declare enum ObservationLevel {
     WARNING = "WARNING",
     ERROR = "ERROR"
 }
+/**
+ * Observation type discriminator.
+ * Matches the server's accepted types for rich categorization of spans.
+ */
+export declare enum ObservationType {
+    /** Generic span (default). */
+    SPAN = "SPAN",
+    /** LLM generation / completion call. */
+    GENERATION = "GENERATION",
+    /** Point-in-time event (no duration). */
+    EVENT = "EVENT",
+    /** Autonomous agent execution. */
+    AGENT = "AGENT",
+    /** Tool / function invocation. */
+    TOOL = "TOOL",
+    /** Chain execution (sequential pipeline). */
+    CHAIN = "CHAIN",
+    /** Retriever / vector search operation. */
+    RETRIEVER = "RETRIEVER",
+    /** Evaluator execution. */
+    EVALUATOR = "EVALUATOR",
+    /** Embedding operation. */
+    EMBEDDING = "EMBEDDING",
+    /** Guardrail / safety check. */
+    GUARDRAIL = "GUARDRAIL"
+}
+/** Score data type discriminator. */
+export type ScoreDataType = 'NUMERIC' | 'BOOLEAN' | 'CATEGORICAL' | 'CORRECTION';
+/** Score source — how the score was produced. */
+export type ScoreSource = 'API' | 'EVAL' | 'ANNOTATION';
 /**
  * Ingestion event type constants.
- * These match the Langfuse API exactly so the server can process them
+ * These match the server's accepted event types so payloads are processed
  * without any translation layer.
  */
 export declare const IngestionEventType: {
@@ -23,7 +54,15 @@ export declare const IngestionEventType: {
     readonly GENERATION_CREATE: "generation-create";
     readonly GENERATION_UPDATE: "generation-update";
     readonly EVENT_CREATE: "event-create";
+    readonly AGENT_CREATE: "agent-create";
+    readonly TOOL_CREATE: "tool-create";
+    readonly CHAIN_CREATE: "chain-create";
+    readonly RETRIEVER_CREATE: "retriever-create";
+    readonly EVALUATOR_CREATE: "evaluator-create";
+    readonly EMBEDDING_CREATE: "embedding-create";
+    readonly GUARDRAIL_CREATE: "guardrail-create";
     readonly SCORE_CREATE: "score-create";
+    readonly DATASET_RUN_ITEM_CREATE: "dataset-run-item-create";
     readonly SDK_LOG: "sdk-log";
 };
 export type IngestionEventType = (typeof IngestionEventType)[keyof typeof IngestionEventType];
@@ -65,6 +104,12 @@ export interface ObservabilityClientConfig {
      * Helps correlate traces with deployments.
      */
     release?: string;
+    /**
+     * Environment name (e.g. "production", "staging", "development").
+     * Attached to all traces and observations for filtering.
+     * @default "default"
+     */
+    environment?: string;
     /**
      * Per-request timeout in milliseconds for flush HTTP calls.
      * @default 10000
@@ -96,6 +141,15 @@ export interface UsageParams {
  * { "cachedTokens": 200, "audioTokens": 50 }
  */
 export type UsageDetailsParams = Record<string, number>;
+/** Structured error information (from Opik). */
+export interface ErrorInfo {
+    /** Exception class / type name. */
+    exceptionType: string;
+    /** Human-readable error message. */
+    message?: string;
+    /** Full stack trace / traceback. */
+    traceback: string;
+}
 /** Parameters for creating or updating a trace. */
 export interface TraceParams {
     /** Client-generated trace ID. Auto-generated if omitted. */
@@ -120,6 +174,16 @@ export interface TraceParams {
     version?: string;
     /** ISO-8601 timestamp. Defaults to now. */
     timestamp?: string;
+    /** Deployment release identifier (e.g. git SHA, semver). */
+    release?: string;
+    /** Environment name (e.g. "production", "staging"). Overrides client-level setting. */
+    environment?: string;
+    /** External system ID for correlation. */
+    externalId?: string;
+    /** Thread/conversation ID for grouping multi-turn interactions. */
+    threadId?: string;
+    /** Structured error information if the trace represents a failure. */
+    errorInfo?: ErrorInfo;
 }
 /** Parameters for creating or updating an LLM generation observation. */
 export interface GenerationParams {
@@ -137,8 +201,10 @@ export interface GenerationParams {
     endTime?: string;
     /** ISO-8601 time of first token received (streaming). */
     completionStartTime?: string;
-    /** Model identifier, e.g. "gpt-4o", "claude-3-opus". */
+    /** Model identifier, e.g. "gpt-4o", "claude-sonnet-4-20250514". */
     model?: string;
+    /** LLM provider name (e.g. "openai", "anthropic", "aws_bedrock", "google"). */
+    provider?: string;
     /** Model parameters (temperature, max_tokens, etc.). */
     modelParameters?: Record<string, unknown>;
     /** Prompt / messages sent to the model. */
@@ -147,8 +213,10 @@ export interface GenerationParams {
     output?: unknown;
     /** Token / cost usage. */
     usage?: UsageParams;
-    /** Extended usage details for non-standard billing. */
+    /** Extended usage details for non-standard billing (e.g. cached_tokens, reasoning_tokens). */
     usageDetails?: UsageDetailsParams;
+    /** Per-usage-type cost breakdown (e.g. { input: 0.015, output: 0.012 }). */
+    costDetails?: Record<string, number>;
     /** Arbitrary metadata. */
     metadata?: Record<string, unknown>;
     /** Observation severity level. */
@@ -157,10 +225,14 @@ export interface GenerationParams {
     statusMessage?: string;
     /** Application version override. */
     version?: string;
+    /** Environment override. */
+    environment?: string;
     /** Reference to a prompt template ID managed in the UI. */
     promptName?: string;
     /** Version of the prompt template. */
     promptVersion?: number;
+    /** Structured error information. */
+    errorInfo?: ErrorInfo;
 }
 /** Parameters for creating or updating a span observation. */
 export interface SpanParams {
@@ -188,6 +260,18 @@ export interface SpanParams {
     statusMessage?: string;
     /** Application version override. */
     version?: string;
+    /** Environment override. */
+    environment?: string;
+    /** Observation type for categorization (TOOL, AGENT, CHAIN, RETRIEVER, etc.). */
+    type?: ObservationType;
+    /** Model name (when a span wraps an LLM call). */
+    model?: string;
+    /** Provider name (when a span wraps an LLM call). */
+    provider?: string;
+    /** Token/cost usage (when a span wraps an LLM call). */
+    usage?: UsageParams;
+    /** Structured error information. */
+    errorInfo?: ErrorInfo;
 }
 /** Parameters for creating an event observation (no duration). */
 export interface EventParams {
@@ -213,6 +297,8 @@ export interface EventParams {
     statusMessage?: string;
     /** Application version override. */
     version?: string;
+    /** Environment override. */
+    environment?: string;
 }
 /** Parameters for creating a score (evaluation metric). */
 export interface ScoreParams {
@@ -222,16 +308,32 @@ export interface ScoreParams {
     traceId: string;
     /** Optional observation within the trace to score. */
     observationId?: string;
+    /** Optional session to attach this score to. */
+    sessionId?: string;
     /** Score name / metric key, e.g. "accuracy", "helpfulness". */
     name: string;
-    /** Numeric score value. */
+    /** Numeric score value (for NUMERIC/BOOLEAN). */
     value: number;
+    /** String value (for CATEGORICAL scores). */
+    stringValue?: string;
     /** Human-readable comment explaining the score. */
     comment?: string;
-    /** Data type hint: "NUMERIC" or "BOOLEAN". */
-    dataType?: 'NUMERIC' | 'BOOLEAN';
+    /**
+     * Data type of the score.
+     * - NUMERIC: arbitrary number
+     * - BOOLEAN: 0 or 1
+     * - CATEGORICAL: string value with optional categories
+     * - CORRECTION: ground truth / correction data
+     */
+    dataType?: ScoreDataType;
+    /** How this score was produced. */
+    source?: ScoreSource;
+    /** Arbitrary metadata for the score. */
+    metadata?: Record<string, unknown>;
     /** Optional config ID for score definitions managed in the UI. */
     configId?: string;
+    /** Environment override. */
+    environment?: string;
 }
 /** A single event in the ingestion batch. */
 export interface IngestionEvent {

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -2,7 +2,8 @@
  * Core types for the Illuma Observability SDK.
  *
  * This module is the single source of truth for all observability types.
- * It mirrors the Langfuse ingestion API contract so payloads are wire-compatible.
+ * It mirrors the Langfuse ingestion API contract so payloads are wire-compatible,
+ * and incorporates best patterns from Opik for comprehensive LLM observability.
  */
 // ---------------------------------------------------------------------------
 // Enums & Constants
@@ -15,9 +16,36 @@ export var ObservationLevel;
     ObservationLevel["WARNING"] = "WARNING";
     ObservationLevel["ERROR"] = "ERROR";
 })(ObservationLevel || (ObservationLevel = {}));
+/**
+ * Observation type discriminator.
+ * Matches the server's accepted types for rich categorization of spans.
+ */
+export var ObservationType;
+(function (ObservationType) {
+    /** Generic span (default). */
+    ObservationType["SPAN"] = "SPAN";
+    /** LLM generation / completion call. */
+    ObservationType["GENERATION"] = "GENERATION";
+    /** Point-in-time event (no duration). */
+    ObservationType["EVENT"] = "EVENT";
+    /** Autonomous agent execution. */
+    ObservationType["AGENT"] = "AGENT";
+    /** Tool / function invocation. */
+    ObservationType["TOOL"] = "TOOL";
+    /** Chain execution (sequential pipeline). */
+    ObservationType["CHAIN"] = "CHAIN";
+    /** Retriever / vector search operation. */
+    ObservationType["RETRIEVER"] = "RETRIEVER";
+    /** Evaluator execution. */
+    ObservationType["EVALUATOR"] = "EVALUATOR";
+    /** Embedding operation. */
+    ObservationType["EMBEDDING"] = "EMBEDDING";
+    /** Guardrail / safety check. */
+    ObservationType["GUARDRAIL"] = "GUARDRAIL";
+})(ObservationType || (ObservationType = {}));
 /**
  * Ingestion event type constants.
- * These match the Langfuse API exactly so the server can process them
+ * These match the server's accepted event types so payloads are processed
  * without any translation layer.
  */
 export const IngestionEventType = {
@@ -31,8 +59,18 @@ export const IngestionEventType = {
     GENERATION_UPDATE: 'generation-update',
     // Events (point-in-time observations)
     EVENT_CREATE: 'event-create',
+    // Typed observation creates (server routes these to observation table with correct type)
+    AGENT_CREATE: 'agent-create',
+    TOOL_CREATE: 'tool-create',
+    CHAIN_CREATE: 'chain-create',
+    RETRIEVER_CREATE: 'retriever-create',
+    EVALUATOR_CREATE: 'evaluator-create',
+    EMBEDDING_CREATE: 'embedding-create',
+    GUARDRAIL_CREATE: 'guardrail-create',
     // Scores
     SCORE_CREATE: 'score-create',
+    // Dataset
+    DATASET_RUN_ITEM_CREATE: 'dataset-run-item-create',
     // SDK metadata
     SDK_LOG: 'sdk-log',
 };

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E,wCAAwC;AACxC,MAAM,CAAN,IAAY,gBAKX;AALD,WAAY,gBAAgB;IAC1B,mCAAe,CAAA;IACf,uCAAmB,CAAA;IACnB,uCAAmB,CAAA;IACnB,mCAAe,CAAA;AACjB,CAAC,EALW,gBAAgB,KAAhB,gBAAgB,QAK3B;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,SAAS;IACT,YAAY,EAAE,cAAc;IAE5B,QAAQ;IACR,WAAW,EAAE,aAAa;IAC1B,WAAW,EAAE,aAAa;IAE1B,cAAc;IACd,iBAAiB,EAAE,mBAAmB;IACtC,iBAAiB,EAAE,mBAAmB;IAEtC,sCAAsC;IACtC,YAAY,EAAE,cAAc;IAE5B,SAAS;IACT,YAAY,EAAE,cAAc;IAE5B,eAAe;IACf,OAAO,EAAE,SAAS;CACV,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E,wCAAwC;AACxC,MAAM,CAAN,IAAY,gBAKX;AALD,WAAY,gBAAgB;IAC1B,mCAAe,CAAA;IACf,uCAAmB,CAAA;IACnB,uCAAmB,CAAA;IACnB,mCAAe,CAAA;AACjB,CAAC,EALW,gBAAgB,KAAhB,gBAAgB,QAK3B;AAED;;;GAGG;AACH,MAAM,CAAN,IAAY,eAqBX;AArBD,WAAY,eAAe;IACzB,8BAA8B;IAC9B,gCAAa,CAAA;IACb,wCAAwC;IACxC,4CAAyB,CAAA;IACzB,yCAAyC;IACzC,kCAAe,CAAA;IACf,kCAAkC;IAClC,kCAAe,CAAA;IACf,kCAAkC;IAClC,gCAAa,CAAA;IACb,6CAA6C;IAC7C,kCAAe,CAAA;IACf,2CAA2C;IAC3C,0CAAuB,CAAA;IACvB,2BAA2B;IAC3B,0CAAuB,CAAA;IACvB,2BAA2B;IAC3B,0CAAuB,CAAA;IACvB,gCAAgC;IAChC,0CAAuB,CAAA;AACzB,CAAC,EArBW,eAAe,KAAf,eAAe,QAqB1B;AAQD;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,SAAS;IACT,YAAY,EAAE,cAAc;IAE5B,QAAQ;IACR,WAAW,EAAE,aAAa;IAC1B,WAAW,EAAE,aAAa;IAE1B,cAAc;IACd,iBAAiB,EAAE,mBAAmB;IACtC,iBAAiB,EAAE,mBAAmB;IAEtC,sCAAsC;IACtC,YAAY,EAAE,cAAc;IAE5B,yFAAyF;IACzF,YAAY,EAAE,cAAc;IAC5B,WAAW,EAAE,aAAa;IAC1B,YAAY,EAAE,cAAc;IAC5B,gBAAgB,EAAE,kBAAkB;IACpC,gBAAgB,EAAE,kBAAkB;IACpC,gBAAgB,EAAE,kBAAkB;IACpC,gBAAgB,EAAE,kBAAkB;IAEpC,SAAS;IACT,YAAY,EAAE,cAAc;IAE5B,UAAU;IACV,uBAAuB,EAAE,yBAAyB;IAElD,eAAe;IACf,OAAO,EAAE,SAAS;CACV,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@illuma-ai/observability-core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Core observability SDK - shared foundation for Node.js and browser clients",
   "type": "module",
   "main": "dist/index.js",
@@ -16,12 +16,15 @@
   ],
   "scripts": {
     "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {},
   "devDependencies": {
     "typescript": "^5.4.5",
-    "@types/node": "^20.14.2"
+    "@types/node": "^20.14.2",
+    "vitest": "^1.6.0"
   },
   "publishConfig": {
     "access": "public"