@diogonzafe/tokenwatch 0.2.1 → 0.5.0

package/dist/langchain.cjs

@@ -0,0 +1,62 @@
+"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/langchain/index.ts
+var langchain_exports = {};
+__export(langchain_exports, {
+  TokenwatchCallbackHandler: () => TokenwatchCallbackHandler
+});
+module.exports = __toCommonJS(langchain_exports);
+
+// src/langchain/handler.ts
+var BaseCallbackHandlerStub = class {
+};
+var TokenwatchCallbackHandler = class extends BaseCallbackHandlerStub {
+  constructor(tracker, options = {}) {
+    super();
+    this.tracker = tracker;
+    this.options = options;
+  }
+  tracker;
+  options;
+  name = "TokenwatchCallbackHandler";
+  async handleLLMEnd(output) {
+    const tokenUsage = output.llmOutput?.tokenUsage ?? output.llmOutput?.estimatedTokenUsage;
+    const inputTokens = tokenUsage?.promptTokens ?? 0;
+    const outputTokens = tokenUsage?.completionTokens ?? 0;
+    const firstGenerations = output.generations[0];
+    const firstGen = firstGenerations?.[0];
+    const modelFromResponse = firstGen?.message?.response_metadata?.model_name;
+    const model = modelFromResponse ?? this.options.defaultModel ?? "unknown";
+    const { sessionId, userId, feature } = this.options;
+    this.tracker.track({
+      model,
+      inputTokens,
+      outputTokens,
+      ...sessionId !== void 0 && { sessionId },
+      ...userId !== void 0 && { userId },
+      ...feature !== void 0 && { feature }
+    });
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  TokenwatchCallbackHandler
+});
+//# sourceMappingURL=langchain.cjs.map

