From ffe4def5e4d5faf565e75677151fd22ae8ed0f02 Mon Sep 17 00:00:00 2001 From: Mason Daugherty Date: Wed, 8 Apr 2026 21:50:54 -0400 Subject: [PATCH] docs(infra): add model reference freshness guidelines (#36626) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a "Model references in docs and examples" subsection to `AGENTS.md` and `CLAUDE.md` under Documentation standards. Codifies that docstrings and examples should use current GA model names, not stale ones — and explicitly draws the line between updating illustrative references (encouraged) and changing shipped code defaults (breaking change, separate process). --- AGENTS.md | 10 ++++++++++ CLAUDE.md | 10 ++++++++++ 2 files changed, 20 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index cf32ad99a3e..19eca04e1eb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -194,6 +194,16 @@ def send_email(to: str, msg: str, *, priority: str = "normal") -> bool: - Ensure American English spelling (e.g., "behavior", not "behaviour") - Do NOT use Sphinx-style double backtick formatting (` ``code`` `). Use single backticks (`` `code` ``) for inline code references in docstrings and comments. +#### Model references in docs and examples + +Always use the latest generally available (GA) models when referencing LLMs in docstrings and illustrative code snippets. Avoid preview or beta identifiers unless the model has no GA equivalent. Outdated model names signal stale code and confuse users. + +Before writing or updating model references, verify current model IDs against the provider's official docs. Do not rely on memorized or cached model names — they go stale quickly. + +Changing **shipped default parameter values** in code (e.g., a `model=` kwarg default in a class constructor) may constitute a breaking change — see "Maintain stable public interfaces" above. This guidance applies to documentation and examples, not code defaults. + +For model *profile data* (capability flags, context windows), use the `langchain-profiles` CLI described below. + ## Model profiles Model profiles are generated using the `langchain-profiles` CLI in `libs/model-profiles`. The `--data-dir` must point to the directory containing `profile_augmentations.toml`, not the top-level package directory. diff --git a/CLAUDE.md b/CLAUDE.md index cf32ad99a3e..19eca04e1eb 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -194,6 +194,16 @@ def send_email(to: str, msg: str, *, priority: str = "normal") -> bool: - Ensure American English spelling (e.g., "behavior", not "behaviour") - Do NOT use Sphinx-style double backtick formatting (` ``code`` `). Use single backticks (`` `code` ``) for inline code references in docstrings and comments. +#### Model references in docs and examples + +Always use the latest generally available (GA) models when referencing LLMs in docstrings and illustrative code snippets. Avoid preview or beta identifiers unless the model has no GA equivalent. Outdated model names signal stale code and confuse users. + +Before writing or updating model references, verify current model IDs against the provider's official docs. Do not rely on memorized or cached model names — they go stale quickly. + +Changing **shipped default parameter values** in code (e.g., a `model=` kwarg default in a class constructor) may constitute a breaking change — see "Maintain stable public interfaces" above. This guidance applies to documentation and examples, not code defaults. + +For model *profile data* (capability flags, context windows), use the `langchain-profiles` CLI described below. + ## Model profiles Model profiles are generated using the `langchain-profiles` CLI in `libs/model-profiles`. The `--data-dir` must point to the directory containing `profile_augmentations.toml`, not the top-level package directory.