# CN Model Integration Guide

Help developers write LangChain integration classes for a specified Chinese model (e.g., Qwen, GLM, DeepSeek, Moonshot) using the OpenAI-compatible interface.

> [!CAUTION]
> **Never read, write, or access user configuration files such as `.env`, `.env.local`, `credentials.json`, or any other files that may contain secrets or sensitive information.** API Keys and other credentials must always be filled in by the user themselves — do not peek into or modify these files under any circumstances.

## Step 1: Gather Information

Confirm the following details with the user. If the user does not explicitly provide any of these, use reasonable defaults from the provider's documentation.

<!-- gather
prompt: "Confirm the following details for the model integration:"
fields:
  - name: model_name
    question: "Model name (lowercase, used for directory and class names)"
    example: "qwen"
    required: true
  - name: api_base
    question: "API base URL (OpenAI-compatible endpoint)"
    example: "https://dashscope.aliyuncs.com/compatible-mode/v1"
    required: true
  - name: api_key_env
    question: "API key environment variable name"
    example: "QWEN_API_KEY"
    required: true
fallback: "Use reasonable defaults from the provider's documentation."
-->

1. **Model Name** — lowercase, e.g., `qwen`, `glm`, `deepseek`. Used for directory names, class names, and `_llm_type`.
2. **API Base URL** — the model's OpenAI-compatible endpoint URL.
3. **API Key Environment Variable Name** — e.g., `QWEN_API_KEY`.

Additionally, inspect the project directory structure to determine the Python package manager (`uv.lock` → uv, `poetry.lock` → poetry, `requirements.txt` → pip, etc.).

## Step 2: Create Directory and Files

1. Create a top-level directory `<models_dir>/`.
2. Create a model subdirectory `<models_dir>/<model_name>/` with `model_name` in lowercase.
3. Keep the top-level `<models_dir>/__init__.py` empty.

```
<models_dir>/
├── __init__.py                   # empty
├── <model_name>/
│   ├── __init__.py
│   └── chat_model.py
└── ...
```

## Step 3: Check if DeepSeek

**If the model is DeepSeek**, install `langchain-deepseek` and use `ChatDeepSeek` directly. Skip all subsequent steps.

**If the model is another provider**, continue with the steps below.

## Step 4: Copy the Template

1. Check whether `langchain-openai` is installed; install it if not.
2. Copy the template from [../../template/chat_model.py](../../template/chat_model.py) into the target subdirectory.
3. Create `__init__.py`: `from .chat_model import <CHAT_CLASS_NAME>`

## Step 5: Replace Placeholders

Use grep to list all placeholders, then replace each one with the actual value:

| Placeholder | Description | Example (Qwen) |
|-------------|-------------|----------------|
| `ChatModel` | Class name | `ChatQwen` |
| `PROVIDER_API_KEY` | API Key env var name | `QWEN_API_KEY` |
| `PROVIDER_API_BASE` | API Base env var name | `QWEN_API_BASE` |
| `PROVIDER_API_BASE_URL` | Default API URL | `https://dashscope.aliyuncs.com/compatible-mode/v1` |
| `chat-provider` | Model identifier for `_llm_type` | `chat-qwen` |
| `provider-name` | Value for `response_metadata["model_provider"]` | `dashscope` |
| `Provider` | Provider display name for error messages | `Qwen` |

Each placeholder is a standalone, complete token — simply do a global find-and-replace. Apply replacements in both `chat_model.py` and `__init__.py`.

## Step 6: Configure Model Profile (Optional)

Use `langchain-model-profiles` to download profile information for the model provider. `<provider_name>` is the provider name; try a few likely candidates.

1. Check whether `langchain-model-profiles` is installed; install it if not.
2. Run the download command:

```bash
langchain-profiles refresh --provider <provider_name> --data-dir ./<models_dir>/<model_name>/data
```

On success, a `data/_profiles.py` file is generated under the model directory, which is used by `_get_default_model_profile` in the template. If you cannot find the corresponding provider after several attempts, skip this step.

## Step 7: Write Integration Tests

After the model class is complete, you must write integration tests. See the detailed guide at [integration-tests.md](integration-tests.md).

> [!IMPORTANT]
> **Before running integration tests, you must remind the user to edit the `.env` file themselves and fill in the required API Key and other environment variables.**
>
> When running tests, you will likely encounter common setup issues (package not importable, async test mode, etc.). Refer to the "Common Issues" section at the end of [integration-tests.md](integration-tests.md) for fixes.