@usetransactional/llm-node 0.1.0

package/README.md

@@ -0,0 +1,103 @@
+# transactional-llm
+
+LLM Ops SDK for Transactional - AI observability with cost tracking, trace analysis, and performance monitoring.
+
+## Installation
+
+```bash
+npm install transactional-llm
+```
+
+## Quick Start
+
+```typescript
+import { initLlmOps, getLlmOps } from 'transactional-llm';
+
+// Initialize once at startup
+initLlmOps({
+  dsn: process.env.TRANSACTIONAL_LLM_OPS_DSN!,
+});
+
+// Create traces
+const llmOps = getLlmOps();
+
+const trace = llmOps.trace({
+  name: 'chat-completion',
+  input: { prompt: 'Hello!' },
+  userId: 'user-123',
+});
+
+const generation = llmOps.generation({
+  name: 'gpt-4o',
+  modelName: 'gpt-4o',
+  input: { messages: [...] },
+});
+
+await generation.end({
+  output: { content: 'Hi there!' },
+  promptTokens: 10,
+  completionTokens: 5,
+});
+
+await trace.end({ output: { response: 'Hi there!' } });
+```
+
+## LangChain Integration
+
+```typescript
+import { TransactionalCallbackHandler } from 'transactional-llm/langchain';
+import { ChatOpenAI } from '@langchain/openai';
+
+const handler = new TransactionalCallbackHandler({
+  sessionId: 'conversation-123',
+  userId: 'user-456',
+});
+
+const model = new ChatOpenAI({ modelName: 'gpt-4o' });
+
+const response = await model.invoke('Hello!', {
+  callbacks: [handler],
+});
+```
+
+## Vercel AI SDK Integration
+
+```typescript
+import { wrapAiSdk } from 'transactional-llm/vercel-ai';
+import { generateText } from 'ai';
+import { openai } from '@ai-sdk/openai';
+
+const wrappedGenerateText = wrapAiSdk(generateText);
+
+const { text } = await wrappedGenerateText({
+  model: openai('gpt-4o'),
+  prompt: 'Hello!',
+});
+```
+
+## Configuration
+
+```typescript
+initLlmOps({
+  // Required: Your project DSN
+  dsn: 'https://pk_...@api.transactional.dev/observability/42',
+
+  // Optional: Disable tracing
+  enabled: process.env.NODE_ENV === 'production',
+
+  // Optional: Batch settings
+  batchSize: 100,
+  flushInterval: 5000,
+
+  // Optional: Debug mode
+  debug: false,
+});
+```
+
+## Documentation
+
+Full documentation available at [transactional.dev/docs/llm-ops](https://transactional.dev/docs/llm-ops)
+
+## License
+
+MIT

package/dist/chunk-IR6P3PV4.mjs

@@ -0,0 +1,319 @@
+// src/client.ts
+import { nanoid } from "nanoid";
+var currentTraceId;
+var currentObservationId;
+function setTraceContext(traceId, observationId) {
+  currentTraceId = traceId;
+  currentObservationId = observationId;
+}
+function getTraceContext() {
+  return { traceId: currentTraceId, observationId: currentObservationId };
+}
+function clearTraceContext() {
+  currentTraceId = void 0;
+  currentObservationId = void 0;
+}
+var LlmOpsClient = class {
+  constructor(config) {
+    this.queue = [];
+    this.config = this.parseConfig(config);
+    if (this.config.enabled) {
+      this.startFlushTimer();
+    }
+  }
+  parseConfig(config) {
+    let publicKey = config.publicKey;
+    let projectId = config.projectId;
+    let baseUrl = config.baseUrl || "https://api.transactional.dev";
+    if (config.dsn) {
+      try {
+        const url = new URL(config.dsn);
+        publicKey = url.username;
+        const pathParts = url.pathname.split("/").filter(Boolean);
+        projectId = parseInt(pathParts[pathParts.length - 1] || "0");
+        baseUrl = `${url.protocol}//${url.host}`;
+      } catch {
+        throw new Error(`Invalid DSN format: ${config.dsn}`);
+      }
+    }
+    if (!publicKey || !projectId) {
+      throw new Error("LlmOps requires either a DSN or publicKey + projectId");
+    }
+    return {
+      publicKey,
+      projectId,
+      baseUrl,
+      enabled: config.enabled ?? true,
+      batchSize: config.batchSize ?? 100,
+      flushInterval: config.flushInterval ?? 5e3,
+      debug: config.debug ?? false
+    };
+  }
+  startFlushTimer() {
+    this.flushTimer = setInterval(() => {
+      this.flush().catch((err) => {
+        if (this.config.debug) {
+          console.error("[LlmOps] Flush error:", err);
+        }
+      });
+    }, this.config.flushInterval);
+  }
+  log(message, ...args) {
+    if (this.config.debug) {
+      console.log(`[LlmOps] ${message}`, ...args);
+    }
+  }
+  enqueue(item) {
+    if (!this.config.enabled) return;
+    this.queue.push(item);
+    this.log("Enqueued:", item.type, item.id);
+    if (this.queue.length >= this.config.batchSize) {
+      this.flush().catch((err) => {
+        if (this.config.debug) {
+          console.error("[LlmOps] Flush error:", err);
+        }
+      });
+    }
+  }
+  /**
+   * Create a new trace
+   */
+  trace(params) {
+    const traceId = nanoid();
+    const startTime = (/* @__PURE__ */ new Date()).toISOString();
+    this.enqueue({
+      type: "trace",
+      id: traceId,
+      projectId: this.config.projectId,
+      ...params,
+      status: "RUNNING",
+      startTime
+    });
+    setTraceContext(traceId);
+    return {
+      id: traceId,
+      end: async (endParams) => {
+        await this.updateTrace(traceId, {
+          status: "COMPLETED",
+          output: endParams?.output,
+          endTime: (/* @__PURE__ */ new Date()).toISOString()
+        });
+        clearTraceContext();
+      },
+      error: async (error) => {
+        await this.updateTrace(traceId, {
+          status: "ERROR",
+          metadata: { error: error.message, stack: error.stack },
+          endTime: (/* @__PURE__ */ new Date()).toISOString()
+        });
+        clearTraceContext();
+      }
+    };
+  }
+  /**
+   * Update an existing trace
+   */
+  async updateTrace(traceId, params) {
+    this.enqueue({
+      type: "trace",
+      id: traceId,
+      ...params
+    });
+  }
+  /**
+   * Create a new observation (span, generation, or event)
+   */
+  observation(params) {
+    const observationId = nanoid();
+    const startTime = (/* @__PURE__ */ new Date()).toISOString();
+    const context = getTraceContext();
+    const traceId = params.traceId || context.traceId;
+    if (!traceId) {
+      throw new Error("No trace context found. Create a trace first.");
+    }
+    const { type: observationType, ...restParams } = params;
+    this.enqueue({
+      type: "observation",
+      id: observationId,
+      traceId,
+      parentObservationId: restParams.parentObservationId || context.observationId,
+      ...restParams,
+      observationType,
+      status: "RUNNING",
+      startTime
+    });
+    setTraceContext(traceId, observationId);
+    return {
+      id: observationId,
+      end: async (endParams) => {
+        await this.updateObservation(observationId, {
+          status: "COMPLETED",
+          output: endParams?.output,
+          promptTokens: endParams?.promptTokens,
+          completionTokens: endParams?.completionTokens,
+          endTime: (/* @__PURE__ */ new Date()).toISOString()
+        });
+        setTraceContext(traceId, params.parentObservationId || context.observationId);
+      },
+      error: async (error) => {
+        await this.updateObservation(observationId, {
+          status: "ERROR",
+          metadata: { error: error.message, stack: error.stack },
+          endTime: (/* @__PURE__ */ new Date()).toISOString()
+        });
+        setTraceContext(traceId, params.parentObservationId || context.observationId);
+      }
+    };
+  }
+  /**
+   * Create a generation observation (LLM call)
+   */
+  generation(params) {
+    return this.observation({
+      ...params,
+      type: "GENERATION"
+    });
+  }
+  /**
+   * Create a span observation
+   */
+  span(params) {
+    return this.observation({
+      ...params,
+      type: "SPAN"
+    });
+  }
+  /**
+   * Create an event observation
+   */
+  event(params) {
+    return this.observation({
+      ...params,
+      type: "EVENT"
+    });
+  }
+  /**
+   * Update an existing observation
+   */
+  async updateObservation(observationId, params) {
+    this.enqueue({
+      type: "observation",
+      id: observationId,
+      ...params
+    });
+  }
+  /**
+   * Flush queued events to the API
+   */
+  async flush() {
+    if (this.queue.length === 0) return;
+    if (this.pendingFlush) {
+      await this.pendingFlush;
+    }
+    const batch = this.queue.splice(0, this.config.batchSize);
+    this.log("Flushing", batch.length, "items");
+    this.pendingFlush = this.sendBatch(batch);
+    await this.pendingFlush;
+    this.pendingFlush = void 0;
+  }
+  async sendBatch(batch) {
+    try {
+      const response = await fetch(
+        `${this.config.baseUrl}/observability/ingest/batch`,
+        {
+          method: "POST",
+          headers: {
+            "Authorization": `Bearer ${this.config.publicKey}`,
+            "Content-Type": "application/json"
+          },
+          body: JSON.stringify({
+            projectId: this.config.projectId,
+            batch
+          })
+        }
+      );
+      if (!response.ok) {
+        const text = await response.text();
+        throw new Error(`Failed to send batch: ${response.status} ${text}`);
+      }
+      this.log("Batch sent successfully");
+    } catch (error) {
+      this.queue.unshift(...batch);
+      throw error;
+    }
+  }
+  /**
+   * Shutdown the client and flush remaining events
+   */
+  async shutdown() {
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+    }
+    await this.flush();
+    this.log("Shutdown complete");
+  }
+};
+
+// src/types/index.ts
+var TraceStatus = /* @__PURE__ */ ((TraceStatus2) => {
+  TraceStatus2["RUNNING"] = "RUNNING";
+  TraceStatus2["COMPLETED"] = "COMPLETED";
+  TraceStatus2["ERROR"] = "ERROR";
+  return TraceStatus2;
+})(TraceStatus || {});
+var ObservationType = /* @__PURE__ */ ((ObservationType2) => {
+  ObservationType2["SPAN"] = "SPAN";
+  ObservationType2["GENERATION"] = "GENERATION";
+  ObservationType2["EVENT"] = "EVENT";
+  return ObservationType2;
+})(ObservationType || {});
+var ObservationLevel = /* @__PURE__ */ ((ObservationLevel2) => {
+  ObservationLevel2["DEBUG"] = "DEBUG";
+  ObservationLevel2["INFO"] = "INFO";
+  ObservationLevel2["WARNING"] = "WARNING";
+  ObservationLevel2["ERROR"] = "ERROR";
+  return ObservationLevel2;
+})(ObservationLevel || {});
+
+// src/index.ts
+var defaultClient = null;
+function initLlmOps(config) {
+  if (defaultClient) {
+    console.warn("[LlmOps] SDK already initialized. Ignoring duplicate initialization.");
+    return defaultClient;
+  }
+  defaultClient = new LlmOpsClient(config);
+  return defaultClient;
+}
+function getLlmOps() {
+  if (!defaultClient) {
+    throw new Error(
+      "LLM Ops SDK not initialized. Call initLlmOps() first."
+    );
+  }
+  return defaultClient;
+}
+function isInitialized() {
+  return defaultClient !== null;
+}
+function resetLlmOps() {
+  if (defaultClient) {
+    defaultClient.shutdown().catch(() => {
+    });
+    defaultClient = null;
+  }
+}
+
+export {
+  setTraceContext,
+  getTraceContext,
+  clearTraceContext,
+  LlmOpsClient,
+  TraceStatus,
+  ObservationType,
+  ObservationLevel,
+  initLlmOps,
+  getLlmOps,
+  isInitialized,
+  resetLlmOps
+};

