@gobing-ai/ts-laya-mlx 0.5.21 → 0.5.23

package/README.md

@@ -21,7 +21,7 @@ Part of the `@gobing-ai/ts-libs` monorepo and lockstep-versioned with it.
 > **Notice:** This is the only package in the workspace with specific host architecture constraints.
 
 1. **Platform:** macOS on Apple Silicon (`darwin arm64`). Unsupported platforms fail fast at construction time before any process is spawned.
-2. **Python:** Python 3.10+ carrying the `laya-mlx` runtime (resolvable via `pythonPath`, injected `env.LAYA_PYTHON`, or `python3` on `PATH`).
+2. **Python (core `mlx-python` only):** Python 3.10+ carrying the `laya-mlx` runtime (resolvable via `pythonPath`, injected `env.LAYA_PYTHON`, or `python3` on `PATH`). Core `mlx-native` needs no Python.
 3. **Supported runtime range:** `laya-mlx 0.1.x` (validated against upstream `0.1.0` @ `fc1df62828a3fedf4d8229fdac1cbd85f1cdf337`).
 4. **Install command:**
    ```sh
@@ -32,6 +32,40 @@ Part of the `@gobing-ai/ts-libs` monorepo and lockstep-versioned with it.
 
 ---
 
+## Execution core and model selection
+
+Both cores run Apple MLX on Metal and return identical neutral answers; pick per host.
+
+| Option | Env (injected) | Values | Default |
+| --- | --- | --- | --- |
+| `core` | `LAYA_CORE` | `mlx-python` · `mlx-native` · `auto` | `mlx-python` |
+| `modelPath` | `LAYA_MODEL_PATH` | local checkpoint dir (fine-tuned) — wins over `modelId` | — |
+| `modelId` | `LAYA_MODEL_ID` | Hugging Face repo id | `convaiinnovations/laya-multilingual` |
+
+- **`mlx-python`** — warm `laya-mlx` Python child process over JSON lines. Lowest latency and memory.
+- **`mlx-native`** — in-process [`@johnhenry/laya`](https://github.com/johnhenry/laya-js) via libmlxc FFI;
+  no Python, no child process. Does not support `cacheDir`/`LAYA_CACHE_DIR` (set `HF_HUB_CACHE` for the
+  process instead) or `dtype: 'bfloat16'`; both are rejected as `DecisionConfigError`.
+- **`auto`** — loads the native core on first ask; any native load failure falls back to `mlx-python`.
+
+Measured on an Apple Silicon Mac (official checkpoint, f16, 3-question batch, 20 warm asks):
+
+| Core | Cold (load + first ask) | Warm p50 | Resident memory |
+| --- | --- | --- | --- |
+| `mlx-python` | ~0.8–1.0 s | ~10 ms | ~1.15 GB (78 MB host + ~1.07 GB worker) |
+| `mlx-native` | ~0.8–1.0 s | ~22 ms | ~1.78 GB (all in host process) |
+
+```ts
+createLayaDriver({ core: 'mlx-native', modelPath: '/models/laya-ft-kk' });
+```
+
+The returned driver implements `dispose()`, which closes the client it was built with — the
+`mlx-python` worker is held warm for the client's lifetime, and its open pipes otherwise keep a
+one-shot parent process alive after the last answer. Call it through `maker.dispose()` (from
+`createDecisionMaker`) or `registry.dispose('laya-local')`.
+
+---
+
 ## Backend selection (`ts-ai-runner`)
 
 Downstream applications using `createDecisionMaker` from `@gobing-ai/ts-ai-runner`
@@ -70,6 +104,7 @@ Resolution order: `options.driver` (custom driver double) → `options.backend`
 | Dimension | Hosted TypeSafe (`ts-ai-runner`) | Local Laya (`ts-laya-mlx`) | Notes |
 |-----------|----------------------------------|---------------------------|-------|
 | **Factory** | `createTypesafeDriver(config)` | `createLayaDriver(options)` | Both return `DecisionDriver` with single `ask()` method. |
+| **Release** | none (stateless HTTP) | `dispose()` closes the warm worker | A `laya-local` maker must be disposed or a one-shot parent never exits. |
 | **Driver name** | `'typesafe'` | `'laya-local'` | Available on `driver.name`. |
 | **Credentials** | `apiKey: string` (`TYPESAFE_API_KEY`) | `env.HF_TOKEN` (optional) | Local inference needs no key; token only for gated HF repos. |
 | **Model selector** | `model?: string` | `modelId?: string` | Default: `'convaiinnovations/laya-multilingual'`. |

package/dist/driver.d.ts

@@ -1,15 +1,38 @@
 /**
  * The local Laya decision driver satisfying {@link DecisionDriver} from `@gobing-ai/ts-ai-runner`.
- * Translates provider-neutral decision requests into the JSON-lines worker format
- * and maps worker answers back onto neutral {@link Answer} types (task 0078).
+ * Translates provider-neutral decision requests into the laya-mlx question format
+ * and maps answers back onto neutral {@link Answer} types (task 0078). Two MLX cores
+ * serve the same wire shape: the Python worker (`mlx-python`) and the in-process
+ * `@johnhenry/laya` port (`mlx-native`).
  */
 import { type Answer, type DecisionDriver, type Question } from '@gobing-ai/ts-ai-runner';
-import { LayaWorkerClient, type LayaWorkerClientOptions, type WorkerQuestion } from './worker-client';
+import { type LayaNativeLoader } from './native-client';
+import { type LayaWorkerClientOptions, type LayaWorkerResult, type WorkerQuestion } from './worker-client';
+/**
+ * Execution core behind `laya-local`. Both run Apple MLX on Metal:
+ * - `mlx-python`: warm `laya-mlx` Python worker over JSON lines (default; needs a Python env).
+ * - `mlx-native`: in-process `@johnhenry/laya` via libmlxc FFI (no Python).
+ * - `auto`: try `mlx-native`, fall back to `mlx-python` when it cannot load.
+ */
+export type LayaCore = 'mlx-python' | 'mlx-native' | 'auto';
+/** The `ask` surface both cores implement. */
+export interface LayaClient {
+    ask(state: string, questions: Record<string, WorkerQuestion>): Promise<LayaWorkerResult>;
+    dispose(): void;
+}
 /** Configuration options for {@link createLayaDriver}. */
 export interface LayaDriverOptions extends LayaWorkerClientOptions {
-    /** Pre-constructed worker client (useful for dependency injection in tests). */
-    client?: LayaWorkerClient;
+    /** Execution core. Default: `env.LAYA_CORE`, else `'mlx-python'`. */
+    core?: LayaCore;
+    /** Pre-constructed client (dependency injection in tests); bypasses core selection. */
+    client?: LayaClient;
+    /** Injected native loader (tests); forwarded to {@link LayaNativeClient}. */
+    nativeLoader?: LayaNativeLoader;
 }
+/** Resolve the configured core: explicit option → injected `env.LAYA_CORE` → `'mlx-python'`. */
+export declare function resolveLayaCore(options?: Pick<LayaDriverOptions, 'core' | 'env'>): LayaCore;
+/** Construct the client for the resolved core. */
+export declare function createLayaClient(options?: LayaDriverOptions): LayaClient;
 /** Convert a neutral {@link Question} into the wire shape consumed by the worker. */
 export declare function toWorkerQuestion(question: Question): WorkerQuestion;
 /**

package/dist/driver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../src/driver.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACH,KAAK,MAAM,EAEX,KAAK,cAAc,EAInB,KAAK,QAAQ,EAChB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtG,0DAA0D;AAC1D,MAAM,WAAW,iBAAkB,SAAQ,uBAAuB;IAC9D,gFAAgF;IAChF,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC7B;AASD,qFAAqF;AACrF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,GAAG,cAAc,CA8BnE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,GAAG,MAAM,CA0E9E;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,iBAAsB,GAAG,cAAc,CAoChF"}
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../src/driver.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACH,KAAK,MAAM,EAGX,KAAK,cAAc,EAInB,KAAK,QAAQ,EAChB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAoB,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAC1E,OAAO,EAEH,KAAK,uBAAuB,EAC5B,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACtB,MAAM,iBAAiB,CAAC;AAEzB;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,YAAY,GAAG,YAAY,GAAG,MAAM,CAAC;AAI5D,8CAA8C;AAC9C,MAAM,WAAW,UAAU;IACvB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACzF,OAAO,IAAI,IAAI,CAAC;CACnB;AAED,0DAA0D;AAC1D,MAAM,WAAW,iBAAkB,SAAQ,uBAAuB;IAC9D,qEAAqE;IACrE,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,uFAAuF;IACvF,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,6EAA6E;IAC7E,YAAY,CAAC,EAAE,gBAAgB,CAAC;CACnC;AAED,gGAAgG;AAChG,wBAAgB,eAAe,CAAC,OAAO,GAAE,IAAI,CAAC,iBAAiB,EAAE,MAAM,GAAG,KAAK,CAAM,GAAG,QAAQ,CAS/F;AA8CD,kDAAkD;AAClD,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,iBAAsB,GAAG,UAAU,CAS5E;AAuBD,qFAAqF;AACrF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,GAAG,cAAc,CA8BnE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,GAAG,MAAM,CA2E9E;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,iBAAsB,GAAG,cAAc,CAwChF"}

package/dist/driver.js

@@ -1,36 +1,118 @@
 /**
  * The local Laya decision driver satisfying {@link DecisionDriver} from `@gobing-ai/ts-ai-runner`.
- * Translates provider-neutral decision requests into the JSON-lines worker format
- * and maps worker answers back onto neutral {@link Answer} types (task 0078).
+ * Translates provider-neutral decision requests into the laya-mlx question format
+ * and maps answers back onto neutral {@link Answer} types (task 0078). Two MLX cores
+ * serve the same wire shape: the Python worker (`mlx-python`) and the in-process
+ * `@johnhenry/laya` port (`mlx-native`).
  */
-import { DecisionBackendError, DecisionRequestError, } from '@gobing-ai/ts-ai-runner';
-import { LayaWorkerClient } from './worker-client.js';
+import { DecisionBackendError, DecisionConfigError, DecisionRequestError, } from '@gobing-ai/ts-ai-runner';
+import { LayaNativeClient } from './native-client.js';
+import { LayaWorkerClient, } from './worker-client.js';
+const LAYA_CORES = ['mlx-python', 'mlx-native', 'auto'];
+/** Resolve the configured core: explicit option → injected `env.LAYA_CORE` → `'mlx-python'`. */
+export function resolveLayaCore(options = {}) {
+    const raw = options.core ?? (options.env?.LAYA_CORE || undefined) ?? 'mlx-python';
+    if (!LAYA_CORES.includes(raw)) {
+        throw new DecisionConfigError(`Unknown laya core '${raw}'; expected one of ${LAYA_CORES.join(', ')}`, 'LAYA_CORE');
+    }
+    return raw;
+}
+/**
+ * `auto` core: the first ask probes `mlx-native` by loading the weights; any load
+ * failure (missing libmlxc, unsupported option, bad checkpoint) falls back to the
+ * Python worker for the client's lifetime. Request-time errors are not retried.
+ */
+class AutoLayaClient {
+    options;
+    active = null;
+    resolved = null;
+    disposed = false;
+    constructor(options) {
+        this.options = options;
+    }
+    async ask(state, questions) {
+        this.active ??= this.select();
+        return (await this.active).ask(state, questions);
+    }
+    dispose() {
+        this.disposed = true;
+        this.resolved?.dispose();
+    }
+    async select() {
+        let chosen;
+        try {
+            const native = new LayaNativeClient({ ...this.options, loader: this.options.nativeLoader });
+            try {
+                await native.warm();
+            }
+            catch (error) {
+                native.dispose();
+                throw error;
+            }
+            chosen = native;
+        }
+        catch (error) {
+            if (!(error instanceof DecisionConfigError))
+                throw error;
+            chosen = new LayaWorkerClient(this.options);
+        }
+        this.resolved = chosen;
+        // dispose() raced the native probe: the chosen client must not outlive us.
+        if (this.disposed)
+            chosen.dispose();
+        return chosen;
+    }
+}
+/** Construct the client for the resolved core. */
+export function createLayaClient(options = {}) {
+    switch (resolveLayaCore(options)) {
+        case 'mlx-native':
+            return new LayaNativeClient({ ...options, loader: options.nativeLoader });
+        case 'auto':
+            return new AutoLayaClient(options);
+        default:
+            return new LayaWorkerClient(options);
+    }
+}
 /** Format a {@link Desc} field into a string instructions value for the worker. */
-function formatDesc(desc) {
+function formatDesc(desc, fallback = '') {
     if (typeof desc === 'string')
-        return desc;
+        return desc.trim().length > 0 ? desc : fallback;
     if (desc === null || desc === undefined)
-        return '';
+        return fallback;
     return JSON.stringify(desc);
 }
+/** Rescale a probability distribution to sum to exactly 1.0 when rounding error exceeds 1e-6. */
+function normalizeDistribution(probs) {
+    const entries = Object.entries(probs);
+    const sum = entries.reduce((s, [, p]) => s + (typeof p === 'number' && Number.isFinite(p) ? p : 0), 0);
+    if (sum <= 0 || Math.abs(sum - 1) <= 1e-6) {
+        return probs;
+    }
+    const result = {};
+    for (const [k, p] of entries) {
+        result[k] = p / sum;
+    }
+    return result;
+}
 /** Convert a neutral {@link Question} into the wire shape consumed by the worker. */
 export function toWorkerQuestion(question) {
     switch (question.kind) {
         case 'choice':
             return {
                 type: 'choice',
-                instructions: formatDesc(question.prompt),
+                instructions: formatDesc(question.prompt, 'Select the best matching option.'),
                 labels: question.labels,
                 criteria: question.labels,
             };
         case 'score':
             return {
                 type: 'score',
-                instructions: formatDesc(question.prompt),
+                instructions: formatDesc(question.prompt, 'Evaluate according to the rubric.'),
                 rubric: question.rubric,
                 // The runtime rejects a map here: score criteria is the rubric as a
                 // nonempty list of descriptions (laya_mlx agent.py `_to_internal`).
-                criteria: question.rubric.map(formatDesc),
+                criteria: question.rubric.map((r) => formatDesc(r, 'Level')),
             };
         case 'noul': {
             const outcomes = question.yes === undefined && question.no === undefined
@@ -38,7 +120,7 @@ export function toWorkerQuestion(question) {
                 : { true: question.yes ?? null, false: question.no ?? null };
             return {
                 type: 'noul',
-                instructions: formatDesc(question.prompt),
+                instructions: formatDesc(question.prompt, 'Evaluate whether the proposition is true.'),
                 ...(outcomes !== undefined ? { criteria: outcomes } : {}),
             };
         }
@@ -60,7 +142,8 @@ export function mapWorkerAnswer(question, rawAnswer) {
                 throw new DecisionBackendError('laya worker returned invalid choice answer: missing label', undefined);
             }
             const confidence = typeof raw.confidence === 'number' ? raw.confidence : 0;
-            const probabilities = (raw.probabilities ?? {});
+            const rawProbs = (raw.probabilities ?? {});
+            const probabilities = normalizeDistribution(rawProbs);
             return {
                 kind: 'choice',
                 label,
@@ -102,7 +185,7 @@ export function mapWorkerAnswer(question, rawAnswer) {
                 score,
                 confidence,
                 legend: rawLegend ? normalizedLegend : legend,
-                probabilities: normalizedProbs,
+                probabilities: normalizeDistribution(normalizedProbs),
             };
         }
         case 'noul': {
@@ -124,9 +207,13 @@ export function mapWorkerAnswer(question, rawAnswer) {
  * Exposes a readonly `name: 'laya-local'` and a single `ask` method with no sugar.
  */
 export function createLayaDriver(options = {}) {
-    const client = options.client ?? new LayaWorkerClient(options);
+    const client = options.client ?? createLayaClient(options);
     return {
         name: 'laya-local',
+        // The client holds a warm Python worker for its lifetime (and the worker's open pipes keep
+        // a one-shot parent alive), so the driver exposes the release the client already owns; a
+        // consumer that made no call has nothing to close and every dispose is idempotent.
+        dispose: () => client.dispose(),
         async ask({ state, questions, }) {
             if (!questions || typeof questions !== 'object' || Object.keys(questions).length === 0) {
                 throw new DecisionRequestError('expected a nonempty question map', undefined, undefined);

package/dist/index.d.ts

@@ -1,7 +1,9 @@
 /**
  * @gobing-ai/ts-laya-mlx — Local Laya decision backend driving the vendored MLX runtime.
- * Implements the {@link DecisionDriver} interface for `@gobing-ai/ts-ai-runner` over a JSON-lines process bridge.
+ * Implements the {@link DecisionDriver} interface for `@gobing-ai/ts-ai-runner` on one of two MLX cores:
+ * a JSON-lines Python worker (`mlx-python`, default) or in-process `@johnhenry/laya` (`mlx-native`).
  */
-export { createLayaDriver, type LayaDriverOptions } from './driver';
-export { LayaWorkerClient, type LayaWorkerClientOptions, type LayaWorkerResult, translateWorkerError, validateHostPrerequisites, type WorkerQuestion, } from './worker-client';
+export { createLayaClient, createLayaDriver, type LayaClient, type LayaCore, type LayaDriverOptions, resolveLayaCore, } from './driver';
+export { LayaNativeClient, type LayaNativeClientOptions, type LayaNativeLoader } from './native-client';
+export { DEFAULT_LAYA_MODEL_ID, LayaWorkerClient, type LayaWorkerClientOptions, type LayaWorkerResult, translateWorkerError, validateHostPrerequisites, type WorkerQuestion, } from './worker-client';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,gBAAgB,EAAE,KAAK,iBAAiB,EAAE,MAAM,UAAU,CAAC;AACpE,OAAO,EACH,gBAAgB,EAChB,KAAK,uBAAuB,EAC5B,KAAK,gBAAgB,EACrB,oBAAoB,EACpB,yBAAyB,EACzB,KAAK,cAAc,GACtB,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACH,gBAAgB,EAChB,gBAAgB,EAChB,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,KAAK,iBAAiB,EACtB,eAAe,GAClB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxG,OAAO,EACH,qBAAqB,EACrB,gBAAgB,EAChB,KAAK,uBAAuB,EAC5B,KAAK,gBAAgB,EACrB,oBAAoB,EACpB,yBAAyB,EACzB,KAAK,cAAc,GACtB,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -1,6 +1,8 @@
 /**
  * @gobing-ai/ts-laya-mlx — Local Laya decision backend driving the vendored MLX runtime.
- * Implements the {@link DecisionDriver} interface for `@gobing-ai/ts-ai-runner` over a JSON-lines process bridge.
+ * Implements the {@link DecisionDriver} interface for `@gobing-ai/ts-ai-runner` on one of two MLX cores:
+ * a JSON-lines Python worker (`mlx-python`, default) or in-process `@johnhenry/laya` (`mlx-native`).
  */
-export { createLayaDriver } from './driver.js';
-export { LayaWorkerClient, translateWorkerError, validateHostPrerequisites, } from './worker-client.js';
+export { createLayaClient, createLayaDriver, resolveLayaCore, } from './driver.js';
+export { LayaNativeClient } from './native-client.js';
+export { DEFAULT_LAYA_MODEL_ID, LayaWorkerClient, translateWorkerError, validateHostPrerequisites, } from './worker-client.js';

package/dist/native-client.d.ts

@@ -0,0 +1,61 @@
+/**
+ * In-process MLX client over `@johnhenry/laya` (`mlx-native` core).
+ * Runs the same Laya checkpoint on Apple Silicon Metal through libmlxc FFI —
+ * no Python interpreter, no child process. Exposes the same `ask()` shape as
+ * {@link LayaWorkerClient} so the driver maps answers identically for both cores.
+ */
+import type { LayaAgent } from '@johnhenry/laya';
+import { type LayaWorkerResult, type WorkerQuestion } from './worker-client';
+/** Loads a checkpoint into a ready agent; the seam the tests substitute. */
+export type LayaNativeLoader = (target: string, opts: Record<string, unknown>) => Promise<LayaAgent>;
+/** Configuration for {@link LayaNativeClient}. */
+export interface LayaNativeClientOptions {
+    /** Hugging Face model id. Default: `convaiinnovations/laya-multilingual`. */
+    modelId?: string;
+    /** Local checkpoint directory (e.g. a fine-tuned model); wins over `modelId`. */
+    modelPath?: string;
+    /** Checkpoint revision pinned for resolution. */
+    revision?: string;
+    /**
+     * Not supported natively: `@johnhenry/laya` resolves the hub cache from the
+     * process environment only. Set → construction fails rather than being silently ignored.
+     */
+    cacheDir?: string;
+    /** Weight precision. `bfloat16` is not supported by the native backend. Default: `'float16'`. */
+    dtype?: 'float32' | 'float16' | 'bfloat16';
+    /** Questions per forward pass. Default: `16`. */
+    batchSize?: number;
+    /** Injected environment record — this package never reads the ambient environment (ADR-011). */
+    env?: Record<string, string | undefined>;
+    platform?: string;
+    arch?: string;
+    /** Injected loader (tests). Default: dynamic import of `@johnhenry/laya`'s `load`. */
+    loader?: LayaNativeLoader;
+}
+/**
+ * In-process MLX client over `@johnhenry/laya`: same wire shape and `ask()`
+ * contract as {@link LayaWorkerClient}, backed by libmlxc instead of a Python
+ * worker. Construction validates the host and the options the native backend
+ * cannot honor; the checkpoint is loaded lazily on the first `warm()`/`ask()`.
+ */
+export declare class LayaNativeClient {
+    private agent;
+    private loading;
+    private chain;
+    private disposed;
+    private readonly target;
+    private readonly loadOptions;
+    private readonly loader;
+    constructor(options?: LayaNativeClientOptions);
+    /** Checkpoint target actually loaded (model path or hub id). */
+    get model(): string;
+    /** Eagerly load the weights; `auto` core resolution uses this to probe native availability. */
+    warm(): Promise<void>;
+    /** Ask one batch of worker-format questions; serialized like the python worker. */
+    ask(state: string, questions: Record<string, WorkerQuestion>): Promise<LayaWorkerResult>;
+    /** Release Metal buffers; safe to call repeatedly. */
+    dispose(): void;
+    private dispatch;
+    private ensureAgent;
+}
+//# sourceMappingURL=native-client.d.ts.map

package/dist/native-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-client.d.ts","sourceRoot":"","sources":["../src/native-client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAa,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAGH,KAAK,gBAAgB,EAErB,KAAK,cAAc,EACtB,MAAM,iBAAiB,CAAC;AAEzB,4EAA4E;AAC5E,MAAM,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;AAErG,kDAAkD;AAClD,MAAM,WAAW,uBAAuB;IACpC,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iGAAiG;IACjG,KAAK,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,UAAU,CAAC;IAC3C,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gGAAgG;IAChG,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sFAAsF;IACtF,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC7B;AAQD;;;;;GAKG;AACH,qBAAa,gBAAgB;IACzB,OAAO,CAAC,KAAK,CAA0B;IACvC,OAAO,CAAC,OAAO,CAAmC;IAClD,OAAO,CAAC,KAAK,CAAuC;IACpD,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA0B;IACtD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;gBAE9B,OAAO,GAAE,uBAA4B;IAiCjD,gEAAgE;IAChE,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,+FAA+F;IACzF,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,mFAAmF;IACnF,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC;IASxF,sDAAsD;IACtD,OAAO,IAAI,IAAI;YAMD,QAAQ;IAmBtB,OAAO,CAAC,WAAW;CA2BtB"}

package/dist/native-client.js

@@ -0,0 +1,111 @@
+/**
+ * In-process MLX client over `@johnhenry/laya` (`mlx-native` core).
+ * Runs the same Laya checkpoint on Apple Silicon Metal through libmlxc FFI —
+ * no Python interpreter, no child process. Exposes the same `ask()` shape as
+ * {@link LayaWorkerClient} so the driver maps answers identically for both cores.
+ */
+import { DecisionBackendError, DecisionConfigError } from '@gobing-ai/ts-ai-runner';
+import { DEFAULT_LAYA_MODEL_ID, hasNonFiniteValues, validateHostPrerequisites, } from './worker-client.js';
+const defaultLoader = async (target, opts) => {
+    // Dynamic import keeps libmlxc/koffi out of the module graph when the python core is used.
+    const { load } = await import('@johnhenry/laya');
+    return load(target, opts);
+};
+/**
+ * In-process MLX client over `@johnhenry/laya`: same wire shape and `ask()`
+ * contract as {@link LayaWorkerClient}, backed by libmlxc instead of a Python
+ * worker. Construction validates the host and the options the native backend
+ * cannot honor; the checkpoint is loaded lazily on the first `warm()`/`ask()`.
+ */
+export class LayaNativeClient {
+    agent = null;
+    loading = null;
+    chain = Promise.resolve();
+    disposed = false;
+    target;
+    loadOptions;
+    loader;
+    constructor(options = {}) {
+        validateHostPrerequisites(options.platform, options.arch);
+        const cacheDir = options.cacheDir ?? options.env?.LAYA_CACHE_DIR;
+        if (cacheDir !== undefined) {
+            throw new DecisionConfigError("laya core 'mlx-native' cannot honor cacheDir/LAYA_CACHE_DIR; set HF_HUB_CACHE for the process or use core 'mlx-python'", 'LAYA_CACHE_DIR');
+        }
+        if (options.dtype === 'bfloat16') {
+            throw new DecisionConfigError("laya core 'mlx-native' supports dtype 'float16' or 'float32', not 'bfloat16'", 'LAYA_DTYPE');
+        }
+        this.target =
+            options.modelPath ??
+                options.env?.LAYA_MODEL_PATH ??
+                options.modelId ??
+                options.env?.LAYA_MODEL_ID ??
+                DEFAULT_LAYA_MODEL_ID;
+        this.loadOptions = {
+            backend: 'mlx',
+            dtype: options.dtype === 'float32' ? 'f32' : 'f16',
+            batchSize: options.batchSize ?? 16,
+            ...(options.revision !== undefined ? { revision: options.revision } : {}),
+            ...(options.env?.HF_TOKEN ? { token: options.env.HF_TOKEN } : {}),
+            // The temperature-clamping notice would otherwise land on the host's console.
+            warn: () => { },
+        };
+        this.loader = options.loader ?? defaultLoader;
+    }
+    /** Checkpoint target actually loaded (model path or hub id). */
+    get model() {
+        return this.target;
+    }
+    /** Eagerly load the weights; `auto` core resolution uses this to probe native availability. */
+    async warm() {
+        await this.ensureAgent();
+    }
+    /** Ask one batch of worker-format questions; serialized like the python worker. */
+    ask(state, questions) {
+        const run = this.chain.then(() => this.dispatch(state, questions));
+        this.chain = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    /** Release Metal buffers; safe to call repeatedly. */
+    dispose() {
+        this.disposed = true;
+        this.agent?.dispose();
+        this.agent = null;
+    }
+    async dispatch(state, questions) {
+        const agent = await this.ensureAgent();
+        let result;
+        try {
+            // WorkerQuestion is the laya-mlx wire shape, which @johnhenry/laya ports 1:1.
+            result = (await agent.predict(state, questions));
+        }
+        catch (cause) {
+            const message = cause instanceof Error ? cause.message : String(cause);
+            throw new DecisionBackendError(`laya native inference failed: ${message}`, undefined, { cause });
+        }
+        if (hasNonFiniteValues(result.answers)) {
+            throw new DecisionBackendError("laya native returned non-finite model outputs; retry with dtype='float32'", undefined);
+        }
+        return result;
+    }
+    ensureAgent() {
+        if (this.disposed) {
+            return Promise.reject(new DecisionBackendError('laya native client has been disposed', undefined));
+        }
+        if (this.agent)
+            return Promise.resolve(this.agent);
+        this.loading ??= this.loader(this.target, this.loadOptions).then((agent) => {
+            this.loading = null;
+            if (this.disposed) {
+                agent.dispose();
+                throw new DecisionBackendError('laya native client has been disposed', undefined);
+            }
+            this.agent = agent;
+            return agent;
+        }, (cause) => {
+            this.loading = null;
+            const message = cause instanceof Error ? cause.message : String(cause);
+            throw new DecisionConfigError(`laya core 'mlx-native' failed to load '${this.target}': ${message}`, 'LAYA_CORE', { cause });
+        });
+        return this.loading;
+    }
+}

package/dist/worker-client.d.ts

@@ -12,7 +12,7 @@
  * boundary. Protocol reference: docs/design/laya-local-decision-backend.md.
  */
 import { type DecisionError } from '@gobing-ai/ts-ai-runner';
-import { type ProcessExecutor } from '@gobing-ai/ts-runtime';
+import { type FileSystem, type ProcessExecutor } from '@gobing-ai/ts-runtime';
 /** Configuration options for {@link LayaWorkerClient}. */
 export interface LayaWorkerClientOptions {
     /** Interpreter that carries `laya-mlx`. Default: `'python3'`. */
@@ -69,10 +69,16 @@ export interface LayaWorkerResult {
  * Throws {@link DecisionConfigError} if the platform is not Apple Silicon macOS.
  */
 export declare function validateHostPrerequisites(platform?: string, arch?: string): void;
+/** Official Laya checkpoint used when no modelId/modelPath is configured. */
+export declare const DEFAULT_LAYA_MODEL_ID = "convaiinnovations/laya-multilingual";
+/** @internal True when any number nested in `obj` is NaN/Infinity (fp16 overflow). */
+export declare function hasNonFiniteValues(obj: unknown): boolean;
 /**
  * Map worker-reported error kinds and messages onto the decision taxonomy (design: Errors table, task 0077).
  */
 export declare function translateWorkerError(kind: string | undefined, message: string): DecisionError;
+/** Resolve the Python interpreter to execute: explicit option -> injected env -> candidate discovery -> 'python3'. */
+export declare function resolvePythonPath(options: LayaWorkerClientOptions, packageRoot: string, cwd: string, fileSystem?: FileSystem): string;
 /**
  * TypeScript half of the laya process bridge: start the Python worker lazily,
  * hold it warm for the client's lifetime, and serve serialized asks with

package/dist/worker-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"worker-client.d.ts","sourceRoot":"","sources":["../src/worker-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"worker-client.d.ts","sourceRoot":"","sources":["../src/worker-client.ts"],"names":[],"mappings":"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"}

package/dist/worker-client.js

@@ -12,7 +12,7 @@
  * boundary. Protocol reference: docs/design/laya-local-decision-backend.md.
  */
 import { DecisionAuthError, DecisionBackendError, DecisionConfigError, DecisionConnectionError, DecisionRequestError, DecisionTimeoutError, } from '@gobing-ai/ts-ai-runner';
-import { joinPath, nodeBunFactory } from '@gobing-ai/ts-runtime';
+import { getHomeDir, joinPath, nodeBunFactory, } from '@gobing-ai/ts-runtime';
 /** Environment keys this package may pass to the child process — the full allowlist. */
 const FORWARDED_ENV_KEYS = ['LAYA_MODEL_ID', 'LAYA_MODEL_PATH', 'LAYA_CACHE_DIR', 'LAYA_PYTHON', 'HF_TOKEN'];
 /** How many trailing stderr bytes to keep for exit-failure messages. */
@@ -44,7 +44,10 @@ export function validateHostPrerequisites(platform = process.platform, arch = pr
         throw new DecisionConfigError(`laya-mlx requires macOS on Apple Silicon (darwin arm64); current platform is '${platform} ${arch}'`, 'PLATFORM');
     }
 }
-function hasNonFiniteValues(obj) {
+/** Official Laya checkpoint used when no modelId/modelPath is configured. */
+export const DEFAULT_LAYA_MODEL_ID = 'convaiinnovations/laya-multilingual';
+/** @internal True when any number nested in `obj` is NaN/Infinity (fp16 overflow). */
+export function hasNonFiniteValues(obj) {
     if (typeof obj === 'number') {
         return !Number.isFinite(obj);
     }
@@ -317,6 +320,27 @@ class WorkerHandle {
         });
     }
 }
+/** Resolve the Python interpreter to execute: explicit option -> injected env -> candidate discovery -> 'python3'. */
+export function resolvePythonPath(options, packageRoot, cwd, fileSystem = nodeBunFactory.createFileSystem()) {
+    if (options.pythonPath !== undefined)
+        return options.pythonPath;
+    if (options.env?.LAYA_PYTHON !== undefined && options.env.LAYA_PYTHON.length > 0) {
+        return options.env.LAYA_PYTHON;
+    }
+    const home = getHomeDir();
+    const candidates = [
+        home ? joinPath(home, '.local', 'share', 'uv', 'tools', 'laya-mlx', 'bin', 'python') : undefined,
+        home ? joinPath(home, '.virtualenvs', 'laya-mlx', 'bin', 'python') : undefined,
+        joinPath(packageRoot, '..', '..', 'vendors', 'laya-mlx', '.venv', 'bin', 'python'),
+        joinPath(cwd, '.venv', 'bin', 'python'),
+    ].filter((p) => p !== undefined);
+    for (const candidate of candidates) {
+        if (fileSystem.exists(candidate)) {
+            return candidate;
+        }
+    }
+    return 'python3';
+}
 /**
  * TypeScript half of the laya process bridge: start the Python worker lazily,
  * hold it warm for the client's lifetime, and serve serialized asks with
@@ -336,8 +360,8 @@ export class LayaWorkerClient {
     constructor(options = {}, executor = nodeBunFactory.createProcessExecutor()) {
         validateHostPrerequisites(options.platform, options.arch);
         const packageRoot = joinPath(import.meta.dir, '..');
-        this.pythonPath = options.pythonPath ?? options.env?.LAYA_PYTHON ?? 'python3';
         this.cwd = options.cwd ?? packageRoot;
+        this.pythonPath = resolvePythonPath(options, packageRoot, this.cwd);
         this.startupTimeoutMs = options.startupTimeoutMs ?? 120_000;
         this.requestTimeoutMs = options.requestTimeoutMs ?? 30_000;
         this.forwardedEnv = resolveForwardedEnv(options.env);
@@ -346,7 +370,7 @@ export class LayaWorkerClient {
         this.args.push('--module', options.module ?? 'laya_mlx');
         const resolvedModelPath = options.modelPath ?? options.env?.LAYA_MODEL_PATH;
         const resolvedCacheDir = options.cacheDir ?? options.env?.LAYA_CACHE_DIR;
-        const resolvedModelId = options.modelId ?? options.env?.LAYA_MODEL_ID ?? 'convaiinnovations/laya-multilingual';
+        const resolvedModelId = options.modelId ?? options.env?.LAYA_MODEL_ID ?? DEFAULT_LAYA_MODEL_ID;
         if (resolvedModelPath !== undefined) {
             this.args.push('--model-path', resolvedModelPath);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-laya-mlx",
-    "version": "0.5.21",
+    "version": "0.5.23",
     "description": "@gobing-ai/ts-laya-mlx — Local Laya decision backend driving the vendored MLX runtime over a process bridge.",
     "keywords": [
         "typescript",
@@ -52,8 +52,12 @@
         "release": "echo 'Manual publish is disabled. Releases go through GitHub Actions via Trusted Publishing — push a tag: git tag @gobing-ai/ts-laya-mlx-v<version> && git push --tags' && exit 1"
     },
     "dependencies": {
-        "@gobing-ai/ts-ai-runner": "^0.5.21",
-        "@gobing-ai/ts-runtime": "^0.5.21"
+        "@gobing-ai/ts-ai-runner": "^0.5.23",
+        "@gobing-ai/ts-runtime": "^0.5.23",
+        "@johnhenry/laya": "0.3.2"
+    },
+    "optionalDependencies": {
+        "@johnhenry/backend-mlx": "0.5.0"
     },
     "devDependencies": {
         "@types/bun": "1.3.14"

package/src/driver.ts

@@ -1,51 +1,162 @@
 /**
  * The local Laya decision driver satisfying {@link DecisionDriver} from `@gobing-ai/ts-ai-runner`.
- * Translates provider-neutral decision requests into the JSON-lines worker format
- * and maps worker answers back onto neutral {@link Answer} types (task 0078).
+ * Translates provider-neutral decision requests into the laya-mlx question format
+ * and maps answers back onto neutral {@link Answer} types (task 0078). Two MLX cores
+ * serve the same wire shape: the Python worker (`mlx-python`) and the in-process
+ * `@johnhenry/laya` port (`mlx-native`).
  */
 
 import {
     type Answer,
     DecisionBackendError,
+    DecisionConfigError,
     type DecisionDriver,
     DecisionRequestError,
     type DecisionState,
     type Desc,
     type Question,
 } from '@gobing-ai/ts-ai-runner';
-import { LayaWorkerClient, type LayaWorkerClientOptions, type WorkerQuestion } from './worker-client';
+import { LayaNativeClient, type LayaNativeLoader } from './native-client';
+import {
+    LayaWorkerClient,
+    type LayaWorkerClientOptions,
+    type LayaWorkerResult,
+    type WorkerQuestion,
+} from './worker-client';
+
+/**
+ * Execution core behind `laya-local`. Both run Apple MLX on Metal:
+ * - `mlx-python`: warm `laya-mlx` Python worker over JSON lines (default; needs a Python env).
+ * - `mlx-native`: in-process `@johnhenry/laya` via libmlxc FFI (no Python).
+ * - `auto`: try `mlx-native`, fall back to `mlx-python` when it cannot load.
+ */
+export type LayaCore = 'mlx-python' | 'mlx-native' | 'auto';
+
+const LAYA_CORES: readonly LayaCore[] = ['mlx-python', 'mlx-native', 'auto'];
+
+/** The `ask` surface both cores implement. */
+export interface LayaClient {
+    ask(state: string, questions: Record<string, WorkerQuestion>): Promise<LayaWorkerResult>;
+    dispose(): void;
+}
 
 /** Configuration options for {@link createLayaDriver}. */
 export interface LayaDriverOptions extends LayaWorkerClientOptions {
-    /** Pre-constructed worker client (useful for dependency injection in tests). */
-    client?: LayaWorkerClient;
+    /** Execution core. Default: `env.LAYA_CORE`, else `'mlx-python'`. */
+    core?: LayaCore;
+    /** Pre-constructed client (dependency injection in tests); bypasses core selection. */
+    client?: LayaClient;
+    /** Injected native loader (tests); forwarded to {@link LayaNativeClient}. */
+    nativeLoader?: LayaNativeLoader;
+}
+
+/** Resolve the configured core: explicit option → injected `env.LAYA_CORE` → `'mlx-python'`. */
+export function resolveLayaCore(options: Pick<LayaDriverOptions, 'core' | 'env'> = {}): LayaCore {
+    const raw = options.core ?? (options.env?.LAYA_CORE || undefined) ?? 'mlx-python';
+    if (!(LAYA_CORES as readonly string[]).includes(raw)) {
+        throw new DecisionConfigError(
+            `Unknown laya core '${raw}'; expected one of ${LAYA_CORES.join(', ')}`,
+            'LAYA_CORE',
+        );
+    }
+    return raw as LayaCore;
+}
+
+/**
+ * `auto` core: the first ask probes `mlx-native` by loading the weights; any load
+ * failure (missing libmlxc, unsupported option, bad checkpoint) falls back to the
+ * Python worker for the client's lifetime. Request-time errors are not retried.
+ */
+class AutoLayaClient implements LayaClient {
+    private active: Promise<LayaClient> | null = null;
+    private resolved: LayaClient | null = null;
+    private disposed = false;
+
+    constructor(private readonly options: LayaDriverOptions) {}
+
+    async ask(state: string, questions: Record<string, WorkerQuestion>): Promise<LayaWorkerResult> {
+        this.active ??= this.select();
+        return (await this.active).ask(state, questions);
+    }
+
+    dispose(): void {
+        this.disposed = true;
+        this.resolved?.dispose();
+    }
+
+    private async select(): Promise<LayaClient> {
+        let chosen: LayaClient;
+        try {
+            const native = new LayaNativeClient({ ...this.options, loader: this.options.nativeLoader });
+            try {
+                await native.warm();
+            } catch (error) {
+                native.dispose();
+                throw error;
+            }
+            chosen = native;
+        } catch (error) {
+            if (!(error instanceof DecisionConfigError)) throw error;
+            chosen = new LayaWorkerClient(this.options);
+        }
+        this.resolved = chosen;
+        // dispose() raced the native probe: the chosen client must not outlive us.
+        if (this.disposed) chosen.dispose();
+        return chosen;
+    }
+}
+
+/** Construct the client for the resolved core. */
+export function createLayaClient(options: LayaDriverOptions = {}): LayaClient {
+    switch (resolveLayaCore(options)) {
+        case 'mlx-native':
+            return new LayaNativeClient({ ...options, loader: options.nativeLoader });
+        case 'auto':
+            return new AutoLayaClient(options);
+        default:
+            return new LayaWorkerClient(options);
+    }
 }
 
 /** Format a {@link Desc} field into a string instructions value for the worker. */
-function formatDesc(desc: Desc | undefined): string {
-    if (typeof desc === 'string') return desc;
-    if (desc === null || desc === undefined) return '';
+function formatDesc(desc: Desc | undefined, fallback = ''): string {
+    if (typeof desc === 'string') return desc.trim().length > 0 ? desc : fallback;
+    if (desc === null || desc === undefined) return fallback;
     return JSON.stringify(desc);
 }
 
+/** Rescale a probability distribution to sum to exactly 1.0 when rounding error exceeds 1e-6. */
+function normalizeDistribution<K extends string | number>(probs: Record<K, number>): Record<K, number> {
+    const entries = Object.entries(probs) as [K, number][];
+    const sum = entries.reduce<number>((s, [, p]) => s + (typeof p === 'number' && Number.isFinite(p) ? p : 0), 0);
+    if (sum <= 0 || Math.abs(sum - 1) <= 1e-6) {
+        return probs;
+    }
+    const result = {} as Record<K, number>;
+    for (const [k, p] of entries) {
+        result[k] = p / sum;
+    }
+    return result;
+}
+
 /** Convert a neutral {@link Question} into the wire shape consumed by the worker. */
 export function toWorkerQuestion(question: Question): WorkerQuestion {
     switch (question.kind) {
         case 'choice':
             return {
                 type: 'choice',
-                instructions: formatDesc(question.prompt),
+                instructions: formatDesc(question.prompt, 'Select the best matching option.'),
                 labels: question.labels,
                 criteria: question.labels,
             };
         case 'score':
             return {
                 type: 'score',
-                instructions: formatDesc(question.prompt),
+                instructions: formatDesc(question.prompt, 'Evaluate according to the rubric.'),
                 rubric: question.rubric,
                 // The runtime rejects a map here: score criteria is the rubric as a
                 // nonempty list of descriptions (laya_mlx agent.py `_to_internal`).
-                criteria: question.rubric.map(formatDesc),
+                criteria: question.rubric.map((r) => formatDesc(r, 'Level')),
             };
         case 'noul': {
             const outcomes =
@@ -54,7 +165,7 @@ export function toWorkerQuestion(question: Question): WorkerQuestion {
                     : { true: question.yes ?? null, false: question.no ?? null };
             return {
                 type: 'noul',
-                instructions: formatDesc(question.prompt),
+                instructions: formatDesc(question.prompt, 'Evaluate whether the proposition is true.'),
                 ...(outcomes !== undefined ? { criteria: outcomes } : {}),
             };
         }
@@ -77,7 +188,8 @@ export function mapWorkerAnswer(question: Question, rawAnswer: unknown): Answer
                 throw new DecisionBackendError('laya worker returned invalid choice answer: missing label', undefined);
             }
             const confidence = typeof raw.confidence === 'number' ? raw.confidence : 0;
-            const probabilities = (raw.probabilities ?? {}) as Record<string, number>;
+            const rawProbs = (raw.probabilities ?? {}) as Record<string, number>;
+            const probabilities = normalizeDistribution(rawProbs);
             return {
                 kind: 'choice',
                 label,
@@ -120,7 +232,7 @@ export function mapWorkerAnswer(question: Question, rawAnswer: unknown): Answer
                 score,
                 confidence,
                 legend: rawLegend ? normalizedLegend : legend,
-                probabilities: normalizedProbs,
+                probabilities: normalizeDistribution(normalizedProbs),
             };
         }
         case 'noul': {
@@ -146,10 +258,14 @@ export function mapWorkerAnswer(question: Question, rawAnswer: unknown): Answer
  * Exposes a readonly `name: 'laya-local'` and a single `ask` method with no sugar.
  */
 export function createLayaDriver(options: LayaDriverOptions = {}): DecisionDriver {
-    const client = options.client ?? new LayaWorkerClient(options);
+    const client = options.client ?? createLayaClient(options);
 
     return {
         name: 'laya-local',
+        // The client holds a warm Python worker for its lifetime (and the worker's open pipes keep
+        // a one-shot parent alive), so the driver exposes the release the client already owns; a
+        // consumer that made no call has nothing to close and every dispose is idempotent.
+        dispose: () => client.dispose(),
         async ask({
             state,
             questions,

package/src/index.ts

@@ -1,10 +1,20 @@
 /**
  * @gobing-ai/ts-laya-mlx — Local Laya decision backend driving the vendored MLX runtime.
- * Implements the {@link DecisionDriver} interface for `@gobing-ai/ts-ai-runner` over a JSON-lines process bridge.
+ * Implements the {@link DecisionDriver} interface for `@gobing-ai/ts-ai-runner` on one of two MLX cores:
+ * a JSON-lines Python worker (`mlx-python`, default) or in-process `@johnhenry/laya` (`mlx-native`).
  */
 
-export { createLayaDriver, type LayaDriverOptions } from './driver';
 export {
+    createLayaClient,
+    createLayaDriver,
+    type LayaClient,
+    type LayaCore,
+    type LayaDriverOptions,
+    resolveLayaCore,
+} from './driver';
+export { LayaNativeClient, type LayaNativeClientOptions, type LayaNativeLoader } from './native-client';
+export {
+    DEFAULT_LAYA_MODEL_ID,
     LayaWorkerClient,
     type LayaWorkerClientOptions,
     type LayaWorkerResult,

package/src/native-client.ts

@@ -0,0 +1,173 @@
+/**
+ * In-process MLX client over `@johnhenry/laya` (`mlx-native` core).
+ * Runs the same Laya checkpoint on Apple Silicon Metal through libmlxc FFI —
+ * no Python interpreter, no child process. Exposes the same `ask()` shape as
+ * {@link LayaWorkerClient} so the driver maps answers identically for both cores.
+ */
+
+import { DecisionBackendError, DecisionConfigError } from '@gobing-ai/ts-ai-runner';
+import type { LayaAgent, Questions } from '@johnhenry/laya';
+import {
+    DEFAULT_LAYA_MODEL_ID,
+    hasNonFiniteValues,
+    type LayaWorkerResult,
+    validateHostPrerequisites,
+    type WorkerQuestion,
+} from './worker-client';
+
+/** Loads a checkpoint into a ready agent; the seam the tests substitute. */
+export type LayaNativeLoader = (target: string, opts: Record<string, unknown>) => Promise<LayaAgent>;
+
+/** Configuration for {@link LayaNativeClient}. */
+export interface LayaNativeClientOptions {
+    /** Hugging Face model id. Default: `convaiinnovations/laya-multilingual`. */
+    modelId?: string;
+    /** Local checkpoint directory (e.g. a fine-tuned model); wins over `modelId`. */
+    modelPath?: string;
+    /** Checkpoint revision pinned for resolution. */
+    revision?: string;
+    /**
+     * Not supported natively: `@johnhenry/laya` resolves the hub cache from the
+     * process environment only. Set → construction fails rather than being silently ignored.
+     */
+    cacheDir?: string;
+    /** Weight precision. `bfloat16` is not supported by the native backend. Default: `'float16'`. */
+    dtype?: 'float32' | 'float16' | 'bfloat16';
+    /** Questions per forward pass. Default: `16`. */
+    batchSize?: number;
+    /** Injected environment record — this package never reads the ambient environment (ADR-011). */
+    env?: Record<string, string | undefined>;
+    platform?: string;
+    arch?: string;
+    /** Injected loader (tests). Default: dynamic import of `@johnhenry/laya`'s `load`. */
+    loader?: LayaNativeLoader;
+}
+
+const defaultLoader: LayaNativeLoader = async (target, opts) => {
+    // Dynamic import keeps libmlxc/koffi out of the module graph when the python core is used.
+    const { load } = await import('@johnhenry/laya');
+    return load(target, opts);
+};
+
+/**
+ * In-process MLX client over `@johnhenry/laya`: same wire shape and `ask()`
+ * contract as {@link LayaWorkerClient}, backed by libmlxc instead of a Python
+ * worker. Construction validates the host and the options the native backend
+ * cannot honor; the checkpoint is loaded lazily on the first `warm()`/`ask()`.
+ */
+export class LayaNativeClient {
+    private agent: LayaAgent | null = null;
+    private loading: Promise<LayaAgent> | null = null;
+    private chain: Promise<unknown> = Promise.resolve();
+    private disposed = false;
+    private readonly target: string;
+    private readonly loadOptions: Record<string, unknown>;
+    private readonly loader: LayaNativeLoader;
+
+    constructor(options: LayaNativeClientOptions = {}) {
+        validateHostPrerequisites(options.platform, options.arch);
+        const cacheDir = options.cacheDir ?? options.env?.LAYA_CACHE_DIR;
+        if (cacheDir !== undefined) {
+            throw new DecisionConfigError(
+                "laya core 'mlx-native' cannot honor cacheDir/LAYA_CACHE_DIR; set HF_HUB_CACHE for the process or use core 'mlx-python'",
+                'LAYA_CACHE_DIR',
+            );
+        }
+        if (options.dtype === 'bfloat16') {
+            throw new DecisionConfigError(
+                "laya core 'mlx-native' supports dtype 'float16' or 'float32', not 'bfloat16'",
+                'LAYA_DTYPE',
+            );
+        }
+        this.target =
+            options.modelPath ??
+            options.env?.LAYA_MODEL_PATH ??
+            options.modelId ??
+            options.env?.LAYA_MODEL_ID ??
+            DEFAULT_LAYA_MODEL_ID;
+        this.loadOptions = {
+            backend: 'mlx',
+            dtype: options.dtype === 'float32' ? 'f32' : 'f16',
+            batchSize: options.batchSize ?? 16,
+            ...(options.revision !== undefined ? { revision: options.revision } : {}),
+            ...(options.env?.HF_TOKEN ? { token: options.env.HF_TOKEN } : {}),
+            // The temperature-clamping notice would otherwise land on the host's console.
+            warn: () => {},
+        };
+        this.loader = options.loader ?? defaultLoader;
+    }
+
+    /** Checkpoint target actually loaded (model path or hub id). */
+    get model(): string {
+        return this.target;
+    }
+
+    /** Eagerly load the weights; `auto` core resolution uses this to probe native availability. */
+    async warm(): Promise<void> {
+        await this.ensureAgent();
+    }
+
+    /** Ask one batch of worker-format questions; serialized like the python worker. */
+    ask(state: string, questions: Record<string, WorkerQuestion>): Promise<LayaWorkerResult> {
+        const run = this.chain.then(() => this.dispatch(state, questions));
+        this.chain = run.then(
+            () => undefined,
+            () => undefined,
+        );
+        return run;
+    }
+
+    /** Release Metal buffers; safe to call repeatedly. */
+    dispose(): void {
+        this.disposed = true;
+        this.agent?.dispose();
+        this.agent = null;
+    }
+
+    private async dispatch(state: string, questions: Record<string, WorkerQuestion>): Promise<LayaWorkerResult> {
+        const agent = await this.ensureAgent();
+        let result: LayaWorkerResult;
+        try {
+            // WorkerQuestion is the laya-mlx wire shape, which @johnhenry/laya ports 1:1.
+            result = (await agent.predict(state, questions as unknown as Questions)) as unknown as LayaWorkerResult;
+        } catch (cause) {
+            const message = cause instanceof Error ? cause.message : String(cause);
+            throw new DecisionBackendError(`laya native inference failed: ${message}`, undefined, { cause });
+        }
+        if (hasNonFiniteValues(result.answers)) {
+            throw new DecisionBackendError(
+                "laya native returned non-finite model outputs; retry with dtype='float32'",
+                undefined,
+            );
+        }
+        return result;
+    }
+
+    private ensureAgent(): Promise<LayaAgent> {
+        if (this.disposed) {
+            return Promise.reject(new DecisionBackendError('laya native client has been disposed', undefined));
+        }
+        if (this.agent) return Promise.resolve(this.agent);
+        this.loading ??= this.loader(this.target, this.loadOptions).then(
+            (agent) => {
+                this.loading = null;
+                if (this.disposed) {
+                    agent.dispose();
+                    throw new DecisionBackendError('laya native client has been disposed', undefined);
+                }
+                this.agent = agent;
+                return agent;
+            },
+            (cause: unknown) => {
+                this.loading = null;
+                const message = cause instanceof Error ? cause.message : String(cause);
+                throw new DecisionConfigError(
+                    `laya core 'mlx-native' failed to load '${this.target}': ${message}`,
+                    'LAYA_CORE',
+                    { cause },
+                );
+            },
+        );
+        return this.loading;
+    }
+}

package/src/worker-client.ts

@@ -20,7 +20,14 @@ import {
     DecisionRequestError,
     DecisionTimeoutError,
 } from '@gobing-ai/ts-ai-runner';
-import { joinPath, nodeBunFactory, type PipeProcess, type ProcessExecutor } from '@gobing-ai/ts-runtime';
+import {
+    type FileSystem,
+    getHomeDir,
+    joinPath,
+    nodeBunFactory,
+    type PipeProcess,
+    type ProcessExecutor,
+} from '@gobing-ai/ts-runtime';
 
 /** Environment keys this package may pass to the child process — the full allowlist. */
 const FORWARDED_ENV_KEYS = ['LAYA_MODEL_ID', 'LAYA_MODEL_PATH', 'LAYA_CACHE_DIR', 'LAYA_PYTHON', 'HF_TOKEN'] as const;
@@ -124,7 +131,11 @@ export function validateHostPrerequisites(platform: string = process.platform, a
     }
 }
 
-function hasNonFiniteValues(obj: unknown): boolean {
+/** Official Laya checkpoint used when no modelId/modelPath is configured. */
+export const DEFAULT_LAYA_MODEL_ID = 'convaiinnovations/laya-multilingual';
+
+/** @internal True when any number nested in `obj` is NaN/Infinity (fp16 overflow). */
+export function hasNonFiniteValues(obj: unknown): boolean {
     if (typeof obj === 'number') {
         return !Number.isFinite(obj);
     }
@@ -452,6 +463,33 @@ class WorkerHandle {
     }
 }
 
+/** Resolve the Python interpreter to execute: explicit option -> injected env -> candidate discovery -> 'python3'. */
+export function resolvePythonPath(
+    options: LayaWorkerClientOptions,
+    packageRoot: string,
+    cwd: string,
+    fileSystem: FileSystem = nodeBunFactory.createFileSystem(),
+): string {
+    if (options.pythonPath !== undefined) return options.pythonPath;
+    if (options.env?.LAYA_PYTHON !== undefined && options.env.LAYA_PYTHON.length > 0) {
+        return options.env.LAYA_PYTHON;
+    }
+    const home = getHomeDir();
+    const candidates = [
+        home ? joinPath(home, '.local', 'share', 'uv', 'tools', 'laya-mlx', 'bin', 'python') : undefined,
+        home ? joinPath(home, '.virtualenvs', 'laya-mlx', 'bin', 'python') : undefined,
+        joinPath(packageRoot, '..', '..', 'vendors', 'laya-mlx', '.venv', 'bin', 'python'),
+        joinPath(cwd, '.venv', 'bin', 'python'),
+    ].filter((p): p is string => p !== undefined);
+
+    for (const candidate of candidates) {
+        if (fileSystem.exists(candidate)) {
+            return candidate;
+        }
+    }
+    return 'python3';
+}
+
 /**
  * TypeScript half of the laya process bridge: start the Python worker lazily,
  * hold it warm for the client's lifetime, and serve serialized asks with
@@ -475,8 +513,8 @@ export class LayaWorkerClient {
     ) {
         validateHostPrerequisites(options.platform, options.arch);
         const packageRoot = joinPath(import.meta.dir, '..');
-        this.pythonPath = options.pythonPath ?? options.env?.LAYA_PYTHON ?? 'python3';
         this.cwd = options.cwd ?? packageRoot;
+        this.pythonPath = resolvePythonPath(options, packageRoot, this.cwd);
         this.startupTimeoutMs = options.startupTimeoutMs ?? 120_000;
         this.requestTimeoutMs = options.requestTimeoutMs ?? 30_000;
         this.forwardedEnv = resolveForwardedEnv(options.env);
@@ -485,7 +523,7 @@ export class LayaWorkerClient {
         this.args.push('--module', options.module ?? 'laya_mlx');
         const resolvedModelPath = options.modelPath ?? options.env?.LAYA_MODEL_PATH;
         const resolvedCacheDir = options.cacheDir ?? options.env?.LAYA_CACHE_DIR;
-        const resolvedModelId = options.modelId ?? options.env?.LAYA_MODEL_ID ?? 'convaiinnovations/laya-multilingual';
+        const resolvedModelId = options.modelId ?? options.env?.LAYA_MODEL_ID ?? DEFAULT_LAYA_MODEL_ID;
 
         if (resolvedModelPath !== undefined) {
             this.args.push('--model-path', resolvedModelPath);

package/worker/laya_worker.py

@@ -153,8 +153,19 @@ def handle_request(agent, line):
     if not isinstance(questions, dict) or not questions:
         return request_error(request_id, "request questions must be a nonempty object")
 
+    # For choice questions, ensure compatibility with laya_mlx >= 0.4.0 where
+    # 'labels' is rejected if present alongside 'criteria'.
+    sanitized_questions = {}
+    for qid, qdef in questions.items():
+        if isinstance(qdef, dict) and qdef.get("type") == "choice" and "labels" in qdef:
+            q_copy = dict(qdef)
+            q_copy.pop("labels", None)
+            sanitized_questions[qid] = q_copy
+        else:
+            sanitized_questions[qid] = qdef
+
     try:
-        result = agent.predict(state, questions)
+        result = agent.predict(state, sanitized_questions)
     except Exception as exc:  # classified and reported, never fatal to the worker
         return {"id": request_id, "ok": False, "error": {"kind": classify(exc), "message": str(exc)}}
     return {"id": request_id, "ok": True, "result": result}