0
# Integration Development
1

2
Create LangChain integration packages with automated scaffolding, template processing, and documentation generation for various component types. This namespace provides tools for building LangChain integrations with external services and libraries.
3

4
## Capabilities
5

6
### Create New Integration
7

8
Creates a new integration package with standardized structure, template processing, and development dependencies.
9

10
```bash { .api }
11
langchain integration new [options]
12

13
Options:
14
  --name TEXT          The name of the integration to create (required, prompt if not provided)
15
  --name-class TEXT    The PascalCase name for classes (e.g. MyIntegration)
16
  --src TEXT          Template file to copy (can be repeated)
17
  --dst TEXT          Destination path for template file (can be repeated)
18
```
19

20
**Usage Examples:**
21

22
```bash
23
# Create full integration package interactively
24
langchain integration new --name my-integration
25

26
# Create with specific class name
27
langchain integration new --name my-integration --name-class MyCustomIntegration
28

29
# Copy specific template files
30
langchain integration new --name my-integration --src chat_models.py --dst my_integration/chat_models.py
31

32
# Copy multiple template files
33
langchain integration new --name my-integration \
34
  --src chat_models.py --dst my_integration/chat.py \
35
  --src embeddings.py --dst my_integration/embeddings.py
36
```
37

38
**Name Processing:**
39

40
Integration names are automatically processed:
41
- Input: `my-custom-integration` 
42
- Package name: `langchain-my-custom-integration`
43
- Module name: `langchain_my_custom_integration`
44
- Class prefix: `MyCustomIntegration`
45

46
### Create Integration Documentation
47

48
Generate integration documentation using pre-built templates for different component types.
49

50
```bash { .api }
51
langchain integration create-doc [options]
52

53
Options:
54
  --name TEXT           Kebab-case integration name (required, prompt if not provided)
55
  --name-class TEXT     PascalCase integration name
56
  --component-type TEXT Component type (default: ChatModel)
57
  --destination-dir TEXT Relative path to docs directory (required, prompt if not provided)
58
```
59

60
**Supported Component Types:**
61

62
- `ChatModel`: Chat model implementations
63
- `DocumentLoader`: Document loading utilities
64
- `Tool`: LangChain tools
65
- `VectorStore`: Vector storage implementations
66
- `Embeddings`: Text embedding models
67
- `ByteStore`: Key-value storage
68
- `LLM`: Language model implementations
69
- `Provider`: Service provider integrations
70
- `Toolkit`: Tool collections
71
- `Retriever`: Document retrieval systems
72

73
**Usage Examples:**
74

75
```bash
76
# Create chat model documentation
77
langchain integration create-doc --name openai --component-type ChatModel --destination-dir docs/docs/integrations/chat/
78

79
# Create vector store documentation
80
langchain integration create-doc --name pinecone --component-type VectorStore --destination-dir docs/docs/integrations/vectorstores/
81

82
# Create documentation with custom class name
83
langchain integration create-doc --name vertex-ai --name-class VertexAI --component-type ChatModel --destination-dir docs/docs/integrations/chat/
84
```
85

86
## Programmatic API
87

88
### Integration Namespace Functions
89

90
```python { .api }
91
def new(
92
    name: str,
93
    name_class: Optional[str] = None,
94
    src: Optional[list[str]] = None,
95
    dst: Optional[list[str]] = None,
96
) -> None:
97
    """Create a new integration package."""
98

99
def create_doc(
100
    name: str,
101
    name_class: Optional[str] = None,
102
    component_type: str = "ChatModel",
103
    destination_dir: str = "docs/docs/integrations/chat/",
104
) -> None:
105
    """Create a new integration doc."""
106

107
def _process_name(name: str, *, community: bool = False) -> Replacements:
108
    """
109
    Process integration name into various template replacement formats.
110
    
111
    Args:
112
        name: Raw integration name  
113
        community: Whether this is a community integration
114
        
115
    Returns:
116
        Replacements dictionary with processed name variants
117
        
118
    Raises:
119
        ValueError: If name doesn't match required pattern
120
    """
121
```
122

123
### Type Definitions
124

125
```python { .api }
126
class Replacements(TypedDict):
127
    """Template replacement mappings."""
128
    __package_name__: str
129
    __module_name__: str
130
    __ModuleName__: str
131
    __MODULE_NAME__: str
132
    __package_name_short__: str
133
    __package_name_short_snake__: str
134

135
TEMPLATE_MAP: dict[str, str] = {
136
    "ChatModel": "chat.ipynb",
137
    "DocumentLoader": "document_loaders.ipynb", 
138
    "Tool": "tools.ipynb",
139
    "VectorStore": "vectorstores.ipynb",
140
    "Embeddings": "text_embedding.ipynb",
141
    "ByteStore": "kv_store.ipynb",
142
    "LLM": "llms.ipynb",
143
    "Provider": "provider.ipynb",
144
    "Toolkit": "toolkits.ipynb",
145
    "Retriever": "retrievers.ipynb",
146
}
147
```
148

