Skip to content

docs(router): add routing guide - #461

Merged
NandhaKishorM merged 1 commit into
NandhaKishorM:mainfrom
Asthenia0412:codex/docs-router-guide
Oct 1, 2026
Merged

NandhaKishorM merged 1 commit into
NandhaKishorM:mainfrom
Asthenia0412:codex/docs-router-guide

Conversation

@Asthenia0412

Copy link
Copy Markdown

What

Add a Router guide covering checkpoint selection, language overrides, custom language hints, explicit typed-decisions routing, inspection without model loading, checkpoint memory, and mixed batches.

Why

Issue #390 calls out a routing guide as one of the next documentation pages. The API reference documents the surface, but the practical choices and their order were spread across the README and docstrings.

How it was verified

  • uvx --from zensical==0.0.64 --with mkdocstrings-python==2.0.9 --with ruff==0.16.8 zensical build --strict --clean — passed with no issues.
  • git diff --check — passed.

Refs #390

@NandhaKishorM

Copy link
Copy Markdown
Owner

Thank you for a clear, accurate routing guide. I checked the precedence order, the examples and the loading and batching sections against router.py, and they hold up. One fix: an unrecognised hint does not abstain. Only None, blank strings and codes that name no language (C, POSIX, C.UTF-8, und, zxx, mul) fall through, while any other value, such as "xx", False or 0, routes to multilingual. Could you correct that paragraph and the 'other recognized language codes' line, and add a row for the page in docs/index.md so the 'Routing is in the README for now' sentence can go?

NandhaKishorM added a commit that referenced this pull request Oct 1, 2026
#461's guide is accurate everywhere I checked it against laya/router.py, with
one exception: it said an unrecognized hint does not force a checkpoint, and it
does. Measured on the merged tree with Router().route("hello there my friend",
lang_guess=...):

  None, '', '   ', 'C', 'POSIX', 'C.UTF-8', 'und', 'zxx', 'mul'  ->  english
  'xx', False, 0, 'de'                                           ->  multilingual

So the abstaining set falls through as the guide describes, but any other value
is read as "not English" and picks multilingual. A reader passing a detector's
garbage code expecting fallthrough would get the wrong checkpoint and the page
told them they would not.

The paragraph now separates the two cases and says to map a detector's unknown
case to None if it matters.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@NandhaKishorM
NandhaKishorM merged commit d9bf96c into NandhaKishorM:main Oct 1, 2026
@NandhaKishorM

Copy link
Copy Markdown
Owner

Merged for 0.3.24, with one paragraph corrected on the way in.

The guide holds up. I re-checked the precedence order, the examples, and the loading and batching sections against laya/router.py on today's main, and they are accurate. Issue #390 asked for exactly this page, and the practical ordering was genuinely only discoverable by reading the README and the docstrings together.

The one fix is the claim I raised in September, which had not been picked up, so I made it rather than hold the page any longer. Measured on the merged tree with Router().route("hello there my friend", lang_guess=...):

None, '', '   ', 'C', 'POSIX', 'C.UTF-8', 'und', 'zxx', 'mul'  ->  english   (falls through)
'xx', False, 0, 'de'                                           ->  multilingual

So the abstaining set behaves as you described, but an unrecognized hint is not an abstention: any other value is read as "not English" and picks multilingual. The page said an unrecognized hint continues to the next rule, which would send a reader passing a detector's garbage code to the wrong checkpoint while believing they were safe. The paragraph now separates the two cases and says to map a detector's unknown case to None if that matters.

One thing you did not need to do and I checked anyway: docs/.nav.yml has a glob: "*" under Guides, so the page appears there without a nav edit. That is by design per the comment at the top of that file.

test_doc_tables and test_env_docs pass. Thank you for a page that was accurate enough that one sentence was the whole review.

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