@pikku/core 0.12.84 → 0.12.86

package/dist/wirings/ai-agent/voice-input.d.ts

@@ -1,69 +0,0 @@
-/**
- * Raised when every audio part in a turn turned out to be non-speech.
- *
- * Distinct from a transcription failure, because the response is different: a
- * failure is worth reporting, whereas this is the microphone doing its job on a
- * pause. A voice loop should catch it and go back to listening without running
- * the agent — answering a hallucinated sentence is worse than answering nothing.
- */
-export declare class NoSpeechDetectedError extends Error {
-    constructor();
-}
-/**
- * Whether nothing usable was said — an empty transcript, and nothing cleverer
- * than that.
- *
- * There was a confidence gate here once, and it is worth recording why it is
- * gone. Whisper is trained on subtitles, so audio it cannot parse comes back
- * not as nothing but as stock filler appended to real speech: "Hello, my name
- * is Yasir. Thank you." where only the first sentence was spoken. The obvious
- * defence is to drop low-confidence segments, and it does not work. Measured on
- * a real turn, the invented "Thank you." scored `avg_logprob` -0.52 against
- * -0.30 for the genuine sentence beside it, and `no_speech_prob` read 0.000 for
- * both. Whisper is *confident* when it invents, because the text it invents is
- * high-probability text. No threshold separates those two numbers, and one set
- * low enough to try would take real quiet speech with it.
- *
- * The fix belongs at the model, not behind it: an ASR that is not a
- * subtitle-trained autoregressive decoder returns an empty string on non-speech
- * and there is nothing left to filter. Hence this reduces to asking whether
- * anything came back at all — which is a property every provider reports
- * honestly, unlike per-segment confidence (Nemotron, for one, hardcodes
- * `avg_logprob` to 0.0).
- */
-export declare const readsAsNonSpeech: (result: {
-    text?: string;
-}) => boolean;
-/**
- * Shared-notes key recording whether the user's turn arrived as audio.
- *
- * Written here because this is the last point at which it is knowable: the
- * transcript that replaces the audio is indistinguishable from something typed.
- * Read by `voiceOutput` to decide whether to answer aloud.
- *
- * Absent — rather than `false` — when this middleware is not wired at all, which
- * is what lets `voiceOutput` still speak for a caller that has no voice input.
- */
-export declare const SPOKEN_TURN = "voice:spokenTurn";
-/**
- * Shared-notes key holding what the user was heard to say, when they spoke.
- *
- * Absent on a typed turn. Read by the stream wiring, which forwards it to the
- * client as a `transcript` event — a voice client has no idea what its own
- * audio said, and without this the user's turn shows up in the UI as an empty
- * bubble followed by an answer to a question they cannot see.
- */
-export declare const SPOKEN_TRANSCRIPT = "voice:transcript";
-export declare const voiceInput: (config?: {
-    language?: string;
-    model?: string;
-    allowedAudioHosts?: string[];
-}) => import("./ai-agent.types.js").PikkuAIMiddlewareHooks<Record<string, unknown>, import("../../types/core.types.js").CoreSingletonServices<{
-    logLevel?: import("../../services/logger.js").LogLevel;
-    secrets?: {
-        requireAllowedHosts?: boolean;
-    };
-    workflow?: import("../workflow/workflow.types.js").WorkflowServiceConfig;
-    webhook?: import("../../services/webhook-service.js").WebhookServiceConfig;
-    postgres?: import("../../types/core.types.js").PostgresConfig;
-}>>;

package/dist/wirings/ai-agent/voice-input.js

