Workflow:Langchain ai Langchain Adding Partner Integration
| Knowledge Sources | |
|---|---|
| Domains | Integration_Development, Testing, Package_Management |
| Last Updated | 2026-02-11 15:00 GMT |
Overview
End-to-end process for creating a new LangChain partner integration package that conforms to the standard package structure, test suite, and CI pipeline.
Description
This workflow describes how to add a new third-party model provider or service integration to the LangChain monorepo. Each partner integration is an independently versioned Python package under libs/partners/ that implements LangChain's abstract interfaces (BaseChatModel, Embeddings, VectorStore, etc.) for a specific provider. The integration must conform to the standard package structure, pass the shared test suite from langchain-tests, and integrate with the monorepo's CI/CD pipeline. The process covers package scaffolding, model implementation, test conformance, linting, and release preparation.
Usage
Execute this workflow when adding support for a new AI model provider, embedding service, vector database, or other integration to the LangChain ecosystem. This applies to both team-maintained integrations (in the main monorepo) and community-maintained integrations (in separate repositories following the same patterns).
Execution Steps
Step 1: Scaffold the Package Structure
Create the standard directory structure under libs/partners/{provider_name}/. Every partner package follows a consistent layout: a source directory langchain_{provider}/ with __init__.py, implementation modules, and a data/ subdirectory for model profiles; a tests/ directory with unit_tests/ and integration_tests/ subdirectories; a scripts/ directory with import validation scripts; and top-level configuration files (pyproject.toml, Makefile, README.md).
Key considerations:
- Package name follows the pattern langchain-{provider} (with hyphen)
- Import name follows the pattern langchain_{provider} (with underscore)
- Include py.typed marker file for PEP 561 type checking support
- Use existing simple integrations (e.g., deepseek, xai) as templates
Step 2: Configure Package Metadata
Write the pyproject.toml with package metadata, dependencies, and development tool configuration. Declare langchain-core as a required dependency with a compatible version range. Set up dependency groups for testing (test), linting (lint), type checking (typing), and integration testing (test_integration). Configure uv sources for local editable installs of langchain-core during development. Set up ruff for linting/formatting and mypy with strict type checking (disallow_untyped_defs = true).
Key considerations:
- Use hatchling as the build backend (consistent with other packages)
- Pin dependency ranges (e.g., langchain-core>=1.1.0,<2.0.0)
- Include editable source references in [tool.uv.sources] for local development
- Set requires-python = ">=3.10.0,<4.0.0"
Step 3: Implement the Chat Model Class
Create the main model class extending BaseChatModel from langchain-core (or BaseChatOpenAI for OpenAI-compatible APIs). Implement the required abstract methods: _generate() for synchronous generation and _stream() for synchronous streaming. Optionally implement _agenerate() and _astream() for native async support. Register model profiles in data/_profiles.py to provide capability metadata (context window, supported features).
Key considerations:
- All public methods must have complete type hints and return types
- Use Google-style docstrings with Args, Returns, and Raises sections
- API keys should be read from environment variables using Pydantic SecretStr
- The _llm_type property must return a unique string identifier
- Override bind_tools() and with_structured_output() if the provider has native tool support
Step 4: Implement the Public API Surface
Define the package's public API in __init__.py using an explicit __all__ list. Export the main classes (chat model, embeddings, vector store as applicable). Read the package version dynamically from importlib.metadata. Keep the public API minimal and intentional.
Key considerations:
- __all__ must exactly match what is importable
- Import validation scripts (check_imports.py) verify this at CI time
- Import boundary scripts (lint_imports.sh) enforce that the package does not import from other partner packages
Step 5: Write Unit Tests with Standard Test Conformance
Create unit tests that inherit from ChatModelUnitTests (and EmbeddingsUnitTests, VectorStoreIntegrationTests as applicable) from the langchain-tests package. Implement the required abstract properties: chat_model_class returns the model class, chat_model_params returns initialization parameters, and init_from_env_params defines environment variable mappings. Override feature-support properties (has_tool_calling, supports_json_mode, etc.) to declare what the model supports.
Key considerations:
- Unit tests must run without network calls (use pytest-socket to enforce)
- The standard test suite automatically generates tests based on declared capabilities
- Custom tests should cover provider-specific behavior not in the standard suite
- Test file structure must mirror source code structure
Step 6: Write Integration Tests
Create integration tests that inherit from ChatModelIntegrationTests and make real API calls to validate end-to-end behavior. These tests require API keys set as environment variables and are run separately from unit tests. Include a test_compile.py placeholder that validates the test module can be imported.
Key considerations:
- Integration tests run on a scheduled basis and during releases
- API keys are stored as GitHub secrets for CI
- Tests should cover: basic invocation, streaming, tool calling, structured output
- Use VCR cassettes (optional) for reproducible HTTP recordings
Step 7: Configure CI Integration
Ensure the package is recognized by the monorepo's CI system. The .github/scripts/check_diff.py script automatically detects changed packages from git diffs. Add the package to Dependabot configuration in .github/dependabot.yml for automated dependency updates. Add the package to the PR labeler configuration for automatic labeling.
Key considerations:
- CI automatically runs lint, unit tests, and type checking for changed packages
- The Makefile must support standard targets: test, lint, format, spell_check
- Pre-commit hooks run codespell and ruff across the monorepo
- Integration tests are triggered separately with provider-specific secrets
Step 8: Prepare for Release
Finalize the package for release by setting the version in pyproject.toml, writing a comprehensive README.md with installation and usage examples, and ensuring all linting and tests pass. The release workflow (_release.yml) handles building, Test PyPI publishing, pre-release validation, and production PyPI publishing through trusted publishing (no manual credentials).
Key considerations:
- Version follows semantic versioning
- README should include installation command, basic usage example, and link to documentation
- Release is triggered manually via GitHub Actions workflow dispatch
- The release pipeline publishes to Test PyPI first, runs validation, then publishes to production PyPI