import { z } from "zod";
import type { ModelSrcInput } from "./model-src-utils";
/**
 * Granularity at which the addon can cancel.
 *  - `"request"` — addon cancels a specific in-flight `requestId`.
 *  - `"model"` — addon cancels whatever is running on the model.
 *  - `"none"` — no addon cancel surface; SDK falls back to soft-cancel
 *    (stop yielding, drop result; the C++ work runs to completion).
 */
export type PluginHandlerCancelScope = "request" | "model" | "none";
export interface PluginHandlerCancel {
    scope: PluginHandlerCancelScope;
    /**
     * `true` — `addon.cancel()` interrupts compute; otherwise it's
     * best-effort. Only meaningful for `scope: "model" | "request"`.
     */
    hard?: boolean;
}
/**
 * Definition for a plugin handler with explicit Zod schemas.
 * Each handler must define its request/response schemas for validation.
 */
export interface PluginHandlerDefinition<TRequest extends z.ZodType = z.ZodType, TResponse extends z.ZodType = z.ZodType> {
    requestSchema: TRequest;
    responseSchema: TResponse;
    streaming: boolean;
    duplex?: boolean;
    handler: TRequest extends z.ZodType<infer I> ? TResponse extends z.ZodType<infer O> ? (request: I, inputStream?: AsyncIterable<Buffer>) => Promise<O> | AsyncGenerator<O> : never : never;
    /**
     * Cancel surface this handler advertises. Omitting is equivalent
     * to `{ scope: "none" }` (soft-cancel fallback).
     */
    cancel?: PluginHandlerCancel;
}
/**
 * Variant of `PluginHandlerDefinition` for duplex handlers where
 * `inputStream` is guaranteed to be present. Use with `defineDuplexHandler`.
 */
export interface DuplexPluginHandlerDefinition<TRequest extends z.ZodType = z.ZodType, TResponse extends z.ZodType = z.ZodType> {
    requestSchema: TRequest;
    responseSchema: TResponse;
    streaming: true;
    duplex: true;
    handler: TRequest extends z.ZodType<infer I> ? TResponse extends z.ZodType<infer O> ? (request: I, inputStream: AsyncIterable<Buffer>) => AsyncGenerator<O> : never : never;
    /** See `PluginHandlerDefinition.cancel`. */
    cancel?: PluginHandlerCancel;
}
/**
 * Parameters passed to createModel when loading a plugin model.
 *
 * Core fields are always present. The `artifacts` map contains
 * additional file paths required by specific plugins (e.g., projection
 * models, VAD models, config files).
 *
 * Built-in artifact keys:
 * - `projectionModelPath` - LLM multimodal projection model
 * - `vadModelPath` - Whisper voice activity detection model
 * - `tokenizerPath`, `speechEncoderPath`, `embedTokensPath`, `conditionalDecoderPath`, `languageModelPath` - TTS (Chatterbox) model files
 * - `referenceAudioPath` - TTS (Chatterbox) path to reference WAV file for voice cloning
 * - `tokenizerPath`, `textEncoderPath`, `latentDenoiserPath`, `voiceDecoderPath` - TTS (Supertonic) model files
 * - `voicePath` - TTS (Supertonic) path to voice .bin file (e.g. voices/M1.bin)
 * - `speed`, `numInferenceSteps` - TTS (Supertonic) options
 * - `detectorModelPath` - OCR detector model
 *
 * Custom plugins can define their own artifact keys.
 */
export interface CreateModelParams {
    modelId: string;
    modelPath: string;
    modelConfig?: Record<string, unknown> | undefined;
    modelName?: string | undefined;
    artifacts?: Record<string, string> | undefined;
}
/**
 * Minimal contract for plugin models.
 * All models must implement `load()`. `unload()` is optional.
 */
export interface PluginModel {
    load(force?: boolean): Promise<void>;
    unload?(): void | Promise<void>;
}
export interface PluginModelResult {
    model: PluginModel;
}
export interface PluginLogging {
    module: unknown;
    namespace: string;
}
/**
 * Function to resolve a model source (URL or path) to a local file path.
 * Passed to resolveConfig hook to allow plugins to resolve their artifacts.
 */
export type ResolveModelPath = (src: ModelSrcInput) => Promise<string>;
/**
 * Context passed to plugin resolveConfig hook.
 * Provides resolution utilities and request metadata.
 */
