@qvac/sdk 0.18.2 → 0.19.0

package/dist/client/api/batch-completion.js

@@ -1,332 +0,0 @@
-import { stream as streamRpc } from '../../client/rpc/rpc-client.js';
-import { generateClientRequestId } from '../../client/api/client-request-id.js';
-import { getClientLogger } from '../../logging/index.js';
-import { batchCompletionStreamResponseSchema } from '../../schemas/index.js';
-import { buildFinalFromEvents } from '../../utils/aggregate-events.js';
-import { CompletionFailedError, InferenceCancelledError } from '../../utils/errors-server.js';
-import { getMcpToolsWithHandlers } from '../../utils/mcp-adapter.js';
-import { validateTools } from '../../utils/tool-helpers.js';
-const logger = getClientLogger();
-function createPerIdState() {
-    let finalResolver = () => { };
-    let finalRejecter = () => { };
-    const final = new Promise((resolve, reject) => {
-        finalResolver = resolve;
-        finalRejecter = reject;
-    });
-    final.catch(() => { });
-    return {
-        allEvents: [],
-        final,
-        finalResolver,
-        finalRejecter,
-        eventWaiters: [],
-        done: false
-    };
-}
-function addHandlers(target, source) {
-    for (const [name, handler] of source) {
-        if (target.has(name)) {
-            logger.warn(`Duplicate tool handler for "${name}", overwriting`);
-        }
-        target.set(name, handler);
-    }
-}
-async function resolveBatchPrompts(prompts) {
-    const resolvedPrompts = [];
-    const resolvedHandlers = [];
-    for (const prompt of prompts) {
-        let allTools = [];
-        const handlers = new Map();
-        if (prompt.tools) {
-            const { tools, handlers: toolHandlers } = validateTools(prompt.tools);
-            allTools = tools;
-            addHandlers(handlers, toolHandlers);
-        }
-        if (prompt.mcp && prompt.mcp.length > 0) {
-            const { tools: mcpTools, handlers: mcpHandlers } = await getMcpToolsWithHandlers(prompt.mcp);
-            allTools = [...mcpTools, ...allTools];
-            addHandlers(handlers, mcpHandlers);
-        }
-        resolvedHandlers.push(handlers);
-        resolvedPrompts.push({
-            ...(prompt.id !== undefined && { id: prompt.id }),
-            history: prompt.history,
-            ...(prompt.generationParams && {
-                generationParams: prompt.generationParams
-            }),
-            ...(prompt.responseFormat && { responseFormat: prompt.responseFormat }),
-            ...(allTools.length > 0 && { tools: allTools })
-        });
-    }
-    return { prompts: resolvedPrompts, handlers: resolvedHandlers };
-}
-export function batchCompletion(params) {
-    return createBatchCompletionRun(params, streamRpc);
-}
-export function createBatchCompletionRun(params, streamFactory) {
-    const requestId = generateClientRequestId();
-    const states = new Map();
-    const subStreams = new Map();
-    const eventQueue = [];
-    const handlersById = new Map();
-    let handlersByPosition = [];
-    const emptyHandlers = new Map();
-    let eventResolve = null;
-    let idsResolver = () => { };
-    let idsRejecter = () => { };
-    let resultsResolver = () => { };
-    let resultsRejecter = () => { };
-    let statsResolver = () => { };
-    let statsRejecter = () => { };
-    let idsResolved = false;
-    let done = false;
-    let streamError = null;
-    let settledIds = null;
-    const idsPromise = new Promise((resolve, reject) => {
-        idsResolver = resolve;
-        idsRejecter = reject;
-    });
-    idsPromise.catch(() => { });
-    const resultsPromise = new Promise((resolve, reject) => {
-        resultsResolver = resolve;
-        resultsRejecter = reject;
-    });
-    resultsPromise.catch(() => { });
-    const statsPromise = new Promise((resolve, reject) => {
-        statsResolver = resolve;
-        statsRejecter = reject;
-    });
-    statsPromise.catch(() => { });
-    function ensureState(id) {
-        let state = states.get(id);
-        if (!state) {
-            state = createPerIdState();
-            states.set(id, state);
-            if (done) {
-                if (streamError !== null) {
-                    state.finalRejecter(streamError);
-                    state.done = true;
-                }
-                else if (settledIds?.has(id)) {
-                    settleState(id, state);
-                }
-                else {
-                    state.finalRejecter(new CompletionFailedError(`Unknown batch prompt id "${id}".`));
-                    state.done = true;
-                }
-            }
-        }
-        return state;
-    }
-    function notifyWaiters() {
-        if (eventResolve) {
-            eventResolve();
-            eventResolve = null;
-        }
-        for (const state of states.values()) {
-            const waiters = state.eventWaiters.splice(0);
-            for (const resolve of waiters)
-                resolve();
-        }
-    }
-    function resolveIds(ids) {
-        if (idsResolved)
-            return;
-        idsResolved = true;
-        for (const [index, id] of ids.entries()) {
-            handlersById.set(id, handlersByPosition[index] ?? emptyHandlers);
-            ensureState(id);
-        }
-        idsResolver(ids);
-    }
-    function rejectAll(error) {
-        idsRejecter(error);
-        resultsRejecter(error);
-        statsRejecter(error);
-        for (const state of states.values()) {
-            if (!state.done)
-                state.finalRejecter(error);
-            state.done = true;
-        }
-    }
-    function settleState(id, state) {
-        if (state.done)
-            return undefined;
-        const handlers = handlersById.get(id) ?? emptyHandlers;
-        const { final, error, cancelled } = buildFinalFromEvents(state.allEvents, handlers);
-        if (error) {
-            const err = new CompletionFailedError(error.message, error);
-            state.finalRejecter(err);
-            state.done = true;
-            return err;
-        }
-        if (cancelled) {
-            const err = new InferenceCancelledError(requestId, {
-                text: final.contentText,
-                toolCalls: final.toolCalls,
-                ...(final.stats && { stats: final.stats })
-            });
-            state.finalRejecter(err);
-            state.done = true;
-            return err;
-        }
-        state.finalResolver(final);
-        state.done = true;
-        return { id, final };
-    }
-    function finishAll(ids) {
-        const results = [];
-        let firstError;
-        settledIds = new Set(ids);
-        for (const id of ids) {
-            const state = ensureState(id);
-            const outcome = settleState(id, state);
-            if (outcome instanceof Error) {
-                firstError ??= outcome;
-            }
-            else if (outcome !== undefined) {
-                results.push(outcome);
-            }
-        }
-        for (const [id, state] of states) {
-            if (!settledIds.has(id) && !state.done) {
-                state.finalRejecter(new CompletionFailedError(`Unknown batch prompt id "${id}".`));
-                state.done = true;
-            }
-        }
-        if (firstError !== undefined) {
-            resultsRejecter(firstError);
-        }
-        else {
-            resultsResolver(results);
-        }
-        return firstError;
-    }
-    const processResponses = async () => {
-        try {
-            const resolved = await resolveBatchPrompts(params.prompts);
-            handlersByPosition = resolved.handlers;
-            const request = {
-                type: 'batchCompletionStream',
-                modelId: params.modelId,
-                prompts: resolved.prompts,
-                stream: params.stream ?? true,
-                captureThinking: params.captureThinking,
-                emitRawDeltas: params.emitRawDeltas,
-                toolDialect: params.toolDialect,
-                requestId
-            };
-            let orderedIds = [];
-            const responses = streamFactory(request, params.rpcOptions);
-            for await (const response of responses) {
-                if (response &&
-                    typeof response === 'object' &&
-                    'type' in response &&
-                    response.type === 'batchCompletionStream') {
-                    const streamResponse = batchCompletionStreamResponseSchema.parse(response);
-                    if (streamResponse.ids) {
-                        orderedIds = streamResponse.ids;
-                        resolveIds(orderedIds);
-                    }
-                    for (const batchEvent of streamResponse.events) {
-                        const state = ensureState(batchEvent.id);
-                        state.allEvents.push(batchEvent.event);
-                        eventQueue.push(batchEvent);
-                    }
-                    notifyWaiters();
-                    if (streamResponse.done) {
-                        if (!idsResolved) {
-                            orderedIds =
-                                orderedIds.length > 0
-                                    ? orderedIds
-                                    : params.prompts.map((prompt, index) => prompt.id ?? String(index));
-                            resolveIds(orderedIds);
-                        }
-                        const firstError = finishAll(orderedIds);
-                        if (firstError !== undefined) {
-                            statsRejecter(firstError);
-                        }
-                        else {
-                            statsResolver(streamResponse.stats);
-                        }
-                        done = true;
-                        notifyWaiters();
-                    }
-                }
-            }
-        }
-        catch (error) {
-            streamError = error instanceof Error ? error : new Error(String(error));
-            rejectAll(error);
-            done = true;
-            for (const state of states.values())
-                state.done = true;
-            notifyWaiters();
-        }
-    };
-    void processResponses();
-    const events = (async function* () {
-        while (true) {
-            if (eventQueue.length > 0) {
-                yield eventQueue.shift();
-            }
-            else if (done) {
-                if (streamError !== null) {
-                    throw streamError;
-                }
-                break;
-            }
-            else {
-                await new Promise((resolve) => {
-                    eventResolve = resolve;
-                });
-            }
-        }
-    })();
-    function makeSubStream(id) {
-        const state = ensureState(id);
-        const events = {
-            async *[Symbol.asyncIterator]() {
-                let index = 0;
-                while (true) {
-                    if (index < state.allEvents.length) {
-                        yield state.allEvents[index];
-                        index += 1;
-                    }
-                    else if (state.done || done) {
-                        if (streamError !== null) {
-                            throw streamError;
-                        }
-                        break;
-                    }
-                    else {
-                        await new Promise((resolve) => {
-                            state.eventWaiters.push(resolve);
-                        });
-                    }
-                }
-            }
-        };
-        return {
-            events,
-            final: state.final
-        };
-    }
-    function byId(id) {
-        let subStream = subStreams.get(id);
-        if (!subStream) {
-            subStream = makeSubStream(id);
-            subStreams.set(id, subStream);
-        }
-        return subStream;
-    }
-    return {
-        requestId,
-        ids: idsPromise,
-        events,
-        results: resultsPromise,
-        stats: statsPromise,
-        byId
-    };
-}

