lightrace 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Lightrace Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,93 @@
+# lightrace-js
+
+Lightweight LLM tracing SDK for TypeScript/JavaScript with remote tool invocation.
+
+## Install
+
+```bash
+yarn add lightrace
+```
+
+## Quick Start
+
+```typescript
+import { Lightrace, trace } from "lightrace";
+
+const lt = new Lightrace({
+  publicKey: "pk-lt-demo",
+  secretKey: "sk-lt-demo",
+  host: "http://localhost:3002",
+});
+
+// Root trace
+const runAgent = trace("run-agent", async (query: string) => {
+  const results = await search(query);
+  return results;
+});
+
+// Span
+const search = trace("search", { type: "span" }, async (query: string) => {
+  return ["result1", "result2"];
+});
+
+// Generation (LLM call)
+const generate = trace(
+  "generate",
+  { type: "generation", model: "gpt-4o" },
+  async (prompt: string) => {
+    return "LLM response";
+  },
+);
+
+// Tool — remotely invocable from the Lightrace UI
+const weatherLookup = trace("weather", { type: "tool" }, async (input: { city: string }) => {
+  return { temp: 72, unit: "F" };
+});
+
+// Tool — traced but NOT remotely invocable
+const readFile = trace("read-file", { type: "tool", invoke: false }, async (path: string) => {
+  return "file contents";
+});
+
+await runAgent("hello");
+lt.flush();
+await lt.shutdown();
+```
+
+## `trace()` API
+
+```typescript
+// Root trace (no options)
+trace(name, fn);
+
+// With options
+trace(name, options, fn);
+```
+
+### Options
+
+| Option        | Type      | Default     | Description                                              |
+| ------------- | --------- | ----------- | -------------------------------------------------------- |
+| `type`        | `string`  | `undefined` | `"span"`, `"generation"`, `"tool"`, `"chain"`, `"event"` |
+| `invoke`      | `boolean` | `true`      | For `type: "tool"`: register for remote invocation       |
+| `model`       | `string`  | `undefined` | For `type: "generation"`: LLM model name                 |
+| `inputSchema` | `ZodType` | `undefined` | Optional Zod schema for tool input                       |
+| `metadata`    | `Record`  | `undefined` | Static metadata attached to every call                   |
+
+## Compatibility
+
+Lightrace server also accepts traces from Langfuse Python/JS SDKs.
+
+## Development
+
+```bash
+yarn install
+yarn test
+yarn typecheck
+yarn lint
+yarn format
+```
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Main Lightrace SDK client.
+ */
+import { BatchExporter } from "./exporter.js";
+import { Observation } from "./observation.js";
+import type { UsageDetails } from "./types.js";
+export interface LightraceOptions {
+    publicKey?: string;
+    secretKey?: string;
+    host?: string;
+    flushAt?: number;
+    flushInterval?: number;
+    timeout?: number;
+    enabled?: boolean;
+    /** Default user ID for all traces. */
+    userId?: string;
+    /** Default session ID for all traces. */
+    sessionId?: string;
+}
+export declare class Lightrace {
+    private static instance;
+    private exporter;
+    private enabled;
+    private host;
+    private publicKey;
+    private secretKey;
+    /** Default user ID for all traces. */
+    readonly userId: string | undefined;
+    /** Default session ID for all traces. */
+    readonly sessionId: string | undefined;
+    constructor(options?: LightraceOptions);
+    static getInstance(): Lightrace | null;
+    /** Get the exporter (used by Observation). */
+    getExporter(): BatchExporter | null;
+    flush(): void;
+    shutdown(): Promise<void>;
+    /**
+     * Create a span observation imperatively.
+     */
+    span(opts: {
+        name: string;
+        input?: unknown;
+        metadata?: Record<string, unknown>;
+        traceId?: string;
+        parentObservationId?: string;
+    }): Observation;
+    /**
+     * Create a generation observation imperatively.
+     */
+    generation(opts: {
+        name: string;
+        input?: unknown;
+        model?: string;
+        metadata?: Record<string, unknown>;
+        usage?: UsageDetails;
+        traceId?: string;
+        parentObservationId?: string;
+    }): Observation;
+    /**
+     * Create an event observation imperatively (auto-ended).
+     */
+    event(opts: {
+        name: string;
+        input?: unknown;
+        metadata?: Record<string, unknown>;
+        traceId?: string;
+        parentObservationId?: string;
+    }): Observation;
+    private _createObservation;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE9C,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,MAAM,WAAW,gBAAgB;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,sCAAsC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAA0B;IAEjD,OAAO,CAAC,QAAQ,CAA8B;IAC9C,OAAO,CAAC,OAAO,CAAU;IACzB,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,SAAS,CAAS;IAC1B,sCAAsC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;gBAE3B,OAAO,GAAE,gBAAqB;IA2B1C,MAAM,CAAC,WAAW,IAAI,SAAS,GAAG,IAAI;IAItC,8CAA8C;IAC9C,WAAW,IAAI,aAAa,GAAG,IAAI;IAInC,KAAK,IAAI,IAAI;IAIP,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ/B;;OAEG;IACH,IAAI,CAAC,IAAI,EAAE;QACT,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACnC,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,mBAAmB,CAAC,EAAE,MAAM,CAAC;KAC9B,GAAG,WAAW;IAIf;;OAEG;IACH,UAAU,CAAC,IAAI,EAAE;QACf,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACnC,KAAK,CAAC,EAAE,YAAY,CAAC;QACrB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,mBAAmB,CAAC,EAAE,MAAM,CAAC;KAC9B,GAAG,WAAW;IAIf;;OAEG;IACH,KAAK,CAAC,IAAI,EAAE;QACV,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACnC,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,mBAAmB,CAAC,EAAE,MAAM,CAAC;KAC9B,GAAG,WAAW;IAMf,OAAO,CAAC,kBAAkB;CAqD3B"}

package/dist/client.js

@@ -0,0 +1,116 @@
+/**
+ * Main Lightrace SDK client.
+ */
+import { BatchExporter } from "./exporter.js";
+import { _setExporter, _setClientDefaults, _getTraceContext } from "./trace.js";
+import { Observation } from "./observation.js";
+import { generateId } from "./utils.js";
+export class Lightrace {
+    static instance = null;
+    exporter = null;
+    enabled;
+    host;
+    publicKey;
+    secretKey;
+    /** Default user ID for all traces. */
+    userId;
+    /** Default session ID for all traces. */
+    sessionId;
+    constructor(options = {}) {
+        this.publicKey = options.publicKey ?? process.env.LIGHTRACE_PUBLIC_KEY ?? "";
+        this.secretKey = options.secretKey ?? process.env.LIGHTRACE_SECRET_KEY ?? "";
+        this.host = (options.host ?? process.env.LIGHTRACE_HOST ?? "http://localhost:3002").replace(/\/$/, "");
+        this.enabled = options.enabled !== false;
+        this.userId = options.userId;
+        this.sessionId = options.sessionId;
+        if (!this.enabled)
+            return;
+        this.exporter = new BatchExporter({
+            host: this.host,
+            publicKey: this.publicKey,
+            secretKey: this.secretKey,
+            flushAt: options.flushAt,
+            flushInterval: options.flushInterval,
+            timeout: options.timeout,
+        });
+        _setExporter(this.exporter);
+        _setClientDefaults({ userId: this.userId, sessionId: this.sessionId });
+        Lightrace.instance = this;
+    }
+    static getInstance() {
+        return Lightrace.instance;
+    }
+    /** Get the exporter (used by Observation). */
+    getExporter() {
+        return this.exporter;
+    }
+    flush() {
+        this.exporter?.flush();
+    }
+    async shutdown() {
+        if (this.exporter) {
+            await this.exporter.shutdown();
+            _setExporter(null);
+        }
+        Lightrace.instance = null;
+    }
+    /**
+     * Create a span observation imperatively.
+     */
+    span(opts) {
+        return this._createObservation("span", opts);
+    }
+    /**
+     * Create a generation observation imperatively.
+     */
+    generation(opts) {
+        return this._createObservation("generation", opts);
+    }
+    /**
+     * Create an event observation imperatively (auto-ended).
+     */
+    event(opts) {
+        const obs = this._createObservation("event", opts);
+        obs.end();
+        return obs;
+    }
+    _createObservation(type, opts) {
+        const exporter = this.exporter;
+        // Resolve trace context: explicit > ALS context > create new root trace
+        const ctx = _getTraceContext();
+        let traceId = opts.traceId ?? ctx?.traceId;
+        const parentObservationId = opts.parentObservationId ?? ctx?.observationId ?? undefined;
+        // If no trace context, create an implicit root trace
+        if (!traceId) {
+            traceId = generateId();
+            // Emit root trace event
+            if (exporter) {
+                exporter.enqueue({
+                    id: generateId(),
+                    type: "trace-create",
+                    timestamp: new Date().toISOString(),
+                    body: {
+                        id: traceId,
+                        name: opts.name,
+                        timestamp: new Date().toISOString(),
+                        userId: this.userId,
+                        sessionId: this.sessionId,
+                    },
+                });
+            }
+        }
+        const obs = new Observation({
+            traceId,
+            type,
+            name: opts.name,
+            exporter,
+            input: opts.input,
+            model: opts.model,
+            metadata: opts.metadata,
+            usage: opts.usage,
+            parentObservationId: parentObservationId ?? undefined,
+        });
+        return obs;
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/exporter.d.ts

@@ -0,0 +1,31 @@
+import type { TraceEvent } from "./types.js";
+/**
+ * Batch exporter that sends events to the lightrace ingestion endpoint.
+ */
+export declare class BatchExporter {
+    private queue;
+    private endpoint;
+    private authHeader;
+    private flushAt;
+    private flushInterval;
+    private timeout;
+    private maxRetries;
+    private timer;
+    private running;
+    constructor(options: {
+        host: string;
+        publicKey: string;
+        secretKey: string;
+        flushAt?: number;
+        flushInterval?: number;
+        timeout?: number;
+        maxRetries?: number;
+    });
+    enqueue(event: TraceEvent): void;
+    flush(): void;
+    shutdown(): Promise<void>;
+    private doFlush;
+    private sendWithRetry;
+    private delay;
+}
+//# sourceMappingURL=exporter.d.ts.map

package/dist/exporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exporter.d.ts","sourceRoot":"","sources":["../src/exporter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;GAEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,KAAK,CAAoB;IACjC,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,OAAO,CAAQ;gBAEX,OAAO,EAAE;QACnB,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB;IAmBD,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAOhC,KAAK,IAAI,IAAI;IAIP,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAS/B,OAAO,CAAC,OAAO;YASD,aAAa;IA8B3B,OAAO,CAAC,KAAK;CAGd"}

package/dist/exporter.js

@@ -0,0 +1,88 @@
+/**
+ * Batch exporter that sends events to the lightrace ingestion endpoint.
+ */
+export class BatchExporter {
+    queue = [];
+    endpoint;
+    authHeader;
+    flushAt;
+    flushInterval;
+    timeout;
+    maxRetries;
+    timer = null;
+    running = true;
+    constructor(options) {
+        const host = options.host.replace(/\/$/, "");
+        this.endpoint = `${host}/api/public/ingestion`;
+        this.authHeader = `Basic ${btoa(`${options.publicKey}:${options.secretKey}`)}`;
+        this.flushAt = options.flushAt ?? 50;
+        this.flushInterval = options.flushInterval ?? 5.0;
+        this.timeout = options.timeout ?? 10_000;
+        this.maxRetries = options.maxRetries ?? 2;
+        this.timer = setInterval(() => {
+            if (this.running)
+                this.doFlush();
+        }, this.flushInterval * 1000);
+        // Don't keep the process alive just for flushing
+        if (this.timer && typeof this.timer === "object" && "unref" in this.timer) {
+            this.timer.unref();
+        }
+    }
+    enqueue(event) {
+        this.queue.push(event);
+        if (this.queue.length >= this.flushAt) {
+            this.doFlush();
+        }
+    }
+    flush() {
+        this.doFlush();
+    }
+    async shutdown() {
+        this.running = false;
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        this.doFlush();
+    }
+    doFlush() {
+        if (this.queue.length === 0)
+            return;
+        const batch = this.queue.splice(0);
+        const payload = { batch };
+        // Fire and forget with retry
+        this.sendWithRetry(payload, 0);
+    }
+    async sendWithRetry(payload, attempt) {
+        try {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+            const resp = await fetch(this.endpoint, {
+                method: "POST",
+                headers: {
+                    Authorization: this.authHeader,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify(payload),
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            if (resp.ok || resp.status < 500)
+                return;
+            if (attempt < this.maxRetries) {
+                await this.delay(2 ** attempt * 1000);
+                return this.sendWithRetry(payload, attempt + 1);
+            }
+        }
+        catch {
+            if (attempt < this.maxRetries) {
+                await this.delay(2 ** attempt * 1000);
+                return this.sendWithRetry(payload, attempt + 1);
+            }
+        }
+    }
+    delay(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+//# sourceMappingURL=exporter.js.map

package/dist/exporter.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { Lightrace } from "./client.js";
+export type { LightraceOptions } from "./client.js";
+export { trace } from "./trace.js";
+export { Observation } from "./observation.js";
+export type { TraceOptions, ObservationType, UsageDetails } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { Lightrace } from "./client.js";
+export { trace } from "./trace.js";
+export { Observation } from "./observation.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/integrations/langchain.d.ts

@@ -0,0 +1,74 @@
+/**
+ * LangChain/LangGraph integration for Lightrace.
+ *
+ * Extends `BaseCallbackHandler` from `@langchain/core` to automatically
+ * capture chains, LLM calls, tool invocations, and retriever operations
+ * as Lightrace trace observations.
+ *
+ * @example
+ * ```ts
+ * import { LightraceCallbackHandler } from "lightrace/integrations/langchain";
+ *
+ * const handler = new LightraceCallbackHandler({ userId: "user-123" });
+ * const result = await chain.invoke(inputs, { callbacks: [handler] });
+ * console.log(handler.lastTraceId);
+ * ```
+ */
+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 { DocumentInterface } from "@langchain/core/documents";
+import { Lightrace } from "../client.js";
+export interface LightraceCallbackHandlerOptions {
+    /** User ID to attach to the root trace. */
+    userId?: string;
+    /** Session ID to attach to the root trace. */
+    sessionId?: string;
+    /** Override name for the root trace. */
+    traceName?: string;
+    /** Additional metadata to attach to the root trace. */
+    metadata?: Record<string, unknown>;
+    /** Provide a Lightrace client instance. If omitted, uses Lightrace.getInstance(). */
+    client?: Lightrace;
+}
+export declare class LightraceCallbackHandler extends BaseCallbackHandler {
+    name: string;
+    private runs;
+    private runParents;
+    private completionStartTimes;
+    private rootRunId;
+    private _traceId;
+    private userId?;
+    private sessionId?;
+    private traceName?;
+    private rootMetadata?;
+    private exporter;
+    /** The trace ID from the most recently completed root run. */
+    lastTraceId: string | null;
+    constructor(opts?: LightraceCallbackHandlerOptions);
+    private getParentObservationId;
+    private emit;
+    private emitObservation;
+    private extractModelName;
+    private isAgent;
+    private registerRun;
+    private endRun;
+    handleChainStart(chain: Serialized, inputs: Record<string, unknown>, runId: string, parentRunId?: string, tags?: string[], metadata?: Record<string, unknown>): Promise<void>;
+    handleChainEnd(outputs: Record<string, unknown>, runId: string, _parentRunId?: string): Promise<void>;
+    handleChainError(error: Error, runId: string, _parentRunId?: string): Promise<void>;
+    handleLLMStart(llm: Serialized, prompts: string[], runId: string, parentRunId?: string, _extraParams?: Record<string, unknown>, _tags?: string[], metadata?: Record<string, unknown>): Promise<void>;
+    handleChatModelStart(llm: Serialized, messages: BaseMessage[][], runId: string, parentRunId?: string, _extraParams?: Record<string, unknown>, _tags?: string[], metadata?: Record<string, unknown>): Promise<void>;
+    handleLLMEnd(output: LLMResult, runId: string, _parentRunId?: string): Promise<void>;
+    handleLLMNewToken(_token: string, _idx: unknown, runId: string): Promise<void>;
+    handleLLMError(error: Error, runId: string, _parentRunId?: string): Promise<void>;
+    handleToolStart(tool: Serialized, input: string, runId: string, parentRunId?: string, _tags?: string[], metadata?: Record<string, unknown>): Promise<void>;
+    handleToolEnd(output: string, runId: string, _parentRunId?: string): Promise<void>;
+    handleToolError(error: Error, runId: string, _parentRunId?: string): Promise<void>;
+    handleRetrieverStart(retriever: Serialized, query: string, runId: string, parentRunId?: string, _tags?: string[], metadata?: Record<string, unknown>): Promise<void>;
+    handleRetrieverEnd(documents: DocumentInterface[], runId: string, _parentRunId?: string): Promise<void>;
+    handleRetrieverError(error: Error, runId: string, _parentRunId?: string): Promise<void>;
+    /** Get the current active trace ID (null if no run is active). */
+    get traceId(): string | null;
+}
+//# sourceMappingURL=langchain.d.ts.map

package/dist/integrations/langchain.d.ts.map

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