export interface ResolveContext {
    resolveModelPath: ResolveModelPath;
    modelSrc: string;
    modelType: string;
    modelName?: string;
}
/**
 * Result from plugin resolveConfig hook.
 * Contains transformed config and optional resolved artifacts.
 */
export interface ResolveResult<TConfig = Record<string, unknown>, K extends string = string> {
    config: TConfig;
    artifacts?: Partial<Record<K, string>>;
}
export interface QvacPlugin<TConfig = Record<string, unknown>, TArtifactKeys extends string = string> {
    modelType: string;
    displayName: string;
    addonPackage: string;
    loadConfigSchema: z.ZodType;
    createModel: (params: CreateModelParams) => PluginModelResult;
    handlers: Record<string, PluginHandlerDefinition>;
    logging?: PluginLogging | undefined;
    /** When true, skips file-existence validation for modelPath. Use for plugins that derive paths from config. */
    skipPrimaryModelPathValidation?: boolean;
    /**
     * Optional hook to resolve model sources in modelConfig to local paths.
     * Called before createModel if the plugin needs to download/resolve artifacts.
     * Returns transformed config and optional artifact paths.
     */
    resolveConfig?: (modelConfig: TConfig, ctx: ResolveContext) => Promise<ResolveResult<TConfig, TArtifactKeys>>;
}
export declare const pluginInvokeRequestSchema: z.ZodObject<{
    type: z.ZodLiteral<"pluginInvoke">;
    modelId: z.ZodString;
    handler: z.ZodString;
    params: z.ZodUnknown;
}, z.core.$strip>;
export declare const pluginInvokeResponseSchema: z.ZodObject<{
    type: z.ZodLiteral<"pluginInvoke">;
    result: z.ZodUnknown;
}, z.core.$strip>;
export declare const pluginInvokeStreamRequestSchema: z.ZodObject<{
    type: z.ZodLiteral<"pluginInvokeStream">;
    modelId: z.ZodString;
    handler: z.ZodString;
    params: z.ZodUnknown;
}, z.core.$strip>;
export declare const pluginInvokeStreamResponseSchema: z.ZodObject<{
    type: z.ZodLiteral<"pluginInvokeStream">;
    result: z.ZodUnknown;
    done: z.ZodOptional<z.ZodBoolean>;
}, z.core.$strip>;
export type PluginInvokeRequest = z.infer<typeof pluginInvokeRequestSchema>;
export type PluginInvokeResponse = z.infer<typeof pluginInvokeResponseSchema>;
export type PluginInvokeStreamRequest = z.infer<typeof pluginInvokeStreamRequestSchema>;
export type PluginInvokeStreamResponse = z.infer<typeof pluginInvokeStreamResponseSchema>;
/**
 * Helper function to define a plugin with full type inference.
 *
 * Identity function whose only role is to constrain `plugin` to the
 * `QvacPlugin` shape so consumers get accurate autocompletion and type
 * errors for plugin manifests without having to write an explicit type
 * annotation.
 *
 * @param plugin - The plugin manifest to register.
 * @returns The same `plugin` value, typed as the caller's `T`.
 */
export declare function definePlugin<T extends QvacPlugin>(plugin: T): T;
/**
 * Helper function to define a handler with full type inference.
 *
 * Identity function whose only role is to constrain `definition` to a
 * `PluginHandlerDefinition<TRequest, TResponse>` so the Zod request /
 * response schemas flow through to the handler body without an explicit
 * type annotation on the caller side.
 *
 * @param definition - The plugin handler definition (request/response schemas and handler function).
 * @returns The same `definition` value, typed as `PluginHandlerDefinition<TRequest, TResponse>`.
 */
export declare function defineHandler<TRequest extends z.ZodType, TResponse extends z.ZodType>(definition: PluginHandlerDefinition<TRequest, TResponse>): PluginHandlerDefinition<TRequest, TResponse>;
/**
 * Helper function to define a duplex (bidirectional streaming) handler with full type inference.
 *
 * Identity function whose only role is to constrain `definition` to a
 * `DuplexPluginHandlerDefinition` and cast it to the unified
 * `PluginHandlerDefinition` shape. This bridges TS function-parameter
 * contravariance so duplex handlers can be registered alongside unary ones.
 *
 * @param definition - The duplex plugin handler definition (request/response schemas and streaming handler function).
 * @returns The same `definition` value, typed as `PluginHandlerDefinition<TRequest, TResponse>`.
 */