package/dist/langchain.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/langchain/index.ts","../src/langchain/handler.ts"],"sourcesContent":["export { TokenwatchCallbackHandler } from './handler.js'\nexport type { TokenwatchCallbackHandlerOptions } from './handler.js'\n","import type { Tracker } from '../types/index.js'\n\n// ─── Local type stubs ─────────────────────────────────────────────────────────\n// These mirror the minimal shape of @langchain/core types so this file compiles\n// without a hard compile-time dependency on @langchain/core.\n\ninterface TokenUsage {\n  promptTokens?: number\n  completionTokens?: number\n}\n\ninterface Generation {\n  message?: {\n    response_metadata?: {\n      model_name?: string\n    }\n  }\n}\n\ninterface LLMResult {\n  llmOutput?: {\n    tokenUsage?: TokenUsage\n    estimatedTokenUsage?: TokenUsage\n  } | null\n  generations: Generation[][]\n}\n\n/**\n * Minimal stub that mirrors the shape of BaseCallbackHandler from @langchain/core.\n * Extend this so the class compiles without the peer dependency being installed.\n * LangChain's callback system is duck-typed and will call the methods that exist.\n */\nabstract class BaseCallbackHandlerStub {\n  abstract name: string\n  handleLLMStart?(...args: unknown[]): Promise<void> | void\n  handleLLMEnd?(output: LLMResult, ...args: unknown[]): Promise<void> | void\n  handleLLMError?(...args: unknown[]): Promise<void> | void\n  handleChainStart?(...args: unknown[]): Promise<void> | void\n  handleChainEnd?(...args: unknown[]): Promise<void> | void\n  handleChainError?(...args: unknown[]): Promise<void> | void\n  handleToolStart?(...args: unknown[]): Promise<void> | void\n  handleToolEnd?(...args: unknown[]): Promise<void> | void\n  handleToolError?(...args: unknown[]): Promise<void> | void\n  handleAgentAction?(...args: unknown[]): Promise<void> | void\n  handleAgentEnd?(...args: unknown[]): Promise<void> | void\n  handleText?(...args: unknown[]): Promise<void> | void\n}\n\n// ─── Public types ─────────────────────────────────────────────────────────────\n\nexport interface TokenwatchCallbackHandlerOptions {\n  /** Fallback model name when the response does not include it. Defaults to 'unknown'. */\n  defaultModel?: string\n  /** Tag all calls from this handler with a session ID */\n  sessionId?: string\n  /** Tag all calls from this handler with a user ID */\n  userId?: string\n  /** Tag all calls from this handler with a product feature name */\n  feature?: string\n}\n\n// ─── Handler ──────────────────────────────────────────────────────────────────\n\n/**\n * LangChain callback handler that automatically tracks LLM cost via tokenwatch.\n *\n * @example\n * import { TokenwatchCallbackHandler } from '@diogonzafe/tokenwatch/langchain'\n *\n * const handler = new TokenwatchCallbackHandler(tracker, { defaultModel: 'gpt-4o' })\n * const llm = new ChatOpenAI({ model: 'gpt-4o', callbacks: [handler] })\n */\nexport class TokenwatchCallbackHandler extends BaseCallbackHandlerStub {\n  name = 'TokenwatchCallbackHandler' as const\n\n  constructor(\n    private readonly tracker: Tracker,\n    private readonly options: TokenwatchCallbackHandlerOptions = {},\n  ) {\n    super()\n  }\n\n  async handleLLMEnd(output: LLMResult): Promise<void> {\n    // Prefer exact tokenUsage, fall back to estimatedTokenUsage (streaming)\n    const tokenUsage = output.llmOutput?.tokenUsage ?? output.llmOutput?.estimatedTokenUsage\n\n    const inputTokens = tokenUsage?.promptTokens ?? 0\n    const outputTokens = tokenUsage?.completionTokens ?? 0\n\n    // noUncheckedIndexedAccess: generations[0] is Generation[] | undefined\n    const firstGenerations = output.generations[0]\n    const firstGen = firstGenerations?.[0]\n    const modelFromResponse = firstGen?.message?.response_metadata?.model_name\n    const model = modelFromResponse ?? this.options.defaultModel ?? 'unknown'\n\n    const { sessionId, userId, feature } = this.options\n\n    this.tracker.track({\n      model,\n      inputTokens,\n      outputTokens,\n      ...(sessionId !== undefined && { sessionId }),\n      ...(userId !== undefined && { userId }),\n      ...(feature !== undefined && { feature }),\n    })\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACgCA,IAAe,0BAAf,MAAuC;AAcvC;AA0BO,IAAM,4BAAN,cAAwC,wBAAwB;AAAA,EAGrE,YACmB,SACA,UAA4C,CAAC,GAC9D;AACA,UAAM;AAHW;AACA;AAAA,EAGnB;AAAA,EAJmB;AAAA,EACA;AAAA,EAJnB,OAAO;AAAA,EASP,MAAM,aAAa,QAAkC;AAEnD,UAAM,aAAa,OAAO,WAAW,cAAc,OAAO,WAAW;AAErE,UAAM,cAAc,YAAY,gBAAgB;AAChD,UAAM,eAAe,YAAY,oBAAoB;AAGrD,UAAM,mBAAmB,OAAO,YAAY,CAAC;AAC7C,UAAM,WAAW,mBAAmB,CAAC;AACrC,UAAM,oBAAoB,UAAU,SAAS,mBAAmB;AAChE,UAAM,QAAQ,qBAAqB,KAAK,QAAQ,gBAAgB;AAEhE,UAAM,EAAE,WAAW,QAAQ,QAAQ,IAAI,KAAK;AAE5C,SAAK,QAAQ,MAAM;AAAA,MACjB;AAAA,MACA;AAAA,MACA;AAAA,MACA,GAAI,cAAc,UAAa,EAAE,UAAU;AAAA,MAC3C,GAAI,WAAW,UAAa,EAAE,OAAO;AAAA,MACrC,GAAI,YAAY,UAAa,EAAE,QAAQ;AAAA,IACzC,CAAC;AAAA,EACH;AACF;","names":[]}

package/dist/langchain.d.cts

