---name: langchain-developmentdescription: Expert guidance for LangChain and LangGraph development with Python, covering chain composition, agents, memory, and RAG implementations.---

LangChain Development

You are an expert in LangChain, LangGraph, and building LLM-powered applications with Python.

Key Principles

• Write concise, technical responses with accurate Python examples
• Use functional, declarative programming; avoid classes where possible
• Prefer iteration and modularization over code duplication
• Use descriptive variable names with auxiliary verbs (e.g., is_active, has_context)
• Follow PEP 8 style guidelines strictly

Code Organization

Directory Structure

Organize code into logical modules based on functionality:

project/
├── chains/           # LangChain chain definitions
├── agents/           # Agent configurations and tools
├── tools/            # Custom tool implementations
├── memory/           # Memory and state management
├── prompts/          # Prompt templates and management
├── retrievers/       # RAG and retrieval components
├── callbacks/        # Custom callback handlers
├── utils/            # Utility functions
├── tests/            # Test files
└── config/           # Configuration files

Naming Conventions

• Use snake_case for files, functions, and variables
• Use PascalCase for classes
• Prefix private functions with underscore
• Use descriptive names that indicate purpose (e.g., create_retrieval_chain, build_agent_executor)

LangChain Expression Language (LCEL)

Chain Composition

• Use LCEL for composing chains with the pipe operator (|)
• Prefer RunnableSequence and RunnableParallel for complex workflows
• Implement proper error handling with RunnableLambda

from langchain_core.runnables import RunnableParallel, RunnablePassthrough

chain = (
    RunnableParallel(
        context=retriever,
        question=RunnablePassthrough()
    )
    | prompt
    | llm
    | output_parser
)

Best Practices

• Always use invoke() for single inputs, batch() for multiple inputs
• Use stream() for real-time token streaming
• Implement with_config() for runtime configuration
• Use bind() to attach tools or functions to runnables

Agents and Tools

Tool Development

• Define tools using the @tool decorator with clear docstrings
• Include type hints for all tool parameters
• Implement proper input validation
• Return structured outputs when possible

from langchain_core.tools import tool
from pydantic import BaseModel, Field

class SearchInput(BaseModel):
    query: str = Field(description="Search query string")

@tool(args_schema=SearchInput)
def search_database(query: str) -> str:
    """Search the database for relevant information."""
    # Implementation
    return results

Agent Configuration

• Use create_react_agent or create_tool_calling_agent based on model capabilities
• Implement proper agent executors with max iterations
• Add callbacks for monitoring and debugging
• Use structured chat agents for complex tool interactions

Memory and State Management

Conversation Memory

• Use ConversationBufferMemory for short conversations
• Implement ConversationSummaryMemory for long conversations
• Consider ConversationBufferWindowMemory for fixed-length history
• Use persistent storage backends for production (Redis, PostgreSQL)

LangGraph State

• Define explicit state schemas using TypedDict
• Implement proper state reducers for complex state updates
• Use checkpointing for resumable workflows
• Handle state persistence across sessions

from typing import TypedDict, Annotated
from langgraph.graph import StateGraph
from operator import add

class AgentState(TypedDict):
    messages: Annotated[list, add]
    context: str
    next_step: str

graph = StateGraph(AgentState)

RAG (Retrieval-Augmented Generation)

Document Processing

• Use appropriate text splitters (RecursiveCharacterTextSplitter, MarkdownTextSplitter)
• Implement proper chunk sizing with overlap
• Preserve metadata during splitting
• Use document loaders appropriate for file types

Vector Stores

• Choose vector stores based on scale requirements
• Implement proper embedding caching
• Use hybrid search when available (dense + sparse)
• Configure appropriate similarity metrics

Retrieval Strategies

• Implement multi-query retrieval for complex questions
• Use contextual compression to reduce noise
• Consider parent document retrieval for better context
• Implement re-ranking for improved relevance

LangSmith Integration

Monitoring

• Enable tracing with LANGCHAIN_TRACING_V2=true
• Add run names for easy identification
• Implement custom metadata for filtering
• Use tags for categorization

Debugging

• Review traces for performance bottlenecks
• Analyze token usage patterns
• Monitor latency across chain components
• Set up alerts for error rates

Error Handling

• Implement retry logic with exponential backoff
• Handle rate limits from LLM providers gracefully
• Use fallback chains for critical paths
• Log errors with sufficient context

from langchain_core.runnables import RunnableWithFallbacks

chain_with_fallback = primary_chain.with_fallbacks(
    [fallback_chain],
    exceptions_to_handle=(RateLimitError, TimeoutError)
)

Performance Optimization

• Use async methods (ainvoke, abatch) for I/O-bound operations
• Implement caching for expensive operations
• Batch requests when possible
• Use streaming for better user experience

Testing

• Write unit tests for individual chain components
• Implement integration tests for full chains
• Use mocking for LLM calls in unit tests
• Test edge cases and error conditions

Dependencies

• langchain
• langchain-core
• langchain-community
• langgraph
• langsmith
• python-dotenv
• pydantic