export declare function defineDuplexHandler<TRequest extends z.ZodType, TResponse extends z.ZodType>(definition: DuplexPluginHandlerDefinition<TRequest, TResponse>): PluginHandlerDefinition<TRequest, TResponse>;
export declare const pluginHandlerDefinitionRuntimeSchema: z.ZodObject<{
    requestSchema: z.ZodObject<{
        safeParse: z.ZodCustom<Function, Function>;
    }, z.core.$catchall<z.ZodUnknown>>;
    responseSchema: z.ZodObject<{
        safeParse: z.ZodCustom<Function, Function>;
    }, z.core.$catchall<z.ZodUnknown>>;
    streaming: z.ZodBoolean;
    duplex: z.ZodOptional<z.ZodBoolean>;
    handler: z.ZodCustom<Function, Function>;
    cancel: z.ZodOptional<z.ZodObject<{
        scope: z.ZodEnum<{
            request: "request";
            none: "none";
            model: "model";
        }>;
        hard: z.ZodOptional<z.ZodBoolean>;
    }, z.core.$catchall<z.ZodUnknown>>>;
}, z.core.$catchall<z.ZodUnknown>>;
export declare const pluginDefinitionRuntimeSchema: z.ZodObject<{
    modelType: z.ZodString;
    displayName: z.ZodString;
    addonPackage: z.ZodString;
    loadConfigSchema: z.ZodObject<{
        safeParse: z.ZodCustom<Function, Function>;
    }, z.core.$catchall<z.ZodUnknown>>;
    createModel: z.ZodCustom<Function, Function>;
    handlers: z.ZodRecord<z.ZodString, z.ZodObject<{
        requestSchema: z.ZodObject<{
            safeParse: z.ZodCustom<Function, Function>;
        }, z.core.$catchall<z.ZodUnknown>>;
        responseSchema: z.ZodObject<{
            safeParse: z.ZodCustom<Function, Function>;
        }, z.core.$catchall<z.ZodUnknown>>;
        streaming: z.ZodBoolean;
        duplex: z.ZodOptional<z.ZodBoolean>;
        handler: z.ZodCustom<Function, Function>;
        cancel: z.ZodOptional<z.ZodObject<{
            scope: z.ZodEnum<{
                request: "request";
                none: "none";
                model: "model";
            }>;
            hard: z.ZodOptional<z.ZodBoolean>;
        }, z.core.$catchall<z.ZodUnknown>>>;
    }, z.core.$catchall<z.ZodUnknown>>>;
    logging: z.ZodOptional<z.ZodObject<{
        module: z.ZodOptional<z.ZodUnknown>;
        namespace: z.ZodOptional<z.ZodString>;
    }, z.core.$catchall<z.ZodUnknown>>>;
    resolveConfig: z.ZodOptional<z.ZodCustom<Function, Function>>;
    skipPrimaryModelPathValidation: z.ZodOptional<z.ZodBoolean>;
}, z.core.$catchall<z.ZodUnknown>>;
/**
 * LLM text completion plugin (llama.cpp).
 * Provides: completion, streaming chat, tool calling.
 */
export declare const PLUGIN_LLM: "@qvac/sdk/llamacpp-completion/plugin";
/**
 * Text embedding plugin (llama.cpp).
 * Provides: vector embeddings for RAG and semantic search.
 */
export declare const PLUGIN_EMBEDDING: "@qvac/sdk/llamacpp-embedding/plugin";
/**
 * Speech-to-text transcription plugin (whisper.cpp).
 * Provides: audio transcription, language detection.
 */
export declare const PLUGIN_WHISPER: "@qvac/sdk/whispercpp-transcription/plugin";
/**
 * Brain-Computer Interface neural-signal transcription plugin
 * (whisper.cpp). Provides: transcription of neural signals to text.
 */
export declare const PLUGIN_BCI: "@qvac/sdk/bci-whispercpp-transcription/plugin";
/**
 * Speech-to-text transcription plugin (Parakeet ONNX).
 * Provides: audio transcription using NVIDIA Parakeet models.
 */
