@marinoscar/kvox-eval 0.0.0-bootstrap → 0.1.0-next.0

package/dist/live/adapters.js

@@ -0,0 +1,58 @@
+"use strict";
+// =============================================================================
+// The provider adapters a live run calls (issue #580)
+// =============================================================================
+//
+// The OpenAI and OpenAI-compatible adapters are the platform's
+// (`@marinoscar/platform-api/ai`). Its public entry exports their Nest MODULES
+// (`OpenAiProviderModule`, `OpenAiCompatibleProviderModule`), not the adapter
+// classes, so the adapter is read off the module's own `exports` metadata and
+// constructed by hand over a fresh `AiProviderRegistry` and the module's client
+// factory (no Nest application is booted: the adapter registers itself only in
+// `onModuleInit`, which is never called here).
+//
+// PLATFORM-ADOPTION-SHIM(#578): until the lean provider-adapter package exports
+// the adapter classes (or factories), at which point this file becomes two
+// `new` expressions.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.platformAdapter = platformAdapter;
+/** The platform module that carries each provider's adapter. */
+const ADAPTER_MODULES = {
+    openai: 'OpenAiProviderModule',
+    'openai-compatible': 'OpenAiCompatibleProviderModule',
+};
+/** `Reflect.getMetadata`, installed by `reflect-metadata` (the platform's Nest import loads it). */
+function metadata(key, target) {
+    const reflect = Reflect;
+    if (typeof reflect.getMetadata !== 'function')
+        throw new Error('reflect-metadata is not loaded');
+    return reflect.getMetadata(key, target);
+}
+/**
+ * The platform's adapter for a provider, constructed outside Nest.
+ *
+ * @param provider - `openai` or `openai-compatible`.
+ * @returns the adapter (`responses`, `embeddings`, ...).
+ * @throws Error when the installed platform no longer carries the adapter where this shim looks.
+ * @stability experimental
+ */
+function platformAdapter(provider) {
+    // Required lazily: the platform's AI entry loads Nest and the OpenAI SDK, which a
+    // scoring run (gold, a predictions directory) has no reason to load.
+    const ai = require('@marinoscar/platform-api/ai');
+    const moduleClass = ai[ADAPTER_MODULES[provider]];
+    if (moduleClass === undefined)
+        throw new Error(`@marinoscar/platform-api/ai has no ${ADAPTER_MODULES[provider]}`);
+    const exported = metadata('exports', moduleClass) ?? [];
+    const providers = metadata('providers', moduleClass) ?? [];
+    const Adapter = exported.find((c) => typeof c === 'function');
+    const Factory = providers.find((c) => typeof c === 'function' && c !== Adapter);
+    if (Adapter === undefined || Factory === undefined) {
+        throw new Error(`${ADAPTER_MODULES[provider]} does not carry an adapter and a client factory`);
+    }
+    const adapter = new Adapter(new ai.AiProviderRegistry(), new Factory());
+    if (adapter.id !== provider)
+        throw new Error(`${ADAPTER_MODULES[provider]} built '${adapter.id}', expected '${provider}'`);
+    return adapter;
+}

package/dist/live/env.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The environment variable a live run reads its API key from — never a flag.
+ *
+ * @stability experimental
+ */
+export declare const KVOX_EVAL_API_KEY_ENV = "KVOX_EVAL_OPENAI_API_KEY";
+/**
+ * The former names of {@link KVOX_EVAL_API_KEY_ENV}, read for one release with a
+ * deprecation note.
+ *
+ * @stability deprecated
+ */
+export declare const DEPRECATED_EVAL_API_KEY_ENVS: readonly string[];
+/**
+ * Where a key was found.
+ *
+ * @stability experimental
+ */
+export interface EvalApiKey {
+    /** The key. ⚠ Secret: hand it to the runtime, never print it. */
+    apiKey: string;
+    /** The variable it was read from (safe to print). */
+    source: string;
+}
+/**
+ * The live run's API key from the environment, or `null` when none is set.
+ *
+ * @example
+ * ```ts
+ * const key = readEvalApiKey(process.env, (line) => process.stderr.write(`${line}\n`));
+ * if (key === null) throw new Error(`set ${KVOX_EVAL_API_KEY_ENV}`);
+ * ```
+ *
+ * @param env - the environment to read (`process.env`, or a test's own).
+ * @param warn - receives the one-line deprecation note when an old name supplied the key.
+ * @returns the key and the variable it came from, or `null`.
+ * @stability experimental
+ */
+export declare function readEvalApiKey(env: Readonly<Record<string, string | undefined>>, warn?: (line: string) => void): EvalApiKey | null;

