Skip to content

armgit / laya

Public Imported from GitHub
0

Non-autoregressive System 1 decision engine. Typed choice, score and yes/no decisions over any text in a single forward pass, in 100+ languages, with a router that picks the right checkpoint per request.

feat(ts): port per-language temperature overrides (lang_temperatures) + Router lang forwarding

Aashish271ecb56d6aa
diff --git a/laya-ts/README.md b/laya-ts/README.md
index 4b124855..46261c74 100644
--- a/laya-ts/README.md
+++ b/laya-ts/README.md
@@ -78,6 +78,29 @@ const out = await predictShortlist(agent, state, questions, embedFn, 20);
// embedFnFromAgent(agent) mean-pools the loaded encoder; a dedicated bi-encoder usually shortlists better.
```
+## Per-language calibration (`lang_temperatures`)
+
+Port of the Python `Agent(lang_temperatures=...)` knob. A language override replaces the
+checkpoint's temperature for matching requests — keys normalise to the base subtag
+(`de-AT` → `de`), an omitted `temperature` inherits the base one, and
+`temperature_by_options` works per option-count bucket as usual:
+
+```ts
+const agent = await Agent.load("convaiinnovations/laya", {
+ lang_temperatures: {
+ de: { temperature: [1.2, 1.2, 1.2] }, // fitted on German evals
+ ja: { temperature_by_options: { "choice:11+": 1.4 } }, // buckets only, base temperature kept
+ },
+});
+await agent.systemOne(state, questions, { lang: "de" }); // uses the German temperature
+await router.predict(state, questions); // Router forwards the detected language
+```
+
+`Router.predict` forwards an explicit `lang` verbatim and otherwise the detected language
+(never `"en"` — matching Python, where detection only names non-English languages), so an
+override applies exactly to the requests it was fitted on.
+
+
## Example (repo root)
```bash
diff --git a/laya-ts/src/agent.ts b/laya-ts/src/agent.ts
index 294b7ad7..8c7f0901 100644
--- a/laya-ts/src/agent.ts
+++ b/laya-ts/src/agent.ts
@@ -90,14 +90,31 @@ export interface AgentOptions {
head_max_len?: number;
temperature?: unknown;
temperature_by_options?: Record<string, unknown>;
+ /**
+ * Per-language temperature overrides, keyed by language code; keys are normalised to
+ * their base subtag (`de-AT` -> `de`), matching Python `Agent(lang_temperatures=...)`.
+ * Each entry may carry a `temperature` list of 3 floats (default: the base raw
+ * temperature) and/or a `temperature_by_options` map (default: none). A matching
+ * override replaces the scale wholesale — see the note at the decode site.
+ */
+ lang_temperatures?: Record<
+ string,
+ { temperature?: unknown; temperature_by_options?: Record<string, unknown> } | null
+ >;
hooks?: HookArg;
onPredictStart?: PredictHook;
onPredictEnd?: PredictHook;
hooksRaise?: boolean;
}
-/** Per-call hook options shared by Agent.systemOne/predict and Router.predict. */
+/** Per-call options shared by Agent.systemOne/predict and Router.predict. */
export interface PredictOptions {
+ /**
+ * Language of the request (e.g. "de"); when the Agent has a matching
+ * `lang_temperatures` override it selects that language's temperature, exactly like
+ * Python `system_one(..., lang=...)`. Routing alone never sets this.
+ */
+ lang?: string | null;
hooks?: HookArg;
onPredictStart?: PredictHook;
onPredictEnd?: PredictHook;
@@ -238,6 +255,10 @@ export class Agent extends HookRegistry {
temperatureByOptionsRaw: Record<string, unknown>;
temperature: number[];
temperatureByOptions: Record<string, number>;
+ langTemperatures: Record<
+ string,
+ { temperature: number[]; temperatureByOptions: Record<string, number> }
+ >;
constructor(opts: AgentOptions) {
super();
@@ -282,6 +303,25 @@ export class Agent extends HookRegistry {
`using ${rejected.join(", ")}. Treat confidence from the affected entries as uncalibrated.`,
);
}
+ // Mirrors Agent.__init__ (agent.py): keys normalise to the base subtag, an omitted
+ // temperature defaults to the base raw temperature, and every value is clamped.
+ this.langTemperatures = {};
+ for (const [l, lc] of Object.entries(opts.lang_temperatures ?? {})) {
+ const normL = l.split("-")[0].toLowerCase();
+ const tRaw = lc?.temperature ?? rawList;
+ if (!Array.isArray(tRaw) || tRaw.length !== 3) {
+ throw new Error(
+ `Language override ${JSON.stringify(l)} temperature must be a list of 3 floats`,
+ );
+ }
+ const tboRaw = (lc?.temperature_by_options ?? {}) as Record<string, unknown>;
+ this.langTemperatures[normL] = {
+ temperature: [0, 1, 2].map((i) => clampTemperature(tRaw[i])),
+ temperatureByOptions: Object.fromEntries(
+ Object.entries(tboRaw).map(([k, v]) => [k, clampTemperature(v)]),
+ ),
+ };
+ }
}
/**
@@ -317,7 +357,13 @@ export class Agent extends HookRegistry {
if (ctx.results === null) {
const out: SystemOneResult[] = [];
for (const st of ctx.states) {
- out.push(await this._systemOneCore(st, ctx.questions as Record<string, QuestionDef>));
+ out.push(
+ await this._systemOneCore(
+ st,
+ ctx.questions as Record<string, QuestionDef>,
+ opts.lang ?? null,
+ ),
+ );
}
ctx.results = out as unknown as Record<string, unknown>[];
ctx.model ??= out[0]?.model ?? null;
@@ -346,6 +392,7 @@ export class Agent extends HookRegistry {
private async _systemOneCore(
state: unknown,
questions: Record<string, QuestionDef>,
+ lang: string | null = null,
): Promise<SystemOneResult> {
const ids = Object.keys(questions ?? {});
if (ids.length === 0) {
@@ -393,7 +440,13 @@ export class Agent extends HookRegistry {
const k = items[r].markers.length;
const qt = QTYPES[q.t];
const bucket = tempBucket(qt, k);
- const scale = this.temperatureByOptions[bucket] ?? this.temperature[qt] ?? 1.0;
+ // Python parity (_decode_answers): a matching lang override replaces the scale
+ // wholesale — its own temperature_by_options first, then its 3-slot temperature —
+ // so an override without buckets intentionally ignores the base per-bucket entries.
+ const langCfg = lang ? this.langTemperatures[lang.split("-")[0].toLowerCase()] : undefined;
+ const scale = langCfg
+ ? (langCfg.temperatureByOptions[bucket] ?? langCfg.temperature[qt] ?? 1.0)
+ : (this.temperatureByOptions[bucket] ?? this.temperature[qt] ?? 1.0);
const z = (logits[r] as number[]).slice(0, k).map((v) => v / scale);
const p = softmax(z);
const actRow = (act[r] as number[]) ?? [1, 0];
@@ -449,6 +502,8 @@ export class Agent extends HookRegistry {
localDir?: string;
token?: string | null;
numThreads?: number;
+ /** Per-language temperature overrides; see AgentOptions.lang_temperatures. */
+ lang_temperatures?: AgentOptions["lang_temperatures"];
},
): Promise<Agent> {
const sub = opts?.subfolder ?? null;
@@ -492,6 +547,6 @@ export class Agent extends HookRegistry {
`Incompatible model: tokenizer.json is missing or invalid in ${JSON.stringify(dir)}: ${String(error)}`,
);
}
- return new Agent({ provider, tok, cfg });
+ return new Agent({ provider, tok, cfg, lang_temperatures: opts?.lang_temperatures });
}
}
diff --git a/laya-ts/src/router.ts b/laya-ts/src/router.ts
index b98941ba..58dd276c 100644
--- a/laya-ts/src/router.ts
+++ b/laya-ts/src/router.ts
@@ -439,7 +439,11 @@ export class Router extends HookRegistry {
// Per-call hooks apply to the whole call, including onRoute inside route().
const decision = this.route(state, questions, opts);
const agent = (await this.load(decision.model)) as {
- systemOne(s: unknown, q: Record<string, QuestionDef>): Promise<SystemOneResult>;
+ systemOne(
+ s: unknown,
+ q: Record<string, QuestionDef>,
+ opts?: { lang?: string | null },
+ ): Promise<SystemOneResult>;
};
const ctx = new PredictContext({
states: [state],
@@ -452,9 +456,18 @@ export class Router extends HookRegistry {
try {
dispatch(active, "onPredictStart", ctx, { raiseErrors });
if (ctx.results === null) {
+ // Python parity (router.py predict): the request's language also shapes the answer
+ // distribution through the agent's lang_temperatures. An explicit lang wins;
+ // otherwise forward the language the router detected for the routing decision.
+ // TS analyse() names English "en" where Python's analyse returns None (it only
+ // ever names non-English), so a detected "en" forwards as null — in Python only an
+ // explicit lang="en" can select an "en" override.
+ const detected = decision.detection?.language;
+ const effectiveLang = opts.lang ?? (detected && detected !== "en" ? detected : null);
const result = (await agent.systemOne(
ctx.states[0],
ctx.questions as Record<string, QuestionDef>,
+ { lang: effectiveLang },
)) as RoutedResult;
result["routing"] = { ...decision };
ctx.results = [result as unknown as Record<string, unknown>];
diff --git a/laya-ts/tests/lang-temperature.test.ts b/laya-ts/tests/lang-temperature.test.ts
new file mode 100644
index 00000000..a8603199
--- /dev/null
+++ b/laya-ts/tests/lang-temperature.test.ts
@@ -0,0 +1,136 @@
+import { describe, expect, it } from "vitest";
+import { Agent } from "../src/agent.js";
+import { Router } from "../src/router.js";
+
+// Same fixed logit row as agent.test.ts: softmax([2, 0]) at temperature 1 is
+// [0.8808, 0.1192]; at 2 -> [0.7311, 0.2689]; at 5 -> [0.5987, 0.4013].
+const fakeProvider = () => ({
+ async runEncoder(_b: any) { return { lastHidden: [[1, 0], [0, 1]] }; },
+ async runHead(_h: any) { return { logits: [[2, 0]], act: [[3, 0]] }; },
+});
+
+const CHOICE = { d: { type: "choice", instructions: "q?", criteria: { x: "yes", y: "no" } } } as any;
+const NOUL = { d: { type: "noul", instructions: "q?" } } as any;
+
+describe("lang_temperatures", () => {
+ it("applies the matching language override, normalising both sides to the base subtag", async () => {
+ const a = new Agent({
+ provider: fakeProvider(),
+ lang_temperatures: { "de-AT": { temperature: [2, 2, 2] } },
+ } as any);
+ expect(Object.keys(a.langTemperatures)).toEqual(["de"]);
+ const r: any = await a.systemOne("hi", CHOICE, { lang: "de" });
+ expect(r.answers.d.probabilities.x).toBeCloseTo(0.7311, 4);
+ const regional: any = await a.systemOne("hi", CHOICE, { lang: "de-CH" });
+ expect(regional.answers.d.probabilities.x).toBeCloseTo(0.7311, 4);
+ });
+
+ it("no lang or an unknown lang keeps the base temperature", async () => {
+ const a = new Agent({
+ provider: fakeProvider(),
+ lang_temperatures: { de: { temperature: [2, 2, 2] } },
+ } as any);
+ const plain: any = await a.systemOne("hi", CHOICE);
+ expect(plain.answers.d.probabilities.x).toBeCloseTo(0.8808, 4);
+ const other: any = await a.systemOne("hi", CHOICE, { lang: "fr" });
+ expect(other.answers.d.probabilities.x).toBeCloseTo(0.8808, 4);
+ });
+
+ it("an override without buckets ignores the base per-bucket overrides", async () => {
+ // Python parity: a matching lang override replaces the scale wholesale, so the base
+ // temperature_by_options entry must NOT leak into the overridden language.
+ const a = new Agent({
+ provider: fakeProvider(),
+ temperature_by_options: { "choice:2": 2.0 },
+ lang_temperatures: { de: { temperature: [1, 1, 1] } },
+ } as any);
+ const base: any = await a.systemOne("hi", CHOICE);
+ expect(base.answers.d.probabilities.x).toBeCloseTo(0.7311, 4);
+ const german: any = await a.systemOne("hi", CHOICE, { lang: "de" });
+ expect(german.answers.d.probabilities.x).toBeCloseTo(0.8808, 4);
+ });
+
+ it("an override with only buckets inherits the base raw temperature per type", async () => {
+ const a = new Agent({
+ provider: fakeProvider(),
+ lang_temperatures: { de: { temperature_by_options: { "choice:2": 2.0 } } },
+ } as any);
+ const choice: any = await a.systemOne("hi", CHOICE, { lang: "de" });
+ expect(choice.answers.d.probabilities.x).toBeCloseTo(0.7311, 4);
+ // noul has no bucket override -> the inherited base temperature (1.0) applies.
+ const noul: any = await a.systemOne("hi", NOUL, { lang: "de" });
+ expect(noul.answers.d.noul).toBeCloseTo(0.1192, 4);
+ });
+
+ it("clamps override values like the base temperature", async () => {
+ const a = new Agent({
+ provider: fakeProvider(),
+ lang_temperatures: { de: { temperature: [100, 0, 1] } },
+ } as any);
+ expect(a.langTemperatures.de.temperature).toEqual([5, 0.5, 1]);
+ const r: any = await a.systemOne("hi", CHOICE, { lang: "de" });
+ expect(r.answers.d.probabilities.x).toBeCloseTo(0.5987, 4);
+ });
+
+ it("rejects an override temperature that is not a list of 3 floats", () => {
+ expect(
+ () => new Agent({ provider: fakeProvider(), lang_temperatures: { de: { temperature: [1, 1] } } } as any),
+ ).toThrow('Language override "de" temperature must be a list of 3 floats');
+ expect(
+ () => new Agent({ provider: fakeProvider(), lang_temperatures: { de: { temperature: 2 } } } as any),
+ ).toThrow('Language override "de" temperature must be a list of 3 floats');
+ });
+
+ it("a null entry is an empty override (base raw temperature, no buckets)", async () => {
+ const a = new Agent({
+ provider: fakeProvider(),
+ temperature_by_options: { "choice:2": 2.0 },
+ lang_temperatures: { de: null },
+ } as any);
+ const r: any = await a.systemOne("hi", CHOICE, { lang: "de" });
+ expect(r.answers.d.probabilities.x).toBeCloseTo(0.8808, 4);
+ });
+});
+
+describe("Router.predict lang forwarding", () => {
+ const questions = { q: { type: "noul", instructions: "?" } } as any;
+
+ function routerRecording(seen: any[]) {
+ const stub = {
+ async systemOne(_s: any, _q: any, opts?: any) {
+ seen.push(opts);
+ return { model: "m", answers: {}, usage: { input_tokens: 0, output_tokens: 0 } };
+ },
+ };
+ return new Router({ loader: () => stub } as any);
+ }
+
+ it("forwards an explicit lang, winning over detection", async () => {
+ const seen: any[] = [];
+ const r = routerRecording(seen);
+ // This romanized Bangla text detects as "bn"; the explicit lang must win.
+ await r.predict("ami ekta ticket khulsi, kalke theke payment hocche na", questions, { lang: "de" });
+ expect(seen).toEqual([{ lang: "de" }]);
+ });
+
+ it("forwards the detected language when no explicit lang is given", async () => {
+ const seen: any[] = [];
+ const r = routerRecording(seen);
+ await r.predict("ami ekta ticket khulsi, kalke theke payment hocche na", questions);
+ expect(seen).toEqual([{ lang: "bn" }]);
+ });
+
+ it("forwards null when nothing non-English was detected", async () => {
+ const seen: any[] = [];
+ const r = routerRecording(seen);
+ await r.predict("please refund my ticket", questions);
+ expect(seen).toEqual([{ lang: null }]);
+ });
+
+ it("an explicit lang is forwarded verbatim, even \"en\"", async () => {
+ const seen: any[] = [];
+ const r = routerRecording(seen);
+ await r.predict("please refund my ticket", questions, { lang: "en" });
+ expect(seen).toEqual([{ lang: "en" }]);
+ });
+});