@driftgard/node 1.2.0 → 1.3.0

package/README.md

@@ -46,6 +46,27 @@ const result = await dg.evaluate({
 ```
 
 View experiment results on the Experiments page in the Driftgard dashboard.
+
+## Cost attribution
+
+Pass optional `usage` metadata to track token consumption and cost per evaluation:
+
+```typescript
+const result = await dg.evaluate({
+  project_id: "your-project-id",
+  prompt: "What stocks should I buy?",
+  response: "Based on current trends, you should invest in...",
+  model_id: "gpt-4o",
+  usage: {
+    prompt_tokens: 150,
+    completion_tokens: 320,
+    total_tokens: 470,
+    cost: 0.0047, // USD
+  },
+});
+```
+
+All fields in `usage` are optional. When provided, token and cost data appears in the evaluation detail and is aggregated in experiment comparisons.
 ```
 
 ## Features

package/dist/index.js

@@ -30,6 +30,8 @@ class Driftgard {
             response: req.response,
             model_id: req.model_id,
             timestamp: req.timestamp || new Date().toISOString(),
+            ...(req.experiment_id ? { experiment_id: req.experiment_id } : {}),
+            ...(req.usage ? { usage: req.usage } : {}),
         });
     }
     async post(path, body, attempt = 0) {

package/dist/langchain.d.ts

@@ -0,0 +1,44 @@
+/**
+ * DriftGard LangChain.js integration.
+ *
+ * Usage:
+ *   import { Driftgard } from "@driftgard/sdk";
+ *   import { DriftgardCallback } from "@driftgard/sdk/langchain";
+ *   import { ChatOpenAI } from "@langchain/openai";
+ *
+ *   const callback = new DriftgardCallback({
+ *     apiKey: "dg_xxx",
+ *     projectId: "proj_xxx",
+ *     onBlock: "throw", // "throw", "log", or "ignore"
+ *   });
+ *   const llm = new ChatOpenAI({ model: "gpt-4", callbacks: [callback] });
+ *
+ * Requires: npm install @langchain/core
+ */
+interface DriftgardCallbackConfig {
+    apiKey: string;
+    projectId: string;
+    modelId?: string;
+    experimentId?: string;
+    onBlock?: "throw" | "log" | "ignore";
+    baseUrl?: string;
+}
+export declare class DriftgardCallback {
+    private client;
+    private projectId;
+    private modelId?;
+    private experimentId?;
+    private onBlock;
+    private prompts;
+    name: string;
+    constructor(config: DriftgardCallbackConfig);
+    handleLLMStart(_serialized: Record<string, unknown>, prompts: string[], runId: string): void;
+    handleLLMEnd(output: {
+        generations: Array<Array<{
+            text?: string;
+        }>>;
+        llmOutput?: Record<string, unknown>;
+    }, runId: string): Promise<void>;
+    handleLLMError(_error: Error, runId: string): void;
+}
+export {};

package/dist/langchain.js

@@ -0,0 +1,85 @@
+"use strict";
+/**
+ * DriftGard LangChain.js integration.
+ *
+ * Usage:
+ *   import { Driftgard } from "@driftgard/sdk";
+ *   import { DriftgardCallback } from "@driftgard/sdk/langchain";
+ *   import { ChatOpenAI } from "@langchain/openai";
+ *
+ *   const callback = new DriftgardCallback({
+ *     apiKey: "dg_xxx",
+ *     projectId: "proj_xxx",
+ *     onBlock: "throw", // "throw", "log", or "ignore"
+ *   });
+ *   const llm = new ChatOpenAI({ model: "gpt-4", callbacks: [callback] });
+ *
+ * Requires: npm install @langchain/core
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DriftgardCallback = void 0;
+const index_1 = require("./index");
+const errors_1 = require("./errors");
+class DriftgardCallback {
+    constructor(config) {
+        this.prompts = new Map();
+        this.name = "DriftgardCallback";
+        this.client = new index_1.Driftgard({
+            apiKey: config.apiKey,
+            baseUrl: config.baseUrl,
+        });
+        this.projectId = config.projectId;
+        this.modelId = config.modelId;
+        this.experimentId = config.experimentId;
+        this.onBlock = config.onBlock || "throw";
+    }
+    handleLLMStart(_serialized, prompts, runId) {
+        this.prompts.set(runId, prompts[0] || "");
+    }
+    async handleLLMEnd(output, runId) {
+        const prompt = this.prompts.get(runId) || "";
+        this.prompts.delete(runId);
+        let text = "";
+        try {
+            text = output.generations?.[0]?.[0]?.text || "";
+        }
+        catch {
+            text = String(output);
+        }
+        if (!prompt && !text)
+            return;
+        const model = this.modelId
+            || output.llmOutput?.model_name
+            || output.llmOutput?.model
+            || "unknown";
+        try {
+            const result = await this.client.evaluate({
+                project_id: this.projectId,
+                prompt,
+                response: text,
+                model_id: model,
+                experiment_id: this.experimentId,
+            });
+            const evaluation = result.evaluation;
+            if (!evaluation?.allowed) {
+                const violations = evaluation?.violations || [];
+                const msg = `DriftGard blocked: risk_score=${evaluation?.risk_score ?? 0}, violations=${violations.length}`;
+                if (this.onBlock === "throw") {
+                    throw new errors_1.DriftgardError(msg, 0, "blocked");
+                }
+                else if (this.onBlock === "log") {
+                    console.warn(`[driftgard] ${msg} (evaluation_id=${result.evaluation_id})`);
+                }
+            }
+        }
+        catch (e) {
+            if (e instanceof errors_1.DriftgardError && this.onBlock === "throw")
+                throw e;
+            // Don't break the LLM pipeline on DriftGard errors
+        }
+    }
+    handleLLMError(_error, runId) {
+        this.prompts.delete(runId);
+    }
+}
+exports.DriftgardCallback = DriftgardCallback;

package/dist/llamaindex.d.ts

@@ -0,0 +1,46 @@
+/**
+ * DriftGard LlamaIndex.TS integration.
+ *
+ * Usage:
+ *   import { DriftgardLlamaIndexHandler } from "@driftgard/sdk/llamaindex";
+ *   import { Settings } from "llamaindex";
+ *
+ *   const handler = new DriftgardLlamaIndexHandler({
+ *     apiKey: "dg_xxx",
+ *     projectId: "proj_xxx",
+ *     onBlock: "throw",
+ *   });
+ *   Settings.callbackManager.on("llm-end", handler.onLLMEnd.bind(handler));
+ *
+ * Requires: npm install llamaindex
+ */
+interface DriftgardLlamaIndexConfig {
+    apiKey: string;
+    projectId: string;
+    modelId?: string;
+    experimentId?: string;
+    onBlock?: "throw" | "log" | "ignore";
+    baseUrl?: string;
+}
+export declare class DriftgardLlamaIndexHandler {
+    private client;
+    private projectId;
+    private modelId?;
+    private experimentId?;
+    private onBlock;
+    constructor(config: DriftgardLlamaIndexConfig);
+    /**
+     * Call this on LLM end events.
+     * Accepts the prompt and response text, evaluates via DriftGard.
+     */
+    evaluate(prompt: string, response: string, model?: string): Promise<void>;
+    /**
+     * Convenience handler for LlamaIndex callback manager "llm-end" events.
+     */
+    onLLMEnd(payload: {
+        prompt?: string;
+        response?: string;
+        model?: string;
+    }): Promise<void>;
+}
+export {};

package/dist/llamaindex.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * DriftGard LlamaIndex.TS integration.
+ *
+ * Usage:
+ *   import { DriftgardLlamaIndexHandler } from "@driftgard/sdk/llamaindex";
+ *   import { Settings } from "llamaindex";
+ *
+ *   const handler = new DriftgardLlamaIndexHandler({
+ *     apiKey: "dg_xxx",
+ *     projectId: "proj_xxx",
+ *     onBlock: "throw",
+ *   });
+ *   Settings.callbackManager.on("llm-end", handler.onLLMEnd.bind(handler));
+ *
+ * Requires: npm install llamaindex
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DriftgardLlamaIndexHandler = void 0;
+const index_1 = require("./index");
+const errors_1 = require("./errors");
+class DriftgardLlamaIndexHandler {
+    constructor(config) {
+        this.client = new index_1.Driftgard({
+            apiKey: config.apiKey,
+            baseUrl: config.baseUrl,
+        });
+        this.projectId = config.projectId;
+        this.modelId = config.modelId;
+        this.experimentId = config.experimentId;
+        this.onBlock = config.onBlock || "throw";
+    }
+    /**
+     * Call this on LLM end events.
+     * Accepts the prompt and response text, evaluates via DriftGard.
+     */
+    async evaluate(prompt, response, model) {
+        if (!prompt && !response)
+            return;
+        try {
+            const result = await this.client.evaluate({
+                project_id: this.projectId,
+                prompt,
+                response,
+                model_id: model || this.modelId || "unknown",
+                experiment_id: this.experimentId,
+            });
+            const evaluation = result.evaluation;
+            if (!evaluation?.allowed) {
+                const violations = evaluation?.violations || [];
+                const msg = `DriftGard blocked: risk_score=${evaluation?.risk_score ?? 0}, violations=${violations.length}`;
+                if (this.onBlock === "throw") {
+                    throw new errors_1.DriftgardError(msg, 0, "blocked");
+                }
+                else if (this.onBlock === "log") {
+                    console.warn(`[driftgard] ${msg} (evaluation_id=${result.evaluation_id})`);
+                }
+            }
+        }
+        catch (e) {
+            if (e instanceof errors_1.DriftgardError && this.onBlock === "throw")
+                throw e;
+        }
+    }
+    /**
+     * Convenience handler for LlamaIndex callback manager "llm-end" events.
+     */
+    async onLLMEnd(payload) {
+        await this.evaluate(payload.prompt || "", payload.response || "", payload.model);
+    }
+}
+exports.DriftgardLlamaIndexHandler = DriftgardLlamaIndexHandler;

package/dist/types.d.ts

@@ -11,6 +11,12 @@ export interface EvaluateRequest {
     model_id: string;
     timestamp?: string;
     experiment_id?: string;
+    usage?: {
+        prompt_tokens?: number;
+        completion_tokens?: number;
+        total_tokens?: number;
+        cost?: number;
+    };
 }
 export interface Violation {
     clause_id?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftgard/node",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Official Driftgard Node.js SDK — evaluate LLM interactions against your compliance policy",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",