package/dist/live/env.js

@@ -0,0 +1,56 @@
+"use strict";
+// =============================================================================
+// Where a live evaluation's API key comes from (issue #580)
+// =============================================================================
+//
+// ONE environment variable, `KVOX_EVAL_OPENAI_API_KEY`, for every live run (kg
+// and Ask). The two names it replaces, `KG_EVAL_OPENAI_API_KEY` (#475) and
+// `ASK_EVAL_OPENAI_API_KEY` (#382), are still read for one release, with a
+// one-line deprecation note naming the variable — never its value.
+//
+// ⚠ The key is never a flag, never printed, never written into a report, a
+// prediction or an error message. An empty variable counts as unset.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEPRECATED_EVAL_API_KEY_ENVS = exports.KVOX_EVAL_API_KEY_ENV = void 0;
+exports.readEvalApiKey = readEvalApiKey;
+/**
+ * The environment variable a live run reads its API key from — never a flag.
+ *
+ * @stability experimental
+ */
+exports.KVOX_EVAL_API_KEY_ENV = 'KVOX_EVAL_OPENAI_API_KEY';
+/**
+ * The former names of {@link KVOX_EVAL_API_KEY_ENV}, read for one release with a
+ * deprecation note.
+ *
+ * @stability deprecated
+ */
+exports.DEPRECATED_EVAL_API_KEY_ENVS = Object.freeze(['KG_EVAL_OPENAI_API_KEY', 'ASK_EVAL_OPENAI_API_KEY']);
+/**
+ * The live run's API key from the environment, or `null` when none is set.
+ *
+ * @example
+ * ```ts
+ * const key = readEvalApiKey(process.env, (line) => process.stderr.write(`${line}\n`));
+ * if (key === null) throw new Error(`set ${KVOX_EVAL_API_KEY_ENV}`);
+ * ```
+ *
+ * @param env - the environment to read (`process.env`, or a test's own).
+ * @param warn - receives the one-line deprecation note when an old name supplied the key.
+ * @returns the key and the variable it came from, or `null`.
+ * @stability experimental
+ */
+function readEvalApiKey(env, warn) {
+    const primary = env[exports.KVOX_EVAL_API_KEY_ENV];
+    if (primary)
+        return { apiKey: primary, source: exports.KVOX_EVAL_API_KEY_ENV };
+    for (const name of exports.DEPRECATED_EVAL_API_KEY_ENVS) {
+        const value = env[name];
+        if (value) {
+            warn?.(`kvox-eval: ${name} is deprecated and will stop being read in the next release; set ${exports.KVOX_EVAL_API_KEY_ENV} instead`);
+            return { apiKey: value, source: name };
+        }
+    }
+    return null;
+}

package/dist/live/index.d.ts

@@ -0,0 +1,6 @@
+export { platformAdapter } from './adapters.js';
+export type { PlatformAdapterProvider } from './adapters.js';
+export { DEPRECATED_EVAL_API_KEY_ENVS, KVOX_EVAL_API_KEY_ENV, readEvalApiKey } from './env.js';
+export type { EvalApiKey } from './env.js';
+export { assertLiveProvider, createLiveKvoxAi, LIVE_PROVIDERS, LiveProviderError, staticTaskModelSource } from './live-ai.js';
+export type { CreateLiveKvoxAiOptions, LiveCallFailure, LiveKvoxAi, LiveProvider } from './live-ai.js';