@@ -0,0 +1,68 @@
+import { a as Tracker } from './index-CJKk1hHw.cjs';
+
+interface TokenUsage {
+    promptTokens?: number;
+    completionTokens?: number;
+}
+interface Generation {
+    message?: {
+        response_metadata?: {
+            model_name?: string;
+        };
+    };
+}
+interface LLMResult {
+    llmOutput?: {
+        tokenUsage?: TokenUsage;
+        estimatedTokenUsage?: TokenUsage;
+    } | null;
+    generations: Generation[][];
+}
+/**
+ * Minimal stub that mirrors the shape of BaseCallbackHandler from @langchain/core.
+ * Extend this so the class compiles without the peer dependency being installed.
+ * LangChain's callback system is duck-typed and will call the methods that exist.
+ */
+declare abstract class BaseCallbackHandlerStub {
+    abstract name: string;
+    handleLLMStart?(...args: unknown[]): Promise<void> | void;
+    handleLLMEnd?(output: LLMResult, ...args: unknown[]): Promise<void> | void;
+    handleLLMError?(...args: unknown[]): Promise<void> | void;
+    handleChainStart?(...args: unknown[]): Promise<void> | void;
+    handleChainEnd?(...args: unknown[]): Promise<void> | void;
+    handleChainError?(...args: unknown[]): Promise<void> | void;
+    handleToolStart?(...args: unknown[]): Promise<void> | void;
+    handleToolEnd?(...args: unknown[]): Promise<void> | void;
+    handleToolError?(...args: unknown[]): Promise<void> | void;
+    handleAgentAction?(...args: unknown[]): Promise<void> | void;
+    handleAgentEnd?(...args: unknown[]): Promise<void> | void;
+    handleText?(...args: unknown[]): Promise<void> | void;
+}
+interface TokenwatchCallbackHandlerOptions {
+    /** Fallback model name when the response does not include it. Defaults to 'unknown'. */
+    defaultModel?: string;
+    /** Tag all calls from this handler with a session ID */
+    sessionId?: string;
+    /** Tag all calls from this handler with a user ID */
+    userId?: string;
+    /** Tag all calls from this handler with a product feature name */
+    feature?: string;
+}
+/**
+ * LangChain callback handler that automatically tracks LLM cost via tokenwatch.
+ *
+ * @example
+ * import { TokenwatchCallbackHandler } from '@diogonzafe/tokenwatch/langchain'
+ *
+ * const handler = new TokenwatchCallbackHandler(tracker, { defaultModel: 'gpt-4o' })
+ * const llm = new ChatOpenAI({ model: 'gpt-4o', callbacks: [handler] })
+ */
+declare class TokenwatchCallbackHandler extends BaseCallbackHandlerStub {
+    private readonly tracker;
+    private readonly options;
+    name: "TokenwatchCallbackHandler";
+    constructor(tracker: Tracker, options?: TokenwatchCallbackHandlerOptions);
+    handleLLMEnd(output: LLMResult): Promise<void>;
+}
+
+export { TokenwatchCallbackHandler, type TokenwatchCallbackHandlerOptions };

package/dist/langchain.d.ts

@@ -0,0 +1,68 @@
+import { a as Tracker } from './index-CJKk1hHw.js';
+
+interface TokenUsage {
+    promptTokens?: number;
+    completionTokens?: number;
+}
+interface Generation {
+    message?: {
+        response_metadata?: {
+            model_name?: string;
+        };
+    };
+}
+interface LLMResult {
+    llmOutput?: {
+        tokenUsage?: TokenUsage;
+        estimatedTokenUsage?: TokenUsage;
+    } | null;
+    generations: Generation[][];
+}
+/**
+ * Minimal stub that mirrors the shape of BaseCallbackHandler from @langchain/core.
+ * Extend this so the class compiles without the peer dependency being installed.
+ * LangChain's callback system is duck-typed and will call the methods that exist.
+ */
+declare abstract class BaseCallbackHandlerStub {
+    abstract name: string;
+    handleLLMStart?(...args: unknown[]): Promise<void> | void;
+    handleLLMEnd?(output: LLMResult, ...args: unknown[]): Promise<void> | void;
+    handleLLMError?(...args: unknown[]): Promise<void> | void;
+    handleChainStart?(...args: unknown[]): Promise<void> | void;
+    handleChainEnd?(...args: unknown[]): Promise<void> | void;
+    handleChainError?(...args: unknown[]): Promise<void> | void;
+    handleToolStart?(...args: unknown[]): Promise<void> | void;
+    handleToolEnd?(...args: unknown[]): Promise<void> | void;
+    handleToolError?(...args: unknown[]): Promise<void> | void;
+    handleAgentAction?(...args: unknown[]): Promise<void> | void;
+    handleAgentEnd?(...args: unknown[]): Promise<void> | void;
+    handleText?(...args: unknown[]): Promise<void> | void;
+}
+interface TokenwatchCallbackHandlerOptions {
+    /** Fallback model name when the response does not include it. Defaults to 'unknown'. */
+    defaultModel?: string;
+    /** Tag all calls from this handler with a session ID */
+    sessionId?: string;
+    /** Tag all calls from this handler with a user ID */
+    userId?: string;
+    /** Tag all calls from this handler with a product feature name */
+    feature?: string;
+}
+/**
+ * LangChain callback handler that automatically tracks LLM cost via tokenwatch.
+ *
+ * @example
+ * import { TokenwatchCallbackHandler } from '@diogonzafe/tokenwatch/langchain'
+ *
+ * const handler = new TokenwatchCallbackHandler(tracker, { defaultModel: 'gpt-4o' })
+ * const llm = new ChatOpenAI({ model: 'gpt-4o', callbacks: [handler] })
+ */
+declare class TokenwatchCallbackHandler extends BaseCallbackHandlerStub {
+    private readonly tracker;
+    private readonly options;
+    name: "TokenwatchCallbackHandler";
+    constructor(tracker: Tracker, options?: TokenwatchCallbackHandlerOptions);
+    handleLLMEnd(output: LLMResult): Promise<void>;
+}
+
+export { TokenwatchCallbackHandler, type TokenwatchCallbackHandlerOptions };

