Skip to content

docs: correct default-model guidance in deployment surfaces - #1097

Merged
NandhaKishorM merged 5 commits into
NandhaKishorM:mainfrom
Bruce-Yii:docs/laya-default-model-native-history
Oct 11, 2026
Merged

NandhaKishorM merged 5 commits into
NandhaKishorM:mainfrom
Bruce-Yii:docs/laya-default-model-native-history

Conversation

@Bruce-Yii

Copy link
Copy Markdown
Contributor

What

Five documentation surfaces still describe the pre-0.4.0 routing default, when Router fell back to english for text with no language evidence. Since 0.4.0 the fallback is multilingual, and an operator who wants English has to opt in explicitly. This corrects the guidance on the surfaces a deployer actually reads:

  • README.md: the Router(default="english") example introduced LAYA_DEFAULT_MODEL=multilingual as "the same setting", and the server paragraph told a mostly non-English deployment to set english. Both now match the code.
  • compose.http.yaml: the LAYA_DEFAULT_MODEL comment said an empty value keeps english and advised multilingual for mostly-non-English traffic. Empty keeps multilingual; english is the opt-in for mostly-English traffic.
  • nix/laya-serve.nix: the defaultModel option description said null leaves the english default and reversed the override direction.
  • laya/serve.py (_default_model_option docstring): quoted README advice that no longer exists; it now states the Router default and the opt-in.

Text only; no code, API, or behavior change.

Why

laya/router.py Router.__init__ defaults to multilingual since 0.4.0, and tests/test_serve.py (test_default_model_reaches_the_router_the_server_builds) pins router.default == "multilingual". A deployer who follows the stale text gets the opposite checkpoint from the one they asked for, with no error to catch it — for example setting LAYA_DEFAULT_MODEL=english to "restore" a documented default on a mostly-non-English deployment.

How it was verified

python -m pytest tests/test_serve.py::test_default_model_reaches_the_router_the_server_builds -q   # 1 passed
python tests/test_env_docs.py                                                                       # 27 passed, 0 failed
python -m ruff check laya/ --select=E9,F63,F7,F82,F401,F811 --line-length=120                       # All checks passed!
python -m compileall -q laya/                                                                        # exit 0
git diff --check                                                                                     # exit 0
python -m zensical build --strict --clean                                                            # No issues found; exit 0

Windows 11, Python 3.12.9.

Follow-ups

The full serve suite has one pre-existing environment failure (test_accepted_connections_set_tcp_nodelay, an asyncio teardown issue) that also fails on unmodified main; it is unrelated to this documentation change.

The README shows Router(default="english") as the mostly-English override and
then names LAYA_DEFAULT_MODEL=multilingual as "the same setting", which
contradicts the example directly above it. The env-var spelling of
default="english" is LAYA_DEFAULT_MODEL=english; the stock default stays
multilingual, as the rest of the page says.
@NandhaKishorM
NandhaKishorM merged commit a9edfe4 into NandhaKishorM:main Oct 11, 2026
38 of 40 checks passed
@NandhaKishorM

Copy link
Copy Markdown
Owner

Merged in 0.4.3. Nine lines across five files, and the one I care about most is the README sentence that told a mostly non-English deployment to set english. That is advice pointing the wrong way: after 0.4.0 a mostly non-English deployment should set nothing, and english is the opt-in for mostly-English traffic. Someone following it would have undone the change they were reading about.

The compose.http.yaml comment was the same inversion in the file an operator edits rather than reads, and the nix/laya-serve.nix defaultModel description said null leaves the english default, which is what a Nix user sees in the generated option docs.

Verified on the merged tree: all 87 suites pass including tests/test_packaging.py, which reads the nix option prose against the runtime, and the 94-row real-weights decision diff is identical to 68804629.

Two other PRs this release correct the same fact on surfaces you did not touch, so between the three it is now consistent: #1085 for the laya/serve.py env table and docs/http-api.md, with an ast-derived gate so the column cannot drift again, and #1092 for examples/server.py, which was the one surface genuinely behaving differently rather than just describing it wrongly.

Worth knowing why this mattered now: #1058 is an operator reporting a measured accuracy change across the 0.4.0 default move, and the contributor investigating it ended their analysis by pointing at exactly these stale tables.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants