@raindrop-ai/langchain 0.0.1

package/README.md

@@ -0,0 +1,76 @@
+# @raindrop-ai/langchain
+
+Raindrop integration for LangChain. Automatically captures LLM calls, tool usage, chains, retrievers, and agent actions via LangChain's callback system.
+
+## Installation
+
+```bash
+npm install @raindrop-ai/langchain @langchain/core
+```
+
+## Usage
+
+```typescript
+import { createRaindropLangChain } from "@raindrop-ai/langchain";
+import { ChatOpenAI } from "@langchain/openai";
+import { HumanMessage } from "@langchain/core/messages";
+
+const raindrop = createRaindropLangChain({
+  writeKey: "rk_...",
+  userId: "user-123",
+});
+
+const model = new ChatOpenAI({ model: "gpt-4o" });
+
+const result = await model.invoke(
+  [new HumanMessage("Hello!")],
+  { callbacks: [raindrop.handler] },
+);
+
+await raindrop.flush();
+```
+
+## What gets captured
+
+- **LLM calls**: model name, input, output, token usage
+- **Tool calls**: tool name, input arguments, output
+- **Chains**: execution spans with parent-child nesting
+- **Retrievers**: query and document count
+- **Errors**: captured with OTLP error status
+
+## Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `writeKey` | `string` | - | Raindrop API write key (omit to disable telemetry) |
+| `endpoint` | `string` | `https://api.raindrop.ai/v1/` | API endpoint |
+| `userId` | `string` | - | Associate all events with a user |
+| `convoId` | `string` | - | Group events into a conversation |
+| `debug` | `boolean` | `false` | Enable verbose logging |
+| `traceChains` | `boolean` | `true` | Create spans for chain execution |
+| `traceRetrievers` | `boolean` | `true` | Create spans for retriever calls |
+| `filterLangGraphInternals` | `boolean` | `true` | Filter LangGraph-internal chain events and deduplicate LLM callbacks |
+
+## LangGraph Support
+
+Works with LangGraph out of the box. The handler automatically:
+- Filters LangGraph-internal chain events (graph executor, `__start__`, `__end__`, channel nodes)
+- Deduplicates LLM callbacks that LangGraph fires multiple times with the same `runId`
+
+Pass the handler both at `graph.invoke()` and inside your LLM node. See `examples/langchain-langgraph-basic/` for a full example.
+
+**Best practices:**
+- Pass callbacks to the **model inside your node**, not to `graph.invoke()` — this avoids duplicate events from LangGraph's internal callback propagation
+- Create a new handler instance per request in server environments
+
+## LangSmith Coexistence
+
+Raindrop and LangSmith can run simultaneously — both receive the same LangChain callbacks independently. Set `LANGSMITH_TRACING=false` to disable LangSmith if you only want Raindrop.
+
+## Testing
+
+```bash
+pnpm test
+```
+
+Tests use MSW to intercept HTTP requests — no real LLM calls are made.

package/dist/index.d.mts

