@introspection-sdk/introspection-node 0.4.1 → 0.4.3

package/dist/otel/index.js

@@ -0,0 +1,33 @@
+/**
+ * OpenTelemetry surface for the Introspection Node SDK.
+ *
+ * Subpath entry point: `@introspection-sdk/introspection-node/otel`.
+ *
+ * Importing from here pulls in OTel SDK packages (peer deps). The
+ * REST-only `IntrospectionClient` is available from the package root
+ * and does not require these to be installed.
+ */
+// IntrospectionLogs — OTel logs exporter with track/feedback/identify
+// and baggage context helpers (extracted from the old IntrospectionClient).
+export { IntrospectionLogs } from "./logs.js";
+// One-call tracing bootstrap (NodeTracerProvider + AsyncLocalStorage +
+// W3C baggage propagator + IntrospectionSpanProcessor).
+export { setupTracing } from "./setup.js";
+// Span processor — attach to your own TracerProvider.
+export { IntrospectionSpanProcessor } from "./span-processor.js";
+// OpenAI Agents SDK tracing processor.
+export { IntrospectionTracingProcessor } from "./tracing-processor.js";
+// Claude Agent SDK hooks.
+export { IntrospectionClaudeHooks } from "./claude-hooks.js";
+// Claude Agent SDK wrapper.
+export { withIntrospection } from "./claude-wrapper.js";
+// Anthropic SDK instrumentor.
+export { AnthropicInstrumentor, tracedMessagesCreate, REDACTED_THINKING_CONTENT, } from "./anthropic.js";
+// Pi Agent SDK instrumentor.
+export { IntrospectionPiInstrumentor } from "./pi.js";
+// Gemini SDK instrumentor.
+export { GeminiInstrumentor } from "./gemini.js";
+// OpenInference span exporter (drops Arize/OpenInference attrs onto a
+// downstream OTel SpanExporter).
+export { addOpenInferenceAttributes, OpenInferenceSpanExporter, } from "../converters/openinference.js";
+//# sourceMappingURL=index.js.map

package/dist/otel/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/otel/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,sEAAsE;AACtE,4EAA4E;AAC5E,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAG9C,uEAAuE;AACvE,wDAAwD;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG1C,sDAAsD;AACtD,OAAO,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAGjE,uCAAuC;AACvC,OAAO,EAAE,6BAA6B,EAAE,MAAM,wBAAwB,CAAC;AAMvE,0BAA0B;AAC1B,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAiB7D,4BAA4B;AAC5B,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAOxD,8BAA8B;AAC9B,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,gBAAgB,CAAC;AAExB,6BAA6B;AAC7B,OAAO,EAAE,2BAA2B,EAAE,MAAM,SAAS,CAAC;AAMtD,2BAA2B;AAC3B,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD,sEAAsE;AACtE,iCAAiC;AACjC,OAAO,EACL,0BAA0B,EAC1B,yBAAyB,GAC1B,MAAM,gCAAgC,CAAC"}

package/dist/otel/langchain-handler.d.ts

