Skip to content

feat(go): port the routing half of laya.router (Route, RouteBatch) - #1310

Merged
NandhaKishorM merged 4 commits into
NandhaKishorM:mainfrom
keemsisi:feat/go-router-routing
Oct 23, 2026
Merged

NandhaKishorM merged 4 commits into
NandhaKishorM:mainfrom
keemsisi:feat/go-router-routing

Conversation

@keemsisi

Copy link
Copy Markdown
Contributor

What and why

Part What
router New with WithDefault, WithAutoTaskDetection, WithStandaloneRepos, WithLangGuess, WithSource, WithSourceIn. Route and RouteBatch return a Decision (model, repo, reason, detection, workflow) and load nothing. Per-call ForModel, ForTask, ForLang, ForLangGuess. Also NormaliseName, CanonicalName, ResolveModelSpec, EnglishFromCode, MatchTypedDecisionsWorkflow, QuestionSchema
scripts/gen_go_fixtures.py new router family in go_extra.json, recorded from laya.router.Router. Inputs: the laya-dotnet/tools/routing_cases.py corpus plus seeded fuzz. The dotnet golden JSON is not read
CI floor 1603 -> 3462 (comment and both --min-tests). No --only change: the family lives in go_extra.json, which the existing step regenerates

Names follow Java (Router, normaliseName, matchTypedDecisionsWorkflow) and .NET (Route, RouteBatch) in Go idiom: a closed Checkpoint type, Decision, functional Option (router) and CallOption (per call), and LangHint (concurrent calls possible, so a hint must be goroutine-safe). Precedence is Python's: model, task, workflow (opt-in), lang, call hint, installed hint, detection, default. The default is multilingual.

Later changes: router hooks (on_route), model lifecycle, routed inference, config surface.

Differences from Python

Python Go Why
register, unregister, custom checkpoint names not ported; WithSource repoints a built-in, any other name is an *UnknownModelError the closed set is what Java and .NET ship; defer to the lifecycle change
route(explain=True) not ported lang.Analysis carries no diagnostic
name or code of any type, str(x) string the type system rules the rest out
lang_guess callable returning anything LangHint func(state any) string; "" abstains no None; a non-str return has no Go form
_question_schema(dict) signs the dict as written QuestionSchema signs the validated Questions in canonical wire form never splits what Python groups; merges only question sets that render the same. Over all 1,081 pairs of the 47 recorded definitions: Python-equal implies Go-equal (0 violations), Go-equal implies identical render (0), and the 11 pairs Go groups and Python splits are an explicit list in the test (noul criteria {}/none/blank, labels in another key order). For R4: Go batch grouping yields fewer forward passes than Python with identical prompts
route_batch request dict checks (missing key, wrong type) typed Request; a nil State is refused with laya's text only the nil check survives typing
Router.route hooks none R2
models value ~ expanded as os.path.expanduser (HOME, else the account; ~name) for WithSource; not for WithSourceIn same rule as Python for str and pair

Evidence

Check Result
go_extra.json only the router family differs from upstream/main (the other families are byte-equal; no predict_plan churn)
goldens: 263 names, 279 codes, 50 workflow id sets, 107 signatures, 1,058 routes (937 decided, 117 refused routes, 4 refused routers), 63 batches all equal Python: model, repo, reason text, workflow, detection fields, error text
independent differential fuzz vs Python (random Unicode names and codes, nested states, mixed-language lines, odd models, a callable hint), seeds 7, 11, 12 100,000 cases, 0 mismatches; a 59-code-point cut is caught
lane: race 1.27.1, 1.22.12, committed goldens, private output dir 3462 ran, 0 skipped, 0 failed on each; floor+1 exits 1
gofmt, vet, staticcheck, gen_go_fixtures --check, gen_tables --check, workflow folding, ruff clean

Mutants

Each compiles and fails the named test.

Behavior Mutant Killed by
precedence task before model; workflow after lang; installed hint before call hint TestPrecedence, TestLangHintReceivesState
default multilingual flipped to english or typed-decisions TestDefaultIsMultilingual
reason cut 59, 61 code points; cut by bytes TestMixedSegmentCutsAtCodePoints
percent half up instead of half even TestPercentRoundsHalfToEven
quoting %q instead of repr; unquoted lang TestReasonQuoting
workflow subset match; dropped when auto detection is off TestWorkflowNeedsExactIDs, TestWorkflowReportedWithoutAutoDetection
lang code und not abstaining; .UTF-8 not cut; _ not split; english dropped; blank decides TestEnglishFromCodeGolden, TestRouteGolden
names no alias; lower before strip order TestNamesGolden
task canonical key in the reason; unknown task falls to typed TestTaskSpelling, TestUnknownModelText
batch nil state allowed; last request dropped TestRouteBatchRefusesNilState, TestRouteBatchGolden
signature compact separators TestQuestionSchemaGolden