@@ -1,150 +0,0 @@
-import { pikkuAIMiddleware } from '../../types/core.types.js';
-import { safeFetch } from '../../utils/safe-fetch.js';
-function base64ToUint8Array(base64) {
-    const binary = atob(base64);
-    const bytes = new Uint8Array(binary.length);
-    for (let i = 0; i < binary.length; i++) {
-        bytes[i] = binary.charCodeAt(i);
-    }
-    return bytes;
-}
-const MAX_AUDIO_SIZE = 50 * 1024 * 1024;
-/**
- * Raised when every audio part in a turn turned out to be non-speech.
- *
- * Distinct from a transcription failure, because the response is different: a
- * failure is worth reporting, whereas this is the microphone doing its job on a
- * pause. A voice loop should catch it and go back to listening without running
- * the agent — answering a hallucinated sentence is worse than answering nothing.
- */
-export class NoSpeechDetectedError extends Error {
-    constructor() {
-        super('No speech was detected in the audio.');
-        this.name = 'NoSpeechDetectedError';
-    }
-}
-/**
- * Whether nothing usable was said — an empty transcript, and nothing cleverer
- * than that.
- *
- * There was a confidence gate here once, and it is worth recording why it is
- * gone. Whisper is trained on subtitles, so audio it cannot parse comes back
- * not as nothing but as stock filler appended to real speech: "Hello, my name
- * is Yasir. Thank you." where only the first sentence was spoken. The obvious
- * defence is to drop low-confidence segments, and it does not work. Measured on
- * a real turn, the invented "Thank you." scored `avg_logprob` -0.52 against
- * -0.30 for the genuine sentence beside it, and `no_speech_prob` read 0.000 for
- * both. Whisper is *confident* when it invents, because the text it invents is
- * high-probability text. No threshold separates those two numbers, and one set
- * low enough to try would take real quiet speech with it.
- *
- * The fix belongs at the model, not behind it: an ASR that is not a
- * subtitle-trained autoregressive decoder returns an empty string on non-speech
- * and there is nothing left to filter. Hence this reduces to asking whether
- * anything came back at all — which is a property every provider reports
- * honestly, unlike per-segment confidence (Nemotron, for one, hardcodes
- * `avg_logprob` to 0.0).
- */
-export const readsAsNonSpeech = (result) => !(result.text ?? '').trim();
-async function fetchAsUint8Array(url, allowedAudioHosts) {
-    const response = await safeFetch(url, {}, { allowedHosts: allowedAudioHosts });
-    const contentLength = response.headers.get('content-length');
-    if (contentLength && parseInt(contentLength, 10) > MAX_AUDIO_SIZE) {
-        throw new Error('Audio file exceeds maximum size');
-    }
-    const buffer = await response.arrayBuffer();
-    if (buffer.byteLength > MAX_AUDIO_SIZE) {
-        throw new Error('Audio file exceeds maximum size');
-    }
-    return new Uint8Array(buffer);
-}
-/**
- * Shared-notes key recording whether the user's turn arrived as audio.
- *
- * Written here because this is the last point at which it is knowable: the
- * transcript that replaces the audio is indistinguishable from something typed.
- * Read by `voiceOutput` to decide whether to answer aloud.
- *
- * Absent — rather than `false` — when this middleware is not wired at all, which
- * is what lets `voiceOutput` still speak for a caller that has no voice input.
- */
-export const SPOKEN_TURN = 'voice:spokenTurn';
-/**
- * Shared-notes key holding what the user was heard to say, when they spoke.
- *
- * Absent on a typed turn. Read by the stream wiring, which forwards it to the
- * client as a `transcript` event — a voice client has no idea what its own
- * audio said, and without this the user's turn shows up in the UI as an empty
- * bubble followed by an answer to a question they cannot see.
- */
-export const SPOKEN_TRANSCRIPT = 'voice:transcript';
-export const voiceInput = (config) => pikkuAIMiddleware({
-    modifyInput: async (services, { messages, instructions, shared }) => {
-        const aiAgentRunner = services.aiAgentRunner;
-        if (!aiAgentRunner?.transcribe)
-            return { messages, instructions };
-        const last = messages[messages.length - 1];
-        const parts = last?.role === 'user' && typeof last.content !== 'string'
-            ? last.content
-            : undefined;
-        const hasAudio = !!parts?.some((p) => p.type === 'file' && !!p.mediaType?.startsWith('audio/'));
-        // Recorded on every turn this middleware sees, spoken or not, so that a
-        // typed turn is an explicit `false` downstream rather than a silence that
-        // could equally mean nobody was asked.
-        shared[SPOKEN_TURN] = hasAudio;
-        if (!hasAudio || !parts)
-            return { messages, instructions };
-        const updatedContent = [];
-        const heard = [];
-        for (const p of parts) {
-            if (!(p.type === 'file' && p.mediaType?.startsWith('audio/'))) {
-                updatedContent.push(p);
-                continue;
-            }
-            if (!config?.model) {
-                throw new Error('voiceInput requires a transcription model (e.g. openai/whisper-1)');
-            }
-            const audioData = p.data
-                ? base64ToUint8Array(p.data)
-                : await fetchAsUint8Array(p.url, config.allowedAudioHosts);
-            if (audioData.byteLength > MAX_AUDIO_SIZE) {
-                throw new Error('Audio file exceeds maximum size');
-            }
-            const result = await aiAgentRunner.transcribe({
-                model: config.model,
-                audio: audioData,
-                ...(config.language
-                    ? {
-                        providerOptions: {
-                            openai: {
-                                language: config.language,
-                            },
-                        },
-                    }
-                    : {}),
-            });
-            // Dropped when nothing was said: an empty text part is still a turn the
-            // model will answer, and what it answers is a guess about what it could
-            // not hear.
-            if (readsAsNonSpeech(result))
-                continue;
-            heard.push(result.text);
-            updatedContent.push({ type: 'text', text: result.text });
-        }
-        // Every part was audio, and none of it was speech. There is nothing left
-        // to send, and a message with no content is not a question.
-        if (updatedContent.length === 0)
-            throw new NoSpeechDetectedError();
-        // knowledge: decisions/internals/an-empty-transcript-is-not-recorded.md
-        if (heard.length > 0) {
-            shared[SPOKEN_TRANSCRIPT] = heard.join(' ');
-        }
-        return {
-            messages: [
-                ...messages.slice(0, -1),
-                { ...last, content: updatedContent },
-            ],
-            instructions,
-        };
-    },
-});