package/dist/live/index.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.staticTaskModelSource = exports.LiveProviderError = exports.LIVE_PROVIDERS = exports.createLiveKvoxAi = exports.assertLiveProvider = exports.readEvalApiKey = exports.KVOX_EVAL_API_KEY_ENV = exports.DEPRECATED_EVAL_API_KEY_ENVS = exports.platformAdapter = void 0;
+// The live slice's public surface (re-exported by the package root).
+var adapters_js_1 = require("./adapters.js");
+Object.defineProperty(exports, "platformAdapter", { enumerable: true, get: function () { return adapters_js_1.platformAdapter; } });
+var env_js_1 = require("./env.js");
+Object.defineProperty(exports, "DEPRECATED_EVAL_API_KEY_ENVS", { enumerable: true, get: function () { return env_js_1.DEPRECATED_EVAL_API_KEY_ENVS; } });
+Object.defineProperty(exports, "KVOX_EVAL_API_KEY_ENV", { enumerable: true, get: function () { return env_js_1.KVOX_EVAL_API_KEY_ENV; } });
+Object.defineProperty(exports, "readEvalApiKey", { enumerable: true, get: function () { return env_js_1.readEvalApiKey; } });
+var live_ai_js_1 = require("./live-ai.js");
+Object.defineProperty(exports, "assertLiveProvider", { enumerable: true, get: function () { return live_ai_js_1.assertLiveProvider; } });
+Object.defineProperty(exports, "createLiveKvoxAi", { enumerable: true, get: function () { return live_ai_js_1.createLiveKvoxAi; } });
+Object.defineProperty(exports, "LIVE_PROVIDERS", { enumerable: true, get: function () { return live_ai_js_1.LIVE_PROVIDERS; } });
+Object.defineProperty(exports, "LiveProviderError", { enumerable: true, get: function () { return live_ai_js_1.LiveProviderError; } });
+Object.defineProperty(exports, "staticTaskModelSource", { enumerable: true, get: function () { return live_ai_js_1.staticTaskModelSource; } });

package/dist/live/live-ai.d.ts

@@ -0,0 +1,104 @@
+import { type KvoxTaskModelSource } from '@marinoscar/kvox-ai';
+import type { KvoxAiPort } from '@marinoscar/kvox-api/ports';
+import type { AiProviderAdapter } from '@marinoscar/platform-api/ai';
+import { type PlatformAdapterProvider } from './adapters.js';
+/**
+ * The providers a live run may name. `copilot` is listed so it can be refused
+ * with a reason (its adapter arrives with #581).
+ *
+ * @stability experimental
+ */
+export declare const LIVE_PROVIDERS: readonly ["openai", "openai-compatible", "copilot"];
+/**
+ * One of {@link LIVE_PROVIDERS}.
+ *
+ * @stability experimental
+ */
+export type LiveProvider = (typeof LIVE_PROVIDERS)[number];
+/**
+ * A live run that cannot be set up as asked (an unknown or unavailable provider,
+ * a missing base URL or key). The CLI maps it to exit code 2.
+ *
+ * @stability experimental
+ */
+export declare class LiveProviderError extends Error {
+}
+/**
+ * The code and HTTP status of one failed provider round trip: what a report may
+ * say about a failure (never a message body, which could echo a credential).
+ *
+ * @stability experimental
+ */
+export interface LiveCallFailure {
+    /** The platform's error code (`AI_KEY_INVALID`, `AI_RATE_LIMITED`, ...), or the error's name. */
+    code: string;
+    /** The HTTP status the code maps to, when the error carries one. */
+    status: number | null;
+}
+/**
+ * What {@link createLiveKvoxAi} is built from.
+ *
+ * @stability experimental
+ */
+export interface CreateLiveKvoxAiOptions {
+    /** The provider every call goes to. */
+    provider: LiveProvider | string;
+    /** The model every call targets (the only enabled model). */
+    model: string;
+    /**
+     * The API key. ⚠ Secret. Required for `openai`; optional for an
+     * `openai-compatible` server that needs none (the platform's keyless marker is sent).
+     */
+    apiKey: string | null;
+    /** The server's API root (`/v1` included). Required for `openai-compatible`; an override for `openai`. */
+    baseUrl?: string;
+    /** The adapters by provider id. Default: the platform's, built by `platformAdapter`. A test passes a fake. */
+    adapters?: Readonly<Record<string, AiProviderAdapter>>;
+}
+/**
+ * The live port plus what the caller may report about its failures.
+ *
+ * @stability experimental
+ */
+export interface LiveKvoxAi {
+    /** The model port (`createKvoxAi` over the direct runtime). */
+    ai: KvoxAiPort;
+    /** Every failed round trip so far, code and status only. */
+    failures: LiveCallFailure[];
+}
+/**
+ * Refuses a provider a live run cannot use today: `copilot` (its adapter arrives
+ * with #581) and any id that is not a {@link LIVE_PROVIDERS} entry.
+ *
+ * @param provider - the provider id a run names.
+ * @throws {@link LiveProviderError} with the reason.
+ * @stability experimental
+ */
+export declare function assertLiveProvider(provider: string): asserts provider is PlatformAdapterProvider;
+/**
+ * The task-model state of a run on one provider and one model: AI on, the graph
+ * switch on, every task on that model, no reasoning parameter (`none`).
+ *
+ * @param provider - the provider id.
+ * @param model - the model id.
+ * @returns a source whose `load()` always answers that state.
+ * @stability experimental
+ */
+export declare function staticTaskModelSource(provider: string, model: string): KvoxTaskModelSource;
+/**
+ * Builds the model port a live evaluation runs on.
+ *
+ * @example
+ * ```ts
+ * const key = readEvalApiKey(process.env);
+ * const { ai } = createLiveKvoxAi({ provider: 'openai', model: 'gpt-5-mini', apiKey: key?.apiKey ?? null });
+ * const report = await runKgEval({ runner: 'extract', ai, model: 'gpt-5-mini' });
+ * ```
+ *
+ * @param options - provider, model, key and (optionally) the adapters.
+ * @returns the port and its failure log.
+ * @throws {@link LiveProviderError} for `copilot`, an unknown provider, an
+ *   `openai` run without a key, or an `openai-compatible` run without a base URL.
+ * @stability experimental
+ */
+export declare function createLiveKvoxAi(options: CreateLiveKvoxAiOptions): LiveKvoxAi;