149
## Integration Package Structure
150

151
Full integration packages have the following structure:
152

153
```
154
langchain-my-integration/
155
├── pyproject.toml                    # Package configuration
156
├── README.md                         # Package documentation
157
├── langchain_my_integration/         # Main package
158
│   ├── __init__.py                  # Package exports
159
│   ├── chat_models.py               # Chat model implementations
160
│   ├── embeddings.py                # Embedding implementations
161
│   ├── vectorstores.py              # Vector store implementations
162
│   └── ...                          # Other component types
163
├── tests/                           # Test suite
164
│   ├── integration_tests/           # Integration tests
165
│   └── unit_tests/                  # Unit tests
166
└── docs/                            # Documentation
167
```
168

169
## Template Processing
170

171
### Available Templates
172

173
The integration template system includes:
174

175
- **Chat Models**: `chat_models.py` - Chat completion interfaces
176
- **Embeddings**: `embeddings.py` - Text embedding models
177
- **Vector Stores**: `vectorstores.py` - Vector database integrations
178
- **Document Loaders**: `document_loaders.py` - Document ingestion
179
- **Tools**: `tools.py` - LangChain tool implementations
180
- **Toolkits**: `toolkits.py` - Tool collections
181
- **Retrievers**: `retrievers.py` - Document retrieval systems
182

183
### Template Variables
184

185
Templates use these replacement variables:
186

187
- `__package_name__`: Full package name (e.g., `langchain-my-integration`)
188
- `__module_name__`: Python module name (e.g., `langchain_my_integration`)
189
- `__ModuleName__`: PascalCase class prefix (e.g., `MyIntegration`)
190
- `__MODULE_NAME__`: Uppercase constant prefix (e.g., `MY_INTEGRATION`)
191
- `__package_name_short__`: Short name (e.g., `my-integration`)
192
- `__package_name_short_snake__`: Snake case short name (e.g., `my_integration`)
193

194
### File Processing
195

196
Template processing includes:
197

198
1. **Directory Structure**: Complete package scaffolding
199
2. **File Copying**: Template files with variable replacement
200
3. **Dependency Installation**: Poetry setup with dev dependencies
201
4. **Configuration**: Pre-configured linting, typing, and testing
202

203
## Development Dependencies
204

205
Integration packages include comprehensive development tooling:
206

207
```toml
208
[dependency-groups]
209
dev = ["pytest", "pytest-watcher"]
210
lint = ["ruff", "mypy"] 
211
test = ["langchain-core", "langchain"]
212
typing = ["langchain"]
213
test_integration = []
214
```
215

216
## Validation and Quality
217

218
### Name Validation
219

220
Integration names must follow strict patterns:
221

222
- Start with lowercase letter
223
- Contain only lowercase letters, numbers, and hyphens
224
- No consecutive hyphens
225
- No trailing hyphens
226
- Automatic `langchain-` prefix handling
227

228
### Class Name Validation
229

230
Class names must follow Python conventions:
231

232
- Start with uppercase letter
233
- Contain only letters and numbers
234
- Used for generating component class names
235

236
### Template Validation
237

238
The system validates:
239

240
- Template file existence
241
- Destination path uniqueness
242
- Variable replacement completeness
243
- Package structure integrity
244

245
## Integration Best Practices
246

247
### Component Implementation
248

249
Follow LangChain patterns for each component type:
250

251
```python
252
from langchain_core.chat_models import BaseChatModel
253

254
class MyIntegrationChatModel(BaseChatModel):
255
    """Chat model implementation."""
256
    # Implementation details
257
```
258

259
### Configuration Management
260

261
Use Pydantic for configuration:
262

263
```python
264
from pydantic import BaseModel, Field
265

266
class MyIntegrationConfig(BaseModel):
267
    api_key: str = Field(..., description="API key for service")
268
    base_url: str = Field(default="https://api.example.com")
269
```
270

271
### Error Handling
272

273
Implement comprehensive error handling:
274

275
```python
276
from langchain_core.exceptions import LangChainException
277

278
class MyIntegrationError(LangChainException):
279
    """Integration-specific errors."""
280
```
281

282
### Testing Strategy
283

284
Include both unit and integration tests:
285

286
- **Unit Tests**: Component logic without external dependencies
287
- **Integration Tests**: Full workflow with real or mocked services
288
- **Type Tests**: MyPy validation for type safety