@@ -0,0 +1,320 @@
+import { BaseCallbackHandler } from '@langchain/core/callbacks/base';
+import { Serialized } from '@langchain/core/load/serializable';
+import { LLMResult } from '@langchain/core/outputs';
+import { BaseMessage } from '@langchain/core/messages';
+import { AgentAction, AgentFinish } from '@langchain/core/agents';
+import { DocumentInterface } from '@langchain/core/documents';
+import { ChainValues } from '@langchain/core/utils/types';
+
+type OtlpAnyValue = {
+    stringValue?: string;
+    intValue?: string;
+    doubleValue?: number;
+    boolValue?: boolean;
+    arrayValue?: {
+        values: OtlpAnyValue[];
+    };
+};
+type OtlpKeyValue = {
+    key: string;
+    value: OtlpAnyValue;
+};
+declare const SpanStatusCode: {
+    readonly UNSET: 0;
+    readonly OK: 1;
+    readonly ERROR: 2;
+};
+type OtlpSpanStatus = {
+    code: (typeof SpanStatusCode)[keyof typeof SpanStatusCode] | number;
+    message?: string;
+};
+type OtlpSpan = {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    startTimeUnixNano: string;
+    endTimeUnixNano: string;
+    attributes?: OtlpKeyValue[];
+    status?: OtlpSpanStatus;
+};
+type SpanIds = {
+    traceIdB64: string;
+    spanIdB64: string;
+    parentSpanIdB64?: string;
+};
+
+type Attachment = {
+    type: string;
+    role: string;
+    name?: string;
+    value: string;
+};
+type IdentifyInput = {
+    userId: string;
+    traits?: Record<string, unknown>;
+};
+type Patch = {
+    eventName?: string;
+    userId?: string;
+    convoId?: string;
+    input?: string;
+    output?: string;
+    model?: string;
+    properties?: Record<string, unknown>;
+    attachments?: Attachment[];
+    isPending?: boolean;
+    timestamp?: string;
+};
+type SignalInput = {
+    eventId: string;
+    name: string;
+    type?: "default" | "feedback" | "edit" | "standard" | "agent" | "agent_internal";
+    sentiment?: "POSITIVE" | "NEGATIVE";
+    timestamp?: string;
+    properties?: Record<string, unknown>;
+    attachmentId?: string;
+    comment?: string;
+    after?: string;
+};
+type EventShipperOptions = {
+    writeKey?: string;
+    endpoint?: string;
+    enabled?: boolean;
+    debug: boolean;
+    partialFlushMs?: number;
+    sdkName?: string;
+    libraryName?: string;
+    libraryVersion?: string;
+    defaultEventName?: string;
+};
+declare class EventShipper {
+    private baseUrl;
+    private writeKey?;
+    private enabled;
+    private debug;
+    private partialFlushMs;
+    private sdkName;
+    private prefix;
+    private defaultEventName;
+    private context;
+    private buffers;
+    private sticky;
+    private timers;
+    private inFlight;
+    constructor(opts: EventShipperOptions);
+    isDebugEnabled(): boolean;
+    private authHeaders;
+    patch(eventId: string, patch: Patch): Promise<void>;
+    finish(eventId: string, patch: {
+        output?: string;
+        model?: string;
+        properties?: Record<string, unknown>;
+        userId?: string;
+    }): Promise<void>;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+    trackSignal(signal: SignalInput): Promise<void>;
+    identify(users: IdentifyInput | IdentifyInput[]): Promise<void>;
+    private flushOne;
+}
+
+type InternalSpan = {
+    ids: SpanIds;
+    name: string;
+    startTimeUnixNano: string;
+    endTimeUnixNano?: string;
+    attributes: Array<OtlpKeyValue | undefined>;
+};
+type TraceShipperOptions = {
+    writeKey?: string;
+    endpoint?: string;
+    enabled?: boolean;
+    debug: boolean;
+    debugSpans?: boolean;
+    flushIntervalMs?: number;
+    maxBatchSize?: number;
+    maxQueueSize?: number;
+    sdkName?: string;
+    serviceName?: string;
+    serviceVersion?: string;
+};
+declare class TraceShipper {
+    private baseUrl;
+    private writeKey?;
+    private enabled;
+    private debug;
+    private debugSpans;
+    private sdkName;
+    private prefix;
+    private serviceName;
+    private serviceVersion;
+    private flushIntervalMs;
+    private maxBatchSize;
+    private maxQueueSize;
+    private queue;
+    private timer;
+    private inFlight;
+    constructor(opts: TraceShipperOptions);
+    isDebugEnabled(): boolean;
+    private authHeaders;
+    startSpan(args: {
+        name: string;
+        parent?: {
+            traceIdB64: string;
+            spanIdB64: string;
+        };
+        eventId: string;
+        operationId?: string;
+        attributes?: Array<OtlpKeyValue | undefined>;
+        startTimeUnixNano?: string;
+    }): InternalSpan;
+    endSpan(span: InternalSpan, extra?: {
+        attributes?: InternalSpan["attributes"];
+        error?: unknown;
+        status?: OtlpSpanStatus;
+        endTimeUnixNano?: string;
+    }): void;
+    createSpan(args: {
+        name: string;
+        parent?: {
+            traceIdB64: string;
+            spanIdB64: string;
+        };
+        eventId: string;
+        startTimeUnixNano: string;
+        endTimeUnixNano: string;
+        attributes?: Array<OtlpKeyValue | undefined>;
+        status?: OtlpSpanStatus;
+    }): void;
+    enqueue(span: OtlpSpan): void;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+
+type ParentSpanContext = {
+    traceIdB64: string;
+    spanIdB64: string;
+    eventId: string;
+};
+interface ContextSpan {
+    readonly traceIdB64: string;
+    readonly spanIdB64: string;
+    readonly eventId: string;
+    log?(data: Record<string, unknown>): void;
+}
+interface AsyncLocalStorageLike<T> {
+    getStore(): T | undefined;
+    run<R>(store: T, callback: () => R): R;
+    enterWith?(store: T): void;
+}
+declare abstract class ContextManager {
+    abstract getParentSpanIds(): ParentSpanContext | undefined;
+    abstract runInContext<R>(span: ContextSpan, callback: () => R): R;
+    abstract getCurrentSpan(): ContextSpan | undefined;
+    abstract isReady(): boolean;
+}
+declare global {
+    var RAINDROP_CONTEXT_MANAGER: (new () => ContextManager) | undefined;
+    var RAINDROP_ASYNC_LOCAL_STORAGE: (new <T>() => AsyncLocalStorageLike<T>) | undefined;
+}
+
+interface RaindropCallbackHandlerOptions {
+    eventShipper: EventShipper;
+    traceShipper: TraceShipper;
+    userId?: string;
+    convoId?: string;
+    traceChains?: boolean;
+    traceRetrievers?: boolean;
+    /**
+     * Filter out LangGraph-internal chain events (graph executor, `__start__`,
+     * `__end__`, node wrappers). When enabled, only user-defined chains produce
+     * spans. Also deduplicates LLM callbacks that LangGraph fires multiple
+     * times with the same runId. Defaults to `true`.
+     */
+    filterLangGraphInternals?: boolean;
+}
+declare class RaindropCallbackHandler extends BaseCallbackHandler {
+    name: string;
+    private eventShipper;
+    private traceShipper;
+    private userId?;
+    private convoId?;
+    private traceChains;
+    private traceRetrievers;
+    private filterLangGraphInternals;
+    private spans;
+    private rootRunIds;
+    private eventIds;
+    constructor(opts: RaindropCallbackHandlerOptions);
+    private getEventId;
+    private getParent;
+    private cleanup;
+    private finalizeEventIfRoot;
+    /** Called at the start of an LLM run with string prompts. */
+    handleLLMStart(llm: Serialized, prompts: string[], runId: string, parentRunId?: string, _extraParams?: Record<string, unknown>, tags?: string[], metadata?: Record<string, unknown>, runName?: string): Promise<void>;
+    /** Called at the start of a chat model run with structured messages. */
+    handleChatModelStart(llm: Serialized, messages: BaseMessage[][], runId: string, parentRunId?: string, _extraParams?: Record<string, unknown>, tags?: string[], metadata?: Record<string, unknown>, runName?: string): Promise<void>;
+    handleLLMEnd(output: LLMResult, runId: string, _parentRunId?: string): Promise<void>;
+    /** Called when an LLM run encounters an error. */
+    handleLLMError(err: unknown, runId: string): Promise<void>;
+    handleChainStart(chain: Serialized, _inputs: ChainValues, runId: string, parentRunId?: string, _tags?: string[], _metadata?: Record<string, unknown>, _runType?: string, runName?: string): Promise<void>;
+    handleChainEnd(_outputs: ChainValues, runId: string): Promise<void>;
+    handleChainError(err: unknown, runId: string): Promise<void>;
+    handleToolStart(tool: Serialized, input: string, runId: string, parentRunId?: string, _tags?: string[], _metadata?: Record<string, unknown>, runName?: string): Promise<void>;
+    /** Called at the end of a tool run. */
+    handleToolEnd(output: unknown, runId: string): Promise<void>;
+    /** Called when a tool run encounters an error. */
+    handleToolError(err: unknown, runId: string): Promise<void>;
+    /** Called at the start of a retriever run. */
+    handleRetrieverStart(retriever: Serialized, query: string, runId: string, parentRunId?: string, _tags?: string[], _metadata?: Record<string, unknown>, name?: string): Promise<void>;
+    /** Called at the end of a retriever run. */
+    handleRetrieverEnd(documents: DocumentInterface[], runId: string): Promise<void>;
+    /** Called when a retriever run encounters an error. */
+    handleRetrieverError(err: unknown, runId: string): Promise<void>;
+    handleAgentAction(action: AgentAction, runId: string, parentRunId?: string): Promise<void>;
+    handleAgentEnd(_action: AgentFinish, runId: string): Promise<void>;
+}
+
+interface LangChainOptions {
+    /**
+     * API write key. If omitted, telemetry shipping is disabled but the handler
+     * is still available for a consistent integration surface.
+     */
+    writeKey?: string;
+    endpoint?: string;
+    debug?: boolean;
+    userId?: string;
+    convoId?: string;
+    traceChains?: boolean;
+    traceRetrievers?: boolean;
+    /**
+     * Filter out LangGraph-internal chain events and deduplicate LLM callbacks.
+     * Recommended when using LangGraph. Defaults to `true`.
+     */
+    filterLangGraphInternals?: boolean;
+}
+type RaindropLangChainClient = {
+    handler: RaindropCallbackHandler;
+    events: {
+        patch(eventId: string, patch: Patch): Promise<void>;
+        finish(eventId: string, patch: {
+            output?: string;
+            model?: string;
+            properties?: Record<string, unknown>;
+        }): Promise<void>;
+        addAttachments(eventId: string, attachments: Attachment[]): Promise<void>;
+        setProperties(eventId: string, properties: Record<string, unknown>): Promise<void>;
+    };
+    users: {
+        identify(users: IdentifyInput | IdentifyInput[]): Promise<void>;
+    };
+    signals: {
+        track(signal: SignalInput): Promise<void>;
+    };
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+};
+declare function createRaindropLangChain(opts: LangChainOptions): RaindropLangChainClient;
+
+export { type LangChainOptions, RaindropCallbackHandler, type RaindropLangChainClient, createRaindropLangChain };