package/dist/langchain.js

@@ -0,0 +1,35 @@
+// src/langchain/handler.ts
+var BaseCallbackHandlerStub = class {
+};
+var TokenwatchCallbackHandler = class extends BaseCallbackHandlerStub {
+  constructor(tracker, options = {}) {
+    super();
+    this.tracker = tracker;
+    this.options = options;
+  }
+  tracker;
+  options;
+  name = "TokenwatchCallbackHandler";
+  async handleLLMEnd(output) {
+    const tokenUsage = output.llmOutput?.tokenUsage ?? output.llmOutput?.estimatedTokenUsage;
+    const inputTokens = tokenUsage?.promptTokens ?? 0;
+    const outputTokens = tokenUsage?.completionTokens ?? 0;
+    const firstGenerations = output.generations[0];
+    const firstGen = firstGenerations?.[0];
+    const modelFromResponse = firstGen?.message?.response_metadata?.model_name;
+    const model = modelFromResponse ?? this.options.defaultModel ?? "unknown";
+    const { sessionId, userId, feature } = this.options;
+    this.tracker.track({
+      model,
+      inputTokens,
+      outputTokens,
+      ...sessionId !== void 0 && { sessionId },
+      ...userId !== void 0 && { userId },
+      ...feature !== void 0 && { feature }
+    });
+  }
+};
+export {
+  TokenwatchCallbackHandler
+};
+//# sourceMappingURL=langchain.js.map

