@qvac/harness 0.2.12 → 0.3.0

package/dist-lib/lib/tools/generate-image.js

@@ -1,6 +1,7 @@
 import ScopeLock from 'scope-lock';
 import { AbortedError, raceAbort } from '../helpers/race-abort.js';
 import { DIFFUSION_CATALOG, imageModelFor } from '../models/model-catalog.js';
+import { createLoadStall } from '../helpers/load-stall.js';
 import { createLoadTracker } from '../models/model-pool.js';
 import { resolveModelSrc } from '../models/model-source.js';
 export const MAX_DIM = 1024;
@@ -36,30 +37,6 @@ function diffusionProgressName(set) {
     return entry?.name ?? set.model;
 }
 export const IMAGE_LOAD_STALL_ERROR = 'image model download stalled';
-function createLoadStall(ms) {
-    let timer = null;
-    let rejectStall = null;
-    const promise = new Promise((_, reject) => {
-        rejectStall = reject;
-    });
-    const arm = () => {
-        if (timer !== null)
-            clearTimeout(timer);
-        timer = setTimeout(() => {
-            rejectStall?.(new Error(IMAGE_LOAD_STALL_ERROR));
-        }, ms);
-    };
-    arm();
-    return {
-        bump: arm,
-        clear: () => {
-            if (timer !== null)
-                clearTimeout(timer);
-            timer = null;
-        },
-        promise
-    };
-}
 export function createDiffusionRuntime({ loadSdk, onProgress, onLoaded, onBeforeLoad, loads = createLoadTracker(), stallMs = IMAGE_LOAD_STALL_MS, ...base }) {
     let loading = null;
     let residentFingerprint = null;
@@ -116,7 +93,7 @@ export function createDiffusionRuntime({ loadSdk, onProgress, onLoaded, onBefore
                         config.vaeModelSrc = await resolveModelSrc(sdk, set.vaeModel, 'diffusion');
                     }
                     const modelConfig = Object.keys(config).length ? config : undefined;
-                    const stall = createLoadStall(stallMs);
+                    const stall = createLoadStall(stallMs, IMAGE_LOAD_STALL_ERROR);
                     const pending = sdk.loadModel({
                         modelSrc,
                         modelType: 'diffusion',

package/dist-lib/lib/tools/translate.d.ts

@@ -0,0 +1,78 @@
+import type { AbortSignal as BareAbortSignal } from 'bare-abort-controller';
+import type { ToolDefinition } from '../capabilities/completion.ts';
+import type { ModelSrc } from '../models/context.ts';
+import { type NmtPlan } from '../models/nmt-catalog.ts';
+import { type LoadTracker, type TrackedLoad } from '../models/model-pool.ts';
+import { type ModelRegistrySdk } from '../models/model-source.ts';
+interface BergamotConfig {
+    engine: 'Bergamot';
+    from: string;
+    to: string;
+    pivotModel?: {
+        modelSrc: ModelSrc;
+    };
+    srcVocabSrc?: string;
+    dstVocabSrc?: string;
+}
+export type TranslationSdk = ModelRegistrySdk & {
+    loadModel(params: {
+        modelSrc: ModelSrc;
+        modelType: 'nmtcpp-translation';
+        modelConfig: BergamotConfig;
+        onProgress?: (progress: Record<string, unknown>) => void;
+    }): TrackedLoad;
+    unloadModel(params: {
+        modelId: string;
+    }): Promise<unknown>;
+    cancel?(params: {
+        requestId: string;
+    }): Promise<void>;
+    translate(params: {
+        modelId: string;
+        text: string;
+        stream: false;
+        modelType: 'nmt';
+    }): {
+        text: Promise<string>;
+    };
+};
+export declare const TRANSLATION_LOAD_STALL_MS: number;
+export declare const TRANSLATION_LOAD_STALL_ERROR = "translation model download stalled";
+export interface TranslationRuntimeOptions {
+    loadSdk: () => Promise<TranslationSdk>;
+    loads?: LoadTracker;
+    onProgress?: (model: string, progress: Record<string, unknown>) => void;
+    stallMs?: number;
+}
+export interface TranslationRuntime {
+    loadSdk: () => Promise<TranslationSdk>;
+    ensureLoaded: (sdk: TranslationSdk, plan: NmtPlan, signal?: BareAbortSignal) => Promise<{
+        modelId: string;
+    }>;
+    unload: () => Promise<void>;
+    enter: (signal?: BareAbortSignal) => Promise<void>;
+    exit: () => void;
+}
+export declare function createTranslationRuntime({ loadSdk, loads, onProgress, stallMs }: TranslationRuntimeOptions): TranslationRuntime;
+export type SlmTranslateFn = (model: string, params: {
+    text: string;
+    from: string;
+    to: string;
+}, signal?: BareAbortSignal) => Promise<string>;
+export declare function stripLanguageLabel(text: string, ...codes: string[]): string;
+export interface TranslateArgs {
+    text: string;
+    to: string;
+    from?: string;
+}
+export declare function parseTranslateArgs(args: Record<string, unknown>): TranslateArgs | {
+    error: string;
+};
+export declare function sourceLanguage(text: string, from?: string): string | {
+    error: string;
+};
+export interface TranslateToolOptions {
+    slm?: SlmTranslateFn;
+}
+export declare function createTranslateTool(runtime: TranslationRuntime, { slm }?: TranslateToolOptions): ToolDefinition;
+export {};

package/dist-lib/lib/tools/translate.js

@@ -0,0 +1,228 @@
+import ScopeLock from 'scope-lock';
+import { getLangName } from '@qvac/langdetect-text';
+import { detectLanguage, UNDETERMINED } from '../capabilities/detect-language.js';
+import { AbortedError, raceAbort } from '../helpers/race-abort.js';
+import { ENGLISH, NMT_FROM_ENGLISH, NMT_TO_ENGLISH, languageLabel, SLM_LANGUAGE_CODES, sameLanguage, translationPlanFor } from '../models/nmt-catalog.js';
+import { createLoadStall } from '../helpers/load-stall.js';
+import { createLoadTracker } from '../models/model-pool.js';
+import { resolveModelSrc } from '../models/model-source.js';
+export const TRANSLATION_LOAD_STALL_MS = 15 * 60_000;
+export const TRANSLATION_LOAD_STALL_ERROR = 'translation model download stalled';
+function packName(plan) {
+    const pair = plan.model.match(/model\.([a-z]+)\.intgemm/)?.[1];
+    if (pair)
+        return `Bergamot ${pair}`;
+    return plan.model.includes('/en-xx/') ? 'EuroNano en-xx' : 'EuroNano xx-en';
+}
+const fingerprintOf = (plan) => `${plan.model}|${plan.pivot ?? ''}`;
+function bergamotConfig(plan) {
+    const config = { engine: 'Bergamot', from: plan.from, to: plan.to };
+    if (plan.srcVocab)
+        config.srcVocabSrc = plan.srcVocab;
+    if (plan.dstVocab)
+        config.dstVocabSrc = plan.dstVocab;
+    return config;
+}
+export function createTranslationRuntime({ loadSdk, loads = createLoadTracker(), onProgress, stallMs = TRANSLATION_LOAD_STALL_MS }) {
+    let loading = null;
+    let residentFingerprint = null;
+    const lock = new ScopeLock();
+    const turn = new ScopeLock();
+    const loadPack = async (sdk, plan) => {
+        const modelSrc = await resolveModelSrc(sdk, plan.model, 'nmt');
+        const modelConfig = bergamotConfig(plan);
+        if (plan.pivot) {
+            modelConfig.pivotModel = { modelSrc: await resolveModelSrc(sdk, plan.pivot, 'nmt') };
+        }
+        const name = packName(plan);
+        const stall = createLoadStall(stallMs, TRANSLATION_LOAD_STALL_ERROR);
+        onProgress?.(name, {});
+        const pending = sdk.loadModel({
+            modelSrc,
+            modelType: 'nmtcpp-translation',
+            modelConfig,
+            onProgress: (progress) => {
+                stall.bump();
+                onProgress?.(name, progress);
+            }
+        });
+        try {
+            const modelId = await Promise.race([loads.track(pending), stall.promise]);
+            return { modelId };
+        }
+        catch (err) {
+            if (err instanceof Error &&
+                err.message === TRANSLATION_LOAD_STALL_ERROR &&
+                pending.requestId) {
+                void sdk.cancel?.({ requestId: pending.requestId }).catch(() => { });
+            }
+            throw err;
+        }
+        finally {
+            stall.clear();
+        }
+    };
+    const doUnload = async () => {
+        const pending = loading;
+        if (!pending) {
+            residentFingerprint = null;
+            return;
+        }
+        const loaded = await pending.catch(() => null);
+        if (!loaded) {
+            loading = null;
+            residentFingerprint = null;
+            return;
+        }
+        const sdk = await loadSdk();
+        await sdk.unloadModel({ modelId: loaded.modelId });
+        loading = null;
+        residentFingerprint = null;
+    };
+    const unload = async () => {
+        await lock.lock();
+        try {
+            await doUnload();
+        }
+        finally {
+            lock.unlock();
+        }
+    };
+    return {
+        loadSdk,
+        ensureLoaded: async (sdk, plan, signal) => {
+            const fingerprint = fingerprintOf(plan);
+            await lock.lock();
+            try {
+                if (loading && residentFingerprint !== fingerprint)
+                    await doUnload();
+                residentFingerprint = fingerprint;
+                loading ??= loadPack(sdk, plan).catch((err) => {
+                    loading = null;
+                    residentFingerprint = null;
+                    throw err;
+                });
+            }
+            finally {
+                lock.unlock();
+            }
+            return raceAbort(loading, signal);
+        },
+        unload,
+        enter: async (signal) => {
+            const pending = turn.lock();
+            try {
+                await raceAbort(pending, signal);
+            }
+            catch (err) {
+                void pending.then(() => turn.unlock());
+                throw err;
+            }
+        },
+        exit: () => turn.unlock()
+    };
+}
+export function stripLanguageLabel(text, ...codes) {
+    const at = text.indexOf(':');
+    if (at === -1)
+        return text;
+    const head = text.slice(0, at).trim();
+    const labels = codes.map((code) => languageLabel(code) ?? getLangName(code));
+    return labels.includes(head) ? text.slice(at + 1).trim() : text;
+}
+export function parseTranslateArgs(args) {
+    const text = typeof args.text === 'string' ? args.text.trim() : '';
+    if (!text)
+        return { error: 'text must be a non-empty string' };
+    const to = typeof args.to === 'string' ? args.to.trim() : '';
+    if (!to)
+        return { error: 'to must be a language code' };
+    const from = typeof args.from === 'string' ? args.from.trim() : undefined;
+    return { text, to, from };
+}
+export function sourceLanguage(text, from) {
+    if (from)
+        return from;
+    const [{ code }] = detectLanguage({ text });
+    if (code === UNDETERMINED)
+        return { error: NEEDS_SOURCE };
+    return code;
+}
+const NEEDS_SOURCE = 'could not detect the source language; pass `from` explicitly';
+export function createTranslateTool(runtime, { slm } = {}) {
+    return {
+        name: 'translate',
+        toolset: null,
+        description: 'Translate text between languages using the local neural translation models. ' +
+            `\`to\` and \`from\` are ISO 639-1 codes. Translating into ${ENGLISH} supports ` +
+            `${NMT_TO_ENGLISH.length} languages and out of it ${NMT_FROM_ENGLISH.length}; a pair ` +
+            'with English on neither side is translated through English, except between the ' +
+            'languages below. ' +
+            `${SLM_LANGUAGE_CODES.length} further languages, mostly African, may also be named by ` +
+            'their FLORES-200 code and always need an explicit `from`, which the detector cannot ' +
+            'name. Elsewhere `from` is detected from the text when omitted; pass it when known.',
+        parameters: {
+            type: 'object',
+            properties: {
+                text: { type: 'string', description: 'The text to translate' },
+                to: {
+                    type: 'string',
+                    description: 'Target language as an ISO 639-1 code, e.g. `es`, or a FLORES-200 code'
+                },
+                from: {
+                    type: 'string',
+                    description: 'Source language as an ISO 639-1 or FLORES-200 code; detected from the text when omitted'
+                }
+            },
+            required: ['text', 'to']
+        },
+        effect: () => 'read',
+        resource: (args) => ({ kind: 'translation', label: String(args.to ?? '') }),
+        execute: async (args, ctx) => {
+            const parsed = parseTranslateArgs(args);
+            if ('error' in parsed)
+                return parsed;
+            const from = sourceLanguage(parsed.text, parsed.from);
+            if (typeof from === 'object')
+                return from;
+            if (sameLanguage(from, parsed.to)) {
+                return { text: parsed.text, from, to: parsed.to, engine: 'none' };
+            }
+            const plan = translationPlanFor(from, parsed.to);
+            if ('error' in plan)
+                return plan;
+            if (plan.route === 'slm' && !slm) {
+                return { error: `this device cannot translate ${from} to ${parsed.to}` };
+            }
+            let entered = false;
+            try {
+                await runtime.enter(ctx?.signal);
+                entered = true;
+                if (plan.route === 'slm') {
+                    const text = await slm(plan.model, { text: parsed.text, from: plan.from, to: plan.to }, ctx?.signal);
+                    return {
+                        text: stripLanguageLabel(text, plan.from, plan.to),
+                        from,
+                        to: parsed.to,
+                        engine: 'slm',
+                        model: plan.model
+                    };
+                }
+                const sdk = await runtime.loadSdk();
+                const { modelId } = await runtime.ensureLoaded(sdk, plan, ctx?.signal);
+                const source = plan.tag ? `${plan.tag} ${parsed.text}` : parsed.text;
+                const text = await raceAbort(sdk.translate({ modelId, text: source, stream: false, modelType: 'nmt' }).text, ctx?.signal);
+                return { text, from, to: parsed.to, engine: 'nmt', pivoted: Boolean(plan.pivot) };
+            }
+            catch (err) {
+                if (err instanceof AbortedError)
+                    return { error: 'translation canceled' };
+                throw err;
+            }
+            finally {
+                if (entered)
+                    runtime.exit();
+            }
+        }
+    };
+}

package/dist-lib/schema/harness.js

@@ -112,7 +112,8 @@ export function registerHarnessTypes(ns) {
             { name: 'grantedWriteDirs', type: 'string', array: true },
             { name: 'captureInferenceCalls', type: 'bool' },
             { name: 'capability', type: 'string' },
-            { name: 'arguments', type: 'json' }
+            { name: 'arguments', type: 'json' },
+            { name: 'enhance', type: 'string' }
         ]
     });
     ns.register({

package/dist-lib/spec/hrpc/messages.js

@@ -1,12 +1,12 @@
 // This file is autogenerated by the hyperschema compiler
-// Schema Version: 11
+// Schema Version: 12
 /* eslint-disable camelcase */
 /* eslint-disable quotes */
 /* eslint-disable space-before-function-paren */
 
 import { c } from 'hyperschema/runtime'
 
-const VERSION = 11
+const VERSION = 12
 
 // eslint-disable-next-line no-unused-vars
 let version = VERSION
@@ -490,7 +490,8 @@ const encoding11 = {
       ((version >= 5 && m.grantedWriteDirs) ? 16777216 : 0) |
       ((version >= 9 && m.captureInferenceCalls) ? 33554432 : 0) |
       ((version >= 11 && m.capability) ? 67108864 : 0) |
-      ((version >= 11 && m.arguments) ? 134217728 : 0)
+      ((version >= 11 && m.arguments) ? 134217728 : 0) |
+      ((version >= 12 && m.enhance) ? 268435456 : 0)
 
     encoding10.preencode(state, m.type)
     c.uint.preencode(state, flags)
@@ -520,6 +521,7 @@ const encoding11 = {
     if (version >= 5 && m.grantedWriteDirs) encoding11_25.preencode(state, m.grantedWriteDirs)
     if (version >= 11 && m.capability) c.string.preencode(state, m.capability)
     if (version >= 11 && m.arguments) c.json.preencode(state, m.arguments)
+    if (version >= 12 && m.enhance) c.string.preencode(state, m.enhance)
   },
   encode(state, m) {
     const flags =
@@ -550,7 +552,8 @@ const encoding11 = {
       ((version >= 5 && m.grantedWriteDirs) ? 16777216 : 0) |
       ((version >= 9 && m.captureInferenceCalls) ? 33554432 : 0) |
       ((version >= 11 && m.capability) ? 67108864 : 0) |
-      ((version >= 11 && m.arguments) ? 134217728 : 0)
+      ((version >= 11 && m.arguments) ? 134217728 : 0) |
+      ((version >= 12 && m.enhance) ? 268435456 : 0)
 
     encoding10.encode(state, m.type)
     c.uint.encode(state, flags)
@@ -580,6 +583,7 @@ const encoding11 = {
     if (version >= 5 && m.grantedWriteDirs) encoding11_25.encode(state, m.grantedWriteDirs)
     if (version >= 11 && m.capability) c.string.encode(state, m.capability)
     if (version >= 11 && m.arguments) c.json.encode(state, m.arguments)
+    if (version >= 12 && m.enhance) c.string.encode(state, m.enhance)
   },
   decode(state) {
     const r0 = encoding10.decode(state)
@@ -614,7 +618,8 @@ const encoding11 = {
       grantedWriteDirs: (version >= 5 && (flags & 16777216) !== 0) ? encoding11_25.decode(state) : null,
       captureInferenceCalls: (version >= 9 && (flags & 33554432) !== 0),
       capability: (version >= 11 && (flags & 67108864) !== 0) ? c.string.decode(state) : null,
-      arguments: (version >= 11 && (flags & 134217728) !== 0) ? c.json.decode(state) : null
+      arguments: (version >= 11 && (flags & 134217728) !== 0) ? c.json.decode(state) : null,
+      enhance: (version >= 12 && (flags & 268435456) !== 0) ? c.string.decode(state) : null
     }
   }
 }

package/dist-lib/spec/hyperschema/index.js

@@ -1,12 +1,12 @@
 // This file is autogenerated by the hyperschema compiler
-// Schema Version: 11
+// Schema Version: 12
 /* eslint-disable camelcase */
 /* eslint-disable quotes */
 /* eslint-disable space-before-function-paren */
 
 import { c } from 'hyperschema/runtime'
 
-const VERSION = 11
+const VERSION = 12
 
 // eslint-disable-next-line no-unused-vars
 let version = VERSION
@@ -490,7 +490,8 @@ const encoding11 = {
       ((version >= 5 && m.grantedWriteDirs) ? 16777216 : 0) |
       ((version >= 9 && m.captureInferenceCalls) ? 33554432 : 0) |
       ((version >= 11 && m.capability) ? 67108864 : 0) |
-      ((version >= 11 && m.arguments) ? 134217728 : 0)
+      ((version >= 11 && m.arguments) ? 134217728 : 0) |
+      ((version >= 12 && m.enhance) ? 268435456 : 0)
 
     encoding10.preencode(state, m.type)
     c.uint.preencode(state, flags)
@@ -520,6 +521,7 @@ const encoding11 = {
     if (version >= 5 && m.grantedWriteDirs) encoding11_25.preencode(state, m.grantedWriteDirs)
     if (version >= 11 && m.capability) c.string.preencode(state, m.capability)
     if (version >= 11 && m.arguments) c.json.preencode(state, m.arguments)
+    if (version >= 12 && m.enhance) c.string.preencode(state, m.enhance)
   },
   encode(state, m) {
     const flags =
@@ -550,7 +552,8 @@ const encoding11 = {
       ((version >= 5 && m.grantedWriteDirs) ? 16777216 : 0) |
       ((version >= 9 && m.captureInferenceCalls) ? 33554432 : 0) |
       ((version >= 11 && m.capability) ? 67108864 : 0) |
-      ((version >= 11 && m.arguments) ? 134217728 : 0)
+      ((version >= 11 && m.arguments) ? 134217728 : 0) |
+      ((version >= 12 && m.enhance) ? 268435456 : 0)
 
     encoding10.encode(state, m.type)
     c.uint.encode(state, flags)
@@ -580,6 +583,7 @@ const encoding11 = {
     if (version >= 5 && m.grantedWriteDirs) encoding11_25.encode(state, m.grantedWriteDirs)
     if (version >= 11 && m.capability) c.string.encode(state, m.capability)
     if (version >= 11 && m.arguments) c.json.encode(state, m.arguments)
+    if (version >= 12 && m.enhance) c.string.encode(state, m.enhance)
   },
   decode(state) {
     const r0 = encoding10.decode(state)
@@ -614,7 +618,8 @@ const encoding11 = {
       grantedWriteDirs: (version >= 5 && (flags & 16777216) !== 0) ? encoding11_25.decode(state) : null,
       captureInferenceCalls: (version >= 9 && (flags & 33554432) !== 0),
       capability: (version >= 11 && (flags & 67108864) !== 0) ? c.string.decode(state) : null,
-      arguments: (version >= 11 && (flags & 134217728) !== 0) ? c.json.decode(state) : null
+      arguments: (version >= 11 && (flags & 134217728) !== 0) ? c.json.decode(state) : null,
+      enhance: (version >= 12 && (flags & 268435456) !== 0) ? c.string.decode(state) : null
     }
   }
 }

package/dist-lib/spec/hyperschema/schema.json

@@ -1,5 +1,5 @@
 {
-  "version": 11,
+  "version": 12,
   "schema": [
     {
       "name": "empty",
@@ -470,6 +470,11 @@
           "name": "arguments",
           "type": "json",
           "version": 11
+        },
+        {
+          "name": "enhance",
+          "type": "string",
+          "version": 12
         }
       ]
     },

package/dist-lib/spec/hyperschema/types.d.ts

@@ -1,5 +1,5 @@
 // This file is autogenerated by hyperschema-ts
-// Schema version: 11
+// Schema version: 12
 // Do not edit manually.
 
 export interface HarnessEmpty {
@@ -90,6 +90,7 @@ export interface HarnessCompletionFrame {
   captureInferenceCalls?: boolean
   capability?: string | null
   arguments?: unknown | null
+  enhance?: string | null
 }
 
 export type HarnessCompletionEventType = "content" | "thinking" | "tool-call" | "tool-result" | "approval-ask" | "metrics" | "error" | "aborted" | "attach-ask" | "fetch-ask" | "progress" | "rag-ask" | "question-ask" | "done" | "tool-activity" | "drive-ask" | "inference-call" | "inference-sent"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qvac/harness",
-  "version": "0.2.12",
+  "version": "0.3.0",
   "type": "module",
   "description": "An AI harness implementing generate(context) via @qvac/sdk. Knows nothing about workbench, hyperdb, or chunks — just inference in, events out.",
   "exports": {
@@ -540,6 +540,10 @@
       "types": "./dist-lib/lib/tools/skills/tool-grants.d.ts",
       "default": "./dist-lib/lib/tools/skills/tool-grants.js"
     },
+    "./lib/tools/translate.ts": {
+      "types": "./dist-lib/lib/tools/translate.d.ts",
+      "default": "./dist-lib/lib/tools/translate.js"
+    },
     "./lib/tools/url-guard.ts": {
       "types": "./dist-lib/lib/tools/url-guard.d.ts",
       "default": "./dist-lib/lib/tools/url-guard.js"
@@ -565,6 +569,7 @@
     "lint": "prettier . --check && lunte && tsc --noEmit",
     "build:bundle": "node scripts/build-bundle.mjs",
     "skill-eval": "bare examples/skill-eval/run.ts",
+    "translate-eval": "bare examples/translate-eval/run.ts",
     "prepack": "node scripts/vendor-python-wheels.mjs && node scripts/build-lib.mjs && node scripts/build-bundle.mjs --minify",
     "vendor:wheels": "node scripts/vendor-python-wheels.mjs",
     "build:lib": "node scripts/build-lib.mjs",