package/dist/live/live-ai.js

@@ -0,0 +1,157 @@
+"use strict";
+// =============================================================================
+// createLiveKvoxAi: the model port a live evaluation runs on (issue #580)
+// =============================================================================
+//
+// An evaluation is a developer or CI tool: no signed-in user, no organization,
+// no stored key, no platform AI service. So it binds the SAME port every host
+// binds, `createKvoxAi` of `@marinoscar/kvox-ai`, over `createDirectRuntime`
+// (the provider adapters, called directly) and a static task-model source that
+// answers "this provider, this one model". The runners never see more than the
+// port; nothing here is a second implementation of a provider call (#475's
+// private OpenAI client is gone).
+//
+// THE KEY. Handed in by the caller (the CLI reads it with `readEvalApiKey`),
+// given to the direct runtime's `keys()` callback, and from there to one adapter
+// call at a time. It is never logged, never put in an error, never returned.
+// A failed call surfaces as the port's `KvoxAiError` (scrubbed); `failures`
+// records only the platform error CODE and HTTP status of each failed round
+// trip, which is what the CLI prints.
+//
+// `copilot` is refused until the Copilot adapter exists (#581): no installed
+// package carries one today.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LiveProviderError = exports.LIVE_PROVIDERS = void 0;
+exports.assertLiveProvider = assertLiveProvider;
+exports.staticTaskModelSource = staticTaskModelSource;
+exports.createLiveKvoxAi = createLiveKvoxAi;
+const kvox_ai_1 = require("@marinoscar/kvox-ai");
+const adapters_js_1 = require("./adapters.js");
+/**
+ * The providers a live run may name. `copilot` is listed so it can be refused
+ * with a reason (its adapter arrives with #581).
+ *
+ * @stability experimental
+ */
+exports.LIVE_PROVIDERS = Object.freeze(['openai', 'openai-compatible', 'copilot']);
+/**
+ * A live run that cannot be set up as asked (an unknown or unavailable provider,
+ * a missing base URL or key). The CLI maps it to exit code 2.
+ *
+ * @stability experimental
+ */
+class LiveProviderError extends Error {
+}
+exports.LiveProviderError = LiveProviderError;
+/**
+ * Refuses a provider a live run cannot use today: `copilot` (its adapter arrives
+ * with #581) and any id that is not a {@link LIVE_PROVIDERS} entry.
+ *
+ * @param provider - the provider id a run names.
+ * @throws {@link LiveProviderError} with the reason.
+ * @stability experimental
+ */
+function assertLiveProvider(provider) {
+    if (provider === 'copilot') {
+        throw new LiveProviderError("the 'copilot' provider is not available yet: it arrives with the Copilot adapter (#581). Use --provider openai or openai-compatible.");
+    }
+    if (provider !== 'openai' && provider !== 'openai-compatible') {
+        throw new LiveProviderError(`unknown provider '${provider}' (known: ${exports.LIVE_PROVIDERS.join(', ')})`);
+    }
+}
+/**
+ * The task-model state of a run on one provider and one model: AI on, the graph
+ * switch on, every task on that model, no reasoning parameter (`none`).
+ *
+ * @param provider - the provider id.
+ * @param model - the model id.
+ * @returns a source whose `load()` always answers that state.
+ * @stability experimental
+ */
+function staticTaskModelSource(provider, model) {
+    const state = {
+        provider,
+        models: [{ id: model, label: model, structuredOutput: true, toolCalling: true, contextWindow: null, maxOutputTokens: null }],
+        policy: {
+            enabled: true,
+            provider,
+            defaultModel: model,
+            graphEnabled: true,
+            taskModels: {},
+            reasoningEffort: 'none',
+            maxInputTokens: null,
+            maxOutputTokens: null,
+        },
+    };
+    return { load: async () => state };
+}
+/**
+ * Builds the model port a live evaluation runs on.
+ *
+ * @example
+ * ```ts
+ * const key = readEvalApiKey(process.env);
+ * const { ai } = createLiveKvoxAi({ provider: 'openai', model: 'gpt-5-mini', apiKey: key?.apiKey ?? null });
+ * const report = await runKgEval({ runner: 'extract', ai, model: 'gpt-5-mini' });
+ * ```
+ *
+ * @param options - provider, model, key and (optionally) the adapters.
+ * @returns the port and its failure log.
+ * @throws {@link LiveProviderError} for `copilot`, an unknown provider, an
+ *   `openai` run without a key, or an `openai-compatible` run without a base URL.
+ * @stability experimental
+ */
+function createLiveKvoxAi(options) {
+    const { provider, model, apiKey, baseUrl } = options;
+    assertLiveProvider(provider);
+    if (provider === 'openai' && !apiKey)
+        throw new LiveProviderError('the openai provider needs an API key');
+    if (provider === 'openai-compatible' && !baseUrl)
+        throw new LiveProviderError('the openai-compatible provider needs --base-url <url>');
+    if (!model)
+        throw new LiveProviderError('a live run needs a model');
+    const adapters = options.adapters ?? { [provider]: (0, adapters_js_1.platformAdapter)(provider) };
+    // The platform's marker for a keyless OpenAI-compatible server: the client sends no Authorization header.
+    const KEYLESS = 'not-needed';
+    const key = apiKey || KEYLESS;
+    const failures = [];
+    const runtime = recordingFailures((0, kvox_ai_1.createDirectRuntime)({
+        adapters,
+        keys: async (p) => (p === provider ? { apiKey: key, ...(baseUrl ? { baseUrl } : {}) } : null),
+    }), failures);
+    return { ai: (0, kvox_ai_1.createKvoxAi)({ runtime, taskModels: staticTaskModelSource(provider, model) }), failures };
+}
+/** The code and status of a thrown value, never its message. */
+function failureOf(error) {
+    const e = error;
+    const status = typeof e?.getStatus === 'function' ? e.getStatus() : e?.status;
+    return {
+        code: typeof e?.code === 'string' ? e.code : typeof e?.name === 'string' ? e.name : 'Error',
+        status: typeof status === 'number' ? status : null,
+    };
+}
+/** The runtime, with each failed round trip's code and status appended to `failures`. */
+function recordingFailures(runtime, failures) {
+    return {
+        ...runtime,
+        async create(call, req) {
+            try {
+                return await runtime.create(call, req);
+            }
+            catch (error) {
+                failures.push(failureOf(error));
+                throw error;
+            }
+        },
+        async *stream(call, req) {
+            try {
+                yield* runtime.stream(call, req);
+            }
+            catch (error) {
+                failures.push(failureOf(error));
+                throw error;
+            }
+        },
+    };
+}

