# raindrop-langchain

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

## Installation

```bash
pip install raindrop-langchain langchain-core
```

## Usage

```python
from raindrop_langchain import create_raindrop_langchain
from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage

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

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

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

raindrop["flush"]()
```

## What gets captured

- **LLM calls**: model name, input, output, token usage
- **Tool calls**: tool name, input arguments, output
- **Chains**: execution tracking
- **Retrievers**: query and document count

## Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `api_key` | `str` | required | Raindrop API key |
| `user_id` | `str` | `None` | Associate all events with a user |
| `convo_id` | `str` | `None` | Group events into a conversation |
| `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 |

## LangGraph Support

Works with LangGraph out of the box. The handler automatically filters LangGraph-internal chain events and deduplicates LLM callbacks. Pass the handler both at `graph.invoke()` and inside your LLM node. 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.

## 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.
- **No `events.*`, `users.*`, or `signals.*` APIs** — Python SDK limitation. Use `raindrop.analytics` directly for these features.

## Testing

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