Equivalent, not killable: dropping the - to _ rewrite for task. NormaliseName already resolves typed-decisions and typed_decisions in any case, so the rewrite only mirrors Python.

Real-weights e2e

Not applicable: routing runs no model.

Scanners and review

Check Result
CodeQL (Go security-extended), Semgrep (golang, security-audit, secrets), govulncheck, staticcheck, actionlint 0 findings; govulncheck: no vulnerabilities
Independent adversarial review 163,000 more differential cases vs Python, 0 mismatches; findings fixed in the last commit

names, language codes, workflow match, question signatures, 1,058 route
decisions (the .NET probe corpus inputs plus seeded fuzz) and 63 route_batch
calls, all run through laya.router.Router.
Route and RouteBatch name a checkpoint and the reason without loading
anything: NormaliseName, EnglishFromCode, MatchTypedDecisionsWorkflow and
QuestionSchema, with laya's reason strings (repr quoting, half-even percent,
code-point cut at 60). Hooks, lifecycle and routed inference are later.
Not ported: custom checkpoints (register), explain=True, non-string names.
Restore upstream's predict_plan values in go_extra.json (only the router
family differs from upstream/main); golden pair check for QuestionSchema
(Python-equal implies Go-equal, Go-equal implies same render, 11 coarser pairs
listed); zzz superset case for the workflow match; LangHint concurrency doc.
@NandhaKishorM
NandhaKishorM merged commit eeec3f6 into NandhaKishorM:main Oct 23, 2026
50 checks passed
NandhaKishorM added a commit that referenced this pull request Oct 23, 2026
Three things my conflict resolution got wrong across #1306, #1307, #1308, #1309,
#1310 and #1311, which all touch go.yml, README.md, gen_go_fixtures.py and
go_extra.json:

1. `shortlist_order_family` lost its `return {"cases": cases}`. The conflict
   boundary fell on that line, so the function built its cases and returned None,
   and go_extra.json carried `"shortlist_order": null`. Found by parsing the
   merged file and checking all 98 top-level names against the PR each came from;
   only this one and `build` failed, and `build` is the validated union of all
   23 keys.

2. go.yml lost four of #1309's parity steps (the samples module's golden check,
   build, test and no-cgo build). #1310 conflicted over the same hunk and my
   resolver kept one side. Restored; the merged file now holds every step name
   from every PR in the series and none that is not in one of them.

3. `build()` had `email_fuzz` ahead of `router`. They are the only two of the
   new families that draw from the shared `rng`, so that order re-drew the
   corpus #1311 recorded `router.signatures` from, and
   `router/golden_test.go` pins how many of those 107 signatures come out
   byte-identical to Python's: 42 instead of 50. Nothing was wrong with that
   constant, or with Go. Putting `router` first gives it the stream #1311
   measured, and `email_fuzz` is the one re-drawn, which it can be: it has no
   such constant, only a 1500-case count, and it still holds 1500.

With that, `gen_go_fixtures.py --check` passes and each PR's own key reproduces
verbatim from this tree: calibration (#1306), shortlist_order (#1307),
email_fold (#1308) and router (#1311). `go build`, `go vet` and `go test` are
green across all 12 packages.

`--min-tests` is left at 3869 as a floor rather than an exact count, because the
figure a full lane reports cannot be measured here: several goldens need ONNX
exports. The comment says so and asks for it to be tightened on the next green
run.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@NandhaKishorM

Copy link
Copy Markdown
Owner

Merged into 0.4.14, with #1306, #1307, #1308, #1309 and #1311.

The routing half is the right place to cut this. Route and RouteBatch need no weights, no ONNX session and no tokenizer, so the port can be held to Python exactly rather than approximately, and the golden corpus does that: every route case in go_extra.json's router key reproduces verbatim from this tree.

names.go keeping the checkpoint name resolution separate from the decision is worth keeping that way. In Python those are also separate, and the repo field being deliberately left out of the golden is the kind of omission that should stay documented where it is.

One thing to know about the merge. This PR's go.yml hunk collided with #1309's four new parity steps and my resolution dropped them; they are restored. Details on #1311, along with a build() ordering problem that made your golden_test.go report 42 signatures instead of 50 until I fixed the order rather than the constant.

--min-tests is now a floor at 3869 rather than an exact count, because the merged total cannot be measured outside CI. #1311 has the full note and the ask.

go build, go vet and go test are green across all 12 packages.

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