package/dist/parity/constants.d.ts

@@ -0,0 +1,79 @@
+import type { KvoxAiModelState, KvoxTaskModelSource } from '@marinoscar/kvox-ai';
+/**
+ * The provider both bindings run on.
+ *
+ * @stability experimental
+ */
+export declare const PARITY_PROVIDER = "openai";
+/**
+ * One model of the parity state.
+ *
+ * @stability experimental
+ */
+export interface ParityModel {
+    /** The provider's model id. */
+    id: string;
+    /** The context window in tokens. */
+    contextWindow: number;
+    /** The output ceiling in tokens. */
+    maxOutputTokens: number;
+}
+/**
+ * The enabled models: all structured-output and tool-calling capable.
+ *
+ * @stability experimental
+ */
+export declare const PARITY_MODELS: readonly ParityModel[];
+/**
+ * The deployment's default model and effort (notes generation runs on them).
+ *
+ * @stability experimental
+ */
+export declare const PARITY_DEFAULT_MODEL = "gpt-parity";
+/**
+ * The deployment-wide reasoning effort.
+ *
+ * @stability experimental
+ */
+export declare const PARITY_DEFAULT_EFFORT: "low";
+/**
+ * The per-task models and efforts (`ai.taskModels`).
+ *
+ * @stability experimental
+ */
+export declare const PARITY_TASK_MODELS: Readonly<{
+    readonly 'graph.extract': {
+        readonly model: "gpt-parity-extract";
+        readonly reasoningEffort: "medium";
+    };
+    readonly 'graph.adjudicate': {
+        readonly model: "gpt-parity-adjudicate";
+        readonly reasoningEffort: "high";
+    };
+    readonly 'graph.agent': {
+        readonly model: "gpt-parity-agent";
+        readonly reasoningEffort: "low";
+    };
+}>;
+/**
+ * The user every parity call is made for. Host-specific, never compared.
+ *
+ * @stability experimental
+ */
+export declare const PARITY_USER_ID = "11111111-1111-4111-8111-111111111111";
+/**
+ * The task-model state of a parity run: AI on, the graph switch on, the models above, the tasks above.
+ *
+ * @param provider - the provider id the state names (the active provider and the policy's). Default {@link PARITY_PROVIDER}; `copilot` runs the same scenario over the GitHub Copilot adapter (#581).
+ * @returns a fresh state.
+ * @stability experimental
+ */
+export declare function parityModelState(provider?: string): KvoxAiModelState;
+/**
+ * The same state as a static task-model source, for `createKvoxAi({ taskModels })` of the direct binding.
+ *
+ * @param provider - the provider id the state names. Default {@link PARITY_PROVIDER}.
+ * @returns a source whose `load()` always answers {@link parityModelState}.
+ * @stability experimental
+ */
+export declare function parityTaskModelSource(provider?: string): KvoxTaskModelSource;

