Repository navigation
docs(http-api): report every key a decision response actually carries - #816
Merged
NandhaKishorM merged 2 commits intoOct 1, 2026
Merged
Conversation
The Response section showed a usage block of two keys while both agents build six always-present ones plus a conditional `options`, named three of the five routing keys, listed four of the eight fields `laya.lang.analyse()` returns, and described `lang_guess` as routing evidence when it is a request control that leaves no key of its own. The sample itself predated NandhaKishorM#174's truncation report, so the one thing a caller cannot see anywhere else in the payload -- that its state was cut before the model read it -- was invisible here too. Replace the sample with an answer this server really gave (the request the page prints, cached `english` checkpoint, CPU) and add the two field tables.
…uild Every key list is read out of the source rather than transcribed: the result and `usage` literals of both agents' batch inference, the keywords every `RouteDecision(...)` in `_route` is built with, and `analyse()` at runtime over four states to show its key set does not move with the script. Held to the page in both directions, as the request-body and `/health` gates above already do, so a key added to a response and a key dropped from the docs both fail here. The sample is also checked against itself -- the flag is the worst-case drop being non-zero, `output_tokens` is 0 -- because the page now presents it as one real answer rather than as illustration.
Owner
|
Merged for 0.3.24. Reading every key list out of the source rather than typing it into the test is the right shape, and it is the same approach as the The Verified on the integrated branch: Thank you. |
This was referenced Oct 1, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
docs/http-api.md's### Responsesection described a smaller payload than the server sends, andnamed one key no code path has ever set. This corrects the page and adds a gate that reads every key
list out of the source, so the page and both agents have to keep describing the same response.
Two files:
docs/http-api.md(the sample, two new field tables, and the prose around them) andtests/test_serve.py(one new test, plus the three helpers it reads the code with).Why
What the page said, against what the code does, measured on
4185647with the cachedenglishcheckpoint on CPU:
The truncation report is the part that matters.
state_tokens,state_tokens_dropped,truncatedand
truncated_questionsare the only place a caller can learn that its state was cut before themodel read it -- the budget that decides that moves with
max_len,head_max_lenand everyquestion's own option prompt (#174), so nothing in the request tells it.
optionsis the same storyone level down: when the head budget leaves the options without a token span each, the answer has a
ceiling the caller cannot otherwise see. A page that documents two of those keys leaves a caller
sizing states by character count with no hint that the four others exist.
lang_guesswas worse than an omission -- the page listed it as evidence carried insiderouting,so code written against the page would find
routing.get("lang_guess")isNoneon every response.What a hint actually does is named in
reason, and it is a request control.And the sample could not be reproduced: it printed
"input_tokens": 74for the request the pageitself shows, while that request on this commit gives
83withstate_tokens: 12. It is now ananswer this server really gave (the printed request, cached
english, CPU), which is also what letsthe gate check the sample against itself -- the flag is the worst-case drop being non-zero,
output_tokensis0.How it was verified
Nothing is transcribed.
_decision_response_site()parses the two agents and returns the resultdict's keys, the keys its
usageliteral always carries, the keys it adds conditionally, and themodelconstant it stamps;_route_decision_keys()collects the keywords of everyRouteDecision(...)inlaya/router.py;analyse()is called over four states (English, German,Japanese, empty) to show its key set does not move with the script -- which is what licenses one
table row to describe it. Each set is then held to the page in both directions, the way the
request-body and
/healthgates above already do, so a key added to a response and a key droppedfrom the docs both fail here. The two agents are also held to each other, because the page describes
one payload for both.
python -m pytest tests/test_serve.py -q-> 185 passed (184 before this PR + the new one)python tests/test_doc_tables.py-> 114 passed, 0 failed;python tests/test_env_docs.py-> 27passed, 0 failed (both parse docs pages, and both had to keep passing)
ruff check laya/ --select=E9,F63,F7,F82,F401,F811 --line-length=120clean,compileallcleanRouter.predict(state, questions)before writing it, andevery number in it checked field by field against that run
Fourteen mutation arms, each reverting after itself; the gate was green only with nothing changed:
mainstate_tokens"agent.pystops buildingstate_tokensusage = {...}literal with astate_tokenskey"onnx_agent.pyadds a key torch does not sendoptionsrowworkflow_routestarts reportinglang_guessdetectionrow stops namingdiacritic_ratedetectionfieldanalyse()makesmixed_segmentconditionaltruncatedwith nothing droppedworkflowstate_tokensOne thing this deliberately does not touch:
README.mdsays Laya's payload is"schema-identical" to hosted Jev's and names a two-key usage block. The key set is wrong there the
same way, but the sentence is a parity claim about Jev's schema, which nothing in this repo can
check, so it is left for someone who can.
Related work: #814 edits the same page -- its
400row and the "Not (yet) here" section, severalhundred lines below this change -- so the two will not conflict, but whichever lands second should
rebase. #716 and #667 touch
tests/test_serve.pyat other locations, and nothing open changes whatthe response carries. No open issue proposes this; #390 tracks the docs site's structure, not field
lists.
Checklist
mainFixes # (no open issue for this: the response field lists are only on
docs/http-api.md, and noissue proposes holding them to the code)