package/dist/wirings/ai-agent/voice-output.d.ts

@@ -1,85 +0,0 @@
-export type VoiceOutputState = {
-    textBuffer?: string;
-    /**
-     * The audio emitted so far, as a chain.
-     *
-     * Synthesis for every finished sentence starts immediately, so the second
-     * sentence is being generated while the first is still being spoken. That
-     * also means the second can finish first — a short sentence after a long one
-     * routinely does. Chaining the *emissions* keeps the client receiving audio
-     * in the order it was written while leaving the generation overlapped.
-     */
-    tail?: Promise<void>;
-    /** Whether this reply has already said it cannot be spoken aloud. */
-    reportedUnspeakable?: boolean;
-};
-/**
- * The scripts a model can pronounce, and optionally the voice each one needs.
- *
- * The array form is for a model whose voice is the same whatever the script.
- * The record form exists because that is not the common case: Kokoro speaks
- * Mandarin, Japanese and Hindi well, but only through a voice belonging to that
- * language. Asked for Chinese in its default American-English voice it spells
- * the characters out — 9.9 seconds of "Chinese letter, Chinese letter" for a
- * sentence the right voice says in 3.5. Same model, same text, same price.
- */
-export type SpeakableScripts = string[] | Record<string, string>;
-/**
- * The scripts present in `text` that the model was not said to handle.
- *
- * Silence would be the wrong answer here and so would a best effort. Handed
- * Arabic — which it has no voice for at all — Kokoro does not fail and does not
- * stay quiet: it reads out the *letter names*, twenty-four seconds of "Arabic
- * meem, Arabic ra" for a one-line sentence, which is worse than either. Naming
- * the gap lets the caller say so instead.
- */
-export declare const unspeakableScripts: (text: string, speakable: SpeakableScripts) => string[];
-/**
- * The voice to speak `text` in, or `fallback` if no mapped script appears.
- *
- * A sentence is regularly in more than one script, so which one decides is
- * settled by {@link SCRIPT_PRECEDENCE} rather than by the order the config
- * happens to be written in.
- */
-export declare const voiceForText: (text: string, speakable: SpeakableScripts, fallback?: string) => string | undefined;
-export declare const voiceOutput: (config?: {
-    model?: string;
-    format?: string;
-    voice?: string;
-    instructions?: string;
-    speed?: number;
-    language?: string;
-    /**
-     * Scripts the configured model can actually pronounce, and the voice each
-     * needs — see {@link SpeakableScripts}. Anything written in another script is
-     * left unspoken and reported once, as a `voice-unsupported` data event,
-     * rather than sent to a model that will mangle it.
-     *
-     * Omitted means no check: every model is trusted with every script, which is
-     * the right default for a provider that genuinely is multilingual.
-     */
-    speakableScripts?: SpeakableScripts;
-    /**
-     * Speak every reply, including answers to turns that were typed.
-     *
-     * The default is to speak only what was spoken to. An agent is usually one
-     * agent serving both kinds of caller — the same thread is typed at from a
-     * desk and talked to from a phone — and synthesizing a reply nobody is
-     * listening to costs real money on every sentence of every turn. Whether the
-     * user is in a call is not something the client needs to declare: sending
-     * audio is what saying so looks like.
-     *
-     * Set this for the cases where speech is not a reply to speech at all — a
-     * read-aloud accessibility mode, a kiosk, anything whose whole output is
-     * meant to be heard.
-     */
-    always?: boolean;
-}) => import("./ai-agent.types.js").PikkuAIMiddlewareHooks<VoiceOutputState, import("../../types/core.types.js").CoreSingletonServices<{
-    logLevel?: import("../../services/logger.js").LogLevel;
-    secrets?: {
-        requireAllowedHosts?: boolean;
-    };
-    workflow?: import("../workflow/workflow.types.js").WorkflowServiceConfig;
-    webhook?: import("../../services/webhook-service.js").WebhookServiceConfig;
-    postgres?: import("../../types/core.types.js").PostgresConfig;
-}>>;