package/dist/client/api/bci-transcribe.d.ts

@@ -1,57 +0,0 @@
-import { type BciTranscribeClientParams, type BciTranscribeStreamClientParams, type BciTranscribeStreamSession, type BciTranscribeStreamMetadataSession, type RPCOptions, type TranscribeSegment } from '../../schemas/index.js';
-/**
- * Transcribe a neural-signal buffer with a loaded BCI model and return the
- * complete text. Accepts either a `.bin` file path or a raw neural buffer.
- *
- * @param params - BCI transcription parameters.
- * @param params.modelId - The identifier of the loaded BCI model to use.
- * @param params.neuralData - Neural signal as either a file path (string) or
- *                            a binary buffer (`Uint8Array`).
- * @param params.metadata - When true, resolves to an array of transcript
- *                          segments (`{ text, startMs, endMs, append, id }`)
- *                          instead of joined text.
- * @param options - Optional RPC options including per-call profiling.
- * @returns A promise (decorated with `requestId`) resolving to the complete
- *          transcribed text, or — when `metadata` is true — the list of
- *          transcript segments in emission order. The `requestId` is
- *          reachable synchronously so callers can target this in-flight
- *          transcription with `cancel({ requestId })` before `await` resolves.
- */
-export declare function bciTranscribe(params: BciTranscribeClientParams & {
-    metadata: true;
-}, options?: RPCOptions): Promise<TranscribeSegment[]> & {
-    requestId: string;
-};
-export declare function bciTranscribe(params: BciTranscribeClientParams, options?: RPCOptions): Promise<string> & {
-    requestId: string;
-};
-/**
- * Opens a bidirectional streaming BCI transcription session. Neural-signal
- * chunks are streamed in via `write()`, and transcription is yielded as the
- * addon's sliding window decodes successive windows.
- *
- * The returned session is single-use. Attempting to iterate a second time
- * will throw a `TranscriptionFailedError`.
- *
- * @param params - Streaming BCI transcription parameters.
- * @param params.modelId - The loaded BCI model to use.
- * @param params.metadata - When true, the session yields transcript segment
- *                          objects (`{ text, startMs, endMs, append, id }`)
- *                          instead of plain text.
- * @param params.windowTimesteps - Decode window size in timesteps.
- * @param params.hopTimesteps - How far the window advances between decodes.
- * @param params.emit - `'delta'` (default) yields only the newly-discovered
- *                       tail per window; `'full'` yields the full running
- *                       transcript each update.
- * @param options - Optional RPC options including per-call profiling.
- * @returns A session object: call `write(neuralChunk)` with a `Uint8Array`
- *          to feed neural-signal bytes, iterate with `for await (...)` to
- *          receive transcription, and `end()` to signal end of input. The
- *          session exposes `requestId` synchronously for targeted
- *          `cancel({ requestId })`.
- */
-export declare function bciTranscribeStream(params: BciTranscribeStreamClientParams & {
-    metadata: true;
-}, options?: RPCOptions): Promise<BciTranscribeStreamMetadataSession>;
-export declare function bciTranscribeStream(params: BciTranscribeStreamClientParams, options?: RPCOptions): Promise<BciTranscribeStreamSession>;
-//# sourceMappingURL=bci-transcribe.d.ts.map

