qmd/dist/embedding/factory.d.ts

/**
 * factory.ts - EmbeddingProvider factory with config precedence.
 *
 * Resolution order (first match wins):
 *   1. Explicit `kind` argument or `--provider` CLI flag → forces a kind
 *   2. `QMD_EMBED_ENDPOINT` env var present and non-empty → "openai"
 *   3. Config file (`~/.config/qmd/config.json`) commercial endpoint
 *   4. Otherwise → typed HOLD (there is no local or self-hosted fallback)
 */
import { type OpenAIProviderConfig } from "./openai.js";
import type { EmbeddingProvider, ProviderKind } from "./provider.js";
export type EmbedProviderConfigFile = {
    embedProvider?: {
        kind?: ProviderKind;
        endpoint?: string;
        apiKey?: string;
        modelId?: string;
        upstreamModel?: string;
        batchSize?: number;
        /**
         * Max in-flight HTTP requests during a single `embedBatch` call. Default 4
         * (matches qmd-embed-worker's MAX_CONCURRENT_REQUESTS=4 semaphore). Set
         * to 1 to force legacy sequential dispatch.
         */
        concurrency?: number;
        timeoutMs?: number;
        /** Historical only. `true` is rejected because local fallback is forbidden. */
        autoFallback?: boolean;
    };
};
export declare function defaultConfigPath(): string;
/**
 * Load `~/.config/qmd/config.json` if present. Returns an empty object on
 * any read/parse error; provider construction then fails closed without an endpoint.
 */
export declare function loadConfigFile(path?: string): EmbedProviderConfigFile;
export type CreateEmbeddingProviderOptions = {
    /** Force a specific provider kind. Overrides env + config. */
    kind?: ProviderKind;
    /** Override config file path (mostly for tests) */
    configPath?: string;
    /** OpenAI-provider overrides — merged on top of env/config */
    openai?: Partial<OpenAIProviderConfig>;
    /**
     * Historical compatibility input. Any truthy value produces typed HOLD;
     * commercial provider failures must never fall back to a local model.
     */
    autoFallback?: boolean;
    /**
     * Custom env source (mostly for tests). Defaults to `process.env`.
     * Read keys: QMD_EMBED_PROVIDER, QMD_EMBED_ENDPOINT, QMD_EMBED_API_KEY,
     * QMD_EMBED_MODEL_ID, QMD_EMBED_UPSTREAM_MODEL, QMD_EMBED_BATCH_SIZE,
     * QMD_EMBED_TIMEOUT_MS, QMD_EMBED_AUTO_FALLBACK.
     */
    env?: Record<string, string | undefined>;
};
/**
 * Resolve the provider kind without instantiating anything. Useful for
 * logging and tests.
 */
export declare function resolveProviderKind(opts?: CreateEmbeddingProviderOptions): ProviderKind;
/**
 * Factory entry point — returns the appropriate `EmbeddingProvider`.
 * Throws if `openai` kind is requested but no endpoint is configured.
 */
export declare function createEmbeddingProvider(opts?: CreateEmbeddingProviderOptions): EmbeddingProvider;
export declare function assertCommercialEndpoint(endpoint: string): void;