@softprobe/langchain 0.1.0

package/dist/CallbackHandler.d.ts

@@ -0,0 +1,54 @@
+import { BaseCallbackHandler } from "@langchain/core/callbacks/base";
+import type { AgentAction, AgentFinish } from "@langchain/core/agents";
+import type { DocumentInterface } from "@langchain/core/documents";
+import type { Serialized } from "@langchain/core/load/serializable";
+import { BaseMessage } from "@langchain/core/messages";
+import type { LLMResult } from "@langchain/core/outputs";
+import type { ChainValues } from "@langchain/core/utils/types";
+import { SoftprobeClient, type JsonValue } from "@softprobe/tracing";
+export type CallbackHandlerParams = {
+    softprobeClient: SoftprobeClient;
+    sessionId?: string;
+    userId?: string;
+    tags?: string[];
+    metadata?: Record<string, JsonValue>;
+    version?: string;
+    parentSpanContext?: {
+        traceId: string;
+        spanId: string;
+    };
+};
+export declare class CallbackHandler extends BaseCallbackHandler {
+    name: string;
+    private readonly client;
+    private readonly sessionId?;
+    private readonly userId?;
+    private readonly tags;
+    private readonly metadata?;
+    private readonly version?;
+    private readonly parentSpanContext?;
+    private readonly runs;
+    private readonly completionStart;
+    private readonly toolMeta;
+    lastTraceId: string | null;
+    constructor(params: CallbackHandlerParams);
+    private parent;
+    private start;
+    private end;
+    handleLLMNewToken(_token: string, _idx: unknown, runId: string): Promise<void>;
+    handleChainStart(chain: Serialized, inputs: ChainValues, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>, _runType?: string, name?: string): Promise<void>;
+    handleChainEnd(outputs: ChainValues, runId: string): Promise<void>;
+    handleChainError(err: Error, runId: string): Promise<void>;
+    handleAgentAction(action: AgentAction, runId: string, parentRunId?: string): Promise<void>;
+    handleAgentEnd(action: AgentFinish, runId: string): Promise<void>;
+    handleChatModelStart(llm: Serialized, messages: BaseMessage[][], runId: string, parentRunId?: string, extraParams?: Record<string, unknown>, tags?: string[], metadata?: Record<string, unknown>, name?: string): Promise<void>;
+    handleLLMStart(llm: Serialized, prompts: string[], runId: string, parentRunId?: string, extraParams?: Record<string, unknown>, tags?: string[], metadata?: Record<string, unknown>, name?: string): Promise<void>;
+    handleLLMEnd(output: LLMResult, runId: string): Promise<void>;
+    handleLLMError(err: Error, runId: string): Promise<void>;
+    handleToolStart(tool: Serialized, input: string, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>, name?: string): Promise<void>;
+    handleToolEnd(output: unknown, runId: string): Promise<void>;
+    handleToolError(err: Error, runId: string): Promise<void>;
+    handleRetrieverStart(retriever: Serialized, query: string, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>, name?: string): Promise<void>;
+    handleRetrieverEnd(documents: DocumentInterface[], runId: string): Promise<void>;
+    handleRetrieverError(err: Error, runId: string): Promise<void>;
+}

package/dist/CallbackHandler.js