package/dist/client/api/bci-transcribe.js

@@ -1,173 +0,0 @@
-import { bciTranscribeResponseSchema, bciTranscribeClientParamsSchema, bciTranscribeStreamResponseSchema } from '../../schemas/index.js';
-import { stream, duplex } from '../../client/rpc/rpc-client.js';
-import { getClientLogger } from '../../logging/index.js';
-import { TranscriptionFailedError } from '../../utils/errors-client.js';
-import { decoratePromise } from '../../utils/decorate-promise.js';
-import { parseClientInput } from '../../client/parse-input.js';
-import { generateClientRequestId } from '../../client/api/client-request-id.js';
-const logger = getClientLogger();
-function buildBciTranscribeRequest(params, requestId) {
-    return {
-        type: 'bciTranscribe',
-        modelId: params.modelId,
-        neuralData: typeof params.neuralData === 'string'
-            ? { type: 'filePath', value: params.neuralData }
-            : {
-                type: 'base64',
-                value: Buffer.from(params.neuralData).toString('base64')
-            },
-        ...(params.metadata === true && { metadata: true }),
-        requestId
-    };
-}
-export function bciTranscribe(params, options) {
-    const parsed = parseClientInput(bciTranscribeClientParamsSchema, params);
-    const requestId = generateClientRequestId();
-    const inner = runBciTranscribe(parsed, requestId, options);
-    return decoratePromise(inner, { requestId });
-}
-async function runBciTranscribe(params, requestId, options) {
-    const request = buildBciTranscribeRequest(params, requestId);
-    if (params.metadata === true) {
-        const segments = [];
-        for await (const response of stream(request, options)) {
-            if (response.type === 'bciTranscribe') {
-                const parsed = bciTranscribeResponseSchema.parse(response);
-                if (parsed.segment) {
-                    segments.push(parsed.segment);
-                }
-                if (parsed.done) {
-                    break;
-                }
-            }
-        }
-        return segments;
-    }
-    let fullText = '';
-    for await (const response of stream(request, options)) {
-        if (response.type === 'bciTranscribe') {
-            const parsed = bciTranscribeResponseSchema.parse(response);
-            if (parsed.text) {
-                fullText += parsed.text;
-            }
-            if (parsed.done) {
-                break;
-            }
-        }
-    }
-    return fullText;
-}
-function buildBciTranscribeStreamRequest(params, requestId) {
-    const streamOpts = {
-        ...(params.windowTimesteps !== undefined && {
-            windowTimesteps: params.windowTimesteps
-        }),
-        ...(params.hopTimesteps !== undefined && {
-            hopTimesteps: params.hopTimesteps
-        }),
-        ...(params.emit !== undefined && { emit: params.emit })
-    };
-    return {
-        type: 'bciTranscribeStream',
-        modelId: params.modelId,
-        ...(params.metadata === true && { metadata: true }),
-        ...(Object.keys(streamOpts).length > 0 && { streamOpts }),
-        requestId
-    };
-}
-export function bciTranscribeStream(params, options) {
-    if (params.metadata === true) {
-        return createBciStreamSession(params, options, processLineMetadata, 'BciTranscribeStreamMetadataSession');
-    }
-    return createBciStreamSession(params, options, processLine, 'BciTranscribeStreamSession');
-}
-async function createBciStreamSession(params, options, process, sessionName) {
-    const requestId = generateClientRequestId();
-    const request = buildBciTranscribeStreamRequest(params, requestId);
-    const { requestStream, responseStream } = await duplex(request, options);
-    const responses = parseLines(responseStream, process);
-    let consumed = false;
-    return {
-        requestId,
-        write(neuralChunk) {
-            requestStream.write(neuralChunk);
-        },
-        end() {
-            requestStream.end();
-        },
-        destroy() {
-            requestStream.destroy();
-            responseStream.destroy();
-        },
-        [Symbol.asyncIterator]() {
-            if (consumed) {
-                throw new TranscriptionFailedError(`${sessionName} can only be iterated once`);
-            }
-            consumed = true;
-            return responses;
-        }
-    };
-}
-/**
- * Line-delimited parser: reads newline-separated frames from a duplex
- * response stream, passes each non-empty line through `process`, and yields
- * whatever values it returns. `null` from `process` terminates the stream.
- */
-async function* parseLines(responseStream, process) {
-    let buf = '';
-    for await (const chunk of responseStream) {
-        buf += chunk.toString();
-        const lines = buf.split('\n');
-        buf = lines.pop() || '';
-        for (const line of lines) {
-            const result = process(line);
-            if (result === null)
-                return;
-            if (result !== undefined)
-                yield result;
-        }
-    }
-    if (buf.trim()) {
-        const result = process(buf);
-        if (result !== null && result !== undefined)
-            yield result;
-    }
-}
-function parseResponseLine(line) {
-    if (!line.trim())
-        return null;
-    let parsed;
-    try {
-        parsed = JSON.parse(line);
-    }
-    catch {
-        logger.warn('bciTranscribeStream: malformed JSON from server:', line);
-        return null;
-    }
-    const obj = parsed;
-    if (obj['type'] === 'error') {
-        throw new TranscriptionFailedError(obj['message'] ?? 'Unknown server error');
-    }
-    return bciTranscribeStreamResponseSchema.parse(parsed);
-}
-/**
- * Shared wire-frame decoder. Returns `null` for the terminal `done` frame,
- * `undefined` for frames the caller should skip, or the value extracted from
- * the frame.
- */
-function processWith(line, extract) {
-    const response = parseResponseLine(line);
-    if (response === null)
-        return undefined;
-    if (response.error)
-        throw new TranscriptionFailedError(response.error);
-    if (response.done)
-        return null;
-    return extract(response);
-}
-function processLine(line) {
-    return processWith(line, (response) => (response.text?.trim() ? response.text : undefined));
-}
-function processLineMetadata(line) {
-    return processWith(line, (response) => response.segment);
-}

