akm-cli/dist/setup/semantic-assets.js

akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cur

// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at https://mozilla.org/MPL/2.0/.
/**
 * Semantic-search asset preparation for the setup wizard. Transformers.js is
 * a normal external package dependency; setup never mutates the installed CLI.
 * This module only prepares the model.
 */
import * as p from "../cli/clack.js";
import { isHttpUrl } from "../core/common.js";
import { checkEmbeddingAvailability, DEFAULT_LOCAL_MODEL, isTransformersAvailable } from "../llm/embedder.js";
// Approximate first-download size of the default local model (DEFAULT_LOCAL_MODEL), used in the setup note.
const LOCAL_MODEL_APPROX_SIZE_MB = 130;
export function isRemoteEmbeddingConfig(embedding) {
    return isHttpUrl(embedding?.endpoint);
}
/**
 * @internal Exported for testing only.
 */
export function describeSemanticSearchAssets(embedding) {
    if (isRemoteEmbeddingConfig(embedding)) {
        return [`• Embedding endpoint: ${embedding?.provider ?? "custom"} / ${embedding?.model} (no local model download)`];
    }
    return [
        `• Local embedding model: ${embedding?.localModel ?? DEFAULT_LOCAL_MODEL} (~${LOCAL_MODEL_APPROX_SIZE_MB} MB download on first use)`,
    ];
}
export async function prepareSemanticSearchAssets(config) {
    const remote = isRemoteEmbeddingConfig(config.embedding);
    // Local embeddings require the declared Transformers dependency.
    if (!remote) {
        if (!isTransformersAvailable()) {
            const message = "The @huggingface/transformers dependency is unavailable. Reinstall akm-cli, then re-run `akm setup` or `akm index --full --verbose`.";
            p.log.warn(message);
            return { ok: false, reason: "missing-package", message };
        }
    }
    const spin = p.spinner();
    spin.start(remote
        ? "Checking remote embedding endpoint..."
        : `Downloading local embedding model (${config.embedding?.localModel ?? DEFAULT_LOCAL_MODEL})...`);
    const result = await checkEmbeddingAvailability(config.embedding);
    if (!result.available) {
        spin.stop("Semantic-search assets could not be prepared.");
        if (result.reason === "remote-unreachable") {
            p.log.warn("The remote embedding endpoint is not reachable. Check your endpoint and credentials, then retry `akm index --full --verbose`.");
            return { ok: false, reason: "remote-network", message: "The remote embedding endpoint is not reachable." };
        }
        else if (result.reason === "missing-package") {
            p.log.warn("The @huggingface/transformers dependency is unavailable. Reinstall akm-cli, then re-run `akm setup` or `akm index --full --verbose`.");
            return { ok: false, reason: "missing-package", message: "The local embedding runtime is unavailable." };
        }
        else {
            p.log.warn(`The local embedding model could not be downloaded: ${result.message}\n` +
                "Retry `akm index --full --verbose` after confirming local model downloads are permitted.");
            return { ok: false, reason: "local-model-download", message: result.message };
        }
    }
    spin.stop(remote ? "Remote embedding endpoint is ready." : "Local embedding model downloaded and ready.");
    return { ok: true };
}