package/dist/index.d.mts

@@ -0,0 +1,289 @@
+/**
+ * LLM Ops Type Definitions
+ *
+ * Core types for the LLM Ops SDK.
+ */
+declare enum TraceStatus {
+    RUNNING = "RUNNING",
+    COMPLETED = "COMPLETED",
+    ERROR = "ERROR"
+}
+declare enum ObservationType {
+    SPAN = "SPAN",
+    GENERATION = "GENERATION",
+    EVENT = "EVENT"
+}
+declare enum ObservationLevel {
+    DEBUG = "DEBUG",
+    INFO = "INFO",
+    WARNING = "WARNING",
+    ERROR = "ERROR"
+}
+interface Trace {
+    id: string;
+    projectId: number;
+    sessionId?: string;
+    name: string;
+    status: TraceStatus;
+    input?: Record<string, unknown>;
+    output?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    tags?: string[];
+    userId?: string;
+    startTime: string;
+    endTime?: string;
+    totalTokens: number;
+    totalCost: number;
+    latencyMs?: number;
+}
+interface CreateTraceParams {
+    name: string;
+    sessionId?: string;
+    input?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    tags?: string[];
+    userId?: string;
+}
+interface UpdateTraceParams {
+    status?: TraceStatus;
+    output?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    endTime?: string;
+}
+interface Observation {
+    id: string;
+    traceId: string;
+    parentObservationId?: string;
+    type: ObservationType;
+    name: string;
+    status: TraceStatus;
+    modelName?: string;
+    input?: Record<string, unknown>;
+    output?: Record<string, unknown>;
+    promptTokens?: number;
+    completionTokens?: number;
+    totalTokens?: number;
+    cost?: number;
+    startTime: string;
+    endTime?: string;
+    latencyMs?: number;
+    metadata?: Record<string, unknown>;
+    level?: ObservationLevel;
+}
+interface CreateObservationParams {
+    traceId?: string;
+    parentObservationId?: string;
+    type: ObservationType;
+    name: string;
+    modelName?: string;
+    input?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    level?: ObservationLevel;
+}
+interface UpdateObservationParams {
+    status?: TraceStatus;
+    output?: Record<string, unknown>;
+    promptTokens?: number;
+    completionTokens?: number;
+    metadata?: Record<string, unknown>;
+    endTime?: string;
+}
+interface Session {
+    id: string;
+    projectId: number;
+    externalId?: string;
+    userId?: string;
+    metadata?: Record<string, unknown>;
+    startTime: string;
+    endTime?: string;
+    traceCount: number;
+    totalTokens: number;
+    totalCost: number;
+}
+interface UpsertSessionParams {
+    id?: string;
+    userId?: string;
+    metadata?: Record<string, unknown>;
+}
+interface BatchIngestParams {
+    traces?: CreateTraceParams[];
+    observations?: CreateObservationParams[];
+    sessions?: UpsertSessionParams[];
+}
+interface BatchIngestResult {
+    success: boolean;
+    tracesCreated: number;
+    observationsCreated: number;
+    sessionsCreated: number;
+    errors?: string[];
+}
+interface LlmOpsConfig {
+    /** DSN format: https://{publicKey}@api.transactional.dev/observability/{projectId} */
+    dsn?: string;
+    /** Public key (alternative to DSN) */
+    publicKey?: string;
+    /** Project ID (alternative to DSN) */
+    projectId?: number;
+    /** Base URL (alternative to DSN) */
+    baseUrl?: string;
+    /** Enable/disable tracing (default: true) */
+    enabled?: boolean;
+    /** Batch size before flushing (default: 100) */
+    batchSize?: number;
+    /** Flush interval in ms (default: 5000) */
+    flushInterval?: number;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+}
+interface TraceHandle {
+    id: string;
+    end: (params?: {
+        output?: Record<string, unknown>;
+    }) => Promise<void>;
+    error: (error: Error) => Promise<void>;
+}
+interface ObservationHandle {
+    id: string;
+    end: (params?: {
+        output?: Record<string, unknown>;
+        promptTokens?: number;
+        completionTokens?: number;
+    }) => Promise<void>;
+    error: (error: Error) => Promise<void>;
+}
+
+/**
+ * LLM Ops Client
+ *
+ * Main client for sending traces and observations to the LLM Ops API.
+ */
+
+declare function setTraceContext(traceId: string, observationId?: string): void;
+declare function getTraceContext(): {
+    traceId?: string;
+    observationId?: string;
+};
+declare function clearTraceContext(): void;
+declare class LlmOpsClient {
+    private config;
+    private queue;
+    private flushTimer?;
+    private pendingFlush?;
+    constructor(config: LlmOpsConfig);
+    private parseConfig;
+    private startFlushTimer;
+    private log;
+    private enqueue;
+    /**
+     * Create a new trace
+     */
+    trace(params: CreateTraceParams): TraceHandle;
+    /**
+     * Update an existing trace
+     */
+    updateTrace(traceId: string, params: UpdateTraceParams): Promise<void>;
+    /**
+     * Create a new observation (span, generation, or event)
+     */
+    observation(params: CreateObservationParams): ObservationHandle;
+    /**
+     * Create a generation observation (LLM call)
+     */
+    generation(params: Omit<CreateObservationParams, 'type'>): ObservationHandle;
+    /**
+     * Create a span observation
+     */
+    span(params: Omit<CreateObservationParams, 'type'>): ObservationHandle;
+    /**
+     * Create an event observation
+     */
+    event(params: Omit<CreateObservationParams, 'type'>): ObservationHandle;
+    /**
+     * Update an existing observation
+     */
+    updateObservation(observationId: string, params: UpdateObservationParams): Promise<void>;
+    /**
+     * Flush queued events to the API
+     */
+    flush(): Promise<void>;
+    private sendBatch;
+    /**
+     * Shutdown the client and flush remaining events
+     */
+    shutdown(): Promise<void>;
+}
+
+/**
+ * Transactional LLM Ops SDK
+ *
+ * AI observability with cost tracking, trace analysis, and performance monitoring.
+ *
+ * @example
+ * ```typescript
+ * import { initLlmOps, getLlmOps } from 'transactional-llm';
+ *
+ * initLlmOps({
+ *   dsn: process.env.TRANSACTIONAL_LLM_OPS_DSN!,
+ * });
+ *
+ * const llmOps = getLlmOps();
+ *
+ * const trace = llmOps.trace({
+ *   name: 'chat-completion',
+ *   input: { prompt: 'Hello!' },
+ * });
+ *
+ * const generation = llmOps.generation({
+ *   name: 'gpt-4o',
+ *   modelName: 'gpt-4o',
+ * });
+ *
+ * await generation.end({
+ *   output: { content: 'Hi there!' },
+ *   promptTokens: 10,
+ *   completionTokens: 5,
+ * });
+ *
+ * await trace.end({ output: { response: 'Hi there!' } });
+ * ```
+ */
+
+/**
+ * Initialize the LLM Ops SDK
+ *
+ * Call this once at application startup before using any tracing functions.
+ *
+ * @param config - Configuration options including DSN
+ * @returns The initialized client instance
+ *
+ * @example
+ * ```typescript
+ * initLlmOps({
+ *   dsn: 'https://pk_...@api.transactional.dev/observability/42',
+ * });
+ * ```
+ */
+declare function initLlmOps(config: LlmOpsConfig): LlmOpsClient;
+/**
+ * Get the LLM Ops client instance
+ *
+ * @throws Error if SDK has not been initialized
+ * @returns The client instance
+ *
+ * @example
+ * ```typescript
+ * const llmOps = getLlmOps();
+ * const trace = llmOps.trace({ name: 'my-trace' });
+ * ```
+ */
+declare function getLlmOps(): LlmOpsClient;
+/**
+ * Check if the SDK is initialized
+ */
+declare function isInitialized(): boolean;
+/**
+ * Reset the SDK (mainly for testing)
+ */
+declare function resetLlmOps(): void;
+
+export { type BatchIngestParams, type BatchIngestResult, type CreateObservationParams, type CreateTraceParams, LlmOpsClient, type LlmOpsConfig, type Observation, type ObservationHandle, ObservationLevel, ObservationType, type Session, type Trace, type TraceHandle, TraceStatus, type UpdateObservationParams, type UpdateTraceParams, clearTraceContext, getLlmOps, getTraceContext, initLlmOps, isInitialized, resetLlmOps, setTraceContext };