langchain/openwiki/quickstart.md at 17dd9830c059f0f2d1113e4c5256e499c26887b6

0 Fork 0

mirror of https://github.com/langchain-ai/langchain.git synced 2026-10-05 09:25:14 +03:00

Files

T

github-actions[bot]andnpentrel a9780cd3dd docs: update OpenWiki (#40903 )

Automated OpenWiki documentation update.

OpenWiki result: success

When the result is `failure`, this PR intentionally preserves only the
pages completed before the failure. Merge it to make that progress the
baseline for the next scheduled run.

Co-authored-by: npentrel <5212232+npentrel@users.noreply.github.com>

2026-09-29 11:29:02 -04:00

18 KiB

Raw Blame History

type, title, description, tags, verified, sources, generated

type

title

description

Welcome to LangChain Development

LangChain is the agent engineering platform—a framework for building LLM-powered applications with composable abstractions, provider integrations, and orchestration primitives. This page guides you through the monorepo structure, essential setup, common dev tasks, and routing to deeper documentation.

New to the repo? Start with Installation & Setup, then jump to Quick Navigation to find what you need to work on.

Want a complete tour? See Architecture Overview for system design, Dev Commands for detailed CLI reference, and Source Map to locate code by topic.

Monorepo Overview

LangChain is organized as a three-layer architecture in /libs/:

/libs/
├── core/              # langchain-core (v1.6.5): Base abstractions (Runnable, BaseChatModel, tools, prompts, messages)
├── langchain_v1/      # langchain (v1.4.3): Agent orchestration, factory, middleware
├── partners/          # Provider-specific integrations (OpenAI, Anthropic, Ollama, etc.)
├── standard-tests/    # Shared test suites for component conformance
├── text-splitters/    # Text splitting utilities
├── model-profiles/    # LLM metadata and capability profiles
└── Makefile           # Monorepo-level build targets

When to Edit Each Layer

Layer	Edit when you are…	Key files
core	Adding or modifying base abstractions and core interfaces: `Runnable`, `BaseChatModel`, messages, tools, prompts, callbacks, output parsers.	`libs/core/langchain_core/`
langchain_v1	Building agent factory features (`create_agent`), middleware composition, model initialization (`init_chat_model`), or high-level orchestration.	`libs/langchain_v1/langchain/agents/factory.py`, `libs/langchain_v1/langchain/chat_models/base.py`
partners/{name}	Adding a new LLM provider (OpenAI, Anthropic, etc.), implementing `ChatModel`, handling message conversion, or adding provider-specific features (streaming, tool calling, structured output).	`libs/partners/{provider}/langchain_{provider}/chat_models/base.py`
standard-tests	Defining reusable test suites and test fixtures for evaluating chat models, embeddings, and tools across all providers.	`libs/standard-tests/langchain_tests/`
model-profiles	Publishing model metadata, capability profiles, context windows, and supported features for discovery by `init_chat_model`.	`libs/model-profiles/langchain_model_profiles/`

Installation & Setup

Clone the Repository

git clone https://github.com/langchain-ai/langchain.git
cd langchain

Install Dependencies with `uv`

The monorepo uses uv for fast, deterministic dependency resolution. Install it once:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or via Homebrew
brew install uv

Then sync all dependencies in your package:

# From any libs/ subdirectory, install all groups (test, lint, type, typing, dev)
uv sync --all-groups

# Or install only what you need
uv sync --group test          # For running tests
uv sync --group test_integration  # For integration tests with VCR cassettes
uv sync --group lint          # For ruff formatting
uv sync --group typing        # For mypy type checking
uv sync --group dev           # For dev tools (Jupyter, setuptools, etc.)

Pre-Commit Hooks

Install git hooks to enforce code quality automatically:

pre-commit install

# To manually run all hooks
pre-commit run --all-files

# To run a specific hook
pre-commit run ruff --all-files

Pre-commit hooks run:

YAML/TOML syntax validation
Text normalization and trailing whitespace fixes
Per-package formatting and linting (ruff, mypy)
Version consistency checks across pyproject.toml files

Common Development Tasks

Run Unit Tests

# From any package directory (libs/core, libs/langchain_v1, etc.)
make test

# Run a specific test file
make test TEST_FILE=tests/unit_tests/agents/test_factory.py

# Run tests in watch mode (auto-rerun on file changes)
make test_watch

# Run extended tests (marked @pytest.mark.requires)
make extended_tests

Key details:

Tests run with socket restrictions (--disable-socket) to prevent accidental network calls
Tests run in parallel via pytest-xdist (-n auto)
LangSmith tracing variables are unset to keep tests isolated
Typical test path mirrors source: langchain_core/runnables/base.py → tests/unit_tests/runnables/test_base.py

Format and Lint

# Format all Python files (ruff)
make format

# Check linting issues (ruff, mypy)
make lint

# Type checking only (mypy)
make type

# Format only changed files (git diff against main)
make format_diff

Tools used:

ruff: Fast Python linter and formatter (replaces black, isort, flake8). Run via uv run --group lint
mypy: Static type checker. Run via uv run --group typing
Both are integrated into pre-commit hooks and make targets

Run Integration Tests

Integration tests call real model APIs with recorded responses (VCR cassettes):

# From any package directory
make integration_tests

# Run a specific integration test
make integration_tests TEST_FILE=tests/integration_tests/test_specific.py

# Record new cassettes (requires API credentials in .env)
make integration_tests RECORD=true

See Integration Testing for detailed cassette management.

Full Local Validation

Run this before pushing a PR:

# From your package directory
make format && make lint && make test

Or in one line:

cd libs/core && make format lint test

For integration tests as well:

cd libs/langchain_v1 && make format lint test integration_tests

Use the table below to route to detailed documentation:

Task	Start Here	Key Concepts
Build an agent	Agent Factory	create_agent, AgentState, middleware composition, graph execution
Add a new LLM provider	Adding a Chat Model Provider	ChatModel impl, message conversion, provider registration, standard tests
Integrate OpenAI (ChatGPT, o1, etc.)	OpenAI Integration	ChatOpenAI, Responses API, vision, streaming, tool calling, Azure
Understand the architecture	Architecture Overview	Three-layer design, dependency flow, core vs. orchestration vs. partners
Work with chat models	Chat Model Interface	BaseChatModel protocol, streaming, tool binding, structured output
Initialize models dynamically	Model Initialization	init_chat_model factory, provider:model syntax, fallback chains
Compose components (chains, pipelines)	Runnables & Composability, Composability	Runnable protocol, \| operator, branching, retry, fallback
Work with tools	Tools	BaseTool, schema generation, tool calling, result handling
Stream responses	Streaming	Token-by-token output, streaming across components
Enforce response formats	Structured Output	JSON schemas, response validation, typed outputs
Write middleware	Agent Middleware	Middleware types, composition, custom hooks
Trace agent execution	Agent Execution Flow	Runtime lifecycle, loop control, state transitions
Add observability	Callbacks & Tracing	Callback manager, LangSmith integration, logging
Write unit/integration tests	Unit Testing, Integration Testing	Test structure, fixtures, mocking, VCR cassettes
Work with prompts	Prompts	Templates, few-shot, variables, image handling
Understand message types	Messages	AIMessage, ToolMessage, content blocks, provider conversion
Use Model Context Protocol	MCP Integration	MCP servers, tool adapters, elicitation
Reference all file paths	Source Map	Concept-to-path lookup table, directory structure
Check CI/CD workflows	CI/CD Workflows	GitHub Actions, testing, linting, release process
Development command reference	Dev Commands	Detailed make targets, uv syntax, env setup

Repository Structure at a Glance

Root Level

/
├── .github/              # GitHub Actions workflows (CI/CD)
├── .pre-commit-config.yaml # Pre-commit hooks definition
├── .vscode/              # VS Code settings
├── libs/                 # Main monorepo workspace
├── AGENTS.md             # Contributing guide (READ THIS BEFORE PR)
└── README.md             # Top-level project overview

Inside `/libs/`

core/ — Base abstractions (langchain-core package)

core/
├── langchain_core/
│   ├── language_models/  # BaseChatModel and language model contracts
│   ├── messages/         # Message types and content blocks
│   ├── runnables/        # Runnable protocol and operators
│   ├── tools/            # BaseTool and tool utilities
│   ├── prompts/          # Prompt templates and few-shot
│   ├── callbacks/        # Callback manager and handlers
│   └── output_parsers/   # Output parsing and validation
├── tests/unit_tests/     # Unit tests (no network)
├── tests/integration_tests/ # Integration tests (live APIs)
├── Makefile              # Build targets (test, lint, format)
└── pyproject.toml        # Package deps and metadata

langchain_v1/ — Agent orchestration (langchain package)

langchain_v1/
├── langchain/
│   ├── agents/
│   │   ├── factory.py    # create_agent function
│   │   ├── middleware/   # Pluggable middleware hooks
│   │   └── structured_output.py # Response schema
│   ├── chat_models/
│   │   └── base.py       # init_chat_model factory
│   ├── mcp/              # Model Context Protocol
│   └── ...
├── tests/unit_tests/
├── tests/integration_tests/
├── tests/cassettes/      # VCR cassettes for HTTP mocking
├── Makefile
└── pyproject.toml

partners/ — Provider integrations

partners/
├── openai/               # ChatOpenAI (Chat Completions & Responses APIs), embeddings
├── anthropic/            # ChatAnthropic (Claude)
├── ollama/               # ChatOllama (local models)
├── groq/                 # ChatGroq
├── mistralai/            # ChatMistralAI
├── huggingface/          # HuggingFace models/embeddings
├── deepseek/             # ChatDeepSeek
└── ... (20+ more providers)

Each partner has the same structure:

provider/
├── langchain_{provider}/
│   ├── __init__.py       # Exports ChatModel class
│   ├── chat_models/
│   │   └── base.py       # ChatModel implementation
│   └── data/             # Model profiles
├── tests/
│   ├── unit_tests/       # Standard tests + custom
│   └── integration_tests/
├── pyproject.toml
├── Makefile
└── uv.lock

Some providers (like OpenAI) support advanced API modes—see OpenAI Integration for details on the Responses API and streaming with structured output.

Your First PR: A Workflow

1. Pick a Task

Decide what you want to work on using the Quick Navigation table above. For first-time contributors:

Easy: Add a test, fix a type error, improve documentation
Medium: Add a new middleware hook, extend a tool interface
Hard: Add a new provider integration (follow Adding a Chat Model Provider)

2. Read the Contributing Guide

Before coding, read:

AGENTS.md — Conventions, style, and PR expectations
Relevant wiki page — Deep context on your area (see table above)

3. Set Up Your Package

cd libs/{core|langchain_v1|partners/provider}
uv sync --all-groups
pre-commit install

4. Make Your Changes

Follow the style and patterns you see in the codebase. Use type hints; write tests alongside code.

5. Run Local Checks

make format lint test

All checks must pass before pushing.

6. Commit and Push

Follow Conventional Commits format with scope (required):

git add .
# Format: type(scope): description
# Example: feat(core): add streaming support to BaseChatModel
# Example: fix(openai): handle timeout errors gracefully
git commit -m "type(scope): description"
git push origin your-branch

See AGENTS.md for commit conventions and branch naming (<username>/<scope>/<description>).

Pre-commit hooks will run automatically. If they fail, fix and commit again.

7. Open a Pull Request

Link the PR to any relevant issue and reference the wiki pages you read in the description. The LangChain team will review and provide feedback.

Key Files to Know

File	Purpose
`AGENTS.md`	Contributing guide, style, and conventions
`libs/Makefile`	Monorepo-level make targets (lock, check-lock)
`libs/{core,langchain_v1,partners/*/Makefile`	Per-package test, lint, format targets
`.pre-commit-config.yaml`	Git hooks for code quality
`pyproject.toml` (per-package)	Package metadata, dependencies, build config

Troubleshooting

Tests Fail with Socket Errors

Tests run with socket restrictions by default. If you need network access:

Write an integration test in tests/integration_tests/ (see Integration Testing)
Or disable socket restrictions locally: uv run --group test pytest --disable-socket=false ...

Import Errors or Version Mismatches

Regenerate lockfiles:

cd libs
make lock

Or in a single package:

cd libs/core
uv lock

Type Checking Fails

Run mypy to see detailed errors:

make type

Check the Chat Models or Runnables pages for type signature patterns.

Pre-Commit Hooks Block Commit

Pre-commit will auto-fix formatting and some issues. Re-stage and commit:

git add .
git commit -m "..."  # Try again

If linting still fails, run make lint to see details and fix manually.

Quick Command Reference

# Setup
uv sync --all-groups          # Install all dependencies
pre-commit install            # Setup git hooks

# Testing
make test                      # Run unit tests
make test TEST_FILE=path/     # Run specific test file
make test_watch               # Watch mode (auto-rerun)
make integration_tests        # Run integration tests

# Code Quality
make format                   # Format code (ruff)
make lint                     # Check linting (ruff, mypy)
make type                     # Type check only (mypy)

# Lockfile Management
cd libs && make lock          # Regenerate all lockfiles
cd libs && make check-lock    # Verify lockfiles are up-to-date

# All Before PR
make format && make lint && make test

Next Steps

Read AGENTS.md for contributing conventions
Pick a wiki page from Quick Navigation matching your task
Clone, setup, and make your first change
Run make format lint test to validate locally
Open a PR and engage with the team

Welcome to LangChain! 🚀

18 KiB Raw Blame History