# Example
pnpm run start:dist ./dist/prompts/few_shot.js
```
资料来源：[examples/src/README.md:1-45]()
### Testing
Test files follow naming conventions:
- Unit tests: `*.test.ts`
- Integration tests: `*.int.test.ts`
```bash
# Run all tests
pnpm test
# Run integration tests specifically
pnpm test:int
```
For individual packages:
```bash
# Build a specific package
pnpm build --filter @langchain/textsplitters
# Run tests for a specific package
cd libs/langchain-textsplitters
pnpm test
```
资料来源：[libs/langchain-textsplitters/README.md:25-50]()
## Quick Start Example
### Basic Chat Model Usage
```typescript
import { ChatAnthropic } from "@langchain/anthropic";
import { HumanMessage } from "@langchain/core/messages";
const model = new ChatAnthropic({
model: "claude-sonnet-4-5-20250514",
});
const response = await model.invoke([
new HumanMessage("Translate "I love programming" into French.")
]);
console.log(response.content);
// Output: J'adore la programmation.
```
资料来源：[libs/providers/langchain-anthropic/README.md:1-50]()
### Document Splitting for RAG
```typescript
import { RecursiveCharacterTextSplitter } from "@langchain/textsplitters";
const text = `
LangChain
Welcome
Building applications with LLMs
`;
const splitter = RecursiveCharacterTextSplitter.fromLanguage("html", {
chunkSize: 175,
chunkOverlap: 20,
});
const output = await splitter.createDocuments([text]);
console.log(output);
```
资料来源：[examples/src/langchain-classic/indexes/html_text_splitter.ts:1-30]()
## Choosing the Right Package
### For New Projects
Use `langchain` v1.0 for new projects. It provides:
- **`createAgent`**: A cleaner, more powerful way to build agents with middleware support
- **Better performance**: Optimized for modern agent workflows
- **Focused API surface**: Less complexity, easier to learn
- **Active development**: New features and improvements focus on v1.0 APIs
### For Legacy Projects
Use `@langchain/classic` if you:
- Have existing code using legacy chains (e.g., `LLMChain`, `ConversationalRetrievalQAChain`)
- Use the indexing API
- Depend on functionality from `@langchain/community` previously re-exported from `langchain`
- Are maintaining an existing application and not yet ready to migrate
### Package Decision Flow
```mermaid
graph TD
A[New Project?] -->|Yes| B[Use langchain v1.0]
A -->|No| C[Maintaining Existing Code?]
C -->|Yes| D[Using Legacy Chains?]
C -->|No| E[Use langchain v1.0]
D -->|Yes| F[Use @langchain/classic]
D -->|No| E
```
资料来源：[libs/langchain-classic/README.md:40-80]()
## Additional Resources
| Resource | Description |
|----------|-------------|
| [Documentation](https://docs.langchain.com/oss/javascript/langchain/overview) | Official LangChain.js documentation |
| [Deep Agents](https://docs.langchain.com/oss/javascript/deepagents/) | Higher-level package for common agent patterns |
| [Release Notes](https://docs.langchain.com/oss/javascript/releases/langchain-v1) | Version-specific changelog and migration guides |
| [API Reference](https://api.js.langchain.com/) | Generated API documentation |
资料来源：[README.md:15-30]()
---
## Package Architecture
### 相关页面
相关主题：[Introduction to LangChain.js](#introduction), [Core Abstractions](#core-abstractions)
相关源码文件
以下源码文件用于生成本页说明：
- [pnpm-workspace.yaml](https://github.com/langchain-ai/langchainjs/blob/main/pnpm-workspace.yaml)
- [turbo.json](https://github.com/langchain-ai/langchainjs/blob/main/turbo.json)
- [libs/langchain-core/package.json](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/package.json)
- [libs/langchain/package.json](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain/package.json)
- [libs/langchain-classic/package.json](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-classic/package.json)
- [libs/langchain-mcp-adapters/package.json](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-mcp-adapters/package.json)
- [libs/langchain-textsplitters/package.json](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-textsplitters/package.json)
# Package Architecture
## Overview
The LangChain.js repository employs a sophisticated **monorepo architecture** built on pnpm workspaces and Turbo. This design enables modular development, shared tooling, and independent versioning across multiple packages. The monorepo structure separates concerns into distinct layers: core abstractions, main integration packages, provider-specific SDKs, and community contributions. This architectural approach allows developers to install only the dependencies they need while maintaining a coherent ecosystem where packages can reference and compose with each other seamlessly.
## Monorepo Structure
### Workspace Organization
The repository uses **pnpm workspaces** to manage multiple packages under a single repository. This enables efficient dependency management, shared node_modules, and unified versioning strategies across the ecosystem.
```mermaid
graph TD
A[Root: langchainjs] --> B[libs/]
A --> C[examples/]
A --> D[docs/]
B --> E[langchain-core/]
B --> F[langchain/]
B --> G[langchain-classic/]
B --> H[providers/]
B --> I[langchain-textsplitters/]
B --> J[community/]
H --> K[langchain-openai/]
H --> L[langchain-anthropic/]
H --> M[langchain-google/]
H --> N[langchain-pinecone/]
H --> O[langchain-qdrant/]
```
### Build Pipeline with Turbo
The build system uses **Turbo** to orchestrate builds, tests, and linting across packages. Turbo's caching mechanism significantly improves build times by only rebuilding packages that have changed since the last build.
```mermaid
graph LR
A[pnpm install] --> B[turbo build]
B --> C[langchain-core]
C --> D[langchain]
C --> E[providers]
C --> F[community]
D --> G[langchain-classic]
G --> H[examples]
```
## Core Packages
### @langchain/core
The foundational package that contains all core abstractions, interfaces, and utilities. This package is a peer dependency for all other LangChain packages and must be kept synchronized across the ecosystem.
```mermaid
graph TD
A[@langchain/core] --> B[Messages & Chat Models]
A --> C[Tools & Toolkits]
A --> D[Vector Stores]
A --> E[Document Loaders]
A --> F[Output Parsers]
A --> G[Retrievers]
A --> H[Callbacks]
A --> I[Memory]
```
**Key Responsibilities:**
- Defines base classes for all major abstractions (BaseLanguageModel, BaseRetriever, BaseChatModel)
- Provides TypeScript utilities and type guards for common patterns
- Exports core message types (AIMessage, HumanMessage, SystemMessage, ToolMessage)
- Implements hash utilities and data transformation functions
### @langchain/langchain
The main package that re-exports functionality from core and community packages. This serves as a convenient entry point for users who want access to all integrations without managing individual package dependencies.
### @langchain/classic
Contains legacy chain implementations from v0.x that have been deprecated or replaced in v1.0. This package provides migration paths for existing users while maintaining backward compatibility.
| Component | Description |
|-----------|-------------|
| LLMChain | Basic chain for calling an LLM with a prompt template |
| ConversationalRetrievalQAChain | Chain for conversational question-answering over documents |
| RetrievalQAChain | Chain for question-answering over documents without conversation memory |
| StuffDocumentsChain | Chain for stuffing documents into a prompt |
| MapReduceDocumentsChain | Chain for map-reduce operations over documents |
| RefineDocumentsChain | Chain for iterative refinement over documents |
## Text Processing Packages
### @langchain/textsplitters
Provides various implementations of text splitters commonly used in retrieval-augmented generation (RAG) pipelines. Text splitters break large documents into smaller chunks for embedding and retrieval.
**Supported Languages:**
| Language | Use Case |
|----------|----------|
| html | HTML document splitting |
| markdown | Markdown document splitting |
| javascript | JavaScript/TypeScript code splitting |
| python | Python code splitting |
| text | Plain text splitting |
**Example Usage:**
```typescript
import { RecursiveCharacterTextSplitter } from "@langchain/textsplitters";
const splitter = RecursiveCharacterTextSplitter.fromLanguage("html", {
chunkSize: 175,
chunkOverlap: 20,
});
const output = await splitter.createDocuments([text]);
```
## Provider Integration Packages
The provider packages in `libs/providers/` contain integrations for specific third-party services. Each package follows a consistent structure and can be used independently or alongside other LangChain packages.
### Package Naming Convention
Provider packages follow the naming pattern `@langchain/[provider-name]`, where the provider name typically corresponds to the service being integrated. All provider packages depend on `@langchain/core` and may optionally depend on the provider's official SDK.
### Provider Packages
| Package | Dependency |
|---------|------------|
| @langchain/anthropic | @langchain/core, @anthropic-ai/sdk |
| @langchain/openai | @langchain/core, openai |
| @langchain/google | @langchain/core, @google-ai/generativelanguage |
| @langchain/pinecone | @langchain/core, @pinecone-database/pinecone |
| @langchain/qdrant | @langchain/core, qdrant-client |
### Common Package Structure
Each provider package follows a standardized structure:
```mermaid
graph TD
A[Package Root] --> B[README.md]
A --> C[package.json]
A --> D[src/index.ts]
A --> E[src/chat_models/]
A --> F[src/output_parsers/]
A --> G[tests/]
E --> H[index.ts]
G --> I[*.test.ts]
G --> J[*.int.test.ts]
```
## Dependency Management
### Core Dependency Synchronization
When using multiple LangChain packages in a project, it is critical to ensure all packages depend on the same instance of `@langchain/core`. Package managers may resolve different versions of `@langchain/core` as separate instances, causing runtime errors.
**Recommended Configuration (package.json):**
```json
{
"name": "your-project",
"version": "0.0.0",
"dependencies": {
"@langchain/openai": "^0.0.0",
"@langchain/anthropic": "^0.0.0",
"@langchain/core": "^0.3.0"
},
"resolutions": {
"@langchain/core": "^0.3.0"
},
"overrides": {
"@langchain/core": "^0.3.0"
}
}
```
Different package managers require specific configuration fields:
| Package Manager | Field |
|----------------|-------|
| npm/yarn | `resolutions` |
| pnpm | `pnpm.overrides` |
## Entry Points and Exports
### Export Strategy
Packages can export functionality through two mechanisms: re-exports from `src/index.ts` or explicit entry points defined in the `exports` field of `package.json`. The exports field enables conditional imports and tree-shaking optimization.
### Deprecation Warnings
When importing from deprecated entry points, packages emit console warnings directing users to the new import paths. These warnings can be suppressed by setting the environment variable `LANGCHAIN_SUPPRESS_MIGRATION_WARNINGS` to `"true"`.
```typescript
// Deprecated warning format
if (getEnvironmentVariable("LANGCHAIN_SUPPRESS_MIGRATION_WARNINGS") !== "true") {
console.warn(warningText);
}
```
## Development Workflow
### Installing Dependencies
```bash
pnpm install
```
### Building Packages
Individual packages can be built using the Turbo filter:
```bash
pnpm build --filter @langchain/core
```
### Running Tests
| Test Type | Command | File Pattern |
|-----------|---------|--------------|
| Unit Tests | `pnpm test` | `*.test.ts` |
| Integration Tests | `pnpm test:int` | `*.int.test.ts` |
Test files should be located in a `tests/` directory within the `src/` folder.
### Linting and Formatting
```bash
pnpm lint && pnpm format
```
## Migration Path
### From langchain v0.x to v1.0
The v1.0 release introduces significant architectural changes. Legacy functionality has been moved to `@langchain/classic`, while new abstractions live in `@langchain/core` and provider-specific packages. Users upgrading from v0.x should:
1. Install `@langchain/classic` for backward compatibility
2. Install new provider packages as needed
3. Update import statements to use new package paths
4. Remove imports from deprecated `langchain/` subpaths
```bash
npm install @langchain/classic
npm install @langchain/anthropic @langchain/core
```
## Summary
The LangChain.js package architecture reflects a commitment to modularity, performance, and developer experience. By separating concerns across well-defined packages, the ecosystem enables efficient development while maintaining interoperability. The monorepo structure, powered by pnpm workspaces and Turbo, provides the foundation for managing this complexity at scale.
---
## Core Abstractions
### 相关页面
相关主题：[Package Architecture](#package-architecture), [Chat Models and LLM Providers](#chat-models)
相关源码文件
以下源码文件用于生成本页说明：
- [libs/langchain-core/src/runnables/base.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/runnables/base.ts)
- [libs/langchain-core/src/language_models/chat_models.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/language_models/chat_models.ts)
- [libs/langchain-core/src/language_models/llms.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/language_models/llms.ts)
- [libs/langchain-core/src/embeddings.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/embeddings.ts)
- [libs/langchain-core/src/vectorstores.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/vectorstores.ts)
- [libs/langchain-core/src/callbacks/base.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/callbacks/base.ts)
- [libs/langchain-core/src/prompts/index.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/prompts/index.ts)
- [libs/langchain-core/src/output_parsers/index.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/output_parsers/index.ts)
# Core Abstractions
The **Core Abstractions** in LangChain.js form the foundational building blocks that enable interoperability between different components in LLM-powered applications. These abstractions define standardized interfaces for language models, embeddings, vector stores, prompts, output parsers, and runnable components, allowing developers to swap implementations without changing application logic.
## Overview
LangChain.js implements a set of abstract base classes in `@langchain/core` that establish contracts for:
- **Runnable components** that can be composed into processing pipelines
- **Language models** (chat and completion models)
- **Embedding models** for vector representations
- **Vector stores** for semantic search and retrieval
- **Callback systems** for observability and event handling
- **Prompt templates** for structured input formatting
- **Output parsers** for structured response extraction
This abstraction layer enables loose coupling between components, making it straightforward to migrate between different model providers, vector stores, or embedding implementations while maintaining the same application code.
## Runnable Architecture
### BaseRunnable
The `BaseRunnable` class is the central abstraction that all runnable components extend. It provides a unified interface for invoking, batching, streaming, and composing operations.
```mermaid
graph TD
A[BaseRunnable] --> B[invoke input]
A --> C[batch inputs]
A --> D[stream output]
A --> E[async operations]
B --> F[Runnable Sequence]
B --> G[Runnable Branch]
B --> H[Runnable Map]
style A fill:#e1f5fe
style F fill:#fff3e0
style G fill:#fff3e0
style H fill:#fff3e0
```
The `BaseRunnable` interface defines the following core methods:
| Method | Description | Signature |
|--------|-------------|-----------|
| `invoke` | Synchronous single input processing | `(input: Input, options?: RunnableConfig): Promise