Principle:Langchain ai Langchain Package Scaffolding

Overview

A standardized directory structure that every LangChain partner integration package must follow to ensure consistency, testability, and compatibility with the monorepo tooling.

Description

The Package Scaffolding principle defines the canonical layout for a LangChain partner integration package. Every partner package lives under libs/partners/<name>/ in the LangChain monorepo and must contain a predictable set of directories and files. This structure enables the CI/CD pipeline to automatically discover packages, run the correct test suites, enforce linting standards, and publish releases without per-package configuration.

The required layout includes:

• A Python package directory (langchain_<name>/) containing the integration source code, an __init__.py that exports the public API, and a py.typed marker for PEP 561 type-checking support.
• A tests directory split into tests/unit_tests/ (no network access permitted) and tests/integration_tests/ (real API calls allowed).
• A scripts directory (scripts/) for package-level automation utilities such as import checkers.
• A Makefile providing standardized targets: test, lint, format, integration_tests, and help.
• A pyproject.toml that configures the build system, dependencies, dev groups, and tool settings.
• A README.md describing the integration.
• A uv.lock file for reproducible dependency resolution.

This structure mirrors every other partner package in the repository, making it straightforward for contributors to navigate unfamiliar integrations and for CI tooling to operate uniformly.

Usage

Apply this principle when:

• Creating a new LangChain partner integration from scratch.
• Auditing an existing partner package for compliance with monorepo conventions.
• Writing CI/CD scripts that need to discover and operate on partner packages generically.

Theoretical Basis

The scaffolding follows a convention-over-configuration philosophy. By enforcing a uniform layout, the monorepo can use glob patterns and path-based heuristics to automatically detect packages and run the appropriate workflows.

libs/partners/<name>/
  langchain_<name>/
    __init__.py          # Public API exports, __all__, __version__
    chat_models.py       # (or other modules) integration source code
    py.typed             # PEP 561 marker
    data/                # Optional static data (e.g., model profiles)
  tests/
    __init__.py
    unit_tests/          # Offline tests (--disable-socket)
      __init__.py
      test_chat_models.py
    integration_tests/   # Online tests (real API calls)
      __init__.py
      test_chat_models.py
  scripts/               # Package-specific automation
    check_imports.py
  Makefile               # Standardized make targets
  pyproject.toml         # Build, deps, tool config
  README.md              # Integration description
  LICENSE                # License file
  uv.lock               # Locked dependencies

Related Pages

• Implementation:Langchain_ai_Langchain_Partner_Directory_Layout