@usetransactional/llm-node 0.1.0

package/dist/integrations/langchain.d.mts

@@ -0,0 +1,58 @@
+import { Serialized } from '@langchain/core/load/serializable';
+import { LLMResult } from '@langchain/core/outputs';
+
+/**
+ * LangChain Integration
+ *
+ * Callback handler for automatic tracing of LangChain chains and LLM calls.
+ *
+ * @example
+ * ```typescript
+ * import { TransactionalCallbackHandler } from 'transactional-llm/langchain';
+ * import { ChatOpenAI } from '@langchain/openai';
+ *
+ * const handler = new TransactionalCallbackHandler({
+ *   sessionId: 'conversation-123',
+ * });
+ *
+ * const model = new ChatOpenAI({ modelName: 'gpt-4o' });
+ * const response = await model.invoke('Hello!', { callbacks: [handler] });
+ * ```
+ */
+
+interface TransactionalCallbackHandlerOptions {
+    /** Session ID to group traces */
+    sessionId?: string;
+    /** User ID for attribution */
+    userId?: string;
+    /** Custom metadata for all traces */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * LangChain callback handler for automatic tracing.
+ * Implements the LangChain callback interface without extending BaseCallbackHandler
+ * to avoid requiring @langchain/core as a direct dependency.
+ */
+declare class TransactionalCallbackHandler {
+    name: string;
+    private options;
+    private traceHandle?;
+    private observationStack;
+    constructor(options?: TransactionalCallbackHandlerOptions);
+    private getClient;
+    handleChainStart(chain: Serialized, inputs: Record<string, unknown>, runId: string): Promise<void>;
+    handleChainEnd(outputs: Record<string, unknown>, runId: string): Promise<void>;
+    handleChainError(error: Error, runId: string): Promise<void>;
+    handleLLMStart(llm: Serialized, prompts: string[], runId: string): Promise<void>;
+    handleLLMEnd(output: LLMResult, runId: string): Promise<void>;
+    handleLLMError(error: Error, runId: string): Promise<void>;
+    handleChatModelStart(llm: Serialized, messages: unknown[][], runId: string): Promise<void>;
+    handleToolStart(tool: Serialized, input: string, runId: string): Promise<void>;
+    handleToolEnd(output: string, runId: string): Promise<void>;
+    handleToolError(error: Error, runId: string): Promise<void>;
+    handleRetrieverStart(retriever: Serialized, query: string, runId: string): Promise<void>;
+    handleRetrieverEnd(documents: unknown[], runId: string): Promise<void>;
+    handleRetrieverError(error: Error, runId: string): Promise<void>;
+}
+
+export { TransactionalCallbackHandler, type TransactionalCallbackHandlerOptions };

package/dist/integrations/langchain.d.ts

@@ -0,0 +1,58 @@
+import { Serialized } from '@langchain/core/load/serializable';
+import { LLMResult } from '@langchain/core/outputs';
+
+/**
+ * LangChain Integration
+ *
+ * Callback handler for automatic tracing of LangChain chains and LLM calls.
+ *
+ * @example
+ * ```typescript
+ * import { TransactionalCallbackHandler } from 'transactional-llm/langchain';
+ * import { ChatOpenAI } from '@langchain/openai';
+ *
+ * const handler = new TransactionalCallbackHandler({
+ *   sessionId: 'conversation-123',
+ * });
+ *
+ * const model = new ChatOpenAI({ modelName: 'gpt-4o' });
+ * const response = await model.invoke('Hello!', { callbacks: [handler] });
+ * ```
+ */
+
+interface TransactionalCallbackHandlerOptions {
+    /** Session ID to group traces */
+    sessionId?: string;
+    /** User ID for attribution */
+    userId?: string;
+    /** Custom metadata for all traces */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * LangChain callback handler for automatic tracing.
+ * Implements the LangChain callback interface without extending BaseCallbackHandler
+ * to avoid requiring @langchain/core as a direct dependency.
+ */
+declare class TransactionalCallbackHandler {
+    name: string;
+    private options;
+    private traceHandle?;
+    private observationStack;
+    constructor(options?: TransactionalCallbackHandlerOptions);
+    private getClient;
+    handleChainStart(chain: Serialized, inputs: Record<string, unknown>, runId: string): Promise<void>;
+    handleChainEnd(outputs: Record<string, unknown>, runId: string): Promise<void>;
+    handleChainError(error: Error, runId: string): Promise<void>;
+    handleLLMStart(llm: Serialized, prompts: string[], runId: string): Promise<void>;
+    handleLLMEnd(output: LLMResult, runId: string): Promise<void>;
+    handleLLMError(error: Error, runId: string): Promise<void>;
+    handleChatModelStart(llm: Serialized, messages: unknown[][], runId: string): Promise<void>;
+    handleToolStart(tool: Serialized, input: string, runId: string): Promise<void>;
+    handleToolEnd(output: string, runId: string): Promise<void>;
+    handleToolError(error: Error, runId: string): Promise<void>;
+    handleRetrieverStart(retriever: Serialized, query: string, runId: string): Promise<void>;
+    handleRetrieverEnd(documents: unknown[], runId: string): Promise<void>;
+    handleRetrieverError(error: Error, runId: string): Promise<void>;
+}
+
+export { TransactionalCallbackHandler, type TransactionalCallbackHandlerOptions };

package/dist/integrations/langchain.js

@@ -0,0 +1,216 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/integrations/langchain.ts
+var langchain_exports = {};
+__export(langchain_exports, {
+  TransactionalCallbackHandler: () => TransactionalCallbackHandler
+});
+module.exports = __toCommonJS(langchain_exports);
+
+// src/client.ts
+var import_nanoid = require("nanoid");
+
+// src/index.ts
+var defaultClient = null;
+function getLlmOps() {
+  if (!defaultClient) {
+    throw new Error(
+      "LLM Ops SDK not initialized. Call initLlmOps() first."
+    );
+  }
+  return defaultClient;
+}
+function isInitialized() {
+  return defaultClient !== null;
+}
+
+// src/integrations/langchain.ts
+function getModelName(serialized, fallback) {
+  if ("kwargs" in serialized && serialized.kwargs) {
+    const kwargs = serialized.kwargs;
+    return String(kwargs.model || kwargs.modelName || fallback);
+  }
+  return fallback;
+}
+var TransactionalCallbackHandler = class {
+  constructor(options = {}) {
+    this.name = "TransactionalCallbackHandler";
+    this.observationStack = /* @__PURE__ */ new Map();
+    this.options = options;
+  }
+  getClient() {
+    if (!isInitialized()) {
+      console.warn(
+        "[LlmOps] SDK not initialized. Call initLlmOps() before using the LangChain handler."
+      );
+      return null;
+    }
+    return getLlmOps();
+  }
+  // ===========================================
+  // CHAIN CALLBACKS
+  // ===========================================
+  async handleChainStart(chain, inputs, runId) {
+    const client = this.getClient();
+    if (!client) return;
+    const name = chain.id?.join("/") || "chain";
+    if (!this.traceHandle) {
+      this.traceHandle = client.trace({
+        name,
+        sessionId: this.options.sessionId,
+        userId: this.options.userId,
+        input: inputs,
+        metadata: this.options.metadata
+      });
+    } else {
+      const span = client.span({
+        name,
+        input: inputs
+      });
+      this.observationStack.set(runId, span);
+    }
+  }
+  async handleChainEnd(outputs, runId) {
+    const observation = this.observationStack.get(runId);
+    if (observation) {
+      await observation.end({ output: outputs });
+      this.observationStack.delete(runId);
+    } else if (this.traceHandle && this.observationStack.size === 0) {
+      await this.traceHandle.end({ output: outputs });
+      this.traceHandle = void 0;
+    }
+  }
+  async handleChainError(error, runId) {
+    const observation = this.observationStack.get(runId);
+    if (observation) {
+      await observation.error(error);
+      this.observationStack.delete(runId);
+    } else if (this.traceHandle) {
+      await this.traceHandle.error(error);
+      this.traceHandle = void 0;
+    }
+  }
+  // ===========================================
+  // LLM CALLBACKS
+  // ===========================================
+  async handleLLMStart(llm, prompts, runId) {
+    const client = this.getClient();
+    if (!client) return;
+    const name = llm.id?.join("/") || "llm";
+    const modelName = getModelName(llm, name);
+    const generation = client.generation({
+      name,
+      modelName,
+      input: { prompts }
+    });
+    this.observationStack.set(runId, generation);
+  }
+  async handleLLMEnd(output, runId) {
+    const observation = this.observationStack.get(runId);
+    if (!observation) return;
+    const tokenUsage = output.llmOutput?.tokenUsage;
+    await observation.end({
+      output: { generations: output.generations },
+      promptTokens: tokenUsage?.promptTokens,
+      completionTokens: tokenUsage?.completionTokens
+    });
+    this.observationStack.delete(runId);
+  }
+  async handleLLMError(error, runId) {
+    const observation = this.observationStack.get(runId);
+    if (observation) {
+      await observation.error(error);
+      this.observationStack.delete(runId);
+    }
+  }
+  // ===========================================
+  // CHAT MODEL CALLBACKS
+  // ===========================================
+  async handleChatModelStart(llm, messages, runId) {
+    const client = this.getClient();
+    if (!client) return;
+    const name = llm.id?.join("/") || "chat";
+    const modelName = getModelName(llm, name);
+    const generation = client.generation({
+      name,
+      modelName,
+      input: { messages }
+    });
+    this.observationStack.set(runId, generation);
+  }
+  // ===========================================
+  // TOOL CALLBACKS
+  // ===========================================
+  async handleToolStart(tool, input, runId) {
+    const client = this.getClient();
+    if (!client) return;
+    const name = tool.id?.join("/") || "tool";
+    const span = client.span({
+      name,
+      input: { input }
+    });
+    this.observationStack.set(runId, span);
+  }
+  async handleToolEnd(output, runId) {
+    const observation = this.observationStack.get(runId);
+    if (observation) {
+      await observation.end({ output: { output } });
+      this.observationStack.delete(runId);
+    }
+  }
+  async handleToolError(error, runId) {
+    const observation = this.observationStack.get(runId);
+    if (observation) {
+      await observation.error(error);
+      this.observationStack.delete(runId);
+    }
+  }
+  // ===========================================
+  // RETRIEVER CALLBACKS
+  // ===========================================
+  async handleRetrieverStart(retriever, query, runId) {
+    const client = this.getClient();
+    if (!client) return;
+    const name = retriever.id?.join("/") || "retriever";
+    const span = client.span({
+      name,
+      input: { query }
+    });
+    this.observationStack.set(runId, span);
+  }
+  async handleRetrieverEnd(documents, runId) {
+    const observation = this.observationStack.get(runId);
+    if (observation) {
+      await observation.end({ output: { documents } });
+      this.observationStack.delete(runId);
+    }
+  }
+  async handleRetrieverError(error, runId) {
+    const observation = this.observationStack.get(runId);
+    if (observation) {
+      await observation.error(error);
+      this.observationStack.delete(runId);
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  TransactionalCallbackHandler
+});

package/dist/integrations/langchain.mjs

@@ -0,0 +1,177 @@
+import {
+  getLlmOps,
+  isInitialized
+} from "../chunk-IR6P3PV4.mjs";
+
+// src/integrations/langchain.ts
+function getModelName(serialized, fallback) {
+  if ("kwargs" in serialized && serialized.kwargs) {
+    const kwargs = serialized.kwargs;
+    return String(kwargs.model || kwargs.modelName || fallback);
+  }
+  return fallback;
+}
+var TransactionalCallbackHandler = class {
+  constructor(options = {}) {
+    this.name = "TransactionalCallbackHandler";
+    this.observationStack = /* @__PURE__ */ new Map();
+    this.options = options;
+  }
+  getClient() {
+    if (!isInitialized()) {
+      console.warn(
+        "[LlmOps] SDK not initialized. Call initLlmOps() before using the LangChain handler."
+      );
+      return null;
+    }
+    return getLlmOps();
+  }
+  // ===========================================
+  // CHAIN CALLBACKS
+  // ===========================================
+  async handleChainStart(chain, inputs, runId) {
+    const client = this.getClient();
+    if (!client) return;
+    const name = chain.id?.join("/") || "chain";
+    if (!this.traceHandle) {
+      this.traceHandle = client.trace({
+        name,
+        sessionId: this.options.sessionId,
+        userId: this.options.userId,
+        input: inputs,
+        metadata: this.options.metadata
+      });
+    } else {
+      const span = client.span({
+        name,
+        input: inputs
+      });
+      this.observationStack.set(runId, span);
+    }
+  }
+  async handleChainEnd(outputs, runId) {
+    const observation = this.observationStack.get(runId);
+    if (observation) {
+      await observation.end({ output: outputs });
+      this.observationStack.delete(runId);
+    } else if (this.traceHandle && this.observationStack.size === 0) {
+      await this.traceHandle.end({ output: outputs });
+      this.traceHandle = void 0;
+    }
+  }
+  async handleChainError(error, runId) {
+    const observation = this.observationStack.get(runId);
+    if (observation) {
+      await observation.error(error);
+      this.observationStack.delete(runId);
+    } else if (this.traceHandle) {
+      await this.traceHandle.error(error);
+      this.traceHandle = void 0;
+    }
+  }
+  // ===========================================
+  // LLM CALLBACKS
+  // ===========================================
+  async handleLLMStart(llm, prompts, runId) {
+    const client = this.getClient();
+    if (!client) return;
+    const name = llm.id?.join("/") || "llm";
+    const modelName = getModelName(llm, name);
+    const generation = client.generation({
+      name,
+      modelName,
+      input: { prompts }
+    });
+    this.observationStack.set(runId, generation);
+  }
+  async handleLLMEnd(output, runId) {
+    const observation = this.observationStack.get(runId);
+    if (!observation) return;
+    const tokenUsage = output.llmOutput?.tokenUsage;
+    await observation.end({
+      output: { generations: output.generations },
+      promptTokens: tokenUsage?.promptTokens,
+      completionTokens: tokenUsage?.completionTokens
+    });
+    this.observationStack.delete(runId);
+  }
+  async handleLLMError(error, runId) {
+    const observation = this.observationStack.get(runId);
+    if (observation) {
+      await observation.error(error);
+      this.observationStack.delete(runId);
+    }
+  }
+  // ===========================================
+  // CHAT MODEL CALLBACKS
+  // ===========================================
+  async handleChatModelStart(llm, messages, runId) {
+    const client = this.getClient();
+    if (!client) return;
+    const name = llm.id?.join("/") || "chat";
+    const modelName = getModelName(llm, name);
+    const generation = client.generation({
+      name,
+      modelName,
+      input: { messages }
+    });
+    this.observationStack.set(runId, generation);
+  }
+  // ===========================================
+  // TOOL CALLBACKS
+  // ===========================================
+  async handleToolStart(tool, input, runId) {
+    const client = this.getClient();
+    if (!client) return;
+    const name = tool.id?.join("/") || "tool";
+    const span = client.span({
+      name,
+      input: { input }
+    });
+    this.observationStack.set(runId, span);
+  }
+  async handleToolEnd(output, runId) {
+    const observation = this.observationStack.get(runId);
+    if (observation) {
+      await observation.end({ output: { output } });
+      this.observationStack.delete(runId);
+    }
+  }
+  async handleToolError(error, runId) {
+    const observation = this.observationStack.get(runId);
+    if (observation) {
+      await observation.error(error);
+      this.observationStack.delete(runId);
+    }
+  }
+  // ===========================================
+  // RETRIEVER CALLBACKS
+  // ===========================================
+  async handleRetrieverStart(retriever, query, runId) {
+    const client = this.getClient();
+    if (!client) return;
+    const name = retriever.id?.join("/") || "retriever";
+    const span = client.span({
+      name,
+      input: { query }
+    });
+    this.observationStack.set(runId, span);
+  }
+  async handleRetrieverEnd(documents, runId) {
+    const observation = this.observationStack.get(runId);
+    if (observation) {
+      await observation.end({ output: { documents } });
+      this.observationStack.delete(runId);
+    }
+  }
+  async handleRetrieverError(error, runId) {
+    const observation = this.observationStack.get(runId);
+    if (observation) {
+      await observation.error(error);
+      this.observationStack.delete(runId);
+    }
+  }
+};
+export {
+  TransactionalCallbackHandler
+};

package/dist/integrations/vercel-ai.d.mts

@@ -0,0 +1,72 @@
+export { getLlmOps, initLlmOps } from '../index.mjs';
+
+/**
+ * Vercel AI SDK Integration
+ *
+ * Wrapper functions for automatic tracing of Vercel AI SDK calls.
+ *
+ * @example
+ * ```typescript
+ * import { wrapAiSdk } from 'transactional-llm/vercel-ai';
+ * import { generateText } from 'ai';
+ *
+ * const wrappedGenerateText = wrapAiSdk(generateText);
+ *
+ * const { text } = await wrappedGenerateText({
+ *   model: openai('gpt-4o'),
+ *   prompt: 'Hello!',
+ * });
+ * ```
+ */
+interface TelemetryMetadata {
+    userId?: string;
+    sessionId?: string;
+    [key: string]: unknown;
+}
+interface WrappedOptions {
+    experimental_telemetry?: {
+        metadata?: TelemetryMetadata;
+    };
+    model?: {
+        modelId?: string;
+        provider?: string;
+    };
+    prompt?: string;
+    messages?: unknown[];
+    [key: string]: unknown;
+}
+interface GenerateResult {
+    text?: string;
+    usage?: {
+        promptTokens?: number;
+        completionTokens?: number;
+        totalTokens?: number;
+    };
+    [key: string]: unknown;
+}
+type AiFn<T> = (options: WrappedOptions) => Promise<T>;
+/**
+ * Wrap a Vercel AI SDK function to automatically trace calls
+ *
+ * @param fn - The AI SDK function to wrap (e.g., generateText, streamText)
+ * @returns A wrapped function that traces the call
+ *
+ * @example
+ * ```typescript
+ * const wrappedGenerateText = wrapAiSdk(generateText);
+ * const { text } = await wrappedGenerateText({
+ *   model: openai('gpt-4o'),
+ *   prompt: 'Hello!',
+ * });
+ * ```
+ */
+declare function wrapAiSdk<T extends GenerateResult>(fn: AiFn<T>): AiFn<T>;
+/**
+ * Create a traced version of streamText
+ *
+ * For streaming responses, this wraps the stream and captures
+ * the final token counts when the stream completes.
+ */
+declare function wrapStreamText<T extends AsyncIterable<unknown>>(fn: (options: WrappedOptions) => Promise<T>): (options: WrappedOptions) => Promise<T>;
+
+export { wrapAiSdk, wrapStreamText };

package/dist/integrations/vercel-ai.d.ts

@@ -0,0 +1,72 @@
+export { getLlmOps, initLlmOps } from '../index.js';
+
+/**
+ * Vercel AI SDK Integration
+ *
+ * Wrapper functions for automatic tracing of Vercel AI SDK calls.
+ *
+ * @example
+ * ```typescript
+ * import { wrapAiSdk } from 'transactional-llm/vercel-ai';
+ * import { generateText } from 'ai';
+ *
+ * const wrappedGenerateText = wrapAiSdk(generateText);
+ *
+ * const { text } = await wrappedGenerateText({
+ *   model: openai('gpt-4o'),
+ *   prompt: 'Hello!',
+ * });
+ * ```
+ */
+interface TelemetryMetadata {
+    userId?: string;
+    sessionId?: string;
+    [key: string]: unknown;
+}
+interface WrappedOptions {
+    experimental_telemetry?: {
+        metadata?: TelemetryMetadata;
+    };
+    model?: {
+        modelId?: string;
+        provider?: string;
+    };
+    prompt?: string;
+    messages?: unknown[];
+    [key: string]: unknown;
+}
+interface GenerateResult {
+    text?: string;
+    usage?: {
+        promptTokens?: number;
+        completionTokens?: number;
+        totalTokens?: number;
+    };
+    [key: string]: unknown;
+}
+type AiFn<T> = (options: WrappedOptions) => Promise<T>;
+/**
+ * Wrap a Vercel AI SDK function to automatically trace calls
+ *
+ * @param fn - The AI SDK function to wrap (e.g., generateText, streamText)
+ * @returns A wrapped function that traces the call
+ *
+ * @example
+ * ```typescript
+ * const wrappedGenerateText = wrapAiSdk(generateText);
+ * const { text } = await wrappedGenerateText({
+ *   model: openai('gpt-4o'),
+ *   prompt: 'Hello!',
+ * });
+ * ```
+ */
+declare function wrapAiSdk<T extends GenerateResult>(fn: AiFn<T>): AiFn<T>;
+/**
+ * Create a traced version of streamText
+ *
+ * For streaming responses, this wraps the stream and captures
+ * the final token counts when the stream completes.
+ */
+declare function wrapStreamText<T extends AsyncIterable<unknown>>(fn: (options: WrappedOptions) => Promise<T>): (options: WrappedOptions) => Promise<T>;
+
+export { wrapAiSdk, wrapStreamText };