docs: Add comprehensive init_chat_model usage guide

[Vishwajeet-Kumar-Patel]

Overview

This PR adds comprehensive documentation for init_chat_model, the unified model initialization function in LangChain v1. The guide includes practical examples, common mistake patterns with fixes, configuration options, and design rationale to help users effectively use the unified interface and make informed decisions about when to use it versus provider-specific classes.

New documentation: src/oss/python/langchain/init-chat-model.mdx (~700 lines)

Type of change

Type: New documentation page

Related issues/PRs

• Following maintainer feedback (@mdrxy) from PR docs: Add comprehensive init_chat_model usage guide langchain#34449
• Maintainer directed documentation contributions to this repository rather than the core library

Context: This documentation fills a gap where init_chat_model exists in LangChain v1 with validation logic, but lacks comprehensive usage guidance covering real-world patterns, common pitfalls, and configuration best practices.

What's Included

📖 Complete Documentation Sections

1. Introduction & Explanation

   • What init_chat_model is and its purpose
   • Why it exists (solves provider fragmentation problem)
   • When to use unified interface vs provider-specific classes
   • Key benefits and design principles

2. 7 Working Code Examples

   All examples are copy-paste ready and tested:

   • Fixed model initialization with specific configuration
   • Provider-agnostic code that works with any provider
   • Runtime configurable models from environment variables
   • Multiple models with environment variable prefixes
   • Tool binding for function calling
   • Streaming responses for better UX
   • Batch processing for efficiency

3. 7 Common Mistakes & Fixes

   Each documented with ❌ wrong code, ✅ correct code, and 💡 explanation:

   • Missing model provider
   • Invalid model name for provider
   • Missing API key configuration
   • Conflicting configuration parameters
   • Using unsupported parameters
   • Incorrect temperature range
   • Model name aliasing confusion

4. Configuration & Advanced Usage

   • Model parameters common across providers
   • Environment variable configuration patterns
   • Prefix-based configuration for multiple models
   • Design rationale and architectural tradeoffs

5. Reference Information

   • Complete list of supported providers
   • Links to related documentation
   • Next steps and advanced topics

📁 Files Changed

1. src/oss/python/langchain/init-chat-model.mdx (new)

   • Complete comprehensive guide (~700 lines)

2. src/docs.json (modified)

   • Added new page to "Core components" navigation section
   • Positioned logically after "models" page

3. src/oss/python/migrate/langchain-v1.mdx (modified)

   • Added Note boxes with links to comprehensive guide
   • Updated both namespace table sections for better discoverability

4. uv.lock (modified)

   • Updated dependencies after running quality checks locally

Checklist

• I have read the contributing guidelines
• I have tested my changes locally using quality checks (ruff, markdownlint, pytest, build)
• All code examples have been tested and work correctly
• I have used root relative paths for internal links
• I have updated navigation in src/docs.json if needed

Quality Checks Passed Locally

All required quality checks have been run:

✅ Ruff formatting - uv run ruff format . - 37 files checked, all formatted
✅ Ruff linting - uv run ruff check . - No new errors introduced
✅ Markdown linting - markdownlint src/oss/python/langchain/init-chat-model.mdx - No errors
✅ Unit tests - uv run pytest - 100/101 tests passed (1 pre-existing failure unrelated to changes)
✅ Documentation build - uv run pipeline build - Built successfully, no errors
✅ Output verification - build/oss/python/langchain/init-chat-model.mdx created correctly

Documentation Standards Met

• MDX format with proper YAML frontmatter (title, description)
• Follows Google Developer Documentation Style Guide
• Sentence-case for all headings
• Second-person voice ("you") throughout
• All code blocks tagged with language identifiers
• Root-relative paths for all internal links (e.g., /oss/python/...)
• No model aliases - uses full model identifiers per style guide
• Follows patterns and standards from AGENTS.md
• Accessible structure with clear headings and lists
• Proper use of Mintlify components (Note, Warning, etc.)

Target Audience & Benefits

This documentation helps:

• New users - Quickly understand how to initialize models with clear examples
• Experienced developers - Learn advanced patterns like runtime configuration and multi-model setups
• Multi-provider applications - Build flexible systems that work across providers
• All users - Avoid common mistakes through proactive error explanations

Value provided:

• Reduces support burden by documenting pitfalls upfront
• Improves developer onboarding experience
• Enables confident API usage through design rationale
• Enhances discoverability via navigation and cross-references

[github-actions]

❌ Import check failed

This PR contains imports from langchain_core that should be imported from langchain instead.

Detailed issues

Analyzing diff for import issues...
 Found 1 import issues:

File: src/oss/python/langchain/init-chat-model.mdx
Line: 142
Issue: Import from langchain.tools instead of langchain_core.tools
Current:   from langchain_core.tools import tool
Suggested: from langchain.tools import tool
--------------------------------------------------------------------------------

 Found 1 import issues that need to be fixed.

Why this is a problem

The langchain package re-exports many modules and classes from langchain_core. When possible, imports should use langchain instead of langchain_core for:

• Better user experience (single import source)
• Consistency across documentation
• Reduced cognitive load for users

How to fix

Replace the imports as suggested above. For example:

• ❌ from langchain_core.messages import HumanMessage
• ✅ from langchain.messages import HumanMessage

🤖 Automated check

This check is based on the latest analysis of langchain re-exports from langchain_core.