package/dist/parity/constants.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PARITY_USER_ID = exports.PARITY_TASK_MODELS = exports.PARITY_DEFAULT_EFFORT = exports.PARITY_DEFAULT_MODEL = exports.PARITY_MODELS = exports.PARITY_PROVIDER = void 0;
+exports.parityModelState = parityModelState;
+exports.parityTaskModelSource = parityTaskModelSource;
+// =============================================================================
+// What both bindings are configured with (issue #580, part 2)
+// =============================================================================
+//
+// The harness-parity check builds the SAME task-model state twice: as a static
+// `KvoxTaskModelSource` for the direct (Desktop-style) binding, and as the web
+// edition's system-settings value plus `ai_models` rows. These constants are the
+// single description both are built from, so a difference between the two
+// bindings' requests can only come from a binding, never from the state.
+//
+// Different tasks run on different models and efforts ON PURPOSE: a binding that
+// ignored `ai.taskModels` (or its per-task effort) would send the default model
+// and fail the comparison.
+// =============================================================================
+/**
+ * The provider both bindings run on.
+ *
+ * @stability experimental
+ */
+exports.PARITY_PROVIDER = 'openai';
+/**
+ * The enabled models: all structured-output and tool-calling capable.
+ *
+ * @stability experimental
+ */
+exports.PARITY_MODELS = Object.freeze([
+    { id: 'gpt-parity', contextWindow: 128_000, maxOutputTokens: 16_000 },
+    { id: 'gpt-parity-extract', contextWindow: 200_000, maxOutputTokens: 32_000 },
+    { id: 'gpt-parity-adjudicate', contextWindow: 64_000, maxOutputTokens: 8_000 },
+    { id: 'gpt-parity-agent', contextWindow: 128_000, maxOutputTokens: 12_000 },
+]);
+/**
+ * The deployment's default model and effort (notes generation runs on them).
+ *
+ * @stability experimental
+ */
+exports.PARITY_DEFAULT_MODEL = 'gpt-parity';
+/**
+ * The deployment-wide reasoning effort.
+ *
+ * @stability experimental
+ */
+exports.PARITY_DEFAULT_EFFORT = 'low';
+/**
+ * The per-task models and efforts (`ai.taskModels`).
+ *
+ * @stability experimental
+ */
+exports.PARITY_TASK_MODELS = Object.freeze({
+    'graph.extract': { model: 'gpt-parity-extract', reasoningEffort: 'medium' },
+    'graph.adjudicate': { model: 'gpt-parity-adjudicate', reasoningEffort: 'high' },
+    'graph.agent': { model: 'gpt-parity-agent', reasoningEffort: 'low' },
+});
+/**
+ * The user every parity call is made for. Host-specific, never compared.
+ *
+ * @stability experimental
+ */
+exports.PARITY_USER_ID = '11111111-1111-4111-8111-111111111111';
+/**
+ * The task-model state of a parity run: AI on, the graph switch on, the models above, the tasks above.
+ *
+ * @param provider - the provider id the state names (the active provider and the policy's). Default {@link PARITY_PROVIDER}; `copilot` runs the same scenario over the GitHub Copilot adapter (#581).
+ * @returns a fresh state.
+ * @stability experimental
+ */
+function parityModelState(provider = exports.PARITY_PROVIDER) {
+    return {
+        provider,
+        models: exports.PARITY_MODELS.map((m) => ({
+            id: m.id,
+            label: m.id,
+            structuredOutput: true,
+            toolCalling: true,
+            contextWindow: m.contextWindow,
+            maxOutputTokens: m.maxOutputTokens,
+        })),
+        policy: {
+            enabled: true,
+            provider,
+            defaultModel: exports.PARITY_DEFAULT_MODEL,
+            graphEnabled: true,
+            taskModels: { ...exports.PARITY_TASK_MODELS },
+            reasoningEffort: exports.PARITY_DEFAULT_EFFORT,
+            maxInputTokens: null,
+            maxOutputTokens: null,
+        },
+    };
+}
+/**
+ * The same state as a static task-model source, for `createKvoxAi({ taskModels })` of the direct binding.
+ *
+ * @param provider - the provider id the state names. Default {@link PARITY_PROVIDER}.
+ * @returns a source whose `load()` always answers {@link parityModelState}.
+ * @stability experimental
+ */
+function parityTaskModelSource(provider = exports.PARITY_PROVIDER) {
+    return { load: async () => parityModelState(provider) };
+}

