raindrop-langchain 0.0.7

Raindrop integration for LangChain

raindrop-langchain

Raindrop integration for LangChain (Python). Automatically captures LLM calls, tool usage, chains, and retrievers via LangChain's callback system.

Installation

pip install raindrop-langchain langchain-core

Quick Start

from raindrop_langchain import RaindropLangchain
from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage

raindrop = RaindropLangchain(
    api_key="rk_...",
    user_id="user-123",
)

model = ChatOpenAI(model="gpt-4o")

result = model.invoke(
    [HumanMessage(content="Hello!")],
    config={"callbacks": [raindrop.handler]},
)

raindrop.flush()

Factory Function (alternative)

from raindrop_langchain import create_raindrop_langchain

raindrop = create_raindrop_langchain(api_key="rk_...", user_id="user-123")
model = ChatOpenAI(model="gpt-4o")
result = model.invoke("Hello!", config={"callbacks": [raindrop.handler]})
raindrop.flush()

Projects

Route events to a specific project by passing its slug as project_id:

raindrop = RaindropLangchain(
    api_key="rk_...",
    project_id="support-prod",
)

project_id sets the X-Raindrop-Project-Id header on every event. Omit it (or pass "default") to use your org's default Production project, which is the existing behavior. The same option is accepted by the create_raindrop_langchain(...) factory. Invalid slugs are ignored with a warning and no header is sent.

What Gets Captured

• LLM calls — model name, input, output, token usage, finish reason
• Tool calls — tool name, input arguments, output, duration (via interaction.track_tool() spans)
• Chains — execution tracking
• Retrievers — query and document count
• Errors — error type and message captured in event properties
• Extended token categories — cached tokens (ai.usage.cached_tokens) and reasoning tokens (ai.usage.thoughts_tokens) when available from the provider (e.g. OpenAI)
• Finish reason — captured as ai.finish_reason in event properties (e.g. "stop", "length")

Debug Mode

Enable verbose logging with debug=True:

raindrop = RaindropLangchain(
    api_key="rk_...",
    debug=True,
)

Identify Users

Associate events with a user after initialization:

raindrop.identify("user-123", {"name": "Alice", "plan": "pro"})

Track Signals

Send feedback, edits, or custom signals:

raindrop.track_signal(
    event_id="evt-abc",
    name="thumbs_up",
    signal_type="feedback",
    sentiment="POSITIVE",
)

Flushing and Shutdown

raindrop.flush()     # flush pending data
raindrop.shutdown()  # flush + release resources

API Reference

RaindropLangchain

Parameter	Type	Default	Description
api_key	Optional[str]	None	Raindrop API key. If None, telemetry is disabled
user_id	Optional[str]	None	Associate all events with a user
convo_id	Optional[str]	None	Group events into a conversation
project_id	Optional[str]	None	Route events to a specific project (slug); omit for the default Production project
trace_chains	bool	True	Track chain execution
trace_retrievers	bool	True	Track retriever calls
filter_langgraph_internals	bool	True	Filter LangGraph-internal chain events and deduplicate LLM callbacks
tracing_enabled	bool	True	Enable distributed tracing
bypass_otel_for_tools	bool	True	Bypass OTEL for tool spans
debug	bool	False	Enable debug logging

Methods

Method	Description
handler	Property — the LangChain callback handler to pass into config={"callbacks": [...]}
flush()	Flush all pending events to the Raindrop API
shutdown()	Flush remaining events and release resources
identify(user_id, traits)	Identify a user with optional traits
track_signal(event_id, name, ...)	Track a signal event

Async Support

The callback handler inherits from LangChain's AsyncCallbackHandler and works with both synchronous and asynchronous LangChain invocations.

result = await model.ainvoke(
    [HumanMessage(content="Hello!")],
    config={"callbacks": [raindrop.handler]},
)

LangGraph Support

Works with LangGraph out of the box. The handler automatically filters LangGraph-internal chain events and deduplicates LLM callbacks. Pass the handler to the model inside your LLM node — not to graph.invoke(). See examples/langchain-langgraph-python-basic/ for a full example.

LangSmith Coexistence

Raindrop and LangSmith can run simultaneously. Set LANGSMITH_TRACING=false to disable LangSmith if you only want Raindrop.

Payload size bounds

Payloads the handler serializes itself — multi-modal chat content lists and agent-action tool inputs — are bounded to 1,000,000 characters with a ...[truncated by raindrop] marker. The bound is enforced during serialization (cost proportional to the cap, not the payload), so a multi-MB content list (e.g. base64 image parts) can't stall your event loop inside a synchronous callback. Plain-string prompts and tool outputs are capped by the Raindrop SDK's own per-field limit (max_text_field_chars, raindrop-ai

= 0.0.51).

Known Limitations

• Multi-LLM chain data: In ReAct loops with multiple child LLMs, only the last child's data survives (Python SDK uses one-shot track_ai vs TS's accumulative EventShipper.patch).
• Error-path input loss: On LLM errors, the input captured during on_llm_start is not forwarded to the finalized event.

Testing

cd packages/langchain-python
pip install -e .
python -m pytest tests/ -v