package/dist/client/api/cancel.d.ts

@@ -1,35 +0,0 @@
-import { type CancelClientInput } from '../../schemas/index.js';
-/**
- * Cancels an ongoing operation.
- *
- * Two cancel paths are supported:
- *  - **By `requestId`** (primary) — pass the `requestId` exposed on
- *    the result of a long-running call (`completion(...)`,
- *    `loadModel(...)`, `downloadAsset(...)`, `embed(...)`,
- *    `transcribe(...)`, `ragIngest(...)`, etc.) to cancel exactly
- *    that request. A cancel that races the originating call is
- *    recorded and applied retroactively when the begin arrives.
- *  - **Broad by `modelId`** (escape hatch) — `{ modelId, kind? }`
- *    cancels every in-flight request on that model. Useful for
- *    model unload, app shutdown, or admin sweeps where the caller
- *    doesn't have a `requestId` to hand.
- *
- * The legacy `{ operation: "inference" | "embeddings", modelId }`
- * sugars remain callable for source compatibility. For migration off
- * the removed `{ operation: "downloadAsset" | "rag" }` shapes, see
- * the 0.11.0 changelog / release notes.
- *
- * @param params - The cancellation parameters.
- * @throws {QvacErrorBase} When the response type is invalid or the cancellation fails.
- *
- * @example
- * // Cancel by requestId (primary path)
- * const run = completion({ ... });
- * await cancel({ requestId: run.requestId });
- *
- * @example
- * // Broad-cancel every inference running on a model
- * await cancel({ modelId: "model-123", kind: "completion" });
- */
-export declare function cancel(params: CancelClientInput): Promise<void>;
-//# sourceMappingURL=cancel.d.ts.map