@@ -0,0 +1,112 @@
+/**
+ * LangChain/LangGraph Callback Handler for Introspection.
+ *
+ * Hooks into LangChain's native callback system to capture LLM, tool, and
+ * chain interactions as gen_ai.* OTel spans for the Introspection backend.
+ *
+ * Similar to IntrospectionTracingProcessor for OpenAI Agents SDK and
+ * IntrospectionClaudeHooks for Claude Agent SDK.
+ *
+ * **Important:** This module requires `@langchain/core` at runtime.
+ * Import via the subpath: `@introspection-sdk/introspection-node/langchain`
+ *
+ * @example
+ * ```ts
+ * import { IntrospectionCallbackHandler } from "@introspection-sdk/introspection-node/langchain";
+ * import { ChatOpenAI } from "@langchain/openai";
+ *
+ * const handler = new IntrospectionCallbackHandler({
+ *   serviceName: "my-langchain-app",
+ * });
+ *
+ * const model = new ChatOpenAI({ modelName: "gpt-4o" });
+ * const response = await model.invoke("Hello!", { callbacks: [handler] });
+ *
+ * await handler.shutdown();
+ * ```
+ */
+import { BaseCallbackHandler } from "@langchain/core/callbacks/base";
+import type { Serialized } from "@langchain/core/load/serializable";
+import type { LLMResult } from "@langchain/core/outputs";
+import type { BaseMessage } from "@langchain/core/messages";
+import type { ChainValues } from "@langchain/core/utils/types";
+import { type SpanExporter, type IdGenerator } from "@opentelemetry/sdk-trace-base";
+/** Advanced options for testing and customization. */
+export interface LangChainHandlerAdvancedOptions {
+    /** Custom span exporter for testing. */
+    spanExporter?: SpanExporter;
+    /** Custom ID generator for testing. */
+    idGenerator?: IdGenerator;
+    /** Use SimpleSpanProcessor instead of BatchSpanProcessor. */
+    useSimpleSpanProcessor?: boolean;
+}
+/** Configuration for {@link IntrospectionCallbackHandler}. */
+export interface IntrospectionCallbackHandlerOptions {
+    /** Authentication token (env: INTROSPECTION_TOKEN). */
+    token?: string;
+    /** Base URL for the API (env: INTROSPECTION_BASE_OTEL_URL). */
+    baseUrl?: string;
+    /** Service name for telemetry (env: INTROSPECTION_SERVICE_NAME). */
+    serviceName?: string;
+    /** Additional headers to include in requests. */
+    additionalHeaders?: Record<string, string>;
+    /** Advanced options for testing. */
+    advanced?: LangChainHandlerAdvancedOptions;
+}
+/**
+ * LangChain callback handler that captures LLM, tool, and chain events
+ * as gen_ai.* OTel spans and exports them to the Introspection backend.
+ *
+ * Pass as a callback to any LangChain invoke call, or set globally via
+ * `setGlobalHandler()`.
+ */
+export declare class IntrospectionCallbackHandler extends BaseCallbackHandler {
+    name: string;
+    private _tracerProvider;
+    private _tracer;
+    private _spans;
+    private _conversationId;
+    private _spanNames;
+    private _spanParents;
+    private _runRoots;
+    private static _wrapperNames;
+    private _llmInputs;
+    constructor(options?: IntrospectionCallbackHandlerOptions);
+    private _rootRunId;
+    /** Keep the top-level run span aligned with child conversation IDs. */
+    private _setRootConversationId;
+    private _endRootIfComplete;
+    /** Create a span under a LangChain parent when one exists.
+     *  Sets gen_ai.agent.name to the parent span's name for hierarchy. */
+    private _createChildSpan;
+    handleChatModelStart(llm: Serialized, messages: BaseMessage[][], runId: string, parentRunId?: string, extraParams?: Record<string, unknown>, _tags?: string[], metadata?: Record<string, unknown>, runName?: string): void;
+    handleLLMStart(llm: Serialized, prompts: string[], runId: string, parentRunId?: string, extraParams?: Record<string, unknown>, _tags?: string[], metadata?: Record<string, unknown>, runName?: string): void;
+    handleLLMEnd(output: LLMResult, runId: string): void;
+    handleLLMError(err: Error, runId: string): void;
+    handleChainStart(chain: Serialized, _inputs: ChainValues, runId: string, _runType?: string, _tags?: string[], metadata?: Record<string, unknown>, runName?: string, parentRunId?: string): void;
+    handleChainEnd(_outputs: ChainValues, runId: string): void;
+    handleChainError(err: Error, runId: string): void;
+    handleToolStart(tool: Serialized, input: string, runId: string, parentRunId?: string, _tags?: string[], metadata?: Record<string, unknown>, runName?: string): void;
+    handleToolEnd(output: unknown, runId: string): void;
+    handleToolError(err: Error, runId: string): void;
+    shutdown(): Promise<void>;
+    forceFlush(): Promise<void>;
+    private _extractModelName;
+    private _extractProvider;
+    /** Walk up the span tree to find the first non-wrapper span name. */
+    private _findAgentName;
+    private _getConversationId;
+    /**
+     * Read a single value from the active OTel baggage. Returns undefined when
+     * no propagator is installed or the key is absent.
+     *
+     * Used so callers can scope LangChain calls with
+     * `IntrospectionClient.withAgent()` / `.withConversation()` /
+     * `.withGenAi()` without threading metadata through every invoke().
+     */
+    private _readBaggage;
+    private _convertMessages;
+    private _mapRole;
+    private _extractContent;
+}
+//# sourceMappingURL=langchain-handler.d.ts.map

package/dist/otel/langchain-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"langchain-handler.d.ts","sourceRoot":"","sources":["../../src/otel/langchain-handler.ts"],"names":[],"mappings":"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"}