Langchain

---
name: LangChain
description: Avoid common LangChain mistakes — LCEL gotchas, memory persistence, RAG chunking, and output parser traps.
metadata: {"clawdbot":{"emoji":"🦜","requires":{"bins":["python3"]},"os":["linux","darwin","win32"]}}
---

## LCEL Basics
- `|` pipes output to next — `prompt | llm | parser`
- `RunnablePassthrough()` forwards input unchanged — use in parallel branches
- `RunnableParallel` runs branches concurrently — `{"a": chain1, "b": chain2}`
- `.invoke()` for single, `.batch()` for multiple, `.stream()` for tokens
- Input must match expected keys — `{"question": x}` not just `x` if prompt expects `{question}`

## Memory Gotchas
- Memory doesn't auto-persist between sessions — save/load explicitly
- `ConversationBufferMemory` grows unbounded — use `ConversationSummaryMemory` for long chats
- Memory key must match prompt variable — `memory_key="chat_history"` needs `{chat_history}` in prompt
- `return_messages=True` for chat models — `False` returns string for completion models

## RAG Chunking
- Chunk size affects retrieval quality — too small loses context, too large dilutes relevance
- Chunk overlap prevents cutting mid-sentence — 10-20% overlap typical
- `RecursiveCharacterTextSplitter` preserves structure — splits on paragraphs, then sentences
- Embedding dimension must match vector store — mixing models causes silent failures

## Output Parsers
- `PydanticOutputParser` needs format instructions in prompt — call `.get_format_instructions()`
- Parser failures aren't always loud — malformed JSON may partially parse
- `OutputFixingParser` retries with LLM — wraps another parser, fixes errors
- `with_structured_output()` on chat models — cleaner than manual parsing for supported models

## Retrieval
- `similarity_search` returns documents — `.page_content` for text
- `k` parameter controls results count — more isn't always better, noise increases
- Metadata filtering before similarity — `filter={"source": "docs"}` in most vector stores
- `max_marginal_relevance_search` for diversity — avoids redundant similar chunks

## Agents
- Agents decide tool order dynamically — chains are fixed sequence
- Tool descriptions matter — agent uses them to decide when to call
- `handle_parsing_errors=True` — prevents crash on malformed agent output
- Max iterations prevents infinite loops — `max_iterations=10` default may be too low

## Common Mistakes
- Prompt template variables case-sensitive — `{Question}` ≠ `{question}`
- Chat models need message format — `ChatPromptTemplate`, not `PromptTemplate`
- Callbacks not propagating — pass `config={"callbacks": [...]}` through chain
- Rate limits crash silently sometimes — wrap in retry logic
- Token count exceeds context — use `trim_messages` or summarization for long histories