package/dist/wirings/ai-agent/voice-output.js

@@ -1,196 +0,0 @@
-import { pikkuAIMiddleware } from '../../types/core.types.js';
-import { SPOKEN_TURN } from './voice-input.js';
-function bufferToBase64(data) {
-    let binary = '';
-    for (let i = 0; i < data.length; i++) {
-        binary += String.fromCharCode(data[i]);
-    }
-    return btoa(binary);
-}
-const SENTENCE_BOUNDARY = /[.!?]\s*$/;
-function isSentenceBoundary(text) {
-    return SENTENCE_BOUNDARY.test(text);
-}
-/**
- * Scripts a speech model can pronounce, as named by {@link voiceOutput}'s
- * `speakableScripts`.
- *
- * Script rather than language because script is what is decidable from the text
- * alone. Spanish, French and English are one test, not three — and the models
- * that handle one Latin-script language generally handle the others. What a
- * model cannot do is invent a phoneme set it was never given.
- */
-const SCRIPT_RANGES = {
-    latin: /[A-ɏ]/,
-    devanagari: /[ऀ-ॿ]/,
-    han: /[㐀-鿿]/,
-    kana: /[぀-ヿ]/,
-    arabic: /[؀-ۿݐ-ݿ]/,
-    cyrillic: /[Ѐ-ӿ]/,
-    hangul: /[가-힯ᄀ-ᇿ]/,
-    hebrew: /[֐-׿]/,
-    greek: /[Ͱ-Ͽ]/,
-    thai: /[฀-๿]/,
-};
-/**
- * Which script decides the voice when a sentence contains several.
- *
- * The ordering is by how much a script narrows down the language, not by
- * preference. Kana appears only in Japanese, so a sentence holding any settles
- * it — while Han is written in both Chinese and Japanese and so cannot, which
- * matters because ordinary Japanese is mostly kanji. Latin comes last for the
- * same reason from the other end: it turns up inside sentences in every other
- * script, and it is the one whose voice is least often the one that counts. A
- * Chinese voice reading an English word is accented; an English voice reading
- * Chinese spells it out.
- *
- * Everything else — Han included — sits between the two in config order.
- */
-const SCRIPT_PRECEDENCE = { kana: -1, latin: 1 };
-const scriptRank = (name) => SCRIPT_PRECEDENCE[name] ?? 0;
-const scriptNames = (speakable) => Array.isArray(speakable) ? speakable : Object.keys(speakable);
-/**
- * The scripts present in `text` that the model was not said to handle.
- *
- * Silence would be the wrong answer here and so would a best effort. Handed
- * Arabic — which it has no voice for at all — Kokoro does not fail and does not
- * stay quiet: it reads out the *letter names*, twenty-four seconds of "Arabic
- * meem, Arabic ra" for a one-line sentence, which is worse than either. Naming
- * the gap lets the caller say so instead.
- */
-export const unspeakableScripts = (text, speakable) => {
-    const allowed = new Set(scriptNames(speakable));
-    return Object.entries(SCRIPT_RANGES)
-        .filter(([name, range]) => !allowed.has(name) && range.test(text))
-        .map(([name]) => name);
-};
-/**
- * The voice to speak `text` in, or `fallback` if no mapped script appears.
- *
- * A sentence is regularly in more than one script, so which one decides is
- * settled by {@link SCRIPT_PRECEDENCE} rather than by the order the config
- * happens to be written in.
- */
-export const voiceForText = (text, speakable, fallback) => {
-    if (Array.isArray(speakable))
-        return fallback;
-    const mapped = Object.entries(speakable).sort(([a], [b]) => scriptRank(a) - scriptRank(b));
-    for (const [name, voice] of mapped) {
-        if (SCRIPT_RANGES[name]?.test(text))
-            return voice;
-    }
-    return fallback;
-};
-async function synthesizeAudio(aiAgentRunner, input) {
-    const result = await aiAgentRunner.generateSpeech?.({
-        model: input.model,
-        text: input.text,
-        voice: input.voice,
-        outputFormat: input.format,
-        instructions: input.instructions,
-        speed: input.speed,
-        language: input.language,
-        abortSignal: input.abortSignal,
-    });
-    if (!result) {
-        throw new Error('voiceOutput requires an aiAgentRunner with generateSpeech support');
-    }
-    return {
-        bytes: result.audio.uint8Array,
-        format: result.audio.format || input.format || 'pcm16',
-    };
-}
-export const voiceOutput = (config) => pikkuAIMiddleware({
-    modifyOutputStream: async (services, { event, state, shared, emit, signal }) => {
-        const { aiAgentRunner, logger } = services;
-        if (!aiAgentRunner?.generateSpeech)
-            return event;
-        // knowledge: decisions/internals/voice-output-speaks-unless-voice-input-explicitly-says-otherwise.md
-        if (!config?.always && shared[SPOKEN_TURN] === false)
-            return event;
-        /**
-         * Queue a finished sentence for speech.
-         *
-         * Nothing here is awaited by the caller. Synthesis is kicked off at once
-         * and its emission is chained behind the previous sentence, which is
-         * what keeps the text flowing at the speed the model writes it instead
-         * of the speed the speech provider answers.
-         */
-        const speak = (text) => {
-            if (!config?.model) {
-                throw new Error('voiceOutput requires a speech model (e.g. openai/tts-1)');
-            }
-            // knowledge: decisions/internals/speech-synthesis-picks-a-voice-per-sentence-and-warns-once.md
-            let voice = config.voice;
-            if (config.speakableScripts) {
-                const unspeakable = unspeakableScripts(text, config.speakableScripts);
-                voice = voiceForText(text, config.speakableScripts, config.voice);
-                if (unspeakable.length > 0) {
-                    if (!state.reportedUnspeakable) {
-                        state.reportedUnspeakable = true;
-                        state.tail = (state.tail ?? Promise.resolve()).then(() => emit({
-                            type: 'data',
-                            name: 'voice-unsupported',
-                            data: { model: config.model, scripts: unspeakable },
-                        }));
-                    }
-                    return;
-                }
-            }
-            // Settled into a value rather than left as a rejectable promise: it
-            // sits unobserved until the chain reaches it, and an unhandled
-            // rejection in that window would take the process down.
-            const synthesis = synthesizeAudio(aiAgentRunner, {
-                model: config.model,
-                text,
-                voice,
-                format: config?.format,
-                instructions: config?.instructions,
-                speed: config?.speed,
-                language: config?.language,
-                // Barge-in should stop the bill, not just the playback. Without this
-                // every sentence already in flight is synthesized in full and paid
-                // for after the user has stopped listening.
-                abortSignal: signal,
-            }).then((audio) => ({ ok: true, audio }), (error) => ({ ok: false, error }));
-            state.tail = (state.tail ?? Promise.resolve()).then(async () => {
-                const result = await synthesis;
-                if (!result.ok) {
-                    // One sentence going unspoken is better than the rest of the reply
-                    // never arriving, so the chain carries on.
-                    logger?.error(`voiceOutput could not synthesize a sentence: ${String(result.error)}`);
-                    return;
-                }
-                await emit({
-                    type: 'audio-delta',
-                    data: bufferToBase64(result.audio.bytes),
-                    format: result.audio.format,
-                    text,
-                });
-            });
-        };
-        if (event.type === 'done') {
-            const remaining = state.textBuffer ?? '';
-            state.textBuffer = '';
-            if (remaining.trim()) {
-                speak(remaining);
-            }
-            // The only place this hook waits. The reply is already over, so the
-            // wait costs the reader nothing, and it is what makes `audio-done`
-            // mean what it says rather than racing the last chunk.
-            await state.tail;
-            state.tail = undefined;
-            return [{ type: 'audio-done' }, event];
-        }
-        if (event.type !== 'text-delta')
-            return event;
-        state.textBuffer = `${state.textBuffer ?? ''}${event.text}`;
-        if (isSentenceBoundary(state.textBuffer)) {
-            const text = state.textBuffer;
-            state.textBuffer = '';
-            speak(text);
-        }
-        // Returned without waiting for any audio — the entire point.
-        return event;
-    },
-});