@@ -0,0 +1,325 @@
+import { BaseCallbackHandler } from "@langchain/core/callbacks/base";
+import { recordToolCalls, recordToolDefinitions, toolResultEventPayload, toolSpanAttributes, normalizeToolCalls, } from "@softprobe/tracing";
+function asJsonValue(value) {
+    return value;
+}
+function messageToDict(message) {
+    const roleMap = {
+        human: "user",
+        ai: "assistant",
+        system: "system",
+        tool: "tool",
+        function: "function",
+    };
+    const raw = message.getType?.() ?? message._getType?.() ?? "unknown";
+    const payload = {
+        role: roleMap[raw] ?? raw,
+        content: asJsonValue(message.content),
+    };
+    const toolCalls = message.tool_calls;
+    if (toolCalls) {
+        const normalized = normalizeToolCalls(toolCalls);
+        payload.tool_calls = asJsonValue(normalized.length ? normalized : toolCalls);
+    }
+    const toolCallId = message.tool_call_id;
+    if (toolCallId)
+        payload.tool_call_id = toolCallId;
+    const name = message.name;
+    if (name)
+        payload.name = name;
+    return payload;
+}
+export class CallbackHandler extends BaseCallbackHandler {
+    name = "SoftprobeCallbackHandler";
+    client;
+    sessionId;
+    userId;
+    tags;
+    metadata;
+    version;
+    parentSpanContext;
+    runs = new Map();
+    completionStart = new Map();
+    toolMeta = new Map();
+    lastTraceId = null;
+    constructor(params) {
+        super();
+        this.client = params.softprobeClient;
+        this.sessionId = params.sessionId;
+        this.userId = params.userId;
+        this.tags = params.tags ?? [];
+        this.metadata = params.metadata;
+        this.version = params.version;
+        this.parentSpanContext = params.parentSpanContext;
+    }
+    parent(parentRunId) {
+        if (!parentRunId)
+            return undefined;
+        return this.runs.get(parentRunId);
+    }
+    start(options) {
+        const parent = this.parent(options.parentRunId);
+        const mergedTags = [...new Set([...(options.tags ?? []), ...this.tags])];
+        const mergedMeta = {
+            ...(this.metadata ?? {}),
+            ...(options.metadata ?? {}),
+        };
+        const common = {
+            name: options.name,
+            sessionId: this.sessionId,
+            userId: this.userId,
+            tags: mergedTags.length ? mergedTags : undefined,
+            metadata: Object.keys(mergedMeta).length ? mergedMeta : undefined,
+            version: this.version,
+            input: options.input,
+            attributes: options.attributes,
+            parent,
+            parentSpanContext: !parent && this.parentSpanContext ? this.parentSpanContext : undefined,
+        };
+        let obs;
+        if (options.asType === "generation") {
+            obs = this.client.startGeneration({
+                ...common,
+                model: options.model,
+                operationName: options.operationName,
+                modelParameters: {
+                    temperature: options.temperature,
+                    maxTokens: options.maxTokens,
+                },
+                promptEvent: options.promptEvent,
+            });
+        }
+        else {
+            obs = this.client.startObservation({
+                ...common,
+                asType: options.asType,
+            });
+        }
+        this.runs.set(options.runId, obs);
+        if (!parent)
+            this.lastTraceId = obs.traceId;
+        return obs;
+    }
+    end(runId, update = {}) {
+        const obs = this.runs.get(runId);
+        this.runs.delete(runId);
+        this.completionStart.delete(runId);
+        this.toolMeta.delete(runId);
+        if (!obs)
+            return;
+        obs.end(update);
+    }
+    async handleLLMNewToken(_token, _idx, runId) {
+        if (!this.completionStart.has(runId) && this.runs.has(runId)) {
+            const iso = new Date().toISOString();
+            this.completionStart.set(runId, iso);
+            const obs = this.runs.get(runId);
+            if (obs && "update" in obs) {
+                obs.update({ completionStartTime: iso });
+            }
+        }
+    }
+    async handleChainStart(chain, inputs, runId, parentRunId, tags, metadata, _runType, name) {
+        const runName = name ?? chain.id?.at(-1)?.toString() ?? chain.name ?? "Langchain Run";
+        const asType = /agent/i.test(runName) ? "agent" : "chain";
+        this.start({
+            runId,
+            parentRunId,
+            name: runName,
+            asType,
+            input: inputs,
+            metadata,
+            tags,
+        });
+    }
+    async handleChainEnd(outputs, runId) {
+        this.end(runId, { output: outputs });
+    }
+    async handleChainError(err, runId) {
+        this.end(runId, { statusMessage: String(err) });
+    }
+    async handleAgentAction(action, runId, parentRunId) {
+        // LangChain reuses the agent runId here; do not overwrite the agent span.
+        if (this.runs.has(runId))
+            return;
+        this.start({
+            runId,
+            parentRunId,
+            name: action.tool,
+            asType: "tool",
+            input: action.toolInput,
+            attributes: toolSpanAttributes({
+                toolName: action.tool,
+                kind: "function",
+                status: "ok",
+            }),
+        });
+    }
+    async handleAgentEnd(action, runId) {
+        this.end(runId, { output: action.returnValues });
+    }
+    async handleChatModelStart(llm, messages, runId, parentRunId, extraParams, tags, metadata, name) {
+        const flat = messages.flat().map(messageToDict);
+        const invocation = (extraParams?.invocation_params ?? {});
+        const model = (typeof invocation.model === "string" && invocation.model) ||
+            (typeof metadata?.ls_model_name === "string" && metadata.ls_model_name) ||
+            llm.id?.at(-1)?.toString();
+        const obs = this.start({
+            runId,
+            parentRunId,
+            name: name ?? llm.id?.at(-1)?.toString() ?? "ChatModel",
+            asType: "generation",
+            input: { messages: flat },
+            metadata,
+            tags,
+            model: model || undefined,
+            operationName: "chat",
+            temperature: typeof invocation.temperature === "number"
+                ? invocation.temperature
+                : undefined,
+            maxTokens: typeof invocation.max_tokens === "number"
+                ? invocation.max_tokens
+                : undefined,
+            promptEvent: flat,
+        });
+        if (invocation.tools !== undefined) {
+            recordToolDefinitions(obs, invocation.tools);
+        }
+    }
+    async handleLLMStart(llm, prompts, runId, parentRunId, extraParams, tags, metadata, name) {
+        const invocation = (extraParams?.invocation_params ?? {});
+        const model = (typeof invocation.model === "string" && invocation.model) ||
+            (typeof metadata?.ls_model_name === "string" && metadata.ls_model_name) ||
+            undefined;
+        const obs = this.start({
+            runId,
+            parentRunId,
+            name: name ?? llm.id?.at(-1)?.toString() ?? "LLM",
+            asType: "generation",
+            input: { prompts },
+            metadata,
+            tags,
+            model,
+            operationName: "completion",
+            promptEvent: prompts,
+        });
+        if (invocation.tools !== undefined) {
+            recordToolDefinitions(obs, invocation.tools);
+        }
+    }
+    async handleLLMEnd(output, runId) {
+        const toolCalls = [];
+        const finishReasons = [];
+        const generations = output.generations.flat().map((gen) => {
+            const message = gen.message;
+            if (message) {
+                const payload = messageToDict(message);
+                if (payload &&
+                    typeof payload === "object" &&
+                    !Array.isArray(payload) &&
+                    Array.isArray(payload.tool_calls) &&
+                    payload.tool_calls.length) {
+                    toolCalls.push(...payload.tool_calls);
+                    finishReasons.push("tool_calls");
+                }
+                else {
+                    finishReasons.push("stop");
+                }
+                return payload;
+            }
+            finishReasons.push("stop");
+            return { content: gen.text };
+        });
+        const tokenUsage = output.llmOutput?.tokenUsage ??
+            output.llmOutput?.token_usage;
+        const obs = this.runs.get(runId);
+        if (obs && toolCalls.length) {
+            recordToolCalls(obs, toolCalls);
+        }
+        this.end(runId, {
+            output: { generations },
+            completionEvent: generations,
+            usage: tokenUsage
+                ? {
+                    inputTokens: tokenUsage.promptTokens ?? tokenUsage.prompt_tokens,
+                    outputTokens: tokenUsage.completionTokens ?? tokenUsage.completion_tokens,
+                    totalTokens: tokenUsage.totalTokens ?? tokenUsage.total_tokens,
+                }
+                : undefined,
+            finishReasons: finishReasons.length ? finishReasons : ["stop"],
+        });
+    }
+    async handleLLMError(err, runId) {
+        this.end(runId, { statusMessage: String(err) });
+    }
+    async handleToolStart(tool, input, runId, parentRunId, tags, metadata, name) {
+        const toolName = name ?? tool.name ?? tool.id?.at(-1)?.toString() ?? "tool";
+        // Only correlate with a provider-supplied id (matches generation
+        // sp.tool.call_ids); never fabricate one from the LangChain runId.
+        const toolCallId = (typeof metadata?.tool_call_id === "string" && metadata.tool_call_id) ||
+            (typeof metadata?.toolCallId === "string" && metadata.toolCallId) ||
+            undefined;
+        this.toolMeta.set(runId, { name: toolName, toolCallId });
+        this.start({
+            runId,
+            parentRunId,
+            name: toolName,
+            asType: "tool",
+            input,
+            metadata,
+            tags,
+            attributes: toolSpanAttributes({
+                toolName,
+                toolCallId,
+                kind: "function",
+                status: "ok",
+            }),
+        });
+    }
+    async handleToolEnd(output, runId) {
+        const obs = this.runs.get(runId);
+        const meta = this.toolMeta.get(runId);
+        const content = asJsonValue(output);
+        if (obs) {
+            obs.addContentEvent("gen_ai.tool.message", toolResultEventPayload({
+                name: meta?.name ?? "tool",
+                content,
+                toolCallId: meta?.toolCallId,
+            }));
+        }
+        this.end(runId, {
+            output: content,
+            attributes: toolSpanAttributes({ status: "ok" }),
+        });
+    }
+    async handleToolError(err, runId) {
+        this.end(runId, {
+            statusMessage: String(err),
+            attributes: toolSpanAttributes({ status: "error" }),
+        });
+    }
+    async handleRetrieverStart(retriever, query, runId, parentRunId, tags, metadata, name) {
+        this.start({
+            runId,
+            parentRunId,
+            name: name ?? retriever.name ?? "retriever",
+            asType: "retriever",
+            input: { query },
+            metadata,
+            tags,
+        });
+    }
+    async handleRetrieverEnd(documents, runId) {
+        this.end(runId, {
+            output: {
+                documents: documents.map((doc) => ({
+                    pageContent: doc.pageContent,
+                    metadata: doc.metadata,
+                })),
+            },
+        });
+    }
+    async handleRetrieverError(err, runId) {
+        this.end(runId, { statusMessage: String(err) });
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { CallbackHandler, type CallbackHandlerParams, } from "./CallbackHandler.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { CallbackHandler, } from "./CallbackHandler.js";

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@softprobe/langchain",
+  "version": "0.1.0",
+  "description": "Softprobe LangChain callback handler",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "lint": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@softprobe/tracing": "workspace:*"
+  },
+  "peerDependencies": {
+    "@langchain/core": ">=0.3.0",
+    "@opentelemetry/api": "^1.9.0"
+  },
+  "devDependencies": {
+    "@langchain/core": "^0.3.40",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/sdk-trace-base": "^1.30.1",
+    "@types/node": "^22.13.10",
+    "typescript": "^5.8.2",
+    "vitest": "^3.0.8"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/softprobe/softprobe-js.git",
+    "directory": "packages/langchain"
+  },
+  "license": "MIT"
+}