package/dist/parity/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `@marinoscar/kvox-eval/parity`: the harness-parity scenario.
+ *
+ * @remarks
+ * For the same input, two bindings of the model port (the web edition's, KVox
+ * Desktop's) must build byte-identical provider requests: system prompt, user
+ * prompt or input, JSON Schema, tool definitions, model, reasoning effort and output
+ * ceiling. `runParityScenario` drives the product's own notes, extraction,
+ * adjudication and Ask code through a port; the committed snapshots
+ * (`parity/requests.*.json`) are what each binding's recording must equal.
+ *
+ * @packageDocumentation
+ */
+export { PARITY_DEFAULT_EFFORT, PARITY_DEFAULT_MODEL, PARITY_MODELS, PARITY_PROVIDER, PARITY_TASK_MODELS, PARITY_USER_ID, parityModelState, parityTaskModelSource, } from './constants.js';
+export type { ParityModel } from './constants.js';
+export { PARITY_FIXTURES, PARITY_QUESTIONS, runParityScenario } from './scenario.js';
+export type { ParityScenarioOptions } from './scenario.js';
+export { createParityScript, goldExtractionAnswer } from './script.js';
+export type { ParityScript } from './script.js';
+export { PARITY_ASK_SNAPSHOT, PARITY_SNAPSHOT_DIR, loadParitySnapshot, paritySnapshotPath, writeParitySnapshot, } from './snapshot.js';