package/dist/wirings/ai-scorer/ai-scorer-grade.d.ts

@@ -1,26 +0,0 @@
-import type { ScoreJob, ScorerOutput } from './ai-scorer.types.js';
-/**
- * Grade one run with one scorer.
- *
- * The single path both callers take — the lane worker on live traffic and the
- * scenario grading RPC — so a scenario's grade is the same computation the
- * production sampler would have made, not an approximation of it.
- *
- * Persisting is optional because the two callers differ on it: a live grade is
- * only useful once recorded, while a scenario asserts on the returned value and
- * runs against servers that may have no run-state adapter at all.
- */
-export declare const gradeRun: (job: ScoreJob, services: {
-    aiAgentRunner?: unknown;
-    aiRunState?: {
-        saveScore: (score: {
-            runId: string;
-            scorerName: string;
-            score: number;
-            reason?: string;
-            metadata?: Record<string, unknown>;
-        }) => Promise<void>;
-    };
-}, options: {
-    persist: boolean;
-}) => Promise<ScorerOutput>;

package/dist/wirings/ai-scorer/ai-scorer-grade.js

@@ -1,33 +0,0 @@
-import { runJudge } from './ai-scorer-judge.js';
-import { resolveAIScorer } from './ai-scorer-registry.js';
-/**
- * Grade one run with one scorer.
- *
- * The single path both callers take — the lane worker on live traffic and the
- * scenario grading RPC — so a scenario's grade is the same computation the
- * production sampler would have made, not an approximation of it.
- *
- * Persisting is optional because the two callers differ on it: a live grade is
- * only useful once recorded, while a scenario asserts on the returned value and
- * runs against servers that may have no run-state adapter at all.
- */
-export const gradeRun = async (job, services, options) => {
-    const { scorerName, ...input } = job;
-    const scorer = resolveAIScorer(scorerName);
-    const result = scorer.score
-        ? await scorer.score(input, services)
-        : await runJudge(scorer, input, services.aiAgentRunner);
-    if (options.persist) {
-        if (!services.aiRunState) {
-            throw new Error(`AI run state service not initialized: cannot record the '${scorerName}' grade of run ${job.runId}`);
-        }
-        await services.aiRunState.saveScore({
-            runId: job.runId,
-            scorerName,
-            score: result.score,
-            ...(result.reason !== undefined ? { reason: result.reason } : {}),
-            ...(result.metadata !== undefined ? { metadata: result.metadata } : {}),
-        });
-    }
-    return result;
-};