package/dist/client/api/cancel.js

@@ -1,83 +0,0 @@
-import { send } from '../../client/rpc/rpc-client.js';
-import {} from '../../schemas/index.js';
-import { InvalidResponseError, CancelFailedError } from '../../utils/errors-client.js';
-/**
- * Cancels an ongoing operation.
- *
- * Two cancel paths are supported:
- *  - **By `requestId`** (primary) — pass the `requestId` exposed on
- *    the result of a long-running call (`completion(...)`,
- *    `loadModel(...)`, `downloadAsset(...)`, `embed(...)`,
- *    `transcribe(...)`, `ragIngest(...)`, etc.) to cancel exactly
- *    that request. A cancel that races the originating call is
- *    recorded and applied retroactively when the begin arrives.
- *  - **Broad by `modelId`** (escape hatch) — `{ modelId, kind? }`
- *    cancels every in-flight request on that model. Useful for
- *    model unload, app shutdown, or admin sweeps where the caller
- *    doesn't have a `requestId` to hand.
- *
- * The legacy `{ operation: "inference" | "embeddings", modelId }`
- * sugars remain callable for source compatibility. For migration off
- * the removed `{ operation: "downloadAsset" | "rag" }` shapes, see
- * the 0.11.0 changelog / release notes.
- *
- * @param params - The cancellation parameters.
- * @throws {QvacErrorBase} When the response type is invalid or the cancellation fails.
- *
- * @example
- * // Cancel by requestId (primary path)
- * const run = completion({ ... });
- * await cancel({ requestId: run.requestId });
- *
- * @example
- * // Broad-cancel every inference running on a model
- * await cancel({ modelId: "model-123", kind: "completion" });
- */
-export async function cancel(params) {
-    const wireParams = normalizeCancelParams(params);
-    const request = {
-        type: 'cancel',
-        ...wireParams
-    };
-    const response = await send(request);
-    if (response.type !== 'cancel') {
-        throw new InvalidResponseError('cancel');
-    }
-    if (!response.success) {
-        throw new CancelFailedError(response.error);
-    }
-}
-function normalizeCancelParams(params) {
-    if ('operation' in params) {
-        if (params.operation === 'request' || params.operation === 'broad') {
-            return params;
-        }
-        // Legacy per-kind sugar: { operation: "inference"|"embeddings", modelId }
-        if (params.operation === 'inference') {
-            return {
-                operation: 'broad',
-                modelId: params.modelId,
-                kind: 'completion'
-            };
-        }
-        return { operation: 'broad', modelId: params.modelId, kind: 'embeddings' };
-    }
-    if ('requestId' in params) {
-        const wire = {
-            operation: 'request',
-            requestId: params.requestId
-        };
-        if (params.clearCache !== undefined) {
-            wire.clearCache = params.clearCache;
-        }
-        return wire;
-    }
-    const broad = {
-        operation: 'broad',
-        modelId: params.modelId
-    };
-    if (params.kind !== undefined) {
-        broad.kind = params.kind;
-    }
-    return broad;
-}