Skip to content

feat(ts): report the options a head budget collapsed, as laya.common does - #817

Merged
NandhaKishorM merged 3 commits into
NandhaKishorM:mainfrom
aashish254:feat-ts-option-collapse
Oct 1, 2026
Merged

NandhaKishorM merged 3 commits into
NandhaKishorM:mainfrom
aashish254:feat-ts-option-collapse

Conversation

@aashish254

Copy link
Copy Markdown
Contributor

What

laya-ts now reports the options its head budget collapsed, the way laya/common.py does.

  • laya-ts/src/common.ts: an OptionStats type (total, distinct, tokens_per_option), carried on
    QuestionPrefix.optionStats and SequenceStats.options, plus an exported collapsedOptions()
    that is the port of laya.common.collapsed_options().
  • laya-ts/src/agent.ts: SystemUsage gains options?, and _systemOneMany publishes it only when
    some question actually lost a span.
  • laya-ts/src/index.ts: exports the function and the type.
  • laya-ts/tests/option-collapse.test.ts: 12 new tests; laya-ts/README.md: the budget section.

Why

build_sequence caps every option at 48 tokens and re-caps all of them to
max(4, (head_max_len - 16) // n) once they overflow the head (#538). Two options that share a
prefix can come out of that cut as the same token span, and the marker count still equals the
option count, so nothing complains -- the question is answered from a head that can no longer name
those options apart. Core measures it and publishes it as usage["options"], so a caller can see
"58 labels, 42 spans". The TS port applies the identical caps -- same 48-token ceiling, same
re-cap formula -- but keeps no count of what they cost, so the same request over laya-ts returns
an answer whose confidence silently has a ceiling nothing in the response mentions.

Every expected number in the new test is what laya/common.py returns for the same character-level
stub tokenizer, so a divergence here is a port bug rather than a style choice. Reproduced on this
tree:

case (max_len/head_max_len) Python build_sequence(..., return_stats=True) laya-ts after this PR
4 shared-prefix labels, 512/256 {options: 4, options_distinct: 4, tokens_per_option: None}, 186 tokens {total: 4, distinct: 4, tokens_per_option: null}, 186 ids
same labels, 128/24 {4, 1, 4}, 4 markers, 35 tokens {total: 4, distinct: 1, tokens_per_option: 4}, 4 markers, 35 ids
4 unrelated labels, 128/24 {4, 4, 4} {total: 4, distinct: 4, tokens_per_option: 4}
40 labels, 40/400 {40, 4, 9}, 2 markers in the sequence {total: 40, distinct: 4, tokens_per_option: 9}, markers.length === 2

The last row is the reason total counts the question's options rather than the markers: a report
counted from the markers would say "2 of 2" about a question with 40 of them. Before this change
usage had six keys and none of them was this fact; a 40-label question at a 24-token head
reported nothing.

Two facts stay separate, and the new tests hold them apart: a truncated state
(state_tokens_dropped) and a collapsed head (options) are different losses, so the
{max_len: 128, head_max_len: 24} arm asserts truncated: true and
options: {intent: {total: 4, distinct: 1, tokens_per_option: 4}} together, while the roomy arm
asserts options is absent and the key set is exactly the six it was before.

How it was verified

cd laya-ts
npx tsc -p tsconfig.json --noEmit          # exit 0
npm test -- --run                          # Test Files 33 passed (33) / Tests 592 passed (592)
npm run test:package                       # pass 1, fail 0
python tests/test_option_collapse.py       # 23 passed, 0 failed   (the oracle this ports)
ruff check laya/ --select=E9,F63,F7,F82,F401,F811 --line-length=120   # All checks passed!
python -m compileall -q laya/ tests/       # clean

No Python file changed; the last three are the repo gates and are run anyway. Then the new gate
was mutation-checked -- nine faithful edits to the shipped code, each expected to turn it red
(python -B /tmp/mut/run.py, restoring every file with git checkout -- between arms; each
result is vitest's own line):

arm verdict vitest
control: nothing changed green 12 passed (12)
distinct always equals the option count red 5 failed | 7 passed
total counted from the markers that reached the sequence red 1 failed | 11 passed
the cap applied is never reported (tokens_per_option) red 6 failed | 6 passed
the agent never publishes it red 2 failed | 10 passed
the agent publishes it on every request red 1 failed | 11 passed
the filter keeps the questions that did NOT collapse red 6 failed | 6 passed
the filter reports every question, collapsed or not red 4 failed | 8 passed
the stats never reach SequenceStats red 9 failed | 3 passed

survived: none. For the record: the second arm's first version (total: markers.length inside
buildQuestionPrefixUncached) survived green, and it was an equivalent mutant rather than a hole
in the gate -- pre-clamp markers.length === opts.length there -- so it was replaced by the
post-clamp edit shown above, which the gate does catch.

Checklist

  • Focused on one change (split unrelated work into another PR)
  • Rebased on the latest main
  • Tests pass locally
  • Docs or examples updated when the public API changed

Fixes # -- no open issue claims this, and no open PR touches laya-ts/src/common.ts;
tests/test_option_collapse.py is the behavior this ports, so this is the TS half of #538's
report. Related: #816 (merged as 350df4b) documents usage.options on the Python side and in
docs/http-api.md; this makes laya-ts actually fill that field, and the wording of both is the
same three keys.

…does

`buildQuestionPrefix` applied Python's option caps exactly -- 48 tokens each, then
`max(4, (headMaxLen - 16) // n)` for all of them once they overflow the head -- and kept no
count of what the cut cost. Two options sharing a prefix therefore collapse into one token
span silently: the marker count still equals the option count, the guard in `_encodeItems`
passes, and the question answers normally while no longer able to name those options apart.
Python reports it as `usage["options"]` since NandhaKishorM#538; the SDK had the truncation half of the
same budget story and not this half.

`build_head`'s stats are mirrored whole (`total`, `distinct`, `tokens_per_option`), counted on
the capped option ids before assembly so the last option cannot look distinguishable by running
into the state, and filtered by a `collapsedOptions` that matches `laya.common.collapsed_options`
including its `total`-is-the-question's rule. The agent adds the key only when something
collapsed, so the 512-token request that loses nothing still reports nothing.
No weights and no network: the same character-level stub tokenizer the Python gate uses, so the
expected numbers are Python's rather than assertions written to match this implementation. On
`d8a2e59` the two agree token for token -- 186 tokens and four spans for the roomy head, 35 and
one span at head_max_len 24, and 40 options behind 2 surviving markers at max_len 40 -- which is
also the first time this path has been held to the Python side end to end. The Agent arms run a
real Agent over a fake provider, so what is checked is the published `usage` block rather than
the stats object, including its absence when nothing collapsed.
@NandhaKishorM
NandhaKishorM merged commit e5e2883 into NandhaKishorM:main Oct 1, 2026
23 checks passed
@NandhaKishorM

Copy link
Copy Markdown
Owner

Merged for 0.3.24.

I checked the port against the original rather than reading the description, and it is faithful. laya.common.collapsed_options gates on options_distinct < options and reports total, distinct, tokens_per_option; collapsedOptions in src/common.ts gates on s.distinct < s.total and reports the same three. Same condition, same fields, same meaning.

The detail worth calling out is that total is the number of options the question defines, not the number of markers that reached the sequence. That is the distinction the Python docstring exists to protect, because a count taken from the markers would report "43/58" about a request where 28 options never entered the input at all, and the whole point of the field is to tell someone their budget is too small. You carried that across, including publishing options only when a question actually lost a span, so an unaffected call's usage shape is unchanged.

Verified on the merged tree: npm run build clean under tsc 7.0.2, 597 tests passing (up from 585, so your 12 are all running), the packed end-to-end test passing, and the full Python lane green with zero decision flips against 0.3.23.

Note that laya-ts moved under you in the same pass: #631 and #633 took vitest to 5.x and TypeScript to 7.x, and tsconfig.json now declares types: ["node"]. Your branch merged cleanly over all of it.

Thank you.

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