package/dist/wirings/ai-scorer/ai-scorer-judge.d.ts

@@ -1,17 +0,0 @@
-import type { AIAgentRunnerService } from '../../services/ai-agent-runner-service.js';
-import type { PikkuAIScorer, ScorerInput, ScorerJudgeConfig, ScorerOutput } from './ai-scorer.types.js';
-/**
- * The message a judge grades when its scorer supplies no `prompt`.
- *
- * A reference-based judge is shown the answer key; a reference-free one is not,
- * and grades the answer on its own merits.
- */
-export declare const buildJudgePrompt: (judge: ScorerJudgeConfig, input: ScorerInput) => string;
-/**
- * Run an LLM judge and force the `{ score, reason }` contract, so a scorer
- * author writes a rubric rather than a parser.
- *
- * A judge has no tools, which is the one case where an output schema is
- * reliably honoured.
- */
-export declare const runJudge: (scorer: PikkuAIScorer<any>, input: ScorerInput, aiAgentRunner: AIAgentRunnerService | undefined) => Promise<ScorerOutput>;

package/dist/wirings/ai-scorer/ai-scorer-judge.js

@@ -1,92 +0,0 @@
-import { randomUUID } from '../ai-agent/ai-agent-utils.js';
-const JUDGE_OUTPUT_SCHEMA = {
-    type: 'object',
-    properties: {
-        score: {
-            type: 'number',
-            minimum: 0,
-            maximum: 1,
-            description: 'How well the answer meets the rubric. 1 is best.',
-        },
-        reason: {
-            type: 'string',
-            description: 'One or two sentences explaining the score.',
-        },
-    },
-    required: ['score', 'reason'],
-    additionalProperties: false,
-};
-/**
- * The message a judge grades when its scorer supplies no `prompt`.
- *
- * A reference-based judge is shown the answer key; a reference-free one is not,
- * and grades the answer on its own merits.
- */
-export const buildJudgePrompt = (judge, input) => {
-    if (judge.prompt)
-        return judge.prompt(input);
-    const sections = [`User asked:\n${input.input}`];
-    if (input.reference !== undefined) {
-        sections.push(`Reference answer:\n${input.reference}`);
-    }
-    sections.push(`Assistant answered:\n${input.output}`);
-    sections.push(judge.goal);
-    sections.push('Respond with a score 0..1 and a brief reason.');
-    return sections.join('\n\n');
-};
-/**
- * Clamp rather than reject: a model that answers 1.2 has still made a legible
- * judgement, and failing the job would lose it. A non-number has not.
- */
-const normalizeScore = (scorerName, value) => {
-    if (typeof value !== 'number' || Number.isNaN(value)) {
-        throw new Error(`Judge '${scorerName}' returned a non-numeric score: ${JSON.stringify(value)}`);
-    }
-    return Math.min(1, Math.max(0, value));
-};
-/**
- * Run an LLM judge and force the `{ score, reason }` contract, so a scorer
- * author writes a rubric rather than a parser.
- *
- * A judge has no tools, which is the one case where an output schema is
- * reliably honoured.
- */
-export const runJudge = async (scorer, input, aiAgentRunner) => {
-    const judge = scorer.judge;
-    if (!judge) {
-        throw new Error(`Scorer '${scorer.name}' is not a judge`);
-    }
-    if (!aiAgentRunner) {
-        throw new Error(`Judge '${scorer.name}' needs an AI provider, but no aiAgentRunner is registered in this process. ` +
-            `A worker deployed apart from the API has to register one to run the slow scoring lane.`);
-    }
-    if (scorer.requiresReference && input.reference === undefined) {
-        throw new Error(`Judge '${scorer.name}' grades against a reference answer, but none was supplied`);
-    }
-    const messages = [
-        {
-            id: randomUUID(),
-            role: 'user',
-            content: buildJudgePrompt(judge, input),
-            createdAt: new Date(),
-        },
-    ];
-    const result = await aiAgentRunner.run({
-        model: judge.model,
-        instructions: judge.goal,
-        messages,
-        tools: [],
-        maxSteps: 1,
-        toolChoice: 'none',
-        outputSchema: JUDGE_OUTPUT_SCHEMA,
-    });
-    const object = (result.object ?? {});
-    return {
-        score: normalizeScore(scorer.name, object.score),
-        ...(typeof object.reason === 'string' ? { reason: object.reason } : {}),
-        metadata: {
-            judgeModel: judge.model,
-            judgeTokens: result.usage.inputTokens + result.usage.outputTokens,
-        },
-    };
-};