package/dist/langchain.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/langchain/handler.ts"],"sourcesContent":["import type { Tracker } from '../types/index.js'\n\n// ─── Local type stubs ─────────────────────────────────────────────────────────\n// These mirror the minimal shape of @langchain/core types so this file compiles\n// without a hard compile-time dependency on @langchain/core.\n\ninterface TokenUsage {\n  promptTokens?: number\n  completionTokens?: number\n}\n\ninterface Generation {\n  message?: {\n    response_metadata?: {\n      model_name?: string\n    }\n  }\n}\n\ninterface LLMResult {\n  llmOutput?: {\n    tokenUsage?: TokenUsage\n    estimatedTokenUsage?: TokenUsage\n  } | null\n  generations: Generation[][]\n}\n\n/**\n * Minimal stub that mirrors the shape of BaseCallbackHandler from @langchain/core.\n * Extend this so the class compiles without the peer dependency being installed.\n * LangChain's callback system is duck-typed and will call the methods that exist.\n */\nabstract class BaseCallbackHandlerStub {\n  abstract name: string\n  handleLLMStart?(...args: unknown[]): Promise<void> | void\n  handleLLMEnd?(output: LLMResult, ...args: unknown[]): Promise<void> | void\n  handleLLMError?(...args: unknown[]): Promise<void> | void\n  handleChainStart?(...args: unknown[]): Promise<void> | void\n  handleChainEnd?(...args: unknown[]): Promise<void> | void\n  handleChainError?(...args: unknown[]): Promise<void> | void\n  handleToolStart?(...args: unknown[]): Promise<void> | void\n  handleToolEnd?(...args: unknown[]): Promise<void> | void\n  handleToolError?(...args: unknown[]): Promise<void> | void\n  handleAgentAction?(...args: unknown[]): Promise<void> | void\n  handleAgentEnd?(...args: unknown[]): Promise<void> | void\n  handleText?(...args: unknown[]): Promise<void> | void\n}\n\n// ─── Public types ─────────────────────────────────────────────────────────────\n\nexport interface TokenwatchCallbackHandlerOptions {\n  /** Fallback model name when the response does not include it. Defaults to 'unknown'. */\n  defaultModel?: string\n  /** Tag all calls from this handler with a session ID */\n  sessionId?: string\n  /** Tag all calls from this handler with a user ID */\n  userId?: string\n  /** Tag all calls from this handler with a product feature name */\n  feature?: string\n}\n\n// ─── Handler ──────────────────────────────────────────────────────────────────\n\n/**\n * LangChain callback handler that automatically tracks LLM cost via tokenwatch.\n *\n * @example\n * import { TokenwatchCallbackHandler } from '@diogonzafe/tokenwatch/langchain'\n *\n * const handler = new TokenwatchCallbackHandler(tracker, { defaultModel: 'gpt-4o' })\n * const llm = new ChatOpenAI({ model: 'gpt-4o', callbacks: [handler] })\n */\nexport class TokenwatchCallbackHandler extends BaseCallbackHandlerStub {\n  name = 'TokenwatchCallbackHandler' as const\n\n  constructor(\n    private readonly tracker: Tracker,\n    private readonly options: TokenwatchCallbackHandlerOptions = {},\n  ) {\n    super()\n  }\n\n  async handleLLMEnd(output: LLMResult): Promise<void> {\n    // Prefer exact tokenUsage, fall back to estimatedTokenUsage (streaming)\n    const tokenUsage = output.llmOutput?.tokenUsage ?? output.llmOutput?.estimatedTokenUsage\n\n    const inputTokens = tokenUsage?.promptTokens ?? 0\n    const outputTokens = tokenUsage?.completionTokens ?? 0\n\n    // noUncheckedIndexedAccess: generations[0] is Generation[] | undefined\n    const firstGenerations = output.generations[0]\n    const firstGen = firstGenerations?.[0]\n    const modelFromResponse = firstGen?.message?.response_metadata?.model_name\n    const model = modelFromResponse ?? this.options.defaultModel ?? 'unknown'\n\n    const { sessionId, userId, feature } = this.options\n\n    this.tracker.track({\n      model,\n      inputTokens,\n      outputTokens,\n      ...(sessionId !== undefined && { sessionId }),\n      ...(userId !== undefined && { userId }),\n      ...(feature !== undefined && { feature }),\n    })\n  }\n}\n"],"mappings":";AAgCA,IAAe,0BAAf,MAAuC;AAcvC;AA0BO,IAAM,4BAAN,cAAwC,wBAAwB;AAAA,EAGrE,YACmB,SACA,UAA4C,CAAC,GAC9D;AACA,UAAM;AAHW;AACA;AAAA,EAGnB;AAAA,EAJmB;AAAA,EACA;AAAA,EAJnB,OAAO;AAAA,EASP,MAAM,aAAa,QAAkC;AAEnD,UAAM,aAAa,OAAO,WAAW,cAAc,OAAO,WAAW;AAErE,UAAM,cAAc,YAAY,gBAAgB;AAChD,UAAM,eAAe,YAAY,oBAAoB;AAGrD,UAAM,mBAAmB,OAAO,YAAY,CAAC;AAC7C,UAAM,WAAW,mBAAmB,CAAC;AACrC,UAAM,oBAAoB,UAAU,SAAS,mBAAmB;AAChE,UAAM,QAAQ,qBAAqB,KAAK,QAAQ,gBAAgB;AAEhE,UAAM,EAAE,WAAW,QAAQ,QAAQ,IAAI,KAAK;AAE5C,SAAK,QAAQ,MAAM;AAAA,MACjB;AAAA,MACA;AAAA,MACA;AAAA,MACA,GAAI,cAAc,UAAa,EAAE,UAAU;AAAA,MAC3C,GAAI,WAAW,UAAa,EAAE,OAAO;AAAA,MACrC,GAAI,YAAY,UAAa,EAAE,QAAQ;AAAA,IACzC,CAAC;AAAA,EACH;AACF;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diogonzafe/tokenwatch",
-  "version": "0.2.1",
+  "version": "0.5.0",
   "description": "Transparent wrapper to track LLM API costs in real-time by session, user and model",
   "author": "diogonzafe",
   "license": "MIT",
@@ -18,6 +18,11 @@
       "types": "./dist/adapters.d.ts",
       "import": "./dist/adapters.js",
       "require": "./dist/adapters.cjs"
+    },
+    "./langchain": {
+      "types": "./dist/langchain.d.ts",
+      "import": "./dist/langchain.js",
+      "require": "./dist/langchain.cjs"
     }
   },
   "bin": {
@@ -52,7 +57,8 @@
     "mongodb": ">=6.0.0",
     "mysql2": ">=3.0.0",
     "openai": ">=4.68.0",
-    "pg": ">=8.0.0"
+    "pg": ">=8.0.0",
+    "@langchain/core": ">=0.1.0"
   },
   "peerDependenciesMeta": {
     "openai": {
@@ -75,6 +81,9 @@
     },
     "mongodb": {
       "optional": true
+    },
+    "@langchain/core": {
+      "optional": true
     }
   },
   "keywords": [