@zansn/langchain 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0
+
+Initial release: LangChain adapter for Zansn.
+
+- Added `createZansnCollector` returning a LangChain `BaseCallbackHandler` and a `finalize()` that runs the local Zansn assurance checks and returns a `ZansnEvidencePack`.
+- Recorded tool calls (start joined to end/error by run id), token usage, and model spans from the callback stream.
+- Added `usageFromLLMResult` to read provider token usage across `llmOutput.tokenUsage`, `llmOutput.usage`, and message `usage_metadata`.
+- Exported `ZansnCallbackHandler` for direct use.

package/LICENSE

@@ -0,0 +1,18 @@
+Apache License
+Version 2.0, January 2004
+https://www.apache.org/licenses/
+
+Copyright 2026 Zansn Labs
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+

package/README.md

@@ -0,0 +1,99 @@
+# @zansn/langchain
+
+[![Zansn Labs AI assurance infrastructure](https://www.zansn.ai/og-image.jpg?v=0.1.0)](https://zansn.ai)
+
+Turn a [LangChain](https://js.langchain.com) agent run into a portable Zansn evidence pack. Capture traces, tool calls, cost, and a readiness verdict with a callback handler.
+
+Website: https://zansn.ai
+
+LangChain surfaces a run through callbacks. This adapter gives you a `BaseCallbackHandler` that records tool calls, token usage, and model/chain spans as they happen, then hands the assembled run to the [`zansn`](https://www.npmjs.com/package/zansn) assurance engine, which runs the same local policy, privacy, cost, latency, and readiness checks and returns the same evidence pack. It runs locally and transmits nothing.
+
+## Install
+
+```bash
+npm install @zansn/langchain zansn @langchain/core
+```
+
+`@langchain/core` and `zansn` are peer dependencies, so you control their versions.
+
+## Quickstart
+
+```ts
+import { createZansnCollector } from "@zansn/langchain";
+
+// 1. create a collector (holds this run's traces, tool calls, usage)
+const zansn = createZansnCollector({
+  projectId: "support-agent",
+  policy: { blockedTools: ["delete_record"], maxLatencyMs: 8000 },
+});
+
+// 2. pass its handler in the callbacks of any LangChain run
+await agentExecutor.invoke(
+  { input: "Look up case CASE-40917 and summarise the billing issue." },
+  { callbacks: [zansn.handler] },
+);
+
+// 3. seal a portable evidence pack from the captured run
+const pack = await zansn.finalize();
+
+console.log(pack.summary.readiness); // "ready" | "review" | "blocked"
+```
+
+The pack is a `ZansnEvidencePack`: readiness, findings, traces, cost, and latency. Export it as JSON or Markdown, attach it to a pull request, or later ingest it into hosted Zansn.
+
+## API
+
+### `createZansnCollector(options)`
+
+Returns a collector for one LangChain run.
+
+| Option | Type | Notes |
+| --- | --- | --- |
+| `projectId` | `string` | Required. Stable id recorded on the pack. |
+| `policy` | `ZansnPolicy` | Blocked/allowed tools, sensitive-data patterns, cost and latency ceilings. |
+| `experimentId`, `name`, `description` | `string` | Recorded on the pack. |
+| `metadata` | `object` | Merged onto the pack metadata. |
+| `expected`, `score` | | Optional expected output and custom scorer. |
+
+The collector exposes:
+
+- `handler`: a LangChain `BaseCallbackHandler`. Pass it in the `callbacks` array on your run.
+- `finalize({ output })`: returns a `Promise<ZansnEvidencePack>`.
+- `toolCallCount`: tool calls captured so far.
+
+`ZansnCallbackHandler` and `usageFromLLMResult` are also exported for direct use.
+
+## What is captured
+
+| LangChain callback | Zansn |
+| --- | --- |
+| `handleToolStart` + `handleToolEnd` / `handleToolError` | `ZansnToolCall` (name, args, result, status) |
+| `handleLLMEnd` (LLMResult usage) | `ZansnUsage` + a model span |
+| `handleChainEnd` | final output |
+
+Token usage is read across the places LangChain providers report it (`llmOutput.tokenUsage`, `llmOutput.usage`, message `usage_metadata`), and missing fields are tolerated.
+
+`finalize()` feeds the assembled result into `ZansnClient.runEvaluation` as a single completed task, so every existing check applies with no new assurance code.
+
+## Fail a pull request when a run is not deployment-ready
+
+```ts
+const pack = await zansn.finalize();
+if (pack.summary.readiness === "blocked") {
+  console.error("Deployment blocked by Zansn:");
+  for (const f of pack.findings) console.error(`  [${f.severity}] ${f.kind}: ${f.title}`);
+  process.exit(1);
+}
+```
+
+## What is and is not in scope
+
+This package **produces** a portable evidence pack locally. It does not store, compare, or govern packs. Hosted ingestion, run-over-run comparison, team workspaces, and enterprise policy packs are part of the commercial Zansn Assurance Control Plane. You keep calling the same local API; the paid tier adds the evidence graph.
+
+## Example
+
+A runnable, no-API-key demo lives in [`examples/langchain.mjs`](./examples/langchain.mjs).
+
+## License
+
+Apache-2.0. See [LICENSE](./LICENSE).

package/SECURITY.md

@@ -0,0 +1,15 @@
+# Security Policy
+
+## Supported Versions
+
+`@zansn/langchain` is pre-1.0 software. Security fixes will target the latest published minor version.
+
+## Reporting a Vulnerability
+
+Report security issues through https://zansn.ai/contact.
+
+Do not include secrets, private customer data, or sensitive production traces in public issues or examples.
+
+## Scope
+
+`@zansn/langchain` runs locally and does not transmit data to Zansn Labs. It reads the callbacks your LangChain run already emits and turns them into a local evidence pack. Future hosted or enterprise products that ingest those packs have separate security documentation, data-retention controls, and disclosure channels.

package/dist/index.d.ts

@@ -0,0 +1,90 @@
+import { BaseCallbackHandler } from '@langchain/core/callbacks/base';
+import { LLMResult } from '@langchain/core/outputs';
+import { Serialized } from '@langchain/core/load/serializable';
+import { ZansnToolCall, ZansnTraceInput, ZansnUsage, ZansnEvidencePack, ZansnPolicy, ZansnMetadata, ZansnAgentResult, ZansnClient } from 'zansn';
+export { ZansnAgentResult, ZansnClient, ZansnEvidencePack, ZansnPolicy, ZansnToolCall, ZansnTraceInput, ZansnUsage } from 'zansn';
+
+/**
+ * @zansn/langchain
+ *
+ * Turn a LangChain agent run into a portable Zansn evidence pack.
+ *
+ * LangChain surfaces a run through a callback handler. This adapter provides a
+ * `BaseCallbackHandler` that records tool calls, token usage, and model/chain
+ * spans as they happen, then `finalize()` hands the assembled run to the
+ * existing `zansn` engine, which applies the same local policy, privacy, cost,
+ * latency, and readiness checks and returns the same `ZansnEvidencePack`.
+ *
+ * This package writes NO assurance logic of its own. It is a translation layer:
+ * LangChain callbacks in, Zansn types out, `ZansnClient.runEvaluation` does the
+ * rest. It runs locally and transmits nothing.
+ */
+
+/**
+ * Extract token usage from an LLMResult across the several places LangChain
+ * providers report it (llmOutput.tokenUsage, llmOutput.usage, or the message's
+ * usage_metadata). Returns a partial ZansnUsage; missing fields are omitted.
+ */
+declare function usageFromLLMResult(output: LLMResult): ZansnUsage;
+/** Options for {@link createZansnCollector}. */
+type ZansnCollectorOptions = {
+    /** Stable project identifier for the evidence pack (required). */
+    projectId: string;
+    experimentId?: string;
+    name?: string;
+    description?: string;
+    /** Local assurance policy applied by the zansn engine at finalize(). */
+    policy?: ZansnPolicy;
+    metadata?: ZansnMetadata;
+    score?: (args: {
+        result: ZansnAgentResult<string>;
+    }) => Promise<number> | number;
+    expected?: unknown;
+    /** Override the ZansnClient (e.g. to set a default policy/organization). */
+    client?: ZansnClient;
+};
+/**
+ * A collector accumulates one LangChain run (via its {@link ZansnCallbackHandler})
+ * and turns it into a Zansn evidence pack.
+ */
+type ZansnCollector = {
+    /** Pass this in the LangChain `callbacks` array on your run. */
+    handler: BaseCallbackHandler;
+    /**
+     * Seal the run into a ZansnEvidencePack. Optionally pass the final output text
+     * (otherwise the last chain/LLM output text captured is used).
+     */
+    finalize: (final?: {
+        output?: string;
+    }) => Promise<ZansnEvidencePack<string>>;
+    /** Tool calls captured so far. */
+    readonly toolCallCount: number;
+};
+/**
+ * Internal callback handler that records a LangChain run into Zansn primitives.
+ */
+declare class ZansnCallbackHandler extends BaseCallbackHandler {
+    name: string;
+    readonly toolCalls: ZansnToolCall[];
+    readonly traces: ZansnTraceInput[];
+    readonly usage: ZansnUsage;
+    lastText: string;
+    private readonly pending;
+    private llmStep;
+    handleToolStart(tool: Serialized, input: string, runId: string, _parentRunId?: string, _tags?: string[], _metadata?: Record<string, unknown>, _runName?: string, toolCallId?: string): void;
+    handleToolEnd(output: unknown, runId: string): void;
+    handleToolError(err: unknown, runId: string): void;
+    handleLLMEnd(output: LLMResult): void;
+    handleChainEnd(outputs: unknown): void;
+}
+/**
+ * Create a Zansn collector for a single LangChain run.
+ *
+ * @example
+ * const zansn = createZansnCollector({ projectId: "support-agent" });
+ * await agentExecutor.invoke({ input }, { callbacks: [zansn.handler] });
+ * const pack = await zansn.finalize();
+ */
+declare function createZansnCollector(options: ZansnCollectorOptions): ZansnCollector;
+
+export { ZansnCallbackHandler, type ZansnCollector, type ZansnCollectorOptions, createZansnCollector, usageFromLLMResult };

package/dist/index.js

@@ -0,0 +1,158 @@
+// src/index.ts
+import { BaseCallbackHandler } from "@langchain/core/callbacks/base";
+import {
+  ZansnClient
+} from "zansn";
+function toolNameFrom(serialized) {
+  if (!serialized || typeof serialized !== "object") return "tool";
+  const s = serialized;
+  if (typeof s.name === "string") return s.name;
+  if (typeof s.kwargs?.name === "string") return s.kwargs.name;
+  if (Array.isArray(s.id) && s.id.length > 0) {
+    const last = s.id[s.id.length - 1];
+    if (typeof last === "string") return last;
+  }
+  if (typeof s.id === "string") return s.id;
+  return "tool";
+}
+function usageFromLLMResult(output) {
+  const candidates = [];
+  const llmOut = output.llmOutput;
+  if (llmOut && typeof llmOut === "object") {
+    for (const key of ["tokenUsage", "usage", "estimatedTokenUsage"]) {
+      const v = llmOut[key];
+      if (v && typeof v === "object") candidates.push(v);
+    }
+  }
+  const firstGen = output.generations?.[0]?.[0];
+  const firstMessageUsage = firstGen?.message?.usage_metadata;
+  if (firstMessageUsage && typeof firstMessageUsage === "object") {
+    candidates.push(firstMessageUsage);
+  }
+  const usage = {};
+  for (const c of candidates) {
+    const input = numeric(c.promptTokens ?? c.input_tokens ?? c.inputTokens);
+    const out = numeric(c.completionTokens ?? c.output_tokens ?? c.outputTokens);
+    const total = numeric(c.totalTokens ?? c.total_tokens);
+    if (input !== void 0 && usage.inputTokens === void 0) usage.inputTokens = input;
+    if (out !== void 0 && usage.outputTokens === void 0) usage.outputTokens = out;
+    if (total !== void 0 && usage.totalTokens === void 0) usage.totalTokens = total;
+  }
+  return usage;
+}
+function numeric(v) {
+  return typeof v === "number" && Number.isFinite(v) ? v : void 0;
+}
+function accumulateUsage(into, add) {
+  if (add.inputTokens !== void 0) into.inputTokens = (into.inputTokens ?? 0) + add.inputTokens;
+  if (add.outputTokens !== void 0) into.outputTokens = (into.outputTokens ?? 0) + add.outputTokens;
+  if (add.totalTokens !== void 0) into.totalTokens = (into.totalTokens ?? 0) + add.totalTokens;
+}
+var ZansnCallbackHandler = class extends BaseCallbackHandler {
+  name = "ZansnCallbackHandler";
+  toolCalls = [];
+  traces = [];
+  usage = {};
+  lastText = "";
+  // toolCallId (or runId) -> index in toolCalls, so end can attach the result.
+  pending = /* @__PURE__ */ new Map();
+  llmStep = 0;
+  handleToolStart(tool, input, runId, _parentRunId, _tags, _metadata, _runName, toolCallId) {
+    const name = toolNameFrom(tool);
+    const call = { id: toolCallId ?? runId, name, status: "ok" };
+    if (input !== void 0) call.arguments = input;
+    const index = this.toolCalls.push(call) - 1;
+    this.pending.set(runId, index);
+    if (toolCallId) this.pending.set(toolCallId, index);
+  }
+  handleToolEnd(output, runId) {
+    const index = this.pending.get(runId);
+    if (index === void 0) return;
+    const call = this.toolCalls[index];
+    if (!call) return;
+    call.result = output;
+  }
+  handleToolError(err, runId) {
+    const index = this.pending.get(runId);
+    if (index === void 0) return;
+    const call = this.toolCalls[index];
+    if (!call) return;
+    call.status = "error";
+    call.result = err instanceof Error ? err.message : String(err);
+  }
+  handleLLMEnd(output) {
+    accumulateUsage(this.usage, usageFromLLMResult(output));
+    const attributes = {
+      "zansn.step.index": this.llmStep,
+      "gen_ai.system": "langchain"
+    };
+    this.traces.push({
+      type: "model",
+      name: `langchain.llm.${this.llmStep}`,
+      attributes
+    });
+    this.llmStep += 1;
+  }
+  handleChainEnd(outputs) {
+    if (typeof outputs === "string") {
+      this.lastText = outputs;
+    } else if (outputs && typeof outputs === "object") {
+      const rec = outputs;
+      const text = rec.output ?? rec.text ?? rec.result;
+      if (typeof text === "string") this.lastText = text;
+    }
+  }
+};
+function createZansnCollector(options) {
+  if (typeof options.projectId !== "string" || options.projectId.trim().length === 0) {
+    throw new Error("createZansnCollector requires a non-empty projectId.");
+  }
+  const client = options.client ?? new ZansnClient();
+  const handler = new ZansnCallbackHandler();
+  const finalize = async (final) => {
+    const agentResult = {
+      output: final?.output ?? handler.lastText,
+      toolCalls: handler.toolCalls,
+      usage: handler.usage,
+      traces: handler.traces
+    };
+    const runOptions = {
+      projectId: options.projectId,
+      tasks: [
+        {
+          id: "langchain-run",
+          input: { source: "langchain", toolCalls: handler.toolCalls.length },
+          ...options.expected !== void 0 ? { expected: options.expected } : {}
+        }
+      ],
+      execute: async () => agentResult,
+      metadata: {
+        ...options.metadata,
+        "zansn.adapter": "@zansn/langchain",
+        "zansn.source": "langchain"
+      }
+    };
+    if (options.experimentId !== void 0) runOptions.experimentId = options.experimentId;
+    if (options.name !== void 0) runOptions.name = options.name;
+    if (options.description !== void 0) runOptions.description = options.description;
+    if (options.policy !== void 0) runOptions.policy = options.policy;
+    if (options.score !== void 0) {
+      const userScore = options.score;
+      runOptions.score = ({ result }) => userScore({ result });
+    }
+    return client.runEvaluation(runOptions);
+  };
+  return {
+    handler,
+    finalize,
+    get toolCallCount() {
+      return handler.toolCalls.length;
+    }
+  };
+}
+export {
+  ZansnCallbackHandler,
+  ZansnClient,
+  createZansnCollector,
+  usageFromLLMResult
+};

package/examples/langchain.mjs

@@ -0,0 +1,82 @@
+/**
+ * @zansn/langchain: LangChain example
+ *
+ * Shows how to capture a LangChain agent run as a Zansn evidence pack.
+ *
+ * This file runs standalone with no API key: it drives the collector's callback
+ * handler with recorded callbacks (the exact shape LangChain emits) so you can
+ * see the full evidence pack without calling a model. The commented block shows
+ * the real integration.
+ *
+ *   node examples/langchain.mjs
+ */
+
+import { createZansnCollector } from "@zansn/langchain";
+import { exportEvidencePackMarkdown } from "zansn";
+
+// ── The real integration (uncomment with your own agent) ────────────────────
+//
+// import { AgentExecutor } from "langchain/agents";
+//
+// const zansn = createZansnCollector({
+//   projectId: "support-agent",
+//   policy: { blockedTools: ["delete_record"], maxLatencyMs: 8000 },
+// });
+//
+// await agentExecutor.invoke(
+//   { input: "Look up case CASE-40917 and summarise the billing issue." },
+//   { callbacks: [zansn.handler] }, // <- the one line that captures the run
+// );
+//
+// const pack = await zansn.finalize();
+// console.log(exportEvidencePackMarkdown(pack));
+
+// ── Standalone demo (recorded callbacks, no API key needed) ──────────────────
+
+const zansn = createZansnCollector({
+  projectId: "support-agent",
+  name: "Support agent readiness (LangChain)",
+  policy: {
+    blockedTools: ["delete_record"],
+    sensitiveDataPatterns: [/sk-[a-z0-9]{8,}/i],
+    maxLatencyMs: 8000,
+  },
+});
+
+const h = zansn.handler;
+const serialized = (name) => ({ lc: 1, type: "constructor", id: ["langchain", "tools", name], kwargs: {} });
+
+// The agent calls a tool to look up a case.
+h.handleToolStart(
+  serialized("crm_lookup_case"),
+  JSON.stringify({ case_id: "CASE-40917" }),
+  "tool-1",
+  undefined,
+  undefined,
+  undefined,
+  undefined,
+  "call-1",
+);
+h.handleToolEnd({ status: "open", topic: "billing" }, "tool-1");
+
+// The model turn reports token usage.
+h.handleLLMEnd(
+  {
+    generations: [[{ text: "ok" }]],
+    llmOutput: { tokenUsage: { promptTokens: 470, completionTokens: 62, totalTokens: 532 } },
+  },
+  "llm-1",
+);
+
+// The chain finishes with the final answer.
+h.handleChainEnd(
+  { output: "Case CASE-40917 is an open billing question about a duplicate charge." },
+  "chain-1",
+);
+
+const pack = await zansn.finalize();
+
+console.log(exportEvidencePackMarkdown(pack));
+console.log("\nReadiness:", pack.summary.readiness);
+console.log("Total tokens:", pack.summary.totalTokens);
+console.log("Findings:", pack.findings.length);

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@zansn/langchain",
+  "version": "0.1.0",
+  "description": "Turn LangChain agent runs into portable Zansn evidence packs. Capture traces, tool calls, cost, and readiness with a callback handler.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/index.js",
+    "dist/index.d.ts",
+    "examples",
+    "README.md",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "release:check": "npm run typecheck && npm test && npm run build && npm audit --omit=dev --omit=optional && npm pack --dry-run",
+    "publish:dry-run": "npm publish --dry-run",
+    "prepack": "npm run typecheck && npm test && npm run build"
+  },
+  "keywords": [
+    "zansn",
+    "zansn-labs",
+    "langchain",
+    "ai-assurance",
+    "agent-evaluation",
+    "agent-observability",
+    "agent-tracing",
+    "ai-agents",
+    "llm-evals",
+    "evidence-pack",
+    "opentelemetry"
+  ],
+  "author": "Zansn Labs",
+  "license": "Apache-2.0",
+  "homepage": "https://zansn.ai",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hemswayy/zansn-labs.git",
+    "directory": "npm-reservation/packages/@zansn/langchain"
+  },
+  "bugs": {
+    "url": "https://zansn.ai/contact"
+  },
+  "funding": {
+    "type": "individual",
+    "url": "https://zansn.ai"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "peerDependencies": {
+    "@langchain/core": ">=0.3",
+    "zansn": "^0.1.3"
+  },
+  "overrides": {
+    "esbuild": "^0.28.1"
+  },
+  "devDependencies": {
+    "@langchain/core": "^1.2.2",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4",
+    "zansn": "^0.1.3"
+  }
+}