export declare const PLUGIN_PARAKEET: "@qvac/sdk/parakeet-transcription/plugin";
/**
 * Neural machine translation plugin (nmt.cpp).
 * Provides: text translation between languages.
 */
export declare const PLUGIN_NMT: "@qvac/sdk/nmtcpp-translation/plugin";
/**
 * Text-to-speech synthesis plugin (GGML).
 * Provides: speech synthesis from text.
 */
export declare const PLUGIN_TTS: "@qvac/sdk/tts-ggml/plugin";
/**
 * Optical character recognition plugin (ONNX).
 * Provides: text extraction from images.
 */
export declare const PLUGIN_OCR: "@qvac/sdk/onnx-ocr/plugin";
/**
 * Image generation plugin (stable-diffusion.cpp).
 * Provides: text-to-image generation and standalone ESRGAN image upscaling.
 */
export declare const PLUGIN_DIFFUSION: "@qvac/sdk/sdcpp-generation/plugin";
/**
 * Vision-Language-Action plugin (ggml). Supports SmolVLA and π₀.₅ (pi05),
 * dispatched on the GGUF `general.architecture` key.
 * Provides: robot-action inference from one or more camera frames (2 for
 * SmolVLA, 3 for π₀.₅) and a natural-language instruction.
 */
export declare const PLUGIN_VLA: "@qvac/sdk/ggml-vla/plugin";
/**
 * Image classification plugin (GGML / MobileNetV3-Small).
 * Provides: image classification with bundled 3-class model (food / report / other).
 */
export declare const PLUGIN_CLASSIFICATION: "@qvac/sdk/ggml-classification/plugin";
/**
 * All built-in SDK plugins.
 *
 * @example
 * // Use all defaults plus a custom plugin:
 * const config = {
 *   plugins: [...SDK_DEFAULT_PLUGINS, myCustomPlugin],
 * };
 */
export declare const SDK_DEFAULT_PLUGINS: readonly ["@qvac/sdk/llamacpp-completion/plugin", "@qvac/sdk/llamacpp-embedding/plugin", "@qvac/sdk/whispercpp-transcription/plugin", "@qvac/sdk/bci-whispercpp-transcription/plugin", "@qvac/sdk/parakeet-transcription/plugin", "@qvac/sdk/nmtcpp-translation/plugin", "@qvac/sdk/tts-ggml/plugin", "@qvac/sdk/onnx-ocr/plugin", "@qvac/sdk/sdcpp-generation/plugin", "@qvac/sdk/ggml-vla/plugin", "@qvac/sdk/ggml-classification/plugin"];
export type BuiltinPlugin = (typeof SDK_DEFAULT_PLUGINS)[number];
/** Native addon package for LLM completion (llama.cpp) */
export declare const ADDON_LLM: "@qvac/llm-llamacpp";
/** Native addon package for text embeddings (llama.cpp) */
export declare const ADDON_EMBEDDING: "@qvac/embed-llamacpp";
/** Native addon package for Whisper transcription (whisper.cpp) */
export declare const ADDON_WHISPER: "@qvac/transcription-whispercpp";
/** Native addon package for BCI neural-signal transcription (whisper.cpp) */
export declare const ADDON_BCI: "@qvac/bci-whispercpp";
/** Native addon package for Parakeet transcription (ONNX) */
export declare const ADDON_PARAKEET: "@qvac/transcription-parakeet";
/** Native addon package for NMT translation (nmt.cpp) */
export declare const ADDON_NMT: "@qvac/translation-nmtcpp";
/** Native addon package for TTS (GGML) */
export declare const ADDON_TTS: "@qvac/tts-ggml";
/** Native addon package for OCR (ONNX) */
export declare const ADDON_OCR: "@qvac/ocr-onnx";
/** Native addon package for image generation (stable-diffusion.cpp) */
export declare const ADDON_DIFFUSION: "@qvac/diffusion-cpp";
/** Native addon package for vision-language-action inference (SmolVLA / π₀.₅ on ggml) */
export declare const ADDON_VLA: "@qvac/vla-ggml";
/** Native addon package for image classification (GGML / MobileNetV3) */
export declare const ADDON_CLASSIFICATION: "@qvac/classification-ggml";
//# sourceMappingURL=plugin.d.ts.map